docs: added how-to guides for architectural modules (#11883)

* added initial how-tos

* finished changes

* generated sidebars

www/utils/packages/typedoc-generate-references/src/constants/custom-options.ts

@@ -11,6 +11,17 @@ import { modules } from "./references.js"
 import { getCoreFlowNamespaces } from "../utils/get-namespaces.js"
 
 const customOptions: Record<string, Partial<TypeDocOptions>> = {
+  "auth-provider": getOptions({
+    entryPointPath: "packages/core/utils/src/auth/abstract-auth-provider.ts",
+    tsConfigName: "utils.json",
+    name: "auth-provider",
+    parentIgnore: true,
+  }),
+  cache: getOptions({
+    entryPointPath: "packages/core/types/src/cache/service.ts",
+    tsConfigName: "types.json",
+    name: "cache",
+  }),
   "core-flows": getOptions({
     entryPointPath: "packages/core/core-flows/src/index.ts",
     tsConfigName: "core-flows.json",
@@ -21,17 +32,6 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
     // @ts-expect-error there's a typing issue in typedoc
     generatePathNamespaces: getCoreFlowNamespaces(),
   }),
-  "auth-provider": getOptions({
-    entryPointPath: "packages/core/utils/src/auth/abstract-auth-provider.ts",
-    tsConfigName: "utils.json",
-    name: "auth-provider",
-    parentIgnore: true,
-  }),
-  locking: getOptions({
-    entryPointPath: "packages/core/types/src/locking/index.ts",
-    tsConfigName: "types.json",
-    name: "locking",
-  }),
   dml: getOptions({
     entryPointPath: [
       "packages/core/utils/src/dml/entity-builder.ts",
@@ -42,29 +42,28 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
     name: "dml",
     generateCustomNamespaces: true,
   }),
+  event: getOptions({
+    entryPointPath: "packages/core/types/src/event-bus/event-bus-module.ts",
+    tsConfigName: "types.json",
+    name: "event",
+  }),
   file: getOptions({
     entryPointPath: "packages/core/utils/src/file/abstract-file-provider.ts",
     tsConfigName: "utils.json",
     name: "file",
     parentIgnore: true,
   }),
+  "file-service": getOptions({
+    entryPointPath: "packages/core/types/src/file/service.ts",
+    tsConfigName: "types.json",
+    name: "file-service",
+  }),
   "fulfillment-provider": getOptions({
     entryPointPath: "packages/core/utils/src/fulfillment/provider.ts",
     tsConfigName: "utils.json",
     name: "fulfillment-provider",
     parentIgnore: true,
   }),
-  "js-sdk": getOptions({
-    entryPointPath: [
-      "packages/core/js-sdk/src/admin/index.ts",
-      "packages/core/js-sdk/src/auth/index.ts",
-      "packages/core/js-sdk/src/store/index.ts",
-    ],
-    tsConfigName: "js-sdk.json",
-    name: "js-sdk",
-    enableInternalResolve: true,
-    exclude: [...(baseOptions.exclude || []), "**/dist/**"],
-  }),
   "helper-steps": getOptions({
     entryPointPath: "packages/core/core-flows/src/common/index.ts",
     tsConfigName: "core-flows.json",
@@ -77,6 +76,22 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
       ),
     ],
   }),
+  "js-sdk": getOptions({
+    entryPointPath: [
+      "packages/core/js-sdk/src/admin/index.ts",
+      "packages/core/js-sdk/src/auth/index.ts",
+      "packages/core/js-sdk/src/store/index.ts",
+    ],
+    tsConfigName: "js-sdk.json",
+    name: "js-sdk",
+    enableInternalResolve: true,
+    exclude: [...(baseOptions.exclude || []), "**/dist/**"],
+  }),
+  locking: getOptions({
+    entryPointPath: "packages/core/types/src/locking/index.ts",
+    tsConfigName: "types.json",
+    name: "locking",
+  }),
   medusa: getOptions({
     entryPointPath: "packages/medusa/src/index.ts",
     tsConfigName: "medusa.json",
@@ -104,6 +119,11 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
       "**/modules-config.ts",
     ],
   }),
