docs: use tooling convention across docs (#10512)

2024-12-09 19:15:29 +02:00
1 parent 7c76ee24cb
commit 3409953c4f
@@ -26,7 +26,7 @@ Modules are created in a sub-directory of `src/modules`. So, start by creating t

 ## 2. Create Data Model

-A data model represents a table in the database. You create data models using Medusa's data modeling utility, which is built to improve readability and provide an intuitive developer experience.
+A data model represents a table in the database. You create data models using Medusa's Data Model Language (DML). It simplifies defining a table's columns, relations, and indexes with straightforward methods and configurations.

 <Note>

@@ -49,7 +49,7 @@ export const Brand = model.define("brand", {

 You create a `Brand` data model which has an `id` primary key property, and a `name` text property.

-You define the data model using the `define` method of the `model` utility imported from `@medusajs/framework/utils`. It accepts two parameters:
+You define the data model using the `define` method of the DML. It accepts two parameters:

 1. The first one is the name of the data model's table in the database. Use snake-case names.
 2. The second is an object, which is the data model's schema.
@@ -95,7 +95,7 @@ class BrandModuleService extends MedusaService({
 export default BrandModuleService
 ```

-The `BrandModuleService` extends a class returned by the `MedusaService` function imported from `@medusajs/framework/utils`. This function generates a class with data-management methods for your module's data models.
+The `BrandModuleService` extends a class returned by `MedusaService` from the Modules SDK. This function generates a class with data-management methods for your module's data models.

 The `MedusaService` function receives an object of the module's data models as a parameter, and generates methods to manage those data models. So, the `BrandModuleService` now has methods like `createBrands` and `retrieveBrand` to manage the `Brand` data model.

@@ -128,7 +128,7 @@ export default Module(BRAND_MODULE, {
 })
 ```

-You use the `Module` function imported from `@medusajs/framework/utils` to create the module's definition. It accepts two parameters:
+You use `Module` from the Modules SDK to create the module's definition. It accepts two parameters:

 1. The module's name (`brand`). You'll use this name when you use this module in other customizations.
 2. An object with a required property `service` indicating the module's main service.
@@ -31,7 +31,7 @@ Learn more about workflows in [this chapter](../../../fundamentals/workflows/pag

 ## 1. Create createBrandStep

-A workflow consists of a series of steps, each step created in a TypeScript or JavaScript file under the `src/workflows` directory. A step is defined using the `createStep` utility function imported from `@medusajs/framework/workflows-sdk`.
+A workflow consists of a series of steps, each step created in a TypeScript or JavaScript file under the `src/workflows` directory. A step is defined using `createStep` from the Workflows SDK

 The workflow you're creating in this guide has one step to create the brand. So, create the file `src/workflows/create-brand.ts` with the following content:

@@ -120,7 +120,7 @@ So, if an error occurs during the workflow's execution, the brand that was creat

 ## 2. Create createBrandWorkflow

-You can now create the workflow that runs the `createBrandStep`. A workflow is created in a TypeScript or JavaScript file under the `src/workflows` directory. In the file, you use the `createWorkflow` function imported from `@medusajs/framework/workflows-sdk` to create the workflow.
+You can now create the workflow that runs the `createBrandStep`. A workflow is created in a TypeScript or JavaScript file under the `src/workflows` directory. In the file, you use `createWorkflow` from the Workflows SDK to create the workflow.

 Add the following content in the same `src/workflows/create-brand.ts` file:

@@ -125,7 +125,7 @@ export default defineMiddlewares({

 You apply the `validateAndTransformQuery` middleware on the `GET /admin/brands` API route. The middleware accepts two parameters:

- A [Zod](https://zod.dev/) schema that a request's query parameters must satisfy. Medusa provides a `createFindParams` utility that generates a Zod schema with the following properties:
+- A [Zod](https://zod.dev/) schema that a request's query parameters must satisfy. Medusa provides `createFindParams` that generates a Zod schema with the following properties:
    - `fields`: A comma-separated string indicating the fields to retrieve.
    - `limit`: The maximum number of items to retrieve.
    - `offset`: The number of items to skip before retrieving the returned items.
@@ -75,7 +75,7 @@ In the `instrumentation.ts` file, you export a `register` function that uses Med

 You also initialize an instance of the exporter, such as Zipkin, and pass it to the `registerOtel` function.

-The `registerOtel` utility function accepts an object having the following properties:
+`registerOtel` accepts an object having the following properties:

 <TypeList
  types={[
@@ -6,7 +6,7 @@ export const metadata = {

 # {metadata.title}

-In this chapter, you'll learn how to write integration tests for API routes using the [medusaIntegrationTestRunner utility function](../page.mdx).
+In this chapter, you'll learn how to write integration tests for API routes using [medusaIntegrationTestRunner](../page.mdx) from Medusa's Testing Framework.

 <Prerequisites
  items={[
@@ -6,7 +6,7 @@ export const metadata = {

 # {metadata.title}

-In this chapter, you'll learn about the `medusaIntegrationTestRunner` utility function used to write integration tests.
+In this chapter, you'll learn about `medusaIntegrationTestRunner` from Medusa's Testing Framework and how to use it to write integration tests.

 <Prerequisites
  items={[
@@ -19,7 +19,7 @@ In this chapter, you'll learn about the `medusaIntegrationTestRunner` utility fu

 ## medusaIntegrationTestRunner Utility

-The `medusaIntegrationTestRunner` utility function is provided by the `@medusajs/test-utils` package to create integration tests in your Medusa project. It runs a full Medusa application, allowing you test API routes, workflows, or other customizations.
+The `medusaIntegrationTestRunner` is from Medusa's Testing Framework and it's used to create integration tests in your Medusa project. It runs a full Medusa application, allowing you test API routes, workflows, or other customizations.

 For example:

@@ -6,7 +6,7 @@ export const metadata = {

 # {metadata.title}

-In this chapter, you'll learn how to write integration tests for workflows using the [medusaIntegrationTestRunner utility function](../page.mdx).
+In this chapter, you'll learn how to write integration tests for workflows using [medusaIntegrationTestRunner](../page.mdx) from Medusa's Testing Framwork.

 <Prerequisites
  items={[
@@ -6,7 +6,7 @@ export const metadata = {

 # {metadata.title}

-In this chapter, find an example of writing an integration test for a module using the [moduleIntegrationTestRunner utility function](../page.mdx).
+In this chapter, find an example of writing an integration test for a module using [moduleIntegrationTestRunner](../page.mdx) from Medusa's Testing Framework.

 <Prerequisites
  items={[
@@ -6,7 +6,7 @@ export const metadata = {

 # {metadata.title}

-In this chapter, you'll learn about the `moduleIntegrationTestRunner` utility function and how to use it to write integration tests for a module's main service.
+In this chapter, you'll learn about `moduleIntegrationTestRunner` from Medusa's Testing Framework and how to use it to write integration tests for a module's main service.

 <Prerequisites
  items={[
@@ -19,7 +19,7 @@ In this chapter, you'll learn about the `moduleIntegrationTestRunner` utility fu

 ## moduleIntegrationTestRunner Utility

-The `moduleIntegrationTestRunner` utility function is provided by the `@medusajs/test-utils` package to create integration tests for a module. The integration tests run on a test Medusa application with only the specified module enabled.
+`moduleIntegrationTestRunner` creates integration tests for a module. The integration tests run on a test Medusa application with only the specified module enabled.

 For example, assuming you have a `hello` module, create a test file at `src/modules/hello/__tests__/service.spec.ts`:

@@ -8,11 +8,9 @@ In this chapter, you'll learn about Medusa's testing tools and how to install an

 ## @medusajs/test-utils Package

-Medusa provides a `@medusajs/test-utils` package with utility tools to create integration tests for your custom API routes, modules, or other Medusa customizations.
+Medusa provides a Testing Framework to create integration tests for your custom API routes, modules, or other Medusa customizations.

-### Install @medusajs/test-utils
-
-To use the `@medusajs/test-utils` package, install it as a `devDependency`:
+To use the Testing Framework, install `@medusajs/test-utils` as a `devDependency`:

 ```bash npm2yarn
 npm install --save-dev @medusajs/test-utils@latest
@@ -92,7 +90,7 @@ You now have two commands:

 <Note>

-Medusa provides utility tools for integration tests only. You can write unit tests using Jest.
+Medusa's Testing Framework works for integration tests only. You can write unit tests using Jest.

 </Note>

@@ -101,7 +101,7 @@ export const config = defineRouteConfig({
 export default CustomPage
 ```

-The configuration object is created using the `defineRouteConfig` function imported from `@medusajs/admin-sdk`. It accepts the following properties:
+The configuration object is created using `defineRouteConfig` from the Medusa Framework. It accepts the following properties:

 - `label`: the sidebar item’s label.
 - `icon`: an optional React component used as an icon in the sidebar.
@@ -61,7 +61,7 @@ export default ProductWidget

 You export the `ProductWidget` component, which shows the heading `Product Widget`. In the widget, you use [Medusa UI](!ui!), a package that Medusa maintains to allow you to customize the dashboard with the same components used to build it.

-To export the widget's configurations, you use the `defineWidgetConfig` function imported from `@medusajs/admin-sdk`. It accepts as a parameter an object with the `zone` property, whose value is a string or an array of strings, each being the name of the zone to inject the widget into.
+To export the widget's configurations, you use `defineWidgetConfig` from the Admin Extension SDK. It accepts as a parameter an object with the `zone` property, whose value is a string or an array of strings, each being the name of the zone to inject the widget into.

 In the example above, the widget is injected at the top of a product’s details.

@@ -10,7 +10,7 @@ In this guide, you'll learn how to throw errors in your Medusa application, how

 ## Throw MedusaError

-When throwing an error in your API routes, middlewares, workflows, or any customization, throw a `MedusaError`, which is imported from `@medusajs/framework/utils`.
+When throwing an error in your API routes, middlewares, workflows, or any customization, throw a `MedusaError` from the Medusa Framework.

 The Medusa application's API route error handler then wraps your thrown error in a uniform object and returns it in the response.

@@ -28,7 +28,7 @@ Refer to the API Reference for [Admin](!api!/admin#authentication) and [Store](!

 ## Protect Custom API Routes

-To protect custom API Routes to only allow authenticated customer or admin users, use the `authenticate` middleware imported from `@medusajs/medusa`.
+To protect custom API Routes to only allow authenticated customer or admin users, use the `authenticate` middleware from the Medusa Framework.

 For example:

@@ -187,7 +187,7 @@ You use Query to retrieve the stock location, to use the first location in the a

 Then, you generate inventory levels for each inventory item, associating it with the first stock location.

-Finally, you use the `createInventoryLevelsWorkflow` imported from `@medusajs/medusa/core-flows` to create the inventory levels.
+Finally, you use the `createInventoryLevelsWorkflow` from Medusa's core workflows to create the inventory levels.

 ### Test Script

@@ -10,7 +10,7 @@ In this chapter, you'll learn how to infer the type of a data model.

 Consider you have a `MyCustom` data model. You can't reference this data model in a type, such as a workflow input or service method output types, since it's a variable.

-Instead, Medusa provides an `InferTypeOf` utility imported from `@medusajs/framework/types` that transforms your data model to a type.
+Instead, Medusa provides `InferTypeOf` that transforms your data model to a type.

 For example:

@@ -21,7 +21,7 @@ import { MyCustom } from "../models/my-custom" // relative path to the model
 export type MyCustom = InferTypeOf<typeof MyCustom>
 ```

-The `InferTypeOf` utility accepts as a type argument the type of the data model.
+`InferTypeOf` accepts as a type argument the type of the data model.

 Since the `MyCustom` data model is a variable, use the `typeof` operator to pass the data model as a type argument to `InferTypeOf`.

@@ -6,8 +6,6 @@ export const metadata = {

 In this chapter, you’ll learn about the types of properties in a data model’s schema.

-These types are available as methods on the `model` utility imported from `@medusajs/framework/utils`.
-
 ## id

 The `id` method defines an automatically generated string ID property. The generated ID is a unique string that has a mix of letters and numbers.
@@ -8,7 +8,7 @@ In this chapter, you’ll learn how to define relationships between data models

 ## What is a Relationship Property?

-A relationship property defines an association in the database between two models. It's created using methods on the `models` utility, such as `hasOne` or `belongsTo`.
+A relationship property defines an association in the database between two models. It's created using the Data Model Language (DML) methods, such as `hasOne` or `belongsTo`.

 When you generate a migration for these data models, the migrations include foreign key columns or pivot tables, based on the relationship's type.

@@ -18,7 +18,7 @@ Instead, you use a module link. A module link forms an association between two d

 ### 1. Create Link File

-Links are defined in a TypeScript or JavaScript file under the `src/links` directory. The file defines the link using the `defineLink` function imported from `@medusajs/framework/utils` and exports it.
+Links are defined in a TypeScript or JavaScript file under the `src/links` directory. The file defines the link using `defineLink` from the Modules SDK and exports it.

 For example:

@@ -6,7 +6,7 @@ export const metadata = {

 # {metadata.title}

-In this chapter, you’ll learn about the Query utility and how to use it to fetch data from modules.
+In this chapter, you’ll learn about Query and how to use it to fetch data from modules.

 ## What is Query?

@@ -18,12 +18,12 @@ This chapter is intended for more advanced database use-cases where you need mor

 [MikroORM's entity manager](https://mikro-orm.io/docs/entity-manager) is a class that has methods to run queries on the database and perform operations.

-Medusa provides an `InjectManager` decorator imported from `@medusajs/utils` that injects a service's method with a [forked entity manager](https://mikro-orm.io/docs/identity-map#forking-entity-manager).
+Medusa provides an `InjectManager` decorator from the Modules SDK that injects a service's method with a [forked entity manager](https://mikro-orm.io/docs/identity-map#forking-entity-manager).

 So, to run database queries in a service:

 1. Add the `InjectManager` decorator to the method.
-2. Add as a last parameter an optional `sharedContext` parameter that has the `MedusaContext` decorator imported from `@medusajs/utils`. This context holds database-related context, including the manager injected by `InjectManager`
+2. Add as a last parameter an optional `sharedContext` parameter that has the `MedusaContext` decorator from the Modules SDK. This context holds database-related context, including the manager injected by `InjectManager`

 For example, in your service, add the following methods:

@@ -81,10 +81,10 @@ Refer to [MikroORM's reference](https://mikro-orm.io/api/5.9/knex/class/EntityMa

 To wrap database operations in a transaction, you create two methods:

-1. A private or protected method that's wrapped in a transaction. To wrap it in a transaction, you use the `InjectTransactionManager` decorator imported from `@medusajs/utils`.
+1. A private or protected method that's wrapped in a transaction. To wrap it in a transaction, you use the `InjectTransactionManager` decorator from the Modules SDK.
 2. A public method that calls the transactional method. You use on it the `InjectManager` decorator as explained in the previous section.

-Both methods must accept as a last parameter an optional `sharedContext` parameter that has the `MedusaContext` decorator imported from `@medusajs/utils`. It holds database-related contexts passed through the Medusa application.
+Both methods must accept as a last parameter an optional `sharedContext` parameter that has the `MedusaContext` decorator from the Modules SDK. It holds database-related contexts passed through the Medusa application.

 For example:

@@ -28,7 +28,7 @@ Modules are created in a sub-directory of `src/modules`. So, start by creating t

 ### 1. Create Data Model

-A data model represents a table in the database. You create data models using Medusa's data modeling utility. It simplifies defining a table's columns, relations, and indexes with straightforward methods and configurations.
+A data model represents a table in the database. You create data models using Medusa's data modeling language (DML). It simplifies defining a table's columns, relations, and indexes with straightforward methods and configurations.

 You create a data model in a TypeScript or JavaScript file under the `models` directory of a module. So, to create a `Post` data model in the Blog Module, create the file `src/modules/blog/models/post.ts` with the following content:

@@ -45,7 +45,7 @@ const Post = model.define("post", {
 export default Post
 ```

-You define the data model using the `define` method of the `model` utility imported from `@medusajs/framework/utils`. It accepts two parameters:
+You define the data model using the `define` method of the DML. It accepts two parameters:

 1. The first one is the name of the data model's table in the database. Use snake-case names.
 2. The second is an object, which is the data model's schema. The schema's properties are defined using the `model`'s methods, such as `text` and `id`.
@@ -84,7 +84,7 @@ class BlogModuleService extends MedusaService({
 export default BlogModuleService
 ```

-Your module's service extends a class generated by the `MedusaService` utility function. This class comes with generated methods for data-management Create, Read, Update, and Delete (CRUD) operations on each of your modules, saving your time that can be spent on building custom business logic.
+Your module's service extends a class generated by `MedusaService` from the Modules SDK. This class comes with generated methods for data-management Create, Read, Update, and Delete (CRUD) operations on each of your modules, saving your time that can be spent on building custom business logic.

 The `MedusaService` function accepts an object of data models to generate methods for. You can pass all data models in your module in this object.

@@ -123,7 +123,7 @@ export default Module(BLOG_MODULE, {
 })
 ```

-You use the `Module` function imported from `@medusajs/framework/utils` to create the module's definition. It accepts two parameters:
+You use `Module` from the Modules SDK to create the module's definition. It accepts two parameters:

 1. The name that the module's main service is registered under (`blog`).
 2. An object with a required property `service` indicating the module's main service.
@@ -24,7 +24,7 @@ Your workflow isn't reusable by other applications. Use a step that performs wha

 ## How to Expose a Hook in a Workflow?

-To expose a hook in your workflow, use the `createHook` function imported from `@medusajs/framework/workflows-sdk`.
+To expose a hook in your workflow, use `createHook` from the Workflows SDK.

 For example:

@@ -4,7 +4,7 @@ export const metadata = {

 # {metadata.title}

-In this chapter, you'll learn how to execute an action based on a condition in a workflow using the when-then utility.
+In this chapter, you'll learn how to execute an action based on a condition in a workflow using when-then from the Workflows SDK.

 ## Why If-Conditions Aren't Allowed in Workflows?

@@ -14,15 +14,13 @@ At that point, variables in the workflow don't have any values. They only do whe

 So, you can't use an if-condition that checks a variable's value, as the condition will be evaluated when Medusa creates the internal representation of the workflow, rather than during execution.

-Instead, use the when-then utility.
+Instead, use when-then from the Workflows SDK.

 ---

 ## What is the When-Then Utility?

-The when-then utility functions execute an action if a condition is satisfied.
-
-The `when` function accepts as a parameter a function that returns a boolean value, and the `then` function is chained to `when`. `then` accepts as a parameter a function that's executed if `when`'s parameter function returns a `true` value.
+when-then from the Workflows SDK executes an action if a condition is satisfied. The `when` function accepts as a parameter a function that returns a boolean value, and the `then` function is chained to `when`. `then` accepts as a parameter a function that's executed if `when`'s parameter function returns a `true` value.

 For example:

@@ -70,7 +68,7 @@ In this code snippet, you execute the `isActiveStep` only if the `input.is_activ

 ### When Parameters

-`when` utility is a function imported from `@medusajs/framework/workflows-sdk`. It accepts the following parameters:
+`when` accepts the following parameters:

 1. The first parameter is either an object or the workflow's input. This data is passed as a parameter to the function in `when`'s second parameter.
 2. The second parameter is a function that returns a boolean indicating whether to execute the action in `then`.
@@ -38,7 +38,7 @@ Learn more about why you can't manipulate variables [in this chapter](../variabl

 </Note>

-Instead, use the `transform` utility function imported from `@medusajs/framework/workflows-sdk`:
+Instead, use `transform` from the Workflows SDK:

 export const highlights = [
  ["9", "", "Don't manipulate variables directly."],
@@ -132,7 +132,7 @@ Learn more about why you can't use if-conditions [in this chapter](../conditions

 </Note>

-Instead, use the when-then utility function imported from `@medusajs/framework/workflows-sdk`:
+Instead, use when-then from the Workflows SDK:

 ```ts
 // Don't
@@ -49,11 +49,11 @@ The object has an `input` property to pass input to the workflow.

 ## Preparing Input Data

-If you need to perform some data manipulation to prepare the other workflow's input data, use the `transform` utility function imported from `@medusajs/framework/workflows-sdk`.
+If you need to perform some data manipulation to prepare the other workflow's input data, use `transform` from the Workflows SDK.

 <Note>

-Learn about the transform utility in [this chapter](../variable-manipulation/page.mdx).
+Learn about transform in [this chapter](../variable-manipulation/page.mdx).

 </Note>

@@ -105,11 +105,11 @@ In this example, you use the `transform` function to prepend `Hello` to the titl

 ## Run Workflow Conditionally

-To run a workflow in another based on a condition, use the when-then utility functions imported from `@medusajs/framework/workflows-sdk`.
+To run a workflow in another based on a condition, use when-then from the Workflows SDK.

 <Note>

-Learn about the when-then utility in [this chapter](../conditions/page.mdx).
+Learn about when-then in [this chapter](../conditions/page.mdx).

 </Note>

@@ -152,4 +152,4 @@ const workflow = createWorkflow(
 )
 ```

-In this example, you use the `when` utility to run the `createProductsWorkflow` only if `should_create` (passed in the `input`) is enabled.
+In this example, you use when-then to run the `createProductsWorkflow` only if `should_create` (passed in the `input`) is enabled.
@@ -30,7 +30,7 @@ You implement all custom flows within workflows, then execute them from [API rou

 ### 1. Create the Steps

-A workflow is made of a series of steps. A step is created using the `createStep` utility function imported from `@medusajs/framework/workflows-sdk`.
+A workflow is made of a series of steps. A step is created using `createStep` from the Workflows SDK.

 Create the file `src/workflows/hello-world.ts` with the following content:

@@ -245,7 +245,7 @@ export const highlights = [
  [
    "11",
    `"product"`,
-    "The resource registration name imported from `@medusajs/framework/utils`.",
+    "The resource registration name.",
  ],
 ]

@@ -8,7 +8,7 @@ In this chapter, you’ll learn how to run workflow steps in parallel.

 ## parallelize Utility Function

-If your workflow has steps that don’t rely on one another’s results, run them in parallel using the `parallelize` utility function imported from the `@medusajs/framework/workflows-sdk`.
+If your workflow has steps that don’t rely on one another’s results, run them in parallel using `parallelize` from the Workflows SDK.

 The workflow waits until all steps passed to the `parallelize` function finish executing before continuing to the next step.

@@ -4,7 +4,7 @@ export const metadata = {

 # {metadata.title}

-In this chapter, you'll learn how to use the `transform` utility to manipulate variables in a workflow.
+In this chapter, you'll learn how to use `transform` from the Workflows SDK to manipulate variables in a workflow.

 ## Why Variable Manipulation isn't Allowed in Workflows

@@ -14,13 +14,13 @@ At that point, variables in the workflow don't have any values. They only do whe

 So, you can only pass variables as parameters to steps. But, in a workflow, you can't change a variable's value or, if the variable is an array, loop over its items.

-Instead, use the transform utility.
+Instead, use `transform` from the Workflows SDK.

 ---

 ## What is the transform Utility?

-The `transform` utility function creates a new variable as the result of manipulating other variables.
+`transform` creates a new variable as the result of manipulating other variables.

 For example, consider you have two strings as the output of two steps:

@@ -62,7 +62,7 @@ const myWorkflow = createWorkflow(
 )
 ```

-The `transform` utility function is imported from `@medusajs/framework/workflows-sdk`. It accepts two parameters:
+`transform` accepts two parameters:

 1. The first parameter is an object of variables to manipulate. The object is passed as a parameter to `transform`'s second parameter function.
 2. The second parameter is the function performing the variable manipulation.
@@ -111,7 +111,7 @@ const myWorkflow = createWorkflow(

 This workflow receives an `items` array in its input.

-You use the `transform` utility to create an `ids` variable, which is an array of strings holding the `id` of each item in the `items` array.
+You use `transform` to create an `ids` variable, which is an array of strings holding the `id` of each item in the `items` array.

 You then pass the `ids` variable as a parameter to the `doSomethingStep`.

@@ -144,7 +144,7 @@ In this workflow, `today` is only evaluated when the workflow is executed.

 ### Transform Evaluation

-The transform utility's value is only evaluated if you pass its output to a step or in the workflow response.
+`transform`'s value is only evaluated if you pass its output to a step or in the workflow response.

 For example, if you have the following workflow:

@@ -166,9 +166,9 @@ Since `str`'s value isn't used as a step's input or passed to `WorkflowResponse`

 ### Data Validation

-The `transform` utility should only be used to perform variable or data manipulation.
+`transform` should only be used to perform variable or data manipulation.

-If you want to perform some validation on the data, use a step or the [when-then utility](../conditions/page.mdx) instead.
+If you want to perform some validation on the data, use a step or [when-then](../conditions/page.mdx) instead.

 For example: