asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: fixes to workflow reference tooling (#10931)

Browse Source
This commit is contained in:
Shahed Nasser
2025-01-13 13:35:04 +02:00
committed by GitHub
parent 1ba2fadf22
commit 2a9ca1d1e1
9 changed files with 75 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts
View File

@@ -9,6 +9,7 @@ const EXCLUDED_TAGS = [
"@typeParamDefinition",
"@version",
"@tags",
"@summary",
]
export default function () {

15
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-examples.ts
View File

@@ -1,9 +1,7 @@
import Handlebars from "handlebars"
import { DeclarationReflection, SignatureReflection } from "typedoc"
import { getReflectionTypeFakeValueStr, getStepInputType } from "utils"
import pkg from "js-beautify"
const { js_beautify } = pkg
import beautifyCode from "../../utils/beautify-code.js"
export default function () {
Handlebars.registerHelper(
@@ -39,8 +37,7 @@ function generateStepExample(stepReflection: DeclarationReflection): string {
// generate example
return `
\`\`\`ts title="src/workflows/my-workflow.ts"
${js_beautify(
`import { createWorkflow } from "@medusajs/framework/workflows-sdk"
${beautifyCode(`import { createWorkflow } from "@medusajs/framework/workflows-sdk"
import { ${stepReflection.name} } from "@medusajs/medusa/core-flows"
const myWorkflow = createWorkflow(
@@ -48,13 +45,7 @@ const myWorkflow = createWorkflow(
() => {
const data = ${stepReflection.name}(${inputStr})
}
)`,
{
indent_size: 2,
brace_style: "preserve-inline",
wrap_line_length: 80,
}
)}
)`)}
\`\`\`
`
}

40
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-examples.ts
View File

@@ -1,9 +1,7 @@
import Handlebars from "handlebars"
import pkg from "js-beautify"
import { DeclarationReflection, SignatureReflection } from "typedoc"
import { getReflectionTypeFakeValueStr, getWorkflowInputType } from "utils"
const { js_beautify } = pkg
import beautifyCode from "../../utils/beautify-code.js"
export default function () {
Handlebars.registerHelper(
@@ -54,18 +52,12 @@ function getExecutionCodeTabs({
workflowName: string
}): string {
exampleCode = exampleCode.replace("```ts\n", "").replace("\n```", "")
const beautifyOptions: pkg.JSBeautifyOptions = {
indent_size: 2,
brace_style: "preserve-inline",
wrap_line_length: 80,
}
return `<CodeTabs group="workflow-exection">
<CodeTab label="Another Workflow" value="another-workflow">
\`\`\`ts title="src/workflows/my-workflow.ts"
${js_beautify(
`import { createWorkflow } from "@medusajs/framework/workflows-sdk"
${beautifyCode(`import { createWorkflow } from "@medusajs/framework/workflows-sdk"
import { ${workflowName} } from "@medusajs/medusa/core-flows"
const myWorkflow = createWorkflow(
@@ -74,19 +66,17 @@ const myWorkflow = createWorkflow(
${exampleCode
.replace(`{ result }`, "result")
.replace(`await `, "")
.replace(`(container)\n\t.run(`, ".runAsStep(")}
.replace(`(container)`, "")
.replace(".run(", ".runAsStep(")}
}
)`,
beautifyOptions
)}
)`)}
\`\`\`
</CodeTab>
<CodeTab label="API Route" value="api-route">
\`\`\`ts title="src/api/workflow/route.ts"
${js_beautify(
`import type {
${beautifyCode(`import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/framework/http"
@@ -100,17 +90,14 @@ export async function POST(
res.send(result)
}
`,
beautifyOptions
)}
`)}
\`\`\`
</CodeTab>
<CodeTab label="Subscriber" value="subscriber">
\`\`\`ts title="src/subscribers/order-placed.ts"
${js_beautify(
`import {
${beautifyCode(`import {
type SubscriberConfig,
type SubscriberArgs,
} from "@medusajs/framework"
@@ -127,17 +114,14 @@ export default async function handleOrderPlaced({
export const config: SubscriberConfig = {
event: "order.placed",
}`,
beautifyOptions
)}
}`)}
\`\`\`
</CodeTab>
<CodeTab label="Scheduled Job" value="scheduled-job">
\`\`\`ts title="src/jobs/message-daily.ts"
${js_beautify(
`import { MedusaContainer } from "@medusajs/framework/types"
${beautifyCode(`import { MedusaContainer } from "@medusajs/framework/types"
import { ${workflowName} } from "@medusajs/medusa/core-flows"
export default async function myCustomJob(
@@ -151,9 +135,7 @@ export default async function myCustomJob(
export const config = {
name: "run-once-a-day",
schedule: "0 0 * * *",
}`,
beautifyOptions
)}
}`)}
\`\`\`
</CodeTab>

13
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-hooks.ts
View File

@@ -2,6 +2,7 @@ import { MarkdownTheme } from "../../theme.js"
import Handlebars from "handlebars"
import { SignatureReflection } from "typedoc"
import { cleanUpHookInput, getProjectChild } from "utils"
import beautifyCode from "../../utils/beautify-code.js"
export default function (theme: MarkdownTheme) {
Handlebars.registerHelper(
@@ -19,7 +20,7 @@ export default function (theme: MarkdownTheme) {
return ""
}
let str = `${Handlebars.helpers.titleLevel()} Hooks`
let str = `${Handlebars.helpers.titleLevel()} Hooks\n\nHooks allow you to inject custom functionalities into the workflow. You'll receive data from the workflow, as well as additional data sent through an HTTP request.\n\nLearn more about [Hooks](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks) and [Additional Data](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data).\n\n`
Handlebars.helpers.incrementCurrentTitleLevel()
@@ -39,14 +40,20 @@ export default function (theme: MarkdownTheme) {
str += `\n\n${hooksTitleLevel} ${hook.name}\n\n`
if (hookReflection.comment?.summary) {
str += `${Handlebars.helpers.comment(
hookReflection.comment.summary
)}\n\n`
}
const hookExample = hookReflection.comment?.getTag(`@example`)
if (hookExample) {
Handlebars.helpers.incrementCurrentTitleLevel()
const innerTitleLevel = Handlebars.helpers.titleLevel()
str += `${innerTitleLevel} Example\n\n\`\`\`ts\n${Handlebars.helpers.comment(
hookExample.content
str += `${innerTitleLevel} Example\n\n\`\`\`ts\n${beautifyCode(
Handlebars.helpers.comment(hookExample.content)
)}\n\`\`\`\n\n${innerTitleLevel} Input\n\n`
Handlebars.helpers.decrementCurrentTitleLevel()

1
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-input.ts
View File

@@ -25,6 +25,7 @@ export default function (theme: MarkdownTheme) {
project: this.project || options.data.theme.project,
maxLevel,
wrapObject: true,
isReturn: false,
})
if (!input.length) {

1
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-output.ts
View File

@@ -25,6 +25,7 @@ export default function (theme: MarkdownTheme) {
project: this.project || options.data.theme.project,
maxLevel,
wrapObject: true,
isReturn: false,
})
if (!output.length) {

13
www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/beautify-code.ts Normal file
View File

@@ -0,0 +1,13 @@
import pkg from "js-beautify"
const { js_beautify } = pkg
export default function beautifyCode(code: string): string {
const beautifyOptions: pkg.JSBeautifyOptions = {
indent_size: 2,
brace_style: "preserve-inline",
wrap_line_length: 80,
}
return js_beautify(code, beautifyOptions)
}

13
www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts
View File

@@ -19,6 +19,7 @@ import {
} from "utils"
import { MarkdownTheme } from "../theme.js"
import { getDmlProperties, isDmlEntity } from "utils"
import { loadComment } from "./reflection-type-parameters.js"
const ALLOWED_KINDS: ReflectionKind[] = [
ReflectionKind.EnumMember,
@@ -338,6 +339,18 @@ export function getComments(
return parameter.type?.declaration?.signatures[0]?.comment
}
}
if (!parameter.comment && parameter.type?.type === "reference") {
// try to load comment
const commentContent = loadComment(parameter.type.name, parameter.project)
if (commentContent) {
return new Comment([
{
kind: "text",
text: commentContent,
},
])
}
}
return parameter.comment
}

23
www/utils/packages/typedoc-plugin-workflows/src/plugin.ts
View File

@@ -207,6 +207,7 @@ class WorkflowsPlugin {
workflow,
workflowVarName: parentReflection.name,
workflowReflection,
workflowComments: parentReflection.comment?.blockTags,
})
if (!steps.length) {
@@ -246,12 +247,14 @@ class WorkflowsPlugin {
workflow,
workflowVarName,
workflowReflection,
workflowComments = [],
}: {
initializer: ts.CallExpression
context: Context
workflow?: WorkflowDefinition
workflowVarName: string
workflowReflection: SignatureReflection
workflowComments?: CommentTag[]
}): ParsedStep[] {
const steps: ParsedStep[] = []
const initializerName = this.helper.normalizeName(
@@ -292,6 +295,7 @@ class WorkflowsPlugin {
context,
inputSymbol: initializer.arguments[1].symbol as ts.Symbol,
workflowName: workflowVarName,
workflowComments,
})
} else {
const initializerReflection = findReflectionInNamespaces(
@@ -478,11 +482,13 @@ class WorkflowsPlugin {
context,
inputSymbol,
workflowName,
workflowComments,
}: {
stepId: string
context: Context
inputSymbol: ts.Symbol
workflowName: string
workflowComments?: CommentTag[]
}): DeclarationReflection {
const declarationReflection = context.createDeclarationReflection(
ReflectionKind.Function,
@@ -492,7 +498,12 @@ class WorkflowsPlugin {
)
declarationReflection.comment = new Comment()
declarationReflection.comment.summary = [
const hookComment = workflowComments?.find(
(tag) => tag.tag === `@property` && tag.name === `hooks.${stepId}`
)
declarationReflection.comment.summary = hookComment?.content || [
{
kind: "text",
text: "This step is a hook that you can inject custom functionality into.",
@@ -515,6 +526,16 @@ class WorkflowsPlugin {
if (parameter.type.name === "__object") {
parameter.type.name = "object"
parameter.type.qualifiedName = "object"
if (!parameter.comment?.summary) {
parameter.comment = new Comment()
parameter.comment.summary = [
{
kind: "text",
text: "The input data for the hook.",
},
]
}
}
signatureReflection.parameters = []