svelte-ag 1.0.57 → 1.0.58

package/dist/lib/api/query/cache.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cache.unit.test.d.ts.map

package/dist/lib/api/query/cache.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.unit.test.d.ts","sourceRoot":"","sources":["../../../../src/lib/api/query/cache.unit.test.ts"],"names":[],"mappings":""}

package/dist/lib/api/query/cache.unit.test.js

@@ -0,0 +1,50 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Cache } from './cache.svelte.js';
+describe('Cache', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+        vi.setSystemTime(0);
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.restoreAllMocks();
+    });
+    it('stores and expires values based on timeout', () => {
+        const cache = new Cache();
+        cache.register('user', { timeout: 100 });
+        cache.set('user', { id: 1 });
+        expect(cache.has('user')).toBe(true);
+        expect(cache.get('user')).toEqual({ id: 1 });
+        vi.advanceTimersByTime(99);
+        expect(cache.has('user')).toBe(true);
+        expect(cache.get('user')).toEqual({ id: 1 });
+        vi.advanceTimersByTime(1);
+        expect(cache.has('user')).toBe(false);
+        expect(cache.get('user')).toBeNull();
+    });
+    it('supports infinite timeout and reset', () => {
+        const cache = new Cache();
+        cache.register('settings', { timeout: 'inf' });
+        cache.set('settings', { theme: 'light' });
+        vi.advanceTimersByTime(10_000);
+        expect(cache.has('settings')).toBe(true);
+        expect(cache.get('settings')).toEqual({ theme: 'light' });
+        cache.reset('settings');
+        expect(cache.has('settings')).toBe(false);
+        expect(cache.get('settings')).toBeNull();
+    });
+    it('deregisters keys completely', () => {
+        const cache = new Cache();
+        cache.register('token', { timeout: 100 });
+        cache.set('token', 'abc');
+        cache.deregister('token');
+        expect(cache.has('token')).toBe(false);
+        expect(() => cache.get('token')).toThrow('The key token is not registered in the cache');
+    });
+    it('throws when mutating an unregistered key', () => {
+        const cache = new Cache();
+        expect(() => cache.set('missing', 1)).toThrow('The key missing is not registered in the cache');
+        expect(() => cache.get('missing')).toThrow('The key missing is not registered in the cache');
+        expect(() => cache.reset('missing')).toThrow('The key missing is not registered in the cache');
+    });
+});

package/dist/lib/api/query/entrypoint.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=entrypoint.unit.test.d.ts.map

package/dist/lib/api/query/entrypoint.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoint.unit.test.d.ts","sourceRoot":"","sources":["../../../../src/lib/api/query/entrypoint.unit.test.ts"],"names":[],"mappings":""}

package/dist/lib/api/query/entrypoint.unit.test.js

@@ -0,0 +1,56 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+function getUserId(input) {
+    return 'id' in input ? input.id : input.ids[0];
+}
+function jsonResponse(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json' }
+    });
+}
+describe('createQueryFunction', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+        vi.setSystemTime(0);
+        vi.resetModules();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.restoreAllMocks();
+    });
+    it('returns the same query instance for the same path, method, and input', async () => {
+        const { createQueryFunction } = await import('./entrypoint.svelte.js');
+        const requestMock = vi.fn(async () => jsonResponse({ ok: true }));
+        const request = requestMock;
+        const createQuery = createQueryFunction(request, {});
+        const query1 = createQuery('/users', 'GET', { id: 1 });
+        const query2 = createQuery('/users', 'GET', { id: 1 });
+        const query3 = createQuery('/users', 'GET', { id: 2 });
+        expect(query1).toBe(query2);
+        expect(query3).not.toBe(query1);
+    });
+    it('reuses requestors so separate queries can batch together', async () => {
+        const { createQueryFunction } = await import('./entrypoint.svelte.js');
+        const requestMock = vi.fn(async () => jsonResponse({ ok: true }));
+        const request = requestMock;
+        const createQuery = createQueryFunction(request, {
+            '/users': {
+                GET: {
+                    canBatch: () => 'users',
+                    batchInput: (inputs) => ({ ids: inputs.map(getUserId) }),
+                    unBatchOutput: (inputs) => inputs.map((input) => jsonResponse({ id: getUserId(input) }))
+                }
+            }
+        });
+        const query1 = createQuery('/users', 'GET', { id: 1 });
+        const query2 = createQuery('/users', 'GET', { id: 2 });
+        const p1 = query1.request();
+        const p2 = query2.request();
+        await vi.advanceTimersByTimeAsync(100);
+        expect(requestMock).toHaveBeenCalledTimes(1);
+        expect(requestMock).toHaveBeenCalledWith('/users', 'GET', { ids: [1, 2] });
+        const [response1, response2] = await Promise.all([p1, p2]);
+        await expect(response1.json()).resolves.toEqual({ id: 1 });
+        await expect(response2.json()).resolves.toEqual({ id: 2 });
+    });
+});

package/dist/lib/api/query/query.svelte.d.ts

