docs: update list of resources in module containers + conventions on loaders (medusajs#13107)

Author: shahednasser

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: "",
-  }
+  },
 })
 ```
 

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`.

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.
 
 <Note title="Extend the service factory when" type="success">
 
-Your service provides data-management functionalities of your data models.
+Your service provides data-management functionality for your data models.
 
 </Note>
 
@@ -48,15 +48,15 @@ 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`.
 
 ### Generated Methods
 
 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
 
 </Note>
 
-<Tabs defaultValue="listMyCustoms" layoutType="vertical" className="mt-2">
+<Tabs defaultValue="listPosts" layoutType="vertical" className="mt-2">
   <TabsList>
     <TabsTriggerVertical value="listPosts">listPosts</TabsTriggerVertical>
     <TabsTriggerVertical value="listAndCountPosts">listAndCountPosts</TabsTriggerVertical>
@@ -78,7 +78,7 @@ Find a complete reference of each of the methods in [this documentation](!resour
     <TabsTriggerVertical value="restorePosts">restorePosts</TabsTriggerVertical>
   </TabsList>
   <TabsContentWrapper className="[&_h3]:!mt-0">
-    <TabsContent value="listMyCustoms">
+    <TabsContent value="listPosts">
 
     ### 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.`)
+}
+```

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"
 }