@toapi/cache 0.3.0

package/README.md

@@ -0,0 +1,5 @@
+# @toapi/cache
+
+Reference cache implementation for Toapi.
+
+Usually used to add caching to [@toapi/server](https://www.npmjs.com/package/@toapi/server).

package/dist/filesystem-cache.d.ts

@@ -0,0 +1,18 @@
+import { DatabaseSync } from "node:sqlite";
+import type { CacheEntry, Cache, Subscription, Json } from "./index";
+export declare class FilesystemCache implements Cache {
+    db: DatabaseSync;
+    gcTimeout: number;
+    subscribers: Set<Subscription>;
+    constructor(filename: string);
+    get(key: string): Promise<CacheEntry | null>;
+    set({ key, data, attachment, ttl, tags, }: CacheEntry & {
+        key: string;
+        ttl: number;
+        tags: string[];
+    }): Promise<void>;
+    delete(tags: string[], meta?: Json): Promise<void>;
+    gc(): void;
+    subscribe(callback: Subscription): () => void;
+}
+//# sourceMappingURL=filesystem-cache.d.ts.map

package/dist/filesystem-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-cache.d.ts","sourceRoot":"","sources":["../src/filesystem-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAOrE,qBAAa,eAAgB,YAAW,KAAK;IAC3C,EAAE,EAAE,YAAY,CAAC;IACjB,SAAS,SAAkB;IAC3B,WAAW,oBAA2B;gBAE1B,QAAQ,EAAE,MAAM;IAgCtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAqBlD,GAAG,CAAC,EACF,GAAG,EACH,IAAI,EACJ,UAAU,EACV,GAAG,EACH,IAAI,GACL,EAAE,UAAU,GAAG;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,EAAE,CAAC;KAChB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoCjB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BlD,EAAE;IAuCF,SAAS,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,IAAI;CAO9C"}

package/dist/filesystem-cache.js

@@ -0,0 +1,143 @@
+import { DatabaseSync } from "node:sqlite";
+import { existsSync } from "node:fs";
+const MIN_GC_TIMEOUT = 5 * 1000;
+const MAX_GC_TIMEOUT = 5 * 60 * 1000;
+const GC_TIMEOUT_STEP = 0.1;
+export class FilesystemCache {
+    db;
+    gcTimeout = MIN_GC_TIMEOUT;
+    subscribers = new Set();
+    constructor(filename) {
+        if (existsSync(filename)) {
+            this.db = new DatabaseSync(filename);
+            setTimeout(() => {
+                this.gc();
+            }, this.gcTimeout);
+            return;
+        }
+        this.db = new DatabaseSync(filename);
+        this.db.exec(`
+      PRAGMA journal_mode = WAL;
+      BEGIN;
+      CREATE TABLE entries (
+        key TEXT PRIMARY KEY,
+        data TEXT,
+        attachment BLOB,
+        added_at INTEGER,
+        expires_at INTEGER
+      );
+      CREATE TABLE tags (
+        key TEXT,
+        tag TEXT,
+        UNIQUE(key, tag),
+        FOREIGN KEY (key) REFERENCES entries(key) ON DELETE CASCADE
+      );
+      COMMIT;
+    `);
+        this.gc();
+    }
+    async get(key) {
+        const result = this.db
+            .prepare(`
+          SELECT data, attachment
+          FROM entries
+          WHERE key = ? AND expires_at >= ?
+        `)
+            .get(key, Date.now());
+        return Promise.resolve(result
+            ? {
+                data: result.data ? JSON.parse(result.data) : null,
+                attachment: result.attachment,
+            }
+            : null);
+    }
+    set({ key, data, attachment, ttl, tags, }) {
+        this.db.exec("BEGIN;");
+        try {
+            this.db
+                .prepare(`
+            INSERT OR REPLACE INTO entries (key, data, attachment, added_at, expires_at)
+            VALUES (?, ?, ?, ?, ?);
+          `)
+                .run(key, data ? JSON.stringify(data) : null, attachment ?? null, Date.now(), Date.now() + ttl * 1000);
+            const stmt = this.db.prepare(`
+        INSERT OR IGNORE INTO tags (key, tag) VALUES (?, ?)
+      `);
+            for (const tag of tags) {
+                stmt.run(key, tag);
+            }
+            this.db.exec("COMMIT;");
+        }
+        catch (e) {
+            try {
+                this.db.exec("ROLLBACK;");
+            }
+            catch { }
+            throw e;
+        }
+        return Promise.resolve();
+    }
+    delete(tags, meta) {
+        this.db.exec("BEGIN;");
+        try {
+            const stmt = this.db.prepare(`
+          DELETE FROM entries WHERE key IN
+            (SELECT key FROM tags WHERE tag = ?);
+        `);
+            for (const tag of tags) {
+                stmt.run(tag);
+            }
+            this.db.exec("COMMIT;");
+        }
+        catch (e) {
+            try {
+                this.db.exec("ROLLBACK;");
+            }
+            catch { }
+            throw e;
+        }
+        for (const callback of this.subscribers) {
+            callback(tags, meta);
+        }
+        return Promise.resolve();
+    }
+    gc() {
+        try {
+            this.db.exec("BEGIN;");
+            let changes = 0;
+            try {
+                const result = this.db
+                    .prepare(`
+              DELETE FROM entries WHERE expires_at < ?;
+            `)
+                    .run(Date.now());
+                changes = result.changes;
+                this.db.exec("COMMIT;");
+            }
+            catch (e) {
+                try {
+                    this.db.exec("ROLLBACK;");
+                }
+                catch { }
+                throw e;
+            }
+            if (changes > 100) {
+                this.gcTimeout = Math.max(Math.floor(this.gcTimeout * (1 - GC_TIMEOUT_STEP)), MIN_GC_TIMEOUT);
+            }
+            else if (changes < 10) {
+                this.gcTimeout = Math.min(Math.floor(this.gcTimeout * (1 + GC_TIMEOUT_STEP)), MAX_GC_TIMEOUT);
+            }
+        }
+        finally {
+            setTimeout(() => {
+                this.gc();
+            }, this.gcTimeout);
+        }
+    }
+    subscribe(callback) {
+        this.subscribers.add(callback);
+        return () => {
+            this.subscribers.delete(callback);
+        };
+    }
+}

package/dist/in-memory-cache.d.ts

@@ -0,0 +1,18 @@
+import { DatabaseSync } from "node:sqlite";
+import type { CacheEntry, Cache, Subscription, Json } from "./index";
+export declare class InMemoryCache implements Cache {
+    db: DatabaseSync;
+    gcTimeout: number;
+    subscribers: Set<Subscription>;
+    constructor();
+    get(key: string): Promise<CacheEntry | null>;
+    set({ key, data, attachment, ttl, tags, }: CacheEntry & {
+        key: string;
+        ttl: number;
+        tags: string[];
+    }): Promise<void>;
+    delete(tags: string[], meta?: Json): Promise<void>;
+    gc(): void;
+    subscribe(callback: Subscription): () => void;
+}
+//# sourceMappingURL=in-memory-cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-cache.d.ts","sourceRoot":"","sources":["../src/in-memory-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAMrE,qBAAa,aAAc,YAAW,KAAK;IACzC,EAAE,eAAgC;IAClC,SAAS,SAAkB;IAC3B,WAAW,oBAA2B;;IA2BhC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAqBlD,GAAG,CAAC,EACF,GAAG,EACH,IAAI,EACJ,UAAU,EACV,GAAG,EACH,IAAI,GACL,EAAE,UAAU,GAAG;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,EAAE,CAAC;KAChB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoCjB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BlD,EAAE;IAuCF,SAAS,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,IAAI;CAO9C"}

package/dist/in-memory-cache.js

@@ -0,0 +1,136 @@
+import { DatabaseSync } from "node:sqlite";
+const MIN_GC_TIMEOUT = 5 * 1000;
+const MAX_GC_TIMEOUT = 5 * 60 * 1000;
+const GC_TIMEOUT_STEP = 0.1;
+export class InMemoryCache {
+    db = new DatabaseSync(":memory:");
+    gcTimeout = MIN_GC_TIMEOUT;
+    subscribers = new Set();
+    constructor() {
+        this.db.exec(`
+      PRAGMA journal_mode = WAL;
+      BEGIN;
+      CREATE TABLE entries (
+        key TEXT PRIMARY KEY,
+        data TEXT,
+        attachment BLOB,
+        added_at INTEGER,
+        expires_at INTEGER
+      );
+      CREATE TABLE tags (
+        key TEXT,
+        tag TEXT,
+        UNIQUE(key, tag),
+        FOREIGN KEY (key) REFERENCES entries(key) ON DELETE CASCADE
+      );
+      COMMIT;
+    `);
+        setTimeout(() => {
+            this.gc();
+        }, this.gcTimeout);
+    }
+    async get(key) {
+        const result = this.db
+            .prepare(`
+          SELECT data, attachment
+          FROM entries
+          WHERE key = ? AND expires_at >= ?
+        `)
+            .get(key, Date.now());
+        return Promise.resolve(result
+            ? {
+                data: result.data ? JSON.parse(result.data) : null,
+                attachment: result.attachment,
+            }
+            : null);
+    }
+    set({ key, data, attachment, ttl, tags, }) {
+        this.db.exec("BEGIN;");
+        try {
+            this.db
+                .prepare(`
+            INSERT OR REPLACE INTO entries (key, data, attachment, added_at, expires_at)
+            VALUES (?, ?, ?, ?, ?);
+          `)
+                .run(key, data ? JSON.stringify(data) : null, attachment ?? null, Date.now(), Date.now() + ttl * 1000);
+            const stmt = this.db.prepare(`
+        INSERT OR IGNORE INTO tags (key, tag) VALUES (?, ?)
+      `);
+            for (const tag of tags) {
+                stmt.run(key, tag);
+            }
+            this.db.exec("COMMIT;");
+        }
+        catch (e) {
+            try {
+                this.db.exec("ROLLBACK;");
+            }
+            catch { }
+            throw e;
+        }
+        return Promise.resolve();
+    }
+    delete(tags, meta) {
+        this.db.exec("BEGIN;");
+        try {
+            const stmt = this.db.prepare(`
+          DELETE FROM entries WHERE key IN
+            (SELECT key FROM tags WHERE tag = ?);
+        `);
+            for (const tag of tags) {
+                stmt.run(tag);
+            }
+            this.db.exec("COMMIT;");
+        }
+        catch (e) {
+            try {
+                this.db.exec("ROLLBACK;");
+            }
+            catch { }
+            throw e;
+        }
+        for (const callback of this.subscribers) {
+            callback(tags, meta);
+        }
+        return Promise.resolve();
+    }
+    gc() {
+        try {
+            this.db.exec("BEGIN;");
+            let changes = 0;
+            try {
+                const result = this.db
+                    .prepare(`
+              DELETE FROM entries WHERE expires_at < ?;
+            `)
+                    .run(Date.now());
+                changes = result.changes;
+                this.db.exec("COMMIT;");
+            }
+            catch (e) {
+                try {
+                    this.db.exec("ROLLBACK;");
+                }
+                catch { }
+                throw e;
+            }
+            if (changes > 100) {
+                this.gcTimeout = Math.max(Math.floor(this.gcTimeout * (1 - GC_TIMEOUT_STEP)), MIN_GC_TIMEOUT);
+            }
+            else if (changes < 10) {
+                this.gcTimeout = Math.min(Math.floor(this.gcTimeout * (1 + GC_TIMEOUT_STEP)), MAX_GC_TIMEOUT);
+            }
+        }
+        finally {
+            setTimeout(() => {
+                this.gc();
+            }, this.gcTimeout);
+        }
+    }
+    subscribe(callback) {
+        this.subscribers.add(callback);
+        return () => {
+            this.subscribers.delete(callback);
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
+export interface CacheEntry {
+    data?: Json | null;
+    attachment?: Uint8Array | null;
+}
+export interface Subscription {
+    (tags: string[], meta?: Json): void;
+}
+export interface Cache {
+    get(key: string): Promise<CacheEntry | null>;
+    set(input: CacheEntry & {
+        key: string;
+        ttl: number;
+        tags: string[];
+    }): Promise<void>;
+    delete(tags: string[], meta?: {
+        clientId?: string;
+    }): Promise<void>;
+    subscribe(callback: Subscription): () => void;
+}
+//# 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":"AAAA,MAAM,MAAM,IAAI,GACZ,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,IAAI,EAAE,GACN;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE5B,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,KAAK;IACpB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC7C,GAAG,CACD,KAAK,EAAE,UAAU,GAAG;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAC/D,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,SAAS,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,IAAI,CAAC;CAC/C"}

package/dist/no-cache.d.ts

@@ -0,0 +1,13 @@
+import type { Cache, CacheEntry, Subscription } from "./index";
+export declare class NoCache implements Cache {
+    subscribers: Set<Subscription>;
+    get(_key: string): Promise<CacheEntry | null>;
+    set(_: CacheEntry & {
+        key: string;
+        ttl: number;
+        tags: string[];
+    }): Promise<void>;
+    delete(tags: string[]): Promise<void>;
+    subscribe(callback: Subscription): () => void;
+}
+//# sourceMappingURL=no-cache.d.ts.map

package/dist/no-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-cache.d.ts","sourceRoot":"","sources":["../src/no-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE/D,qBAAa,OAAQ,YAAW,KAAK;IACnC,WAAW,oBAA2B;IAEhC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAInD,GAAG,CACD,CAAC,EAAE,UAAU,GAAG;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,EAAE,CAAC;KAChB,GACA,OAAO,CAAC,IAAI,CAAC;IAIhB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrC,SAAS,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,IAAI;CAO9C"}

package/dist/no-cache.js

@@ -0,0 +1,21 @@
+export class NoCache {
+    subscribers = new Set();
+    async get(_key) {
+        return null;
+    }
+    set(_) {
+        return Promise.resolve();
+    }
+    delete(tags) {
+        for (const callback of this.subscribers) {
+            callback(tags);
+        }
+        return Promise.resolve();
+    }
+    subscribe(callback) {
+        this.subscribers.add(callback);
+        return () => {
+            this.subscribers.delete(callback);
+        };
+    }
+}

package/dist/postgres-cache.d.ts

@@ -0,0 +1,54 @@
+import type { Pool, PoolClient } from "pg";
+import type { Cache, CacheEntry, Json, Subscription } from "./index";
+export interface PostgresCacheOptions {
+    /**
+     * When `true` (the default) the required tables and indexes are created
+     * lazily on the first operation via `CREATE TABLE IF NOT EXISTS`. Set to
+     * `false` if you manage the schema yourself (e.g. via migrations).
+     */
+    createSchema?: boolean;
+    /**
+     * The Postgres schema to hold the cache tables. Defaults to whatever the
+     * connection's `search_path` resolves to (usually `public`). When set, the
+     * tables are fully qualified as `<schema>.cache_entries` /
+     * `<schema>.cache_tags` and — with `createSchema` enabled — the schema is
+     * created if it does not already exist. Each schema also gets its own
+     * invalidation channel so caches on different schemas do not cross-notify.
+     */
+    schema?: string;
+}
+export declare class PostgresCache implements Cache {
+    private pool;
+    private options;
+    subscriptions: Set<Subscription>;
+    listener?: PoolClient;
+    gcTimeout: number;
+    private ready;
+    private gcTimer?;
+    private stopped;
+    /** Fully-qualified (schema-prefixed when applicable) table identifiers. */
+    private readonly entriesTable;
+    private readonly tagsTable;
+    /** Invalidation channel, namespaced by schema so schemas stay isolated. */
+    private readonly channel;
+    constructor(pool: Pool, options?: PostgresCacheOptions);
+    private setup;
+    get(key: string): Promise<CacheEntry | null>;
+    set({ key, data, attachment, ttl, tags, }: CacheEntry & {
+        key: string;
+        ttl: number;
+        tags: string[];
+    }): Promise<void>;
+    delete(tags: string[], meta?: Json): Promise<void>;
+    private setupListener;
+    subscribe(callback: Subscription): () => void;
+    private gc;
+    /**
+     * Stops the background garbage collector and releases the dedicated
+     * invalidation listener connection back to the pool. Call this before
+     * shutting down so no timers or connections are left dangling. The
+     * underlying pool is left untouched — the caller owns its lifecycle.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=postgres-cache.d.ts.map

package/dist/postgres-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-cache.d.ts","sourceRoot":"","sources":["../src/postgres-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAgB,MAAM,IAAI,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAkBrE,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,aAAc,YAAW,KAAK;IAgBvC,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,OAAO;IAhBjB,aAAa,oBAA2B;IACxC,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,SAAS,SAAkB;IAE3B,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAgC;IAChD,OAAO,CAAC,OAAO,CAAS;IAExB,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAGvB,IAAI,EAAE,IAAI,EACV,OAAO,GAAE,oBAAyB;YAW9B,KAAK;IA8Bb,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAqB5C,GAAG,CAAC,EACR,GAAG,EACH,IAAI,EACJ,UAAU,EACV,GAAG,EACH,IAAI,GACL,EAAE,UAAU,GAAG;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,EAAE,CAAC;KAChB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkDX,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;YAkB1C,aAAa;IAiB3B,SAAS,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,IAAI;YAgB/B,EAAE;IA6BhB;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAW7B"}

package/dist/postgres-cache.js

@@ -0,0 +1,193 @@
+const CHANNEL = "tag_based_cache_invalidate";
+const MIN_GC_TIMEOUT = 5 * 1000;
+const MAX_GC_TIMEOUT = 5 * 60 * 1000;
+const GC_TIMEOUT_STEP = 0.1;
+/** Quote a Postgres identifier so it can be safely interpolated into SQL. */
+function quoteIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+export class PostgresCache {
+    pool;
+    options;
+    subscriptions = new Set();
+    listener;
+    gcTimeout = MIN_GC_TIMEOUT;
+    ready;
+    gcTimer;
+    stopped = false;
+    /** Fully-qualified (schema-prefixed when applicable) table identifiers. */
+    entriesTable;
+    tagsTable;
+    /** Invalidation channel, namespaced by schema so schemas stay isolated. */
+    channel;
+    constructor(pool, options = {}) {
+        this.pool = pool;
+        this.options = options;
+        const { schema } = options;
+        const prefix = schema ? `${quoteIdentifier(schema)}.` : "";
+        this.entriesTable = `${prefix}cache_entries`;
+        this.tagsTable = `${prefix}cache_tags`;
+        this.channel = schema ? `${CHANNEL}:${schema}` : CHANNEL;
+        this.ready = this.setup();
+    }
+    async setup() {
+        if (this.options.createSchema !== false) {
+            if (this.options.schema) {
+                await this.pool.query(`CREATE SCHEMA IF NOT EXISTS ${quoteIdentifier(this.options.schema)}`);
+            }
+            await this.pool.query(`
+        CREATE TABLE IF NOT EXISTS ${this.entriesTable} (
+          key TEXT PRIMARY KEY,
+          data JSONB,
+          attachment BYTEA,
+          added_at BIGINT NOT NULL,
+          expires_at BIGINT NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS ${this.tagsTable} (
+          key TEXT NOT NULL REFERENCES ${this.entriesTable}(key) ON DELETE CASCADE,
+          tag TEXT NOT NULL,
+          PRIMARY KEY (key, tag)
+        );
+        CREATE INDEX IF NOT EXISTS cache_tags_tag_idx ON ${this.tagsTable} (tag);
+        CREATE INDEX IF NOT EXISTS cache_entries_expires_at_idx
+          ON ${this.entriesTable} (expires_at);
+      `);
+        }
+        this.gcTimer = setTimeout(() => this.gc(), this.gcTimeout);
+    }
+    async get(key) {
+        await this.ready;
+        const { rows } = await this.pool.query(`
+        SELECT data, attachment
+        FROM ${this.entriesTable}
+        WHERE key = $1 AND expires_at >= $2
+      `, [key, Date.now()]);
+        const row = rows[0];
+        if (!row)
+            return null;
+        return {
+            data: row.data ?? null,
+            attachment: row.attachment ? new Uint8Array(row.attachment) : null,
+        };
+    }
+    async set({ key, data, attachment, ttl, tags, }) {
+        await this.ready;
+        const client = await this.pool.connect();
+        try {
+            await client.query("BEGIN");
+            await client.query(`
+          INSERT INTO ${this.entriesTable} (key, data, attachment, added_at, expires_at)
+          VALUES ($1, $2, $3, $4, $5)
+          ON CONFLICT (key) DO UPDATE SET
+            data = EXCLUDED.data,
+            attachment = EXCLUDED.attachment,
+            added_at = EXCLUDED.added_at,
+            expires_at = EXCLUDED.expires_at
+        `, [
+                key,
+                data ? JSON.stringify(data) : null,
+                attachment ? Buffer.from(attachment) : null,
+                Date.now(),
+                Date.now() + ttl * 1000,
+            ]);
+            // Replace the full tag set so tags removed since the last `set` are
+            // dropped, matching the `INSERT OR REPLACE` semantics of the SQLite
+            // implementations.
+            await client.query(`DELETE FROM ${this.tagsTable} WHERE key = $1`, [key]);
+            for (const tag of tags) {
+                await client.query(`INSERT INTO ${this.tagsTable} (key, tag) VALUES ($1, $2)
+             ON CONFLICT DO NOTHING`, [key, tag]);
+            }
+            await client.query("COMMIT");
+        }
+        catch (e) {
+            try {
+                await client.query("ROLLBACK");
+            }
+            catch { }
+            throw e;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async delete(tags, meta) {
+        await this.ready;
+        // `cache_tags` rows are removed automatically via `ON DELETE CASCADE`.
+        await this.pool.query(`
+        DELETE FROM ${this.entriesTable}
+        WHERE key IN (SELECT key FROM ${this.tagsTable} WHERE tag = ANY($1))
+      `, [tags]);
+        await this.pool.query(`SELECT pg_notify($1, $2)`, [
+            this.channel,
+            JSON.stringify({ tags, meta }),
+        ]);
+    }
+    async setupListener() {
+        const listener = await this.pool.connect();
+        this.listener = listener;
+        listener.on("notification", (msg) => {
+            if (msg.channel !== this.channel || !msg.payload)
+                return;
+            const { tags, meta } = JSON.parse(msg.payload);
+            for (const callback of this.subscriptions) {
+                callback(tags, meta);
+            }
+        });
+        // LISTEN does not accept a bound parameter; the channel name is quoted so
+        // an arbitrary (schema-derived) identifier is interpolated safely.
+        await listener.query(`LISTEN ${quoteIdentifier(this.channel)}`);
+    }
+    subscribe(callback) {
+        if (this.subscriptions.size === 0) {
+            this.setupListener();
+        }
+        this.subscriptions.add(callback);
+        return () => {
+            this.subscriptions.delete(callback);
+            if (this.subscriptions.size === 0) {
+                this.listener?.removeAllListeners("notification");
+                this.listener?.release();
+                this.listener = undefined;
+            }
+        };
+    }
+    async gc() {
+        try {
+            const result = await this.pool.query(`DELETE FROM ${this.entriesTable} WHERE expires_at < $1`, [Date.now()]);
+            const changes = result.rowCount ?? 0;
+            if (changes > 100) {
+                this.gcTimeout = Math.max(Math.floor(this.gcTimeout * (1 - GC_TIMEOUT_STEP)), MIN_GC_TIMEOUT);
+            }
+            else if (changes < 10) {
+                this.gcTimeout = Math.min(Math.floor(this.gcTimeout * (1 + GC_TIMEOUT_STEP)), MAX_GC_TIMEOUT);
+            }
+        }
+        catch {
+            // Ignore transient errors (e.g. the pool being drained on shutdown);
+            // the next tick will retry.
+        }
+        finally {
+            if (!this.stopped) {
+                this.gcTimer = setTimeout(() => this.gc(), this.gcTimeout);
+            }
+        }
+    }
+    /**
+     * Stops the background garbage collector and releases the dedicated
+     * invalidation listener connection back to the pool. Call this before
+     * shutting down so no timers or connections are left dangling. The
+     * underlying pool is left untouched — the caller owns its lifecycle.
+     */
+    async close() {
+        this.stopped = true;
+        if (this.gcTimer) {
+            clearTimeout(this.gcTimer);
+            this.gcTimer = undefined;
+        }
+        this.listener?.removeAllListeners("notification");
+        this.listener?.release();
+        this.listener = undefined;
+        this.subscriptions.clear();
+    }
+}

package/dist/redis-cache.d.ts

@@ -0,0 +1,18 @@
+import type { RedisClientType } from "@redis/client";
+import type { Cache, CacheEntry, Json, Subscription } from "./index";
+export declare class RedisCache implements Cache {
+    private redis;
+    subscriptions: Set<Subscription>;
+    subscriber?: RedisClientType;
+    constructor(redis: RedisClientType);
+    get(key: string): Promise<CacheEntry | null>;
+    set({ key, data, attachment, ttl, tags, }: CacheEntry & {
+        key: string;
+        ttl: number;
+        tags: string[];
+    }): Promise<void>;
+    delete(tags: string[], meta?: Json): Promise<void>;
+    setupSubscription(): Promise<void>;
+    subscribe(callback: Subscription): () => void;
+}
+//# sourceMappingURL=redis-cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache.d.ts","sourceRoot":"","sources":["../src/redis-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AASrE,qBAAa,UAAW,YAAW,KAAK;IAI1B,OAAO,CAAC,KAAK;IAHzB,aAAa,oBAA2B;IACxC,UAAU,CAAC,EAAE,eAAe,CAAC;gBAET,KAAK,EAAE,eAAe;IAEpC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAkB5C,GAAG,CAAC,EACR,GAAG,EACH,IAAI,EACJ,UAAU,EACV,GAAG,EACH,IAAI,GACL,EAAE,UAAU,GAAG;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,EAAE,CAAC;KAChB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBX,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBlD,iBAAiB;IAWvB,SAAS,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,IAAI;CAc9C"}

package/dist/redis-cache.js

@@ -0,0 +1,76 @@
+const BLOB_STRING_TYPE = 36;
+export class RedisCache {
+    redis;
+    subscriptions = new Set();
+    subscriber;
+    constructor(redis) {
+        this.redis = redis;
+    }
+    async get(key) {
+        const data = await this.redis.get(`data:${key}`);
+        const attachment = (await this.redis
+            .withCommandOptions({
+            typeMapping: {
+                [BLOB_STRING_TYPE]: Buffer,
+            },
+        })
+            .get(`attachment:${key}`));
+        return data || attachment
+            ? {
+                data: data ? JSON.parse(data) : null,
+                attachment: attachment ? new Uint8Array(attachment) : null,
+            }
+            : null;
+    }
+    async set({ key, data, attachment, ttl, tags, }) {
+        let promises = [];
+        if (data) {
+            promises.push(this.redis.set(`data:${key}`, JSON.stringify(data), { EX: ttl }));
+        }
+        if (attachment) {
+            promises.push(this.redis.set(`attachment:${key}`, Buffer.from(attachment), {
+                EX: ttl,
+            }));
+        }
+        for (const tag of tags) {
+            promises.push(this.redis.sAdd(`tag:${tag}`, key));
+        }
+        await Promise.all(promises);
+    }
+    async delete(tags, meta) {
+        const keys = await Promise.all(tags.map((tag) => this.redis.sMembers(`tag:${tag}`)));
+        const keySet = new Set(keys.flat());
+        const keysToDelete = tags.map((tag) => `tag:${tag}`);
+        for (const key of keySet) {
+            keysToDelete.push(`data:${key}`, `attachment:${key}`);
+        }
+        // Delete all the keys if there are any
+        if (keysToDelete.length > 0) {
+            await this.redis.del(keysToDelete);
+        }
+        await this.redis.publish("invalidate", JSON.stringify({ tags, meta }));
+    }
+    async setupSubscription() {
+        this.subscriber = this.redis.duplicate();
+        await this.subscriber.connect();
+        await this.subscriber.subscribe("invalidate", (message) => {
+            const { tags, meta } = JSON.parse(message);
+            for (const callback of this.subscriptions) {
+                callback(tags, meta);
+            }
+        });
+    }
+    subscribe(callback) {
+        if (this.subscriptions.size === 0) {
+            this.setupSubscription();
+        }
+        this.subscriptions.add(callback);
+        return () => {
+            this.subscriptions.delete(callback);
+            if (this.subscriptions.size === 0) {
+                this.subscriber?.destroy();
+                this.subscriber = undefined;
+            }
+        };
+    }
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@toapi/cache",
+  "version": "0.3.0",
+  "author": {
+    "name": "Michel Smola",
+    "email": "michel.smola@farbenmeer.de"
+  },
+  "type": "module",
+  "module": "dist/index.js",
+  "main": "dist/index.js",
+  "private": false,
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./filesystem-cache": {
+      "default": "./dist/filesystem-cache.js",
+      "types": "./dist/filesystem-cache.d.ts"
+    },
+    "./redis-cache": {
+      "default": "./dist/redis-cache.js",
+      "types": "./dist/redis-cache.d.ts"
+    },
+    "./postgres-cache": {
+      "default": "./dist/postgres-cache.js",
+      "types": "./dist/postgres-cache.d.ts"
+    },
+    "./in-memory-cache": {
+      "default": "./dist/in-memory-cache.js",
+      "types": "./dist/in-memory-cache.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "@types/pg": "^8.0.0",
+    "vitest": "^4.0.16",
+    "typescript": "^6.0.0",
+    "@redis/client": "^6.0.0",
+    "pg": "^8.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/farbenmeer/tapi.git"
+  },
+  "peerDependencies": {
+    "@redis/client": "^5.10.0 || ^6.0.0",
+    "pg": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@redis/client": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc --noEmit false",
+    "release": "pnpm build && pnpm publish --no-git-checks",
+    "test": "vitest"
+  }
+}