@seta-labs/nestjs-cache-control 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# @seta-labs/nestjs-cache-control
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The request cache directives of RFC 9111 for NestJS lookups served from a
+store (a table of provider answers, paid or rate-limited): the rule lives in
+one tested function, each app only reads its row, asks its provider and
+writes. The response says what happened in `Cache-Status` (RFC 9211) and
+`Age`.
+
+| Request `Cache-Control` | Stored row usable        | No row, or past `max-age` | Writes the answer |
+| ----------------------- | ------------------------ | ------------------------- | ----------------- |
+| none                    | served (`hit`)           | provider (`fwd=miss`)     | yes               |
+| `no-cache`              | provider (`fwd=request`) | provider                  | yes               |
+| `no-cache, no-store`    | provider                 | provider                  | no: pure bypass   |
+| `no-store`              | served                   | provider                  | no                |
+| `max-age=N`             | served if ≤ N s old      | provider (`fwd=stale`)    | yes               |
+| `only-if-cached`        | served                   | `504` `NOT_CACHED`        | —                 |
+
+If the provider is asked, its answer is stored unless the request says
+`no-store`: a store shared by several apps keeps the freshest answer. Unknown
+directives and an invalid `max-age` are ignored, as the RFC asks.
+
+## Use
+
+```ts
+// app.module.ts: once, it registers the interceptor writing Cache-Status and Age
+CacheControlModule.forRoot({ name: 'seta-geo' });
+```
+
+```ts
+@Post('parcel')
+@ApiCacheControl() // OpenAPI: the Cache-Control header and the 504
+parcel(@Body() dto: ParcelRequestDto, @RequestCachePolicy() cache: CacheContext) {
+    return this.parcelService.parcel(dto, cache);
+}
+```
+
+```ts
+async parcel(request: ParcelRequestDto, cache: CacheContext): Promise<ParcelResultDto> {
+    const stored = await this.repository.find(keyOf(request));
+    const decision = cache.decide(stored?.updatedAt ?? null);
+    switch (decision.action) {
+        case 'serve':
+            return toParcelResultDto(stored!, true);
+        case 'refuse':
+            throw new NotCachedException();
+        case 'fetch': {
+            const answer = await this.provider.lookup(request);
+            const parcel = decision.store ? await this.repository.save(answer) : answer;
+            return toParcelResultDto(parcel, false);
+        }
+    }
+}
+```
+
+`cache.decide(storedAt)` rules on one row and records the decision; the
+interceptor turns a response's single decision into its headers. A request
+deciding for several rows (a batch) gets no `Cache-Status`: one header
+cannot describe its items, the body does. Routes without
+`@RequestCachePolicy()` are left alone.
+
+The headers go through the Nest HTTP adapter, so Express and Fastify behave
+the same. A request that fails after deciding never says `stored`: the fetch
+that threw wrote nothing. Directive arguments may be quoted strings; a comma
+inside quotes never starts a directive.
+
+| Decision                           | Response headers                               |
+| ---------------------------------- | ---------------------------------------------- |
+| `serve`                            | `Cache-Status: <name>; hit`, `Age: <seconds>`  |
+| `fetch` (`miss`/`request`/`stale`) | `Cache-Status: <name>; fwd=<reason>[; stored]` |
+| `refuse`                           | `Cache-Status: <name>; detail=not-cached`, 504 |
+
+## API
+
+- `CacheControlModule.forRoot({ name })`: the global `CacheStatusInterceptor`, `name` labels `Cache-Status`.
+- `@RequestCachePolicy()`: the request's `CacheContext` (`policy`, `decide(storedAt)`, `decisions`).
+- `@ApiCacheControl()`: documents the request header and the 504.
+- `NotCachedException`: the 504 with `code: 'NOT_CACHED'`.
+- `parseCacheControl(header)`, `decideCache(policy, storedAt, now?)`, `createCacheContext(policy)`, `cacheStatusHeaders(name, decision)`: the pure parts, for other transports.

package/dist/api-cache-control.decorator.d.ts

@@ -0,0 +1,2 @@
+/** OpenAPI of a lookup that honours `Cache-Control`: the request header and the 504. */
+export declare function ApiCacheControl(): MethodDecorator & ClassDecorator;

