@toapi/worker 0.12.1

package/dist/cache.d.ts

@@ -0,0 +1,16 @@
+export declare const META_STORE_NAME = "meta";
+export declare const TAGS_STORE_NAME = "tags";
+export interface CacheMeta {
+    tags: string[];
+    expiresAt: number | null;
+}
+export declare function openCacheMetaDB(): Promise<IDBDatabase>;
+export declare function openCache(): Promise<Cache>;
+export declare function deleteCache(): Promise<void>;
+export declare function storeCacheEntry(req: Request, res: Response): Promise<void>;
+export declare function deleteCacheEntry(req: Request): Promise<void>;
+export declare function getMetadata(url: string): Promise<CacheMeta | null>;
+export declare function getCachedEntry(req: Request): Promise<Response | undefined>;
+export declare function invalidateTags(tags: string[]): Promise<void>;
+export declare function expireAll(): Promise<string[]>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,eAAe,SAAS,CAAC;AACtC,eAAO,MAAM,eAAe,SAAS,CAAC;AAEtC,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAKD,wBAAgB,eAAe,yBAS9B;AAED,wBAAgB,SAAS,mBAMxB;AAED,wBAAsB,WAAW,kBAIhC;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,iBAiChE;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,OAAO,iBAmClD;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,6BAU5C;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,OAAO,iCAGhD;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,iBA4BlD;AAED,wBAAsB,SAAS,sBAwB9B"}

package/dist/cache.js

