docs: fixes and changes based on latest updates (#7322)
* docs: changes based on DX changes * remove fields no longer needed * remove unnecessary parameters * fixes to authenticate middleware usage * add highlight to migrations config * change configuration to http * added missing remote link docs * fix name in sidebar * added notification module docs + updated file module docs * add vale exceptions * fix vale errors * added docs on custom cli scripts
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
ff5d573887
commit
154673f3d8
55 files changed
+1674
-3791
No files matched your search
@@ -1,48 +0,0 @@
|
||||
export const metadata = {
|
||||
title: `${pageNumber} Database Connection Loader`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you’ll learn about how to load the database connection in your module.
|
||||
|
||||
## How to Add a Database Connection Loader?
|
||||
|
||||
To ensure that your module's database operations use the Medusa application's database connection, export a database connection loader in your module's definition.
|
||||
|
||||
Medusa provides a utility function that creates the database connection loader for you.
|
||||
|
||||
For example:
|
||||
|
||||
```ts title="src/modules/hello/index.ts"
|
||||
// other imports...
|
||||
import { ModulesSdkUtils } from "@medusajs/utils"
|
||||
import { MyCustom } from "./models/my-custom"
|
||||
|
||||
const pathToMigrations = __dirname + "/migrations"
|
||||
|
||||
// ...
|
||||
|
||||
const connectionLoader = ModulesSdkUtils
|
||||
.mikroOrmConnectionLoaderFactory({
|
||||
moduleName,
|
||||
moduleModels: [MyCustom],
|
||||
migrationsPath: pathToMigrations,
|
||||
})
|
||||
|
||||
export default {
|
||||
// ...
|
||||
loaders: [
|
||||
// ...
|
||||
connectionLoader,
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
The `mikroOrmConnectionLoaderFactory` function accepts an object with the following properties:
|
||||
|
||||
- `moduleName`: The name of the module.
|
||||
- `moduleModules`: An array of data models in the module.
|
||||
- `migrationsPath`: The path to the migrations file.
|
||||
|
||||
You can now implement data-management methods as explained in the next chapters.
|
||||
@@ -14,63 +14,12 @@ So, resources in the module, such as services or loaders, can only resolve other
|
||||
|
||||
---
|
||||
|
||||
## The Container Loader
|
||||
## Resources Registered in the Module's Container
|
||||
|
||||
Medusa provides a utility function that creates a container loader. This loader takes care of registering resources in your container.
|
||||
Some resources registered in the module's container are:
|
||||
|
||||
For example:
|
||||
|
||||
export const highlights = [
|
||||
["11", "moduleContainerLoaderFactory", "Create the container loader."],
|
||||
["25", "", "Export the container loader."]
|
||||
]
|
||||
|
||||
```ts title="src/modules/hello/index.ts" highlights={highlights}
|
||||
// other imports...
|
||||
import HelloModuleService from "./service"
|
||||
import { MyCustom } from "./models/my-custom"
|
||||
import {
|
||||
ModulesSdkUtils,
|
||||
MikroOrmBaseRepository,
|
||||
} from "@medusajs/utils"
|
||||
|
||||
// ...
|
||||
|
||||
const containerLoader = ModulesSdkUtils.moduleContainerLoaderFactory({
|
||||
moduleModels: {
|
||||
MyCustom,
|
||||
},
|
||||
moduleRepositories: {
|
||||
BaseRepository: MikroOrmBaseRepository,
|
||||
},
|
||||
moduleServices: {
|
||||
HelloModuleService,
|
||||
},
|
||||
})
|
||||
|
||||
export default {
|
||||
// ...
|
||||
loaders: [containerLoader],
|
||||
}
|
||||
```
|
||||
|
||||
You create the container loader using the utility function `moduleContainerLoaderFactory` and export it in the module's definition.
|
||||
|
||||
### moduleContainerLoaderFactory Parameters
|
||||
|
||||
The `moduleContainerLoaderFactory` function accepts as a parameter an object with the following properties:
|
||||
|
||||
- `moduleModels`: An object where each key is a data model's name, and its value the data model class.
|
||||
- `moduleRepositories`: An object of the module's repositories. You import here the `MikroOrmBaseRepository` from `@medusajs/utils` and use it as the value of `BaseRepository`.
|
||||
- `moduleServices`: An object where each key is the service's registration name, and its value is the service class.
|
||||
|
||||
### Resources Registered by the Container Loader
|
||||
|
||||
The container loader registers in the module's container:
|
||||
|
||||
- The services passed in the `moduleServices` property.
|
||||
- The repositories provided in the `moduleRepositories`.
|
||||
- A generated service for each data model provided in `moduleModels`.
|
||||
- The module's main service.
|
||||
- A generated service for each data model in your module. The registration name is the camel-case data model name suffixed by `Service`. For example, `myCustomService`.
|
||||
|
||||
|
||||
|
||||
@@ -84,7 +33,7 @@ A service's constructor accepts as a first parameter an object used to resolve r
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
```ts highlights={[["5"], ["12"]]}
|
||||
import { ModulesSdkTypes } from "@medusajs/types"
|
||||
import { MyCustom } from "./models/my-custom"
|
||||
|
||||
@@ -109,12 +58,11 @@ A loader function in a module accepts as a parameter an object having the proper
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
```ts highlights={[["8"]]}
|
||||
import {
|
||||
LoaderOptions,
|
||||
} from "@medusajs/modules-sdk"
|
||||
|
||||
|
||||
export default function helloWorldLoader({
|
||||
container,
|
||||
}: LoaderOptions) {
|
||||
|
||||
+4
-5
@@ -6,14 +6,14 @@ export const metadata = {
|
||||
|
||||
In this document, you’ll learn how to implement database operations, such as creating a record, in the main service.
|
||||
|
||||
## Use Data Model Services
|
||||
## Use the Data Model's Generated Service
|
||||
|
||||
The module container has a generated service registered for each data model. You can resolve that service and use it to perform database operations on the data model.
|
||||
To perform database operations on a data model, use the model's generated service in the module's container.
|
||||
|
||||
For example:
|
||||
|
||||
export const highlights = [
|
||||
["13", "", "Inject myCustomService, which is the service generated by the container loader for the MyCustom data model."],
|
||||
["13", "", "Inject myCustomService, which is the generated service of the `MyCustom` data model."],
|
||||
["22", "", "Add a new field for the generated service of the MyCustom data model."],
|
||||
["29", "", "Set the class field to the injected dependency."],
|
||||
["35", "create", "Use the `create` method of the generated service."]
|
||||
@@ -55,8 +55,7 @@ class HelloModuleService extends ModulesSdkUtils
|
||||
data: CreateMyCustomDTO
|
||||
): Promise<MyCustomDTO> {
|
||||
const myCustom = await this.myCustomService_.create(
|
||||
data,
|
||||
context
|
||||
data
|
||||
)
|
||||
|
||||
return myCustom
|
||||
|
||||
@@ -10,137 +10,14 @@ In this chapter, you’ll learn what a link module is and how to use the remote
|
||||
|
||||
A link module is a module whose only purpose is to define a relationship between two modules’ data models. The relationship is represented as a pivot or link table in the database, pointing at the primary keys of each data model.
|
||||
|
||||
For example, Medusa defines a link module between the Product and Pricing modules. The link module builds a relationship between the `ProductVariant` data model and the `PriceSet` data model.
|
||||
For example, Medusa has a link module that defines a relationship between the Product and Pricing modules. It links the `ProductVariant` and `PriceSet` data models.
|
||||
|
||||
|
||||
|
||||
Link modules provide more flexibility in managing relationships between modules while maintaining module isolation.
|
||||
Link modules provide more flexibility in managing relationships between modules while maintaining module isolation. The Medusa application only creates the link tables when both modules are available.
|
||||
|
||||
Link modules are currently only available for Medusa’s commerce modules. The Medusa application only creates the link tables when both modules are available.
|
||||
<Note type="soon">
|
||||
|
||||
---
|
||||
Link modules are currently only available for Medusa’s commerce modules.
|
||||
|
||||
## What is the Remote Link?
|
||||
|
||||
The remote link is a class with utility methods to manage links between modules. It’s registered in the Medusa container under the `remoteLink` registration name.
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
import {
|
||||
MedusaRequest,
|
||||
MedusaResponse,
|
||||
} from "@medusajs/medusa"
|
||||
import {
|
||||
ModuleRegistrationName,
|
||||
RemoteLink,
|
||||
} from "@medusajs/modules-sdk"
|
||||
import {
|
||||
ContainerRegistrationKeys,
|
||||
} from "@medusajs/utils"
|
||||
|
||||
export async function POST(
|
||||
req: MedusaRequest,
|
||||
res: MedusaResponse
|
||||
): Promise<void> {
|
||||
const remoteLink: RemoteLink = req.scope.resolve(
|
||||
ContainerRegistrationKeys.REMOTE_LINK
|
||||
)
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
You can use its methods to manage links, such as create or delete links.
|
||||
|
||||
### Create Link
|
||||
|
||||
To create a link between records of two data models, use the `create` method of the remote link.
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
import { Modules } from "@medusajs/utils"
|
||||
|
||||
// ...
|
||||
|
||||
await remoteLink.create({
|
||||
[Modules.PRODUCT]: {
|
||||
variant_id: product.variants[0].id,
|
||||
},
|
||||
[Modules.PRICING]: {
|
||||
price_set_id: price.id,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
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. It defines the values of the linked fields.
|
||||
|
||||
So, in the example above, you specify for the Product Module the value of the `variant_id`, and for the Pricing Module the value of `price_set_id`. These are the fields linked between the models of the two modules.
|
||||
|
||||
### Dismiss Link
|
||||
|
||||
To remove a link between records of two data models, use the `dismiss` method of the remote link. This doesn’t remove the records, only the relation between them.
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
import { Modules } from "@medusajs/utils"
|
||||
|
||||
// ...
|
||||
|
||||
await remoteLink.dismiss({
|
||||
[Modules.PRODUCT]: {
|
||||
variant_id: product.variants[0].id,
|
||||
},
|
||||
[Modules.PRICING]: {
|
||||
price_set_id: price.id,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
The `dismiss` method accepts the same parameter type as the [create method](#create-link).
|
||||
|
||||
### Cascade Delete Linked Records
|
||||
|
||||
If a record, such as a variant, is deleted, use the `delete` method of the remote link to delete all associated links with cascade delete enabled.
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
import { Modules } from "@medusajs/utils"
|
||||
|
||||
// ...
|
||||
|
||||
await productModuleService.deleteVariants([variant.id])
|
||||
|
||||
await remoteLink.delete({
|
||||
[Modules.PRODUCT]: {
|
||||
variant_id: variant.id,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
This deletes all records linked to the deleted variant with cascade delete enabled in their relationship.
|
||||
|
||||
### Restore Linked Records
|
||||
|
||||
If a record, such as a variant, that was previously soft-deleted is now restored, use the `restore` method of the remote link to restore all associated links that were cascade deleted.
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
import { Modules } from "@medusajs/utils"
|
||||
|
||||
// ...
|
||||
|
||||
await productModuleService.restoreVariants([variant.id])
|
||||
|
||||
await remoteLink.restore({
|
||||
[Modules.PRODUCT]: {
|
||||
variant_id: variant.id,
|
||||
},
|
||||
})
|
||||
```
|
||||
</Note>
|
||||
@@ -40,18 +40,16 @@ The Medusa application resolves these relationships while maintaining isolation
|
||||
|
||||
Consider you’re creating a data model that adds custom fields associated with a product:
|
||||
|
||||
```ts title="src/modules/hello/models/custom-product-data.ts" highlights={[["19"]]}
|
||||
import { generateEntityId } from "@medusajs/utils"
|
||||
```ts title="src/modules/hello/models/custom-product-data.ts" highlights={[["17"]]}
|
||||
import { BaseEntity } from "@medusajs/utils"
|
||||
import {
|
||||
BeforeCreate,
|
||||
Entity,
|
||||
OnInit,
|
||||
PrimaryKey,
|
||||
Property,
|
||||
} from "@mikro-orm/core"
|
||||
|
||||
@Entity()
|
||||
export class CustomProductData {
|
||||
export class CustomProductData extends BaseEntity {
|
||||
@PrimaryKey({ columnType: "text" })
|
||||
id!: string
|
||||
|
||||
@@ -60,16 +58,6 @@ export class CustomProductData {
|
||||
|
||||
@Property({ columnType: "text", nullable: true })
|
||||
product_id?: string
|
||||
|
||||
@BeforeCreate()
|
||||
onCreate() {
|
||||
this.id = generateEntityId(this.id, "cpd")
|
||||
}
|
||||
|
||||
@OnInit()
|
||||
OnInit() {
|
||||
this.id = generateEntityId(this.id, "cpd")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -81,7 +69,6 @@ When you add a new data model, make sure to:
|
||||
|
||||
- [Create a migration for it.](../../../basics/data-models/page.mdx#create-a-migration)
|
||||
- [Add it to the second parameter of the main service's factory function.](../service-factory/page.mdx#abstractModuleServiceFactory-parameters)
|
||||
- Add it to the [container](../container/page.mdx) and [connection](../connection-loader/page.mdx) loaders.
|
||||
|
||||
</Note>
|
||||
|
||||
@@ -115,7 +102,6 @@ class HelloModuleService extends ModulesSdkUtils
|
||||
__joinerConfig(): ModuleJoinerConfig {
|
||||
return {
|
||||
serviceName: "helloModuleService",
|
||||
primaryKeys: ["id"],
|
||||
alias: [
|
||||
{
|
||||
name: ["my_custom"],
|
||||
@@ -159,12 +145,6 @@ This creates a relationship to the `Product` data model of the Product Module us
|
||||
optional: false,
|
||||
description: "The name of your module (as added in `medusa-config.js`)."
|
||||
},
|
||||
{
|
||||
name: "primaryKeys",
|
||||
type: "`string[]`",
|
||||
optional: false,
|
||||
description: "The primary key field names used in your module's data models.",
|
||||
},
|
||||
{
|
||||
name: "alias",
|
||||
type: "`object[]`",
|
||||
@@ -240,8 +220,6 @@ const modules = {
|
||||
helloModuleService: {
|
||||
// ...
|
||||
definition: {
|
||||
key: "helloModuleService",
|
||||
registrationName: "helloModuleService",
|
||||
isQueryable: true,
|
||||
},
|
||||
},
|
||||
@@ -251,28 +229,6 @@ const modules = {
|
||||
|
||||
Enabling the `isQueryable` property is required to use relationships in a module.
|
||||
|
||||
The `definition` property’s value is an object that accepts the following properties, among others:
|
||||
|
||||
<TypeList types={[
|
||||
{
|
||||
name: "key",
|
||||
type: "`string`",
|
||||
optional: false,
|
||||
description: "The module's key in the `modules` object."
|
||||
},
|
||||
{
|
||||
name: "registrationName",
|
||||
type: "`string`",
|
||||
optional: false,
|
||||
description: "The name that the main service is registered under in the Medusa container. It’s recommended to be the same as `key`'s value.",
|
||||
},
|
||||
{
|
||||
name: "isQueryable",
|
||||
type: "`boolean`",
|
||||
description: "Whether the module is queryable. This must be enabled to allow a module to have relationships."
|
||||
}
|
||||
]} sectionTitle="Adjust Module Configuration" />
|
||||
|
||||
---
|
||||
|
||||
## Reference Inner Data Models
|
||||
|
||||
@@ -0,0 +1,198 @@
|
||||
export const metadata = {
|
||||
title: `${pageNumber} Remote Link`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this chapter, you’ll learn what the remote link is and how to use it to manage links.
|
||||
|
||||
## What is the Remote Link?
|
||||
|
||||
The remote link is a class with utility methods to manage links defined by the link module. It’s registered in the Medusa container under the `remoteLink` registration name.
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
import {
|
||||
MedusaRequest,
|
||||
MedusaResponse,
|
||||
} from "@medusajs/medusa"
|
||||
import {
|
||||
ModuleRegistrationName,
|
||||
RemoteLink,
|
||||
} from "@medusajs/modules-sdk"
|
||||
import {
|
||||
ContainerRegistrationKeys,
|
||||
} from "@medusajs/utils"
|
||||
|
||||
export async function POST(
|
||||
req: MedusaRequest,
|
||||
res: MedusaResponse
|
||||
): Promise<void> {
|
||||
const remoteLink: RemoteLink = req.scope.resolve(
|
||||
ContainerRegistrationKeys.REMOTE_LINK
|
||||
)
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
You can use its methods to manage links, such as create or delete links.
|
||||
|
||||
### Create Link
|
||||
|
||||
To create a link between records of two data models, use the `create` method of the remote link.
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
import { Modules } from "@medusajs/utils"
|
||||
|
||||
// ...
|
||||
|
||||
await remoteLink.create({
|
||||
[Modules.PRODUCT]: {
|
||||
variant_id: product.variants[0].id,
|
||||
},
|
||||
[Modules.PRICING]: {
|
||||
price_set_id: price.id,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
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. It defines the values of the linked fields.
|
||||
|
||||
So, in the example above, you specify for the Product Module the value of the `variant_id`, and for the Pricing Module the value of `price_set_id`. These are the fields linked between the models of the two modules.
|
||||
|
||||
### Dismiss Link
|
||||
|
||||
To remove a link between records of two data models, use the `dismiss` method of the remote link. This doesn’t remove the records, only the relation between them.
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
import { Modules } from "@medusajs/utils"
|
||||
|
||||
// ...
|
||||
|
||||
await remoteLink.dismiss({
|
||||
[Modules.PRODUCT]: {
|
||||
variant_id: product.variants[0].id,
|
||||
},
|
||||
[Modules.PRICING]: {
|
||||
price_set_id: price.id,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
The `dismiss` method accepts the same parameter type as the [create method](#create-link).
|
||||
|
||||
### Cascade Delete Linked Records
|
||||
|
||||
If a record, such as a variant, is deleted, use the `delete` method of the remote link to delete all associated links with cascade delete enabled.
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
import { Modules } from "@medusajs/utils"
|
||||
|
||||
// ...
|
||||
|
||||
await productModuleService.deleteVariants([variant.id])
|
||||
|
||||
await remoteLink.delete({
|
||||
[Modules.PRODUCT]: {
|
||||
variant_id: variant.id,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
This deletes all records linked to the deleted variant with cascade delete enabled in their relationship.
|
||||
|
||||
### Restore Linked Records
|
||||
|
||||
If a record, such as a variant, that was previously soft-deleted is now restored, use the `restore` method of the remote link to restore all associated links that were cascade deleted.
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
import { Modules } from "@medusajs/utils"
|
||||
|
||||
// ...
|
||||
|
||||
await productModuleService.restoreVariants([variant.id])
|
||||
|
||||
await remoteLink.restore({
|
||||
[Modules.PRODUCT]: {
|
||||
variant_id: variant.id,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Link Module's Service
|
||||
|
||||
The remote link has a `getLinkModule` method to retrieve the service of the link module. This service has `list` and `retrieve` methods to retrieve the linked items.
|
||||
|
||||
For example, to retrieve the link module of the Product and Pricing modules:
|
||||
|
||||
export const linkModuleServiceHighlights = [
|
||||
["6", "Modules.PRODUCT", "The name of the first module in the link module's definition."],
|
||||
["7", '"variant_id"', "The foreign key that links to the record in the first module."],
|
||||
["8", "Modules.PRICING", "The name of the second module in the link module's definition."],
|
||||
["9", '"price_set_id"', "The foreign key that links to the record in the second module."],
|
||||
["12", "", "The link module's service is undefined if either of the modules isn't installed or there's no link module with the specified definition."]
|
||||
]
|
||||
|
||||
```ts highlights={linkModuleServiceHighlights}
|
||||
import { Modules } from "@medusajs/utils"
|
||||
|
||||
// ...
|
||||
|
||||
const linkModuleService = remoteLink.getLinkModule(
|
||||
Modules.PRODUCT,
|
||||
"variant_id",
|
||||
Modules.PRICING,
|
||||
"price_set_id"
|
||||
)
|
||||
|
||||
if (!linkModuleService) {
|
||||
return
|
||||
}
|
||||
```
|
||||
|
||||
The `getLinkModule` method accepts four parameter:
|
||||
|
||||
1. A string indicating the name of the first module in the link module's definition.
|
||||
2. A string indicating the foreign key that links to the record in the first module.
|
||||
3. A string indicating the name of the second module in the link module's definition.
|
||||
4. A string indicating the foreign key that links to the record in the second module.
|
||||
|
||||
Notice that the returned link module service might be undefined if either of the modules isn't installed, or if there's no link module with the specified definition.
|
||||
|
||||
### List Linked Items
|
||||
|
||||
The link module's service has a `list` method that retrieves a list of linked records. It also accepts filters to retrieve specific linked items.
|
||||
|
||||
For example, to retrieve the price sets linked to a variant:
|
||||
|
||||
```ts
|
||||
import { Modules } from "@medusajs/utils"
|
||||
|
||||
// ...
|
||||
|
||||
const linkModuleService = remoteLink.getLinkModule(
|
||||
Modules.PRODUCT,
|
||||
"variant_id",
|
||||
Modules.PRICING,
|
||||
"price_set_id"
|
||||
)
|
||||
|
||||
const items = await linkModuleService.list(
|
||||
{ variant_id: [variant.id] },
|
||||
{ select: ["variant_id", "price_set_id"] }
|
||||
)
|
||||
```
|
||||
@@ -114,7 +114,7 @@ The `remoteQueryObjectFromString` function accepts a `variables` property. You c
|
||||
|
||||
## Sort Records
|
||||
|
||||
```ts highlights={[["4"], ["5"], ["6"]]}
|
||||
```ts highlights={[["5"], ["6"], ["7"]]}
|
||||
const query = remoteQueryObjectFromString({
|
||||
entryPoint: "custom_product_data",
|
||||
fields: ["id", "custom_field", "product.title"],
|
||||
|
||||
@@ -22,15 +22,6 @@ Medusa provides a service factory that your module’s main service can extend.
|
||||
|
||||
## How to Extend the Service Factory?
|
||||
|
||||
<Note type="check">
|
||||
|
||||
Your module must be using the following loaders from the previous chapters:
|
||||
|
||||
- [Container Loader](../container/page.mdx).
|
||||
- [Connection Loader](../connection-loader/page.mdx).
|
||||
|
||||
</Note>
|
||||
|
||||
Medusa provides the service factory as a function your service extends. The function creates and returns a service class with generated data-management methods.
|
||||
|
||||
For example, create the file `src/modules/hello/service.ts` with the following content:
|
||||
|
||||
Reference in new issue
Block a user