package/dist/api-cache-control.decorator.js

@@ -0,0 +1,16 @@
+import { applyDecorators } from '@nestjs/common';
+import { ApiGatewayTimeoutResponse, ApiHeader } from '@nestjs/swagger';
+/** OpenAPI of a lookup that honours `Cache-Control`: the request header and the 504. */
+export function ApiCacheControl() {
+    return applyDecorators(ApiHeader({
+        name: 'Cache-Control',
+        required: false,
+        description: 'no-cache: ask the provider and store its answer; no-store: never write the store; ' +
+            'max-age=N: a stored answer older than N seconds is asked again; only-if-cached: ' +
+            'never ask the provider. The response says what happened in Cache-Status ' +
+            '(hit, fwd=miss|request|stale, stored) and, on a hit, Age.',
+    }), ApiGatewayTimeoutResponse({
+        description: 'NOT_CACHED: only-if-cached and no usable stored answer.',
+    }));
+}
+//# sourceMappingURL=api-cache-control.decorator.js.map

package/dist/api-cache-control.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-cache-control.decorator.js","sourceRoot":"","sources":["../src/api-cache-control.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,yBAAyB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEvE,wFAAwF;AACxF,MAAM,UAAU,eAAe;IAC3B,OAAO,eAAe,CAClB,SAAS,CAAC;QACN,IAAI,EAAE,eAAe;QACrB,QAAQ,EAAE,KAAK;QACf,WAAW,EACP,oFAAoF;YACpF,kFAAkF;YAClF,0EAA0E;YAC1E,2DAA2D;KAClE,CAAC,EACF,yBAAyB,CAAC;QACtB,WAAW,EAAE,yDAAyD;KACzE,CAAC,CACL,CAAC;AACN,CAAC"}

package/dist/cache-control.constants.d.ts

@@ -0,0 +1,5 @@
+export declare const CACHE_CONTROL_OPTIONS: unique symbol;
+/** Where `@RequestCachePolicy()` leaves the request's context for the interceptor. */
+export declare const CACHE_CONTEXT: unique symbol;
+/** The `code` of the 504 a refused `only-if-cached` lookup answers. */
+export declare const NOT_CACHED = "NOT_CACHED";

package/dist/cache-control.constants.js

@@ -0,0 +1,6 @@
+export const CACHE_CONTROL_OPTIONS = Symbol('CACHE_CONTROL_OPTIONS');
+/** Where `@RequestCachePolicy()` leaves the request's context for the interceptor. */
+export const CACHE_CONTEXT = Symbol('CACHE_CONTEXT');
+/** The `code` of the 504 a refused `only-if-cached` lookup answers. */
+export const NOT_CACHED = 'NOT_CACHED';
+//# sourceMappingURL=cache-control.constants.js.map

package/dist/cache-control.constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-control.constants.js","sourceRoot":"","sources":["../src/cache-control.constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,uBAAuB,CAAC,CAAC;AAErE,sFAAsF;AACtF,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;AAErD,uEAAuE;AACvE,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC"}

package/dist/cache-control.module.d.ts

@@ -0,0 +1,10 @@
+import { type DynamicModule } from '@nestjs/common';
+import type { CacheControlModuleOptions } from './types/cache-control-options.type.js';
+/**
+ * Import once in the root module: registers `CacheStatusInterceptor` for
+ * every route. Lookups then take `@RequestCachePolicy()` and decide with it;
+ * routes that do not are left alone.
+ */
+export declare class CacheControlModule {
+    static forRoot(options: CacheControlModuleOptions): DynamicModule;
+}

package/dist/cache-control.module.js

