@dcsv-io/d2-caching-abstractions 0.1.1

package/dist/i-cache-broadcast.d.ts

@@ -0,0 +1,47 @@
+import type { D2Result } from "@dcsv-io/d2-result";
+/**
+ * Write surface that publishes invalidation messages via a registered
+ * {@link ICacheInvalidationBackplane} after the underlying write
+ * completes. Subscribers (typically tiered caches in other instances)
+ * drop their L1 copy of the affected key on receipt.
+ *
+ * Implemented by both {@link IDistributedCache} (so callers writing
+ * directly to L2 can still bust other instances' L1) and
+ * {@link ITieredCache} (which writes both tiers and broadcasts in one
+ * call).
+ *
+ * **Registration error carve-out:** `*AndBroadcast*` methods **throw**
+ * (not `D2Result`) when no `ICacheInvalidationBackplane` was registered
+ * with the cache. Registration error is a construction-time / wiring
+ * concern, not a per-call failure. Use the plain `set` / `remove` if
+ * you don't intend to broadcast.
+ */
+export interface ICacheBroadcast {
+    /**
+     * Writes a value AND publishes an invalidation message via the
+     * registered {@link ICacheInvalidationBackplane}.
+     *
+     * @throws When no backplane was registered with the cache.
+     */
+    setAndBroadcast<T>(key: string, value: T, expirationMs?: number, signal?: AbortSignal): Promise<D2Result>;
+    /**
+     * Bulk-write counterpart of {@link setAndBroadcast}.
+     *
+     * @throws When no backplane was registered with the cache.
+     */
+    setManyAndBroadcast<T>(entries: ReadonlyMap<string, T>, expirationMs?: number, signal?: AbortSignal): Promise<D2Result>;
+    /**
+     * Removes a key AND publishes an invalidation message so other
+     * instances drop their L1 copies.
+     *
+     * @throws When no backplane was registered with the cache.
+     */
+    removeAndBroadcast(key: string, signal?: AbortSignal): Promise<D2Result>;
+    /**
+     * Bulk-remove + broadcast invalidation per key.
+     *
+     * @throws When no backplane was registered with the cache.
+     */
+    removeManyAndBroadcast(keys: readonly string[], signal?: AbortSignal): Promise<D2Result>;
+}
+//# sourceMappingURL=i-cache-broadcast.d.ts.map

package/dist/i-cache-broadcast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-cache-broadcast.d.ts","sourceRoot":"","sources":["../src/i-cache-broadcast.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,eAAe,CAAC,CAAC,EACf,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,EACR,YAAY,CAAC,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,QAAQ,CAAC,CAAC;IAErB;;;;OAIG;IACH,mBAAmB,CAAC,CAAC,EACnB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,EAC/B,YAAY,CAAC,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,QAAQ,CAAC,CAAC;IAErB;;;;;OAKG;IACH,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEzE;;;;OAIG;IACH,sBAAsB,CACpB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,QAAQ,CAAC,CAAC;CACtB"}

package/dist/i-cache-broadcast.js

@@ -0,0 +1,5 @@
+// -----------------------------------------------------------------------
+// Copyright (c) DCSV. Licensed under the Apache License, Version 2.0.
+// -----------------------------------------------------------------------
+export {};
+//# sourceMappingURL=i-cache-broadcast.js.map

package/dist/i-cache-broadcast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-cache-broadcast.js","sourceRoot":"","sources":["../src/i-cache-broadcast.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,sEAAsE;AACtE,0EAA0E"}

package/dist/i-cache-invalidation-backplane.d.ts

