@toapi/client 1.1.0 → 1.2.0

package/dist/api.mock.d.ts

@@ -0,0 +1,88 @@
+import { type Logger } from "@toapi/common";
+export declare const mockLogger: Logger;
+export declare const api: import("@toapi/server").ApiDefinition<{
+    "/books": import("@toapi/common").MaybePromise<import("@toapi/common").Route<{}, {
+        id: string;
+        title: string;
+    }[], {}, {
+        id: string;
+        title: string;
+    }, {}, {
+        id: string;
+        title: string;
+    }, never, never, never, never, never, never, never, never>>;
+} & {
+    "/books/:id": import("@toapi/common").MaybePromise<import("@toapi/common").Route<{
+        id: string;
+    }, {
+        id: string;
+        title: string;
+    }, {
+        test: string;
+    }, never, never, never, never, never, never, never, never, never, never, never>>;
+} & {
+    "/movies/:id": import("@toapi/common").MaybePromise<import("@toapi/common").Route<{
+        id: string;
+    }, {
+        id: string;
+        title: string;
+    }, {
+        test: string;
+    }, never, never, never, never, never, never, never, never, never, never, never>>;
+} & {
+    "/movies": import("@toapi/common").MaybePromise<import("@toapi/common").Route<{}, never, never, {
+        id: string;
+        title: string;
+    }, {}, {
+        id: string;
+        title: string;
+    }, never, never, never, never, never, never, never, never>>;
+} & {
+    "/formData": import("@toapi/common").MaybePromise<import("@toapi/common").Route<{}, never, never, {
+        [k: string]: FormDataEntryValue;
+    }, {}, undefined, never, never, never, never, never, never, never, never>>;
+} & {
+    "/authorized": import("@toapi/common").MaybePromise<import("@toapi/common").Route<{}, {
+        authorized: boolean;
+    }, {}, never, never, never, never, never, never, never, never, never, never, never>>;
+} & {
+    "/files/*path": import("@toapi/common").MaybePromise<import("@toapi/common").Route<{
+        path: string;
+    }, {
+        path: string;
+        message: string;
+    }, {}, never, never, never, never, never, never, never, never, never, never, never>>;
+} & {
+    "/wildcard/*": import("@toapi/common").MaybePromise<import("@toapi/common").Route<{}, {
+        pathname: string;
+    }, {}, never, never, never, never, never, never, never, never, never, never, never>>;
+} & {
+    "/method": import("@toapi/common").MaybePromise<import("@toapi/common").Route<{}, {
+        method: string;
+    }, {}, {
+        method: string;
+    }, {}, undefined, {
+        method: string;
+    }, {}, {
+        method: string;
+    }, {}, undefined, {
+        method: string;
+    }, {}, undefined>>;
+} & {
+    "/error/not-found": import("@toapi/common").MaybePromise<import("@toapi/common").Route<{}, unknown, {}, never, never, never, never, never, never, never, never, never, never, never>>;
+} & {
+    "/cached": import("@toapi/common").MaybePromise<import("@toapi/common").Route<{}, {
+        data: string;
+    }, {}, never, never, never, never, never, never, never, never, never, never, never>>;
+} & {
+    "/stream": import("@toapi/common").MaybePromise<import("@toapi/common").Route<{}, AsyncGenerator<{
+        value: number;
+    }, void, unknown>, {}, never, never, never, never, never, never, never, never, never, never, never>>;
+} & {
+    "/optionalQuery": import("@toapi/common").MaybePromise<import("@toapi/common").Route<{}, {
+        optional: string | undefined;
+    }, {
+        optional: string | undefined;
+    }, never, never, never, never, never, never, never, never, never, never, never>>;
+}>;
+//# sourceMappingURL=api.mock.d.ts.map

package/dist/api.mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.mock.d.ts","sourceRoot":"","sources":["../src/api.mock.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwB,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAOlE,eAAO,MAAM,UAAU,EAAE,MAA4B,CAAC;AAEtD,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0LZ,CAAC"}

package/dist/api.mock.js