@@ -0,0 +1,32 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var CacheControlModule_1;
+import { Module } from '@nestjs/common';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import { CACHE_CONTROL_OPTIONS } from './cache-control.constants.js';
+import { CacheStatusInterceptor } from './cache-status.interceptor.js';
+/**
+ * Import once in the root module: registers `CacheStatusInterceptor` for
+ * every route. Lookups then take `@RequestCachePolicy()` and decide with it;
+ * routes that do not are left alone.
+ */
+let CacheControlModule = CacheControlModule_1 = class CacheControlModule {
+    static forRoot(options) {
+        return {
+            module: CacheControlModule_1,
+            providers: [
+                { provide: CACHE_CONTROL_OPTIONS, useValue: options },
+                { provide: APP_INTERCEPTOR, useClass: CacheStatusInterceptor },
+            ],
+        };
+    }
+};
+CacheControlModule = CacheControlModule_1 = __decorate([
+    Module({})
+], CacheControlModule);
+export { CacheControlModule };
+//# sourceMappingURL=cache-control.module.js.map

package/dist/cache-control.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-control.module.js","sourceRoot":"","sources":["../src/cache-control.module.ts"],"names":[],"mappings":";;;;;;;AAAA,OAAO,EAAsB,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAGvE;;;;GAIG;AAEI,IAAM,kBAAkB,0BAAxB,MAAM,kBAAkB;IAC3B,MAAM,CAAC,OAAO,CAAC,OAAkC;QAC7C,OAAO;YACH,MAAM,EAAE,oBAAkB;YAC1B,SAAS,EAAE;gBACP,EAAE,OAAO,EAAE,qBAAqB,EAAE,QAAQ,EAAE,OAAO,EAAE;gBACrD,EAAE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,sBAAsB,EAAE;aACjE;SACJ,CAAC;IACN,CAAC;CACJ,CAAA;AAVY,kBAAkB;IAD9B,MAAM,CAAC,EAAE,CAAC;GACE,kBAAkB,CAU9B"}

package/dist/cache-control.util.d.ts

@@ -0,0 +1,18 @@
+import type { CacheContext } from './types/cache-context.type.js';
+import type { CacheDecision, CachePolicy } from './types/cache-policy.type.js';
+/**
+ * Reads the request directives a lookup honours from a `Cache-Control`
+ * header (RFC 9111 §5.2.1): `no-cache`, `no-store`, `max-age=N`,
+ * `only-if-cached`. Directive names are case-insensitive; unknown
+ * directives and an invalid `max-age` are ignored, as the RFC asks.
+ */
+export declare function parseCacheControl(header: string | string[] | undefined): CachePolicy;
+/**
+ * The one rule of a lookup served from a store. A stored row answers unless
+ * the request says `no-cache` or the row is older than its `max-age`;
+ * otherwise the provider is asked and its answer stored, unless `no-store`.
+ * `only-if-cached` never asks the provider: without a usable row it refuses.
+ */
+export declare function decideCache(policy: CachePolicy, storedAt: Date | null, now?: number): CacheDecision;
+/** A request's cache context: decides with `decideCache` and records every decision. */
+export declare function createCacheContext(policy: CachePolicy, now?: () => number): CacheContext;

package/dist/cache-control.util.js