@@ -6,7 +6,7 @@ export declare class Query<API extends ApiEndpoints, Path extends API['path'], M
     path: Path;
 }>['method']> {
     #private;
-    constructor({ path, method, input, requestor, cache }: {
+    constructor({ path, method, input, requestor, cache, opts }: {
         path: Path;
         method: Method;
         input: ApiInput<API, Path, Method>;

package/dist/lib/api/query/query.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/api/query/query.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,kBAAkB,EAAE,cAAc,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAGnH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAG5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnE,qBAAa,KAAK,CAChB,GAAG,SAAS,YAAY,EACxB,IAAI,SAAS,GAAG,CAAC,MAAM,CAAC,EACxB,MAAM,SAAS,OAAO,CAAC,GAAG,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC,QAAQ,CAAC;;gBAyBzC,EACV,IAAI,EACJ,MAAM,EACN,KAAK,EACL,SAAS,EACT,KAAK,EACN,EAAE;QACD,IAAI,EAAE,IAAI,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QACnC,SAAS,EAAE,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QACxC,KAAK,EAAE,KAAK,CAAC;QACb,IAAI,CAAC,EAAE;YACL,KAAK,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAC1C,CAAC;KACH;IAgBK,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IA+BxD,IAAI,QAAQ,WAEX;IACD,IAAI,QAAQ,YAEX;IACD,UAAU;IAMV,IAAI,MAAM,gBAET;IACD,IAAI,IAAI,IAAI,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,IAAI,CAEnD;IACD,IAAI,SAAS,IAAI,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,IAAI,CAEtD;CACF;AAED,qBAAa,SAAS,CACpB,GAAG,SAAS,YAAY,EACxB,IAAI,SAAS,GAAG,CAAC,MAAM,CAAC,EACxB,MAAM,SAAS,OAAO,CAAC,GAAG,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC,QAAQ,CAAC;;gBA6BnD,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,kBAAkB,CAAC,GAAG,CAAC,EAChC,MAAM,EAAE,KAAK,EACb,YAAY,CAAC,EAAE,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC;YAelC,KAAK;IAOnB;;;OAGG;YACW,eAAe;IAqBvB,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;CAkB3F"}
+{"version":3,"file":"query.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/api/query/query.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,kBAAkB,EAAE,cAAc,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAGnH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAG5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAenE,qBAAa,KAAK,CAChB,GAAG,SAAS,YAAY,EACxB,IAAI,SAAS,GAAG,CAAC,MAAM,CAAC,EACxB,MAAM,SAAS,OAAO,CAAC,GAAG,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC,QAAQ,CAAC;;gBAyBzC,EACV,IAAI,EACJ,MAAM,EACN,KAAK,EACL,SAAS,EACT,KAAK,EACL,IAAI,EACL,EAAE;QACD,IAAI,EAAE,IAAI,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QACnC,SAAS,EAAE,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QACxC,KAAK,EAAE,KAAK,CAAC;QACb,IAAI,CAAC,EAAE;YACL,KAAK,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAC1C,CAAC;KACH;IAgBK,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAyCxD,IAAI,QAAQ,WAEX;IACD,IAAI,QAAQ,YAEX;IACD,UAAU;IAMV,IAAI,MAAM,gBAET;IACD,IAAI,IAAI,IAAI,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,IAAI,CAEnD;IACD,IAAI,SAAS,IAAI,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,IAAI,CAEtD;CACF;AAED,qBAAa,SAAS,CACpB,GAAG,SAAS,YAAY,EACxB,IAAI,SAAS,GAAG,CAAC,MAAM,CAAC,EACxB,MAAM,SAAS,OAAO,CAAC,GAAG,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC,QAAQ,CAAC;;gBA6BnD,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,kBAAkB,CAAC,GAAG,CAAC,EAChC,MAAM,EAAE,KAAK,EACb,YAAY,CAAC,EAAE,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC;YAelC,KAAK;IAOnB;;;OAGG;YACW,eAAe;IA2BvB,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;CAmB3F"}

package/dist/lib/api/query/query.svelte.js

@@ -1,6 +1,15 @@
 import { stringify } from 'devalue';
 import { cacheKey } from './utils.svelte.js';
 import { RateLimiter } from './rate.svelte';
+function cloneResponse(response) {
+    if (response !== null &&
+        typeof response === 'object' &&
+        'clone' in response &&
+        typeof response.clone === 'function') {
+        return response.clone();
+    }
+    return response;
+}
 export class Query {
     // -------- Constants --------
     #TIMEOUT = 1000 * 60 * 5; // 5 minutes
@@ -20,7 +29,7 @@ export class Query {
     #data = $state(null);
     #errorData = $state(null);
     // -------- Functions --------
-    constructor({ path, method, input, requestor, cache }) {
+    constructor({ path, method, input, requestor, cache, opts }) {
         this.#requestor = requestor;
         this.#cache = cache;
         this.#path = path;
@@ -29,32 +38,43 @@ export class Query {
         this.#input = input;
         this.#inputString = stringify(input);
         this.#cacheKey = cacheKey(path, method, input);
-        this.#cache.register(this.#cacheKey, { timeout: this.#TIMEOUT });
+        this.#cache.register(this.#cacheKey, opts?.cache ?? { timeout: this.#TIMEOUT });
     }
     async request() {
         const cachedValue = this.#cache.get(this.#cacheKey);
         if (cachedValue !== null) {
-            return cachedValue;
+            return cloneResponse(cachedValue);
         }
         this.#status = 'loading';
         if (this.#pendingRequest === null) {
             this.#pendingRequest = this.#requestor.request(this.#input);
         }
-        const res = await this.#pendingRequest;
-        this.#pendingRequest = null;
-        this.#cache.set(this.#cacheKey, res);
-        if (res.ok === false) {
-            const body = await res.json();
+        let res;
+        try {
+            res = await this.#pendingRequest;
+        }
+        catch (err) {
+            this.#status = 'error';
+            throw err;
+        }
+        finally {
+            this.#pendingRequest = null;
+        }
+        const responseForState = cloneResponse(res);
+        const responseForCaller = cloneResponse(res);
+        this.#cache.set(this.#cacheKey, cloneResponse(res));
+        if (responseForState.ok === false) {
+            const body = await responseForState.json();
             this.#status = 'error';
             // @ts-expect-error Generics not working for some reason
             this.#errorData = body;
-            return res;
+            return responseForCaller;
         }
         else {
-            const body = await res.json();
+            const body = await responseForState.json();
             this.#status = 'success';
             this.#data = body;
-            return res;
+            return responseForCaller;
         }
     }
     get cacheKey() {
@@ -117,17 +137,22 @@ export class Requestor {
      */
     async flushBatchQueue(batchId) {
         const queue = this.#batchQueue[batchId].splice(0);
-        const batchedInput = this.#batchInput(queue.map((q) => q.input));
-        const res = await this.fetch(batchedInput);
-        const output = await this.#unBatchOutput(queue.map((q) => q.input), res);
-        queue.forEach(({ resolve, reject }, i) => {
-            if (output[i].ok === true) {
-                resolve(output[i]);
+        try {
+            const batchedInput = this.#batchInput(queue.map((q) => q.input));
+            const res = await this.fetch(batchedInput);
+            const output = await this.#unBatchOutput(queue.map((q) => q.input), res);
+            if (output.length !== queue.length) {
+                throw new Error(`Batch output length mismatch for ${batchId}`);
             }
-            else {
-                reject(output[i]);
-            }
-        });
+            queue.forEach(({ resolve }, i) => {
+                resolve(output[i]);
+            });
+        }
+        catch (err) {
+            queue.forEach(({ reject }) => {
+                reject(err);
+            });
+        }
     }
     // Performs a request for a given input. Batches it if possible
     async request(input) {
@@ -139,8 +164,9 @@ export class Requestor {
                 this.#batchQueue[batchId].push({ input, resolve, reject });
                 if (!this.#batchTimers[batchId]) {
                     this.#batchTimers[batchId] = setTimeout(() => {
-                        this.flushBatchQueue(batchId);
-                        delete this.#batchTimers[batchId];
+                        void this.flushBatchQueue(batchId).finally(() => {
+                            delete this.#batchTimers[batchId];
+                        });
                     }, this.#batchDelay);
                 }
             });

package/dist/lib/api/query/query.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=query.unit.test.d.ts.map

package/dist/lib/api/query/query.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.unit.test.d.ts","sourceRoot":"","sources":["../../../../src/lib/api/query/query.unit.test.ts"],"names":[],"mappings":""}

package/dist/lib/api/query/query.unit.test.js

@@ -0,0 +1,276 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Cache } from './cache.svelte.js';
+import { Query, Requestor } from './query.svelte.js';
+function getSingleId(input) {
+    return 'id' in input ? input.id : input.ids[0];
+}
+function jsonResponse(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json' }
+    });
+}
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+describe('Requestor', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+        vi.setSystemTime(0);
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.restoreAllMocks();
+    });
+    it('passes through non-batched requests', async () => {
+        const requestMock = vi.fn(async () => jsonResponse({ id: 1 }));
+        const request = requestMock;
+        const requestor = new Requestor('/users', 'GET', request, new Cache());
+        const response = await requestor.request({ id: 1 });
+        expect(requestMock).toHaveBeenCalledTimes(1);
+        expect(requestMock).toHaveBeenCalledWith('/users', 'GET', { id: 1 });
+        await expect(response.json()).resolves.toEqual({ id: 1 });
+    });
+    it('batches requests with the same batch id and preserves response order', async () => {
+        const requestMock = vi.fn(async () => jsonResponse({ ok: true }));
+        const request = requestMock;
+        const requestor = new Requestor('/users', 'GET', request, new Cache(), {
+            canBatch: (input) => ('group' in input && input.group) || false,
+            batchInput: (inputs) => ({ ids: inputs.map(getSingleId) }),
+            unBatchOutput: (inputs) => inputs.map((input) => jsonResponse({ id: getSingleId(input) }))
+        });
+        const p1 = requestor.request({ id: 1, group: 'team' });
+        const p2 = requestor.request({ id: 2, group: 'team' });
+        await vi.advanceTimersByTimeAsync(99);
+        expect(requestMock).not.toHaveBeenCalled();
+        await vi.advanceTimersByTimeAsync(1);
+        expect(requestMock).toHaveBeenCalledTimes(1);
+        expect(requestMock).toHaveBeenCalledWith('/users', 'GET', { ids: [1, 2] });
+        const [response1, response2] = await Promise.all([p1, p2]);
+        await expect(response1.json()).resolves.toEqual({ id: 1 });
+        await expect(response2.json()).resolves.toEqual({ id: 2 });
+    });
+    it('rate limits separate batches by start time rather than completion time', async () => {
+        const starts = [];
+        const requestMock = vi.fn(async (_path, _method, input) => {
+            starts.push(Date.now());
+            if ('ids' in input && input.ids[0] === 1) {
+                await new Promise((resolve) => setTimeout(resolve, 200));
+            }
+            return jsonResponse({ ids: 'ids' in input ? input.ids : [input.id] });
+        });
+        const request = requestMock;
+        const requestor = new Requestor('/users', 'GET', request, new Cache(), {
+            canBatch: (input) => ('group' in input && input.group) || false,
+            batchInput: (inputs) => ({ ids: inputs.map(getSingleId) }),
+            unBatchOutput: (_inputs, output) => [output]
+        });
+        const p1 = requestor.request({ id: 1, group: 'a' });
+        const p2 = requestor.request({ id: 2, group: 'b' });
+        await vi.advanceTimersByTimeAsync(100);
+        expect(starts).toEqual([100]);
+        await vi.advanceTimersByTimeAsync(100);
+        expect(starts).toEqual([100, 200]);
+        await vi.runAllTimersAsync();
+        const [response1, response2] = await Promise.all([p1, p2]);
+        await expect(response1.json()).resolves.toEqual({ ids: [1] });
+        await expect(response2.json()).resolves.toEqual({ ids: [2] });
+    });
+    it('returns batched error responses without rejecting them', async () => {
+        const requestMock = vi.fn(async () => jsonResponse({ ok: false }, 207));
+        const request = requestMock;
+        const requestor = new Requestor('/users', 'GET', request, new Cache(), {
+            canBatch: () => 'team',
+            batchInput: (inputs) => ({ ids: inputs.map(getSingleId) }),
+            unBatchOutput: () => [jsonResponse({ message: 'bad request' }, 400)]
+        });
+        const responsePromise = requestor.request({ id: 1 });
+        await vi.advanceTimersByTimeAsync(100);
+        const response = await responsePromise;
+        expect(response.ok).toBe(false);
+        expect(response.status).toBe(400);
+        await expect(response.json()).resolves.toEqual({ message: 'bad request' });
+    });
+    it('rejects all queued callers when a batched fetch throws', async () => {
+        const requestMock = vi.fn(async () => {
+            throw new Error('network down');
+        });
+        const request = requestMock;
+        const requestor = new Requestor('/users', 'GET', request, new Cache(), {
+            canBatch: () => 'team',
+            batchInput: (inputs) => ({ ids: inputs.map(getSingleId) }),
+            unBatchOutput: (_inputs, output) => [output]
+        });
+        const p1 = requestor.request({ id: 1 });
+        const p2 = requestor.request({ id: 2 });
+        const p1Expectation = expect(p1).rejects.toThrow('network down');
+        const p2Expectation = expect(p2).rejects.toThrow('network down');
+        await vi.advanceTimersByTimeAsync(100);
+        await Promise.all([p1Expectation, p2Expectation]);
+    });
+});
+describe('Query', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+        vi.setSystemTime(0);
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.restoreAllMocks();
+    });
+    it('deduplicates concurrent requests and returns readable responses to each caller', async () => {
+        const pending = deferred();
+        const requestMock = vi.fn().mockReturnValue(pending.promise);
+        const requestor = {
+            request: requestMock
+        };
+        const query = new Query({
+            path: '/users',
+            method: 'GET',
+            input: { id: 1 },
+            requestor,
+            cache: new Cache()
+        });
+        const p1 = query.request();
+        const p2 = query.request();
+        expect(requestMock).toHaveBeenCalledTimes(1);
+        pending.resolve(jsonResponse({ id: 1 }));
+        const [response1, response2] = await Promise.all([p1, p2]);
+        await expect(response1.json()).resolves.toEqual({ id: 1 });
+        await expect(response2.json()).resolves.toEqual({ id: 1 });
+    });
+    it('caches responses and returns a fresh readable clone on cache hits', async () => {
+        const requestMock = vi.fn().mockResolvedValue(jsonResponse({ id: 1, name: 'Ada' }));
+        const requestor = {
+            request: requestMock
+        };
+        const query = new Query({
+            path: '/users',
+            method: 'GET',
+            input: { id: 1 },
+            requestor,
+            cache: new Cache()
+        });
+        const first = await query.request();
+        const second = await query.request();
+        expect(requestMock).toHaveBeenCalledTimes(1);
+        expect(query.isCached).toBe(true);
+        await expect(first.json()).resolves.toEqual({ id: 1, name: 'Ada' });
+        await expect(second.json()).resolves.toEqual({ id: 1, name: 'Ada' });
+    });
+    it('updates success state from successful responses', async () => {
+        const requestMock = vi.fn().mockResolvedValue(jsonResponse({ id: 1, active: true }));
+        const requestor = {
+            request: requestMock
+        };
+        const query = new Query({
+            path: '/users',
+            method: 'GET',
+            input: { id: 1 },
+            requestor,
+            cache: new Cache()
+        });
+        const response = await query.request();
+        expect(query.status).toBe('success');
+        expect(query.data).toEqual({ id: 1, active: true });
+        expect(query.errorData).toBeNull();
+        await expect(response.json()).resolves.toEqual({ id: 1, active: true });
+    });
+    it('updates error state from error responses without throwing', async () => {
+        const requestMock = vi.fn().mockResolvedValue(jsonResponse({ message: 'missing' }, 404));
+        const requestor = {
+            request: requestMock
+        };
+        const query = new Query({
+            path: '/users',
+            method: 'GET',
+            input: { id: 99 },
+            requestor,
+            cache: new Cache()
+        });
+        const response = await query.request();
+        expect(query.status).toBe('error');
+        expect(query.data).toBeNull();
+        expect(query.errorData).toEqual({ message: 'missing' });
+        expect(response.ok).toBe(false);
+        await expect(response.json()).resolves.toEqual({ message: 'missing' });
+    });
+    it('clears the pending request when the request throws so later retries can succeed', async () => {
+        const requestMock = vi
+            .fn()
+            .mockRejectedValueOnce(new Error('network down'))
+            .mockResolvedValueOnce(jsonResponse({ id: 1, recovered: true }));
+        const requestor = {
+            request: requestMock
+        };
+        const query = new Query({
+            path: '/users',
+            method: 'GET',
+            input: { id: 1 },
+            requestor,
+            cache: new Cache()
+        });
+        await expect(query.request()).rejects.toThrow('network down');
+        expect(query.status).toBe('error');
+        const response = await query.request();
+        expect(requestMock).toHaveBeenCalledTimes(2);
+        expect(query.status).toBe('success');
+        await expect(response.json()).resolves.toEqual({ id: 1, recovered: true });
+    });
+    it('resetCache forces the next request to fetch again', async () => {
+        const requestMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse({ call: 1 }))
+            .mockResolvedValueOnce(jsonResponse({ call: 2 }));
+        const requestor = {
+            request: requestMock
+        };
+        const query = new Query({
+            path: '/users',
+            method: 'GET',
+            input: { id: 1 },
+            requestor,
+            cache: new Cache()
+        });
+        const first = await query.request();
+        query.resetCache();
+        const second = await query.request();
+        expect(requestMock).toHaveBeenCalledTimes(2);
+        await expect(first.json()).resolves.toEqual({ call: 1 });
+        await expect(second.json()).resolves.toEqual({ call: 2 });
+    });
+    it('honors custom cache timeout options', async () => {
+        const requestMock = vi
+            .fn()
+            .mockResolvedValueOnce(jsonResponse({ call: 1 }))
+            .mockResolvedValueOnce(jsonResponse({ call: 2 }));
+        const requestor = {
+            request: requestMock
+        };
+        const query = new Query({
+            path: '/users',
+            method: 'GET',
+            input: { id: 1 },
+            requestor,
+            cache: new Cache(),
+            opts: {
+                cache: { timeout: 50 }
+            }
+        });
+        const first = await query.request();
+        vi.advanceTimersByTime(49);
+        const cached = await query.request();
+        vi.advanceTimersByTime(1);
+        const refreshed = await query.request();
+        expect(requestMock).toHaveBeenCalledTimes(2);
+        await expect(first.json()).resolves.toEqual({ call: 1 });
+        await expect(cached.json()).resolves.toEqual({ call: 1 });
+        await expect(refreshed.json()).resolves.toEqual({ call: 2 });
+    });
+});

package/dist/test/vitest.setup.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=vitest.setup.d.ts.map

package/dist/test/vitest.setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.setup.d.ts","sourceRoot":"","sources":["../../src/test/vitest.setup.ts"],"names":[],"mappings":""}

package/dist/test/vitest.setup.js

@@ -0,0 +1,4 @@
+"use strict";
+if (typeof globalThis.$state !== 'function') {
+    globalThis.$state = (value) => value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-ag",
-  "version": "1.0.57",
+  "version": "1.0.58",
   "description": "Useful svelte components",
   "bugs": "https://github.com/ageorgeh/svelte-ag/issues",
   "repository": {
@@ -70,7 +70,7 @@
     "@iconify/tailwind4": "^1.2.3",
     "@iconify/types": "^2.0.0",
     "@internationalized/date": "^3.12.0",
-    "@lucide/svelte": "^0.577.0",
+    "@lucide/svelte": "^1.7.0",
     "@playwright/test": "1.57.0",
     "@sveltejs/kit": "^2.55.0",
     "@sveltejs/package": "^2.5.7",

package/src/lib/api/query/cache.unit.test.ts

@@ -0,0 +1,66 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Cache } from './cache.svelte.js';
+
+describe('Cache', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('stores and expires values based on timeout', () => {
+    const cache = new Cache();
+
+    cache.register('user', { timeout: 100 });
+    cache.set('user', { id: 1 });
+
+    expect(cache.has('user')).toBe(true);
+    expect(cache.get('user')).toEqual({ id: 1 });
+
+    vi.advanceTimersByTime(99);
+    expect(cache.has('user')).toBe(true);
+    expect(cache.get('user')).toEqual({ id: 1 });
+
+    vi.advanceTimersByTime(1);
+    expect(cache.has('user')).toBe(false);
+    expect(cache.get('user')).toBeNull();
+  });
+
+  it('supports infinite timeout and reset', () => {
+    const cache = new Cache();
+
+    cache.register('settings', { timeout: 'inf' });
+    cache.set('settings', { theme: 'light' });
+
+    vi.advanceTimersByTime(10_000);
+    expect(cache.has('settings')).toBe(true);
+    expect(cache.get('settings')).toEqual({ theme: 'light' });
+
+    cache.reset('settings');
+    expect(cache.has('settings')).toBe(false);
+    expect(cache.get('settings')).toBeNull();
+  });
+
+  it('deregisters keys completely', () => {
+    const cache = new Cache();
+
+    cache.register('token', { timeout: 100 });
+    cache.set('token', 'abc');
+    cache.deregister('token');
+
+    expect(cache.has('token')).toBe(false);
+    expect(() => cache.get('token')).toThrow('The key token is not registered in the cache');
+  });
+
+  it('throws when mutating an unregistered key', () => {
+    const cache = new Cache();
+
+    expect(() => cache.set('missing', 1)).toThrow('The key missing is not registered in the cache');
+    expect(() => cache.get('missing')).toThrow('The key missing is not registered in the cache');
+    expect(() => cache.reset('missing')).toThrow('The key missing is not registered in the cache');
+  });
+});

package/src/lib/api/query/entrypoint.unit.test.ts

@@ -0,0 +1,85 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { ApiEndpoints, ApiRequestFunction } from 'ts-ag';
+
+type TestResponse = ApiEndpoints['response'];
+
+type UserInput = { id: number; group?: string };
+type BatchedInput = { ids: number[] };
+
+type UsersApi = {
+  path: '/users';
+  method: 'GET';
+  requestInput: UserInput | BatchedInput;
+  requestOutput: null;
+  response: TestResponse;
+};
+
+type UsersRequest = ApiRequestFunction<UsersApi>;
+
+function getUserId(input: UsersApi['requestInput']): number {
+  return 'id' in input ? input.id : input.ids[0]!;
+}
+
+function jsonResponse(body: unknown, status = 200): TestResponse {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' }
+  }) as TestResponse;
+}
+
+describe('createQueryFunction', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('returns the same query instance for the same path, method, and input', async () => {
+    const { createQueryFunction } = await import('./entrypoint.svelte.js');
+    const requestMock = vi.fn(async () => jsonResponse({ ok: true }));
+    const request = requestMock as unknown as UsersRequest;
+    const createQuery = createQueryFunction<UsersApi>(request, {});
+
+    const query1 = createQuery('/users', 'GET', { id: 1 });
+    const query2 = createQuery('/users', 'GET', { id: 1 });
+    const query3 = createQuery('/users', 'GET', { id: 2 });
+
+    expect(query1).toBe(query2);
+    expect(query3).not.toBe(query1);
+  });
+
+  it('reuses requestors so separate queries can batch together', async () => {
+    const { createQueryFunction } = await import('./entrypoint.svelte.js');
+    const requestMock = vi.fn(async () => jsonResponse({ ok: true }));
+    const request = requestMock as unknown as UsersRequest;
+    const createQuery = createQueryFunction<UsersApi>(request, {
+      '/users': {
+        GET: {
+          canBatch: () => 'users',
+          batchInput: (inputs) => ({ ids: inputs.map(getUserId) }),
+          unBatchOutput: (inputs) => inputs.map((input) => jsonResponse({ id: getUserId(input) }))
+        }
+      }
+    });
+
+    const query1 = createQuery('/users', 'GET', { id: 1 });
+    const query2 = createQuery('/users', 'GET', { id: 2 });
+
+    const p1 = query1.request();
+    const p2 = query2.request();
+
+    await vi.advanceTimersByTimeAsync(100);
+
+    expect(requestMock).toHaveBeenCalledTimes(1);
+    expect(requestMock).toHaveBeenCalledWith('/users', 'GET', { ids: [1, 2] });
+
+    const [response1, response2] = await Promise.all([p1, p2]);
+    await expect(response1.json()).resolves.toEqual({ id: 1 });
+    await expect(response2.json()).resolves.toEqual({ id: 2 });
+  });
+});