@@ -0,0 +1,141 @@
+import { EXPIRES_AT_HEADER, TAGS_HEADER } from "@toapi/common";
+import { deleteDB, openDB } from "./idb";
+const DB_NAME = "tapi-cache-meta";
+const CACHE_NAME = "tapi-cache";
+const DB_VERSION = 1;
+export const META_STORE_NAME = "meta";
+export const TAGS_STORE_NAME = "tags";
+let metaDb = null;
+let cache = null;
+export function openCacheMetaDB() {
+    if (metaDb)
+        return metaDb;
+    metaDb = openDB(DB_NAME, DB_VERSION, (db) => {
+        db.createObjectStore(META_STORE_NAME);
+        db.createObjectStore(TAGS_STORE_NAME);
+    });
+    return metaDb;
+}
+export function openCache() {
+    if (cache)
+        return cache;
+    cache = self.caches.open(CACHE_NAME);
+    return cache;
+}
+export async function deleteCache() {
+    metaDb = null;
+    cache = null;
+    await Promise.all([deleteDB(DB_NAME), self.caches.delete(CACHE_NAME)]);
+}
+export async function storeCacheEntry(req, res) {
+    const [metaDb, cache] = await Promise.all([openCacheMetaDB(), openCache()]);
+    const url = req.url;
+    const expiresAt = res.headers.get(EXPIRES_AT_HEADER);
+    const meta = {
+        tags: res.headers.get(TAGS_HEADER)?.split(" ").filter(Boolean) ?? [],
+        expiresAt: expiresAt ? parseInt(expiresAt, 10) : null,
+    };
+    await new Promise(async (resolve, reject) => {
+        const tx = metaDb.transaction([META_STORE_NAME, TAGS_STORE_NAME], "readwrite");
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(new Error(`Failed to store metadata for "${url}"`));
+        const metaStore = tx.objectStore(META_STORE_NAME);
+        metaStore.put(meta, url);
+        const tagsStore = tx.objectStore(TAGS_STORE_NAME);
+        for (const tag of meta.tags) {
+            const req = tagsStore.get(tag);
+            req.onsuccess = () => {
+                const urls = req.result ?? [];
+                urls.push(url);
+                tagsStore.put(urls, tag);
+            };
+        }
+    });
+    await cache.put(req, res.clone());
+}
+export async function deleteCacheEntry(req) {
+    const [metaDb, cache] = await Promise.all([openCacheMetaDB(), openCache()]);
+    const url = req.url;
+    await new Promise((resolve, reject) => {
+        const tx = metaDb.transaction([META_STORE_NAME, TAGS_STORE_NAME], "readwrite");
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(new Error(`Failed to clear metadata for "${url}"`));
+        const metaStore = tx.objectStore(META_STORE_NAME);
+        const tagsStore = tx.objectStore(TAGS_STORE_NAME);
+        const meta = metaStore.get(url);
+        meta.onsuccess = () => {
+            const tags = meta.result?.tags ?? [];
+            for (const tag of tags) {
+                const req = tagsStore.get(tag);
+                req.onsuccess = () => {
+                    const urls = req.result ?? [];
+                    tagsStore.put(urls.filter((u) => u !== url), tag);
+                };
+            }
+        };
+        metaStore.delete(url);
+    });
+    await cache.delete(req);
+}
+export async function getMetadata(url) {
+    const db = await openCacheMetaDB();
+    return new Promise((resolve, reject) => {
+        const tx = db.transaction(META_STORE_NAME, "readonly");
+        const metaStore = tx.objectStore(META_STORE_NAME);
+        const req = metaStore.get(url);
+        req.onsuccess = () => resolve(req.result ?? null);
+        req.onerror = () => reject(new Error(`Failed to retrieve metadata for "${url}"`));
+    });
+}
+export async function getCachedEntry(req) {
+    const cache = await openCache();
+    return cache.match(req);
+}
+export async function invalidateTags(tags) {
+    const [metaDb, cache] = await Promise.all([openCacheMetaDB(), openCache()]);
+    return new Promise((resolve, reject) => {
+        const deletes = [];
+        const tx = metaDb.transaction([TAGS_STORE_NAME, META_STORE_NAME], "readwrite");
+        tx.oncomplete = async () => {
+            await Promise.all(deletes);
+            resolve();
+        };
+        tx.onerror = () => reject(new Error(`Failed to invalidate tags ${tags.join(", ")}`));
+        const tagsStore = tx.objectStore(TAGS_STORE_NAME);
+        const metaStore = tx.objectStore(META_STORE_NAME);
+        for (const tag of tags) {
+            const req = tagsStore.get(tag);
+            req.onsuccess = () => {
+                const urls = req.result ?? [];
+                for (const url of urls) {
+                    metaStore.delete(url);
+                    deletes.push(cache.delete(url));
+                }
+                tagsStore.delete(tag);
+            };
+        }
+    });
+}
+export async function expireAll() {
+    const metaDb = await openCacheMetaDB();
+    return new Promise((resolve, reject) => {
+        const tags = new Set();
+        const tx = metaDb.transaction([META_STORE_NAME], "readwrite");
+        tx.oncomplete = () => resolve(Array.from(tags));
+        tx.onerror = () => reject(new Error(`Failed to expire all cache entries`));
+        const metaStore = tx.objectStore(META_STORE_NAME);
+        const cursorRequest = metaStore.openCursor();
+        cursorRequest.onsuccess = () => {
+            const cursor = cursorRequest.result;
+            if (!cursor)
+                return;
+            const value = cursor.value;
+            value.expiresAt = Date.now();
+            for (const tag of value.tags) {
+                tags.add(tag);
+            }
+            metaStore.put(value, cursor.key);
+            cursor.continue();
+        };
+    });
+}

package/dist/cleanup.d.ts

@@ -0,0 +1,28 @@
+export interface CleanupOptions {
+    /**
+     * Grace period in seconds past a cache entry's `expiresAt` before the
+     * entry is dropped. Entries expired within this window are kept; entries
+     * expired longer than this window are deleted from both the cache and
+     * the meta store.
+     */
+    maximumStaleAge: number;
+}
+/**
+ * Reconcile the worker's cache and metadata stores. Intended to be called
+ * from the service worker's `activate` event:
+ *
+ * ```ts
+ * self.addEventListener("activate", (event) => {
+ *   event.waitUntil(cleanup({ maximumStaleAge: 60 * 60 * 24 * 7 }));
+ * });
+ * ```
+ *
+ * Performs three things:
+ *  1. Drops cache + meta entries whose `expiresAt` is older than
+ *     `maximumStaleAge` seconds.
+ *  2. Drops cache entries that have no corresponding meta record (orphans).
+ *  3. Rebuilds the tags store from the surviving meta records, healing any
+ *     drift between the two stores.
+ */
+export declare function cleanup({ maximumStaleAge, }: CleanupOptions): Promise<void>;
+//# sourceMappingURL=cleanup.d.ts.map

