docs-util: support generating helper steps (#8354)

www/utils/packages/typedoc-config/core-flows.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+  "extends": [
+    "../../../../packages/core/core-flows/tsconfig.json"
+  ]
+}

www/utils/packages/typedoc-config/modules-sdk.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+  "extends": [
+    "../../../../packages/core/modules-sdk/tsconfig.json"
+  ]
+}

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

@@ -38,6 +38,18 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
     name: "fulfillment-provider",
     parentIgnore: true,
   }),
+  "helper-steps": getOptions({
+    entryPointPath: "packages/core/core-flows/src/common/index.ts",
+    tsConfigName: "core-flows.json",
+    name: "helper-steps",
+    exclude: [
+      ...(baseOptions.exclude || []),
+      path.join(
+        rootPathPrefix,
+        "packages/core/core-flows/src/common/workflows/**.ts"
+      ),
+    ],
+  }),
   "medusa-config": getOptions({
     entryPointPath: "packages/core/types/src/common/config-module.ts",
     tsConfigName: "types.json",
@@ -104,6 +116,11 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
       ...modules.map((moduleName) => `**/${moduleName}/**/*.ts`),
     ],
   }),
+  "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/helper-steps.ts

@@ -0,0 +1,51 @@
+import { FormattingOptionsType } from "types"
+import baseSectionsOptions from "../base-section-options.js"
+
+const helperStepsOptions: FormattingOptionsType = {
+  "^helper_steps": {
+    expandMembers: true,
+    sections: {
+      ...baseSectionsOptions,
+      member_getterSetter: false,
+    },
+    maxLevel: 2,
+  },
+  "^modules/helper_steps/page\\.mdx": {
+    reflectionDescription:
+      "This section of the documentation provides a reference to utility steps that you can use in your workflows. These steps are imported from the `@medusajs/core-flows` package.",
+    reflectionGroups: {
+      Namespaces: false,
+      Enumerations: false,
+      Classes: false,
+      Interfaces: false,
+      "Type Aliases": false,
+      Variables: false,
+      "Enumeration Members": false,
+      Functions: true,
+    },
+    frontmatterData: {
+      slug: "/references/helper-steps",
+    },
+    reflectionTitle: {
+      fullReplacement: "Helper Steps API Reference",
+    },
+    reflectionGroupRename: {
+      Functions: "Steps",
+    },
+  },
+  "^helper_steps/functions": {
+    reflectionDescription:
+      "This documentation provides a reference to the `{{alias}}` step. It belongs to the `@medusajs/core-flows` package.",
+    frontmatterData: {
+      slug: "/references/helper-steps/{{alias}}",
+      sidebar_label: "{{alias}}",
+    },
+    reflectionTitle: {
+      kind: false,
+      typeParameters: false,
+      suffix: "- Helper Steps API Reference",
+    },
+  },
+}
+
+export default helperStepsOptions

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

@@ -2,6 +2,7 @@ import { FormattingOptionsType } from "types"
 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"