+  "modules-sdk": getOptions({
+    entryPointPath: "packages/core/modules-sdk/src/index.ts",
+    tsConfigName: "modules-sdk.json",
+    name: "modules-sdk",
+  }),
   notification: getOptions({
     entryPointPath:
       "packages/core/utils/src/notification/abstract-notification-provider.ts",
@@ -111,6 +131,11 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
     name: "notification",
     parentIgnore: true,
   }),
+  "notification-service": getOptions({
+    entryPointPath: "packages/core/types/src/notification/service.ts",
+    tsConfigName: "types.json",
+    name: "notification-service",
+  }),
   "payment-provider": getOptions({
     entryPointPath:
       "packages/core/utils/src/payment/abstract-payment-provider.ts",
@@ -143,11 +168,6 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
       ),
     ],
   }),
-  "modules-sdk": getOptions({
-    entryPointPath: "packages/core/modules-sdk/src/index.ts",
-    tsConfigName: "modules-sdk.json",
-    name: "modules-sdk",
-  }),
   utils: getOptions({
     entryPointPath: "packages/core/utils/src/index.ts",
     tsConfigName: "utils.json",

www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/cache.ts

@@ -0,0 +1,49 @@
+import { FormattingOptionsType } from "types"
+
+const cacheOptions: FormattingOptionsType = {
+  "^cache/.*ICacheService": {
+    reflectionGroups: {
+      Constructors: false,
+    },
+    reflectionDescription: `In this document, you’ll learn about the different methods in the Cache Module's service and how to use them.`,
+    frontmatterData: {
+      slug: "/references/cache-service",
+      tags: ["cache", "server", "how to"],
+      sidebar_label: "Use Cache Module",
+    },
+    reflectionTitle: {
+      fullReplacement: "How to Use Cache Module",
+    },
+    expandMembers: true,
+    startSections: [
+      `## Resolve Cache Module's Service
+
+In your workflow's step, you can resolve the Cache Module's service from the Medusa container:
+
+\`\`\`ts
+import { Modules } from "@medusajs/framework/utils"
+import { createStep } from "@medusajs/framework/workflows-sdk"
+
+const step1 = createStep(
+  "step-1",
+  async ({}, { container }) => {
+    const cacheModuleService = container.resolve(
+      Modules.CACHE
+    )
+    
+    // TODO use cacheModuleService
+  } 
+)
+\`\`\`
+
+This will resolve the service of the configured Cache Module, which is the [In-Memory Cache Module](https://docs.medusajs.com/resources/architectural-modules/cache/in-memory) by default.
+
+You can then use the Cache Module's service's methods in the step. The rest of this guide details these methods.
+
+---
+`,
+    ],
+  },
+}
+
+export default cacheOptions

www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/event.ts

@@ -0,0 +1,49 @@
+import { FormattingOptionsType } from "types"
+
+const eventOptions: FormattingOptionsType = {
+  "^event/.*IEventBusModuleService": {
+    reflectionGroups: {
+      Constructors: false,
+    },
+    reflectionDescription: `In this document, you’ll learn about the different methods in the Event Module's service and how to use them.`,
+    frontmatterData: {
+      slug: "/references/event-service",
+      tags: ["event", "server", "how to"],
+      sidebar_label: "Use Event Module",
+    },
+    reflectionTitle: {
+      fullReplacement: "How to Use Event Module",
+    },
+    expandMembers: true,
+    startSections: [
+      `## Resolve Event Module's Service
+
+In your workflow's step, you can resolve the Event Module's service from the Medusa container:
+
+\`\`\`ts
+import { Modules } from "@medusajs/framework/utils"
+import { createStep } from "@medusajs/framework/workflows-sdk"
+
+const step1 = createStep(
+  "step-1",
+  async ({}, { container }) => {
+    const eventModuleService = container.resolve(
+      Modules.EVENT
+    )
+    
+    // TODO use eventModuleService
+  } 
+)
+\`\`\`
+
+This will resolve the service of the configured Event Module, which is the [Local Event Module](https://docs.medusajs.com/resources/architectural-modules/event/local) by default.
+
+You can then use the Event Module's service's methods in the step. The rest of this guide details these methods.
+
+---
+`,
+    ],
+  },
+}
+
+export default eventOptions

www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/file-service.ts

@@ -0,0 +1,47 @@
+import { FormattingOptionsType } from "types"
+
+const fileServiceOptions: FormattingOptionsType = {
+  "^file_service/.*IFileModuleService": {
+    reflectionGroups: {
+      Constructors: false,
+    },
+    reflectionDescription: `In this document, you’ll learn about the different methods in the File Module's service and how to use them.`,
+    frontmatterData: {
+      slug: "/references/file-service",
+      tags: ["file", "server", "how to"],
+      sidebar_label: "Use File Module",
+    },
+    reflectionTitle: {
+      fullReplacement: "How to Use File Module",
+    },
+    expandMembers: true,
+    startSections: [
+      `## Resolve File Module's Service
+
+In your workflow's step, you can resolve the File Module's service from the Medusa container:
+
+\`\`\`ts
+import { Modules } from "@medusajs/framework/utils"
+import { createStep } from "@medusajs/framework/workflows-sdk"
+
+const step1 = createStep(
+  "step-1",
+  async ({}, { container }) => {
+    const fileModuleService = container.resolve(
+      Modules.FILE
+    )
+    
+    // TODO use fileModuleService
+  } 
+)
+\`\`\`
+
+You can then use the File Module's service's methods in the step. The rest of this guide details these methods.
+
+---
+`,
+    ],
+  },
+}
+
+export default fileServiceOptions

www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/index.ts

@@ -14,11 +14,18 @@ import dmlOptions from "./dml.js"
 import coreFlowsOptions from "./core-flows.js"
 import jsSdkOptions from "./js-sdk.js"
 import lockingOptions from "./locking.js"
+import cacheOptions from "./cache.js"
+import eventOptions from "./event.js"
+import fileServiceOptions from "./file-service.js"
+import notificationServiceOptions from "./notification-service.js"
 
 const mergerCustomOptions: FormattingOptionsType = {
   ...authProviderOptions,
+  ...cacheOptions,
   ...coreFlowsOptions,
   ...dmlOptions,
+  ...eventOptions,
+  ...fileServiceOptions,
   ...fileOptions,
   ...fulfillmentProviderOptions,
   ...helperStepsOptions,
@@ -26,6 +33,7 @@ const mergerCustomOptions: FormattingOptionsType = {
   ...lockingOptions,
   ...medusaConfigOptions,
   ...medusaOptions,
+  ...notificationServiceOptions,
   ...notificationOptions,
   ...paymentProviderOptions,
   ...searchOptions,

www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/notification-service.ts

@@ -0,0 +1,47 @@
+import { FormattingOptionsType } from "types"
+
+const notificationServiceOptions: FormattingOptionsType = {
+  "^notification_service/.*INotificationModuleService": {
+    reflectionGroups: {
+      Constructors: false,
+    },
+    reflectionDescription: `In this document, you’ll learn about the different methods in the Notification Module's service and how to use them.`,
+    frontmatterData: {
+      slug: "/references/notification-service",
+      tags: ["notification", "server", "how to"],
+      sidebar_label: "Use Notification Module",
+    },
+    reflectionTitle: {
+      fullReplacement: "How to Use Notification Module",
+    },
+    expandMembers: true,
+    startSections: [
+      `## Resolve Notification Module's Service
+
+In your workflow's step, you can resolve the Notification Module's service from the Medusa container:
+
+\`\`\`ts
+import { Modules } from "@medusajs/framework/utils"
+import { createStep } from "@medusajs/framework/workflows-sdk"
+
+const step1 = createStep(
+  "step-1",
+  async ({}, { container }) => {
+    const notificationModuleService = container.resolve(
+      Modules.NOTIFICATION
+    )
+    
+    // TODO use notificationModuleService
+  } 
+)
+\`\`\`
+
+You can then use the Notification Module's service's methods in the step. The rest of this guide details these methods.
+
+---
+`,
+    ],
+  },
+}
+
+export default notificationServiceOptions

www/utils/packages/typedoc-generate-references/src/constants/references.ts

@@ -39,6 +39,10 @@ const allReferences = [
   "utils",
   "workflows",
   "locking",
+  "cache",
+  "event",
+  "file-service",
+  "notification-service",
 ]
 
 export default allReferences