docs: fix step detection of useQueryGraphStep (#12842)

www/apps/resources/references/core_flows/Common/Steps_Common/functions/core_flows.Common.Steps_Common.useQueryGraphStep/page.mdx

@@ -12,14 +12,83 @@ import { TypeList, WorkflowDiagram } from "docs-ui"
 
 This documentation provides a reference to the `useQueryGraphStep`. It belongs to the `@medusajs/medusa/core-flows` package.
 
-## Type Parameters
+This step fetches data across modules using the Query.
 
-<TypeList types={[{"name":"TEntry","type":"`string`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="useQueryGraphStep"/>
+Learn more in the [Query documentation](https://docs.medusajs.com/learn/fundamentals/module-links/query).
 
-## Parameters
+## Example
 
-<TypeList types={[{"name":"input","type":"[UseQueryGraphStepInput](../../../../types/core_flows.UseQueryGraphStepInput/page.mdx)&#60;TEntry&#62;","description":"","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"options","type":"[RemoteJoinerOptions](../../../../../types/interfaces/types.RemoteJoinerOptions/page.mdx)","description":"","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"throwIfKeyNotFound","type":"`boolean`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"throwIfRelationNotFound","type":"`boolean` \\| `string`[]","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"initialData","type":"`object` \\| `object`[]","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"initialDataOnly","type":"`boolean`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="useQueryGraphStep"/>
+To retrieve a list of records of a data model:
 
-## Returns
+```ts
+const { data: products } = useQueryGraphStep({
+  entity: "product",
+  fields: [
+    "*",
+    "variants.*"
+  ]
+})
+```
 
-<TypeList types={[{"name":"ReturnType","type":"ReturnType&#60;[StepFunction](../../../../../workflows/types/workflows.StepFunction/page.mdx)&#60;[UseQueryGraphStepInput](../../../../types/core_flows.UseQueryGraphStepInput/page.mdx)&#60;TEntry&#62;, [GraphResultSet](../../../../../types/ModulesSdkTypes/types/types.ModulesSdkTypes.GraphResultSet/page.mdx)&#60;TEntry&#62;&#62;&#62;","optional":false,"defaultValue":"","description":"","expandable":false,"children":[{"name":"UseQueryGraphStepInput","type":"[UseQueryGraphStepInput](../../../../types/core_flows.UseQueryGraphStepInput/page.mdx)&#60;TEntry&#62;","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]},{"name":"GraphResultSet","type":"[GraphResultSet](../../../../../types/ModulesSdkTypes/types/types.ModulesSdkTypes.GraphResultSet/page.mdx)&#60;TEntry&#62;","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="useQueryGraphStep"/>
+To retrieve a single item instead of a an array:
+
+```ts
+const { data: products } = useQueryGraphStep({
+  entity: "product",
+  fields: [
+    "*",
+    "variants.*"
+  ],
+  filters: {
+    id: "123"
+  }
+})
+```
+
+To throw an error if a record isn't found matching the specified ID:
+
+```ts
+const { data: products } = useQueryGraphStep({
+  entity: "product",
+  fields: [
+    "*",
+    "variants.*"
+  ],
+  filters: {
+    id: "123"
+  },
+  options: {
+    throwIfKeyNotFound: true
+  }
+})
+```
+
+To set pagination configurations:
+
+```ts
+const { data: products } = useQueryGraphStep({
+  entity: "product",
+  fields: [
+    "*",
+    "variants.*"
+  ],
+  filters: {
+    id: "123"
+  },
+  pagination: {
+    take: 10,
+    skip: 10,
+    order: {
+      created_at: "DESC"
+    }
+  }
+})
+```
+
+## Input
+
+<TypeList types={[{"name":"UseQueryGraphStepInput","type":"[UseQueryGraphStepInput](../../../../types/core_flows.UseQueryGraphStepInput/page.mdx)&#60;TEntry&#62;","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" openedLevel={1} sectionTitle="useQueryGraphStep"/>
+
+## Output
+
+<TypeList types={[{"name":"GraphResultSet","type":"[GraphResultSet](../../../../../types/ModulesSdkTypes/types/types.ModulesSdkTypes.GraphResultSet/page.mdx)&#60;TEntry&#62;","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" openedLevel={1} sectionTitle="useQueryGraphStep"/>

www/apps/resources/references/helper_steps/functions/helper_steps.useQueryGraphStep/page.mdx

@@ -9,14 +9,83 @@ import { TypeList } from "docs-ui"
 
 This documentation provides a reference to the `useQueryGraphStep` step. It belongs to the `@medusajs/medusa/core-flows` package.
 
-## Type Parameters
+This step fetches data across modules using the Query.
 
-<TypeList types={[{"name":"TEntry","type":"`string`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="useQueryGraphStep"/>
+Learn more in the [Query documentation](https://docs.medusajs.com/learn/fundamentals/module-links/query).
 
-## Parameters
+## Example
 
-<TypeList types={[{"name":"input","type":"[UseQueryGraphStepInput](../../types/helper_steps.UseQueryGraphStepInput/page.mdx)&#60;TEntry&#62;","description":"","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"options","type":"[RemoteJoinerOptions](../../../types/interfaces/types.RemoteJoinerOptions/page.mdx)","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="useQueryGraphStep"/>
+To retrieve a list of records of a data model:
 
-## Returns
+```ts
+const { data: products } = useQueryGraphStep({
+  entity: "product",
+  fields: [
+    "*",
+    "variants.*"
+  ]
+})
+```
 
-<TypeList types={[{"name":"ReturnType","type":"ReturnType&#60;[StepFunction](../../../workflows/types/workflows.StepFunction/page.mdx)&#60;[UseQueryGraphStepInput](../../types/helper_steps.UseQueryGraphStepInput/page.mdx)&#60;TEntry&#62;, [GraphResultSet](../../../types/ModulesSdkTypes/types/types.ModulesSdkTypes.GraphResultSet/page.mdx)&#60;TEntry&#62;&#62;&#62;","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="useQueryGraphStep"/>
+To retrieve a single item instead of a an array:
+
+```ts
+const { data: products } = useQueryGraphStep({
+  entity: "product",
+  fields: [
+    "*",
+    "variants.*"
+  ],
+  filters: {
+    id: "123"
+  }
+})
+```
+
+To throw an error if a record isn't found matching the specified ID:
+
+```ts
+const { data: products } = useQueryGraphStep({
+  entity: "product",
+  fields: [
+    "*",
+    "variants.*"
+  ],
+  filters: {
+    id: "123"
+  },
+  options: {
+    throwIfKeyNotFound: true
+  }
+})
+```
+
+To set pagination configurations:
+
+```ts
+const { data: products } = useQueryGraphStep({
+  entity: "product",
+  fields: [
+    "*",
+    "variants.*"
+  ],
+  filters: {
+    id: "123"
+  },
+  pagination: {
+    take: 10,
+    skip: 10,
+    order: {
+      created_at: "DESC"
+    }
+  }
+})
+```
+
+## Input
+
+<TypeList types={[{"name":"UseQueryGraphStepInput","type":"[UseQueryGraphStepInput](../../types/helper_steps.UseQueryGraphStepInput/page.mdx)&#60;TEntry&#62;","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" openedLevel={1} sectionTitle="useQueryGraphStep"/>
+
+## Output
+
+<TypeList types={[{"name":"GraphResultSet","type":"[GraphResultSet](../../../types/ModulesSdkTypes/types/types.ModulesSdkTypes.GraphResultSet/page.mdx)&#60;TEntry&#62;","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" openedLevel={1} sectionTitle="useQueryGraphStep"/>

www/utils/packages/utils/src/step-utils.ts

@@ -1,4 +1,10 @@
-import { ArrayType, SignatureReflection, SomeType, UnionType } from "typedoc"
+import {
+  ArrayType,
+  ReferenceType,
+  SignatureReflection,
+  SomeType,
+  UnionType,
+} from "typedoc"
 
 const disallowedIntrinsicTypeNames = ["unknown", "void", "any", "never"]
 
@@ -6,6 +12,12 @@ export function isWorkflowStep(reflection: SignatureReflection): boolean {
   if (reflection.parent?.children?.some((child) => child.name === "__step__")) {
     return true
   }
+  if (
+    reflection.type?.type === "reference" &&
+    reflection.type.name === "ReturnType"
+  ) {
+    return getStepFunctionTypeArg(reflection.type) !== undefined
+  }
   if (reflection.type?.type !== "intersection") {
     return false
   }
@@ -19,7 +31,21 @@ export function isWorkflowStep(reflection: SignatureReflection): boolean {
 export function getStepInputType(
   reflection: SignatureReflection
 ): SomeType | undefined {
-  if (!isWorkflowStep(reflection) || !reflection.parameters?.length) {
+  if (!isWorkflowStep(reflection)) {
+    return
+  }
+
+  if (reflection.type?.type === "reference") {
+    const stepFunctionType = getStepFunctionTypeArg(reflection.type)
+
+    if (stepFunctionType) {
+      return cleanUpType(stepFunctionType.typeArguments?.[0])
+    }
+
+    return
+  }
+
+  if (!reflection.parameters?.length) {
     return
   }
 
@@ -40,6 +66,16 @@ export function getStepOutputType(
     return
   }
 
+  if (reflection.type?.type === "reference") {
+    const stepFunctionType = getStepFunctionTypeArg(reflection.type)
+
+    if (stepFunctionType) {
+      return cleanUpType(stepFunctionType.typeArguments?.[1])
+    }
+
+    return
+  }
+
   if (reflection.type?.type !== "intersection") {
     return reflection.type
   }
@@ -95,3 +131,9 @@ function cleanUpArrayType(arrayType: ArrayType): SomeType {
 
   return new ArrayType(cleanedUpType)
 }
+
+function getStepFunctionTypeArg(referenceType: ReferenceType) {
+  return referenceType.typeArguments?.find(
+    (typeArg) => typeArg.type === "reference" && typeArg.name === "StepFunction"
+  ) as ReferenceType | undefined
+}