Caching

Declare one or more caches with @Cache on the root module. Inject them with @CacheClient by owner plugin (and optional name) — including caches owned by other plugins. Use route- and method-level helpers to read/invalidate those same named clients.

Stack

@Cache on the root @Module — in-memory or Redis; one plugin may declare multiple named caches
@CacheClient(plugin, name?) — inject an ICache from this plugin or another
@CacheRoute / @DeleteCacheRoute — HTTP response cache keyed by plugin + name
@CacheFn / @DeleteCacheFn — method result cache keyed by plugin + name
Cross-plugin reuse — consumer plugins inject the owner’s cache; they do not re-declare @Cache for the same client

@Cache on the root module

@Cache must sit on the @Module class — not on services or controllers. Pass a unique name when the plugin opens more than one cache. Multiple @Cache decorators on the same module class are allowed.

type — "in-memory" or Redis options (host/port/password from env)
name — optional client id (required when one plugin declares multiple @Cache entries)
checkperiod / ttl / other options — follow the shared-backend-core Cache options for that type
Owner is the loading plugin — consumers address it by that plugin’s metadata.name (or CacheManager.DEFAULT_PLUGIN for core)

TSXmultiple caches in one plugin

import { Cache, Module } from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };

@Cache({
  name: "publisher",
  type: "in-memory",
  checkperiod: 1000,
})
@Cache({
  name: "session",
  type: "redis",
  host: process.env.REDIS_HOST,
  port: Number(process.env.REDIS_PORT ?? 6379),
  password: process.env.REDIS_PASSWORD,
})
@Module({
  name: metadata.name,
  providers: [...],
  controllers: [...],
})
export class MyPluginModule {}

@CacheClient

Inject an ICache on a service property. The first argument is the plugin that owns the cache; the second is the optional connection name when that plugin declared more than one @Cache.

CacheManager.DEFAULT_PLUGIN — core / shared default cache owner
metadata.name — this plugin’s own cache (add name when it has several)
"other-plugin" — a cache created by another plugin (same process / registry)
Second arg name — named client (e.g. "publisher", "session")

TSXinject

import {
  CacheClient,
  CacheManager,
  Service,
} from "@quan-erp/shared-backend-core";
import type { ICache } from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };

@Service()
export class PublisherService {
  // Core / default owner
  @CacheClient(CacheManager.DEFAULT_PLUGIN, "publisher")
  private defaultPublisher: ICache;

  // This plugin’s named cache
  @CacheClient(metadata.name, "session")
  private session: ICache;

  // Cache owned by another plugin
  @CacheClient("warehouse", "replica")
  private warehouseReplica: ICache;
}

Use another plugin’s cache

Caches live in a process-wide registry keyed by owner plugin (+ optional name). A consumer does not re-declare @Cache for that client — it injects the owner’s cache and points route/method helpers at the same plugin + name.

Owner plugin — declares @Cache({ name, … }) and boots first (list it in pluginDependencies)
Consumer plugin — @CacheClient("owner-plugin", "cache-name")
Route / method helpers — set plugin: "owner-plugin" and name: "cache-name"
Do not hard-code a second identical @Cache in every consumer — reuse the owner’s client
Ensure the owner plugin is installed and loaded before consumers that inject its ICache

TSXconsumer service

import { CacheClient, Service } from "@quan-erp/shared-backend-core";
import type { ICache } from "@quan-erp/shared-backend-core";

@Service()
export class ReportService {
  // "warehouse" plugin declared @Cache({ name: "replica", ... })
  @CacheClient("warehouse", "replica")
  private warehouseReplica: ICache;
}

Route-level

@CacheRoute({ key, plugin, name }) — key may be string or (req) => string
@DeleteCacheRoute({ key, plugin, name }) — callback key must return string[]
plugin + name must match the owning @Cache (including another plugin’s client)

TSXroute cache

import {
  CacheRoute,
  Controller,
  DeleteCacheRoute,
  Get,
  Post,
} from "@quan-erp/shared-backend-core";

@Controller("/branch")
export class BranchController {
  @Get("/")
  @CacheRoute({
    key: (req) => `branch-${req.query.skip}-${req.query.limit}`,
    plugin: "warehouse",
    name: "replica",
  })
  async list() { /* … */ }

  @Post("/")
  @DeleteCacheRoute({
    key: (req) => [`branch-${(req as any).user.payload.id}`],
    plugin: "warehouse",
    name: "replica",
  })
  async create() { /* … */ }
}

Method-level

@CacheFn({ key, plugin, name }) — key is (...args) => string
@DeleteCacheFn({ key, plugin, name }) — key returns string[] (wildcards allowed)
Same plugin + name rules as @CacheClient / route helpers

TSXmethod cache

import {
  CacheFn,
  CacheManager,
  DeleteCacheFn,
  Service,
} from "@quan-erp/shared-backend-core";
import type { CreateJobDTO } from "./create-job.dto.js";

@Service()
export class JobService {
  @CacheFn({
    plugin: CacheManager.DEFAULT_PLUGIN,
    name: "publisher",
    key: (skip: number, limit: number) => `active-jobs-${skip}-${limit}`,
  })
  async getActiveJobs(skip: number, limit: number) { /* … */ }

  @DeleteCacheFn({
    plugin: CacheManager.DEFAULT_PLUGIN,
    name: "publisher",
    key: () => [`active-jobs-*`],
  })
  async register(dto: CreateJobDTO) { /* … */ }
}