@nestjs-pipeline/cache 0.2.0

package/dist/interfaces/cache-options.interface.d.ts

@@ -0,0 +1,120 @@
+import type { InjectionToken, ModuleMetadata, OptionalFactoryDependency } from '@nestjs/common';
+import type { IPipelineContext } from '@nestjs-pipeline/core';
+import type { Cache } from 'cache-manager';
+import type { Keyv } from 'keyv';
+/**
+ * Built-in store backends supported through declarative configuration.
+ *
+ * - `memory`   — in-process `Keyv` map (default, no extra dependency).
+ * - `redis`    — requires the optional `@keyv/redis` package.
+ * - `memcache` — requires the optional `@keyv/memcache` package.
+ * - `sqlite`   — requires the optional `@keyv/sqlite` package.
+ * - `postgres` — requires the optional `@keyv/postgres` package.
+ */
+export type CacheStoreType = 'memory' | 'redis' | 'memcache' | 'sqlite' | 'postgres';
+/**
+ * Declarative description of a single cache store backend. Use this when you
+ * want the module to construct the `Keyv` adapter for you.
+ */
+export interface CacheStoreConfig {
+    /** Which backend to build. */
+    type: CacheStoreType;
+    /**
+     * Connection string / URI for the backend, e.g. `redis://localhost:6379`,
+     * `postgresql://user:pass@localhost:5432/db`, `sqlite://./cache.sqlite`, or
+     * `localhost:11211` for memcache. Ignored for `memory`.
+     */
+    url?: string;
+    /** Key namespace/prefix applied to every entry in this store. */
+    namespace?: string;
+    /** Default time-to-live (milliseconds) for entries written to this store. */
+    ttl?: number;
+    /** Adapter-specific options passed through to the underlying `@keyv/*` package. */
+    options?: Record<string, unknown>;
+}
+/** Factory that derives the cache key for a given pipeline request. */
+export type CacheKeyFactory = (context: IPipelineContext) => string;
+/** Predicate deciding whether a given request should participate in caching. */
+export type CacheCondition = (context: IPipelineContext) => boolean;
+/**
+ * Per-handler caching options, supplied through `@UsePipeline([CacheBehavior, options])`
+ * and/or as module-wide defaults via {@link CacheModuleOptions.defaults}.
+ *
+ * @example
+ * ```ts
+ * @UsePipeline([CacheBehavior, {
+ *   key: createPartitionedCacheKeyFactory({
+ *     principal: (ctx) => ctx.items.get('userId') as string | undefined,
+ *     scope: (ctx) => ctx.items.get('capabilityVersion') as string | undefined,
+ *   }),
+ *   ttl: 60_000,
+ * }])
+ * export class GetUserHandler {}
+ * ```
+ */
+export interface CacheBehaviorOptions {
+    /**
+     * Request kinds eligible for caching. Defaults to `['query']` so that
+     * commands and events bypass the cache automatically.
+     */
+    kinds?: Array<IPipelineContext['requestKind']>;
+    /** Time-to-live (milliseconds) for entries written by this handler. */
+    ttl?: number;
+    /**
+     * Cache-key factory. **Required** when this behavior runs — there is no default.
+     *
+     * A cache hit returns without executing the handler, so the key must partition
+     * every dimension that can change the authorized response: tenant, principal,
+     * permission scope and request payload. Use `createPartitionedCacheKeyFactory`
+     * rather than composing one by hand.
+     */
+    key?: CacheKeyFactory;
+    /** Optional predicate gating whether a given request is cached. */
+    condition?: CacheCondition;
+    /**
+     * When a cache read or write throws, bypass the cache and continue (`true`,
+     * default) or propagate the store error (`false`). A failed read bypasses the
+     * write for that execution. This option does not catch key, condition, or
+     * downstream handler errors.
+     */
+    failOpen?: boolean;
+}
+/**
+ * Options accepted by {@link CacheModule.forRoot}. The store can be provided in
+ * three ways: a pre-built `cache`, pre-built `stores`, or declarative `store`
+ * configuration. When several are given, `cache` takes precedence over
+ * `stores`, which takes precedence over `store`; the others are ignored. An
+ * empty `stores` array counts as absent. When none is supplied an in-memory
+ * store is used.
+ *
+ * @example Redis-backed cache
+ * ```ts
+ * CacheModule.forRoot({
+ *   store: { type: 'redis', url: process.env.REDIS_URL! },
+ *   ttl: 30_000,
+ *   defaults: { failOpen: true },
+ * });
+ * ```
+ */
+export interface CacheModuleOptions {
+    /** Escape hatch: a fully constructed `cache-manager` instance. */
+    cache?: Cache;
+    /** Escape hatch: pre-built `Keyv` stores (tiered, highest priority first). */
+    stores?: Keyv[];
+    /** Declarative store configuration — a single store or a tiered list. */
+    store?: CacheStoreConfig | CacheStoreConfig[];
+    /** Default time-to-live (milliseconds) applied across stores and handlers. */
+    ttl?: number;
+    /** Forwarded to `cache-manager`; optimizes behavior across multiple stores. */
+    nonBlocking?: boolean;
+    /** Default per-handler behavior options merged into every pipeline. */
+    defaults?: CacheBehaviorOptions;
+}
+/** Options for {@link CacheModule.forRootAsync}. */
+export interface CacheModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    /** Resolves the module options when the application starts. */
+    useFactory: (...args: never[]) => CacheModuleOptions | Promise<CacheModuleOptions>;
+    /** Providers injected into {@link useFactory}. */
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+}
+//# sourceMappingURL=cache-options.interface.d.ts.map