@@ -0,0 +1,73 @@
+import type { D2Result } from "@dcsv-io/d2-result";
+/**
+ * Pub/sub backplane for cross-instance cache invalidation. Publishers
+ * fire when a caller uses one of the `*AndBroadcast*` variants on
+ * {@link ITieredCache} or {@link IDistributedCache}, or when any code
+ * calls {@link publishInvalidation} directly. Subscribers (typically
+ * tiered caches in other instances) receive the key and act on it —
+ * usually by dropping the named entry from their L1.
+ *
+ * Extends {@link AsyncDisposable}. Runtime: Node ≥ 20 (global
+ * `Symbol.asyncDispose`). Package `lib` includes `ESNext.Disposable`
+ * so the types resolve.
+ *
+ * **Contract (twin of .NET `ICacheInvalidationBackplane` remarks):**
+ *
+ * 1. **Everyone acts** — no sender-ID filter; the publisher receives
+ *    its own messages.
+ * 2. **At-most-once** delivery (missed message → next read hits L2).
+ * 3. **Dispose unsubscribes** — disposing a subscription **removes that
+ *    handler from fan-out** and **stops further invalidation key
+ *    delivery** to it (primary .NET Subscribe law). Signal abort alone
+ *    is **not** sufficient — unsubscribe is the delivery-stop guarantee.
+ * 4. **Signal-on-dispose** — the handler's `AbortSignal` is aborted when
+ *    the **subscription** is disposed (accompanies unsubscribe; does not
+ *    replace it).
+ * 5. **Handler isolation** — one handler throw must not break delivery
+ *    to other handlers.
+ * 6. **Multi-sub independence** — each `subscribe` returns its own
+ *    disposable; subscriptions are independent.
+ * 7. **Dispose idempotency** — disposing a subscription (or the
+ *    backplane) more than once is safe (no throw).
+ * 8. **Backplane dispose cascade** — disposing the backplane tears down
+ *    shared provider resources, unsubscribes remaining handlers, and
+ *    cancels in-flight handler work.
+ *
+ * Provider-agnostic — Redis pub/sub is the default implementation, but
+ * the same interface can wrap Postgres LISTEN/NOTIFY, an in-process
+ * channel for tests, etc.
+ */
+export interface ICacheInvalidationBackplane extends AsyncDisposable {
+    /**
+     * Subscribes to receive invalidation messages. The handler is invoked
+     * once per received key (including keys this instance published).
+     * Implementations isolate errors per handler — one handler throwing
+     * does not affect delivery to other handlers.
+     *
+     * @param handler - Callback invoked for every received invalidation
+     *   key. Receives the key and an optional `AbortSignal` tied to
+     *   subscription lifetime (aborted when the returned subscription is
+     *   disposed).
+     * @returns Disposable subscription. Dispose to **unsubscribe** (stop
+     *   further key delivery to this handler); typically held as a field
+     *   on the subscriber and disposed in the subscriber's own disposal
+     *   so the subscription lifetime matches the subscriber.
+     */
+    subscribe(handler: (key: string, signal?: AbortSignal) => void | Promise<void>): AsyncDisposable;
+    /**
+     * Publishes an invalidation message for a single key. Every
+     * subscriber (across every connected instance, including this one)
+     * receives the key.
+     *
+     * @returns `ok`; failure on backplane error.
+     */
+    publishInvalidation(key: string, signal?: AbortSignal): Promise<D2Result>;
+    /**
+     * Bulk-publish counterpart of {@link publishInvalidation}.
+     * Implementations may pipeline the publishes for fewer round-trips.
+     *
+     * @returns `ok`; failure on backplane error.
+     */
+    publishInvalidationMany(keys: readonly string[], signal?: AbortSignal): Promise<D2Result>;
+}
+//# sourceMappingURL=i-cache-invalidation-backplane.d.ts.map

package/dist/i-cache-invalidation-backplane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-cache-invalidation-backplane.d.ts","sourceRoot":"","sources":["../src/i-cache-invalidation-backplane.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,WAAW,2BAA4B,SAAQ,eAAe;IAClE;;;;;;;;;;;;;;OAcG;IACH,SAAS,CACP,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACnE,eAAe,CAAC;IAEnB;;;;;;OAMG;IACH,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE1E;;;;;OAKG;IACH,uBAAuB,CACrB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,QAAQ,CAAC,CAAC;CACtB"}

