docs: documet withDeleted (medusajs#12841)

* docs: documet withDeleted

* fixes

* small fix

Author: shahednasser

www/apps/book/app/learn/fundamentals/module-links/query/page.mdx

@@ -71,6 +71,35 @@ The method returns an object that has a `data` property, which holds an array of
 }
 ```
 
+### Query Usage in Workflows
+
+To retrieve data with Query in a [workflow](../../workflows/page.mdx), use the [useQueryGraphStep](!resources!/references/helper-steps/useQueryGraphStep).
+
+For example:
+
+```ts title="src/workflows/query.ts"
+import { createWorkflow, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+const myWorkflow = createWorkflow(
+  "my-workflow",
+  () => {
+    const { data: posts } = useQueryGraphStep({
+      entity: "post",
+      fields: ["id", "title"],
+    })
+
+    return new WorkflowResponse({
+      posts,
+    })
+  }
+)
+```
+
+You can learn more about this step in the [useQueryGraphStep](!resources!/references/helper-steps/useQueryGraphStep) reference.
+
+The rest of this chapter uses the `graph` method to explain the different usages of Query, but the same principles apply to `useQueryGraphStep`.
+
 ---
 
 ## Querying the Graph
@@ -98,7 +127,7 @@ const { data: posts } = await query.graph({
 })
 ```
 
-`.*` means that all of data model's properties should be retrieved. You can also retrieve specific properties by replacing the `*` with the property name, for each property.
+`.*` means that all of the data model's properties should be retrieved. You can also retrieve specific properties by replacing the `*` with the property name for each property.
 
 For example:
 
@@ -137,7 +166,7 @@ In the example above, you retrieve all products linked to a post.
 
 ### Apply Filters and Pagination on Linked Records
 
-Consider you want to apply filters or pagination configurations on the product(s) linked to `post`. To do that, you must query the module link's table instead.
+Consider that you want to apply filters or pagination configurations on the product(s) linked to a `post`. To do that, you must query the module link's table instead.
 
 As mentioned in the [Module Link](../page.mdx) documentation, Medusa creates a table for your module link. So, not only can you retrieve linked records, but you can also retrieve the records in a module link's table.
 
@@ -170,7 +199,7 @@ const { data: productCustoms } = await query.graph({
 In the object passed to the `graph` method:
 
 - You pass the `entryPoint` property of the link definition as the value for `entity`. So, Query will retrieve records from the module link's table.
-- You pass three items to the `field` property:
+- You pass three items to the `fields` property:
     - `*` to retrieve the link table's fields. This is useful if the link table has [custom columns](../custom-columns/page.mdx).
     - `product.*` to retrieve the fields of a product record linked to a `Post` record.
     - `post.*` to retrieve the fields of a `Post` record linked to a product record.
@@ -243,7 +272,7 @@ Under the hood, Query uses one of the following methods from the data model's mo
 - `listX` if you don't pass [pagination parameters](#apply-pagination). For example, `listPosts`.
 - `listAndCountX` if you pass pagination parameters. For example, `listAndCountPosts`.
 
-Both methods accepts a filter object that can be used to filter records.
+Both methods accept a filter object that can be used to filter records.
 
 Those filters don't just allow you to filter by exact values. You can also filter by properties that don't match a value, match multiple values, and other filter types.
 
@@ -418,9 +447,57 @@ The `order` property is an object whose keys are property names, and values are
 
 ---
 
+## Retrieve Deleted Records
+
+By default, Query doesn't retrieve deleted records. To retrieve all records including deleted records, you can pass the `withDeleted` property to the `query.graph` method.
+
+<Note>
+
+The `withDeleted` property is available from [Medusa v2.8.5](https://github.com/medusajs/medusa/releases/tag/v2.8.5).
+
+</Note>
+
+For example:
+
+```ts highlights={[["4", "withDeleted", "Include deleted posts in the results."]]}
+const { data: posts } = await query.graph({
+  entity: "post",
+  fields: ["id", "title"],
+  withDeleted: true,
+})
+```
+
+In the example above, you retrieve all posts, including deleted ones.
+
+### Retrieve Only Deleted Records
+
+To retrieve only deleted records, you can add a `deleted_at` filter and set its value to not `null`. For example:
+
+export const withDeletedHighlights = [
+  ["5", "deleted_at", "Filter to retrieve posts whose `deleted_at` property is not `null`."],
+  ["9", "withDeleted", "Include deleted posts in the results."],
+]
+
+```ts highlights={withDeletedHighlights}
+const { data: posts } = await query.graph({
+  entity: "post",
+  fields: ["id", "title"],
+  filters: {
+    deleted_at: {
+      $ne: null,
+    },
+  },
+  withDeleted: true,
+})
+```
+
+In the example above, you retrieve only deleted posts by enabling the `withDeleted` property and adding a filter to only retrieve records where the `deleted_at` property is not `null`.
+
+---
+
 ## Configure Query to Throw Errors
 
-By default, if Query doesn't find records matching your query, it returns an empty array. You can add option to configure Query to throw an error when no records are found.
+By default, if Query doesn't find records matching your query, it returns an empty array. You can add an option to configure Query to throw an error when no records are found.
 
 The `query.graph` method accepts as a second parameter an object that can have a `throwIfKeyNotFound` property. Its value is a boolean indicating whether to throw an error if no record is found when filtering by IDs. By default, it's `false`.
 
@@ -459,7 +536,7 @@ const { data: posts } = await query.graph({
 })
 ```
 
-In the example above, Query throws an error either if no post is found with the ID `post_123` or if its found but its author ID isn't `author_123`.
+In the example above, Query throws an error either if no post is found with the ID `post_123` or if it's found but its author ID isn't `author_123`.
 
 In the above example, it's assumed that a post belongs to an author, so it has an `author_id` property. However, this also works in the opposite case, where an author has many posts.
 
@@ -538,7 +615,7 @@ The `validateAndTransformQuery` accepts two parameters:
     4. `order`: The fields to order the returned items by in ascending or descending order.
 2. A Query configuration object. It accepts the following properties:
     1. `defaults`: An array of default fields and relations to retrieve in each resource.
-    2. `isList`: A boolean indicating whether a list of items are returned in the response.
+    2. `isList`: A boolean indicating whether a list of items is returned in the response.
     3. `allowed`: An array of fields and relations allowed to be passed in the `fields` query parameter.
     4. `defaultLimit`: A number indicating the default limit to use if no limit is provided. By default, it's `50`.
 
@@ -554,7 +631,7 @@ As of [Medusa v2.2.0](https://github.com/medusajs/medusa/releases/tag/v2.2.0), `
 
 </Note>
 
-For example, Create the file `src/api/customs/route.ts` with the following content:
+For example, create the file `src/api/customs/route.ts` with the following content:
 
 export const queryConfigHighlights = [
   ["17", "req.queryConfig", "Pass the parsed request Query configurations to the Query graph execution."]
@@ -590,7 +667,7 @@ In the API route, you pass `req.queryConfig` to `query.graph`. `queryConfig` has
 
 ### Test it Out
 
-To test it out, start your Medusa application and send a `GET` request to the `/customs` API route. A list of records are retrieved with the specified fields in the middleware.
+To test it out, start your Medusa application and send a `GET` request to the `/customs` API route. A list of records is retrieved with the specified fields in the middleware.
 
 ```json title="Returned Data"
 {
@@ -607,6 +684,6 @@ Try passing one of the Query configuration parameters, like `fields` or `limit`,
 
 <Note>
 
-Learn more about [specifing fields and relations](!api!/store#select-fields-and-relations) and [pagination](!api!/store#pagination) in the API reference.
+Learn more about [specifying fields and relations](!api!/store#select-fields-and-relations) and [pagination](!api!/store#pagination) in the API reference.
 
 </Note>

www/apps/book/generated/edit-dates.mjs

@@ -66,7 +66,7 @@ export const generatedEditDates = {
   "app/learn/fundamentals/module-links/custom-columns/page.mdx": "2025-03-11T13:29:54.752Z",
   "app/learn/fundamentals/module-links/directions/page.mdx": "2025-03-17T12:52:06.161Z",
   "app/learn/fundamentals/module-links/page.mdx": "2025-04-17T08:50:17.036Z",
-  "app/learn/fundamentals/module-links/query/page.mdx": "2025-04-18T11:13:02.240Z",
+  "app/learn/fundamentals/module-links/query/page.mdx": "2025-06-26T16:01:59.548Z",
   "app/learn/fundamentals/modules/db-operations/page.mdx": "2025-04-25T14:26:25.000Z",
   "app/learn/fundamentals/modules/multiple-services/page.mdx": "2025-03-18T15:11:44.632Z",
   "app/learn/fundamentals/modules/page.mdx": "2025-03-18T07:51:09.049Z",