package/src/lib/api/query/query.svelte.ts

@@ -9,6 +9,19 @@ import { RateLimiter } from './rate.svelte';
 
 export type QueryStatus = 'idle' | 'loading' | 'success' | 'error';
 
+function cloneResponse<T>(response: T): T {
+  if (
+    response !== null &&
+    typeof response === 'object' &&
+    'clone' in response &&
+    typeof response.clone === 'function'
+  ) {
+    return response.clone();
+  }
+
+  return response;
+}
+
 export class Query<
   API extends ApiEndpoints,
   Path extends API['path'],
@@ -42,7 +55,8 @@ export class Query<
     method,
     input,
     requestor,
-    cache
+    cache,
+    opts
   }: {
     path: Path;
     method: Method;
@@ -65,13 +79,13 @@ export class Query<
     this.#inputString = stringify(input);
     this.#cacheKey = cacheKey(path, method, input);
 
-    this.#cache.register(this.#cacheKey, { timeout: this.#TIMEOUT });
+    this.#cache.register(this.#cacheKey, opts?.cache ?? { timeout: this.#TIMEOUT });
   }
 
   async request(): Promise<ApiResponse<API, Path, Method>> {
     const cachedValue = this.#cache.get(this.#cacheKey);
     if (cachedValue !== null) {
-      return cachedValue;
+      return cloneResponse(cachedValue);
     }
 
     this.#status = 'loading';
@@ -79,23 +93,33 @@ export class Query<
     if (this.#pendingRequest === null) {
       this.#pendingRequest = this.#requestor.request(this.#input);
     }
-    const res = await this.#pendingRequest;
-    this.#pendingRequest = null;
 
-    this.#cache.set(this.#cacheKey, res);
+    let res: ApiResponse<API, Path, Method>;
+    try {
+      res = await this.#pendingRequest;
+    } catch (err) {
+      this.#status = 'error';
+      throw err;
+    } finally {
+      this.#pendingRequest = null;
+    }
+
+    const responseForState = cloneResponse(res);
+    const responseForCaller = cloneResponse(res);
+    this.#cache.set(this.#cacheKey, cloneResponse(res));
 
-    if (res.ok === false) {
-      const body = await res.json();
+    if (responseForState.ok === false) {
+      const body = await responseForState.json();
       this.#status = 'error';
 
       // @ts-expect-error Generics not working for some reason
       this.#errorData = body;
-      return res;
+      return responseForCaller;
     } else {
-      const body = await res.json();
+      const body = await responseForState.json();
       this.#status = 'success';
       this.#data = body;
-      return res;
+      return responseForCaller;
     }
   }
 
@@ -147,7 +171,7 @@ export class Requestor<
     string,
     {
       resolve: (value: ApiResponse<API, Path, Method>) => void;
-      reject: (err: ApiResponse<API, Path, Method>) => void;
+      reject: (err: unknown) => void;
       input: ApiInput<API, Path, Method>;
     }[]
   > = {};
@@ -187,21 +211,27 @@ export class Requestor<
   private async flushBatchQueue(batchId: string): Promise<void> {
     const queue = this.#batchQueue[batchId].splice(0);
 
-    const batchedInput = this.#batchInput(queue.map((q) => q.input));
+    try {
+      const batchedInput = this.#batchInput(queue.map((q) => q.input));
 
-    const res = await this.fetch(batchedInput);
-    const output = await this.#unBatchOutput(
-      queue.map((q) => q.input),
-      res
-    );
+      const res = await this.fetch(batchedInput);
+      const output = await this.#unBatchOutput(
+        queue.map((q) => q.input),
+        res
+      );
 
-    queue.forEach(({ resolve, reject }, i) => {
-      if (output[i].ok === true) {
-        resolve(output[i]);
-      } else {
-        reject(output[i]);
+      if (output.length !== queue.length) {
+        throw new Error(`Batch output length mismatch for ${batchId}`);
       }
-    });
+
+      queue.forEach(({ resolve }, i) => {
+        resolve(output[i]!);
+      });
+    } catch (err) {
+      queue.forEach(({ reject }) => {
+        reject(err);
+      });
+    }
   }
 
   // Performs a request for a given input. Batches it if possible