@@ -0,0 +1,94 @@
+/**
+ * Reads the request directives a lookup honours from a `Cache-Control`
+ * header (RFC 9111 §5.2.1): `no-cache`, `no-store`, `max-age=N`,
+ * `only-if-cached`. Directive names are case-insensitive; unknown
+ * directives and an invalid `max-age` are ignored, as the RFC asks.
+ */
+export function parseCacheControl(header) {
+    const text = Array.isArray(header) ? header.join(',') : (header ?? '');
+    const directives = new Map();
+    for (const part of splitDirectives(text)) {
+        const equals = part.indexOf('=');
+        const name = (equals < 0 ? part : part.slice(0, equals)).trim().toLowerCase();
+        const value = equals < 0 ? undefined : unquote(part.slice(equals + 1).trim());
+        if (name)
+            directives.set(name, value);
+    }
+    const maxAge = deltaSeconds(directives.get('max-age'));
+    return {
+        noCache: directives.has('no-cache'),
+        noStore: directives.has('no-store'),
+        onlyIfCached: directives.has('only-if-cached'),
+        ...(maxAge !== undefined && { maxAge }),
+    };
+}
+// RFC 9111 §1.2.2: a value past the largest one representable counts as 2^31.
+const MAX_DELTA_SECONDS = 2_147_483_648;
+/** `delta-seconds` (decimal digits only, RFC 9111 §1.2.2); anything else is no value. */
+function deltaSeconds(value) {
+    if (value === undefined || !/^\d+$/.test(value))
+        return undefined;
+    return Math.min(Number(value), MAX_DELTA_SECONDS);
+}
+/**
+ * The one rule of a lookup served from a store. A stored row answers unless
+ * the request says `no-cache` or the row is older than its `max-age`;
+ * otherwise the provider is asked and its answer stored, unless `no-store`.
+ * `only-if-cached` never asks the provider: without a usable row it refuses.
+ */
+export function decideCache(policy, storedAt, now = Date.now()) {
+    const ageSeconds = storedAt ? Math.max(0, Math.floor((now - storedAt.getTime()) / 1000)) : 0;
+    const stale = policy.maxAge !== undefined && ageSeconds > policy.maxAge;
+    if (storedAt && !policy.noCache && !stale)
+        return { action: 'serve', ageSeconds };
+    if (policy.onlyIfCached)
+        return { action: 'refuse' };
+    const reason = !storedAt ? 'miss' : policy.noCache ? 'request' : 'stale';
+    return { action: 'fetch', reason, store: !policy.noStore };
+}
+/**
+ * The directives of a header, split on the commas outside quoted strings
+ * (RFC 9110 §5.6.4): `ext="a,only-if-cached"` stays one unknown directive.
+ */
+function splitDirectives(text) {
+    const parts = [];
+    let current = '';
+    let quoted = false;
+    let escaped = false;
+    for (const char of text) {
+        if (escaped)
+            escaped = false;
+        else if (quoted && char === '\\')
+            escaped = true;
+        else if (char === '"')
+            quoted = !quoted;
+        else if (char === ',' && !quoted) {
+            parts.push(current);
+            current = '';
+            continue;
+        }
+        current += char;
+    }
+    parts.push(current);
+    return parts;
+}
+/** A quoted-string argument without its quotes and escapes; a token as is. */
+function unquote(value) {
+    if (!(value.length >= 2 && value.startsWith('"') && value.endsWith('"')))
+        return value;
+    return value.slice(1, -1).replace(/\\(.)/g, '$1');
+}
+/** A request's cache context: decides with `decideCache` and records every decision. */
+export function createCacheContext(policy, now = Date.now) {
+    const decisions = [];
+    return {
+        policy,
+        decisions,
+        decide(storedAt) {
+            const decision = decideCache(policy, storedAt, now());
+            decisions.push(decision);
+            return decision;
+        },
+    };
+}
+//# sourceMappingURL=cache-control.util.js.map

package/dist/cache-control.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-control.util.js","sourceRoot":"","sources":["../src/cache-control.util.ts"],"names":[],"mappings":"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"}

package/dist/cache-status.interceptor.d.ts

@@ -0,0 +1,18 @@
+import { type CallHandler, type ExecutionContext, type NestInterceptor } from '@nestjs/common';
+import { HttpAdapterHost } from '@nestjs/core';
+import { type Observable } from 'rxjs';
+import type { CacheControlModuleOptions } from './types/cache-control-options.type.js';
+/**
+ * Writes `Cache-Status` and `Age` from the decisions the service took, on a
+ * success and on an error alike (a refused `only-if-cached` is a 504).
+ * Headers go through the Nest HTTP adapter, so Express and Fastify behave
+ * the same. A failed request never says `stored`: a fetch that threw did not
+ * write. Routes that never read `@RequestCachePolicy()` get nothing.
+ */
+export declare class CacheStatusInterceptor implements NestInterceptor {
+    private readonly options;
+    private readonly adapterHost;
+    constructor(options: CacheControlModuleOptions, adapterHost: HttpAdapterHost);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+    private write;
+}

package/dist/cache-status.interceptor.js

