@cogenta/core 0.1.0

package/dist/cache/entry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The envelope every driver stores: the value plus what is needed to expire and
+ * invalidate it. Identical across drivers, so an entry written by one is
+ * readable by another — which is what makes the contract suite meaningful.
+ */
+export interface CacheEntry {
+    readonly value: unknown;
+    /** Epoch milliseconds, or `null` for "no expiry". */
+    readonly expiresAt: number | null;
+    readonly tags: readonly string[];
+}
+export declare function assertKey(key: string): void;
+export declare function expiryFrom(ttl: number | undefined, now: number): number | null;
+export declare function isExpired(expiresAt: number | null, now: number): boolean;
+/**
+ * Round-trips a value through JSON, which is what the file and Redis drivers do
+ * anyway. Doing it in `memory` too is what keeps the three drivers substitutable:
+ * a caller must not be able to mutate a cached object by keeping the reference.
+ */
+export declare function serialise(value: unknown): string;
+export declare function deserialise(raw: string): unknown;
+/**
+ * Encodes an entry for any driver that stores it as one blob.
+ *
+ * The value is serialised **first, on its own**. Serialising the whole envelope
+ * in one go would let `JSON.stringify` drop an unserialisable value silently —
+ * a function becomes a missing property rather than an error — and the caller
+ * would only find out on the next read, far from the cause.
+ */
+export declare function encodeEntry(value: unknown, expiresAt: number | null, tags: readonly string[]): string;
+export declare function decodeEntry(raw: string): CacheEntry;
+//# sourceMappingURL=entry.d.ts.map

package/dist/cache/entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../../src/cache/entry.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CACjC;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAQ3C;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW9E;AAED,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAExE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAahD;AAWD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,MAAM,CAGR;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAEnD"}

package/dist/cache/entry.js