@@ -0,0 +1,133 @@
+import { z } from "zod/v4";
+import { defineApi, defineHandler } from "@toapi/server";
+import { TResponse, HttpError } from "@toapi/common";
+import { beforeEach, vi } from "vitest";
+const logError = vi.fn();
+beforeEach(() => {
+    logError.mockClear();
+});
+export const mockLogger = { error: logError };
+export const api = defineApi({
+    logger: mockLogger,
+})
+    .route("/books", {
+    GET: defineHandler({ authorize: () => true }, async () => TResponse.json([
+        { id: "1", title: "Book 1" },
+        { id: "2", title: "Book 2" },
+    ])),
+    POST: defineHandler({
+        authorize: () => true,
+        body: z.object({
+            id: z.string(),
+            title: z.string(),
+        }),
+    }, async (req) => TResponse.json(await req.data())),
+})
+    .route("/books/:id", {
+    GET: defineHandler({
+        params: { id: z.string() },
+        query: { test: z.string() },
+        authorize: () => true,
+    }, async (req) => TResponse.json({
+        id: req.params().id,
+        title: `Book ${req.params().id}`,
+    })),
+})
+    .route("/movies/:id", {
+    GET: defineHandler({
+        params: { id: z.string() },
+        query: { test: z.string() },
+        authorize: () => true,
+    }, async (req) => TResponse.json({
+        id: req.params().id,
+        title: `Movie ${req.params().id}`,
+    }, {
+        cache: {
+            tags: ["movies"],
+        },
+    })),
+})
+    .route("/movies", {
+    POST: defineHandler({
+        body: z.object({ id: z.string(), title: z.string() }),
+        authorize: () => true,
+    }, async (req) => TResponse.json(await req.data(), { cache: { tags: ["movies"] } })),
+})
+    .route("/formData", {
+    POST: defineHandler({
+        authorize: () => true,
+    }, async (req) => TResponse.json(Object.fromEntries(await req.formData()), {
+        cache: { tags: ["movies"] },
+    })),
+})
+    .route("/authorized", {
+    GET: defineHandler({
+        authorize: (req) => {
+            const header = req.headers.get("Authorization");
+            return header === "Bearer token";
+        },
+    }, async () => TResponse.json({ authorized: true })),
+})
+    .route("/files/*path", {
+    GET: defineHandler({
+        params: { path: z.string() },
+        authorize: () => true,
+    }, async (req) => TResponse.json({
+        path: req.params().path,
+        message: `Accessing file: ${req.params().path}`,
+    })),
+})
+    .route("/wildcard/*", {
+    GET: defineHandler({
+        authorize: () => true,
+    }, async (req) => TResponse.json({ pathname: req.url })),
+})
+    .route("/method", {
+    GET: defineHandler({
+        authorize: () => true,
+    }, async () => TResponse.json({ method: "GET" })),
+    POST: defineHandler({
+        authorize: () => true,
+    }, async () => TResponse.json({ method: "POST" })),
+    PUT: defineHandler({
+        authorize: () => true,
+    }, async () => TResponse.json({ method: "PUT" })),
+    PATCH: defineHandler({
+        authorize: () => true,
+    }, async () => TResponse.json({ method: "PATCH" })),
+    DELETE: defineHandler({
+        authorize: () => true,
+    }, async () => TResponse.json({ method: "DELETE" })),
+})
+    .route("/error/not-found", {
+    GET: defineHandler({
+        authorize: () => true,
+    }, async () => {
+        throw new HttpError(404, "Not Found");
+    }),
+})
+    .route("/cached", {
+    GET: defineHandler({ authorize: () => true }, async () => TResponse.json({ data: "cached" }, { cache: { tags: ["cached"], ttl: 60 } })),
+})
+    .route("/stream", {
+    GET: defineHandler({
+        authorize: () => true,
+    }, async () => {
+        async function* stream() {
+            for (let i = 0; i < 5; i++) {
+                yield { value: i };
+            }
+        }
+        return TResponse.ndjson(stream());
+    }),
+})
+    .route("/optionalQuery", {
+    GET: defineHandler({
+        query: {
+            optional: z.string().optional(),
+        },
+        authorize: () => true,
+    }, async (req) => {
+        return TResponse.json(req.query());
+    }),
+});

package/dist/cache.d.ts