@@ -0,0 +1,59 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable, } from '@nestjs/common';
+import { HttpAdapterHost } from '@nestjs/core';
+import { catchError, tap, throwError } from 'rxjs';
+import { CACHE_CONTEXT, CACHE_CONTROL_OPTIONS } from './cache-control.constants.js';
+import { responseCacheHeaders } from './cache-status.util.js';
+/**
+ * Writes `Cache-Status` and `Age` from the decisions the service took, on a
+ * success and on an error alike (a refused `only-if-cached` is a 504).
+ * Headers go through the Nest HTTP adapter, so Express and Fastify behave
+ * the same. A failed request never says `stored`: a fetch that threw did not
+ * write. Routes that never read `@RequestCachePolicy()` get nothing.
+ */
+let CacheStatusInterceptor = class CacheStatusInterceptor {
+    options;
+    adapterHost;
+    constructor(options, adapterHost) {
+        this.options = options;
+        this.adapterHost = adapterHost;
+    }
+    intercept(context, next) {
+        return next.handle().pipe(tap(() => {
+            this.write(context, true);
+        }), catchError((error) => {
+            this.write(context, false);
+            return throwError(() => error);
+        }));
+    }
+    write(context, succeeded) {
+        const http = context.switchToHttp();
+        const decisions = http.getRequest()[CACHE_CONTEXT]?.decisions ?? [];
+        const headers = responseCacheHeaders(this.options.name, decisions, succeeded);
+        const { httpAdapter } = this.adapterHost;
+        const response = http.getResponse();
+        if (!headers || httpAdapter.isHeadersSent(response))
+            return;
+        httpAdapter.setHeader(response, 'Cache-Status', headers['Cache-Status']);
+        if (headers.Age !== undefined)
+            httpAdapter.setHeader(response, 'Age', headers.Age);
+    }
+};
+CacheStatusInterceptor = __decorate([
+    Injectable(),
+    __param(0, Inject(CACHE_CONTROL_OPTIONS)),
+    __metadata("design:paramtypes", [Object, HttpAdapterHost])
+], CacheStatusInterceptor);
+export { CacheStatusInterceptor };
+//# sourceMappingURL=cache-status.interceptor.js.map

package/dist/cache-status.interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-status.interceptor.js","sourceRoot":"","sources":["../src/cache-status.interceptor.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,OAAO,EAGH,MAAM,EACN,UAAU,GAEb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAmB,GAAG,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAEpE,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAQ9D;;;;;;GAMG;AAEI,IAAM,sBAAsB,GAA5B,MAAM,sBAAsB;IAEqB;IAC/B;IAFrB,YACoD,OAAkC,EACjE,WAA4B;QADG,YAAO,GAAP,OAAO,CAA2B;QACjE,gBAAW,GAAX,WAAW,CAAiB;IAC9C,CAAC;IAEJ,SAAS,CAAC,OAAyB,EAAE,IAAiB;QAClD,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CACrB,GAAG,CAAC,GAAG,EAAE;YACL,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC9B,CAAC,CAAC,EACF,UAAU,CAAC,CAAC,KAAc,EAAE,EAAE;YAC1B,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YAC3B,OAAO,UAAU,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;QACnC,CAAC,CAAC,CACL,CAAC;IACN,CAAC;IAEO,KAAK,CAAC,OAAyB,EAAE,SAAkB;QACvD,MAAM,IAAI,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;QACpC,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,EAAgB,CAAC,aAAa,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;QAClF,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QAC9E,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC;QACzC,MAAM,QAAQ,GAAY,IAAI,CAAC,WAAW,EAAE,CAAC;QAC7C,IAAI,CAAC,OAAO,IAAI,WAAW,CAAC,aAAa,CAAC,QAAQ,CAAC;YAAE,OAAO;QAE5D,WAAW,CAAC,SAAS,CAAC,QAAQ,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;QACzE,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS;YAAE,WAAW,CAAC,SAAS,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACvF,CAAC;CACJ,CAAA;AA7BY,sBAAsB;IADlC,UAAU,EAAE;IAGJ,WAAA,MAAM,CAAC,qBAAqB,CAAC,CAAA;6CACA,eAAe;GAHxC,sBAAsB,CA6BlC"}

package/dist/cache-status.util.d.ts

