@signalium/query 0.0.1 → 0.1.0

package/src/__tests__/stale-time.test.ts

@@ -0,0 +1,357 @@
+/* eslint-disable @typescript-eslint/no-unused-expressions */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { SyncQueryStore, MemoryPersistentStore, updatedAtKeyFor } from '../QueryStore.js';
+import { QueryClient } from '../QueryClient.js';
+import { query } from '../query.js';
+import { createMockFetch, testWithClient, sleep } from './utils.js';
+
+/**
+ * StaleTime Tests
+ *
+ * Tests staleTime behavior: serving cached data while refetching in background
+ */
+
+describe('StaleTime', () => {
+  let client: QueryClient;
+  let mockFetch: ReturnType<typeof createMockFetch>;
+  let kv: any;
+  let store: any;
+
+  beforeEach(() => {
+    client?.destroy();
+    kv = new MemoryPersistentStore();
+    store = new SyncQueryStore(kv);
+    mockFetch = createMockFetch();
+    client = new QueryClient(store, { fetch: mockFetch as any });
+  });
+
+  describe('Fresh Data', () => {
+    it('should not refetch when data is fresh (within staleTime)', async () => {
+      // Set up query with 10 second staleTime
+      const getItem = query(t => ({
+        path: '/item',
+        response: { value: t.string },
+        cache: { staleTime: 10000 }, // 10 seconds
+      }));
+
+      mockFetch.get('/item', { value: 'first' });
+
+      await testWithClient(client, async () => {
+        // First fetch
+        const relay1 = getItem();
+        await relay1;
+        expect(relay1.value).toEqual({ value: 'first' });
+        expect(mockFetch.calls).toHaveLength(1);
+
+        // Second access immediately (data is fresh)
+        mockFetch.get('/item', { value: 'second' });
+        const relay2 = getItem();
+
+        // Force evaluation
+        relay2.value;
+        await sleep(50);
+
+        // Should use cached data without refetch
+        expect(relay2.value).toEqual({ value: 'first' });
+        expect(mockFetch.calls).toHaveLength(1); // Still only one call
+      });
+    });
+
+    it('should use fresh data from disk cache without refetch', async () => {
+      const getItem = query(t => ({
+        path: '/item',
+        response: { data: t.number },
+        cache: { staleTime: 5000 },
+      }));
+
+      mockFetch.get('/item', { data: 42 });
+
+      await testWithClient(client, async () => {
+        const relay1 = getItem();
+        await relay1;
+        expect(mockFetch.calls).toHaveLength(1);
+      });
+
+      // Create new client with same store (simulating app restart)
+      mockFetch.reset();
+      mockFetch.get('/item', { data: 99 }, { delay: 50 });
+      const client2 = new QueryClient(store, { fetch: mockFetch as any });
+
+      await testWithClient(client2, async () => {
+        const relay = getItem();
+
+        // Should immediately have cached value
+        relay.value;
+        await sleep(10);
+        expect(relay.value).toEqual({ data: 42 });
+
+        // Should not refetch since data is still fresh
+        await sleep(100);
+        expect(mockFetch.calls).toHaveLength(0);
+      });
+    });
+  });
+
+  describe('Stale Data', () => {
+    it('should serve stale data immediately while refetching in background', async () => {
+      const getItem = query(t => ({
+        path: '/item',
+        response: { count: t.number },
+        staleTime: 100, // 100ms
+      }));
+
+      mockFetch.get('/item', { count: 1 });
+
+      await testWithClient(client, async () => {
+        // Initial fetch
+        const relay1 = getItem();
+        await relay1;
+        expect(relay1.value).toEqual({ count: 1 });
+      });
+
+      // Wait for data to become stale, and unwatch query entirely
+      await sleep(200);
+
+      await testWithClient(client, async () => {
+        // Set up new response
+        mockFetch.get('/item', { count: 2 }, { delay: 50 });
+
+        // Access again - should serve stale data immediately
+        const relay2 = getItem();
+        relay2.value;
+        await sleep(10);
+
+        // Should have stale data immediately
+        expect(relay2.value).toEqual({ count: 1 });
+
+        // Wait for background refetch to complete
+        await sleep(100);
+
+        // Should now have fresh data
+        expect(relay2.value).toEqual({ count: 2 });
+        expect(mockFetch.calls).toHaveLength(2);
+      });
+    });
+
+    it('should refetch stale data from disk cache', async () => {
+      const getItem = query(t => ({
+        path: '/data',
+        response: { version: t.number },
+        staleTime: 100,
+      }));
+
+      mockFetch.get('/data', { version: 1 });
+
+      await testWithClient(client, async () => {
+        const relay = getItem();
+        await relay;
+      });
+
+      // Wait for data to become stale
+      await sleep(150);
+
+      // Create new client
+      mockFetch.reset();
+      mockFetch.get('/data', { version: 2 }, { delay: 50 });
+      const client2 = new QueryClient(store, { fetch: mockFetch as any });
+
+      await testWithClient(client2, async () => {
+        const relay = getItem();
+
+        // Should have cached value immediately
+        relay.value;
+        await sleep(10);
+        expect(relay.value).toEqual({ version: 1 });
+
+        // Should trigger background refetch
+        await sleep(100);
+
+        expect(relay.value).toEqual({ version: 2 });
+        expect(mockFetch.calls).toHaveLength(1);
+      });
+    });
+
+    it('should handle no staleTime (always refetch)', async () => {
+      const getItem = query(t => ({
+        path: '/item',
+        response: { value: t.string },
+        // No staleTime configured
+      }));
+
+      mockFetch.get('/item', { value: 'first' });
+
+      await testWithClient(client, async () => {
+        const relay1 = getItem();
+        await relay1;
+        expect(mockFetch.calls).toHaveLength(1);
+      });
+
+      // Access again immediately
+      await testWithClient(client, async () => {
+        mockFetch.get('/item', { value: 'second' }, { delay: 50 });
+        const relay2 = getItem();
+
+        relay2.value;
+        await sleep(10);
+
+        // Should have cached value
+        expect(relay2.value).toEqual({ value: 'first' });
+
+        // But should refetch in background
+        await sleep(100);
+
+        expect(relay2.value).toEqual({ value: 'second' });
+        expect(mockFetch.calls).toHaveLength(2);
+      });
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle staleTime of 0 (always stale)', async () => {
+      const getItem = query(t => ({
+        path: '/item',
+        response: { n: t.number },
+        cache: { staleTime: 0 },
+      }));
+
+      mockFetch.get('/item', { n: 1 });
+
+      await testWithClient(client, async () => {
+        const relay1 = getItem();
+        await relay1;
+      });
+
+      await testWithClient(client, async () => {
+        mockFetch.get('/item', { n: 2 }, { delay: 50 });
+        const relay2 = getItem();
+
+        // Should serve cached but refetch immediately
+        relay2.value;
+        await sleep(10);
+        expect(relay2.value).toEqual({ n: 1 });
+
+        await sleep(100);
+        expect(relay2.value).toEqual({ n: 2 });
+      });
+    });
+
+    it('should handle very long staleTime', async () => {
+      vi.useFakeTimers();
+
+      try {
+        const getItem = query(t => ({
+          path: '/item',
+          response: { data: t.string },
+          cache: { staleTime: 1000 * 60 * 60 }, // 1 hour
+        }));
+
+        mockFetch.get('/item', { data: 'cached' });
+
+        // First subscription - fetch initial data
+        await testWithClient(client, async () => {
+          const relay1 = getItem();
+          await relay1;
+          expect(relay1.value).toEqual({ data: 'cached' });
+          expect(mockFetch.calls).toHaveLength(1);
+        });
+
+        // Unsubscribed now (testWithClient ended)
+
+        // Second subscription - should still use cache (data is fresh)
+        mockFetch.reset();
+        mockFetch.get('/item', { data: 'fresh1' });
+        await testWithClient(client, async () => {
+          const relay2 = getItem();
+          relay2.value;
+          await vi.advanceTimersByTimeAsync(100);
+
+          // Should use cached data without refetch (still fresh)
+          expect(relay2.value).toEqual({ data: 'cached' });
+          expect(mockFetch.calls).toHaveLength(0);
+        });
+
+        // Advance time by 30 minutes - still within 1 hour staleTime
+        await vi.advanceTimersByTimeAsync(30 * 60 * 1000);
+
+        // Third subscription - data should still be fresh
+        mockFetch.reset();
+        mockFetch.get('/item', { data: 'fresh2' });
+        await testWithClient(client, async () => {
+          const relay3 = getItem();
+          relay3.value;
+          await vi.advanceTimersByTimeAsync(100);
+
+          // Should still use cached data (within 1 hour)
+          expect(relay3.value).toEqual({ data: 'cached' });
+          expect(mockFetch.calls).toHaveLength(0);
+        });
+
+        // Advance time past the 1 hour mark (31 more minutes = 61 minutes total)
+        await vi.advanceTimersByTimeAsync(31 * 60 * 1000);
+
+        // Fourth subscription - data should now be stale and trigger refetch
+        mockFetch.reset();
+        mockFetch.get('/item', { data: 'fresh-after-hour' }, { delay: 100 });
+        await testWithClient(client, async () => {
+          const relay4 = getItem();
+
+          // Should serve stale data immediately
+          relay4.value;
+          await vi.advanceTimersByTimeAsync(10);
+          expect(relay4.value).toEqual({ data: 'cached' });
+
+          // Wait for background refetch to complete
+          await vi.advanceTimersByTimeAsync(100);
+
+          // Should now have fresh data
+          expect(relay4.value).toEqual({ data: 'fresh-after-hour' });
+          expect(mockFetch.calls).toHaveLength(1);
+        });
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it('should handle concurrent access to stale data', async () => {
+      const getItem = query(t => ({
+        path: '/item',
+        response: { id: t.number },
+        cache: { staleTime: 50 },
+      }));
+
+      mockFetch.get('/item', { id: 1 });
+
+      await testWithClient(client, async () => {
+        const relay1 = getItem();
+        await relay1;
+
+        await sleep(100); // Make stale
+      });
+
+      await testWithClient(client, async () => {
+        mockFetch.get('/item', { id: 2 }, { delay: 100 });
+
+        // Multiple concurrent accesses
+        const relay2 = getItem();
+        const relay3 = getItem();
+        const relay4 = getItem();
+
+        // All should be the same relay
+        expect(relay2).toBe(relay3);
+        expect(relay3).toBe(relay4);
+
+        // Should serve stale data immediately
+        relay2.value;
+        await sleep(10);
+        expect(relay2.value).toEqual({ id: 1 });
+
+        // Wait for refetch
+        await sleep(100);
+        expect(relay2.value).toEqual({ id: 2 });
+
+        // Should only refetch once
+        expect(mockFetch.calls).toHaveLength(2);
+      });
+    });
+  });
+});

package/src/__tests__/utils.ts

@@ -51,13 +51,8 @@ export function createMockFetch(): MockFetch {
   const calls: Array<{ url: string; options: RequestInit }> = [];
 
   const matchRoute = (url: string, method: string): MockRoute | undefined => {
-    // First try exact match
-    const exactMatch = routes.find(r => r.url === url && r.method === method && !r.used);
-    if (exactMatch) return exactMatch;
-
-    // Then try pattern matching (for URLs with query params or path segments)
-    return routes.find(r => {
-      if (r.method !== method || r.used) return false;
+    const isMatch = (r: MockRoute): boolean => {
+      if (r.method !== method) return false;
 
       // Simple pattern: check if the route URL is a prefix or matches the base path
       const routeBase = r.url.split('?')[0];
@@ -80,7 +75,20 @@ export function createMockFetch(): MockFetch {
       }
 
       return false;
-    });
+    };
+
+    // First try to find an unused match
+    const unusedMatch = routes.find(r => !r.used && isMatch(r));
+    if (unusedMatch) return unusedMatch;
+
+    // If no unused matches, reuse the last matching route
+    for (let i = routes.length - 1; i >= 0; i--) {
+      if (isMatch(routes[i])) {
+        return routes[i];
+      }
+    }
+
+    return undefined;
   };
 
   const mockFetch = async (url: string, options: RequestInit = {}): Promise<Response> => {
@@ -110,6 +118,14 @@ export function createMockFetch(): MockFetch {
     const status = route.options.status ?? 200;
     const headers = route.options.headers ?? {};
 
+    // Resolve response if it's a function
+    const resolveResponse = async () => {
+      if (typeof route.response === 'function') {
+        return await route.response();
+      }
+      return route.response;
+    };
+
     // Create a mock Response object
     const response = {
       ok: status >= 200 && status < 300,
@@ -120,11 +136,11 @@ export function createMockFetch(): MockFetch {
         if (route.options.jsonError) {
           throw route.options.jsonError;
         }
-        return route.response;
+        return await resolveResponse();
       },
-      text: async () => JSON.stringify(route.response),
-      blob: async () => new Blob([JSON.stringify(route.response)]),
-      arrayBuffer: async () => new TextEncoder().encode(JSON.stringify(route.response)).buffer,
+      text: async () => JSON.stringify(await resolveResponse()),
+      blob: async () => new Blob([JSON.stringify(await resolveResponse())]),
+      arrayBuffer: async () => new TextEncoder().encode(JSON.stringify(await resolveResponse())).buffer,
       clone: () => response,
     } as Response;
 

package/src/__tests__/validation-edge-cases.test.ts

@@ -19,6 +19,7 @@ describe('Type Validation and Edge Cases', () => {
   let mockFetch: ReturnType<typeof createMockFetch>;
 
   beforeEach(() => {
+    client?.destroy();
     const store = new SyncQueryStore(new MemoryPersistentStore());
     mockFetch = createMockFetch();
     client = new QueryClient(store, { fetch: mockFetch as any });

package/src/query.ts

@@ -67,6 +67,7 @@ interface RESTQueryDefinition {
   response: Record<string, ObjectFieldTypeDef> | ObjectFieldTypeDef;
 
   cache?: QueryCacheOptions;
+  refetchInterval?: number;
 }
 
 type ExtractTypesFromObjectOrTypeDef<S extends Record<string, ObjectFieldTypeDef> | ObjectFieldTypeDef | undefined> =
@@ -123,7 +124,7 @@ export function query<const QDef extends RESTQueryDefinition>(
       }
 
       if (queryDefinition === undefined) {
-        const { path, method = 'GET', response, cache } = queryDefinitionBuilder(t);
+        const { path, method = 'GET', response, cache, refetchInterval } = queryDefinitionBuilder(t);
 
         const id = `${method}:${path}`;
 

package/src/react/__tests__/basic.test.tsx

@@ -23,6 +23,7 @@ describe('React Query Integration', () => {
   let mockFetch: ReturnType<typeof createMockFetch>;
 
   beforeEach(() => {
+    client?.destroy();
     const store = new SyncQueryStore(new MemoryPersistentStore());
     mockFetch = createMockFetch();
     client = new QueryClient(store, { fetch: mockFetch as any });
@@ -216,7 +217,7 @@ describe('React Query Integration', () => {
 
       await expect.element(getByText('Alice Updated')).toBeInTheDocument();
       expect(getByTestId(String(Counter.testId))).toBeDefined();
-      expect(Counter.renderCount).toBe(3);
+      expect(Counter.renderCount).toBe(2);
     });
 
     it('should keep multiple components in sync when sharing entity data', async () => {
@@ -906,16 +907,20 @@ describe('React Query Integration', () => {
       // Trigger refetch with delay
       await getByText('Refetch').click();
 
-      // During refetch, should show loading AND still have previous value
+      // During refetch, should show fetching AND still have previous value
       await sleep(10);
-      // Note: The value should still be accessible even during pending state
+      // Note: The value should still be accessible even during refetch state
       expect(itemQuery!.value?.data).toBe('first');
-      expect(itemQuery!.isPending).toBe(true);
+      expect(itemQuery!.isPending).toBe(false); // Not pending - we have data!
+      expect(itemQuery!.isRefetching).toBe(true); // But we are refetching
+      expect(itemQuery!.isFetching).toBe(true); // isFetching = isPending || isRefetching
 
       await sleep(100);
 
       // After refetch completes
       expect(getByTestId('data').element().textContent).toBe('second');
+      expect(itemQuery!.isRefetching).toBe(false);
+      expect(itemQuery!.isFetching).toBe(false);
     });
   });
 });

package/src/react/__tests__/component.test.tsx

@@ -24,6 +24,7 @@ describe('React Query Integration with component()', () => {
   let mockFetch: ReturnType<typeof createMockFetch>;
 
   beforeEach(() => {
+    client?.destroy();
     const store = new SyncQueryStore(new MemoryPersistentStore());
     mockFetch = createMockFetch();
     client = new QueryClient(store, { fetch: mockFetch as any });
@@ -724,6 +725,7 @@ describe('React Query Integration with component()', () => {
         return (
           <div>
             <div data-testid="count">{result.isReady ? result.value!.count : 'Loading'}</div>
+            <div data-testid="refetching">{result.isRefetching ? 'Refetching' : 'Idle'}</div>
             <button
               onClick={async () => {
                 mockFetch.get('/counter', { count: (result.value?.count ?? 0) + 1 });
@@ -754,6 +756,7 @@ describe('React Query Integration with component()', () => {
       await sleep(10);
 
       expect(getByTestId('count').element().textContent).toBe('1');
+      expect(getByTestId('refetching').element().textContent).toBe('Idle');
     });
 
     it('should work with nested components', async () => {
@@ -962,16 +965,20 @@ describe('React Query Integration with component()', () => {
       // Trigger refetch with delay
       await getByText('Refetch').click();
 
-      // During refetch, should show loading AND still have previous value
+      // During refetch, should show fetching AND still have previous value
       await sleep(10);
-      // Note: The value should still be accessible even during pending state
+      // Note: The value should still be accessible even during refetch state
       expect(itemQuery!.value?.data).toBe('first');
-      expect(itemQuery!.isPending).toBe(true);
+      expect(itemQuery!.isPending).toBe(false); // Not pending - we have data!
+      expect(itemQuery!.isRefetching).toBe(true); // But we are refetching
+      expect(itemQuery!.isFetching).toBe(true); // isFetching = isPending || isRefetching
 
       await sleep(100);
 
       // After refetch completes
       expect(getByTestId('data').element().textContent).toBe('second');
+      expect(itemQuery!.isRefetching).toBe(false);
+      expect(itemQuery!.isFetching).toBe(false);
     });
   });
 });

package/src/types.ts

@@ -1,6 +1,15 @@
 import { PendingReactivePromise, ReadyReactivePromise } from 'signalium';
 import { ReactivePromise } from 'signalium';
 
+export enum RefetchInterval {
+  Every1Second = 1000,
+  Every5Seconds = 5000,
+  Every10Seconds = 10000,
+  Every30Seconds = 30000,
+  Every1Minute = 60000,
+  Every5Minutes = 300000,
+}
+
 export const enum Mask {
   // Fundamental types
   UNDEFINED = 1 << 0,
@@ -110,6 +119,8 @@ export interface APITypes {
 
 type QueryResultExtensions<T> = {
   refetch: () => Promise<T>;
+  readonly isRefetching: boolean;
+  readonly isFetching: boolean;
 };
 
 export type QueryResult<T> = ReactivePromise<T> & QueryResultExtensions<T>;