import { TypeList } from "docs-ui"

How to Use Caching Module

In this guide, you’ll learn about the different methods in the Caching Module's service and how to use them.

:::note

The Caching Module and its providers are available starting Medusa v2.11.0.

:::

:::tip

You should use the Caching Module's service when you're caching computed data or data from external APIs. To cache database query results, enable caching in Query or Index Module instead.

:::

Resolve Caching Module's Service

In your workflow's step, you can resolve the Caching Module's service from the Medusa container:

import { Modules } from "@medusajs/framework/utils"
import { createStep } from "@medusajs/framework/workflows-sdk"

const step1 = createStep(
  "step-1",
  async ({}, { container }) => {
    const cachingModuleService = container.resolve(
      Modules.CACHING
    )
    
    // TODO use cachingModuleService
  } 
)

You can then use the Caching Module's service's methods in the step. The rest of this guide details these methods.

clear

This method clears data from the cache. If neither key nor tags are provided, nothing is cleared.

By default, all items matching the key or tags are cleared regardless of their options. If you provide options.autoInvalidate: true, only items that were set with options.autoInvalidate: true are cleared.

For example, if you set options.autoInvalidate: true, only items that were set with options.autoInvalidate: true are cleared. Items that were set with options.autoInvalidate: false are only cleared when you don't provide any options.

Example

To invalidate cache by key:

await cachingModuleService.clear({
 key: "products" // this key would typically be a hash
})

This example will clear the item with the key products regardless of its options.autoInvalidate value.

To invalidate cache by tags:

await cachingModuleService.clear({
 tags: ["Product:list:*"]
})

This example will clear all items with the tag Product:list:* regardless of their options.autoInvalidate value.

To invalidate only the cache data that were set to automatically invalidate:

await cachingModuleService.clear({
 tags: ["Product:list:*"],
 options: { autoInvalidate: true }
})

This example will only clear items with the tag Product:list:* that were set with options.autoInvalidate: true. Items that were set with options.autoInvalidate: false will not be cleared.

:::note

Setting options.autoInvalidate: false when calling the clear method will not clear any items. To clear items that were set with options.autoInvalidate: false, you must call the clear method without any options.

:::

To invalidate cache from specific providers:

await cachingModuleService.clear({
 key: "products",
 providers: ["caching-redis", "caching-memcached"]
})

This example will try to clear the data from both the caching-redis and caching-memcached providers.

Parameters

Returns

<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"A promise that resolves when the item(s) have been cleared.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="clear"/>

computeKey

This method computes a cache key based on the input object. It's useful to generate consistent and unique keys for caching.

Example

const key = await cachingModuleService.computeKey({
  id: "prod_123",
  title: "Product 123"
})
// key will be a hash string like "a1b2c3d4e5f6g7h8i9j0"

Parameters

Returns

<TypeList types={[{"name":"Promise","type":"Promise<string>","optional":false,"defaultValue":"","description":"The computed cache key.","expandable":false,"children":[{"name":"string","type":"string","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="computeKey"/>

computeTags

This method computes cache tags based on the input object. It's useful to generate consistent and relevant tags for caching.

Example

const tags = await cachingModuleService.computeTags({
  products: [{ id: "prod_123" }, { id: "prod_456" }],
}, {
  operation: "updated"
})
// tags might be ["Product:prod_123", "Product:prod_456", "Product:list:*"]

Parameters

<TypeList types={[{"name":"input","type":"object","description":"The input object to compute the tags from.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"Record<string, any>","description":"Additional options to influence tag computation.","optional":true,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="computeTags"/>

Returns

<TypeList types={[{"name":"Promise","type":"Promise<string[]>","optional":false,"defaultValue":"","description":"An array of computed cache tags.","expandable":false,"children":[{"name":"string[]","type":"string[]","optional":false,"defaultValue":"","description":"","expandable":false,"children":[{"name":"string","type":"string","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="computeTags"/>

get

This method retrieves data from the cache. If neither key nor tags are provided, or the item is not found, null is returned.

Example

To retrieve by key:

const data = await cachingModuleService.get({
  key: "products", // this key would typically be a hash
}) as { id: string; title: string; }

To retrieve by tags:

const data = await cachingModuleService.get({
  tags: ["Product:list:*"],
}) as { id: string; title: string; }[]

To retrieve by key from specific providers:

const data = await cachingModuleService.get({
  key: "products", // this key would typically be a hash
  providers: ["caching-redis", "caching-memcached"]
}) as { id: string; title: string; }

This example will try to get the data from the caching-redis provider first, and if not found, it will try to get it from the caching-memcached provider.

Parameters

Returns

<TypeList types={[{"name":"Promise","type":"Promise<any>","optional":false,"defaultValue":"","description":"The item(s) that was stored in the cache. If no item was found, or neither key nor tags were provided, null is returned.","expandable":false,"children":[{"name":"any","type":"any","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="get"/>

set

This method stores data in the cache using the default Caching Module Provider.

Example

To store with key:

const data = { id: "prod_123", title: "Product 123" }
const key = await cachingModuleService.computeKey(data)
await cachingModuleService.set({
  key,
  data
})

To store with tags:

:::note

Tags should follow conventions to ensure they're automatically invalidated.

:::

const data = [{ id: "prod_123", title: "Product 123" }]
const key = await cachingModuleService.computeKey(data)
await cachingModuleService.set({
  key,
  data,
  tags: [`Product:${data[0].id}`, "Product:list:*"]
})

To disable auto-invalidation for the item:

const data = [{ id: "prod_123", title: "Product 123" }]
const key = await cachingModuleService.computeKey(data)
await cachingModuleService.set({
  key,
  data,
  options: { autoInvalidate: false }
})

The item is now only invalidated when calling the clear method directly with the same key or tags.

To store with specific providers:

const data = { id: "prod_123", title: "Product 123" }
const key = await cachingModuleService.computeKey(data)
await cachingModuleService.set({
  key,
  data,
  providers: [
    "caching-redis",
    { id: "caching-memcached", ttl: 120 } // custom TTL for this provider
  ]
})

This example will store the item in both the caching-redis and caching-memcached providers, with a custom TTL of 120 seconds for the caching-memcached provider.

Parameters

Returns

<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"A promise that resolves when the item has been stored.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="set"/>