package/dist/cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../src/cleanup.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,OAAO,CAAC,EAC5B,eAAe,GAChB,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAoEhC"}

package/dist/cleanup.js

@@ -0,0 +1,80 @@
+import { META_STORE_NAME, TAGS_STORE_NAME, openCache, openCacheMetaDB, } from "./cache";
+/**
+ * Reconcile the worker's cache and metadata stores. Intended to be called
+ * from the service worker's `activate` event:
+ *
+ * ```ts
+ * self.addEventListener("activate", (event) => {
+ *   event.waitUntil(cleanup({ maximumStaleAge: 60 * 60 * 24 * 7 }));
+ * });
+ * ```
+ *
+ * Performs three things:
+ *  1. Drops cache + meta entries whose `expiresAt` is older than
+ *     `maximumStaleAge` seconds.
+ *  2. Drops cache entries that have no corresponding meta record (orphans).
+ *  3. Rebuilds the tags store from the surviving meta records, healing any
+ *     drift between the two stores.
+ */
+export async function cleanup({ maximumStaleAge, }) {
+    const [metaDb, cache] = await Promise.all([openCacheMetaDB(), openCache()]);
+    const cutoff = Date.now() - maximumStaleAge * 1000;
+    const survivors = new Map();
+    const dropped = [];
+    // Pass 1: cursor meta, drop long-expired records, rebuild tags store
+    // from survivors. All in a single readwrite transaction so meta and tags
+    // can't disagree halfway through.
+    await new Promise((resolve, reject) => {
+        const tx = metaDb.transaction([META_STORE_NAME, TAGS_STORE_NAME], "readwrite");
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(new Error("Failed to clean up tapi cache"));
+        const metaStore = tx.objectStore(META_STORE_NAME);
+        const tagsStore = tx.objectStore(TAGS_STORE_NAME);
+        const cursorReq = metaStore.openCursor();
+        cursorReq.onsuccess = () => {
+            const cursor = cursorReq.result;
+            if (!cursor) {
+                // cursor done — rebuild tags store from `survivors`
+                tagsStore.clear();
+                const tagToUrls = new Map();
+                for (const [url, tags] of survivors) {
+                    for (const tag of tags) {
+                        const urls = tagToUrls.get(tag);
+                        if (urls)
+                            urls.push(url);
+                        else
+                            tagToUrls.set(tag, [url]);
+                    }
+                }
+                for (const [tag, urls] of tagToUrls) {
+                    tagsStore.put(urls, tag);
+                }
+                return;
+            }
+            const url = cursor.key;
+            const value = cursor.value;
+            if (value.expiresAt !== null && value.expiresAt < cutoff) {
+                dropped.push(url);
+                cursor.delete();
+            }
+            else {
+                survivors.set(url, value.tags);
+            }
+            cursor.continue();
+        };
+    });
+    // Delete dropped URLs from Cache Storage. Outside the IDB transaction
+    // because the Cache API is async and would auto-commit the tx.
+    await Promise.all(dropped.map((url) => cache.delete(url)));
+    // Pass 2: drop cache entries that have no surviving meta record.
+    // `survivors` already contains every URL with a (kept) meta record, so
+    // anything in the cache not in `survivors` and not in `dropped` is an
+    // orphan from a prior interrupted write.
+    const cacheKeys = await cache.keys();
+    const knownUrls = new Set(survivors.keys());
+    await Promise.all(cacheKeys.map((req) => {
+        if (knownUrls.has(req.url))
+            return Promise.resolve(true);
+        return cache.delete(req);
+    }));
+}

package/dist/idb.d.ts

@@ -0,0 +1,3 @@
+export declare function openDB(name: string, version: number, migrate: (db: IDBDatabase) => void): Promise<IDBDatabase>;
+export declare function deleteDB(name: string): Promise<void>;
+//# sourceMappingURL=idb.d.ts.map

package/dist/idb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idb.d.ts","sourceRoot":"","sources":["../src/idb.ts"],"names":[],"mappings":"AAAA,wBAAgB,MAAM,CACpB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,IAAI,GACjC,OAAO,CAAC,WAAW,CAAC,CAatB;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUpD"}

package/dist/idb.js

