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 14:40:56 +00: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
www/apps/resources/app/service-factory-reference/methods/create/page.mdx
+44
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.
www/apps/resources/app/service-factory-reference/methods/delete/page.mdx
+50
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>
www/apps/resources/app/service-factory-reference/methods/list/page.mdx
+132
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.
www/apps/resources/app/service-factory-reference/methods/listAndCount/page.mdx
+150
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.
www/apps/resources/app/service-factory-reference/methods/restore/page.mdx
+97
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"
]
}
```
www/apps/resources/app/service-factory-reference/methods/retrieve/page.mdx
+67
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.
www/apps/resources/app/service-factory-reference/methods/soft-delete/page.mdx
+97
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"]
}
```
www/apps/resources/app/service-factory-reference/methods/update/page.mdx
+137
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.