@@ -1,18 +1,5 @@
-import type { Logger, Observable } from "@toapi/common";
-type ObservablePromise = Promise<unknown> & Observable<unknown>;
-type Subscription = (data: Promise<unknown>) => void;
-interface CacheEntry {
-    current?: {
-        value: ObservablePromise;
-        expiresAt?: number;
-        tags: Set<string>;
-    };
-    next?: ObservablePromise;
-    queuedRevalidation?: Promise<void>;
-    fetch: () => Promise<Response>;
-    subscriptions: Set<Subscription>;
-    timeout: ReturnType<typeof setTimeout> | null;
-}
+import { type Logger } from "@toapi/common";
+import { type ObservablePromise } from "./state-machine.js";
 interface Options {
     minTTL?: number;
     maxOverdueTTL?: number;
@@ -25,13 +12,16 @@ export declare class Cache {
     private maxOverdueTTL;
     private errorLog;
     constructor(options: Options);
-    private emplace;
-    private revalidateRequest;
     request(url: string, fetch: () => Promise<Response>): ObservablePromise;
-    queueRevalidation(url: string, entry: CacheEntry): Promise<void>;
+    private setResolveHook;
     revalidateUrl(url: string): Promise<void>;
     revalidateTags(tags: string[]): Promise<void>;
-    queueClearEntry(url: string): void;
+    private evictEntry;
+    private loadFreshData;
+    private subscribe;
+    private unsubscribe;
+    private setTimer;
+    private extractMetadata;
 }
 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":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGxD,KAAK,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;AAChE,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;AAErD,UAAU,UAAU;IAClB,OAAO,CAAC,EAAE;QACR,KAAK,EAAE,iBAAiB,CAAC;QACzB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;KACnB,CAAC;IACF,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,kBAAkB,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,KAAK,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/B,aAAa,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;IACjC,OAAO,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI,CAAC;CAC/C;AAED,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,OAAO;IAef,OAAO,CAAC,iBAAiB;IA+HzB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,iBAAiB;IAqBjE,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU;IAMhD,aAAa,CAAC,GAAG,EAAE,MAAM;IAuBzB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE;IAcnC,eAAe,CAAC,GAAG,EAAE,MAAM;CAiB5B"}
+{"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;AAY5B,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;YAuBzD,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;IAqBrB,OAAO,CAAC,SAAS;IA4CjB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,QAAQ;IA4BhB,OAAO,CAAC,eAAe;CAUxB"}

package/dist/cache.js