package/dist/i-cache-invalidation-backplane.js

@@ -0,0 +1,5 @@
+// -----------------------------------------------------------------------
+// Copyright (c) DCSV. Licensed under the Apache License, Version 2.0.
+// -----------------------------------------------------------------------
+export {};
+//# sourceMappingURL=i-cache-invalidation-backplane.js.map

package/dist/i-cache-invalidation-backplane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-cache-invalidation-backplane.js","sourceRoot":"","sources":["../src/i-cache-invalidation-backplane.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,sEAAsE;AACtE,0EAA0E"}

package/dist/i-cache-serializer.d.ts

@@ -0,0 +1,35 @@
+import type { D2Result } from "@dcsv-io/d2-result";
+/**
+ * Pluggable serialization seam for distributed caches. Local caches
+ * store objects directly and do not need this. This package owns the
+ * port only; a default JSON implementation is part of the
+ * `@dcsv-io/d2-caching-distributed-redis` package surface. Provider-specific
+ * impls may swap in MessagePack, Protobuf, etc., for size or perf wins.
+ *
+ * Impl failure codes (not defined here — reuse existing catalogs when
+ * implementing): `COULD_NOT_BE_SERIALIZED` /
+ * `COULD_NOT_BE_DESERIALIZED`.
+ */
+export interface ICacheSerializer {
+    /**
+     * Stable identifier for the serialization format (free string, e.g.
+     * `"application/json"`). Allows mixed-serializer DLQs / archive
+     * blobs to round-trip safely.
+     */
+    readonly contentType: string;
+    /**
+     * Serializes `value` to bytes.
+     *
+     * @returns `ok(bytes)`; failure with a serialize error code on
+     *   serializer error.
+     */
+    serialize<T>(value: T): D2Result<Uint8Array>;
+    /**
+     * Deserializes `bytes` back to a value.
+     *
+     * @returns `ok(value)`; failure with a deserialize error code on
+     *   deserializer error.
+     */
+    deserialize<T>(bytes: Uint8Array): D2Result<T>;
+}
+//# sourceMappingURL=i-cache-serializer.d.ts.map

package/dist/i-cache-serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-cache-serializer.d.ts","sourceRoot":"","sources":["../src/i-cache-serializer.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;;;;OAKG;IACH,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;IAE7C;;;;;OAKG;IACH,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;CAChD"}

package/dist/i-cache-serializer.js

@@ -0,0 +1,5 @@
+// -----------------------------------------------------------------------
+// Copyright (c) DCSV. Licensed under the Apache License, Version 2.0.
+// -----------------------------------------------------------------------
+export {};
+//# sourceMappingURL=i-cache-serializer.js.map

package/dist/i-cache-serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-cache-serializer.js","sourceRoot":"","sources":["../src/i-cache-serializer.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,sEAAsE;AACtE,0EAA0E"}

package/dist/i-cache-set.d.ts