@@ -214,8 +244,9 @@ export class Requestor<
         this.#batchQueue[batchId].push({ input, resolve, reject });
         if (!this.#batchTimers[batchId]) {
           this.#batchTimers[batchId] = setTimeout(() => {
-            this.flushBatchQueue(batchId);
-            delete this.#batchTimers[batchId];
+            void this.flushBatchQueue(batchId).finally(() => {
+              delete this.#batchTimers[batchId];
+            });
           }, this.#batchDelay);
         }
       });

package/src/lib/api/query/query.unit.test.ts

@@ -0,0 +1,367 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { ApiEndpoints, ApiRequestFunction } from 'ts-ag';
+import { Cache } from './cache.svelte.js';
+import { Query, Requestor } from './query.svelte.js';
+
+type PlainUserInput = { id: number };
+type BatchedUserInput = { id: number; group?: string };
+type BatchedRequestInput = { ids: number[] };
+
+type TestResponse = ApiEndpoints['response'];
+
+type PlainUsersApi = {
+  path: '/users';
+  method: 'GET';
+  requestInput: PlainUserInput;
+  requestOutput: null;
+  response: TestResponse;
+};
+
+type BatchedUsersApi = {
+  path: '/users';
+  method: 'GET';
+  requestInput: BatchedUserInput | BatchedRequestInput;
+  requestOutput: null;
+  response: TestResponse;
+};
+
+type PlainUsersRequestor = Requestor<PlainUsersApi, '/users', 'GET'>;
+type PlainUsersRequest = ApiRequestFunction<PlainUsersApi>;
+type BatchedUsersRequest = ApiRequestFunction<BatchedUsersApi>;
+
+function getSingleId(input: BatchedUsersApi['requestInput']): number {
+  return 'id' in input ? input.id : input.ids[0]!;
+}
+
+function jsonResponse(body: unknown, status = 200): TestResponse {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' }
+  }) as TestResponse;
+}
+
+function deferred<T>() {
+  let resolve!: (value: T | PromiseLike<T>) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+
+  return { promise, resolve, reject };
+}
+
+describe('Requestor', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('passes through non-batched requests', async () => {
+    const requestMock = vi.fn(async () => jsonResponse({ id: 1 }));
+    const request = requestMock as unknown as PlainUsersRequest;
+    const requestor = new Requestor<PlainUsersApi, '/users', 'GET'>('/users', 'GET', request, new Cache());
+
+    const response = await requestor.request({ id: 1 });
+
+    expect(requestMock).toHaveBeenCalledTimes(1);
+    expect(requestMock).toHaveBeenCalledWith('/users', 'GET', { id: 1 });
+    await expect(response.json()).resolves.toEqual({ id: 1 });
+  });
+
+  it('batches requests with the same batch id and preserves response order', async () => {
+    const requestMock = vi.fn(async () => jsonResponse({ ok: true }));
+    const request = requestMock as unknown as BatchedUsersRequest;
+    const requestor = new Requestor<BatchedUsersApi, '/users', 'GET'>('/users', 'GET', request, new Cache(), {
+      canBatch: (input) => ('group' in input && input.group) || false,
+      batchInput: (inputs) => ({ ids: inputs.map(getSingleId) }),
+      unBatchOutput: (inputs) => inputs.map((input) => jsonResponse({ id: getSingleId(input) }))
+    });
+
+    const p1 = requestor.request({ id: 1, group: 'team' });
+    const p2 = requestor.request({ id: 2, group: 'team' });
+
+    await vi.advanceTimersByTimeAsync(99);
+    expect(requestMock).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(1);
+    expect(requestMock).toHaveBeenCalledTimes(1);
+    expect(requestMock).toHaveBeenCalledWith('/users', 'GET', { ids: [1, 2] });
+
+    const [response1, response2] = await Promise.all([p1, p2]);
+    await expect(response1.json()).resolves.toEqual({ id: 1 });
+    await expect(response2.json()).resolves.toEqual({ id: 2 });
+  });
+
+  it('rate limits separate batches by start time rather than completion time', async () => {
+    const starts: number[] = [];
+    const requestMock = vi.fn(async (_path: '/users', _method: 'GET', input: BatchedUsersApi['requestInput']) => {
+      starts.push(Date.now());
+
+      if ('ids' in input && input.ids[0] === 1) {
+        await new Promise((resolve) => setTimeout(resolve, 200));
+      }
+
+      return jsonResponse({ ids: 'ids' in input ? input.ids : [input.id] });
+    });
+    const request = requestMock as unknown as BatchedUsersRequest;
+
+    const requestor = new Requestor<BatchedUsersApi, '/users', 'GET'>('/users', 'GET', request, new Cache(), {
+      canBatch: (input) => ('group' in input && input.group) || false,
+      batchInput: (inputs) => ({ ids: inputs.map(getSingleId) }),
+      unBatchOutput: (_inputs, output) => [output]
+    });
+
+    const p1 = requestor.request({ id: 1, group: 'a' });
+    const p2 = requestor.request({ id: 2, group: 'b' });
+
+    await vi.advanceTimersByTimeAsync(100);
+    expect(starts).toEqual([100]);
+
+    await vi.advanceTimersByTimeAsync(100);
+    expect(starts).toEqual([100, 200]);
+
+    await vi.runAllTimersAsync();
+
+    const [response1, response2] = await Promise.all([p1, p2]);
+    await expect(response1.json()).resolves.toEqual({ ids: [1] });
+    await expect(response2.json()).resolves.toEqual({ ids: [2] });
+  });
+
+  it('returns batched error responses without rejecting them', async () => {
+    const requestMock = vi.fn(async () => jsonResponse({ ok: false }, 207));
+    const request = requestMock as unknown as BatchedUsersRequest;
+    const requestor = new Requestor<BatchedUsersApi, '/users', 'GET'>('/users', 'GET', request, new Cache(), {
+      canBatch: () => 'team',
+      batchInput: (inputs) => ({ ids: inputs.map(getSingleId) }),
+      unBatchOutput: () => [jsonResponse({ message: 'bad request' }, 400)]
+    });
+
+    const responsePromise = requestor.request({ id: 1 });
+
+    await vi.advanceTimersByTimeAsync(100);
+
+    const response = await responsePromise;
+    expect(response.ok).toBe(false);
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toEqual({ message: 'bad request' });
+  });
+
+  it('rejects all queued callers when a batched fetch throws', async () => {
+    const requestMock = vi.fn(async () => {
+      throw new Error('network down');
+    });
+    const request = requestMock as unknown as BatchedUsersRequest;
+    const requestor = new Requestor<BatchedUsersApi, '/users', 'GET'>('/users', 'GET', request, new Cache(), {
+      canBatch: () => 'team',
+      batchInput: (inputs) => ({ ids: inputs.map(getSingleId) }),
+      unBatchOutput: (_inputs, output) => [output]
+    });
+
+    const p1 = requestor.request({ id: 1 });
+    const p2 = requestor.request({ id: 2 });
+    const p1Expectation = expect(p1).rejects.toThrow('network down');
+    const p2Expectation = expect(p2).rejects.toThrow('network down');
+
+    await vi.advanceTimersByTimeAsync(100);
+
+    await Promise.all([p1Expectation, p2Expectation]);
+  });
+});
+
+describe('Query', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('deduplicates concurrent requests and returns readable responses to each caller', async () => {
+    const pending = deferred<Response>();
+    const requestMock = vi.fn().mockReturnValue(pending.promise);
+    const requestor = {
+      request: requestMock as PlainUsersRequest
+    } as unknown as PlainUsersRequestor;
+
+    const query = new Query<PlainUsersApi, '/users', 'GET'>({
+      path: '/users',
+      method: 'GET',
+      input: { id: 1 },
+      requestor,
+      cache: new Cache()
+    });
+
+    const p1 = query.request();
+    const p2 = query.request();
+
+    expect(requestMock).toHaveBeenCalledTimes(1);
+
+    pending.resolve(jsonResponse({ id: 1 }));
+
+    const [response1, response2] = await Promise.all([p1, p2]);
+    await expect(response1.json()).resolves.toEqual({ id: 1 });
+    await expect(response2.json()).resolves.toEqual({ id: 1 });
+  });
+
+  it('caches responses and returns a fresh readable clone on cache hits', async () => {
+    const requestMock = vi.fn().mockResolvedValue(jsonResponse({ id: 1, name: 'Ada' }));
+    const requestor = {
+      request: requestMock as PlainUsersRequest
+    } as unknown as PlainUsersRequestor;
+
+    const query = new Query<PlainUsersApi, '/users', 'GET'>({
+      path: '/users',
+      method: 'GET',
+      input: { id: 1 },
+      requestor,
+      cache: new Cache()
+    });
+
+    const first = await query.request();
+    const second = await query.request();
+
+    expect(requestMock).toHaveBeenCalledTimes(1);
+    expect(query.isCached).toBe(true);
+    await expect(first.json()).resolves.toEqual({ id: 1, name: 'Ada' });
+    await expect(second.json()).resolves.toEqual({ id: 1, name: 'Ada' });
+  });
+
+  it('updates success state from successful responses', async () => {
+    const requestMock = vi.fn().mockResolvedValue(jsonResponse({ id: 1, active: true }));
+    const requestor = {
+      request: requestMock as PlainUsersRequest
+    } as unknown as PlainUsersRequestor;
+
+    const query = new Query<PlainUsersApi, '/users', 'GET'>({
+      path: '/users',
+      method: 'GET',
+      input: { id: 1 },
+      requestor,
+      cache: new Cache()
+    });
+
+    const response = await query.request();
+
+    expect(query.status).toBe('success');
+    expect(query.data).toEqual({ id: 1, active: true });
+    expect(query.errorData).toBeNull();
+    await expect(response.json()).resolves.toEqual({ id: 1, active: true });
+  });
+
+  it('updates error state from error responses without throwing', async () => {
+    const requestMock = vi.fn().mockResolvedValue(jsonResponse({ message: 'missing' }, 404));
+    const requestor = {
+      request: requestMock as PlainUsersRequest
+    } as unknown as PlainUsersRequestor;
+
+    const query = new Query<PlainUsersApi, '/users', 'GET'>({
+      path: '/users',
+      method: 'GET',
+      input: { id: 99 },
+      requestor,
+      cache: new Cache()
+    });
+
+    const response = await query.request();
+
+    expect(query.status).toBe('error');
+    expect(query.data).toBeNull();
+    expect(query.errorData).toEqual({ message: 'missing' });
+    expect(response.ok).toBe(false);
+    await expect(response.json()).resolves.toEqual({ message: 'missing' });
+  });
+
+  it('clears the pending request when the request throws so later retries can succeed', async () => {
+    const requestMock = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('network down'))
+      .mockResolvedValueOnce(jsonResponse({ id: 1, recovered: true }));
+    const requestor = {
+      request: requestMock as PlainUsersRequest
+    } as unknown as PlainUsersRequestor;
+
+    const query = new Query<PlainUsersApi, '/users', 'GET'>({
+      path: '/users',
+      method: 'GET',
+      input: { id: 1 },
+      requestor,
+      cache: new Cache()
+    });
+
+    await expect(query.request()).rejects.toThrow('network down');
+    expect(query.status).toBe('error');
+
+    const response = await query.request();
+
+    expect(requestMock).toHaveBeenCalledTimes(2);
+    expect(query.status).toBe('success');
+    await expect(response.json()).resolves.toEqual({ id: 1, recovered: true });
+  });
+
+  it('resetCache forces the next request to fetch again', async () => {
+    const requestMock = vi
+      .fn()
+      .mockResolvedValueOnce(jsonResponse({ call: 1 }))
+      .mockResolvedValueOnce(jsonResponse({ call: 2 }));
+    const requestor = {
+      request: requestMock as PlainUsersRequest
+    } as unknown as PlainUsersRequestor;
+
+    const query = new Query<PlainUsersApi, '/users', 'GET'>({
+      path: '/users',
+      method: 'GET',
+      input: { id: 1 },
+      requestor,
+      cache: new Cache()
+    });
+
+    const first = await query.request();
+    query.resetCache();
+    const second = await query.request();
+
+    expect(requestMock).toHaveBeenCalledTimes(2);
+    await expect(first.json()).resolves.toEqual({ call: 1 });
+    await expect(second.json()).resolves.toEqual({ call: 2 });
+  });
+
+  it('honors custom cache timeout options', async () => {
+    const requestMock = vi
+      .fn()
+      .mockResolvedValueOnce(jsonResponse({ call: 1 }))
+      .mockResolvedValueOnce(jsonResponse({ call: 2 }));
+    const requestor = {
+      request: requestMock as PlainUsersRequest
+    } as unknown as PlainUsersRequestor;
+
+    const query = new Query<PlainUsersApi, '/users', 'GET'>({
+      path: '/users',
+      method: 'GET',
+      input: { id: 1 },
+      requestor,
+      cache: new Cache(),
+      opts: {
+        cache: { timeout: 50 }
+      }
+    });
+
+    const first = await query.request();
+    vi.advanceTimersByTime(49);
+    const cached = await query.request();
+    vi.advanceTimersByTime(1);
+    const refreshed = await query.request();
+
+    expect(requestMock).toHaveBeenCalledTimes(2);
+    await expect(first.json()).resolves.toEqual({ call: 1 });
+    await expect(cached.json()).resolves.toEqual({ call: 1 });
+    await expect(refreshed.json()).resolves.toEqual({ call: 2 });
+  });
+});

package/src/test/vitest.setup.ts

@@ -0,0 +1,3 @@
+if (typeof (globalThis as { $state?: unknown }).$state !== 'function') {
+  (globalThis as { $state: <T>(value: T) => T }).$state = <T>(value: T): T => value;
+}