From fffd4f2b3b226e06def7cf7e205dde0685ee36e9 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Tue, 30 Jul 2024 19:06:16 +0300 Subject: [PATCH] docs-util: support generating helper steps (#8354) --- .../packages/typedoc-config/core-flows.json | 6 ++ .../packages/typedoc-config/modules-sdk.json | 6 ++ .../src/constants/custom-options.ts | 17 ++++ .../merger-custom-options/helper-steps.ts | 51 ++++++++++++ .../constants/merger-custom-options/index.ts | 2 + .../src/constants/merger-options.ts | 1 + .../src/constants/references.ts | 2 + .../src/render-utils.ts | 6 ++ .../src/resources/helpers/if-workflow-step.ts | 12 +++ .../src/resources/helpers/step-input.ts | 43 ++++++++++ .../src/resources/helpers/step-output.ts | 43 ++++++++++ .../partials/member.signature-wrapper.hbs | 8 ++ .../src/resources/partials/member.step.hbs | 18 +++++ .../src/utils/step-utils.ts | 79 +++++++++++++++++++ 14 files changed, 294 insertions(+) create mode 100644 www/utils/packages/typedoc-config/core-flows.json create mode 100644 www/utils/packages/typedoc-config/modules-sdk.json create mode 100644 www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/helper-steps.ts create mode 100644 www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/if-workflow-step.ts create mode 100644 www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-input.ts create mode 100644 www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-output.ts create mode 100644 www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.step.hbs create mode 100644 www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/step-utils.ts diff --git a/www/utils/packages/typedoc-config/core-flows.json b/www/utils/packages/typedoc-config/core-flows.json new file mode 100644 index 0000000000..0cbf3d84da --- /dev/null +++ b/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" + ] +} \ No newline at end of file diff --git a/www/utils/packages/typedoc-config/modules-sdk.json b/www/utils/packages/typedoc-config/modules-sdk.json new file mode 100644 index 0000000000..0ca89faf8c --- /dev/null +++ b/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" + ] +} \ No newline at end of file diff --git a/www/utils/packages/typedoc-generate-references/src/constants/custom-options.ts b/www/utils/packages/typedoc-generate-references/src/constants/custom-options.ts index 412fdf1e76..4bedce1c2b 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/custom-options.ts +++ b/www/utils/packages/typedoc-generate-references/src/constants/custom-options.ts @@ -38,6 +38,18 @@ const customOptions: Record> = { 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> = { ...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", diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/helper-steps.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/helper-steps.ts new file mode 100644 index 0000000000..218cdc4745 --- /dev/null +++ b/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 diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/index.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/index.ts index 194a4da0fd..c708d43dd5 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/index.ts +++ b/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, diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-options.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-options.ts index 9ee8209101..a5d2303951 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/merger-options.ts +++ b/www/utils/packages/typedoc-generate-references/src/constants/merger-options.ts @@ -33,6 +33,7 @@ const mergerOptions: Partial = { ...modules, ...dmlModules.map((module) => `${module}-models`), "dml", + "helper-steps", "workflows", ], allReflectionsHaveOwnDocumentInNamespace: ["Utilities"], diff --git a/www/utils/packages/typedoc-generate-references/src/constants/references.ts b/www/utils/packages/typedoc-generate-references/src/constants/references.ts index 6d23dd988b..7971c84813 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/references.ts +++ b/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", diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts index 2d311797d7..ef44c29e7a 100644 --- a/www/utils/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts +++ b/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) } diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/if-workflow-step.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/if-workflow-step.ts new file mode 100644 index 0000000000..945c41ac35 --- /dev/null +++ b/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) + } + ) +} diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-input.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-input.ts new file mode 100644 index 0000000000..68f5f2df95 --- /dev/null +++ b/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}` + } + ) +} diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-output.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-output.ts new file mode 100644 index 0000000000..d496347b0d --- /dev/null +++ b/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}` + } + ) +} diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.signature-wrapper.hbs b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.signature-wrapper.hbs index b8620ae5d4..07053d706c 100644 --- a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.signature-wrapper.hbs +++ b/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}} \ No newline at end of file diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.step.hbs b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.step.hbs new file mode 100644 index 0000000000..f4a204176d --- /dev/null +++ b/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}}} + diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/step-utils.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/step-utils.ts new file mode 100644 index 0000000000..85eace1ead --- /dev/null +++ b/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) +}