@@ -0,0 +1,20 @@
+import type { CacheDecision } from './types/cache-policy.type.js';
+/** The response headers describing one decision. */
+export interface CacheStatusHeaders {
+    'Cache-Status': string;
+    Age?: string;
+}
+/**
+ * `Cache-Status` (RFC 9211) for one decision, plus `Age` (RFC 9111 §5.1) on
+ * a hit: `hit`; `fwd=miss|request|stale`, with `stored` only when the answer
+ * was written (`stored: false` for a request that failed after deciding); a
+ * refusal carries no `fwd` because nothing was forwarded.
+ */
+export declare function cacheStatusHeaders(name: string, decision: CacheDecision, stored?: boolean): CacheStatusHeaders;
+/**
+ * The headers of a whole response: those of its decision when it took one.
+ * Several lookups (a batch) describe their items in the body instead: one
+ * header cannot tell them apart. `succeeded` false (the request failed)
+ * drops `stored`: whatever the decision allowed, nothing was written.
+ */
+export declare function responseCacheHeaders(name: string, decisions: readonly CacheDecision[], succeeded?: boolean): CacheStatusHeaders | undefined;

package/dist/cache-status.util.js

@@ -0,0 +1,31 @@
+/**
+ * `Cache-Status` (RFC 9211) for one decision, plus `Age` (RFC 9111 §5.1) on
+ * a hit: `hit`; `fwd=miss|request|stale`, with `stored` only when the answer
+ * was written (`stored: false` for a request that failed after deciding); a
+ * refusal carries no `fwd` because nothing was forwarded.
+ */
+export function cacheStatusHeaders(name, decision, stored = true) {
+    switch (decision.action) {
+        case 'serve':
+            return { 'Cache-Status': `${name}; hit`, Age: String(decision.ageSeconds) };
+        case 'fetch': {
+            const written = decision.store && stored ? '; stored' : '';
+            return { 'Cache-Status': `${name}; fwd=${decision.reason}${written}` };
+        }
+        case 'refuse':
+            return { 'Cache-Status': `${name}; detail=not-cached` };
+    }
+}
+/**
+ * The headers of a whole response: those of its decision when it took one.
+ * Several lookups (a batch) describe their items in the body instead: one
+ * header cannot tell them apart. `succeeded` false (the request failed)
+ * drops `stored`: whatever the decision allowed, nothing was written.
+ */
+export function responseCacheHeaders(name, decisions, succeeded = true) {
+    const [decision, ...others] = decisions;
+    return decision && others.length === 0
+        ? cacheStatusHeaders(name, decision, succeeded)
+        : undefined;
+}
+//# sourceMappingURL=cache-status.util.js.map

package/dist/cache-status.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-status.util.js","sourceRoot":"","sources":["../src/cache-status.util.ts"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAC9B,IAAY,EACZ,QAAuB,EACvB,MAAM,GAAG,IAAI;IAEb,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;QACtB,KAAK,OAAO;YACR,OAAO,EAAE,cAAc,EAAE,GAAG,IAAI,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAChF,KAAK,OAAO,CAAC,CAAC,CAAC;YACX,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,IAAI,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3D,OAAO,EAAE,cAAc,EAAE,GAAG,IAAI,SAAS,QAAQ,CAAC,MAAM,GAAG,OAAO,EAAE,EAAE,CAAC;QAC3E,CAAC;QACD,KAAK,QAAQ;YACT,OAAO,EAAE,cAAc,EAAE,GAAG,IAAI,qBAAqB,EAAE,CAAC;IAChE,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAChC,IAAY,EACZ,SAAmC,EACnC,SAAS,GAAG,IAAI;IAEhB,MAAM,CAAC,QAAQ,EAAE,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC;IACxC,OAAO,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAClC,CAAC,CAAC,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,CAAC;QAC/C,CAAC,CAAC,SAAS,CAAC;AACpB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { ApiCacheControl } from './api-cache-control.decorator.js';
+export { NOT_CACHED } from './cache-control.constants.js';
+export { CacheControlModule } from './cache-control.module.js';
+export { createCacheContext, decideCache, parseCacheControl } from './cache-control.util.js';
+export { CacheStatusInterceptor } from './cache-status.interceptor.js';
+export { cacheStatusHeaders, type CacheStatusHeaders } from './cache-status.util.js';
+export { NotCachedException } from './not-cached.exception.js';
+export { RequestCachePolicy } from './request-cache-policy.decorator.js';
+export type { CacheContext } from './types/cache-context.type.js';
+export type { CacheControlModuleOptions } from './types/cache-control-options.type.js';
+export type { CacheDecision, CachePolicy, FetchReason } from './types/cache-policy.type.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export { ApiCacheControl } from './api-cache-control.decorator.js';
+export { NOT_CACHED } from './cache-control.constants.js';
+export { CacheControlModule } from './cache-control.module.js';
+export { createCacheContext, decideCache, parseCacheControl } from './cache-control.util.js';
+export { CacheStatusInterceptor } from './cache-status.interceptor.js';
+export { cacheStatusHeaders } from './cache-status.util.js';
+export { NotCachedException } from './not-cached.exception.js';
+export { RequestCachePolicy } from './request-cache-policy.decorator.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC7F,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAA2B,MAAM,wBAAwB,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC"}