@@ -0,0 +1,59 @@
+import type { D2Result } from "@dcsv-io/d2-result";
+/**
+ * Distributed-set primitives — add-to-set, cardinality, membership.
+ * Maps to Redis SADD / SCARD / SREM / SISMEMBER. Only on
+ * {@link IDistributedCache}; per-process set-cardinality has no
+ * realistic use case (it's a single-instance counter that can't
+ * aggregate across the cluster), and tiered composition would silently
+ * hide the cluster-wide nature of the operation.
+ *
+ * The motivating use case is rate-limiting "fingerprint too common"
+ * detection: track distinct IPs ever observed for a given fingerprint,
+ * compare cardinality against a threshold to decide whether the
+ * fingerprint is shared widely enough to be unreliable. Other
+ * plausible uses include distinct-user counts per feature flag,
+ * active-session tracking by org, and any bounded-cardinality
+ * "have I seen X for Y" check.
+ *
+ * **Counter width:** `number` (not `bigint`) is an intentional TS
+ * ergonomic delta vs .NET `long`. Implementations must stay within
+ * `Number.MAX_SAFE_INTEGER`.
+ */
+export interface ICacheSet {
+    /**
+     * Adds a member to the set at `key`. The set is created on first
+     * add.
+     *
+     * **TTL-on-create-only:** optional `expirationMs` is applied **only
+     * when the set is created**; subsequent adds on an existing set
+     * **preserve the existing TTL**.
+     *
+     * @returns `ok(true)` if the member was newly added. `ok(false)` if
+     *   the member already existed in the set. Failure on backing-store
+     *   error.
+     */
+    setAdd(key: string, member: string, expirationMs?: number, signal?: AbortSignal): Promise<D2Result<boolean>>;
+    /**
+     * Returns the cardinality (number of distinct members) of the set at
+     * `key`. Absent set → `ok(0)`.
+     *
+     * @returns `ok(count)`. Failure on backing-store error.
+     */
+    setCardinality(key: string, signal?: AbortSignal): Promise<D2Result<number>>;
+    /**
+     * Removes a member from the set at `key`. **Idempotent** — succeeds
+     * whether the member existed or not.
+     *
+     * @returns `ok(true)` if the member was present and removed.
+     *   `ok(false)` if the member was absent. Failure on backing-store
+     *   error.
+     */
+    setRemove(key: string, member: string, signal?: AbortSignal): Promise<D2Result<boolean>>;
+    /**
+     * Returns whether `member` is in the set at `key`.
+     *
+     * @returns `ok(true|false)`. Failure on backing-store error.
+     */
+    setContains(key: string, member: string, signal?: AbortSignal): Promise<D2Result<boolean>>;
+}
+//# sourceMappingURL=i-cache-set.d.ts.map

package/dist/i-cache-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-cache-set.d.ts","sourceRoot":"","sources":["../src/i-cache-set.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;;;;OAWG;IACH,MAAM,CACJ,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IAE9B;;;;;OAKG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAE7E;;;;;;;OAOG;IACH,SAAS,CACP,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IAE9B;;;;OAIG;IACH,WAAW,CACT,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;CAC/B"}

package/dist/i-cache-set.js

@@ -0,0 +1,5 @@
+// -----------------------------------------------------------------------
+// Copyright (c) DCSV. Licensed under the Apache License, Version 2.0.
+// -----------------------------------------------------------------------
+export {};
+//# sourceMappingURL=i-cache-set.js.map

package/dist/i-cache-set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-cache-set.js","sourceRoot":"","sources":["../src/i-cache-set.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,sEAAsE;AACtE,0EAA0E"}

package/dist/i-distributed-cache.d.ts

@@ -0,0 +1,25 @@
+import type { ICacheAtomic } from "./i-cache-atomic.js";
+import type { ICacheBasic } from "./i-cache-basic.js";
+import type { ICacheBroadcast } from "./i-cache-broadcast.js";
+import type { ICacheSet } from "./i-cache-set.js";
+/**
+ * Cluster-scoped cache backed by a remote store (e.g. Redis). Atomic
+ * primitives coordinate cluster-wide. The {@link ICacheBroadcast}
+ * surface coordinates with tiered consumers in other instances so
+ * their L1 entries get busted in lockstep.
+ *
+ * Composes {@link ICacheBasic} + {@link ICacheAtomic} +
+ * {@link ICacheBroadcast} + {@link ICacheSet}.
+ *
+ * **Marker vs {@link ITieredCache}:** shared building blocks
+ * (Basic + Atomic + Broadcast) are method-identical. **`ICacheSet` is
+ * only on `IDistributedCache`** (not full structural identity). The
+ * marker name carries behavioral intent at the dependency site: reading
+ * `IDistributedCache` tells you the cache talks to the remote store on
+ * every read (no L1), so freshness matters more than read speed for
+ * this consumer (e.g. rate-limit counters, lock state, ephemeral
+ * session data).
+ */
+export interface IDistributedCache extends ICacheBasic, ICacheAtomic, ICacheBroadcast, ICacheSet {
+}
+//# sourceMappingURL=i-distributed-cache.d.ts.map