@@ -1,5 +1,6 @@
-import { EXPIRES_AT_HEADER, TAGS_HEADER } from "@toapi/common";
+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;
 const DEFAULT_MAX_OVERDUE_TTL = 1000;
 export class Cache {
@@ -13,168 +14,128 @@ export class Cache {
         this.maxOverdueTTL = options.maxOverdueTTL ?? DEFAULT_MAX_OVERDUE_TTL;
         this.errorLog = options.logger?.error ?? console.error;
     }
-    emplace(url, fetch) {
-        const currentEntry = this.storage.get(url);
-        if (currentEntry) {
-            currentEntry.fetch = fetch;
-            return currentEntry;
+    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;
+            }
         }
-        const newEntry = {
-            subscriptions: new Set(),
-            timeout: null,
-            fetch,
-        };
-        this.storage.set(url, newEntry);
-        return newEntry;
-    }
-    revalidateRequest(url, entry) {
-        if (entry.timeout) {
-            // clear timeout to make sure it the entry doesn't get revalidated again or removed based on TTL
-            clearTimeout(entry.timeout);
+        else {
+            const { observable } = this.loadFreshData(url, fetch);
+            this.storage.set(url, {
+                state: init(observable),
+                fetch,
+                subscriptions: new Set(),
+                timeout: null,
+            });
+            return observable;
         }
-        // actually load fresh data
-        const responsePromise = entry.fetch();
-        const observable = Object.assign(responsePromise.then(handleResponse), {
-            subscribe: (callback) => {
-                if (entry.subscriptions.size === 0) {
-                    if (entry.timeout) {
-                        clearTimeout(entry.timeout);
-                    }
-                    if (entry.current?.expiresAt) {
-                        entry.timeout = setTimeout(() => {
-                            this.revalidateRequest(url, entry);
-                        }, entry.current.expiresAt - Date.now() +
-                            Math.round(Math.random() * this.maxOverdueTTL));
-                    }
-                }
-                entry.subscriptions.add(callback);
-                // If there's a newer revalidation in-flight or completed since
-                // this observable was created, notify the new subscriber immediately
-                // so it doesn't miss the update.
-                if (entry.next && entry.next !== observable) {
-                    callback(entry.next);
-                }
-                else if (entry.current && entry.current.value !== observable) {
-                    // A revalidation completed between cache.request() returning this
-                    // observable and subscribe() being called — notify with the newer value.
-                    callback(entry.current.value);
-                }
-                return () => {
-                    entry.subscriptions.delete(callback);
-                    if (entry.subscriptions.size === 0) {
-                        this.queueClearEntry(url);
+    }
+    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.next = observable;
-        // notify subscribers
-        for (const callback of entry.subscriptions) {
-            callback(observable);
-        }
-        const next = entry.next;
-        const waitForRevalidation = async () => {
-            try {
-                // wait for request to finish
-                const response = await responsePromise;
-                // this will throw an error if the response is not ok
-                await observable;
-                if (entry.next !== next) {
-                    // request was superseded by a new request
+                    entry.state = resolve(entry.state, observable, tags, expiresAt);
+                    this.setTimer(url, entry);
                     return;
                 }
-                // update entry
-                const oldTags = entry.current?.tags ?? new Set();
-                const newTags = new Set(response.headers.get(TAGS_HEADER)?.split(" ") ?? []);
-                const expiresAtHeader = response.headers.get(EXPIRES_AT_HEADER);
-                const expiresAt = expiresAtHeader
-                    ? parseInt(expiresAtHeader, 10)
-                    : undefined;
-                entry.current = {
-                    value: observable,
-                    tags: newTags,
-                    expiresAt,
-                };
-                entry.next = undefined;
-                // add url to tagIndex for new tags
-                for (const tag of newTags.difference(oldTags)) {
-                    const urls = this.tagIndex.get(tag);
-                    if (urls) {
-                        urls.add(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]));
+                        }
                     }
-                    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);
                     }
-                }
-                // remove url from tagIndex for removed tags
-                for (const tag of oldTags.difference(newTags)) {
-                    this.tagIndex.get(tag)?.delete(url);
+                    entry.state = resolve(entry.state, observable, tags, expiresAt);
+                    this.setTimer(url, entry);
+                    return;
                 }
             }
-            catch (error) {
-                if (!entry.current) {
-                    // no current value, we are stuck with the rejected promise
-                    entry.current = {
-                        value: observable,
-                        tags: new Set(),
-                    };
-                }
-                // there is a current valid value, we'll keep that an drop the error
-                entry.next = undefined;
-                await this.errorLog(error);
+        }
+        catch (error) {
+            if (error instanceof HttpError && error.status < 500) {
+                // not found, no access etc, evict the entry
+                this.evictEntry(url);
+                return;
             }
-            finally {
-                if (entry.subscriptions.size === 0) {
-                    // clear response after minTTL if no subscribers active
-                    this.queueClearEntry(url);
-                }
+            const entry = this.storage.get(url);
+            if (!entry) {
+                // evicted, ignore
+                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);
+                    return;
             }
-        };
-        return { observable, revalidated: waitForRevalidation() };
-    }
-    request(url, fetch) {
-        const now = Date.now();
-        let entry = this.emplace(url, fetch);
-        if (entry.current) {
-            // has cached value, serve from cache
-            return entry.current.value;
-        }
-        // no cached value
-        if (entry.next) {
-            // already loading, serve from next
-            return entry.next;
         }
-        // nothing cached, load fresh
-        const { observable } = this.revalidateRequest(url, entry);
-        return observable;
     }
-    async queueRevalidation(url, entry) {
-        await entry.next;
-        const { revalidated } = this.revalidateRequest(url, entry);
-        await revalidated;
-    }
-    async revalidateUrl(url) {
+    revalidateUrl(url) {
         const entry = this.storage.get(url);
+        // no entry, nothing to do
         if (!entry)
-            return;
-        if (entry.next) {
-            // we are currently fetching that url
-            if (entry.queuedRevalidation) {
-                // another revalidation is already queued, wait for it to finish
-                await entry.queuedRevalidation;
-            }
-            else {
-                // queue another revalidation
-                const queuedRevalidation = this.queueRevalidation(url, entry);
-                entry.queuedRevalidation = queuedRevalidation;
-                await queuedRevalidation;
-            }
+            return Promise.resolve();
+        // no subscribers, evict the entry
+        if (entry.subscriptions.size === 0) {
+            this.evictEntry(url);
+            return Promise.resolve();
         }
-        else {
-            // there is no request in flight, revalidate immediately
-            const { revalidated } = this.revalidateRequest(url, entry);
-            await revalidated;
+        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;
     }
     async revalidateTags(tags) {
         // collect urls to revalidate
@@ -188,20 +149,92 @@ export class Cache {
         // revalidate urls and wait until all are resolved or rejected
         await Promise.allSettled(Array.from(urls).map((url) => this.revalidateUrl(url)));
     }
-    queueClearEntry(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);
+                }
+        }
+        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), {
+            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),
+                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);
         }
-        entry.timeout = setTimeout(() => {
-            if (entry.current) {
-                for (const tag of entry.current.tags) {
-                    this.tagIndex.get(tag)?.delete(url);
-                }
-            }
-            this.storage.delete(url);
-        }, this.minTTL);
+        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;
+    }
+    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/request-handler.mock.d.ts

