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

docs-util: add events to workflows reference (#12376)

Browse Source
This commit is contained in:
Shahed Nasser
2025-05-06 16:04:12 +03:00
committed by GitHub
parent aba4cba373
commit ecf3556589
10 changed files with 276 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/utils/packages/typedoc-config/tsdoc.json
+4
View File
@@ -69,6 +69,10 @@
{
"tagName": "@eventPayload",
"syntaxKind": "block"
},
{
"tagName": "@workflowEvent",
"syntaxKind": "block"
}
]
}
www/utils/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts
+2
View File
@@ -82,6 +82,7 @@ import workflowExamplesHelper from "./resources/helpers/workflow-examples.js"
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 { MarkdownTheme } from "./theme.js"
import { getDirname } from "utils"
@@ -195,4 +196,5 @@ export function registerHelpers(theme: MarkdownTheme) {
stepExamplesHelper()
ifEventsReferenceHelper(theme)
eventsListingHelper()
workflowEventsHelper()
}
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts
+1
View File
@@ -10,6 +10,7 @@ const EXCLUDED_TAGS = [
"@version",
"@tags",
"@summary",
"@workflowEvent",
]
export default function () {
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/events-listing.ts
+71 -23
View File
@@ -1,6 +1,6 @@
import Handlebars from "handlebars"
import pkg from "slugify"
import { DeclarationReflection } from "typedoc"
import { DeclarationReflection, ReflectionKind } from "typedoc"
import { pascalToWords } from "utils"
const slugify = pkg.default
@@ -14,19 +14,34 @@ export default function () {
const subtitleLevel = (this.children?.length ?? 0) > 1 ? 3 : 2
const showHeader = (this.children?.length ?? 0) > 1
this.children?.forEach((child, index) => {
content.push(
formatEventsType(child as DeclarationReflection, {
subtitleLevel,
showHeader,
})
)
if (index < this.children!.length - 1) {
content.push("")
content.push("---")
content.push("")
}
})
function parseChildren(children: DeclarationReflection[]) {
children?.forEach((child, index) => {
content.push(
formatEventsType(child as DeclarationReflection, {
subtitleLevel,
showHeader,
})
)
if (index < children!.length - 1) {
content.push("")
content.push("---")
content.push("")
}
})
}
if (this.kind === ReflectionKind.Module) {
this.children?.forEach((child, index) => {
parseChildren(child.children || [])
if (index < this.children!.length - 1) {
content.push("")
content.push("---")
content.push("")
}
})
} else {
parseChildren(this.children || [])
}
return content.join("\n")
}
@@ -73,24 +88,38 @@ function formatEventsType(
// table body start
content.push(` <Table.Body>`)
eventProperties.forEach((event) => {
const eventName =
let eventName =
event.comment?.blockTags
.find((tag) => tag.tag === "@eventName")
?.content.map((content) => content.text)
.join("") || ""
eventName = `[${eventName}](#${slugify(eventName.replace(".", ""), {
lower: true,
})})`
const eventDescription = event.comment?.summary
.map((content) => content.text)
.join("")
const deprecationTag = event.comment?.blockTags.find(
(tag) => tag.tag === "@deprecated"
)
if (deprecationTag) {
eventName += `\n`
const deprecationText = deprecationTag.content
.map((content) => content.text)
.join("")
.trim()
if (deprecationText.length) {
eventName += `<Tooltip text="${deprecationText}">`
}
eventName += `<Badge variant="orange">Deprecated</Badge>`
if (deprecationText.length) {
eventName += `</Tooltip>`
}
}
content.push(` <Table.Row>`)
content.push(
` <Table.Cell>\n[${eventName}](#${slugify(
eventName.replace(".", ""),
{
lower: true,
}
)})\n</Table.Cell>`
)
content.push(` <Table.Cell>\n${eventName}\n</Table.Cell>`)
content.push(` <Table.Cell>\n${eventDescription}\n</Table.Cell>`)
content.push(` </Table.Row>`)
})
@@ -117,9 +146,28 @@ function formatEventsType(
?.content.map((content) => content.text)
.join("")
.split(", ")
const deprecatedTag = event.comment?.blockTags.find(
(tag) => tag.tag === "@deprecated"
)
content.push(`${subHeaderPrefix} \`${eventName}\``)
content.push("")
if (deprecatedTag) {
const deprecationText = deprecatedTag.content
.map((content) => content.text)
.join("")
.trim()
if (deprecationText.length) {
content.push(`<Tooltip text="${deprecationText}">`)
}
content.push(`<Badge variant="orange">Deprecated</Badge>`)
if (deprecationText.length) {
content.push(`</Tooltip>`)
}
content.push("")
}
content.push(eventDescription || "")
content.push("")
content.push(`${subHeaderPrefix}# Payload`)
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-events.ts
+67
View File
@@ -0,0 +1,67 @@
import Handlebars from "handlebars"
import { SignatureReflection } from "typedoc"
export default function () {
Handlebars.registerHelper(
"workflowEvents",
function (this: SignatureReflection): string {
if (!this.parent) {
return ""
}
const workflowEventComments = this.parent.comment?.blockTags.filter(
(tag) => tag.tag === "@workflowEvent"
)
if (!workflowEventComments?.length) {
return ""
}
let str = `${Handlebars.helpers.titleLevel()} Emitted Events\n\nThis section lists the events that are either triggered by the \`emitEventStep\` in the workflow, or by another workflow executed within this workflow.\n\nYou can listen to these events in a subscriber, as explained in the [Subscribers](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers) documentation.\n\n`
str += `<Table>\n`
str += ` <Table.Header>\n`
str += ` <Table.Row>\n`
str += ` <Table.HeaderCell>\nEvent\n</Table.HeaderCell>\n`
str += ` <Table.HeaderCell>\nDescription\n</Table.HeaderCell>\n`
str += ` <Table.HeaderCell>\nPayload\n</Table.HeaderCell>\n`
str += ` </Table.Row>\n`
str += ` </Table.Header>\n`
str += ` <Table.Body>\n`
workflowEventComments.forEach((comment) => {
const commentContent = comment.content
.map((c) => c.text)
.join(" ")
.split("--")
let eventName = `\`${commentContent[0].trim()}\``
const eventDescription = commentContent[1]?.trim() || ""
const eventPayload = (commentContent[2]?.trim() || "")
.replace("```ts\n", "")
.replace("\n```", "")
const isDeprecated = commentContent.length >= 4
if (isDeprecated) {
const deprecatedText = commentContent[4]?.trim()
eventName += `\n`
if (deprecatedText) {
eventName += `<Tooltip text="${deprecatedText}">`
}
eventName += `<Badge variant="orange">Deprecated</Badge>`
if (deprecatedText) {
eventName += `</Tooltip>`
}
}
str += ` <Table.Row>\n`
str += ` <Table.Cell>\n${eventName}\n</Table.Cell>\n`
str += ` <Table.Cell>\n${eventDescription}\n</Table.Cell>\n`
str += ` <Table.Cell>\n\`\`\`ts blockStyle="inline"\n${eventPayload}\n\`\`\`\n</Table.Cell>\n`
str += ` </Table.Row>\n`
})
str += ` </Table.Body>\n`
str += `</Table>\n\n`
return str
}
)
}
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.workflow.hbs
+3 -1
View File
@@ -22,4 +22,6 @@
{{{workflowOutput sectionTitle=name}}}
{{{workflowHooks}}}
{{{workflowHooks}}}
{{{workflowEvents}}}
www/utils/packages/typedoc-plugin-workflows/src/plugin.ts
+61
View File
@@ -25,6 +25,9 @@ import {
} from "utils"
import { StepType } from "./types.js"
import Examples from "./utils/examples.js"
import { MedusaEvent } from "types"
import path from "path"
import { readFileSync } from "fs"
type ParsedStep = {
stepReflection: DeclarationReflection
@@ -47,6 +50,7 @@ class WorkflowsPlugin {
workflowIds: string[]
}
}
protected events: MedusaEvent[] = []
constructor(app: Application) {
this.app = app
@@ -92,6 +96,7 @@ class WorkflowsPlugin {
if (!isEnabled) {
return
}
this.readEventsJson()
for (const reflection of context.project.getReflectionsByKind(
ReflectionKind.All
)) {
@@ -235,6 +240,7 @@ class WorkflowsPlugin {
])
this.updateWorkflowsTagsMap(workflowId, uniqueResources)
this.attachEvents(parentReflection)
}
/**
@@ -855,6 +861,61 @@ class WorkflowsPlugin {
argument.getText()
)
}
readEventsJson() {
if (this.events.length) {
return
}
const eventsPath = path.resolve(
"..",
"..",
"generated",
"events-output.json"
)
this.events = JSON.parse(readFileSync(eventsPath, "utf-8"))
}
attachEvents(workflowReflection: DeclarationReflection) {
if (!workflowReflection.comment) {
workflowReflection.comment = new Comment()
}
const eventsTag = workflowReflection.comment.blockTags.find(
(tag) => tag.tag === "@workflowEvent"
)
if (eventsTag) {
return
}
const workflowEvents = this.events.filter((event) =>
event.workflows.includes(workflowReflection.name)
)
if (!workflowEvents) {
return
}
workflowReflection.comment.blockTags.push(
...workflowEvents.map((event) => {
let commentText = `${event.name} -- ${event.description} -- ${event.payload}`
if (event.deprecated) {
commentText += " -- deprecated"
if (event.deprecated_message) {
commentText += ` -- ${event.deprecated_message}`
}
}
return new CommentTag(`@workflowEvent`, [
{
kind: "text",
text: commentText,
},
])
})
)
}
}
export default WorkflowsPlugin
www/utils/packages/typedoc-plugin-workflows/src/utils/helper.ts
+3 -4
View File
@@ -33,10 +33,9 @@ export default class Helper {
? dotPos
: Math.min(dotPos, parenPos)
return nameWithoutQuotes.substring(
0,
endIndex === -1 ? nameWithoutQuotes.length : endIndex
)
return nameWithoutQuotes
.substring(0, endIndex === -1 ? nameWithoutQuotes.length : endIndex)
.trim()
}
/**