package/dist/i-distributed-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-distributed-cache.d.ts","sourceRoot":"","sources":["../src/i-distributed-cache.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,iBACf,SAAQ,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,SAAS;CAAG"}

package/dist/i-distributed-cache.js

@@ -0,0 +1,5 @@
+// -----------------------------------------------------------------------
+// Copyright (c) DCSV. Licensed under the Apache License, Version 2.0.
+// -----------------------------------------------------------------------
+export {};
+//# sourceMappingURL=i-distributed-cache.js.map

package/dist/i-distributed-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-distributed-cache.js","sourceRoot":"","sources":["../src/i-distributed-cache.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,sEAAsE;AACtE,0EAA0E"}

package/dist/i-local-cache.d.ts

@@ -0,0 +1,18 @@
+import type { ICacheAtomic } from "./i-cache-atomic.js";
+import type { ICacheBasic } from "./i-cache-basic.js";
+/**
+ * Per-process in-memory cache. Atomic primitives operate at process
+ * scope — they do not coordinate across instances. There is no
+ * broadcast surface because nothing outside this process can observe
+ * local cache state.
+ *
+ * The interface name documents the cache scope at the dependency site.
+ * Reading `ILocalCache` at an inject site tells you, without looking
+ * at registration, that this cache lives in process memory and dies
+ * with the process.
+ *
+ * Composes {@link ICacheBasic} + {@link ICacheAtomic} only.
+ */
+export interface ILocalCache extends ICacheBasic, ICacheAtomic {
+}
+//# sourceMappingURL=i-local-cache.d.ts.map

package/dist/i-local-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-local-cache.d.ts","sourceRoot":"","sources":["../src/i-local-cache.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAY,SAAQ,WAAW,EAAE,YAAY;CAAG"}

package/dist/i-local-cache.js

@@ -0,0 +1,5 @@
+// -----------------------------------------------------------------------
+// Copyright (c) DCSV. Licensed under the Apache License, Version 2.0.
+// -----------------------------------------------------------------------
+export {};
+//# sourceMappingURL=i-local-cache.js.map

package/dist/i-local-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-local-cache.js","sourceRoot":"","sources":["../src/i-local-cache.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,sEAAsE;AACtE,0EAA0E"}

package/dist/i-tiered-cache.d.ts

@@ -0,0 +1,31 @@
+import type { ICacheAtomic } from "./i-cache-atomic.js";
+import type { ICacheBasic } from "./i-cache-basic.js";
+import type { ICacheBroadcast } from "./i-cache-broadcast.js";
+/**
+ * Composed L1 (in-process) + L2 (remote) cache. Reads check L1 first,
+ * fall through to L2 on miss, populate L1 with whatever L2 returned.
+ * Writes go L2-first — L1 only writes if L2 succeeded — so partial-write
+ * states are impossible and the result is binary (success or the L2
+ * failure bubbled up). Atomic primitives route through L2 (the source
+ * of truth) and invalidate / refresh L1 as a side effect.
+ *
+ * Composes {@link ICacheBasic} + {@link ICacheAtomic} +
+ * {@link ICacheBroadcast}. **Does NOT compose {@link ICacheSet}** —
+ * set primitives are cluster-only and tiered composition would
+ * silently hide their cluster-wide nature. Callers needing
+ * SADD/SCARD inject {@link IDistributedCache} directly.
+ *
+ * **Marker vs {@link IDistributedCache}:** shared building blocks
+ * (Basic + Atomic + Broadcast) are method-identical. The marker name
+ * carries behavioral intent: reading `ITieredCache` tells you reads
+ * served from L1 are sub-microsecond, L1 stays cluster-coherent via
+ * the broadcast backplane, and per-tier expirations are kept in
+ * lockstep so L1 never outlives L2.
+ *
+ * Use this for read-heavy entity data where freshness within a few
+ * seconds is acceptable. Prefer {@link IDistributedCache} when every
+ * read must hit the canonical store.
+ */
+export interface ITieredCache extends ICacheBasic, ICacheAtomic, ICacheBroadcast {
+}
+//# sourceMappingURL=i-tiered-cache.d.ts.map

