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

docs: added a service factory reference (#8292)

Browse Source 
Added a service factory reference of the generated methods and how to use them.

Since the types in the codebase are a bit complex, a generated reference won't provide a valuable result.

Instead, this reference is created manually and aims to cover common use cases, providing examples for them.

Closes DOCS-844
This commit is contained in:
Shahed Nasser
2024-07-26 17:40:56 +03:00
committed by GitHub
parent 71411463b1
commit a4eab3f37a
14 changed files with 1131 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
www/apps/book/app/advanced-development/modules/service-factory/page.mdx
View File

@@ -60,6 +60,12 @@ The method's names are the operation's name, suffixed by the data model's key in
For example, the following methods are generated for the service above:
<Note>
Find a complete reference of each of the methods in [this documentation](!resources!/service-factory-reference)
</Note>
<Tabs defaultValue="listMyCustoms" layoutType="vertical" className="mt-2">
<TabsList>
<TabsTrigger value="listMyCustoms">listMyCustoms</TabsTrigger>

44
www/apps/resources/app/service-factory-reference/methods/create/page.mdx Normal file
View File

@@ -0,0 +1,44 @@
---
sidebar_label: "create"
---
export const metadata = {
title: `create Method - Service Factory Reference`,
}
# {metadata.title}
This method creates one or more records of the data model.
## Create One Record
```ts
const post = await postModuleService.createPosts({
name: "My Post",
published_at: new Date(),
metadata: {
external_id: "1234"
}
})
```
If an object is passed of the method, an object of the created record is also returned.
---
## Create Multiple Records
```ts
const posts = await postModuleService.createPosts([
{
name: "My Post",
published_at: new Date()
},
{
name: "My Other Post",
published_at: new Date()
}
])
```
If an array is passed of the method, an array of the created records is also returned.

50
www/apps/resources/app/service-factory-reference/methods/delete/page.mdx Normal file
View File

@@ -0,0 +1,50 @@
---
sidebar_label: "delete"
---
export const metadata = {
title: `delete Method - Service Factory Reference`,
}
# {metadata.title}
This method deletes one or more records.
## Delete One Record
```ts
await postModuleService.deletePosts("123")
```
To delete one record, pass its ID as a parameter of the method.
---
## Delete Multiple Records
```ts
await postModuleService.deletePosts([
"123",
"321"
])
```
To delete multiple records, pass an array of IDs as a parameter of the method.
---
## Delete Records Matching Filters
```ts
await postModuleService.deletePosts({
name: "My Post"
})
```
To delete records matching a set of filters, pass an object of filters as a parameter.
<Note>
Learn more about accepted filters in [this documentation](../../tips/filtering/page.mdx).
</Note>

132
www/apps/resources/app/service-factory-reference/methods/list/page.mdx Normal file
View File

@@ -0,0 +1,132 @@
---
sidebar_label: "list"
---
export const metadata = {
title: `list Method - Service Factory Reference`,
}
# {metadata.title}
This method retrieves a list of records.
## Retrieve List of Records
```ts
const posts = await postModuleService.listPosts()
```
If no parameters are passed, the method returns an array of the first `15` records.
---
## Filter Records
```ts
const posts = await postModuleService.listPosts({
id: ["123", "321"]
})
```
### Parameters
To retrieve records matching a set of filters, pass an object of the filters as a first parameter.
<Note>
Learn more about accepted filters in [this documentation](../../tips/filtering/page.mdx).
</Note>
### Returns
The method returns an array of the first `15` records matching the filters.
---
## Retrieve Relations
<Note>
This applies to relations between data models of the same module. To retrieve linked records of different modules, use [remote query](!docs!/advanced-development/modules/remote-query).
</Note>
```ts
const posts = await postModuleService.listPosts({}, {
relations: ["author"]
})
```
### Parameters
To retrieve records with their relations, pass as a second parameter an object having a `relations` property. `relations`'s value is an array of relation names.
### Returns
The method returns an array of the first `15` records matching the filters.
---
## Select Properties
```ts
const posts = await postModuleService.listPosts({}, {
select: ["id", "name"]
})
```
### Parameters
By default, retrieved records have all their properties. To select specific properties to retrieve, pass in the second object parameter a `select` property.
`select`'s value is an array of property names to retrieve.
### Returns
The method returns an array of the first `15` records matching the filters.
---
## Paginate Relations
```ts
const posts = await postModuleService.listPosts({}, {
take: 20,
skip: 10
})
```
### Parameters
To paginate the returned records, the second object parameter accepts the following properties:
- `take`: a number indicating how many records to retrieve. By default, it's `15`.
- `skip`: a number indicating how many records to skip before the retrieved records. By default, it's `0`.
### Returns
The method returns an array of records. The number of records is less than or equal to `take`'s value.
---
## Sort Records
```ts
const posts = await postModuleService.listPosts({}, {
order: {
name: "ASC"
}
})
```
### Parameters
To sort records by one or more properties, pass to the second object parameter the `order` property. Its value is an object whose keys are the property names, and values can either be:
- `ASC` to sort by this property in the ascending order.
- `DESC` to sort by this property in the descending order.
### Returns
The method returns an array of the first `15` records matching the filters.

150
www/apps/resources/app/service-factory-reference/methods/listAndCount/page.mdx Normal file
View File

@@ -0,0 +1,150 @@
---
sidebar_label: "listAndCount"
---
export const metadata = {
title: `listAndCount Method - Service Factory Reference`,
}
# {metadata.title}
This method retrieves a list of records with the total count.
## Retrieve List of Records
```ts
const [posts, count] = await postModuleService.listAndCountPosts()
```
If no parameters are passed, the method returns an array with two items:
1. The first is an array of the first `15` records retrieved.
2. The second is the total count of records.
---
## Filter Records
```ts
const [posts, count] = await postModuleService.listAndCountPosts({
id: ["123", "321"]
})
```
### Parameters
To retrieve records matching a set of filters, pass an object of the filters as a first parameter.
<Note>
Learn more about accepted filters in [this documentation](../../tips/filtering/page.mdx).
</Note>
### Returns
The method returns an array with two items:
1. The first is an array of the first `15` records retrieved matching the specified filters.
2. The second is the total count of records matching the specified filters.
---
## Retrieve Relations
<Note>
This applies to relations between data models of the same module. To retrieve linked records of different modules, use [remote query](!docs!/advanced-development/modules/remote-query).
</Note>
```ts
const [posts, count] = await postModuleService.listAndCountPosts({}, {
relations: ["author"]
})
```
### Parameters
To retrieve records with their relations, pass as a second parameter an object having a `relations` property. Its value is an array of relation names.
### Returns
The method returns an array with two items:
1. The first is an array of the first `15` records retrieved.
2. The second is the total count of records.
---
## Select Properties
```ts
const [posts, count] = await postModuleService.listAndCountPosts({}, {
select: ["id", "name"]
})
```
### Parameters
By default, retrieved records have all their properties. To select specific properties to retrieve, pass in the second object parameter a `select` property.
`select`'s value is an array of property names to retrieve.
### Returns
The method returns an array with two items:
1. The first is an array of the first `15` records retrieved.
2. The second is the total count of records.
---
## Paginate Relations
```ts
const [posts, count] = await postModuleService.listAndCountPosts({}, {
take: 20,
skip: 10
})
```
### Parameters
To paginate the returned records, the second object parameter accepts the following properties:
- `take`: a number indicating how many records to retrieve. By default, it's `15`.
- `skip`: a number indicating how many records to skip before the retrieved records. By default, it's `0`.
### Returns
The method returns an array with two items:
1. The first is an array of the records retrieved. The number of records is less than or equal to `take`'s value.
2. The second is the total count of records.
---
## Sort Records
```ts
const [posts, count] = await postModuleService.listAndCountPosts({}, {
order: {
name: "ASC"
}
})
```
### Parameters
To sort records by one or more properties, pass to the second object parameter the `order` property. Its value is an object whose keys are the property names, and values can either be:
- `ASC` to sort by this property in the ascending order.
- `DESC` to sort by this property in the descending order.
### Returns
The method returns an array with two items:
1. The first is an array of the first `15` records retrieved.
2. The second is the total count of records.

97
www/apps/resources/app/service-factory-reference/methods/restore/page.mdx Normal file
View File

@@ -0,0 +1,97 @@
---
sidebar_label: "restore"
---
export const metadata = {
title: `restore Method - Service Factory Reference`,
}
# {metadata.title}
This method restores one or more records of the data model that were [soft-deleted](../soft-delete/page.mdx).
## Restore One Record
```ts
const restoredPosts = await postModuleService.restorePosts("123")
```
### Parameters
To restore one record, pass its ID as a parameter of the method.
### Returns
The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of restored records' IDs.
For example, the returned object of the above example is:
```ts
restoredPosts = {
post_id: ["123"]
}
```
---
## Restore Multiple Records
```ts
const restoredPosts = await postModuleService.restorePosts([
"123",
"321"
])
```
### Parameters
To restore multiple records, pass an array of IDs as a parameter of the method.
### Returns
The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of restored records' IDs.
For example, the returned object of the above example is:
```ts
restoredPosts = {
post_id: [
"123",
"321"
]
}
```
---
## Restore Records Matching Filters
```ts
const restoredPosts = await postModuleService.restorePosts({
name: "My Post"
})
```
### Parameters
To restore records matching a set of filters, pass an object of fitlers as a parameter of the method.
<Note>
Learn more about accepted filters in [this documentation](../../tips/filtering/page.mdx).
</Note>
### Returns
The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of restored records' IDs.
For example, the returned object of the above example is:
```ts
restoredPosts = {
post_id: [
"123"
]
}
```

67
www/apps/resources/app/service-factory-reference/methods/retrieve/page.mdx Normal file
View File

@@ -0,0 +1,67 @@
---
sidebar_label: "retrieve"
---
export const metadata = {
title: `retrieve Method - Service Factory Reference`,
}
# {metadata.title}
This method retrieves one record of the data model by its ID.
## Retrieve a Record
```ts
const post = await postModuleService.retrievePost("123")
```
### Parameters
Pass the ID of the record to retrieve.
### Returns
The method returns the record as an object.
---
## Retrieve a Record's Relations
<Note>
This applies to relations between data models of the same module. To retrieve linked records of different modules, use [remote query](!docs!/advanced-development/modules/remote-query).
</Note>
```ts
const post = await postModuleService.retrievePost("123", {
relations: ["author"]
})
```
### Parameters
To retrieve the data model with relations, pass as a second parameter of the method an object with the property `relations`. `relations`'s value is an array of relation names.
### Returns
The method returns the record as an object.
---
## Select Properties to Retrieve
```ts
const post = await postModuleService.retrievePost("123", {
select: ["id", "name"]
})
```
### Parameters
By default, all of the record's properties are retrieved. To select specific ones, pass in the second object parameter a `select` property. Its value is an array of property names.
### Returns
The method returns the record as an object.

97
www/apps/resources/app/service-factory-reference/methods/soft-delete/page.mdx Normal file
View File

@@ -0,0 +1,97 @@
---
sidebar_label: "softDelete"
---
export const metadata = {
title: `softDelete Method - Service Factory Reference`,
}
# {metadata.title}
This method soft deletes one or more records of the data model.
## Soft Delete One Record
```ts
const deletedPosts = await postModuleService.softDeletePosts(
"123"
)
```
### Parameters
To soft delete a record, pass its ID as a parameter of the method.
### Returns
The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of soft-deleted records' IDs.
For example, the returned object of the above example is:
```ts
deletedPosts = {
post_id: ["123"]
}
```
---
## Soft Delete Multiple Records
```ts
const deletedPosts = await postModuleService.softDeletePosts([
"123",
"321"
])
```
### Parameters
To soft delete multiple records, pass an array of IDs as a parameter of the method.
### Returns
The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of soft-deleted records' IDs.
For example, the returned object of the above example is:
```ts
deletedPosts = {
post_id: [
"123",
"321"
]
}
```
---
## Soft Delete Records Matching Filters
```ts
const deletedPosts = await postModuleService.softDeletePosts({
name: "My Post"
})
```
### Parameters
To soft delete records matching a set of filters, pass an object of filters as a parameter.
<Note>
Learn more about accepted filters in [this documentation](../../tips/filtering/page.mdx).
</Note>
### Returns
The method returns an object, whose keys are of the format `{camel_case_data_model_name}_id`, and their values are arrays of soft-deleted records' IDs.
For example, the returned object of the above example is:
```ts
deletedPosts = {
post_id: ["123"]
}
```

137
www/apps/resources/app/service-factory-reference/methods/update/page.mdx Normal file
View File

@@ -0,0 +1,137 @@
---
sidebar_label: "update"
---
export const metadata = {
title: `update Method - Service Factory Reference`,
}
# {metadata.title}
This method updates one or more records of the data model.
## Update One Record
```ts
const post = await postModuleService.updatePosts({
id: "123",
name: "My Post"
})
```
### Parameters
To update one record, pass an object that at least has an `id` property, identifying the ID of the record to update.
You can pass in the same object any other properties to update.
### Returns
The method returns the updated record as an object.
---
## Update Multiple Records
```ts
const posts = await postModuleService.updatePosts([
{
id: "123",
name: "My Post"
},
{
id: "321",
published_at: new Date()
}
])
```
### Parameters
To update multiple records, pass an array of objects. Each object has at least an `id` property, identifying the ID of the record to update.
You can pass in each object any other properties to update.
### Returns
The method returns an array of objects of updated records.
---
## Update Records Matching a Filter
```ts
const posts = await postModuleService.updatePosts({
selector: {
name: "My Post"
},
data: {
published_at: new Date()
}
})
```
### Parameters
To update records that match specified filters, pass as a parameter an object having two properties:
- `selector`: An object of filters that a record must match to be updated.
- `data`: An object of the properties to update in every record that match the filters in `selector`.
In the example above, you update the `published_at` property of every post record whose name is `My Post`.
<Note>
Learn more about accepted filters in [this documentation](../../tips/filtering/page.mdx).
</Note>
### Returns
The method returns an array of objects of updated records.
---
## Multiple Record Updates with Filters
```ts
const posts = await postModuleService.updatePosts([
{
selector: {
name: "My Post"
},
data: {
published_at: new Date()
}
},
{
selector: {
name: "Another Post"
},
data: {
metadata: {
external_id: "123"
}
}
}
])
```
### Parameters
To update records matching different sets of filters, pass an array of objects, each having two properties:
- `selector`: An object of filters that a record must match to be updated.
- `data`: An object of the properties to update in every record that match the filters in `selector`.
In the example above, you update the `published_at` property of post records whose name is `My Post`, and update the `metadata` property of post records whose name is `Another Post`.
<Note>
Learn more about accepted filters in [this documentation](../../tips/filtering/page.mdx).
</Note>
### Returns
The method returns an array of objects of updated records.

41
www/apps/resources/app/service-factory-reference/page.mdx Normal file
View File

@@ -0,0 +1,41 @@
import { ChildDocs } from "docs-ui"
export const metadata = {
title: `Service Factory Reference`,
}
# {metadata.title}
This section of the documentation provides a reference of the methods generated for services extending the service factory (`MedusaService`), and how to use them.
<Note title="Tip">
Learn more about the service factory in [this documentation](!docs!/advanced-development/modules/service-factory).
</Note>
## Method Names
Generated method names are of the format `{operationName}_{dataModelName}`, where:
- `{operationName}` is the name of the operation. For example, `create`.
- `{dataModelName}` is the pascal-case version of the data model's key that's passed in the object parameter of `MedusaService`. The name is pluralized for all operations except for the `retrieve` operation.
Some examples of method names:
- `createPosts`
- `createMyPosts`
- `retrievePost`
- `listPosts`
---
## Methods Reference
<Note>
The reference uses only the operation name to refer to the method.
</Note>
<ChildDocs showItems={["Methods"]} hideTitle />

161
www/apps/resources/app/service-factory-reference/tips/filtering/page.mdx Normal file
View File

@@ -0,0 +1,161 @@
---
sidebar_label: "Filtering"
---
export const metadata = {
title: `Filter Records - Service Factory Reference`,
}
# {metadata.title}
Many of the service factory's generated methods allow passing filters to perform an operation, such as to update or delete records matching the filters.
This guide provides examples of using filters.
<Note>
The `list` method is used in the example snippets of this reference, but you can use the same filtering mechanism with any method that accepts filters.
</Note>
---
## Match Exact Value
```ts
const posts = await postModuleService.listPosts({
name: "My Post 2",
})
```
If you pass a property with its value, only records whose properties exactly match the value are selected.
In the example above, only posts having the name `My Post 2` are retrieved.
---
## Match Multiple Values
```ts
const posts = await postModuleService.listPosts({
views: [
50,
100
]
})
```
To find records with a property matching multiple values, pass an array of those values as the property's value in the filter.
In the example above, only posts having either `50` or `100` views are retrieved.
---
## Don't Match Values
```ts
const posts = await postModuleService.listPosts({
name: {
$nin: [
"My Post"
]
}
})
```
To find records with a property that doesn't match one or more values, pass an object with a `$nin` property. Its value is an array of multiple values that a record's property shouldn't match.
In the example above, only posts that don't have the name `My Post` are retrieved.
---
## Match Text Like Value
<Note>
This filter only applies to text-like properties, including `id` and `enum` properties.
</Note>
```ts
const posts = await postModuleService.listPosts({
name: {
$like: "My%"
}
})
```
To perform a `like` filter on a record's property, set the property's value to an object with a `$like` property. Its value is the string to use when applying the `like` filter.
The example above matches all posts whose name starts with `My`.
---
## Apply Range Filters
<Note>
This filter only applies to the `number` and `dateTime` properties.
</Note>
```ts
const posts = await postModuleService.listPosts({
published_at: {
$lt: new Date()
}
})
```
To filter a record's property to be within a range, set the property's value to an object with any of the following properties:
1. `$lt`: The property's value must be less than the supplied value.
2. `$lte`: The property's value must be less than or equal to the supplied value.
3. `$gt`: The property's value must be greater than the supplied value.
4. `$gte`: The property's value must be greater than or equal the supplied value.
In the example above, only posts whose `published_at` property is before the current date and time are retrieved.
### Example: Retrieve Posts Published Today
```ts
const startToday = new Date()
startToday.setHours(0, 0, 0, 0)
const endToday = new Date()
endToday.setHours(23, 59, 59, 59)
const posts = await postModuleService.listPosts({
published_at: {
$gte: startToday,
$lte: endToday
}
})
```
The `dateTime` property also stores the time. So, when matching for an exact day, you must set a range filter to be between the beginning and end of the day.
In this example, you retrieve the current date twice: once to set its time to `00:00:00`, and another to set its time `23:59:59`. Then, you retrieve posts whose `published_at` property is between `00:00:00` and `23:59:59` of today.
---
## Apply Or Condition
```ts
const posts = await postModuleService.listPosts({
$or: [
{
name: "My Post",
},
{
published_at: {
$lt: new Date()
}
}
]
})
```
To use an `or` condition, pass to the filter object the `$or` property, whose value is an array of filters.
In the example above, posts whose name is `My Post` or their `published_at` date is less than the current date and time are retrieved.

40
www/apps/resources/generated/files-map.mjs
View File

@@ -743,6 +743,46 @@ export const filesMap = [
"filePath": "/www/apps/resources/app/recipes/subscriptions/page.mdx",
"pathname": "/recipes/subscriptions"
},
{
"filePath": "/www/apps/resources/app/service-factory-reference/methods/create/page.mdx",
"pathname": "/service-factory-reference/methods/create"
},
{
"filePath": "/www/apps/resources/app/service-factory-reference/methods/delete/page.mdx",
"pathname": "/service-factory-reference/methods/delete"
},
{
"filePath": "/www/apps/resources/app/service-factory-reference/methods/list/page.mdx",
"pathname": "/service-factory-reference/methods/list"
},
{
"filePath": "/www/apps/resources/app/service-factory-reference/methods/listAndCount/page.mdx",
"pathname": "/service-factory-reference/methods/listAndCount"
},
{
"filePath": "/www/apps/resources/app/service-factory-reference/methods/restore/page.mdx",
"pathname": "/service-factory-reference/methods/restore"
},
{
"filePath": "/www/apps/resources/app/service-factory-reference/methods/retrieve/page.mdx",
"pathname": "/service-factory-reference/methods/retrieve"
},
{
"filePath": "/www/apps/resources/app/service-factory-reference/methods/soft-delete/page.mdx",
"pathname": "/service-factory-reference/methods/soft-delete"
},
{
"filePath": "/www/apps/resources/app/service-factory-reference/methods/update/page.mdx",
"pathname": "/service-factory-reference/methods/update"
},
{
"filePath": "/www/apps/resources/app/service-factory-reference/page.mdx",
"pathname": "/service-factory-reference"
},
{
"filePath": "/www/apps/resources/app/service-factory-reference/tips/filtering/page.mdx",
"pathname": "/service-factory-reference/tips/filtering"
},
{
"filePath": "/www/apps/resources/app/storefront-development/cart/context/page.mdx",
"pathname": "/storefront-development/cart/context"

92
www/apps/resources/generated/sidebar.mjs
View File

@@ -7152,7 +7152,7 @@ export const generatedSidebar = [
{
"loaded": true,
"isPathHref": true,
"title": "API References",
"title": "References",
"hasTitleStyling": true,
"children": [
{
@@ -7398,6 +7398,96 @@ export const generatedSidebar = [
]
}
]
},
{
"loaded": true,
"isPathHref": true,
"path": "/service-factory-reference",
"title": "Service Factory Reference",
"isChildSidebar": true,
"children": [
{
"loaded": true,
"isPathHref": true,
"title": "Methods",
"hasTitleStyling": true,
"autogenerate_path": "/service-factory-reference/methods",
"children": [
{
"loaded": true,
"isPathHref": true,
"path": "/service-factory-reference/methods/create",
"title": "create",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"path": "/service-factory-reference/methods/delete",
"title": "delete",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"path": "/service-factory-reference/methods/list",
"title": "list",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"path": "/service-factory-reference/methods/listAndCount",
"title": "listAndCount",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"path": "/service-factory-reference/methods/restore",
"title": "restore",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"path": "/service-factory-reference/methods/retrieve",
"title": "retrieve",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"path": "/service-factory-reference/methods/soft-delete",
"title": "softDelete",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"path": "/service-factory-reference/methods/update",
"title": "update",
"children": []
}
]
},
{
"loaded": true,
"isPathHref": true,
"title": "Tips",
"hasTitleStyling": true,
"autogenerate_path": "/service-factory-reference/tips",
"children": [
{
"loaded": true,
"isPathHref": true,
"path": "/service-factory-reference/tips/filtering",
"title": "Filtering",
"children": []
}
]
}
]
}
]
},

19
www/apps/resources/sidebar.mjs
View File

@@ -1799,7 +1799,7 @@ export const sidebar = sidebarAttachHrefCommonOptions([
],
},
{
title: "API References",
title: "References",
hasTitleStyling: true,
children: [
{
@@ -1852,6 +1852,23 @@ export const sidebar = sidebarAttachHrefCommonOptions([
},
],
},
{
path: "/service-factory-reference",
title: "Service Factory Reference",
isChildSidebar: true,
children: [
{
title: "Methods",
hasTitleStyling: true,
autogenerate_path: "/service-factory-reference/methods",
},
{
title: "Tips",
hasTitleStyling: true,
autogenerate_path: "/service-factory-reference/tips",
},
],
},
],
},
{