package/dist/not-cached.exception.d.ts

@@ -0,0 +1,9 @@
+import { GatewayTimeoutException } from '@nestjs/common';
+/**
+ * What an `only-if-cached` lookup answers without a usable row: 504, as
+ * RFC 9111 §5.2.1.7 asks, with `code: NOT_CACHED` to tell it from a gateway
+ * that timed out.
+ */
+export declare class NotCachedException extends GatewayTimeoutException {
+    constructor(message?: string);
+}

package/dist/not-cached.exception.js

@@ -0,0 +1,13 @@
+import { GatewayTimeoutException } from '@nestjs/common';
+import { NOT_CACHED } from './cache-control.constants.js';
+/**
+ * What an `only-if-cached` lookup answers without a usable row: 504, as
+ * RFC 9111 §5.2.1.7 asks, with `code: NOT_CACHED` to tell it from a gateway
+ * that timed out.
+ */
+export class NotCachedException extends GatewayTimeoutException {
+    constructor(message = 'Not in the store: only-if-cached forbids asking the provider.') {
+        super({ code: NOT_CACHED, message });
+    }
+}
+//# sourceMappingURL=not-cached.exception.js.map

package/dist/not-cached.exception.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-cached.exception.js","sourceRoot":"","sources":["../src/not-cached.exception.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAEzD,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE1D;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,uBAAuB;IAC3D,YAAY,OAAO,GAAG,+DAA+D;QACjF,KAAK,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;IACzC,CAAC;CACJ"}

package/dist/request-cache-policy.decorator.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The request's `Cache-Control` as a `CacheContext` for the service. The
+ * context stays on the request, where `CacheStatusInterceptor` reads the
+ * decisions to write `Cache-Status` and `Age`.
+ */
+export declare const RequestCachePolicy: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/dist/request-cache-policy.decorator.js

@@ -0,0 +1,14 @@
+import { createParamDecorator } from '@nestjs/common';
+import { CACHE_CONTEXT } from './cache-control.constants.js';
+import { createCacheContext, parseCacheControl } from './cache-control.util.js';
+/**
+ * The request's `Cache-Control` as a `CacheContext` for the service. The
+ * context stays on the request, where `CacheStatusInterceptor` reads the
+ * decisions to write `Cache-Status` and `Age`.
+ */
+export const RequestCachePolicy = createParamDecorator((_data, context) => {
+    const request = context.switchToHttp().getRequest();
+    request[CACHE_CONTEXT] ??= createCacheContext(parseCacheControl(request.headers['cache-control']));
+    return request[CACHE_CONTEXT];
+});
+//# sourceMappingURL=request-cache-policy.decorator.js.map

package/dist/request-cache-policy.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-cache-policy.decorator.js","sourceRoot":"","sources":["../src/request-cache-policy.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAyB,MAAM,gBAAgB,CAAC;AAE7E,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAQhF;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAClD,CAAC,KAAc,EAAE,OAAyB,EAAgB,EAAE;IACxD,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,UAAU,EAAgB,CAAC;IAClE,OAAO,CAAC,aAAa,CAAC,KAAK,kBAAkB,CACzC,iBAAiB,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CACtD,CAAC;IACF,OAAO,OAAO,CAAC,aAAa,CAAC,CAAC;AAClC,CAAC,CACJ,CAAC"}