@@ -0,0 +1,2 @@
+export declare const requestHandler: (req: Request) => Promise<Response>;
+//# sourceMappingURL=request-handler.mock.d.ts.map

package/dist/request-handler.mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-handler.mock.d.ts","sourceRoot":"","sources":["../src/request-handler.mock.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,cAAc,qCAAkD,CAAC"}

package/dist/request-handler.mock.js

@@ -0,0 +1,3 @@
+import { createRequestHandler } from "@toapi/server";
+import { api } from "./api.mock.js";
+export const requestHandler = createRequestHandler(api, { basePath: "/api" });

package/dist/state-machine.d.ts

@@ -0,0 +1,28 @@
+import type { Observable } from "@toapi/common";
+export type ObservablePromise = Promise<unknown> & Observable<unknown>;
+export type Pending = {
+    status: "pending";
+    next: ObservablePromise;
+    queued?: ObservablePromise;
+};
+export type Cached = {
+    status: "cached";
+    value: ObservablePromise;
+    expiresAt?: number;
+    tags: Set<string>;
+};
+export type Revalidating = {
+    status: "revalidating";
+    value: ObservablePromise;
+    tags: Set<string>;
+    expiresAt?: number;
+    next: ObservablePromise;
+    queued?: ObservablePromise;
+};
+export type CacheEntryState = Pending | Cached | Revalidating;
+export declare function init(next: ObservablePromise): Pending;
+export declare function revalidate(state: Cached, next: ObservablePromise): Revalidating;
+export declare function queue<S extends Revalidating | Pending>(state: S, queued: ObservablePromise): S;
+export declare function resolve(state: Pending | Revalidating, value: ObservablePromise, tags: Set<string>, expiresAt?: number): CacheEntryState;
+export declare function revert(state: Revalidating): Cached;
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../src/state-machine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;AAEvE,MAAM,MAAM,OAAO,GAAG;IACpB,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,iBAAiB,CAAC;IACxB,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG;IACnB,MAAM,EAAE,QAAQ,CAAC;IACjB,KAAK,EAAE,iBAAiB,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,iBAAiB,CAAC;IACzB,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,iBAAiB,CAAC;IACxB,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,GAAG,YAAY,CAAC;AAE9D,wBAAgB,IAAI,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAKrD;AAED,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,iBAAiB,GACtB,YAAY,CAQd;AAED,wBAAgB,KAAK,CAAC,CAAC,SAAS,YAAY,GAAG,OAAO,EACpD,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,iBAAiB,GACxB,CAAC,CAKH;AAED,wBAAgB,OAAO,CACrB,KAAK,EAAE,OAAO,GAAG,YAAY,EAC7B,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,eAAe,CAmBjB;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAOlD"}

package/dist/state-machine.js

@@ -0,0 +1,50 @@
+export function init(next) {
+    return {
+        status: "pending",
+        next,
+    };
+}
+export function revalidate(state, next) {
+    return {
+        status: "revalidating",
+        value: state.value,
+        tags: state.tags,
+        expiresAt: state.expiresAt,
+        next,
+    };
+}
+export function queue(state, queued) {
+    return {
+        ...state,
+        queued,
+    };
+}
+export function resolve(state, value, tags, expiresAt) {
+    if (state.next !== value)
+        return state;
+    if (state.queued) {
+        return {
+            status: "revalidating",
+            value,
+            tags,
+            expiresAt,
+            next: state.queued,
+        };
+    }
+    else {
+        return {
+            status: "cached",
+            value,
+            tags,
+            expiresAt,
+        };
+    }
+}
+export function revert(state) {
+    return {
+        status: "cached",
+        value: state.value,
+        tags: state.tags,
+        expiresAt: state.expiresAt,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toapi/client",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "author": {
     "name": "Michel Smola",
     "email": "michel.smola@farbenmeer.de"
@@ -20,12 +20,13 @@
     }
   },
   "dependencies": {
-    "@toapi/common": "^1.1.0"
+    "@toapi/common": "^1.2.0"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
     "vitest": "^4.0.16",
-    "zod": "^4.0.17"
+    "zod": "^4.0.17",
+    "@toapi/server": "^1.2.0"
   },
   "peerDependencies": {
     "typescript": "^5 || ^6.0.0",
@@ -38,6 +39,6 @@
   "scripts": {
     "build": "tsc --noEmit false",
     "release": "pnpm build && pnpm publish --no-git-checks",
-    "test": "vitest run --passWithNoTests"
+    "test": "vitest"
   }
 }