From 5fb73e6698e1b044bae50424e31e4b1ad135dc68 Mon Sep 17 00:00:00 2001
From: Shahed Nasser <shahednasser@gmail.com>
Date: Tue, 19 Nov 2024 18:31:33 +0200
Subject: [PATCH] chore(core-flows,types): add TSDocs for useQueryGraphStep
 (#10042)

---
 .../src/common/steps/use-query-graph.ts       | 85 +++++++++++++++++++
 .../src/common/steps/use-remote-query.ts      |  8 +-
 .../remote-query-object-from-string.ts        | 24 ++++++
 3 files changed, 116 insertions(+), 1 deletion(-)

diff --git a/packages/core/core-flows/src/common/steps/use-query-graph.ts b/packages/core/core-flows/src/common/steps/use-query-graph.ts
index 0789f1fdb0..d3297f82ce 100644
--- a/packages/core/core-flows/src/common/steps/use-query-graph.ts
+++ b/packages/core/core-flows/src/common/steps/use-query-graph.ts
@@ -26,6 +26,91 @@ const step = createStep(
   }
 )
 
+/**
+ * This step fetches data across modules using the Query.
+ *
+ * Learn more in the [Query documentation](https://docs.medusajs.com/learn/advanced-development/module-links/query).
+ * 
+ * @example
+ * To retrieve a list of records of a data model:
+ *
+ * ```ts
+ * import {
+ *   createWorkflow
+ * } from "@medusajs/framework/workflows-sdk"
+ * import {
+ *   useQueryGraphStep
+ * } from "@medusajs/medusa/core-flows"
+ *
+ * const helloWorldWorkflow = createWorkflow(
+ *   "hello-world",
+ *   () => {
+ *     const { data: products } = useQueryGraphStep({
+ *       entity: "product",
+ *       fields: [
+ *         "*",
+ *         "variants.*"
+ *       ]
+ *     })
+ *   }
+ * )
+ * ```
+ *
+ * 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"
+ *     }
+ *   }
+ * })
+ * ```
+ */
 export const useQueryGraphStep = <const TEntry extends string>(
   input: UseQueryGraphStepInput<TEntry>
 ): ReturnType<StepFunction<UseQueryGraphStepInput<TEntry>, GraphResultSet<TEntry>>> =>
diff --git a/packages/core/core-flows/src/common/steps/use-remote-query.ts b/packages/core/core-flows/src/common/steps/use-remote-query.ts
index b4c194a70a..377e8ab9d2 100644
--- a/packages/core/core-flows/src/common/steps/use-remote-query.ts
+++ b/packages/core/core-flows/src/common/steps/use-remote-query.ts
@@ -50,7 +50,13 @@ export const useRemoteQueryStepId = "use-remote-query"
 /**
  * This step fetches data across modules using the remote query.
  *
- * Learn more in the [Remote Query documentation](https://docs.medusajs.com/advanced-development/modules/remote-query).
+ * Learn more in the [Remote Query documentation](https://docs.medusajs.com/learn/advanced-development/module-links/query).
+ * 
+ * :::note
+ * 
+ * This step is deprecated. Use {@link useQueryGraphStep} instead.
+ * 
+ * :::
  *
  * @example
  *
diff --git a/packages/core/types/src/modules-sdk/remote-query-object-from-string.ts b/packages/core/types/src/modules-sdk/remote-query-object-from-string.ts
index ad69df760a..405f142ff3 100644
--- a/packages/core/types/src/modules-sdk/remote-query-object-from-string.ts
+++ b/packages/core/types/src/modules-sdk/remote-query-object-from-string.ts
@@ -25,7 +25,13 @@ export type RemoteQueryObjectFromStringResult<
 
 export type RemoteQueryInput<TEntry extends string> = {
   // service: string This property is still supported under the hood but part of the type due to types missmatch towards fields
+  /**
+   * The name of the entity to retrieve. For example, `product`.
+   */
   entity: TEntry | keyof RemoteQueryEntryPoints
+  /**
+   * The fields and relations to retrieve in the entity.
+   */
   fields: ObjectToRemoteQueryFields<
     RemoteQueryEntryPoints[TEntry & keyof RemoteQueryEntryPoints]
   > extends never
@@ -33,12 +39,30 @@ export type RemoteQueryInput<TEntry extends string> = {
     : ObjectToRemoteQueryFields<
         RemoteQueryEntryPoints[TEntry & keyof RemoteQueryEntryPoints]
       >[]
+  /**
+   * Pagination configurations for the returned list of items.
+   */
   pagination?: {
+    /**
+     * The number of items to skip before retrieving the returned items.
+     */
     skip: number
+    /**
+     * The maximum number of items to return.
+     */
     take?: number
+    /**
+     * Sort by field names in ascending or descending order.
+     */
     order?: IndexOrderBy<TEntry>
   }
+  /**
+   * Filters to apply on the retrieved items.
+   */
   filters?: RemoteQueryFilters<TEntry>
+  /**
+   * Apply a query context on the retrieved data. For example, to retrieve product prices for a certain context.
+   */
   context?: any
 }