package/dist/interfaces/cache-options.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-options.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/cache-options.interface.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,yBAAyB,EAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAEjC;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,OAAO,GACP,UAAU,GACV,QAAQ,GACR,UAAU,CAAC;AAEf;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,IAAI,EAAE,cAAc,CAAC;IACrB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,uEAAuE;AACvE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,MAAM,CAAC;AAEpE,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC;AAEpE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC,CAAC;IAC/C,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,eAAe,CAAC;IACtB,mEAAmE;IACnE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,8EAA8E;IAC9E,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC;IAChB,yEAAyE;IACzE,KAAK,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAAC;IAC9C,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CACjC;AAED,oDAAoD;AACpD,MAAM,WAAW,uBACf,SAAQ,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC;IACvC,+DAA+D;IAC/D,UAAU,EAAE,CACV,GAAG,IAAI,EAAE,KAAK,EAAE,KACb,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACtD,kDAAkD;IAClD,MAAM,CAAC,EAAE,KAAK,CAAC,cAAc,GAAG,yBAAyB,CAAC,CAAC;CAC5D"}

package/dist/interfaces/cache-options.interface.js

@@ -0,0 +1,4 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=cache-options.interface.js.map

package/dist/interfaces/cache-options.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-options.interface.js","sourceRoot":"","sources":["../../src/interfaces/cache-options.interface.ts"],"names":[],"mappings":";AAAA,sEAAsE"}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@nestjs-pipeline/cache",
+  "version": "0.2.0",
+  "description": "Caching behavior for the NestJS pipeline — cache-manager v7 on top of Keyv with pluggable stores (memory, redis, memcache, sqlite, postgres).",
+  "author": "Aristotelis <aristotelis@ik.me>",
+  "license": "SEE LICENSE IN LICENSE",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "nestjs",
+    "pipeline",
+    "cqrs",
+    "cache",
+    "caching",
+    "cache-manager",
+    "keyv",
+    "redis",
+    "behavior"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aristoteliss/nestjs-pipeline.git",
+    "directory": "packages/pipeline-cache"
+  },
+  "homepage": "https://github.com/aristoteliss/nestjs-pipeline#readme",
+  "bugs": {
+    "url": "https://github.com/aristoteliss/nestjs-pipeline/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "COMMERCIAL_LICENSE.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@keyv/memcache": "^2.0.0",
+    "@keyv/postgres": "^2.0.0",
+    "@keyv/redis": "^4.0.0 || ^5.0.0",
+    "@keyv/sqlite": "^4.0.0",
+    "@nestjs/common": "^11.0.0",
+    "cache-manager": "^7.0.0",
+    "keyv": "^5.0.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0",
+    "@nestjs-pipeline/core": "^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@keyv/memcache": {
+      "optional": true
+    },
+    "@keyv/postgres": {
+      "optional": true
+    },
+    "@keyv/redis": {
+      "optional": true
+    },
+    "@keyv/sqlite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.2.6",
+    "@vitest/coverage-v8": "^4.1.11",
+    "cache-manager": "^7.2.9",
+    "keyv": "^5.6.0",
+    "reflect-metadata": "^0.2.2",
+    "vitest": "^4.1.11",
+    "@nestjs-pipeline/core": "0.2.0"
+  },
+  "dependencies": {
+    "@cqrs-ddd/safe-stringify": "^0.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "rebuild": "pnpm run clean && pnpm run build",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}