@@ -16,6 +17,7 @@ const mergerCustomOptions: FormattingOptionsType = {
   ...dmlOptions,
   ...fileOptions,
   ...fulfillmentProviderOptions,
+  ...helperStepsOptions,
   ...medusaConfigOptions,
   ...medusaOptions,
   ...notificationOptions,

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

@@ -33,6 +33,7 @@ const mergerOptions: Partial<TypeDocOptions> = {
     ...modules,
     ...dmlModules.map((module) => `${module}-models`),
     "dml",
+    "helper-steps",
     "workflows",
   ],
   allReflectionsHaveOwnDocumentInNamespace: ["Utilities"],

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

@@ -25,8 +25,10 @@ const allReferences = [
   "dml",
   "file",
   "fulfillment-provider",
+  "helper-steps",
   "medusa-config",
   "medusa",
+  "modules-sdk",
   "notification",
   "payment-provider",
   "search",

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

@@ -66,6 +66,9 @@ import shouldExpandDeclarationChildrenHelper from "./resources/helpers/should-ex
 import startSectionsHelper from "./resources/helpers/start-sections"
 import ifDmlEntityHelper from "./resources/helpers/if-dml-entity"
 import dmlPropertiesHelper from "./resources/helpers/dml-properties"
+import ifWorkflowStepHelper from "./resources/helpers/if-workflow-step"
+import stepInputHelper from "./resources/helpers/step-input"
+import stepOutputHelper from "./resources/helpers/step-output"
 import { MarkdownTheme } from "./theme"
 
 const TEMPLATE_PATH = path.join(__dirname, "resources", "templates")
@@ -160,4 +163,7 @@ export function registerHelpers(theme: MarkdownTheme) {
   startSectionsHelper(theme)
   ifDmlEntityHelper()
   dmlPropertiesHelper()
+  ifWorkflowStepHelper()
+  stepInputHelper(theme)
+  stepOutputHelper(theme)
 }

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/if-workflow-step.ts

@@ -0,0 +1,12 @@
+import * as Handlebars from "handlebars"
+import { SignatureReflection } from "typedoc"
+import { isWorkflowStep } from "../../utils/step-utils"
+
+export default function () {
+  Handlebars.registerHelper(
+    "ifWorkflowStep",
+    function (this: SignatureReflection, options: Handlebars.HelperOptions) {
+      return isWorkflowStep(this) ? options.fn(this) : options.inverse(this)
+    }
+  )
+}

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-input.ts

@@ -0,0 +1,43 @@
+import { MarkdownTheme } from "../../theme"
+import * as Handlebars from "handlebars"
+import { SignatureReflection } from "typedoc"
+import { getStepInputType } from "../../utils/step-utils"
+import { formatParameterComponent } from "../../utils/format-parameter-component"
+import { getReflectionTypeParameters } from "../../utils/reflection-type-parameters"
+
+export default function (theme: MarkdownTheme) {
+  Handlebars.registerHelper(
+    "stepInput",
+    function (
+      this: SignatureReflection,
+      options: Handlebars.HelperOptions
+    ): string {
+      const { parameterComponent, maxLevel, parameterComponentExtraProps } =
+        theme.getFormattingOptionsForLocation()
+
+      const inputType = getStepInputType(this)
+      if (!inputType) {
+        return ""
+      }
+
+      const input = getReflectionTypeParameters({
+        reflectionType: inputType,
+        project: this.project || options.data.theme.project,
+        maxLevel,
+      })
+
+      if (!input.length) {
+        return ""
+      }
+
+      const formattedComponent = formatParameterComponent({
+        parameterComponent,
+        componentItems: input,
+        extraProps: parameterComponentExtraProps,
+        sectionTitle: options.hash.sectionTitle,
+      })
+
+      return `${Handlebars.helpers.titleLevel()} Input\n\n${formattedComponent}`
+    }
+  )
+}

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-output.ts

@@ -0,0 +1,43 @@
+import { MarkdownTheme } from "../../theme"
+import * as Handlebars from "handlebars"
+import { SignatureReflection } from "typedoc"
+import { getStepOutputType } from "../../utils/step-utils"
+import { formatParameterComponent } from "../../utils/format-parameter-component"
+import { getReflectionTypeParameters } from "../../utils/reflection-type-parameters"
+
+export default function (theme: MarkdownTheme) {
+  Handlebars.registerHelper(
+    "stepOutput",
+    function (
+      this: SignatureReflection,
+      options: Handlebars.HelperOptions
+    ): string {
+      const { parameterComponent, maxLevel, parameterComponentExtraProps } =
+        theme.getFormattingOptionsForLocation()
+
+      const outputType = getStepOutputType(this)
+      if (!outputType) {
+        return ""
+      }
+
+      const output = getReflectionTypeParameters({
+        reflectionType: outputType,
+        project: this.project || options.data.theme.project,
+        maxLevel,
+      })
+
+      if (!output.length) {
+        return ""
+      }
+
+      const formattedComponent = formatParameterComponent({
+        parameterComponent,
+        componentItems: output,
+        extraProps: parameterComponentExtraProps,
+        sectionTitle: options.hash.sectionTitle,
+      })
+
+      return `${Handlebars.helpers.titleLevel()} Output\n\n${formattedComponent}`
+    }
+  )
+}

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

@@ -4,6 +4,14 @@
 
 {{else}}
 
+{{#ifWorkflowStep}}
+
+{{> member.step}}
+
+{{else}}
+
 {{> member.signature}}
 
+{{/ifWorkflowStep}}
+
 {{/ifReactQueryType}}

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

@@ -0,0 +1,18 @@
+{{{signatureTitle accessor parent}}}
+
+{{#if (sectionEnabled "member_signature_comment")}}
+
+{{> comment}}
+
+{{/if}}
+
+{{#if (sectionEnabled "member_signature_example")}}
+
+{{{example this}}}
+
+{{/if}}
+
+{{{stepInput sectionTitle=name}}}
+
+{{{stepOutput sectionTitle=name}}}
+

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

@@ -0,0 +1,79 @@
+import { ArrayType, SignatureReflection, SomeType, UnionType } from "typedoc"
+
+export function isWorkflowStep(reflection: SignatureReflection): boolean {
+  return (
+    reflection.parent?.children?.some((child) => child.name === "__step__") ||
+    false
+  )
+}
+
+export function getStepInputType(
+  reflection: SignatureReflection
+): SomeType | undefined {
+  if (!isWorkflowStep(reflection)) {
+    return
+  }
+
+  if (!reflection.parameters?.length) {
+    return
+  }
+
+  return cleanUpType(reflection.parameters[0].type)
+}
+
+export function getStepOutputType(
+  reflection: SignatureReflection
+): SomeType | undefined {
+  if (!isWorkflowStep(reflection)) {
+    return
+  }
+
+  if (reflection.type?.type !== "intersection") {
+    return reflection.type
+  }
+
+  if (reflection.type.types.length <= 3) {
+    return
+  }
+
+  const returnType = reflection.type.types
+    .slice(0, 3)
+    .find(
+      (itemType) =>
+        itemType.type !== "reflection" || itemType.declaration.name !== "__type"
+    )
+
+  return cleanUpType(returnType)
+}
+
+function cleanUpType(itemType: SomeType | undefined): SomeType | undefined {
+  switch (itemType?.type) {
+    case "union":
+      return cleanUpUnionType(itemType)
+    case "array":
+      return cleanUpArrayType(itemType)
+    default:
+      return itemType
+  }
+}
+
+function cleanUpUnionType(unionType: UnionType): SomeType {
+  const cleanedUpTypes = unionType.types.filter(
+    (itemType) =>
+      itemType.type !== "reference" || itemType.name !== "WorkflowData"
+  )
+
+  return cleanedUpTypes.length === 1
+    ? cleanedUpTypes[0]
+    : new UnionType(cleanedUpTypes)
+}
+
+function cleanUpArrayType(arrayType: ArrayType): SomeType {
+  const cleanedUpType = cleanUpType(arrayType.elementType)
+
+  if (!cleanedUpType) {
+    return arrayType
+  }
+
+  return new ArrayType(cleanedUpType)
+}