docs: added file module docs (#7278)
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
8b2429d24f
commit
803e4aad02
32 files changed
+745
-3448
No files matched your search
@@ -0,0 +1,165 @@
|
||||
export const metadata = {
|
||||
title: `How to Create a Cache Module`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this guide, you’ll learn how to create a Cache Module.
|
||||
|
||||
## 1. Create Module Directory
|
||||
|
||||
Start by creating a new directory for your module. For example, `src/modules/my-cache`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Create the Cache Service
|
||||
|
||||
Create the file `src/modules/my-cache/service.ts` that holds the implementation of the cache service.
|
||||
|
||||
The Cache Module's main service must implement the `ICacheService` interface imported from `@medusajs/types`:
|
||||
|
||||
```ts title="src/modules/my-cache/service.ts"
|
||||
import { ICacheService } from "@medusajs/types"
|
||||
|
||||
class MyCacheService implements ICacheService {
|
||||
get<T>(key: string): Promise<T> {
|
||||
throw new Error("Method not implemented.")
|
||||
}
|
||||
set(key: string, data: unknown, ttl?: number): Promise<void> {
|
||||
throw new Error("Method not implemented.")
|
||||
}
|
||||
invalidate(key: string): Promise<void> {
|
||||
throw new Error("Method not implemented.")
|
||||
}
|
||||
}
|
||||
|
||||
export default MyCacheService
|
||||
```
|
||||
|
||||
The service implements the required methods based on the desired caching mechanism.
|
||||
|
||||
### Implement get Method
|
||||
|
||||
The `get` method retrieves the value of a cached item based on its key.
|
||||
|
||||
The method accepts a string as a first parameter, which is the key in the cache. It either returns the cached item or `null` if it doesn’t exist.
|
||||
|
||||
For example, to implement this method using Memcached:
|
||||
|
||||
```ts title="src/modules/my-cache/service.ts"
|
||||
class MyCacheService implements ICacheService {
|
||||
// ...
|
||||
async get<T>(cacheKey: string): Promise<T | null> {
|
||||
return new Promise((res, rej) => {
|
||||
this.memcached.get(cacheKey, (err, data) => {
|
||||
if (err) {
|
||||
res(null)
|
||||
} else {
|
||||
if (data) {
|
||||
res(JSON.parse(data))
|
||||
} else {
|
||||
res(null)
|
||||
}
|
||||
}
|
||||
})
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Implement set Method
|
||||
|
||||
The `set` method is used to set an item in the cache. It accepts three parameters:
|
||||
|
||||
1. The first parameter is a string indicating the key of the data being added to the cache. This key can be used later to get or invalidate the cached item.
|
||||
2. The second parameter is the data to be added to the cache. The data can be of any type.
|
||||
3. The third parameter is optional. It’s a number indicating how long (in seconds) the data should be kept in the cache.
|
||||
|
||||
For example, to implement this method using Memcached:
|
||||
|
||||
```ts title="src/modules/my-cache/service.ts"
|
||||
class MyCacheService implements ICacheService {
|
||||
protected TTL = 60
|
||||
// ...
|
||||
async set(
|
||||
key: string,
|
||||
data: Record<string, unknown>,
|
||||
ttl: number = this.TTL // or any value
|
||||
): Promise<void> {
|
||||
return new Promise((res, rej) =>
|
||||
this.memcached.set(
|
||||
key, JSON.stringify(data), ttl, (err) => {
|
||||
if (err) {
|
||||
rej(err)
|
||||
} else {
|
||||
res()
|
||||
}
|
||||
})
|
||||
)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Implement invalidate Method
|
||||
|
||||
The `invalidate` method removes an item from the cache using its key.
|
||||
|
||||
By default, items are removed from the cache when their time-to-live (ttl) expires. The `invalidate` method can be used to remove the item beforehand.
|
||||
|
||||
The method accepts a string as a first parameter, which is the key of the item to invalidate and remove from the cache.
|
||||
|
||||
For example, to implement this method using Memcached:
|
||||
|
||||
```ts title="src/modules/my-cache/service.ts"
|
||||
class MyCacheService implements ICacheService {
|
||||
// ...
|
||||
async invalidate(key: string): Promise<void> {
|
||||
return new Promise((res, rej) => {
|
||||
this.memcached.del(key, (err) => {
|
||||
if (err) {
|
||||
rej(err)
|
||||
} else {
|
||||
res()
|
||||
}
|
||||
})
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Create Module Definition File
|
||||
|
||||
Create the file `src/modules/my-cache/index.ts` with the following content:
|
||||
|
||||
```ts title="src/modules/my-cache/index.ts"
|
||||
import MyCacheService from "./service"
|
||||
|
||||
export default {
|
||||
service: MyCacheService,
|
||||
}
|
||||
```
|
||||
|
||||
This exports the module's definition, indicating that the `MyCacheService` is the main service of the module.
|
||||
|
||||
---
|
||||
|
||||
## 4. Use Module
|
||||
|
||||
To use your Cache Module, add it to the `modules` object exported as part of the configurations in `medusa-config.js`. A Cache Module is added under the `cacheService` key.
|
||||
|
||||
For example:
|
||||
|
||||
```js title="medusa-config.js"
|
||||
const modules = {
|
||||
// other modules...
|
||||
cacheService: {
|
||||
resolve: "./dist/modules/my-cache/index.ts",
|
||||
options: {
|
||||
// any necessary options
|
||||
ttl: 30,
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,11 @@
|
||||
import { ChildDocs } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Cache Modules`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
Learn how to create a cache module in [this guide](./create/page.mdx).
|
||||
|
||||
<ChildDocs type="item" filters={["Guides"]} onlyTopLevel={true} />
|
||||
@@ -0,0 +1,119 @@
|
||||
export const metadata = {
|
||||
title: `How to Create an Event Module`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this guide, you’ll learn how to create an Event Module.
|
||||
|
||||
## 1. Create Module Directory
|
||||
|
||||
Start by creating a new directory for your module. For example, `src/modules/my-event`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Create the Event Service
|
||||
|
||||
Create the file `src/modules/my-event/service.ts` that holds the implementation of the event service.
|
||||
|
||||
The Event Module's main service must extend the `AbstractEventBusModuleService` class imported from `@medusajs/utils`:
|
||||
|
||||
```ts title="src/modules/my-event/service.ts"
|
||||
import { EmitData, Message } from "@medusajs/types"
|
||||
import { AbstractEventBusModuleService } from "@medusajs/utils"
|
||||
|
||||
class MyEventService extends AbstractEventBusModuleService {
|
||||
emit<T>(eventName: string, data: T, options: Record<string, unknown>): Promise<void>;
|
||||
emit<T>(data: EmitData<T>[]): Promise<void>;
|
||||
emit<T>(data: Message<T>[]): Promise<void>;
|
||||
emit(eventName: unknown, data?: unknown, options?: unknown): Promise<void> {
|
||||
throw new Error("Method not implemented.")
|
||||
}
|
||||
}
|
||||
|
||||
export default MyEventService
|
||||
```
|
||||
|
||||
The service implements the required methods based on the desired publish/subscribe logic.
|
||||
|
||||
### Note About the eventToSubscribersMap Property
|
||||
|
||||
The `AbstractEventBusModuleService` has a field `eventToSubscribersMap`, which is a JavaScript Map. The map's keys are the event names, whereas the value of each key is an array of subscribed handler functions.
|
||||
|
||||
In your custom implementation, you can use this property to manage the subscribed handler functions:
|
||||
|
||||
```ts
|
||||
const eventSubscribers =
|
||||
this.eventToSubscribersMap.get(eventName) || []
|
||||
```
|
||||
|
||||
### Implement emit Method
|
||||
|
||||
The `emit` method is used to push an event from the Medusa application into your messaging system. The subscribers to that event would then pick up the message and execute their asynchronous tasks.
|
||||
|
||||
The `emit` method has three different signatures:
|
||||
|
||||
1. The first signature accepts three parameters:
|
||||
- The first parameter is a string indicating the name of the event to trigger.
|
||||
- The second parameter is data to send to subscribers of that event.
|
||||
- The third optional parameter can be used to pass options specific to the event service.
|
||||
2. The second signature accepts one parameter, which is an array of objects having the following properties:
|
||||
- `eventName`: A string indicating the name of the event to trigger.
|
||||
- `data`: The data to send to subsribers of that event.
|
||||
- `options`: (optional) options specific to the event service.
|
||||
3. The third signature accepts one parameter, which is an array of objects having the following properties:
|
||||
- `eventName`: A string indicating the name of the event to trigger.
|
||||
- `body`: An object of event-related data. It has two properties: `data` holding the data of the event, and `metadata` which is an object with more details on how the event was emitted, such as the action that occurred or the service that emitted it.
|
||||
- `options`: (optional) options specific to the event service.
|
||||
|
||||
You can implement your method in a way that supports both signatures by checking the type of the first input. For example:
|
||||
|
||||
```ts title="src/modules/my-event/service.ts"
|
||||
class MyEventService extends AbstractEventBusModuleService {
|
||||
// ...
|
||||
emit<T>(eventName: string, data: T, options: Record<string, unknown>): Promise<void>;
|
||||
emit<T>(data: EmitData<T>[]): Promise<void>;
|
||||
emit<T>(data: Message<T>[]): Promise<void>;
|
||||
emit(eventOrData: unknown, data?: unknown, options?: unknown): Promise<void> {
|
||||
const isBulkEmit = Array.isArray(eventOrData)
|
||||
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Create Module Definition File
|
||||
|
||||
Create the file `src/modules/my-event/index.ts` with the following content:
|
||||
|
||||
```ts
|
||||
import MyEventService from "./service"
|
||||
|
||||
export default {
|
||||
service: MyEventService,
|
||||
}
|
||||
```
|
||||
|
||||
This exports the module's definition, indicating that the `MyEventService` is the main service of the module.
|
||||
|
||||
---
|
||||
|
||||
## 4. Use Module
|
||||
|
||||
To use your Event Module, add it to the `modules` object exported as part of the configurations in `medusa-config.js`. An Event Module is added under the `eventBus` key.
|
||||
|
||||
For example:
|
||||
|
||||
```js title="medusa-config.js"
|
||||
const modules = {
|
||||
// other modules...
|
||||
eventBus: {
|
||||
resolve: "./dist/modules/my-event/index.ts",
|
||||
options: {
|
||||
// any necessary options
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,11 @@
|
||||
import { ChildDocs } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Event Modules`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
Learn how to create a event module in [this guide](./create/page.mdx).
|
||||
|
||||
<ChildDocs type="item" filters={["Guides"]} onlyTopLevel={true} />
|
||||
@@ -0,0 +1,101 @@
|
||||
import { Table } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Local File Provider Module`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
The Local File Provider Module stores files uploaded to your Medusa application in the `/uploads` directory.
|
||||
|
||||
---
|
||||
|
||||
## Install the Local File Module
|
||||
|
||||
To install the Local File Provider Module, run the following command in the directory of your Medusa application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/file-local-next
|
||||
```
|
||||
|
||||
Next, add the module into the `providers` array of the File Module:
|
||||
|
||||
<Note>
|
||||
|
||||
The File Module accepts one provider only.
|
||||
|
||||
</Note>
|
||||
|
||||
```js title="medusa-config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
modules: {
|
||||
// ...
|
||||
[Modules.FILE]: {
|
||||
resolve: "@medusajs/file",
|
||||
options: {
|
||||
providers: [
|
||||
{
|
||||
resolve: "@medusajs/file-local-next",
|
||||
options: {
|
||||
config: {
|
||||
local: {
|
||||
// provider options...
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Local File Module Options
|
||||
|
||||
<Table>
|
||||
<Table.Header>
|
||||
<Table.Row>
|
||||
<Table.HeaderCell>Option</Table.HeaderCell>
|
||||
<Table.HeaderCell>Description</Table.HeaderCell>
|
||||
<Table.HeaderCell>Default</Table.HeaderCell>
|
||||
</Table.Row>
|
||||
</Table.Header>
|
||||
<Table.Body>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`upload_dir`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
The directory to upload files to.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
`uploads`
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`upload_dir`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
The URL of the Medusa application.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
`http://localhost:9000`
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
</Table.Body>
|
||||
</Table>
|
||||
@@ -0,0 +1,11 @@
|
||||
import { ChildDocs } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `File Provider Modules`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
Learn how to create a file provider module in [this guide](/references/file-provider-module).
|
||||
|
||||
<ChildDocs type="item" filters={["Guides"]} onlyTopLevel={true} />
|
||||
@@ -8,4 +8,4 @@ export const metadata = {
|
||||
|
||||
This section includes documentation for official Medusa architectural modules.
|
||||
|
||||
<ChildDocs />
|
||||
<ChildDocs filters={["Guides"]} />
|
||||
@@ -48,11 +48,15 @@ const modules = {
|
||||
{
|
||||
resolve: "@medusajs/payment-stripe",
|
||||
options: {
|
||||
credentials: {
|
||||
usd: {
|
||||
apiKey: process.env.STRIPE_USD_API_KEY,
|
||||
},
|
||||
},
|
||||
config: {
|
||||
stripe: {
|
||||
credentials: {
|
||||
usd: {
|
||||
apiKey: process.env.STRIPE_USD_API_KEY,
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
},
|
||||
},
|
||||
],
|
||||
|
||||
Reference in new issue
Block a user