@@ -0,0 +1,72 @@
+import { CogentaError } from '../errors/index.js';
+export function assertKey(key) {
+    if (key.length === 0) {
+        throw new CogentaError({
+            code: 'CACHE_FAILED',
+            message: 'A cache key must not be empty.',
+            hint: 'Build the key from something stable, such as "page:" plus the locale and the slug.',
+        });
+    }
+}
+export function expiryFrom(ttl, now) {
+    if (ttl === undefined)
+        return null;
+    if (!Number.isFinite(ttl) || ttl <= 0) {
+        throw new CogentaError({
+            code: 'CACHE_FAILED',
+            message: `A cache TTL must be a positive number of seconds, received ${String(ttl)}.`,
+            hint: 'Omit the ttl option for an entry that lives until it is invalidated.',
+        });
+    }
+    return now + ttl * 1000;
+}
+export function isExpired(expiresAt, now) {
+    return expiresAt !== null && expiresAt <= now;
+}
+/**
+ * Round-trips a value through JSON, which is what the file and Redis drivers do
+ * anyway. Doing it in `memory` too is what keeps the three drivers substitutable:
+ * a caller must not be able to mutate a cached object by keeping the reference.
+ */
+export function serialise(value) {
+    let raw;
+    try {
+        raw = JSON.stringify(value ?? null);
+    }
+    catch (error) {
+        throw unserialisable(error);
+    }
+    // `JSON.stringify` returns undefined — it does not throw — for a function or a
+    // symbol. Left unchecked that caches the string "undefined" and hands it back
+    // on the next read, so the failure surfaces far from its cause.
+    if (raw === undefined)
+        throw unserialisable(undefined);
+    return raw;
+}
+function unserialisable(cause) {
+    return new CogentaError({
+        code: 'CACHE_FAILED',
+        message: 'This value cannot be cached: it is not serialisable to JSON.',
+        hint: 'Cache plain data. Functions, symbols, class instances and BigInt do not survive any cache driver.',
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+export function deserialise(raw) {
+    return JSON.parse(raw);
+}
+/**
+ * Encodes an entry for any driver that stores it as one blob.
+ *
+ * The value is serialised **first, on its own**. Serialising the whole envelope
+ * in one go would let `JSON.stringify` drop an unserialisable value silently —
+ * a function becomes a missing property rather than an error — and the caller
+ * would only find out on the next read, far from the cause.
+ */
+export function encodeEntry(value, expiresAt, tags) {
+    const encodedValue = serialise(value);
+    return `{"value":${encodedValue},"expiresAt":${JSON.stringify(expiresAt)},"tags":${JSON.stringify(tags)}}`;
+}
+export function decodeEntry(raw) {
+    return JSON.parse(raw);
+}
+//# sourceMappingURL=entry.js.map

package/dist/cache/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../src/cache/entry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAcjD,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,YAAY,CAAC;YACrB,IAAI,EAAE,cAAc;YACpB,OAAO,EAAE,gCAAgC;YACzC,IAAI,EAAE,oFAAoF;SAC3F,CAAC,CAAA;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAuB,EAAE,GAAW;IAC7D,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IAElC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,YAAY,CAAC;YACrB,IAAI,EAAE,cAAc;YACpB,OAAO,EAAE,8DAA8D,MAAM,CAAC,GAAG,CAAC,GAAG;YACrF,IAAI,EAAE,sEAAsE;SAC7E,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,GAAG,GAAG,GAAG,GAAG,IAAI,CAAA;AACzB,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,SAAwB,EAAE,GAAW;IAC7D,OAAO,SAAS,KAAK,IAAI,IAAI,SAAS,IAAI,GAAG,CAAA;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,IAAI,GAAuB,CAAA;IAC3B,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,IAAI,CAAC,CAAA;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,cAAc,CAAC,KAAK,CAAC,CAAA;IAC7B,CAAC;IAED,+EAA+E;IAC/E,8EAA8E;IAC9E,gEAAgE;IAChE,IAAI,GAAG,KAAK,SAAS;QAAE,MAAM,cAAc,CAAC,SAAS,CAAC,CAAA;IACtD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,OAAO,IAAI,YAAY,CAAC;QACtB,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,8DAA8D;QACvE,IAAI,EAAE,mGAAmG;QACzG,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;KAC1C,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;AACxB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,KAAc,EACd,SAAwB,EACxB,IAAuB;IAEvB,MAAM,YAAY,GAAG,SAAS,CAAC,KAAK,CAAC,CAAA;IACrC,OAAO,YAAY,YAAY,gBAAgB,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,WAAW,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAA;AAC5G,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAe,CAAA;AACtC,CAAC"}

package/dist/cache/file.d.ts

@@ -0,0 +1,16 @@
+import type { Driver } from '../drivers/index.js';
+import type { CacheConfig, CacheDriver, CacheDriverOptions } from './types.js';
+export interface FileCacheOptions extends CacheDriverOptions {
+    readonly path: string;
+}
+/**
+ * Cache on disk. Survives a restart and is shared between processes on the same
+ * machine, which is what a shared-hosting deployment gets instead of Redis.
+ *
+ * Writes go to a temporary file and are then renamed. `rename` is atomic on a
+ * single filesystem, so a reader never sees a half-written entry — the failure
+ * mode that makes naive file caches corrupt data under load.
+ */
+export declare function createFileCache(options: FileCacheOptions): CacheDriver;
+export declare function fileCacheDriver(options?: CacheDriverOptions): Driver<CacheDriver, CacheConfig>;
+//# sourceMappingURL=file.d.ts.map

package/dist/cache/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../src/cache/file.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAgB,MAAM,qBAAqB,CAAA;AAU/D,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB,EAAmB,MAAM,YAAY,CAAA;AA2C/F,MAAM,WAAW,gBAAiB,SAAQ,kBAAkB;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,WAAW,CAgHtE;AAED,wBAAgB,eAAe,CAC7B,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC,CAwClC"}

package/dist/cache/file.js

@@ -0,0 +1,191 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CogentaError } from '../errors/index.js';
+import { assertKey, decodeEntry, encodeEntry, expiryFrom, isExpired, } from './entry.js';
+/**
+ * Keys become filenames through a hash, not through escaping. A cache key is
+ * arbitrary text — Unicode, slashes, hundreds of characters — and every escaping
+ * scheme eventually collides or produces a path the filesystem rejects.
+ */
+function fileNameFor(key) {
+    return createHash('sha256').update(key).digest('hex');
+}
+// Exponential, with jitter so contending writers do not retry in lockstep and
+// collide again. Worst case is about a second, and only under heavy contention.
+const RENAME_RETRY_DELAYS_MS = [5, 10, 20, 40, 80, 160, 320, 640];
+const RETRYABLE_RENAME_ERRORS = new Set(['EPERM', 'EACCES', 'EBUSY']);
+/**
+ * Retries the transient failures Windows returns for a filesystem operation.
+ *
+ * Windows refuses an operation while another handle is still open on the target
+ * — a rename onto a file being read, or the removal of a directory that was
+ * just enumerated. Both surface as EPERM, EACCES or EBUSY, and both clear on
+ * their own within milliseconds. On POSIX the loop never runs a second time.
+ */
+async function withWindowsRetry(operation) {
+    for (const [attempt, delay] of RENAME_RETRY_DELAYS_MS.entries()) {
+        try {
+            await operation();
+            return;
+        }
+        catch (error) {
+            const code = error.code ?? '';
+            const lastAttempt = attempt === RENAME_RETRY_DELAYS_MS.length - 1;
+            if (!RETRYABLE_RENAME_ERRORS.has(code) || lastAttempt)
+                throw error;
+            const jittered = delay * (0.5 + Math.random());
+            await new Promise((resolve) => setTimeout(resolve, jittered));
+        }
+    }
+}
+const replaceAtomically = (temporary, target) => withWindowsRetry(() => rename(temporary, target));
+/**
+ * Cache on disk. Survives a restart and is shared between processes on the same
+ * machine, which is what a shared-hosting deployment gets instead of Redis.
+ *
+ * Writes go to a temporary file and are then renamed. `rename` is atomic on a
+ * single filesystem, so a reader never sees a half-written entry — the failure
+ * mode that makes naive file caches corrupt data under load.
+ */
+export function createFileCache(options) {
+    const now = options.now ?? Date.now;
+    const entriesDir = join(options.path, 'entries');
+    const tagsDir = join(options.path, 'tags');
+    async function ensureDirectories() {
+        await mkdir(entriesDir, { recursive: true });
+        await mkdir(tagsDir, { recursive: true });
+    }
+    async function readEntry(name) {
+        try {
+            return decodeEntry(await readFile(join(entriesDir, name), 'utf8'));
+        }
+        catch {
+            // A missing or unreadable entry is a cache miss, never an outage: a cache
+            // that throws is worse than a cache that forgets.
+            return null;
+        }
+    }
+    /** Drops the tag markers pointing at an entry, leaving the entry itself alone. */
+    async function untag(name) {
+        const entry = await readEntry(name);
+        for (const tag of entry?.tags ?? []) {
+            await rm(join(tagsDir, fileNameFor(tag), name), { force: true });
+        }
+    }
+    async function removeEntry(name) {
+        await untag(name);
+        await rm(join(entriesDir, name), { force: true });
+    }
+    return {
+        get: async (key) => {
+            assertKey(key);
+            const name = fileNameFor(key);
+            const entry = await readEntry(name);
+            if (entry === null)
+                return null;
+            if (isExpired(entry.expiresAt, now())) {
+                await removeEntry(name);
+                return null;
+            }
+            return entry.value;
+        },
+        set: async (key, value, setOptions) => {
+            assertKey(key);
+            const expiresAt = expiryFrom(setOptions?.ttl, now());
+            const tags = [...new Set(setOptions?.tags ?? [])];
+            const name = fileNameFor(key);
+            // Encode before touching the disk, so an unserialisable value fails
+            // without leaving a half-updated cache behind.
+            const payload = encodeEntry(value, expiresAt, tags);
+            await ensureDirectories();
+            // Only the tag markers are cleared up front. The entry itself is replaced
+            // by the rename below, so a concurrent reader never sees it missing.
+            await untag(name);
+            const target = join(entriesDir, name);
+            // Unique per write, not per process: two concurrent writes to the same key
+            // sharing a temporary file means one of them renames it and the other
+            // fails on a file that is no longer there.
+            const temporary = `${target}.${randomUUID()}.tmp`;
+            try {
+                await writeFile(temporary, payload, 'utf8');
+                await replaceAtomically(temporary, target);
+            }
+            catch (error) {
+                await rm(temporary, { force: true });
+                throw new CogentaError({
+                    code: 'CACHE_FAILED',
+                    message: `Could not write the cache entry for "${key}".`,
+                    hint: `Check that ${options.path} exists and is writable, or set cache.driver to "memory".`,
+                    cause: error,
+                });
+            }
+            for (const tag of tags) {
+                const tagDir = join(tagsDir, fileNameFor(tag));
+                await mkdir(tagDir, { recursive: true });
+                await writeFile(join(tagDir, name), '', 'utf8');
+            }
+        },
+        delete: async (key) => {
+            assertKey(key);
+            await removeEntry(fileNameFor(key));
+        },
+        invalidateTags: async (tags) => {
+            for (const tag of tags) {
+                const tagDir = join(tagsDir, fileNameFor(tag));
+                let names;
+                try {
+                    names = await readdir(tagDir);
+                }
+                catch {
+                    continue;
+                }
+                for (const name of names)
+                    await removeEntry(name);
+                await withWindowsRetry(() => rm(tagDir, { recursive: true, force: true }));
+            }
+        },
+        clear: async () => {
+            await rm(options.path, { recursive: true, force: true });
+            await ensureDirectories();
+        },
+    };
+}
+export function fileCacheDriver(options = {}) {
+    let instance;
+    let path;
+    return {
+        name: 'file',
+        tier: 'degraded',
+        // "Can we actually write there?" — not "is a path configured?". A read-only
+        // filesystem is exactly the case this check exists to catch.
+        available: async (config) => {
+            const candidate = config.path ?? './.cogenta/cache';
+            try {
+                await mkdir(candidate, { recursive: true });
+                const probe = join(candidate, `.probe-${process.pid}`);
+                await writeFile(probe, '', 'utf8');
+                await rm(probe, { force: true });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        init: async (config) => {
+            path = config.path ?? './.cogenta/cache';
+            instance ??= createFileCache({ ...options, path });
+            return instance;
+        },
+        dispose: async () => {
+            instance = undefined;
+        },
+        health: async () => ({
+            status: 'degraded',
+            driver: 'file',
+            tier: 'degraded',
+            message: `Cache on disk at ${path ?? 'an unopened path'}. Shared between processes on this machine only.`,
+        }),
+    };
+}
+//# sourceMappingURL=file.js.map

package/dist/cache/file.js.map

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

package/dist/cache/index.d.ts

@@ -0,0 +1,20 @@
+import { type DriverRegistry } from '../drivers/index.js';
+import type { Logger } from '../logger/index.js';
+import type { CacheConfig, CacheDriver, CacheDriverOptions } from './types.js';
+export type { FileCacheOptions } from './file.js';
+export { createFileCache, fileCacheDriver } from './file.js';
+export { createMemoryCache, memoryCacheDriver } from './memory.js';
+export type { RedisCacheOptions } from './redis.js';
+export { createRedisCache, loadRedisModule, redisCacheDriver } from './redis.js';
+export type { CacheConfig, CacheDriver, CacheDriverOptions, CacheSetOptions } from './types.js';
+export interface CacheRegistryOptions extends CacheDriverOptions {
+    readonly logger?: Logger;
+}
+/**
+ * The cache drivers Cogenta ships, in tier order.
+ *
+ * `file` before `memory`: both need no service, but a cache that survives a
+ * restart and is shared between processes is worth more than one that does not.
+ */
+export declare function createCacheRegistry(options?: CacheRegistryOptions): DriverRegistry<CacheDriver, CacheConfig>;
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAIhD,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAE9E,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AACjD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAC5D,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAClE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAChF,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAE/F,MAAM,WAAW,oBAAqB,SAAQ,kBAAkB;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,oBAAyB,GACjC,cAAc,CAAC,WAAW,EAAE,WAAW,CAAC,CAY1C"}

package/dist/cache/index.js

@@ -0,0 +1,25 @@
+import { createDriverRegistry } from '../drivers/index.js';
+import { fileCacheDriver } from './file.js';
+import { memoryCacheDriver } from './memory.js';
+import { redisCacheDriver } from './redis.js';
+export { createFileCache, fileCacheDriver } from './file.js';
+export { createMemoryCache, memoryCacheDriver } from './memory.js';
+export { createRedisCache, loadRedisModule, redisCacheDriver } from './redis.js';
+/**
+ * The cache drivers Cogenta ships, in tier order.
+ *
+ * `file` before `memory`: both need no service, but a cache that survives a
+ * restart and is shared between processes is worth more than one that does not.
+ */
+export function createCacheRegistry(options = {}) {
+    const { logger, ...driverOptions } = options;
+    const registry = createDriverRegistry({
+        need: 'cache',
+        ...(logger === undefined ? {} : { logger }),
+    });
+    registry.register(redisCacheDriver(driverOptions));
+    registry.register(fileCacheDriver(driverOptions));
+    registry.register(memoryCacheDriver(driverOptions));
+    return registry;
+}
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAuB,MAAM,qBAAqB,CAAA;AAE/E,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAI7C,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAC5D,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAElE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAOhF;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAO,GAAyB,EAAE;IAElC,MAAM,EAAE,MAAM,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,CAAA;IAC5C,MAAM,QAAQ,GAAG,oBAAoB,CAA2B;QAC9D,IAAI,EAAE,OAAO;QACb,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;KAC5C,CAAC,CAAA;IAEF,QAAQ,CAAC,QAAQ,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC,CAAA;IAClD,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAAA;IACjD,QAAQ,CAAC,QAAQ,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC,CAAA;IAEnD,OAAO,QAAQ,CAAA;AACjB,CAAC"}

package/dist/cache/memory.d.ts

@@ -0,0 +1,11 @@
+import type { Driver } from '../drivers/index.js';
+import type { CacheConfig, CacheDriver, CacheDriverOptions } from './types.js';
+/**
+ * In-process cache. The last line of defence: it needs nothing at all, so it is
+ * what a site falls back to when there is neither Redis nor a writable cache
+ * directory. Its contents die with the process, which is correct — a cache is
+ * never a source of truth.
+ */
+export declare function createMemoryCache(options?: CacheDriverOptions): CacheDriver;
+export declare function memoryCacheDriver(options?: CacheDriverOptions): Driver<CacheDriver, CacheConfig>;
+//# sourceMappingURL=memory.d.ts.map

package/dist/cache/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/cache/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAgB,MAAM,qBAAqB,CAAA;AAE/D,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB,EAAmB,MAAM,YAAY,CAAA;AAS/F;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CA+D/E;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC,CAsBlC"}

package/dist/cache/memory.js

@@ -0,0 +1,89 @@
+import { assertKey, deserialise, expiryFrom, isExpired, serialise } from './entry.js';
+/**
+ * In-process cache. The last line of defence: it needs nothing at all, so it is
+ * what a site falls back to when there is neither Redis nor a writable cache
+ * directory. Its contents die with the process, which is correct — a cache is
+ * never a source of truth.
+ */
+export function createMemoryCache(options = {}) {
+    const now = options.now ?? Date.now;
+    const entries = new Map();
+    const byTag = new Map();
+    function forget(key) {
+        const entry = entries.get(key);
+        if (entry === undefined)
+            return;
+        for (const tag of entry.tags) {
+            const keys = byTag.get(tag);
+            if (keys === undefined)
+                continue;
+            keys.delete(key);
+            if (keys.size === 0)
+                byTag.delete(tag);
+        }
+        entries.delete(key);
+    }
+    return {
+        get: async (key) => {
+            assertKey(key);
+            const entry = entries.get(key);
+            if (entry === undefined)
+                return null;
+            if (isExpired(entry.expiresAt, now())) {
+                forget(key);
+                return null;
+            }
+            return deserialise(entry.raw);
+        },
+        set: async (key, value, setOptions) => {
+            assertKey(key);
+            const raw = serialise(value);
+            const expiresAt = expiryFrom(setOptions?.ttl, now());
+            const tags = [...new Set(setOptions?.tags ?? [])];
+            forget(key);
+            entries.set(key, { raw, expiresAt, tags });
+            for (const tag of tags) {
+                const keys = byTag.get(tag) ?? new Set();
+                keys.add(key);
+                byTag.set(tag, keys);
+            }
+        },
+        delete: async (key) => {
+            assertKey(key);
+            forget(key);
+        },
+        invalidateTags: async (tags) => {
+            for (const tag of tags) {
+                for (const key of byTag.get(tag) ?? [])
+                    forget(key);
+            }
+        },
+        clear: async () => {
+            entries.clear();
+            byTag.clear();
+        },
+    };
+}
+export function memoryCacheDriver(options = {}) {
+    let instance;
+    return {
+        name: 'memory',
+        tier: 'degraded',
+        available: async () => true,
+        init: async () => {
+            instance ??= createMemoryCache(options);
+            return instance;
+        },
+        dispose: async () => {
+            await instance?.clear();
+            instance = undefined;
+        },
+        health: async () => ({
+            status: 'degraded',
+            driver: 'memory',
+            tier: 'degraded',
+            message: 'In-process cache. Not shared between processes and lost on restart.',
+        }),
+    };
+}
+//# sourceMappingURL=memory.js.map

package/dist/cache/memory.js.map

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

package/dist/cache/redis.d.ts

@@ -0,0 +1,54 @@
+import type { Driver } from '../drivers/index.js';
+import type { CacheConfig, CacheDriver, CacheDriverOptions } from './types.js';
+/**
+ * Only what this driver calls, described structurally.
+ *
+ * Importing the client's own types would put `@redis/client` in the published
+ * type declarations, and it is an *optional* peer: a site with no Redis must not
+ * be asked to install it to typecheck.
+ */
+interface RedisClientLike {
+    connect(): Promise<unknown>;
+    quit(): Promise<unknown>;
+    ping(): Promise<string>;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        PX?: number;
+    }): Promise<unknown>;
+    del(keys: string[]): Promise<number>;
+    sAdd(key: string, members: string[]): Promise<number>;
+    sRem(key: string, members: string[]): Promise<number>;
+    sMembers(key: string): Promise<string[]>;
+    scan(cursor: string, options: {
+        MATCH: string;
+        COUNT: number;
+    }): Promise<{
+        cursor: string | number;
+        keys: string[];
+    }>;
+}
+interface RedisModuleLike {
+    createClient(options: {
+        url?: string;
+    }): RedisClientLike;
+}
+/**
+ * Loads the client if the host application installed it. Absent is a normal
+ * outcome, not an error: it is what makes the registry fall through to the file
+ * driver, and what lets `pnpm install` stay dependency-free (rule R1).
+ */
+export declare function loadRedisModule(): Promise<RedisModuleLike | null>;
+export interface RedisCacheOptions extends CacheDriverOptions {
+    readonly client: RedisClientLike;
+    /**
+     * Namespace for every key this driver writes. A Redis instance is often
+     * shared; `clear()` must never touch what it does not own.
+     */
+    readonly prefix?: string;
+}
+export declare function createRedisCache(options: RedisCacheOptions): CacheDriver;
+export declare function redisCacheDriver(options?: CacheDriverOptions & {
+    prefix?: string;
+}): Driver<CacheDriver, CacheConfig>;
+export {};
+//# sourceMappingURL=redis.d.ts.map

package/dist/cache/redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../src/cache/redis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAgB,MAAM,qBAAqB,CAAA;AAG/D,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB,EAAmB,MAAM,YAAY,CAAA;AAE/F;;;;;;GAMG;AACH,UAAU,eAAe;IACvB,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3B,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IACxB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IACvB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC5E,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACpC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACrD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACrD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IACxC,IAAI,CACF,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GACxC,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAA;CACxD;AAED,UAAU,eAAe;IACvB,YAAY,CAAC,OAAO,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,eAAe,CAAA;CACzD;AAED;;;;GAIG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAMvE;AAED,MAAM,WAAW,iBAAkB,SAAQ,kBAAkB;IAC3D,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;IAChC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,WAAW,CAgFxE;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,kBAAkB,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GACrD,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC,CA8ElC"}