package/dist/i-tiered-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-tiered-cache.d.ts","sourceRoot":"","sources":["../src/i-tiered-cache.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,YACf,SAAQ,WAAW,EAAE,YAAY,EAAE,eAAe;CAAG"}

package/dist/i-tiered-cache.js

@@ -0,0 +1,5 @@
+// -----------------------------------------------------------------------
+// Copyright (c) DCSV. Licensed under the Apache License, Version 2.0.
+// -----------------------------------------------------------------------
+export {};
+//# sourceMappingURL=i-tiered-cache.js.map

package/dist/i-tiered-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-tiered-cache.js","sourceRoot":"","sources":["../src/i-tiered-cache.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,sEAAsE;AACtE,0EAA0E"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export type { ICacheBasic } from "./i-cache-basic.js";
+export type { ICacheAtomic } from "./i-cache-atomic.js";
+export type { ICacheBroadcast } from "./i-cache-broadcast.js";
+export type { ICacheSet } from "./i-cache-set.js";
+export type { ILocalCache } from "./i-local-cache.js";
+export type { IDistributedCache } from "./i-distributed-cache.js";
+export type { ITieredCache } from "./i-tiered-cache.js";
+export type { ICacheInvalidationBackplane } from "./i-cache-invalidation-backplane.js";
+export type { ICacheSerializer } from "./i-cache-serializer.js";
+export type { LocalCacheOptions } from "./local-cache-options.js";
+export { LOCAL_CACHE_DEFAULTS, createLocalCacheOptions, } from "./local-cache-options.js";
+export { InputFailures } from "./input-failures.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AACvF,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EACL,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+// -----------------------------------------------------------------------
+// Copyright (c) DCSV. Licensed under the Apache License, Version 2.0.
+// -----------------------------------------------------------------------
+export { LOCAL_CACHE_DEFAULTS, createLocalCacheOptions, } from "./local-cache-options.js";
+export { InputFailures } from "./input-failures.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,0EAA0E;AAC1E,sEAAsE;AACtE,0EAA0E;AAY1E,OAAO,EACL,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/input-failures.d.ts

@@ -0,0 +1,27 @@
+import { type D2Result } from "@dcsv-io/d2-result";
+export declare const InputFailures: {
+    /**
+     * Builds a `D2Result` / `D2Result<T>` input failure for a missing
+     * (null / empty / falsey) required parameter.
+     *
+     * @param paramName - Parameter name (use a string literal matching
+     *   the call-site argument name).
+     */
+    required: {
+        (paramName: string): D2Result;
+        <T>(paramName: string): D2Result<T>;
+    };
+    /**
+     * Builds a `D2Result` / `D2Result<T>` input failure for a present but
+     * invalid parameter value (range, non-finite, non-safe-integer, etc.).
+     * Does **not** use `NOT_NULL_VIOLATION` — the value is present.
+     *
+     * @param paramName - Parameter name (use a string literal matching
+     *   the call-site argument name).
+     */
+    invalid: {
+        (paramName: string): D2Result;
+        <T>(paramName: string): D2Result<T>;
+    };
+};
+//# sourceMappingURL=input-failures.d.ts.map