package/dist/types/cache-context.type.d.ts

@@ -0,0 +1,14 @@
+import type { CacheDecision, CachePolicy } from './cache-policy.type.js';
+/**
+ * The cache policy of one request, handed to the service by
+ * `@RequestCachePolicy()`. Every `decide` is recorded: the interceptor turns
+ * the decisions into `Cache-Status` and `Age`, so the service never touches
+ * the response.
+ */
+export interface CacheContext {
+    readonly policy: CachePolicy;
+    /** Rules on one stored row (`null` when there is none) and records the decision. */
+    decide(storedAt: Date | null): CacheDecision;
+    /** The decisions taken so far, in order: one per lookup of the request. */
+    readonly decisions: readonly CacheDecision[];
+}

package/dist/types/cache-context.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cache-context.type.js.map

package/dist/types/cache-context.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-context.type.js","sourceRoot":"","sources":["../../src/types/cache-context.type.ts"],"names":[],"mappings":""}

package/dist/types/cache-control-options.type.d.ts

@@ -0,0 +1,4 @@
+export interface CacheControlModuleOptions {
+    /** The cache's name in `Cache-Status` (RFC 9211), e.g. the service name. */
+    name: string;
+}

package/dist/types/cache-control-options.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cache-control-options.type.js.map

package/dist/types/cache-control-options.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-control-options.type.js","sourceRoot":"","sources":["../../src/types/cache-control-options.type.ts"],"names":[],"mappings":""}

package/dist/types/cache-policy.type.d.ts

@@ -0,0 +1,24 @@
+/** The request directives of RFC 9111 a lookup honours; any other directive is ignored. */
+export interface CachePolicy {
+    /** `no-cache`: never answer from the store without asking the provider. */
+    noCache: boolean;
+    /** `no-store`: never write the provider's answer to the store. */
+    noStore: boolean;
+    /** `only-if-cached`: never ask the provider; without a usable row, refuse. */
+    onlyIfCached: boolean;
+    /** `max-age=N`: a stored row older than N seconds is not usable. */
+    maxAge?: number;
+}
+/** Why a lookup goes to the provider: no row, a `no-cache` request, or a row past `max-age`. */
+export type FetchReason = 'miss' | 'request' | 'stale';
+/** What a lookup does for one stored row, as `decideCache` rules it. */
+export type CacheDecision = {
+    action: 'serve';
+    ageSeconds: number;
+} | {
+    action: 'fetch';
+    reason: FetchReason;
+    store: boolean;
+} | {
+    action: 'refuse';
+};

package/dist/types/cache-policy.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cache-policy.type.js.map

package/dist/types/cache-policy.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-policy.type.js","sourceRoot":"","sources":["../../src/types/cache-policy.type.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,48 @@
 {
-  "name": "@seta-labs/nestjs-cache-control",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@seta-labs/nestjs-cache-control",
+    "version": "0.1.0",
+    "description": "RFC 9111 request cache directives for NestJS lookups served from a store: no-cache, no-store, max-age and only-if-cached decided in one place, Cache-Status and Age on the response, a 504 for a refused lookup",
+    "license": "UNLICENSED",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Seta-Labs/node-common.git",
+        "directory": "packages/nestjs-cache-control"
+    },
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "test": "vitest run",
+        "typecheck": "tsc -p tsconfig.json --noEmit"
+    },
+    "peerDependencies": {
+        "@nestjs/common": "^11.0.0 || ^12.0.0",
+        "@nestjs/core": "^11.0.0 || ^12.0.0",
+        "@nestjs/swagger": "^11.0.0 || ^12.0.0",
+        "rxjs": "^7.0.0"
+    },
+    "devDependencies": {
+        "@nestjs/common": "^12.1.2",
+        "@nestjs/core": "^12.1.2",
+        "@nestjs/platform-express": "^12.1.2",
+        "@nestjs/swagger": "^12.0.2",
+        "@types/node": "^26.6.5",
+        "reflect-metadata": "^0.2.2",
+        "rxjs": "^7.8.1",
+        "typescript": "^6.0.3",
+        "vitest": "^5.0.3"
+    }
+}