@medusajs/caching 2.22.0-snapshot-20261020204851 → 2.22.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +80 -0
- package/README.md +103 -0
- package/package.json +8 -4
package/AGENTS.md
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# @medusajs/caching
|
|
2
|
+
|
|
3
|
+
Caching Module (`Modules.CACHING`, container key `"caching"`). Provider-based, tag-aware cache that replaces the deprecated Cache Module (`cache-inmemory` / `cache-redis`). Powers `query.graph` / `query.index` / `useQueryGraphStep` caching and auto-invalidates entries from module events. Requires the `caching` feature flag (`MEDUSA_FF_CACHING=true`).
|
|
4
|
+
|
|
5
|
+
## Using this package
|
|
6
|
+
|
|
7
|
+
- Not registered by default for self-hosted projects (on Cloud, `defineConfig` adds it with `caching-redis` when `CACHE_REDIS_URL` is set).
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
module.exports = defineConfig({
|
|
11
|
+
modules: [
|
|
12
|
+
{
|
|
13
|
+
resolve: "@medusajs/medusa/caching",
|
|
14
|
+
options: {
|
|
15
|
+
ttl: 3600,
|
|
16
|
+
providers: [
|
|
17
|
+
{
|
|
18
|
+
resolve: "@medusajs/medusa/caching-redis",
|
|
19
|
+
id: "caching-redis",
|
|
20
|
+
is_default: true,
|
|
21
|
+
options: { redisUrl: process.env.CACHE_REDIS_URL },
|
|
22
|
+
},
|
|
23
|
+
],
|
|
24
|
+
},
|
|
25
|
+
},
|
|
26
|
+
],
|
|
27
|
+
})
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
- Options (`CachingModuleOptions`, `src/types/index.ts`):
|
|
31
|
+
- `ttl`: default TTL in seconds, default `3600`.
|
|
32
|
+
- `providers: { resolve, id, is_default?, options? }[]`: a single provider is always the default.
|
|
33
|
+
- `in_memory`: private; `{ enable, ttl, maxKeys, checkPeriod, useClones, maxSize }` enables the built-in `cache-memory` provider (node-cache, `maxSize` default 300MB).
|
|
34
|
+
- Service (`ICachingModuleService`, `src/services/cache-module.ts`):
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
const caching = container.resolve(Modules.CACHING)
|
|
38
|
+
|
|
39
|
+
const key = await caching.computeKey(input)
|
|
40
|
+
const cached = await caching.get({ key }) // or { tags }, optional providers: string[]
|
|
41
|
+
await caching.set({ key, data, tags: [`Brand:${brand.id}`], ttl: 600 })
|
|
42
|
+
await caching.clear({ tags: [`Brand:${brand.id}`] })
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
- `get({ key?, tags?, providers? })`: tries providers in order, returns first non-null; provider errors are logged and skipped.
|
|
46
|
+
- `set({ key, data, ttl?, tags?, computeAutomaticTags?, providers?, options: { autoInvalidate? } })`.
|
|
47
|
+
- `clear({ key?, tags?, options?, providers? })`, `computeKey(input)`, `computeTags(input, options?)`.
|
|
48
|
+
- Query caching: pass `cache` options to `query.graph` / `query.index` / `useQueryGraphStep` instead of calling the service.
|
|
49
|
+
- Custom providers implement `ICachingProviderService` and need a static `identifier`.
|
|
50
|
+
- No data models, no emitted events, no module links. It consumes events (see Architecture).
|
|
51
|
+
- Docs: https://docs.medusajs.com/resources/infrastructure-modules/caching.md, https://docs.medusajs.com/resources/infrastructure-modules/caching/concepts.md, https://docs.medusajs.com/resources/infrastructure-modules/caching/providers.md, https://docs.medusajs.com/resources/infrastructure-modules/caching/migrate-cache.md
|
|
52
|
+
|
|
53
|
+
## Architecture
|
|
54
|
+
|
|
55
|
+
- Loaders: `src/loaders/hash.ts` registers `hasher` (xxhash-wasm `h64ToString`); `src/loaders/providers.ts` registers the strategy, optional in-memory provider, and configured providers as aliases `lp_<id>`, then picks `default_provider`.
|
|
56
|
+
- `src/utils/strategy.ts` (`DefaultCacheStrategy`): `computeKey` = xxhash of `fast-json-stable-stringify(input)`. `computeTags` uses `CacheInvalidationParser` (`src/utils/parser.ts`) over the merged GraphQL schema of all loaded modules to find entities in the data.
|
|
57
|
+
- On `onApplicationStart`, the strategy subscribes to `"*"` on the Event Bus (and `addInterceptor` when available). Each event `<...>.<entity>.<operation>` is turned into tags and cleared with `autoInvalidate: true`.
|
|
58
|
+
- Concurrent identical `get`/`set`/`clear` calls are de-duplicated via `ongoingRequests`.
|
|
59
|
+
- Static `traceGet` / `traceSet` / `traceClear` hooks are used for instrumentation.
|
|
60
|
+
- Module definition dependencies: `Modules.EVENT_BUS`, `logger`.
|
|
61
|
+
|
|
62
|
+
## Development
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
yarn build
|
|
66
|
+
yarn test # src/**/__tests__ (memory provider, parser)
|
|
67
|
+
yarn test:integration # integration-tests/__tests__/*.spec.ts
|
|
68
|
+
yarn test:integration -t "<test name>"
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
- `integration-tests/__tests__/redis/invalidation.spec.ts` needs a Redis at `localhost:6379`.
|
|
72
|
+
- Event bus is mocked via `integration-tests/__fixtures__/event-bus-mock.ts`.
|
|
73
|
+
|
|
74
|
+
## Gotchas
|
|
75
|
+
|
|
76
|
+
- Load fails with "No providers have been configured and the built in memory cache has not been enabled." if there are no providers and `in_memory.enable` is not set.
|
|
77
|
+
- With multiple providers and none marked `is_default`, there is no default unless `in_memory` is enabled (then `cache-memory` is used with a warning).
|
|
78
|
+
- Passing explicit `tags` to `set` disables automatic tag computation unless `computeAutomaticTags: true`.
|
|
79
|
+
- `get`/`clear` throw `INVALID_ARGUMENT` without `key` or `tags`; `set` throws without `key`.
|
|
80
|
+
- A per-provider TTL can be passed as `providers: [{ id, ttl }]` to `set`; precedence is provider ttl, then call `ttl`, then module `ttl`.
|
package/README.md
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://www.medusajs.com">
|
|
3
|
+
<picture>
|
|
4
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
|
|
5
|
+
<source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
|
|
6
|
+
<img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
|
|
7
|
+
</picture>
|
|
8
|
+
</a>
|
|
9
|
+
</p>
|
|
10
|
+
<h1 align="center">
|
|
11
|
+
@medusajs/caching
|
|
12
|
+
</h1>
|
|
13
|
+
|
|
14
|
+
<h4 align="center">
|
|
15
|
+
<a href="https://docs.medusajs.com">Documentation</a> |
|
|
16
|
+
<a href="https://www.medusajs.com">Website</a>
|
|
17
|
+
</h4>
|
|
18
|
+
|
|
19
|
+
<p align="center">
|
|
20
|
+
Building blocks for digital commerce
|
|
21
|
+
</p>
|
|
22
|
+
<p align="center">
|
|
23
|
+
<a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
|
|
24
|
+
<img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
|
|
25
|
+
</a>
|
|
26
|
+
<a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
|
|
27
|
+
<img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
|
|
28
|
+
</a>
|
|
29
|
+
<a href="https://discord.gg/xpCwq3Kfn8">
|
|
30
|
+
<img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
|
|
31
|
+
</a>
|
|
32
|
+
<a href="https://twitter.com/intent/follow?screen_name=medusajs">
|
|
33
|
+
<img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
|
|
34
|
+
</a>
|
|
35
|
+
</p>
|
|
36
|
+
|
|
37
|
+
Caching Module for Medusa: caches data such as Query and Index Module results in a pluggable caching service like Redis. It replaces the deprecated Cache Modules (`@medusajs/cache-inmemory`, `@medusajs/cache-redis`) and uses a provider pattern, so the underlying store is a Caching Module Provider. It ships with `@medusajs/medusa` and is registered from `@medusajs/medusa/caching`.
|
|
38
|
+
|
|
39
|
+
## At a glance
|
|
40
|
+
|
|
41
|
+
| | |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| Package | `@medusajs/caching` |
|
|
44
|
+
| Type | Infrastructure Module |
|
|
45
|
+
| Module key | `Modules.CACHING` (`"caching"`) |
|
|
46
|
+
| Registered by default | No |
|
|
47
|
+
| Import from | `@medusajs/medusa/caching` |
|
|
48
|
+
|
|
49
|
+
## Features
|
|
50
|
+
|
|
51
|
+
- Cache Query and Index Module results, or cache any data directly through the module's service.
|
|
52
|
+
- Pluggable providers, with a default provider selected by `is_default` (or the only registered provider). Official provider:
|
|
53
|
+
- [`@medusajs/caching-redis`](../providers/caching-redis): stores cached data in Redis.
|
|
54
|
+
|
|
55
|
+
## Installation
|
|
56
|
+
|
|
57
|
+
No installation needed. The module ships with `@medusajs/medusa`. To use it:
|
|
58
|
+
|
|
59
|
+
1. Enable the caching feature flag by setting `MEDUSA_FF_CACHING=true` in your environment.
|
|
60
|
+
2. Register the module with at least one provider in `medusa-config.ts`. The module throws on startup if no provider is configured.
|
|
61
|
+
|
|
62
|
+
## Usage
|
|
63
|
+
|
|
64
|
+
```ts title="medusa-config.ts"
|
|
65
|
+
import { defineConfig } from "@medusajs/framework/utils"
|
|
66
|
+
|
|
67
|
+
module.exports = defineConfig({
|
|
68
|
+
// ...
|
|
69
|
+
modules: [
|
|
70
|
+
{
|
|
71
|
+
resolve: "@medusajs/medusa/caching",
|
|
72
|
+
options: {
|
|
73
|
+
providers: [
|
|
74
|
+
{
|
|
75
|
+
resolve: "@medusajs/caching-redis",
|
|
76
|
+
id: "caching-redis",
|
|
77
|
+
is_default: true,
|
|
78
|
+
options: {
|
|
79
|
+
redisUrl: process.env.CACHE_REDIS_URL,
|
|
80
|
+
},
|
|
81
|
+
},
|
|
82
|
+
],
|
|
83
|
+
},
|
|
84
|
+
},
|
|
85
|
+
],
|
|
86
|
+
})
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Then resolve the service with `container.resolve(Modules.CACHING)`.
|
|
90
|
+
|
|
91
|
+
## Configuration
|
|
92
|
+
|
|
93
|
+
| Option | Type | Description | Default |
|
|
94
|
+
| --- | --- | --- | --- |
|
|
95
|
+
| `providers` | `{ resolve: string, id: string, is_default?: boolean, options?: Record<string, unknown> }[]` | Caching Module Providers to register. | - |
|
|
96
|
+
| `ttl` | `number` | Time to keep data in the cache, in seconds. | `3600` |
|
|
97
|
+
|
|
98
|
+
## Resources
|
|
99
|
+
|
|
100
|
+
- [Caching Module](https://docs.medusajs.com/resources/infrastructure-modules/caching)
|
|
101
|
+
- [Caching Module concepts](https://docs.medusajs.com/resources/infrastructure-modules/caching/concepts)
|
|
102
|
+
- [Redis Caching Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/caching/providers/redis)
|
|
103
|
+
- [Migrate from the Cache Module](https://docs.medusajs.com/resources/infrastructure-modules/caching/migrate-cache)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@medusajs/caching",
|
|
3
|
-
"version": "2.22.0
|
|
3
|
+
"version": "2.22.0",
|
|
4
4
|
"description": "Caching Module for Medusa",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"repository": {
|
|
@@ -13,10 +13,14 @@
|
|
|
13
13
|
},
|
|
14
14
|
"files": [
|
|
15
15
|
"dist",
|
|
16
|
+
"AGENTS.md",
|
|
16
17
|
"!dist/**/__tests__",
|
|
17
18
|
"!dist/**/__mocks__",
|
|
18
19
|
"!dist/**/__fixtures__"
|
|
19
20
|
],
|
|
21
|
+
"llms": "https://docs.medusajs.com/llms.txt",
|
|
22
|
+
"llmsFull": "https://docs.medusajs.com/llms-full.txt",
|
|
23
|
+
"mcpServer": "https://docs.medusajs.com/mcp",
|
|
20
24
|
"publishConfig": {
|
|
21
25
|
"access": "public"
|
|
22
26
|
},
|
|
@@ -31,12 +35,12 @@
|
|
|
31
35
|
"test:integration": "../../../node_modules/.bin/jest --passWithNoTests --forceExit --testPathPattern=\"integration-tests/__tests__/.*\\.ts\""
|
|
32
36
|
},
|
|
33
37
|
"devDependencies": {
|
|
34
|
-
"@medusajs/framework": "2.22.0
|
|
35
|
-
"@medusajs/test-utils": "2.22.0
|
|
38
|
+
"@medusajs/framework": "2.22.0",
|
|
39
|
+
"@medusajs/test-utils": "2.22.0",
|
|
36
40
|
"awilix": "^8.0.1"
|
|
37
41
|
},
|
|
38
42
|
"peerDependencies": {
|
|
39
|
-
"@medusajs/framework": "2.22.0
|
|
43
|
+
"@medusajs/framework": "2.22.0",
|
|
40
44
|
"awilix": "^8.0.1"
|
|
41
45
|
},
|
|
42
46
|
"dependencies": {
|