package/dist/input-failures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-failures.d.ts","sourceRoot":"","sources":["../src/input-failures.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,oBAAoB,CAAC;AAwB5B,eAAO,MAAM,aAAa;IACxB;;;;;;OAMG;cACuB;QACxB,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAAC;QAC9B,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;KACrC;IAED;;;;;;;OAOG;aACqB;QACtB,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAAC;QAC9B,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;KACrC;CACF,CAAC"}

package/dist/input-failures.js

@@ -0,0 +1,45 @@
+// -----------------------------------------------------------------------
+// Copyright (c) DCSV. Licensed under the Apache License, Version 2.0.
+// -----------------------------------------------------------------------
+import { TK } from "@dcsv-io/d2-i18n-keys";
+import { inputError, validationFailed, } from "@dcsv-io/d2-result";
+/**
+ * Pre-built `D2Result` input-failure responses for cache impls.
+ * Keeps the cache surface pure errors-as-values instead of mixing in
+ * throws for caller mistakes.
+ *
+ * Constructors / DI registration still throw — that is a different
+ * lifecycle concern from per-call input validation.
+ *
+ * Twin of .NET `DcsvIo.D2.Caching.InputFailures`.
+ */
+function requiredImpl(paramName) {
+    return validationFailed({
+        inputErrors: [inputError(paramName, [TK.common.errors.NOT_NULL_VIOLATION])],
+    });
+}
+function invalidImpl(paramName) {
+    return validationFailed({
+        inputErrors: [inputError(paramName, [TK.common.errors.VALIDATION_FAILED])],
+    });
+}
+export const InputFailures = {
+    /**
+     * Builds a `D2Result` / `D2Result<T>` input failure for a missing
+     * (null / empty / falsey) required parameter.
+     *
+     * @param paramName - Parameter name (use a string literal matching
+     *   the call-site argument name).
+     */
+    required: requiredImpl,
+    /**
+     * Builds a `D2Result` / `D2Result<T>` input failure for a present but
+     * invalid parameter value (range, non-finite, non-safe-integer, etc.).
+     * Does **not** use `NOT_NULL_VIOLATION` — the value is present.
+     *
+     * @param paramName - Parameter name (use a string literal matching
+     *   the call-site argument name).
+     */
+    invalid: invalidImpl,
+};
+//# sourceMappingURL=input-failures.js.map

package/dist/input-failures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-failures.js","sourceRoot":"","sources":["../src/input-failures.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,sEAAsE;AACtE,0EAA0E;AAE1E,OAAO,EAAE,EAAE,EAAE,MAAM,uBAAuB,CAAC;AAC3C,OAAO,EACL,UAAU,EACV,gBAAgB,GAEjB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;GASG;AACH,SAAS,YAAY,CAAW,SAAiB;IAC/C,OAAO,gBAAgB,CAAI;QACzB,WAAW,EAAE,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAAC;KAC5E,CAAC,CAAC;AACL,CAAC;AAED,SAAS,WAAW,CAAW,SAAiB;IAC9C,OAAO,gBAAgB,CAAI;QACzB,WAAW,EAAE,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC;KAC3E,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B;;;;;;OAMG;IACH,QAAQ,EAAE,YAGT;IAED;;;;;;;OAOG;IACH,OAAO,EAAE,WAGR;CACF,CAAC"}