@@ -0,0 +1,25 @@
+export function openDB(name, version, migrate) {
+    return new Promise((resolve, reject) => {
+        const req = self.indexedDB.open(name, version);
+        req.onsuccess = () => {
+            resolve(req.result);
+        };
+        req.onerror = () => {
+            reject(new Error(`Failed to open IndexedDB Database ${name}@${version}`));
+        };
+        req.onupgradeneeded = () => {
+            migrate(req.result);
+        };
+    });
+}
+export function deleteDB(name) {
+    return new Promise((resolve, reject) => {
+        const req = self.indexedDB.deleteDatabase(name);
+        req.onsuccess = () => {
+            resolve();
+        };
+        req.onerror = () => {
+            reject(new Error(`Failed to delete IndexedDB Database ${name}`));
+        };
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { Logger } from "@toapi/common";
+export { listenForInvalidations } from "./revalidation-stream";
+export { cleanup } from "./cleanup";
+export type { CleanupOptions } from "./cleanup";
+export type { Logger } from "@toapi/common";
+export declare function handleTapiRequest(req: Request, options?: {
+    logger?: Logger;
+}): Promise<Response>;
+//# 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":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAI5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,YAAY,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,qBAmClF"}

package/dist/index.js

@@ -0,0 +1,40 @@
+import { isMutation } from "@toapi/common";
+import { getCachedEntry, getMetadata } from "./cache";
+import { mutateAndInvalidate } from "./mutate-and-invalidate";
+import { serveFromNetwork } from "./serve-from-network";
+export { listenForInvalidations } from "./revalidation-stream";
+export { cleanup } from "./cleanup";
+export async function handleTapiRequest(req, options) {
+    const errorLog = options?.logger?.error ?? ((err) => console.error("TApi Worker fetch failed", err));
+    if (isMutation(req)) {
+        return mutateAndInvalidate(req);
+    }
+    else {
+        const cachedResponse = await getCachedEntry(req);
+        if (!cachedResponse) {
+            // no cached response, serve from network
+            return serveFromNetwork(req);
+        }
+        const meta = await getMetadata(req.url);
+        if (meta?.expiresAt) {
+            if (meta.expiresAt > Date.now()) {
+                // cached response is still valid
+                return cachedResponse;
+            }
+            else {
+                // cached response is expired
+                try {
+                    // try to serve from network
+                    return serveFromNetwork(req);
+                }
+                catch (error) {
+                    // probably network not available, serve old response
+                    errorLog(error);
+                    return cachedResponse;
+                }
+            }
+        }
+        // no expiration header, serve cached response
+        return cachedResponse;
+    }
+}

package/dist/mutate-and-invalidate.d.ts

@@ -0,0 +1,2 @@
+export declare function mutateAndInvalidate(req: Request): Promise<Response>;
+//# sourceMappingURL=mutate-and-invalidate.d.ts.map

package/dist/mutate-and-invalidate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutate-and-invalidate.d.ts","sourceRoot":"","sources":["../src/mutate-and-invalidate.ts"],"names":[],"mappings":"AAGA,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,OAAO,qBAUrD"}

package/dist/mutate-and-invalidate.js

@@ -0,0 +1,11 @@
+import { TAGS_HEADER } from "@toapi/common";
+import { invalidateTags } from "./cache";
+export async function mutateAndInvalidate(req) {
+    const res = await fetch(req);
+    const tags = res.headers.get(TAGS_HEADER)?.split(" ")?.filter(Boolean) ?? [];
+    if (tags.length === 0) {
+        return res;
+    }
+    await invalidateTags(tags);
+    return res;
+}

package/dist/revalidation-stream.d.ts

@@ -0,0 +1,6 @@
+interface Options {
+    url: string;
+}
+export declare function listenForInvalidations({ url }: Options): Promise<void>;
+export {};
+//# sourceMappingURL=revalidation-stream.d.ts.map

package/dist/revalidation-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revalidation-stream.d.ts","sourceRoot":"","sources":["../src/revalidation-stream.ts"],"names":[],"mappings":"AAQA,UAAU,OAAO;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAsB,sBAAsB,CAAC,EAAE,GAAG,EAAE,EAAE,OAAO,iBAoF5D"}

package/dist/revalidation-stream.js

@@ -0,0 +1,70 @@
+import { INVALIDATION_POST_EVENT, TAGS_CONTENT_TYPE, } from "@toapi/common";
+import { deleteCache, expireAll, invalidateTags } from "./cache";
+export async function listenForInvalidations({ url }) {
+    console.info("TApi: Listening for invalidations...");
+    let res = null;
+    const MAX_ATTEMPTS = 1000;
+    for (let retry = 0; retry < MAX_ATTEMPTS; retry++) {
+        try {
+            res = await fetch(url);
+            break;
+        }
+        catch (error) {
+            console.warn(`TApi: Failed attempt #${retry + 1} to open invalidation stream`, error);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 500 * Math.pow(2, retry)));
+    }
+    if (!res) {
+        console.error(`TApi: Failed to open invalidation stream after ${MAX_ATTEMPTS} attempts, giving up.`);
+        return;
+    }
+    const contentType = res.headers.get("Content-Type");
+    if (!res.ok || contentType !== TAGS_CONTENT_TYPE || !res.body) {
+        console.error("TApi: Failed to open invalidation stream. Cleaning up and unregistering service worker.", res.status, res.statusText);
+        await deleteCache();
+        await self.registration.unregister();
+        return;
+    }
+    console.info("TApi: Invalidation Stream Connection Established");
+    try {
+        const tags = await expireAll();
+        const clients = await self.clients.matchAll();
+        for (const client of clients) {
+            client.postMessage({ type: INVALIDATION_POST_EVENT, tags });
+        }
+        console.info("TApi: Marked all cached entries as expired");
+    }
+    catch {
+        console.warn("TApi: Failed to expire existing cache entries");
+    }
+    try {
+        let buffer = "";
+        const decoder = new TextDecoder();
+        for await (const chunk of res.body) {
+            buffer += decoder.decode(chunk);
+            const lines = buffer.split("\n");
+            buffer = lines.pop() || "";
+            const clients = await self.clients.matchAll();
+            for (const line of lines) {
+                const rawTags = line.trim();
+                if (!rawTags)
+                    continue;
+                const tags = rawTags.split(" ");
+                console.info("TApi: Remote-Invalidating tags", tags);
+                await invalidateTags(tags);
+                for (const client of clients) {
+                    client.postMessage({ type: INVALIDATION_POST_EVENT, tags });
+                }
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "NetworkError") {
+            console.info("TApi: Network disconnected, retrying revalidation connection...");
+            setTimeout(() => {
+                listenForInvalidations({ url });
+            }, 5000);
+        }
+        console.error("TApi: Failed to read invalidation stream", error);
+    }
+}

package/dist/serve-from-network.d.ts

@@ -0,0 +1,2 @@
+export declare function serveFromNetwork(req: Request): Promise<Response>;
+//# sourceMappingURL=serve-from-network.d.ts.map

package/dist/serve-from-network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-from-network.d.ts","sourceRoot":"","sources":["../src/serve-from-network.ts"],"names":[],"mappings":"AAGA,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,OAAO,qBAYlD"}

package/dist/serve-from-network.js

@@ -0,0 +1,14 @@
+import { EXPIRES_AT_HEADER, TAGS_HEADER } from "@toapi/common";
+import { deleteCacheEntry, storeCacheEntry } from "./cache";
+export async function serveFromNetwork(req) {
+    const res = await fetch(req);
+    // only cache ok responses with tags or expires-at header
+    if (res.ok &&
+        (res.headers.has(TAGS_HEADER) || res.headers.has(EXPIRES_AT_HEADER))) {
+        await storeCacheEntry(req, res);
+    }
+    else {
+        await deleteCacheEntry(req);
+    }
+    return res;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@toapi/worker",
+  "version": "0.12.1",
+  "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": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@toapi/common": "^0.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "vitest": "^4.0.16"
+  },
+  "peerDependencies": {
+    "typescript": "^5 || ^6.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/farbenmeer/tapi.git"
+  },
+  "scripts": {
+    "build": "tsc --noEmit false",
+    "release": "pnpm build && pnpm publish --no-git-checks",
+    "test": "vitest run --passWithNoTests"
+  }
+}