3.4.2. Link

In this chapter, you’ll learn what Link is and how to use it to manage links.

What is Link?#

Link is a class with utility methods to manage links between data models. It’s registered in the Medusa container under the link registration name.

For example:

Code
Show Imports
8
9export async function POST(10  req: MedusaRequest,11  res: MedusaResponse12): Promise<void> {13  const link = req.scope.resolve(14    ContainerRegistrationKeys.LINK15  )16    17  // ...18}

You can use its methods to manage links, such as create or delete links.

Link Usage in Workflows#

To perform link operations in a workflow, Medusa provides the following steps out-of-the-box:

• createRemoteLinkStep: Creates a link between records of two data models.
• dismissRemoteLinkStep: Removes a link between records of two data models.
• removeRemoteLinkStep: Deletes all linked records whose links are defined with cascade deletion.
• updateRemoteLinksStep: Updates links between records of two data models.

The rest of this chapter provides examples using the Link class and the workflow steps.

Create Link#

To create a link between records of two data models, use the create method of Link.

For example:

The create method accepts as a parameter an object. The object’s keys are the names of the linked modules.

The value of each module’s property is an object, whose keys are of the format {data_model_snake_name}_id, and values are the IDs of the linked record.

So, in the example above, you link a record of the Post data model in a blog module to a Product record in the Product Module.

Enforced Integrity Constraints on Link Creation#

Medusa enforces integrity constraints on links based on the link's relation type. So, an error is thrown in the following scenarios:

• If the link is one-to-one and one of the linked records already has a link to another record of the same data model. For example:

Code
1// no error2await link.create({3  [Modules.PRODUCT]: {4    product_id: "prod_123",5  },6  blog: {7    post_id: "post_123",8  },9})10
11// throws an error because `prod_123` already has a link to `post_123`12await link.create({13  [Modules.PRODUCT]: {14    product_id: "prod_123",15  },16  blog: {17    post_id: "mc_456",18  },19})

• If the link is one-to-many and the "one" side already has a link to another record of the same data model. For example, if a product can have many Post records, but a Post record can only have one product:

Code
1// no error2await link.create({3  [Modules.PRODUCT]: {4    product_id: "prod_123",5  },6  blog: {7    post_id: "post_123",8  },9})10
11// also no error12await link.create({13  [Modules.PRODUCT]: {14    product_id: "prod_123",15  },16  blog: {17    post_id: "mc_456",18  },19})20
21// throws an error because `post_123` already has a link to `prod_123`22await link.create({23  [Modules.PRODUCT]: {24    product_id: "prod_456",25  },26  blog: {27    post_id: "post_123",28  },29})

There are no integrity constraints in a many-to-many link, so you can create multiple links between the same records.

Dismiss Link#

To remove a link between records of two data models, use the dismiss method of Link.

For example:

The dismiss method accepts the same parameter type as the create method.

Cascade Delete Linked Records#

If you delete a record using a workflow or its module's service, use the delete method of Link to delete all linked records whose links are defined with cascade deletion.

For example:

This deletes all records linked to the deleted product.

Restore Linked Records#

If a record that was previously soft-deleted is now restored, use the restore method of Link to restore all linked records.

For example:

Code
1import { Modules } from "@medusajs/framework/utils"2
3// ...4
5await productModuleService.restoreProducts(["prod_123"])6
7await link.restore({8  [Modules.PRODUCT]: {9    product_id: "prod_123",10  },11})

Update Links#

Links may have custom columns to store additional information, such as a metadata column to store JSON data about the link.

You can update the custom columns of existing links by calling the create method again with the same linked records and the new values for the custom columns.

For example:

The object parameter you pass to the create method (or the updateRemoteLinksStep step) accepts an optional data property. The value of this property is an object whose keys are the names of the custom columns to update, and values are the new values for those columns.

Learn more in the Custom Columns chapter.