@toapi/client 1.2.5 → 1.3.0

package/README.md

@@ -0,0 +1,24 @@
+# @toapi/client
+
+The typed fetch client for Toapi: a proxy that mirrors your [@toapi/server](https://www.npmjs.com/package/@toapi/server) API, with deduplication, tag-based revalidation, and subscriptions.
+
+📚 [Docs](https://toapi-js.github.io/toapi/client/)
+
+## Installation
+
+```bash
+npm install @toapi/client
+```
+
+## Quick start
+
+```ts
+import { createFetchClient } from "@toapi/client";
+import type { api } from "./api"; // the type of your server's defineApi(...)
+
+const client = createFetchClient<typeof api.routes>("https://example.com/api");
+
+const users = await client.users.get();
+await client.users.post({ name: "Alice" });
+const user = await client.users["123"].get();
+```

package/dist/build-observable.d.ts

@@ -0,0 +1,13 @@
+import type { Observable } from "@toapi/common";
+import type { PubSub } from "./pub-sub.js";
+import type { Cache } from "./cache.js";
+interface Options {
+    fetch(url: string, init: RequestInit): Promise<Response>;
+    url: string;
+    init: RequestInit;
+    pubSub: PubSub;
+    cache: Cache;
+}
+export declare function buildObservable(options: Options): Observable<unknown> & Promise<unknown>;
+export {};
+//# sourceMappingURL=build-observable.d.ts.map

package/dist/build-observable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-observable.d.ts","sourceRoot":"","sources":["../src/build-observable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,UAAU,OAAO;IACf,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,KAAK,CAAC;CACd;AAMD,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,GACf,UAAU,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAmBxC"}

package/dist/build-observable.js

@@ -0,0 +1,19 @@
+import { request } from "./request.js";
+export function buildObservable(options) {
+    const { url, pubSub } = options;
+    const { data } = request(options);
+    function subscribe(callback) {
+        const { data } = request(options);
+        callback(data);
+        return pubSub.subscribe(async (invalidUrls) => {
+            if (invalidUrls.has(url)) {
+                const { data } = request(options);
+                callback(data);
+            }
+        });
+    }
+    return Object.assign(data, {
+        subscribe,
+        queryKey: url,
+    });
+}

package/dist/cache.d.ts

@@ -1,27 +1,30 @@
 import { type Logger } from "@toapi/common";
-import { type ObservablePromise } from "./state-machine.js";
+import type { Metadata } from "./extract-metadata.js";
+import type { PubSub } from "./pub-sub.js";
+export interface CacheEntry {
+    response: Promise<Response>;
+    meta: Promise<Metadata>;
+    data: Promise<unknown>;
+}
 interface Options {
-    minTTL?: number;
     maxOverdueTTL?: number;
     logger?: Logger;
+    minTTL: number;
+    pubSub: PubSub;
 }
 export declare class Cache {
     private storage;
     private tagIndex;
-    private minTTL;
     private maxOverdueTTL;
+    private minTTL;
     private errorLog;
+    private pubSub;
     constructor(options: Options);
-    request(url: string, fetch: () => Promise<Response>): ObservablePromise;
-    private setResolveHook;
-    revalidateUrl(url: string): Promise<void>;
-    revalidateTags(tags: string[]): Promise<void>;
-    private evictEntry;
-    private loadFreshData;
-    private subscribe;
-    private unsubscribe;
-    private setTimer;
-    private extractMetadata;
+    set(url: string, entry: CacheEntry): void;
+    get(url: string): CacheEntry | undefined;
+    invalidateUrl(url: string): Promise<void>;
+    invalidateTags(tags: string[]): Promise<void>;
+    invalidateAll(): Promise<void>;
 }
 export {};
 //# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,MAAM,EAEZ,MAAM,eAAe,CAAC;AAEvB,OAAO,EAGL,KAAK,iBAAiB,EAKvB,MAAM,oBAAoB,CAAC;AAa5B,UAAU,OAAO;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD,qBAAa,KAAK;IAChB,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAA2C;gBAE/C,OAAO,EAAE,OAAO;IAM5B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,iBAAiB;YAwBzD,cAAc;IA+E5B,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6CnC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE;IAenC,OAAO,CAAC,UAAU;IAgBlB,OAAO,CAAC,aAAa;IAuBrB,OAAO,CAAC,SAAS;IA6CjB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,QAAQ;IA4BhB,OAAO,CAAC,eAAe;CAUxB"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5B,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CACxB;AAED,UAAU,OAAO;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,qBAAa,KAAK;IAChB,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAA2C;IAC3D,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE,OAAO;IAOrB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU;IA8ClC,GAAG,CAAC,GAAG,EAAE,MAAM;IAIf,aAAa,CAAC,GAAG,EAAE,MAAM;IAKzB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE;IAiB7B,aAAa;CAMrB"}

package/dist/cache.js

@@ -1,245 +1,88 @@
-import { EXPIRES_AT_HEADER, HttpError, TAGS_HEADER, } from "@toapi/common";
-import { handleResponse } from "./handle-response.js";
-import { init, queue, resolve, revalidate, revert, } from "./state-machine.js";
-const DEFAULT_MIN_TTL = 5 * 1000;
+import {} from "@toapi/common";
 const DEFAULT_MAX_OVERDUE_TTL = 1000;
 export class Cache {
     storage = new Map();
     tagIndex = new Map();
-    minTTL;
     maxOverdueTTL;
+    minTTL;
     errorLog;
+    pubSub;
     constructor(options) {
-        this.minTTL = options.minTTL ?? DEFAULT_MIN_TTL;
         this.maxOverdueTTL = options.maxOverdueTTL ?? DEFAULT_MAX_OVERDUE_TTL;
         this.errorLog = options.logger?.error ?? console.error;
+        this.pubSub = options.pubSub;
+        this.minTTL = options.minTTL;
     }
-    request(url, fetch) {
-        const entry = this.storage.get(url);
-        if (entry) {
-            switch (entry.state.status) {
-                case "pending":
-                case "revalidating":
-                    return entry.state.queued ?? entry.state.next;
-                case "cached":
-                    return entry.state.value;
-            }
-        }
-        else {
-            const { observable } = this.loadFreshData(url, fetch);
-            this.storage.set(url, {
-                state: init(observable),
-                queryKey: observable.queryKey,
-                fetch,
-                subscriptions: new Set(),
-                timeout: null,
-            });
-            return observable;
-        }
-    }
-    async setResolveHook(url, responsePromise, observable) {
-        try {
-            const response = await responsePromise;
-            await observable;
-            const entry = this.storage.get(url);
-            switch (entry?.state.status) {
-                case "pending": {
-                    const { tags, expiresAt } = this.extractMetadata(response);
-                    for (const tag of tags) {
-                        const urls = this.tagIndex.get(tag);
-                        if (urls) {
-                            urls.add(url);
-                        }
-                        else {
-                            this.tagIndex.set(tag, new Set([url]));
-                        }
-                    }
-                    entry.state = resolve(entry.state, observable, tags, expiresAt);
-                    this.setTimer(url, entry);
-                    return;
+    set(url, entry) {
+        this.storage.set(url, entry);
+        entry.data.catch((error) => {
+            setTimeout(() => {
+                if (this.storage.get(url) === entry) {
+                    this.storage.delete(url);
                 }
-                case "revalidating": {
-                    const { tags, expiresAt } = this.extractMetadata(response);
-                    // add url to tagIndex for new tags
-                    for (const tag of tags.difference(entry.state.tags)) {
-                        const urls = this.tagIndex.get(tag);
-                        if (urls) {
-                            urls.add(url);
-                        }
-                        else {
-                            this.tagIndex.set(tag, new Set([url]));
-                        }
-                    }
-                    // remove url from tagIndex for removed tags
-                    for (const tag of entry.state.tags.difference(tags)) {
-                        this.tagIndex.get(tag)?.delete(url);
-                    }
-                    entry.state = resolve(entry.state, observable, tags, expiresAt);
-                    this.setTimer(url, entry);
-                    return;
+            }, this.minTTL);
+            return this.errorLog(error);
+        });
+        entry.meta
+            .then(({ tags, expiresAt }) => {
+            const tagsToSet = new Set(tags);
+            // sync with tagIndex
+            for (const [tag, urls] of this.tagIndex) {
+                if (tagsToSet.delete(tag)) {
+                    urls.add(url);
+                }
+                else {
+                    urls.delete(url);
                 }
             }
-        }
-        catch (error) {
-            if (error instanceof HttpError && error.status < 500) {
-                // not found, no access etc, evict the entry
-                this.evictEntry(url);
-                return;
+            for (const tag of tagsToSet) {
+                // these are only tags that are not in the index yet
+                this.tagIndex.set(tag, new Set([url]));
             }
-            const entry = this.storage.get(url);
-            if (!entry) {
-                // evicted, ignore
+            if (!expiresAt)
                 return;
-            }
-            // log every other error
-            this.errorLog(error);
-            switch (entry.state.status) {
-                case "pending":
-                    // no point to caching a failed request
-                    this.evictEntry(url);
-                    return;
-                case "revalidating":
-                    // revert to last good state
-                    entry.state = revert(entry.state);
+            const timeUntilRevalidation = expiresAt -
+                Date.now() +
+                Math.round(Math.random() * this.maxOverdueTTL);
+            setTimeout(() => {
+                const cached = this.storage.get(url);
+                if (cached !== entry)
                     return;
-            }
-        }
+                this.storage.delete(url);
+                this.pubSub.publish(new Set([url]));
+            }, Math.max(0, timeUntilRevalidation));
+        })
+            .catch(() => { });
     }
-    revalidateUrl(url) {
-        const entry = this.storage.get(url);
-        // no entry, nothing to do
-        if (!entry)
-            return Promise.resolve();
-        // no subscribers, evict the entry
-        if (entry.subscriptions.size === 0) {
-            this.evictEntry(url);
-            return Promise.resolve();
-        }
-        const { observable, resolved } = this.loadFreshData(url, entry.fetch, entry.state.status === "revalidating"
-            ? entry.state.next
-            : Promise.resolve());
-        switch (entry.state.status) {
-            case "pending":
-                // pending is stale now, replace it with a fresh request
-                entry.state = init(observable);
-                break;
-            case "cached":
-                // revalidate
-                entry.state = revalidate(entry.state, observable);
-                break;
-            case "revalidating":
-                // already revalidating, queue
-                entry.state = queue(entry.state, observable);
-                break;
-        }
-        // notify subscribers
-        for (const callback of entry.subscriptions) {
-            callback(observable);
-        }
-        return resolved;
+    get(url) {
+        return this.storage.get(url);
     }
-    async revalidateTags(tags) {
-        // collect urls to revalidate
-        let urls = new Set();
+    invalidateUrl(url) {
+        this.storage.delete(url);
+        return this.pubSub.publish(new Set([url]));
+    }
+    invalidateTags(tags) {
+        const urls = new Set();
         for (const tag of tags) {
             const taggedUrls = this.tagIndex.get(tag);
             if (!taggedUrls)
                 continue;
-            urls = urls.union(taggedUrls);
-        }
-        // revalidate urls and wait until all are resolved or rejected
-        await Promise.allSettled(Array.from(urls).map((url) => this.revalidateUrl(url)));
-    }
-    evictEntry(url) {
-        const entry = this.storage.get(url);
-        if (!entry)
-            return;
-        switch (entry.state.status) {
-            case "cached":
-            case "revalidating":
-                // remove tags from index
-                for (const tag of entry.state.tags) {
-                    this.tagIndex.get(tag)?.delete(url);
+            for (const url of taggedUrls) {
+                if (this.storage.has(url)) {
+                    this.storage.delete(url);
                 }
+                else {
+                    taggedUrls.delete(url);
+                }
+                urls.add(url);
+            }
         }
-        this.storage.delete(url);
-    }
-    loadFreshData(url, fetch, waitFor = Promise.resolve()) {
-        // actually load fresh data
-        const responsePromise = waitFor.then(() => fetch());
-        const observable = Object.assign(responsePromise.then(handleResponse), {
-            // A response promise changes on every refresh, but the query does not.
-            // An object also separates identical URLs on different client caches.
-            queryKey: this.storage.get(url)?.queryKey ?? {},
-            subscribe: (callback) => this.subscribe(url, fetch, callback),
-        });
-        const resolved = this.setResolveHook(url, responsePromise, observable);
-        return { observable, resolved };
-    }
-    subscribe(url, fetch, callback) {
-        const entry = this.storage.get(url);
-        if (!entry) {
-            // has been evicted
-            const { observable } = this.loadFreshData(url, fetch);
-            const newEntry = {
-                state: init(observable),
-                queryKey: observable.queryKey,
-                fetch,
-                subscriptions: new Set([callback]),
-                timeout: null,
-            };
-            this.storage.set(url, newEntry);
-            callback(observable);
-            return () => this.unsubscribe(url, newEntry, callback);
-        }
-        // set up subscription
-        entry.subscriptions.add(callback);
-        if (entry.subscriptions.size === 1) {
-            // was scheduled for eviction, reset the timer
-            this.setTimer(url, entry);
-        }
-        // Immediately push the current value to the new subscriber
-        // so it doesn't miss any updates
-        switch (entry.state.status) {
-            case "cached":
-                callback(entry.state.value);
-                break;
-            case "pending":
-            case "revalidating":
-                callback(entry.state.queued ?? entry.state.next);
-                break;
-        }
-        return () => this.unsubscribe(url, entry, callback);
-    }
-    unsubscribe(url, entry, callback) {
-        entry.subscriptions.delete(callback);
-        this.setTimer(url, entry);
-    }
-    setTimer(url, entry) {
-        if (entry.timeout) {
-            clearTimeout(entry.timeout);
-        }
-        if (entry.subscriptions.size === 0) {
-            // no active subscriptions, set up eviction timer
-            entry.timeout = setTimeout(() => this.evictEntry(url), this.minTTL);
-            return;
-        }
-        if (entry.state.status === "cached" && entry.state.expiresAt) {
-            // entry expires, set up revalidation timer
-            const timeUntilRevalidation = entry.state.expiresAt -
-                Date.now() +
-                Math.round(Math.random() * this.maxOverdueTTL);
-            entry.timeout = setTimeout(() => this.revalidateUrl(url), Math.max(0, timeUntilRevalidation));
-            return;
-        }
-        // no timeout necessary
-        entry.timeout = null;
+        return this.pubSub.publish(urls);
     }
-    extractMetadata(response) {
-        const expiresAtHeader = response.headers.get(EXPIRES_AT_HEADER);
-        return {
-            tags: new Set(response.headers.get(TAGS_HEADER)?.split(" ") ?? []),
-            expiresAt: expiresAtHeader ? parseInt(expiresAtHeader, 10) : undefined,
-        };
+    invalidateAll() {
+        const urls = new Set(this.storage.keys());
+        this.storage.clear();
+        this.tagIndex.clear();
+        return this.pubSub.publish(urls);
     }
 }

package/dist/create-fetch-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-fetch-client.d.ts","sourceRoot":"","sources":["../src/create-fetch-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,IAAI,IAAI,QAAQ,EAChB,SAAS,EACT,MAAM,EACN,YAAY,EACb,MAAM,eAAe,CAAC;AAOvB,OAAO,KAAK,EAAE,MAAM,EAAgB,MAAM,mBAAmB,CAAC;AAiC9D,UAAU,OAAO;IACf,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CACnC;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,SAAS,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC,EACxD,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,OAAY,GAyGpB,MAAM,CAAC,MAAM,CAAC,CAChC"}
+{"version":3,"file":"create-fetch-client.d.ts","sourceRoot":"","sources":["../src/create-fetch-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,IAAI,IAAI,QAAQ,EAChB,SAAS,EACT,MAAM,EACN,YAAY,EACb,MAAM,eAAe,CAAC;AAIvB,OAAO,KAAK,EAAE,MAAM,EAAgB,MAAM,mBAAmB,CAAC;AAO9D,UAAU,OAAO;IACf,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CACnC;AAID,wBAAgB,iBAAiB,CAC/B,MAAM,SAAS,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC,EACxD,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,OAAY,GAkGpB,MAAM,CAAC,MAAM,CAAC,CAChC"}

package/dist/create-fetch-client.js

@@ -1,80 +1,54 @@
-import { INVALIDATION_POST_EVENT, INVALIDATIONS_ROUTE, TAGS_HEADER, } from "@toapi/common";
+import { INVALIDATIONS_ROUTE, TAGS_HEADER } from "@toapi/common";
+import { buildObservable } from "./build-observable.js";
 import { Cache } from "./cache.js";
 import { handleResponse } from "./handle-response.js";
+import { listenForInvalidations } from "./invalidation-stream.js";
+import { PubSub } from "./pub-sub.js";
 const globalFetch = fetch;
-async function listenForInvalidations(url, cache) {
-    const MAX_ATTEMPTS = 1000;
-    for (let retry = 0; retry < MAX_ATTEMPTS; retry++) {
-        try {
-            const res = await globalFetch(url);
-            if (!res.ok || !res.body)
-                break;
-            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() ?? "";
-                for (const line of lines) {
-                    const rawTags = line.trim();
-                    if (!rawTags)
-                        continue;
-                    await cache.revalidateTags(rawTags.split(" "));
-                }
-            }
-        }
-        catch {
-            // network error — retry below
-        }
-        await new Promise((resolve) => setTimeout(resolve, 500 * Math.pow(2, Math.min(retry, 10))));
-    }
-}
+const DEFAULT_MIN_TTL = 100;
 export function createFetchClient(apiUrl, options = {}) {
     const fetch = options.fetch ?? globalFetch;
+    const minTTL = options?.minTTL ?? DEFAULT_MIN_TTL;
+    const pubSub = new PubSub({
+        minTTL,
+    });
     const cache = new Cache({
-        minTTL: options.minTTL,
         maxOverdueTTL: options.maxOverdueTTL,
         logger: options.logger,
+        pubSub,
+        minTTL,
     });
     const invalidationsUrl = options.invalidationsUrl === false
         ? null
         : (options.invalidationsUrl ?? apiUrl + INVALIDATIONS_ROUTE);
-    if ("serviceWorker" in navigator) {
-        navigator.serviceWorker.addEventListener("message", async (event) => {
-            if (typeof event.data === "object" &&
-                event.data !== null &&
-                "type" in event.data &&
-                event.data.type === INVALIDATION_POST_EVENT) {
-                try {
-                    await cache.revalidateTags(event.data.tags);
-                }
-                catch (error) {
-                    console.warn("TApi: Failed to revalidate tags: received invalid post message", event.data);
-                }
-            }
-        });
-        if (invalidationsUrl && !navigator.serviceWorker.controller) {
-            listenForInvalidations(invalidationsUrl, cache);
-        }
-    }
-    else if (invalidationsUrl && typeof window !== "undefined") {
-        listenForInvalidations(invalidationsUrl, cache);
-    }
+    listenForInvalidations({
+        fetch,
+        onInvalidate: (tags) => cache.invalidateTags(tags),
+        onConnect: () => cache.invalidateAll(),
+        logger: options.logger,
+        invalidationsUrl,
+    });
     function load(url, init = {}) {
-        return cache.request(url, () => fetch(url, {
-            method: "GET",
-            ...init,
-        }));
+        return buildObservable({
+            fetch,
+            url,
+            init: {
+                method: "GET",
+                ...init,
+            },
+            pubSub,
+            cache,
+        });
     }
     async function revalidate(url) {
-        await cache.revalidateUrl(url);
+        await cache.invalidateUrl(url);
     }
     function mutate(method, url, data, init = {}) {
         const headers = new Headers(init.headers);
         if (!(data instanceof FormData) && !headers.has("Content-Type")) {
             headers.set("Content-Type", "application/json");
         }
-        const res = fetch(url, {
+        const response = fetch(url, {
             method,
             body: typeof data === "undefined"
                 ? undefined
@@ -84,14 +58,18 @@ export function createFetchClient(apiUrl, options = {}) {
             ...init,
             headers,
         });
-        const revalidationPromise = res.then((res) => cache.revalidateTags(res.headers.get(TAGS_HEADER)?.split(" ") ?? []));
-        return Object.assign(res
-            .then((res) => handleResponse(res))
-            .catch(async (error) => {
+        const body = response.then(handleResponse).catch(async (error) => {
             await options?.logger?.error?.(error);
             throw error;
-        }), {
-            revalidated: revalidationPromise,
+        });
+        const revalidated = response.then(async (res) => {
+            await Promise.all([
+                body,
+                cache.invalidateTags(res.headers.get(TAGS_HEADER)?.split(" ") ?? []),
+            ]);
+        });
+        return Object.assign(body, {
+            revalidated,
         });
     }
     return new Proxy(() => { }, {

package/dist/extract-metadata.d.ts

@@ -0,0 +1,6 @@
+export interface Metadata {
+    tags: Set<string>;
+    expiresAt?: number;
+}
+export declare function extractMetadata(response: Response): Metadata;
+//# sourceMappingURL=extract-metadata.d.ts.map

package/dist/extract-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-metadata.d.ts","sourceRoot":"","sources":["../src/extract-metadata.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAM5D"}

package/dist/extract-metadata.js

@@ -0,0 +1,8 @@
+import { EXPIRES_AT_HEADER, TAGS_HEADER } from "@toapi/common";
+export function extractMetadata(response) {
+    const expiresAtHeader = response.headers.get(EXPIRES_AT_HEADER);
+    return {
+        tags: new Set(response.headers.get(TAGS_HEADER)?.split(" ") ?? []),
+        expiresAt: expiresAtHeader ? parseInt(expiresAtHeader, 10) : undefined,
+    };
+}

package/dist/invalidation-stream.d.ts

@@ -0,0 +1,11 @@
+import { type Logger } from "@toapi/common";
+interface Options {
+    fetch: (url: string, init: RequestInit) => Promise<Response>;
+    invalidationsUrl: string | null;
+    onInvalidate(tags: string[]): Promise<void>;
+    onConnect(): Promise<void>;
+    logger?: Logger;
+}
+export declare function listenForInvalidations(options: Options): void;
+export {};
+//# sourceMappingURL=invalidation-stream.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"invalidation-stream.d.ts","sourceRoot":"","sources":["../src/invalidation-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,MAAM,EACZ,MAAM,eAAe,CAAC;AAEvB,UAAU,OAAO;IACf,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7D,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,QAoCtD"}

package/dist/invalidation-stream.js

@@ -0,0 +1,85 @@
+import { INVALIDATION_POST_EVENT, CONNECT_POST_EVENT, } from "@toapi/common";
+export function listenForInvalidations(options) {
+    const { onInvalidate, onConnect, logger } = options;
+    const warn = logger?.warn ?? console.warn;
+    if ("serviceWorker" in navigator) {
+        navigator.serviceWorker.addEventListener("message", async (event) => {
+            if (typeof event.data === "object" &&
+                event.data !== null &&
+                "type" in event.data) {
+                switch (event.data.type) {
+                    case INVALIDATION_POST_EVENT: {
+                        try {
+                            await onInvalidate(event.data.tags);
+                        }
+                        catch (error) {
+                            warn(`TApi: Failed to revalidate tags: received invalid post message ${JSON.stringify(event.data)}`);
+                        }
+                        return;
+                    }
+                    case CONNECT_POST_EVENT: {
+                        await onConnect();
+                        return;
+                    }
+                }
+            }
+        });
+        if (!navigator.serviceWorker.controller) {
+            fetchInvalidationStream(options);
+        }
+    }
+    else if (typeof window !== "undefined") {
+        fetchInvalidationStream(options);
+    }
+}
+async function fetchInvalidationStream({ fetch, onInvalidate, invalidationsUrl, onConnect, logger, }) {
+    if (!invalidationsUrl)
+        return;
+    const warn = logger?.warn ?? console.warn;
+    const info = logger?.info ?? console.info;
+    const MAX_ATTEMPTS = 500;
+    for (let retry = 0; retry < MAX_ATTEMPTS; retry++) {
+        try {
+            const res = await fetch(invalidationsUrl, {});
+            if (!res.ok)
+                throw `${res.status} ${res.statusText}`;
+            if (!res.body) {
+                throw `Invalidation stream response has no body`;
+            }
+            // reset retry counter
+            retry = 0;
+            // invalidate everything in the cache, it might have gone stale while we were not listening
+            await onConnect();
+            info("Invalidations stream connection established");
+            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() ?? "";
+                for (const line of lines) {
+                    const rawTags = line.trim();
+                    if (!rawTags)
+                        continue;
+                    await onInvalidate(rawTags.split(" "));
+                }
+            }
+        }
+        catch (error) {
+            const formattedError = error instanceof Error
+                ? `${error.name} ${error.message}`
+                : String(error);
+            warn(`Reconnecting to invalidation stream after error: ${formattedError}`);
+        }
+        finally {
+            // error or stream ended, retry with exponential backoff
+            await new Promise((resolve) => 
+            // so the retry interval is roughly
+            // 0.55s, 0.61s, 0.66s, 0.73s
+            // growing exponentially up to 1.9hours and then stays constant
+            // for about 63 days before it throws an error
+            setTimeout(resolve, 500 * Math.pow(1.1, Math.min(retry, 100))));
+        }
+    }
+    throw new Error("Failed to reconnect to invalidation stream");
+}

package/dist/pub-sub.d.ts

@@ -1,11 +1,15 @@
+type Subscription = (urls: Set<string>) => Promise<void>;
+interface Options {
+    minTTL: number;
+}
 export declare class PubSub {
     private subscriptions;
-    private onClear;
-    constructor({ onClear }: {
-        onClear: (url: string) => void;
-    });
-    subscribe(url: string, callback: (data: Promise<unknown>) => void): () => void;
-    publish(url: string, data: Promise<unknown>): void;
-    has(url: string): boolean;
+    private debounceTimeouts;
+    private requestedUrls;
+    private minTTL;
+    constructor(options: Options);
+    subscribe(callback: Subscription): () => void;
+    publish(urls: Set<string>): Promise<void>;
 }
+export {};
 //# sourceMappingURL=pub-sub.d.ts.map

package/dist/pub-sub.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pub-sub.d.ts","sourceRoot":"","sources":["../src/pub-sub.ts"],"names":[],"mappings":"AAAA,qBAAa,MAAM;IACjB,OAAO,CAAC,aAAa,CAGjB;IACJ,OAAO,CAAC,OAAO,CAAwB;gBAE3B,EAAE,OAAO,EAAE,EAAE;QAAE,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE;IAI3D,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI;IAgBjE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC;IAS3C,GAAG,CAAC,GAAG,EAAE,MAAM;CAGhB"}
+{"version":3,"file":"pub-sub.d.ts","sourceRoot":"","sources":["../src/pub-sub.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEzD,UAAU,OAAO;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,MAAM;IACjB,OAAO,CAAC,aAAa,CAA2B;IAChD,OAAO,CAAC,gBAAgB,CAAoD;IAC5E,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE,OAAO;IAI5B,SAAS,CAAC,QAAQ,EAAE,YAAY;IAO1B,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC;CAkChC"}

package/dist/pub-sub.js

@@ -1,33 +1,39 @@
 export class PubSub {
-    subscriptions = new Map();
-    onClear;
-    constructor({ onClear }) {
-        this.onClear = onClear;
+    subscriptions = new Set();
+    debounceTimeouts = new Map();
+    requestedUrls = new Set();
+    minTTL;
+    constructor(options) {
+        this.minTTL = options.minTTL;
     }
-    subscribe(url, callback) {
-        let urlSubscriptions = this.subscriptions.get(url);
-        if (!urlSubscriptions) {
-            urlSubscriptions = new Set();
-            this.subscriptions.set(url, urlSubscriptions);
-        }
-        urlSubscriptions.add(callback);
+    subscribe(callback) {
+        this.subscriptions.add(callback);
         return () => {
-            urlSubscriptions.delete(callback);
-            if (urlSubscriptions.size === 0) {
-                this.subscriptions.delete(url);
-                this.onClear(url);
-            }
+            this.subscriptions.delete(callback);
         };
     }
-    publish(url, data) {
-        const urlSubscriptions = this.subscriptions.get(url);
-        if (urlSubscriptions) {
-            for (const callback of urlSubscriptions.values()) {
-                callback(data);
+    async publish(urls) {
+        for (const url of urls) {
+            if (this.debounceTimeouts.has(url)) {
+                // debounced, mark as requested and ignore now
+                this.requestedUrls.add(url);
+                urls.delete(url);
             }
         }
-    }
-    has(url) {
-        return this.subscriptions.has(url);
+        const timeout = setTimeout(() => Promise.all(Array.from(urls).map((url) => {
+            if (this.requestedUrls.has(url)) {
+                this.debounceTimeouts.delete(url);
+                // needs to be refetched
+                return this.publish(urls);
+            }
+            else {
+                // debounce timeout over
+                this.debounceTimeouts.delete(url);
+            }
+        })), this.minTTL);
+        for (const url of urls) {
+            this.debounceTimeouts.set(url, timeout);
+        }
+        await Promise.all(this.subscriptions.values().map((callback) => callback(urls)));
     }
 }

package/dist/request.d.ts

@@ -0,0 +1,10 @@
+import type { Cache, CacheEntry } from "./cache.js";
+interface Options {
+    fetch(url: string, init: RequestInit): Promise<Response>;
+    url: string;
+    cache: Cache;
+    init: RequestInit;
+}
+export declare function request(options: Options): CacheEntry;
+export {};
+//# sourceMappingURL=request.d.ts.map

package/dist/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEpD,UAAU,OAAO;IACf,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,CAqBpD"}

package/dist/request.js

@@ -0,0 +1,21 @@
+import { extractMetadata } from "./extract-metadata.js";
+import { handleResponse } from "./handle-response.js";
+export function request(options) {
+    const { fetch, url, cache, init } = options;
+    const cached = cache.get(url);
+    if (cached)
+        return cached;
+    const response = fetch(url, init);
+    const data = response.then(handleResponse);
+    const meta = response.then(extractMetadata);
+    cache.set(url, {
+        response,
+        data,
+        meta,
+    });
+    return {
+        response,
+        data,
+        meta,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toapi/client",
-  "version": "1.2.5",
+  "version": "1.3.0",
   "author": {
     "name": "Michel Smola",
     "email": "michel.smola@farbenmeer.de"
@@ -20,13 +20,13 @@
     }
   },
   "dependencies": {
-    "@toapi/common": "^1.2.5"
+    "@toapi/common": "^1.3.0"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
     "vitest": "^5.0.0",
     "zod": "^4.0.17",
-    "@toapi/server": "^1.2.5"
+    "@toapi/server": "^1.3.0"
   },
   "peerDependencies": {
     "typescript": "^5 || ^6.0.0 || ^7.0.0",
@@ -34,11 +34,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/farbenmeer/tapi.git"
+    "url": "git+https://github.com/toapi-js/toapi.git"
   },
   "scripts": {
     "build": "tsc --noEmit false",
     "release": "pnpm build && pnpm publish --no-git-checks",
-    "test": "vitest"
+    "test": "vitest run"
   }
 }