package/dist/local-cache-options.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Configuration knobs for an {@link ILocalCache} implementation.
+ * Defaults are tuned for typical microservice workloads (100K entries,
+ * 1-hour default TTL).
+ *
+ * Per-entry size accounting is intentionally NOT exposed — the default
+ * implementation always counts entries as size 1 so `maxEntries`
+ * behaves as the literal entry-count cap most callers expect.
+ *
+ * No options validation on this POCO (mirrors .NET — no range check /
+ * ValidateOnStart). The factory does not fail on absurd values;
+ * enforcement belongs in the local-default implementation.
+ */
+export interface LocalCacheOptions {
+    /**
+     * Maximum number of entries before LRU-ish eviction kicks in.
+     * Default 100_000.
+     */
+    maxEntries: number;
+    /**
+     * Default TTL (milliseconds) applied to entries written without an
+     * explicit expiration. Default 3_600_000 (1 hour).
+     */
+    defaultExpirationMs: number;
+    /**
+     * Optional key prefix automatically prepended to every cache key.
+     * Useful when multiple caches share a process and the caller wants
+     * namespace isolation (e.g. `"jwks:"`) without coordinating keys
+     * explicitly. Default is empty string (no prefix).
+     */
+    keyPrefix: string;
+}
+export declare const LOCAL_CACHE_DEFAULTS: Readonly<LocalCacheOptions>;
+/**
+ * Builds a mutable {@link LocalCacheOptions} by merging an optional
+ * partial over {@link LOCAL_CACHE_DEFAULTS}. Always returns a fresh
+ * object (not shared with the defaults constant).
+ */
+export declare function createLocalCacheOptions(partial?: Partial<LocalCacheOptions>): LocalCacheOptions;
+//# sourceMappingURL=local-cache-options.d.ts.map

package/dist/local-cache-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-cache-options.d.ts","sourceRoot":"","sources":["../src/local-cache-options.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAE5B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,iBAAiB,CAI5D,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACnC,iBAAiB,CAOnB"}

package/dist/local-cache-options.js

@@ -0,0 +1,22 @@
+// -----------------------------------------------------------------------
+// Copyright (c) DCSV. Licensed under the Apache License, Version 2.0.
+// -----------------------------------------------------------------------
+// Numeric twin of .NET LocalCacheOptions (MaxEntries=100_000, DefaultExpiration=1h, KeyPrefix="").
+export const LOCAL_CACHE_DEFAULTS = {
+    maxEntries: 100_000,
+    defaultExpirationMs: 3_600_000,
+    keyPrefix: "",
+};
+/**
+ * Builds a mutable {@link LocalCacheOptions} by merging an optional
+ * partial over {@link LOCAL_CACHE_DEFAULTS}. Always returns a fresh
+ * object (not shared with the defaults constant).
+ */
+export function createLocalCacheOptions(partial) {
+    return {
+        maxEntries: partial?.maxEntries ?? LOCAL_CACHE_DEFAULTS.maxEntries,
+        defaultExpirationMs: partial?.defaultExpirationMs ?? LOCAL_CACHE_DEFAULTS.defaultExpirationMs,
+        keyPrefix: partial?.keyPrefix ?? LOCAL_CACHE_DEFAULTS.keyPrefix,
+    };
+}
+//# sourceMappingURL=local-cache-options.js.map

package/dist/local-cache-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-cache-options.js","sourceRoot":"","sources":["../src/local-cache-options.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,sEAAsE;AACtE,0EAA0E;AAqC1E,mGAAmG;AACnG,MAAM,CAAC,MAAM,oBAAoB,GAAgC;IAC/D,UAAU,EAAE,OAAO;IACnB,mBAAmB,EAAE,SAAS;IAC9B,SAAS,EAAE,EAAE;CACd,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAoC;IAEpC,OAAO;QACL,UAAU,EAAE,OAAO,EAAE,UAAU,IAAI,oBAAoB,CAAC,UAAU;QAClE,mBAAmB,EACjB,OAAO,EAAE,mBAAmB,IAAI,oBAAoB,CAAC,mBAAmB;QAC1E,SAAS,EAAE,OAAO,EAAE,SAAS,IAAI,oBAAoB,CAAC,SAAS;KAChE,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@dcsv-io/d2-caching-abstractions",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@dcsv-io/d2-i18n-keys": "0.1.1",
+    "@dcsv-io/d2-result": "0.1.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.0.18",
+    "typescript": "5.9.3",
+    "vitest": "4.0.18"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "type-check:test": "tsc -p tsconfig.test.json"
+  }
+}