@break-limits/mongoose-cache 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,296 @@
+import { EventEmitter } from 'node:events';
+import { Mongoose } from 'mongoose';
+import { Redis } from 'ioredis';
+
+/**
+ * Storage contract used by the CacheManager. The in-memory implementation is
+ * the reference (and powers unit tests); a Redis-backed adapter (Phase 2)
+ * implements the same contract with Lua scripts for the atomic version guard.
+ *
+ * The per-model version counter underpins the write-after-read race guard:
+ * a reader captures the version before loading from Mongo and only writes the
+ * value to cache if no write bumped the version meanwhile.
+ */
+interface CacheStore {
+    get(key: string): Promise<Buffer | null>;
+    set(key: string, value: Buffer, ttlMs?: number): Promise<void>;
+    del(keys: string[]): Promise<void>;
+    getVersion(model: string): Promise<number>;
+    bumpVersion(model: string): Promise<number>;
+    /** Tag membership — backs conservative (collection-tag) invalidation. */
+    addToSet(setKey: string, member: string): Promise<void>;
+    /** Return all members of a set and delete the set (atomic drain). */
+    drainSet(setKey: string): Promise<string[]>;
+}
+declare class InMemoryCacheStore implements CacheStore {
+    private readonly data;
+    private readonly versions;
+    private readonly sets;
+    get(key: string): Promise<Buffer | null>;
+    set(key: string, value: Buffer, _ttlMs?: number): Promise<void>;
+    del(keys: string[]): Promise<void>;
+    getVersion(model: string): Promise<number>;
+    bumpVersion(model: string): Promise<number>;
+    addToSet(setKey: string, member: string): Promise<void>;
+    drainSet(setKey: string): Promise<string[]>;
+}
+
+interface ModelConfig {
+    ttlMs?: number;
+    enabled?: boolean;
+}
+interface CreateCacheOptions {
+    mongoose: Mongoose;
+    redis: Redis;
+    /** Override the storage backend (e.g. for testing). Defaults to Redis. */
+    store?: CacheStore;
+    /** Opt-in model map. Omit to cache every currently-registered model. */
+    models?: Record<string, ModelConfig>;
+    defaults?: {
+        ttlMs?: number;
+    };
+    /** Resolve the current tenant id for keyspace isolation. */
+    tenant?: () => string | undefined;
+}
+interface Cache extends EventEmitter {
+    /** Restore all patched Mongoose methods. */
+    close(): void;
+}
+declare function createCache(options: CreateCacheOptions): Cache;
+
+/**
+ * Redis-backed {@link CacheStore}. Implements the same contract proven against
+ * the in-memory store, so all CacheManager correctness logic carries over.
+ *
+ * Phase 1 targets single-node correctness (in-process single-flight + a
+ * per-model version counter). Phase 2 hardens the version guard into an atomic
+ * Lua compare-and-set for multi-node deployments.
+ */
+declare class RedisCacheStore implements CacheStore {
+    private readonly redis;
+    private readonly versionPrefix;
+    constructor(redis: Redis, versionPrefix?: string);
+    get(key: string): Promise<Buffer | null>;
+    set(key: string, value: Buffer, ttlMs?: number): Promise<void>;
+    del(keys: string[]): Promise<void>;
+    getVersion(model: string): Promise<number>;
+    bumpVersion(model: string): Promise<number>;
+    addToSet(setKey: string, member: string): Promise<void>;
+    drainSet(setKey: string): Promise<string[]>;
+    private versionKey;
+}
+
+/**
+ * In-memory evaluation of a MongoDB filter against a single plain document.
+ *
+ * This is the engine that powers precise (T1) invalidation: on a write we
+ * evaluate whether a document entered or left a cached query's result set.
+ *
+ * CRITICAL CORRECTNESS CONTRACT: `matches` must agree with MongoDB's matching
+ * semantics for every operator that {@link isSupportedPredicate} accepts. A
+ * predicate using any operator we cannot faithfully evaluate must be rejected
+ * by `isSupportedPredicate` so the tier classifier downgrades it to T2
+ * (collection-tag invalidation) rather than risk a missed invalidation.
+ */
+type Filter = Record<string, unknown>;
+type Doc = Record<string, unknown>;
+declare function matches(filter: Filter, doc: Doc): boolean;
+declare function isSupportedPredicate(filter: unknown): boolean;
+
+/**
+ * Metadata recorded for every cached T1 query so that a later write can decide,
+ * precisely, whether the query's result set could have changed.
+ */
+interface QueryMeta {
+    predicate: Filter;
+    /** True when the query has a limit (top-N) — see InvalidationEngine step 5. */
+    limited: boolean;
+    /** Stable string ids of the documents currently in the cached result. */
+    resultDocIds: string[];
+}
+interface RegisteredQuery extends QueryMeta {
+    queryKey: string;
+}
+/**
+ * Index of active T1 queries, keyed by model. The in-memory implementation is
+ * the source of truth for unit tests and single-process use; a Redis-backed
+ * implementation (Phase 2) provides the same contract across nodes.
+ */
+interface DependencyIndex {
+    addQuery(model: string, queryKey: string, meta: QueryMeta): Promise<void>;
+    removeQuery(model: string, queryKey: string): Promise<void>;
+    getQueries(model: string): Promise<RegisteredQuery[]>;
+    /** Remove every registered query for a model, returning the keys removed. */
+    clearModel(model: string): Promise<string[]>;
+}
+declare class InMemoryDependencyIndex implements DependencyIndex {
+    private readonly byModel;
+    addQuery(model: string, queryKey: string, meta: QueryMeta): Promise<void>;
+    removeQuery(model: string, queryKey: string): Promise<void>;
+    getQueries(model: string): Promise<RegisteredQuery[]>;
+    clearModel(model: string): Promise<string[]>;
+}
+
+/**
+ * Redis-backed {@link DependencyIndex}. Persisting the registry alongside the
+ * cached entries themselves is a correctness requirement: if the registry were
+ * only in-process, a restart would orphan still-cached query results — a later
+ * write could no longer find them to invalidate, serving stale data.
+ *
+ * Predicate metadata is stored as BSON (not JSON) so ObjectId/Date values
+ * inside a predicate survive the round-trip and the matcher stays accurate.
+ */
+declare class RedisDependencyIndex implements DependencyIndex {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: Redis, prefix?: string);
+    addQuery(model: string, queryKey: string, meta: QueryMeta): Promise<void>;
+    removeQuery(model: string, queryKey: string): Promise<void>;
+    getQueries(model: string): Promise<RegisteredQuery[]>;
+    clearModel(model: string): Promise<string[]>;
+    private setKey;
+    private metaKey;
+}
+
+/**
+ * Query fingerprinting: convert an arbitrary Mongoose query shape into a
+ * deterministic, canonical structure suitable for hashing.
+ *
+ * Two semantically-equal queries (e.g. `{a:1,b:2}` and `{b:2,a:1}`) must
+ * produce identical fingerprints. Special BSON-ish types (ObjectId, Date,
+ * RegExp) are normalized to stable tagged forms.
+ */
+declare function normalizeQuery(value: unknown): unknown;
+
+/**
+ * Deterministic hash of an arbitrary value. The value is first canonicalized
+ * via {@link normalizeQuery} so semantically-equal inputs hash identically,
+ * then hashed with SHA-256 and truncated for compactness.
+ */
+declare function stableHash(value: unknown): string;
+
+/**
+ * Deterministic cache-key construction. Keys are namespaced by tenant (for
+ * isolation), kind (`q` for query results, `doc` for point reads), and model.
+ */
+interface CacheKeyInput {
+    model: string;
+    op: string;
+    filter?: unknown;
+    projection?: unknown;
+    sort?: unknown;
+    skip?: number | undefined;
+    limit?: number | undefined;
+    populate?: unknown;
+    collation?: unknown;
+    /** The field name for a `distinct` query (so distinct('a') ≠ distinct('b')). */
+    distinct?: unknown;
+    tenant?: string | undefined;
+    schemaVersion?: string | undefined;
+}
+declare function buildQueryKey(input: CacheKeyInput): string;
+declare function buildDocKey(model: string, id: string, tenant?: string): string;
+
+/**
+ * Lossless serialization of cache values. We never store hydrated Mongoose
+ * documents — only plain (lean) data — but that data still contains BSON types
+ * (ObjectId, Date, Decimal128, Buffer) that must survive a Redis round-trip.
+ *
+ * Values are wrapped (`{ v: value }`) before BSON encoding so that arrays and
+ * primitives — not just documents — can be stored.
+ */
+declare function serialize(value: unknown): Buffer;
+declare function deserialize(buffer: Buffer): unknown;
+
+interface WriteReport {
+    invalidatedQueryKeys: string[];
+}
+/**
+ * Drives precise (T1) invalidation via the membership-transition algorithm
+ * (see plan.md "On write"). Given the before- and after-images of a changed
+ * document, it determines exactly which cached queries could have changed.
+ */
+declare class InvalidationEngine {
+    private readonly index;
+    constructor(index: DependencyIndex);
+    registerQuery(model: string, queryKey: string, meta: QueryMeta): Promise<void>;
+    onWrite(model: string, before: Doc | null, after: Doc | null): Promise<WriteReport>;
+    /**
+     * Remove every registered query for a model and return their cache keys.
+     * Used as a conservative fallback (bulkWrite, upserts) where per-document
+     * before/after images aren't available.
+     */
+    clearQueries(model: string): Promise<string[]>;
+}
+
+/**
+ * Cacheability tiers. See plan.md "Cacheability Tiers".
+ *
+ * - T0: point read keyed by document id — surgical invalidation.
+ * - T1: predicate query we can evaluate in-memory — precise invalidation.
+ * - T2: bounded but unpredicatable — conservative collection-tag invalidation.
+ * - T3: aggregation — conservative by touched collection(s).
+ * - T4: never cache (active session/transaction, cursor/streaming).
+ */
+type Tier = "T0" | "T1" | "T2" | "T3" | "T4";
+interface ClassifyInput {
+    op: string;
+    filter?: Filter;
+    hasSession?: boolean;
+    isCursor?: boolean;
+}
+declare function classifyQuery(input: ClassifyInput): Tier;
+
+interface CachedQuery {
+    key: string;
+    model: string;
+    tier: Tier;
+    predicate?: Filter | undefined;
+    limited?: boolean | undefined;
+    ttlMs?: number | undefined;
+    /** Collection names to tag this entry with (conservative T2/T3 invalidation). */
+    tags?: string[] | undefined;
+}
+/**
+ * Ties together the store, serializer, and invalidation engine into the
+ * read/write caching brain. Guarantees the no-stale-read invariant via a
+ * version-token race guard and prevents stampedes via in-process single-flight.
+ */
+declare class CacheManager {
+    private readonly store;
+    private readonly engine;
+    private readonly events?;
+    private readonly inflight;
+    constructor(store: CacheStore, engine: InvalidationEngine, events?: EventEmitter | undefined);
+    /**
+     * Return the cached value for a query, or load it via `loader`, cache it
+     * (when safe), and register it for precise invalidation.
+     *
+     * @param extractIds maps a loaded result to the stable string ids of the
+     *   documents it contains — required for T1 direct-membership invalidation.
+     */
+    getOrLoad<T>(query: CachedQuery, loader: () => Promise<T>, extractIds?: (result: T) => string[]): Promise<T>;
+    private loadAndCache;
+    /**
+     * Apply a write: bump the model version (closing the race window), run the
+     * invalidation engine, and delete every affected cache key.
+     */
+    onWrite(model: string, before: Doc | null, after: Doc | null, extraKeys?: string[]): Promise<string[]>;
+    /**
+     * Conservative invalidation: drain a collection's tag and delete every
+     * entry tagged with it (T2/T3/distinct/populate). Degrade-safe.
+     */
+    invalidateCollection(collection: string): Promise<string[]>;
+    /**
+     * Nuclear precise fallback: remove every registered T1 query for a model and
+     * delete its cache keys. Used for writes we cannot image (bulkWrite, upserts).
+     */
+    flushModelPrecise(model: string): Promise<string[]>;
+    /**
+     * Emit an `error` event without crashing: a bare `error` emit on an
+     * EventEmitter with no listeners would itself throw.
+     */
+    private emitError;
+}
+
+export { type Cache, type CacheKeyInput, CacheManager, type CacheStore, type CachedQuery, type ClassifyInput, type CreateCacheOptions, type DependencyIndex, type Doc, type Filter, InMemoryCacheStore, InMemoryDependencyIndex, InvalidationEngine, type ModelConfig, type QueryMeta, RedisCacheStore, RedisDependencyIndex, type RegisteredQuery, type Tier, type WriteReport, buildDocKey, buildQueryKey, classifyQuery, createCache, deserialize, isSupportedPredicate, matches, normalizeQuery, serialize, stableHash };