docs: add missing methods in guides and references (#12495)

* initial

* remove unused references

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

@@ -155,11 +155,6 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
     tsConfigName: "utils.json",
     name: "payment-provider",
   }),
-  search: getOptions({
-    entryPointPath: "packages/core/utils/src/search/abstract-service.ts",
-    tsConfigName: "utils.json",
-    name: "search",
-  }),
   "tax-provider": getOptions({
     entryPointPath: "packages/core/types/src/tax/provider.ts",
     tsConfigName: "types.json",
@@ -205,7 +200,6 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
       "**/orchestration/**",
       "**/pg/**",
       "**/pricing/builders.ts",
-      "**/search/**",
       "**/totals/**",
     ],
   }),

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

@@ -19,6 +19,7 @@ const authProviderOptions: FormattingOptionsType = {
     shouldIncrementAfterStartSections: true,
     expandMembers: true,
     expandProperties: true,
+    sortMembers: true,
     sections: {
       ...baseSectionsOptions,
       member_declaration_title: false,

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

@@ -16,6 +16,7 @@ const cacheOptions: FormattingOptionsType = {
       fullReplacement: "How to Use Cache Module",
     },
     expandMembers: true,
+    sortMembers: true,
     startSections: [
       `## Resolve Cache Module's Service
 

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

@@ -15,6 +15,7 @@ const fileServiceOptions: FormattingOptionsType = {
       fullReplacement: "How to Use File Module",
     },
     expandMembers: true,
+    sortMembers: true,
     startSections: [
       `## Resolve File Module's Service
 

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

@@ -17,6 +17,7 @@ const fileOptions: FormattingOptionsType = {
     shouldIncrementAfterStartSections: true,
     expandMembers: true,
     expandProperties: true,
+    sortMembers: true,
     sections: {
       ...baseSectionsOptions,
       member_declaration_title: false,

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

@@ -19,6 +19,7 @@ const fulfillmentProviderOptions: FormattingOptionsType = {
     shouldIncrementAfterStartSections: true,
     expandMembers: true,
     expandProperties: true,
+    sortMembers: true,
     sections: {
       ...baseSectionsOptions,
       member_declaration_title: false,

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

@@ -3,11 +3,9 @@ import authProviderOptions from "./auth-provider.js"
 import fileOptions from "./file.js"
 import fulfillmentProviderOptions from "./fulfillment-provider.js"
 import helperStepsOptions from "./helper-steps.js"
-import medusaConfigOptions from "./medusa-config.js"
 import medusaOptions from "./medusa.js"
 import notificationOptions from "./notification.js"
 import paymentProviderOptions from "./payment-provider.js"
-import searchOptions from "./search.js"
 import taxProviderOptions from "./tax-provider.js"
 import workflowsOptions from "./workflows.js"
 import dmlOptions from "./dml.js"
@@ -33,12 +31,10 @@ const mergerCustomOptions: FormattingOptionsType = {
   ...helperStepsOptions,
   ...jsSdkOptions,
   ...lockingOptions,
-  ...medusaConfigOptions,
   ...medusaOptions,
   ...notificationServiceOptions,
   ...notificationOptions,
   ...paymentProviderOptions,
-  ...searchOptions,
   ...taxProviderOptions,
   ...workflowsOptions,
 }

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

@@ -19,6 +19,7 @@ const lockingOptions: FormattingOptionsType = {
     shouldIncrementAfterStartSections: true,
     expandMembers: true,
     expandProperties: true,
+    sortMembers: true,
     sections: {
       ...baseSectionsOptions,
       member_declaration_title: false,
@@ -139,6 +140,7 @@ The Locking Module will now use your provider to handle all locking operations.
       fullReplacement: "How to Use Locking Module",
     },
     expandMembers: true,
+    sortMembers: true,
     startSections: [
       `## Resolve Locking Module's Service
 

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

@@ -1,28 +0,0 @@
-import { FormattingOptionsType } from "types"
-import baseSectionsOptions from "../base-section-options.js"
-
-const medusaConfigOptions: FormattingOptionsType = {
-  "^medusa_config": {
-    expandMembers: true,
-  },
-  "^medusa_config/.*ConfigModule": {
-    frontmatterData: {
-      slug: "/references/medusa-config",
-    },
-    reflectionDescription: `In this document, you’ll learn how to create a file service in the Medusa application and the methods you must implement in it.`,
-    reflectionTitle: {
-      fullReplacement: "Configure Medusa Backend",
-    },
-    expandMembers: true,
-    expandProperties: true,
-    sections: {
-      ...baseSectionsOptions,
-      member_declaration_title: false,
-      member_declaration_children: true,
-      member_declaration_typeDeclaration: false,
-      member_declaration_signatures: false,
-    },
-  },
-}
-
-export default medusaConfigOptions

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

@@ -16,6 +16,7 @@ const notificationServiceOptions: FormattingOptionsType = {
       fullReplacement: "How to Use Notification Module",
     },
     expandMembers: true,
+    sortMembers: true,
     startSections: [
       `## Resolve Notification Module's Service
 

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

@@ -19,6 +19,7 @@ const paymentProviderOptions: FormattingOptionsType = {
     shouldIncrementAfterStartSections: true,
     expandMembers: true,
     expandProperties: true,
+    sortMembers: true,
     sections: {
       ...baseSectionsOptions,
       member_declaration_title: false,

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

@@ -1,54 +0,0 @@
-import { FormattingOptionsType } from "types"
-
-const searchOptions: FormattingOptionsType = {
-  "^search/.*AbstractSearchService": {
-    reflectionDescription: `In this document, you’ll learn how to create a search service in the Medusa backend and the methods you must implement in it.
-
-## Prerequisites
-
-A search service must extend the \`AbstractSearchService\` class imported from the \`@medusajs/framework/utils\` package. If you don’t already have the package 
-installed, run the following command to install it within your project:
-
-\`\`\`bash npm2yarn
-npm install @medusajs/utils
-\`\`\`
-
----`,
-    frontmatterData: {
-      slug: "/references/search-service",
-    },
-    reflectionTitle: {
-      fullReplacement: "How to Create a Search Service",
-    },
-    endSections: [
-      `## Test Implementation
-
-:::note
-
-If you created your search service in a plugin, refer to [this guide on how to test plugins](https://docs.medusajs.com/development/plugins/create#test-your-plugin).
-
-:::
-
-After finishing your search service implementation:
-
-1\\. Make sure you have an [event bus module](https://docs.medusajs.com/development/events/modules/redis) installed that triggers search indexing when the Medusa backend loads.
-
-2\\. Run the \`build\` command in the root of your Medusa backend:
-
-\`\`\`bash npm2yarn
-npm run build
-\`\`\`
-
-3\\. Start the backend with the \`develop\` command:
-
-\`\`\`bash
-npx medusa develop
-\`\`\`
-
-4\\. Try to search for products either using the [Search Products API Route](https://docs.medusajs.com/api/store#products_postproductssearch). The results returned by your search service's \`search\` method is returned in the \`hits\` response field.
-    `,
-    ],
-  },
-}
-
-export default searchOptions

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

@@ -18,6 +18,7 @@ const taxProviderOptions: FormattingOptionsType = {
     shouldIncrementAfterStartSections: true,
     expandMembers: true,
     expandProperties: true,
+    sortMembers: true,
     startSections: [
       `## Overview
 

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

@@ -32,7 +32,6 @@ const allReferences = [
   "modules-sdk",
   "notification",
   "payment-provider",
-  "search",
   "tax-provider",
   "types",
   "utils",

www/utils/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts

@@ -83,6 +83,8 @@ import stepExamplesHelper from "./resources/helpers/step-examples.js"
 import ifEventsReferenceHelper from "./resources/helpers/if-events-reference.js"
 import eventsListingHelper from "./resources/helpers/events-listing.js"
 import workflowEventsHelper from "./resources/helpers/workflow-events.js"
+import getAllChildrenHelper from "./resources/helpers/get-all-children.js"
+import reflectionBadgesHelper from "./resources/helpers/reflection-badges.js"
 import { MarkdownTheme } from "./theme.js"
 import { getDirname } from "utils"
 
@@ -197,4 +199,6 @@ export function registerHelpers(theme: MarkdownTheme) {
   ifEventsReferenceHelper(theme)
   eventsListingHelper()
   workflowEventsHelper()
+  getAllChildrenHelper(theme)
+  reflectionBadgesHelper()
 }

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/get-all-children.ts

@@ -0,0 +1,54 @@
+import Handlebars from "handlebars"
+import { DeclarationReflection, ReflectionGroup } from "typedoc"
+import { getProjectChild } from "utils"
+import { MarkdownTheme } from "../../theme.js"
+
+export default function (theme: MarkdownTheme) {
+  Handlebars.registerHelper("getAllChildren", function (this: ReflectionGroup) {
+    const { sortMembers } = theme.getFormattingOptionsForLocation()
+    if (!this.children) {
+      return []
+    }
+    const children = [...this.children]
+    const implementedTypes = (this.owningReflection as DeclarationReflection)
+      .implementedTypes
+    implementedTypes?.forEach((type) => {
+      if (type.type !== "reference") {
+        return
+      }
+
+      const referencedReflection = type.reflection
+        ? type.reflection
+        : getProjectChild(this.owningReflection.project, type.name)
+
+      if (
+        !referencedReflection ||
+        !(referencedReflection instanceof DeclarationReflection)
+      ) {
+        return
+      }
+
+      const matchingGroup = referencedReflection.groups?.find(
+        (group) => group.title === this.title
+      )
+      matchingGroup?.children?.forEach((child) => {
+        if (
+          !(child instanceof DeclarationReflection) ||
+          children.find((c) => c.id === child.id || c.name === child.name)
+        ) {
+          return
+        }
+        children.push(child)
+      })
+    })
+
+    if (sortMembers) {
+      // sort alphabetically
+      children.sort((a, b) => {
+        return a.name.localeCompare(b.name)
+      })
+    }
+
+    return children
+  })
+}

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/reflection-badges.ts

@@ -0,0 +1,36 @@
+import Handlebars from "handlebars"
+import { DeclarationReflection } from "typedoc"
+
+export default function () {
+  Handlebars.registerHelper(
+    "reflectionBadges",
+    function (this: DeclarationReflection) {
+      const badges: {
+        variant: string
+        children: string
+        [k: string]: string
+      }[] = []
+
+      // TODO maybe support more badges
+      const isOptional =
+        this.flags.isOptional ||
+        this.signatures?.some((s) => s.flags.isOptional)
+      if (isOptional) {
+        badges.push({
+          variant: "neutral",
+          children: "optional",
+        })
+      }
+
+      if (!badges.length) {
+        return ""
+      }
+
+      return `<BadgesList badges={${JSON.stringify(
+        badges,
+        null,
+        2
+      )}} className="mb-1" />`
+    }
+  )
+}

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.hbs

@@ -4,6 +4,8 @@
 
 {{titleLevel}} {{#ifNamedAnchors}}<a id="{{anchor}}" name="{{this.anchor}}"></a> {{/ifNamedAnchors}}{{ escape name }}
 
+{{{reflectionBadges}}}
+
 {{incrementCurrentTitleLevel}}
 
 {{/if}}

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/partials/members.group.hbs

@@ -24,7 +24,7 @@ ___
 
 {{#if (shouldExpandProperties title)}}
 
-{{#each children}}
+{{#each (getAllChildren)}}
 
 {{> member }}
 
@@ -32,7 +32,7 @@ ___
 
 {{else if (showPropertiesAsComponent title)}}
 
-{{#with children}}
+{{#with (getAllChildren)}}
 
 {{{parameterComponent sectionTitle=../owningReflection.name}}}
 
@@ -40,7 +40,7 @@ ___
 
 {{else}}
 
-{{#each children}}
+{{#each (getAllChildren)}}
 
 {{> member }}
 
@@ -76,7 +76,7 @@ ___
 
 {{#if (shouldExpandProperties title)}}
 
-{{#each children}}
+{{#each (getAllChildren)}}
 
 {{> member }}
 
@@ -84,7 +84,7 @@ ___
 
 {{else if (showPropertiesAsComponent title)}}
 
-{{#with children}}
+{{#with (getAllChildren)}}
 
 {{{parameterComponent sectionTitle=../owningReflection.name}}}
 
@@ -92,7 +92,7 @@ ___
 
 {{else}}
 
-{{#each children}}
+{{#each (getAllChildren)}}
 
 {{> member}}
 

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/partials/members.hbs

@@ -20,7 +20,7 @@ ___
 
 {{/unless}}
 
-{{#each children}}
+{{#each getAllChildren}}
 
 {{#unless hasOwnDocument}}
 

www/utils/packages/types/lib/index.d.ts

@@ -102,6 +102,7 @@ export type FormattingOptionType = {
   hideTocHeaders?: boolean
   workflowDiagramComponent?: string
   isEventsReference?: boolean
+  sortMembers?: boolean
 }
 
 export type AllowedProjectDocumentsOption = {