diff --git a/www/apps/book/app/learn/fundamentals/data-models/json-properties/page.mdx b/www/apps/book/app/learn/fundamentals/data-models/json-properties/page.mdx index 652b7b4e5e..9e7268d23c 100644 --- a/www/apps/book/app/learn/fundamentals/data-models/json-properties/page.mdx +++ b/www/apps/book/app/learn/fundamentals/data-models/json-properties/page.mdx @@ -97,7 +97,7 @@ const brand = await brandModuleService.updateBrands({ id: "brand_123", metadata: { category: "electronics", - } + }, }) ``` @@ -119,7 +119,7 @@ const brand = await brandModuleService.updateBrands({ id: "brand_123", metadata: { is_featured: true, - } + }, }) ``` @@ -146,7 +146,7 @@ const brand = await brandModuleService.updateBrands({ id: "brand_123", metadata: { category: "home appliances", - } + }, }) ``` @@ -189,9 +189,9 @@ const brand = await brandModuleService.updateBrands({ metadata: { details: { warranty: "2 years", - origin: "China" - } - } + origin: "China", + }, + }, }) ``` @@ -221,7 +221,7 @@ const brand = await brandModuleService.updateBrands({ id: "brand_123", metadata: { is_featured: "", - } + }, }) ``` diff --git a/www/apps/book/app/learn/fundamentals/modules/container/page.mdx b/www/apps/book/app/learn/fundamentals/modules/container/page.mdx index b6daa783b7..5119efbad4 100644 --- a/www/apps/book/app/learn/fundamentals/modules/container/page.mdx +++ b/www/apps/book/app/learn/fundamentals/modules/container/page.mdx @@ -4,9 +4,9 @@ export const metadata = { # {metadata.title} -In this chapter, you'll learn about the module's container and how to resolve resources in that container. +In this chapter, you'll learn about the module container and how to resolve resources from it. -Since modules are [isolated](../isolation/page.mdx), each module has a local container only used by the resources of that module. +Since modules are [isolated](../isolation/page.mdx), each module has a local container used only by the resources of that module. So, resources in the module, such as services or loaders, can only resolve other resources registered in the module's container, and some Framework tools that the Medusa application registers in the module's container. @@ -16,13 +16,13 @@ Find a list of resources or dependencies registered in a module's container in [ --- -## Resolve Resources +## Resolve Resources from the Module Container -### Services +### Resolve in Services -A service's constructor accepts as a first parameter an object used to resolve resources registered in the module's container. +A service's constructor accepts as a first parameter an object used to resolve resources registered in the module's container. To resolve a resource, add the resource's registration name as a property of the object. -For example: +For example, to resolve the [Logger](../../../debugging-and-testing/logging/page.mdx) from the container: ```ts highlights={[["4"], ["10"]]} import { Logger } from "@medusajs/framework/types" @@ -44,11 +44,13 @@ export default class BlogModuleService { } ``` -### Loader +You can then use the logger in the service's methods. -A loader function accepts as a parameter an object having the property `container`. Its value is the module's container used to resolve resources. +### Resolve in Loaders -For example: +[Loaders](../loaders/page.mdx) accept an object parameter with the property `container`. Its value is the module's container that can be used to resolve resources using its `resolve` method. + +For example, to resolve the [Logger](../../../debugging-and-testing/logging/page.mdx) in a loader: ```ts highlights={[["9"]]} import { @@ -66,3 +68,69 @@ export default async function helloWorldLoader({ logger.info("[helloWorldLoader]: Hello, World!") } ``` + +You can then use the logger in the loader's code. + +--- + +## Caveat: Resolving Module Services in Loaders + +Consider a module that has a main service `BrandModuleService`, and an internal service `CmsService`. Medusa will register both of these services in the module's container. + +However, loaders are executed before any services are initialized and registered in the module's container. So, you can't resolve the `BrandModuleService` and `CmsService` in a loader. + +Instead, if your main service extends the `MedusaService` [service factory](../service-factory/page.mdx), you can resolve the internal services generated for each data model passed to the `MedusaService` function. + +For example, if the `BrandModuleService` is defined as follows: + +```ts +import { MedusaService } from "@medusajs/framework/utils" +import Brand from "./models/brand" + +class BrandModuleService extends MedusaService({ + Brand, +}) { +} + +export default BrandModuleService +``` + +Then, you can resolve the `brandService` that allows you to manage brands in the module's loader: + +```ts +import { + LoaderOptions, +} from "@medusajs/framework/types" + +export default async function helloWorldLoader({ + container, +}: LoaderOptions) { + const brandService = container.resolve("brandService") + + const brands = await brandService.list() + + console.log("[helloWorldLoader]: Brands:", brands) +} +``` + +Refer to the [Service Factory reference](!resources!/service-factory-reference) for details on the available methods in the generated services. + +--- + +## Alternative to Resolving Other Modules' Services + +Since modules are [isolated](../isolation/page.mdx), you can't resolve resources that belong to other modules from the module's container. For example, you can't resolve the Product Module's service in the Blog Module's service. + +Instead, to build commerce features that span multiple modules, you can create [workflows](../../workflows/page.mdx). In those workflows, you can resolve services of all modules registered in the Medusa application, including the services of the Product and Blog modules. + +Then, you can execute the workflows in [API routes](../../api-routes/page.mdx), [subscribers](../../events-and-subscribers/page.mdx), or [scheduled jobs](../../scheduled-jobs/page.mdx). + +Learn more and find examples in the [Module Isolation](../isolation/page.mdx) chapter. + +--- + +## Avoid Circular Dependencies + +When resolving resources in a module's services, make sure you don't create circular dependencies. For example, if `BlogModuleService` resolves `CmsService`, and `CmsService` resolves `BlogModuleService`, it will cause a circular dependency error. + +Instead, you should generally only resolve services within the main service. For example, `BlogModuleService` can resolve `CmsService`, but `CmsService` should not resolve `BlogModuleService`. \ No newline at end of file diff --git a/www/apps/book/app/learn/fundamentals/modules/service-factory/page.mdx b/www/apps/book/app/learn/fundamentals/modules/service-factory/page.mdx index f40c0e0122..3504e140b3 100644 --- a/www/apps/book/app/learn/fundamentals/modules/service-factory/page.mdx +++ b/www/apps/book/app/learn/fundamentals/modules/service-factory/page.mdx @@ -12,11 +12,11 @@ In this chapter, you’ll learn about what the service factory is and how to use Medusa provides a service factory that your module’s main service can extend. -The service factory generates data management methods for your data models in the database, so you don't have to implement these methods manually. +The service factory generates data management methods for your data models, saving you time on implementing these methods manually. -Your service provides data-management functionalities of your data models. +Your service provides data-management functionality for your data models. @@ -48,7 +48,7 @@ export default BlogModuleService ### MedusaService Parameters -The `MedusaService` function accepts one parameter, which is an object of data models to generate data-management methods for. +The `MedusaService` function accepts one parameter, which is an object of data models for which to generate data-management methods. In the example above, since the `BlogModuleService` extends `MedusaService`, it has methods to manage the `Post` data model, such as `createPosts`. @@ -56,7 +56,7 @@ In the example above, since the `BlogModuleService` extends `MedusaService`, it The service factory generates methods to manage the records of each of the data models provided in the first parameter in the database. -The method's names are the operation's name, suffixed by the data model's key in the object parameter passed to `MedusaService`. +The method names are the operation name, suffixed by the data model's key in the object parameter passed to `MedusaService`. For example, the following methods are generated for the service above: @@ -66,7 +66,7 @@ Find a complete reference of each of the methods in [this documentation](!resour - + listPosts listAndCountPosts @@ -78,7 +78,7 @@ Find a complete reference of each of the methods in [this documentation](!resour restorePosts - + ### listPosts @@ -279,7 +279,7 @@ Find a complete reference of each of the methods in [this documentation](!resour ### Using a Constructor -If you implement the `constructor` of your service, make sure to call `super` passing it `...arguments`. +If you implement a `constructor` in your service, make sure to call `super` and pass it `...arguments`. For example: @@ -297,3 +297,45 @@ class BlogModuleService extends MedusaService({ export default BlogModuleService ``` + +--- + +## Generated Internal Services + +The service factory also generates internal services for each data model passed to the `MedusaService` function. These services are registered in the module's container and can be resolved using their camel-cased names. + +For example, if the `BlogModuleService` is defined as follows: + +```ts +import { MedusaService } from "@medusajs/framework/utils" +import Post from "./models/post" + +class BlogModuleService extends MedusaService({ + Post, +}){ +} + +export default BlogModuleService +``` + +Then, you'll have a `postService` registered in the module's container that allows you to manage posts. + +Generated internal services have the same methods as the `BlogModuleService`, such as `create`, `retrieve`, `update`, and `delete`, but without the data model name suffix. + +These services are useful when you need to perform database operations in loaders, as they are executed before the module's services are registered. Learn more in the [Module Container](../container/page.mdx) documentation. + +For example, you can create a loader that logs the number of posts in the database: + +```ts +import { LoaderOptions } from "@medusajs/framework/types" + +export default async function helloWorldLoader({ + container, +}: LoaderOptions) { + const postService = container.resolve("postService") + + const [_, count] = await postService.listAndCount() + + console.log(`[helloWorldLoader]: There are ${count} posts in the database.`) +} +``` diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index df6ffc5e0e..2d93665ad3 100644 --- a/www/apps/book/generated/edit-dates.mjs +++ b/www/apps/book/generated/edit-dates.mjs @@ -16,7 +16,7 @@ export const generatedEditDates = { "app/learn/fundamentals/api-routes/page.mdx": "2025-07-25T15:19:33.365Z", "app/learn/fundamentals/modules/modules-directory-structure/page.mdx": "2025-07-25T15:40:20.362Z", "app/learn/fundamentals/events-and-subscribers/page.mdx": "2025-05-16T13:40:16.111Z", - "app/learn/fundamentals/modules/container/page.mdx": "2025-05-21T15:07:12.059Z", + "app/learn/fundamentals/modules/container/page.mdx": "2025-07-31T14:24:04.087Z", "app/learn/fundamentals/workflows/execute-another-workflow/page.mdx": "2024-12-09T15:56:22.895Z", "app/learn/fundamentals/modules/loaders/page.mdx": "2025-06-16T13:34:16.462Z", "app/learn/fundamentals/admin/widgets/page.mdx": "2025-07-25T15:08:07.035Z", @@ -38,7 +38,7 @@ export const generatedEditDates = { "app/learn/fundamentals/modules/options/page.mdx": "2025-03-18T15:12:34.510Z", "app/learn/fundamentals/data-models/relationships/page.mdx": "2025-07-16T09:51:22.141Z", "app/learn/fundamentals/workflows/compensation-function/page.mdx": "2025-04-24T13:16:00.941Z", - "app/learn/fundamentals/modules/service-factory/page.mdx": "2025-03-18T15:14:13.486Z", + "app/learn/fundamentals/modules/service-factory/page.mdx": "2025-07-31T13:27:53.791Z", "app/learn/fundamentals/modules/module-links/page.mdx": "2024-09-30T08:43:53.126Z", "app/learn/fundamentals/scheduled-jobs/execution-number/page.mdx": "2025-07-25T15:54:56.135Z", "app/learn/fundamentals/api-routes/parameters/page.mdx": "2025-02-14T08:34:03.184Z", @@ -127,5 +127,5 @@ export const generatedEditDates = { "app/learn/fundamentals/generated-types/page.mdx": "2025-07-25T13:17:35.319Z", "app/learn/introduction/from-v1-to-v2/page.mdx": "2025-07-30T08:13:48.592Z", "app/learn/debugging-and-testing/debug-workflows/page.mdx": "2025-07-30T13:45:14.117Z", - "app/learn/fundamentals/data-models/json-properties/page.mdx": "2025-07-31T10:47:27.882Z" + "app/learn/fundamentals/data-models/json-properties/page.mdx": "2025-07-31T14:25:01.268Z" } \ No newline at end of file diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt index 7ff4caeb9f..4ada615076 100644 --- a/www/apps/book/public/llms-full.txt +++ b/www/apps/book/public/llms-full.txt @@ -9695,7 +9695,7 @@ const brand = await brandModuleService.updateBrands({ id: "brand_123", metadata: { category: "electronics", - } + }, }) ``` @@ -9717,7 +9717,7 @@ const brand = await brandModuleService.updateBrands({ id: "brand_123", metadata: { is_featured: true, - } + }, }) ``` @@ -9744,7 +9744,7 @@ const brand = await brandModuleService.updateBrands({ id: "brand_123", metadata: { category: "home appliances", - } + }, }) ``` @@ -9787,9 +9787,9 @@ const brand = await brandModuleService.updateBrands({ metadata: { details: { warranty: "2 years", - origin: "China" - } - } + origin: "China", + }, + }, }) ``` @@ -9819,7 +9819,7 @@ const brand = await brandModuleService.updateBrands({ id: "brand_123", metadata: { is_featured: "", - } + }, }) ``` @@ -14939,9 +14939,9 @@ Your workflow can use services of both custom and Commerce Modules, supporting y # Module Container -In this chapter, you'll learn about the module's container and how to resolve resources in that container. +In this chapter, you'll learn about the module container and how to resolve resources from it. -Since modules are [isolated](https://docs.medusajs.com/learn/fundamentals/modules/isolation/index.html.md), each module has a local container only used by the resources of that module. +Since modules are [isolated](https://docs.medusajs.com/learn/fundamentals/modules/isolation/index.html.md), each module has a local container used only by the resources of that module. So, resources in the module, such as services or loaders, can only resolve other resources registered in the module's container, and some Framework tools that the Medusa application registers in the module's container. @@ -14951,13 +14951,13 @@ Find a list of resources or dependencies registered in a module's container in [ *** -## Resolve Resources +## Resolve Resources from the Module Container -### Services +### Resolve in Services -A service's constructor accepts as a first parameter an object used to resolve resources registered in the module's container. +A service's constructor accepts as a first parameter an object used to resolve resources registered in the module's container. To resolve a resource, add the resource's registration name as a property of the object. -For example: +For example, to resolve the [Logger](https://docs.medusajs.com/learn/debugging-and-testing/logging/index.html.md) from the container: ```ts highlights={[["4"], ["10"]]} import { Logger } from "@medusajs/framework/types" @@ -14979,11 +14979,13 @@ export default class BlogModuleService { } ``` -### Loader +You can then use the logger in the service's methods. -A loader function accepts as a parameter an object having the property `container`. Its value is the module's container used to resolve resources. +### Resolve in Loaders -For example: +[Loaders](https://docs.medusajs.com/learn/fundamentals/modules/loaders/index.html.md) accept an object parameter with the property `container`. Its value is the module's container that can be used to resolve resources using its `resolve` method. + +For example, to resolve the [Logger](https://docs.medusajs.com/learn/debugging-and-testing/logging/index.html.md) in a loader: ```ts highlights={[["9"]]} import { @@ -15002,6 +15004,72 @@ export default async function helloWorldLoader({ } ``` +You can then use the logger in the loader's code. + +*** + +## Caveat: Resolving Module Services in Loaders + +Consider a module that has a main service `BrandModuleService`, and an internal service `CmsService`. Medusa will register both of these services in the module's container. + +However, loaders are executed before any services are initialized and registered in the module's container. So, you can't resolve the `BrandModuleService` and `CmsService` in a loader. + +Instead, if your main service extends the `MedusaService` [service factory](https://docs.medusajs.com/learn/fundamentals/modules/service-factory/index.html.md), you can resolve the internal services generated for each data model passed to the `MedusaService` function. + +For example, if the `BrandModuleService` is defined as follows: + +```ts +import { MedusaService } from "@medusajs/framework/utils" +import Brand from "./models/brand" + +class BrandModuleService extends MedusaService({ + Brand, +}) { +} + +export default BrandModuleService +``` + +Then, you can resolve the `brandService` that allows you to manage brands in the module's loader: + +```ts +import { + LoaderOptions, +} from "@medusajs/framework/types" + +export default async function helloWorldLoader({ + container, +}: LoaderOptions) { + const brandService = container.resolve("brandService") + + const brands = await brandService.list() + + console.log("[helloWorldLoader]: Brands:", brands) +} +``` + +Refer to the [Service Factory reference](https://docs.medusajs.com/resources/service-factory-reference/index.html.md) for details on the available methods in the generated services. + +*** + +## Alternative to Resolving Other Modules' Services + +Since modules are [isolated](https://docs.medusajs.com/learn/fundamentals/modules/isolation/index.html.md), you can't resolve resources that belong to other modules from the module's container. For example, you can't resolve the Product Module's service in the Blog Module's service. + +Instead, to build commerce features that span multiple modules, you can create [workflows](https://docs.medusajs.com/learn/fundamentals/workflows/index.html.md). In those workflows, you can resolve services of all modules registered in the Medusa application, including the services of the Product and Blog modules. + +Then, you can execute the workflows in [API routes](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md), [subscribers](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md), or [scheduled jobs](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md). + +Learn more and find examples in the [Module Isolation](https://docs.medusajs.com/learn/fundamentals/modules/isolation/index.html.md) chapter. + +*** + +## Avoid Circular Dependencies + +When resolving resources in a module's services, make sure you don't create circular dependencies. For example, if `BlogModuleService` resolves `CmsService`, and `CmsService` resolves `BlogModuleService`, it will cause a circular dependency error. + +Instead, you should generally only resolve services within the main service. For example, `BlogModuleService` can resolve `CmsService`, but `CmsService` should not resolve `BlogModuleService`. + # Perform Database Operations in a Service @@ -16836,9 +16904,9 @@ In this chapter, you’ll learn about what the service factory is and how to use Medusa provides a service factory that your module’s main service can extend. -The service factory generates data management methods for your data models in the database, so you don't have to implement these methods manually. +The service factory generates data management methods for your data models, saving you time on implementing these methods manually. -Your service provides data-management functionalities of your data models. +Your service provides data-management functionality for your data models. *** @@ -16863,7 +16931,7 @@ export default BlogModuleService ### MedusaService Parameters -The `MedusaService` function accepts one parameter, which is an object of data models to generate data-management methods for. +The `MedusaService` function accepts one parameter, which is an object of data models for which to generate data-management methods. In the example above, since the `BlogModuleService` extends `MedusaService`, it has methods to manage the `Post` data model, such as `createPosts`. @@ -16871,7 +16939,7 @@ In the example above, since the `BlogModuleService` extends `MedusaService`, it The service factory generates methods to manage the records of each of the data models provided in the first parameter in the database. -The method's names are the operation's name, suffixed by the data model's key in the object parameter passed to `MedusaService`. +The method names are the operation name, suffixed by the data model's key in the object parameter passed to `MedusaService`. For example, the following methods are generated for the service above: @@ -16983,7 +17051,7 @@ await blogModuleService.softDeletePosts({ ### Using a Constructor -If you implement the `constructor` of your service, make sure to call `super` passing it `...arguments`. +If you implement a `constructor` in your service, make sure to call `super` and pass it `...arguments`. For example: @@ -17002,6 +17070,48 @@ class BlogModuleService extends MedusaService({ export default BlogModuleService ``` +*** + +## Generated Internal Services + +The service factory also generates internal services for each data model passed to the `MedusaService` function. These services are registered in the module's container and can be resolved using their camel-cased names. + +For example, if the `BlogModuleService` is defined as follows: + +```ts +import { MedusaService } from "@medusajs/framework/utils" +import Post from "./models/post" + +class BlogModuleService extends MedusaService({ + Post, +}){ +} + +export default BlogModuleService +``` + +Then, you'll have a `postService` registered in the module's container that allows you to manage posts. + +Generated internal services have the same methods as the `BlogModuleService`, such as `create`, `retrieve`, `update`, and `delete`, but without the data model name suffix. + +These services are useful when you need to perform database operations in loaders, as they are executed before the module's services are registered. Learn more in the [Module Container](https://docs.medusajs.com/learn/fundamentals/modules/container/index.html.md) documentation. + +For example, you can create a loader that logs the number of posts in the database: + +```ts +import { LoaderOptions } from "@medusajs/framework/types" + +export default async function helloWorldLoader({ + container, +}: LoaderOptions) { + const postService = container.resolve("postService") + + const [_, count] = await postService.listAndCount() + + console.log(`[helloWorldLoader]: There are ${count} posts in the database.`) +} +``` + # Create a Plugin @@ -80937,16 +81047,23 @@ Refer to the [JSON Properties](https://docs.medusajs.com/docs/learn/fundamentals # Service Factory Reference -This section of the documentation provides a reference of the methods generated for services extending the service factory (`MedusaService`), and how to use them. +This section of the documentation provides a reference to the methods generated for services extending the service factory (`MedusaService`) and how to use them. -Learn more about the service factory in [this documentation](https://docs.medusajs.com/docs/learn/fundamentals/modules/service-factory/index.html.md). +Refer to the [Service Factory](https://docs.medusajs.com/docs/learn/fundamentals/modules/service-factory/index.html.md) documentation to learn more. ## Method Names -Generated method names are of the format `{operationName}_{dataModelName}`, where: +When your module's main service extends the service factory, Medusa will: + +1. Generate data-management methods in your main service for each of the data models passed to the `MedusaService` function. +2. Generate internal services for each of the data models passed to the `MedusaService` function, which can be resolved in loaders. + +### Main Service Methods + +The names of the generated methods for a service extending the service factory are of the format `{operationName}_{dataModelName}`, where: - `{operationName}` is the name of the operation. For example, `create`. -- `{dataModelName}` is the pascal-case version of the data model's key that's passed in the object parameter of `MedusaService`. The name is pluralized for all operations except for the `retrieve` operation. +- `{dataModelName}` is the pascal-case version of the data model's key that's passed in the object parameter of `MedusaService`. The name is pluralized for all operations except the `retrieve` operation. Some examples of method names: @@ -80955,6 +81072,14 @@ Some examples of method names: - `retrievePost` - `listPosts` +### Internal Generated Service Methods + +The internal services are useful when you need to perform database operations in loaders, as they're executed before the module's services are registered. Learn more in the [Module Container](https://docs.medusajs.com/docs/learn/fundamentals/modules/container/index.html.md) documentation. + +For the internal services, the method names are only the operation name, without the data model name. + +For example, a `Post` data model would have a `postService` with methods like `create`, `retrieve`, `update`, and `delete`. + *** ## Methods Reference diff --git a/www/apps/resources/app/medusa-container-resources/page.mdx b/www/apps/resources/app/medusa-container-resources/page.mdx index 9711fa9d56..4e213522e9 100644 --- a/www/apps/resources/app/medusa-container-resources/page.mdx +++ b/www/apps/resources/app/medusa-container-resources/page.mdx @@ -6,21 +6,21 @@ export const metadata = { # {metadata.title} -This documentation page includes the list of resources registered in the container of the Medusa application and modules. +This reference provides the list of resources registered in the Medusa container and module containers. ## Medusa Container Resources -The following table has a list of all resources that you can resolve in your customizations outside a module (such as API routes or workflows). +The following table lists all resources that you can resolve in your customizations outside a module (such as API routes, workflows, subscribers, and scheduled jobs). -Learn more about the Medusa Container in [this documentation](!docs!/learn/fundamentals/medusa-container). +Refer to the [Medusa Container](!docs!/learn/fundamentals/medusa-container) documentation for more information on how to use these resources. -Use the `ContainerRegistrationKeys` enum imported from `@medusajs/framework/utils` where specified. +You can use the `ContainerRegistrationKeys` enum imported from `@medusajs/framework/utils` where specified. @@ -49,12 +49,12 @@ Use the `ContainerRegistrationKeys` enum imported from `@medusajs/framework/util - Configurations + [Medusa Configurations](!docs!/learn/configurations/medusa-config) - The configurations that are exported from `medusa-config.ts`. + The configurations defined in `medusa-config.ts`. @@ -67,12 +67,12 @@ Use the `ContainerRegistrationKeys` enum imported from `@medusajs/framework/util - Logger + [Logger](!docs!/learn/debugging-and-testing/logging) - An instance of Medusa CLI’s logger. You can use it to log messages to the terminal. + Utility to log messages to the terminal. @@ -108,7 +108,7 @@ Use the `ContainerRegistrationKeys` enum imported from `@medusajs/framework/util - Link function to manage links between records of two modules' data models. + Manage links between records of two modules' data models. @@ -131,8 +131,8 @@ Use the `ContainerRegistrationKeys` enum imported from `@medusajs/framework/util - - For custom modules, the registration name is the key of the module in the `modules` configuration in `medusa-config.ts`. - - For Medusa's Commerce Modules, use the `Modules` enum imported from `@medusajs/framework/utils`. + - For custom modules, the registration name is the first parameter of `Module` exported in the `index.ts` file of the module. + - For Medusa's Commerce and Infrastructural Modules, use the `Modules` enum imported from `@medusajs/framework/utils`. @@ -143,17 +143,17 @@ Use the `ContainerRegistrationKeys` enum imported from `@medusajs/framework/util ## Module Container Resources -The following table has a list of all resources that you can resolve in a module's services or loaders. +The following table lists all resources that you can resolve in a module's services or loaders. -Learn more about the Module Container in [this documentation](!docs!/learn/fundamentals/modules/container). +Refer to the [Module Container](!docs!/learn/fundamentals/modules/container) documentation for more information on how to use these resources. -Use the `ContainerRegistrationKeys` enum imported from `@medusajs/framework/utils` where specified. +Use the `ContainerRegistrationKeys` and `Modules` enums imported from `@medusajs/framework/utils` where specified. @@ -182,12 +182,12 @@ Use the `ContainerRegistrationKeys` enum imported from `@medusajs/framework/util - Logger + [Logger](!docs!/learn/debugging-and-testing/logging) - An instance of Medusa CLI’s logger. You can use it to log messages to the terminal. + Utility to log messages to the terminal. @@ -218,12 +218,12 @@ Use the `ContainerRegistrationKeys` enum imported from `@medusajs/framework/util - Base Repository + [Base Repository](!docs!/learn/fundamentals/modules/db-operations#configure-transactions-with-the-base-repository) - An instance of the base repository, used to run transactions or perform other database operations. + An instance of the base repository, used to run transactions and perform database operations. @@ -236,12 +236,12 @@ Use the `ContainerRegistrationKeys` enum imported from `@medusajs/framework/util - Configurations + [Medusa Configurations](!docs!/learn/configurations/medusa-config) - The configurations exported from `medusa-config.ts`. + The configurations defined in `medusa-config.ts`. @@ -254,19 +254,61 @@ Use the `ContainerRegistrationKeys` enum imported from `@medusajs/framework/util - Modules' services + [Event Module](../infrastructure-modules/event/page.mdx)'s service - All services exported by the `services/index.ts` file of a module. + The service of the Event Module, used to emit events. - Each service is registered by its camel-case name. For example, if the service's class name is `ClientService`, its registration name is `clientService`. + `event_bus` or `Modules.EVENT_MODULE` + + + + + + + + Services generated by the [service factory](../service-factory-reference/page.mdx) + + + + + The service of every data model passed to the `MedusaService` function that your module's service extends. The service has the methods described in the [service factory reference](../service-factory-reference/page.mdx). + + + + + Each service is registered as the camel-cased name of the data model. For example: + + - `Brand` data model's service is registered as `brandService`. + - `DigitalProduct` data model's service is registered as `digitalProductService`. + + + + + + + + Module services + + + + + You can resolve the module's services from one another, but not in loaders. Learn more in the [Module Container](!docs!/learn/fundamentals/modules/container) documentation. + + + + + Each service is registered as the camel-cased name of the service. For example: + + - `BrandModuleService` is registered as `brandModuleService`. + - `CmsService` is registered as `cmsService`. - \ No newline at end of file + diff --git a/www/apps/resources/app/service-factory-reference/page.mdx b/www/apps/resources/app/service-factory-reference/page.mdx index d6c9fc88b7..40d7a88446 100644 --- a/www/apps/resources/app/service-factory-reference/page.mdx +++ b/www/apps/resources/app/service-factory-reference/page.mdx @@ -6,20 +6,27 @@ export const metadata = { # {metadata.title} -This section of the documentation provides a reference of the methods generated for services extending the service factory (`MedusaService`), and how to use them. +This section of the documentation provides a reference to the methods generated for services extending the service factory (`MedusaService`) and how to use them. -Learn more about the service factory in [this documentation](!docs!/learn/fundamentals/modules/service-factory). +Refer to the [Service Factory](!docs!/learn/fundamentals/modules/service-factory) documentation to learn more. ## Method Names -Generated method names are of the format `{operationName}_{dataModelName}`, where: +When your module's main service extends the service factory, Medusa will: + +1. Generate data-management methods in your main service for each of the data models passed to the `MedusaService` function. +2. Generate internal services for each of the data models passed to the `MedusaService` function, which can be resolved in loaders. + +### Main Service Methods + +The names of the generated methods for a service extending the service factory are of the format `{operationName}_{dataModelName}`, where: - `{operationName}` is the name of the operation. For example, `create`. -- `{dataModelName}` is the pascal-case version of the data model's key that's passed in the object parameter of `MedusaService`. The name is pluralized for all operations except for the `retrieve` operation. +- `{dataModelName}` is the pascal-case version of the data model's key that's passed in the object parameter of `MedusaService`. The name is pluralized for all operations except the `retrieve` operation. Some examples of method names: @@ -28,6 +35,14 @@ Some examples of method names: - `retrievePost` - `listPosts` +### Internal Generated Service Methods + +The internal services are useful when you need to perform database operations in loaders, as they're executed before the module's services are registered. Learn more in the [Module Container](!docs!/learn/fundamentals/modules/container) documentation. + +For the internal services, the method names are only the operation name, without the data model name. + +For example, a `Post` data model would have a `postService` with methods like `create`, `retrieve`, `update`, and `delete`. + --- ## Methods Reference diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs index deb490ee4c..d8c7034078 100644 --- a/www/apps/resources/generated/edit-dates.mjs +++ b/www/apps/resources/generated/edit-dates.mjs @@ -106,7 +106,7 @@ export const generatedEditDates = { "app/deployment/page.mdx": "2025-06-24T08:50:10.114Z", "app/integrations/page.mdx": "2025-06-25T10:48:35.928Z", "app/medusa-cli/page.mdx": "2024-08-28T11:25:32.382Z", - "app/medusa-container-resources/page.mdx": "2025-04-17T08:48:10.255Z", + "app/medusa-container-resources/page.mdx": "2025-07-31T13:24:15.786Z", "app/medusa-workflows-reference/page.mdx": "2025-01-20T08:21:29.962Z", "app/nextjs-starter/page.mdx": "2025-02-26T11:37:47.137Z", "app/recipes/b2b/page.mdx": "2025-05-20T07:51:40.718Z", @@ -133,7 +133,7 @@ export const generatedEditDates = { "app/service-factory-reference/methods/soft-delete/page.mdx": "2024-07-31T17:01:33+03:00", "app/service-factory-reference/methods/update/page.mdx": "2025-07-31T08:24:03.685Z", "app/service-factory-reference/tips/filtering/page.mdx": "2025-04-23T14:38:29.068Z", - "app/service-factory-reference/page.mdx": "2024-07-26T14:40:56+00:00", + "app/service-factory-reference/page.mdx": "2025-07-31T13:29:12.136Z", "app/storefront-development/cart/context/page.mdx": "2025-03-27T14:47:14.258Z", "app/storefront-development/cart/create/page.mdx": "2025-03-27T14:46:51.473Z", "app/storefront-development/cart/manage-items/page.mdx": "2025-03-26T15:54:31.446Z",