@signalium/query 0.0.1 → 0.1.0

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

@@ -0,0 +1,327 @@
+/* eslint-disable @typescript-eslint/no-unused-expressions */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { SyncQueryStore, MemoryPersistentStore, valueKeyFor } from '../QueryStore.js';
+import { QueryClient } from '../QueryClient.js';
+import { query } from '../query.js';
+import { t, entity } from '../typeDefs.js';
+import { createMockFetch, testWithClient, sleep } from './utils.js';
+import { hashValue } from 'signalium/utils';
+
+/**
+ * GC Time Tests
+ *
+ * Tests gcTime-based garbage collection with sorted queue management,
+ * LRU interaction, and subscriber-aware eviction
+ */
+
+describe('GC Time', () => {
+  let client: QueryClient;
+  let mockFetch: ReturnType<typeof createMockFetch>;
+  let kv: any;
+  let store: any;
+
+  beforeEach(() => {
+    kv = new MemoryPersistentStore();
+    store = new SyncQueryStore(kv);
+    mockFetch = createMockFetch();
+    client = new QueryClient(store, { fetch: mockFetch as any, evictionMultiplier: 0.001 });
+  });
+
+  afterEach(() => {
+    client?.destroy();
+  });
+
+  describe('Basic GC', () => {
+    it('should evict queries from disk after gcTime expires', async () => {
+      const getItem = query(t => ({
+        path: '/item/[id]',
+        response: { id: t.number, name: t.string },
+        cache: { gcTime: 100, staleTime: 50 }, // 1 second
+      }));
+
+      mockFetch.get('/item/1', { id: 1, name: 'Item 1' });
+
+      await testWithClient(client, async () => {
+        const relay = getItem({ id: '1' });
+        expect(relay.value).toEqual(undefined);
+        await relay;
+        expect(relay.value).toEqual({ id: 1, name: 'Item 1' });
+      });
+
+      await sleep(75);
+
+      mockFetch.get('/item/1', { id: 1, name: 'Item 1 updated' }, { delay: 50 });
+      await testWithClient(client, async () => {
+        const relay = getItem({ id: '1' });
+        expect(relay.value).toEqual({ id: 1, name: 'Item 1' });
+        await relay;
+        expect(relay.value).toEqual({ id: 1, name: 'Item 1' });
+
+        await sleep(60);
+        expect(relay.value).toEqual({ id: 1, name: 'Item 1 updated' });
+      });
+
+      await sleep(200);
+
+      await testWithClient(client, async () => {
+        const relay = getItem({ id: '1' });
+        expect(relay.value).toEqual(undefined);
+        await relay;
+        expect(relay.value).toEqual({ id: 1, name: 'Item 1 updated' });
+      });
+    });
+
+    it('should NOT evict queries with active subscribers', async () => {
+      const getItem = query(t => ({
+        path: '/active',
+        response: { data: t.string },
+        cache: { gcTime: 50 },
+      }));
+
+      mockFetch.get('/active', { data: 'test' });
+
+      // Keep query active
+      await testWithClient(client, async () => {
+        const relay = getItem();
+        await relay;
+
+        const queryKey = hashValue(['GET:/active', undefined]);
+
+        // Wait past GC time
+        await sleep(60);
+
+        // Should still be in memory because it's active (has subscriber)
+        expect(client.queryInstances.has(queryKey)).toBe(true);
+      });
+    }, 3000);
+  });
+
+  describe('GC with LRU', () => {
+    it('should work alongside LRU cache eviction', async () => {
+      const User = entity(() => ({
+        __typename: t.typename('User'),
+        id: t.id,
+        name: t.string,
+      }));
+
+      const getUser = query(t => ({
+        path: '/users/[id]',
+        response: { user: User },
+        cache: {
+          maxCount: 2, // LRU size
+          gcTime: 5000, // 5 seconds
+        },
+      }));
+
+      mockFetch.get('/users/1', { user: { __typename: 'User', id: 1, name: 'User 1' } });
+      mockFetch.get('/users/2', { user: { __typename: 'User', id: 2, name: 'User 2' } });
+      mockFetch.get('/users/3', { user: { __typename: 'User', id: 3, name: 'User 3' } });
+
+      await testWithClient(client, async () => {
+        // Fetch 3 users - third should evict first from disk via LRU
+        const relay1 = getUser({ id: '1' });
+        await relay1;
+
+        const relay2 = getUser({ id: '2' });
+        await relay2;
+
+        const relay3 = getUser({ id: '3' });
+        await relay3;
+
+        const query1Key = hashValue(['GET:/users/[id]', { id: '1' }]);
+        const query2Key = hashValue(['GET:/users/[id]', { id: '2' }]);
+        const query3Key = hashValue(['GET:/users/[id]', { id: '3' }]);
+
+        // All should be in memory initially
+        expect(client.queryInstances.has(query1Key)).toBe(true);
+        expect(client.queryInstances.has(query2Key)).toBe(true);
+        expect(client.queryInstances.has(query3Key)).toBe(true);
+
+        // First query should be evicted from DISK by LRU (but still in memory)
+        expect(kv.getString(valueKeyFor(query1Key))).toBeUndefined();
+        expect(kv.getString(valueKeyFor(query2Key))).toBeDefined();
+        expect(kv.getString(valueKeyFor(query3Key))).toBeDefined();
+      });
+    });
+  });
+
+  describe('GC Queue Management', () => {
+    it('should add queries to GC queue when deactivated', async () => {
+      const getItem = query(t => ({
+        path: '/item',
+        response: { value: t.string },
+        cache: { gcTime: 2000 },
+      }));
+
+      mockFetch.get('/item', { value: 'test' });
+
+      const queryKey = hashValue(['GET:/item', undefined]);
+
+      await testWithClient(client, async () => {
+        const relay = getItem();
+        await relay;
+
+        expect(client.queryInstances.has(queryKey)).toBe(true);
+      });
+
+      // After context ends, query should be scheduled for GC
+      // In a real implementation, we'd check the GC queue
+      // For now, we verify the query is still in memory
+      expect(client.queryInstances.has(queryKey)).toBe(true);
+    });
+
+    it('should remove queries from GC queue when reactivated', async () => {
+      const getItem = query(t => ({
+        path: '/reactivate',
+        response: { n: t.number },
+        cache: { gcTime: 1000 },
+      }));
+
+      mockFetch.get('/reactivate', { n: 1 });
+
+      const queryKey = hashValue(['GET:/reactivate', undefined]);
+
+      await testWithClient(client, async () => {
+        const relay = getItem();
+        await relay;
+      });
+
+      // Query deactivated, scheduled for GC
+      await sleep(40);
+
+      // Reactivate before GC
+      mockFetch.get('/reactivate', { n: 2 });
+      await testWithClient(client, async () => {
+        const relay = getItem();
+        relay.value; // Access it
+        await sleep(60);
+
+        // Should still be in memory
+        expect(client.queryInstances.has(queryKey)).toBe(true);
+      });
+
+      // Even after original GC time, should not be evicted due to reactivation
+      await sleep(40);
+      expect(client.queryInstances.has(queryKey)).toBe(true);
+    });
+  });
+
+  describe('GC with Entities', () => {
+    it("should handle entity cleanup when query is GC'd", async () => {
+      const Post = entity(() => ({
+        __typename: t.typename('Post'),
+        id: t.id,
+        title: t.string,
+      }));
+
+      const User = entity(() => ({
+        __typename: t.typename('User'),
+        id: t.id,
+        name: t.string,
+        post: Post,
+      }));
+
+      const getUser = query(t => ({
+        path: '/user',
+        response: { user: User },
+        cache: { gcTime: 1000 },
+      }));
+
+      mockFetch.get('/user', {
+        user: {
+          __typename: 'User',
+          id: 1,
+          name: 'Alice',
+          post: {
+            __typename: 'Post',
+            id: 10,
+            title: 'Test Post',
+          },
+        },
+      });
+
+      await testWithClient(client, async () => {
+        const relay = getUser();
+        await relay;
+      });
+
+      const userKey = hashValue('User:1');
+      const postKey = hashValue('Post:10');
+
+      // Entities should exist in store
+      expect(kv.getString(valueKeyFor(userKey))).toBeDefined();
+      expect(kv.getString(valueKeyFor(postKey))).toBeDefined();
+
+      // Note: The actual GC of entities is handled by the LRU system
+      // when queries are evicted. The gcTime affects when queries
+      // are removed from memory, but disk cleanup is done by LRU.
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle queries without gcTime', async () => {
+      const getItem = query(t => ({
+        path: '/no-gc',
+        response: { data: t.string },
+        // No gcTime configured
+      }));
+
+      mockFetch.get('/no-gc', { data: 'test' });
+
+      const queryKey = hashValue(['GET:/no-gc', undefined]);
+
+      await testWithClient(client, async () => {
+        const relay = getItem();
+        await relay;
+      });
+
+      // Should remain in memory indefinitely
+      await sleep(100);
+      expect(client.queryInstances.has(queryKey)).toBe(true);
+    });
+
+    it('should handle very short gcTime', async () => {
+      const getItem = query(t => ({
+        path: '/short-gc',
+        response: { value: t.number },
+        cache: { gcTime: 100 }, // Very short
+      }));
+
+      mockFetch.get('/short-gc', { value: 42 });
+
+      const queryKey = hashValue(['GET:/short-gc', undefined]);
+
+      await testWithClient(client, async () => {
+        const relay = getItem();
+        await relay;
+      });
+
+      // Should be scheduled for GC quickly
+      // Note: Actual eviction timing depends on GC interval
+    });
+
+    it('should handle very long gcTime', async () => {
+      const getItem = query(t => ({
+        path: '/long-gc',
+        response: { data: t.string },
+        cache: { gcTime: 1000 * 60 * 60 }, // 1 hour
+      }));
+
+      mockFetch.get('/long-gc', { data: 'persisted' });
+
+      const queryKey = hashValue(['GET:/long-gc', undefined]);
+
+      await testWithClient(client, async () => {
+        const relay = getItem();
+        await relay;
+      });
+
+      // Should remain in memory for a while, then be evicted
+      await sleep(40);
+      expect(client.queryInstances.has(queryKey)).toBe(true);
+
+      await sleep(100);
+      expect(client.queryInstances.has(queryKey)).toBe(false);
+    });
+  });
+});

package/src/__tests__/mock-fetch.test.ts

@@ -155,15 +155,19 @@ describe('createMockFetch', () => {
     expect(data).toEqual({ users: [] });
   });
 
-  it('should only use each route once by default', async () => {
+  it('should reuse the last match when no unused mocks remain', async () => {
     const mockFetch = createMockFetch();
     mockFetch.get('/users/123', { id: 123, name: 'Alice' });
 
     // First call should succeed
-    await mockFetch('/users/123', { method: 'GET' });
+    const response1 = await mockFetch('/users/123', { method: 'GET' });
+    const data1 = await response1.json();
+    expect(data1).toEqual({ id: 123, name: 'Alice' });
 
-    // Second call should fail because route was already used
-    await expect(mockFetch('/users/123', { method: 'GET' })).rejects.toThrow('No mock response configured');
+    // Second call should reuse the same mock since there are no unused ones
+    const response2 = await mockFetch('/users/123', { method: 'GET' });
+    const data2 = await response2.json();
+    expect(data2).toEqual({ id: 123, name: 'Alice' });
   });
 
   it('should allow multiple setups for repeated calls', async () => {

package/src/__tests__/parse-entities.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { SyncQueryStore, MemoryPersistentStore, valueKeyFor, refIdsKeyFor, refCountKeyFor } from '../QueryStore.js';
 import { QueryClient } from '../QueryClient.js';
 import { entity, t } from '../typeDefs.js';
@@ -23,6 +23,10 @@ describe('Parse Entities', () => {
     store = queryStore;
   });
 
+  afterEach(() => {
+    client?.destroy();
+  });
+
   describe('nested entities', () => {
     it('should track refs for deeply nested entities (A->B->C)', async () => {
       const EntityC = entity(() => ({

package/src/__tests__/reactivity.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { SyncQueryStore, MemoryPersistentStore } from '../QueryStore.js';
 import { QueryClient, QueryClientContext } from '../QueryClient.js';
 import { entity, t } from '../typeDefs.js';
@@ -26,6 +26,10 @@ describe('Signalium Reactivity', () => {
     client = new QueryClient(store, { fetch: mockFetch as any });
   });
 
+  afterEach(() => {
+    client?.destroy();
+  });
+
   describe('Relay Lifecycle', () => {
     it('should start relay in pending state', async () => {
       mockFetch.get('/item', { data: 'test' }, { delay: 100 });

package/src/__tests__/refetch-interval.test.ts

@@ -0,0 +1,262 @@
+/* eslint-disable @typescript-eslint/no-unused-expressions */
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { SyncQueryStore, MemoryPersistentStore } from '../QueryStore.js';
+import { QueryClient } from '../QueryClient.js';
+import { query } from '../query.js';
+import { RefetchInterval } from '../types.js';
+import { createMockFetch, testWithClient, sleep } from './utils.js';
+
+/**
+ * RefetchInterval Tests
+ *
+ * Tests refetchInterval with dynamic GCD-based timer management,
+ * subscriber tracking, exponential backoff, and no overlapping fetches
+ */
+
+describe('RefetchInterval', () => {
+  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, refetchMultiplier: 0.1 });
+  });
+
+  afterEach(() => {
+    client?.destroy();
+  });
+
+  describe('Basic Refetch Interval', () => {
+    it('should refetch at specified interval', async () => {
+      let callCount = 0;
+      mockFetch.get('/counter', () => ({ count: ++callCount }));
+
+      const getCounter = query(t => ({
+        path: '/counter',
+        response: { count: t.number },
+        cache: { refetchInterval: RefetchInterval.Every1Second },
+      }));
+
+      await testWithClient(client, async () => {
+        const relay = getCounter();
+        await relay;
+        expect(relay.value).toEqual({ count: 1 });
+
+        // Wait for interval to trigger (100ms with 0.1 multiplier + buffer)
+        await sleep(120);
+        expect(relay.value?.count).toBeGreaterThan(1);
+
+        // Wait for another interval
+        await sleep(110);
+        expect(relay.value?.count).toBeGreaterThan(2);
+      });
+    });
+
+    it('should stop refetching when query is no longer accessed', async () => {
+      let callCount = 0;
+      mockFetch.get('/item', () => ({ n: ++callCount }));
+
+      const getItem = query(t => ({
+        path: '/item',
+        response: { n: t.number },
+        cache: { refetchInterval: RefetchInterval.Every1Second },
+      }));
+
+      await testWithClient(client, async () => {
+        const relay = getItem();
+        await relay;
+        const initialCount = relay.value!.n;
+
+        // Wait a bit (250ms with 0.1 multiplier = ~2.5 intervals)
+        await sleep(250);
+        const afterCount = relay.value!.n;
+
+        expect(afterCount).toBeGreaterThan(initialCount);
+
+        await sleep(250);
+      });
+
+      // After context ends, wait and check that no more calls happen
+      const countBeforeWait = callCount;
+      await sleep(200);
+
+      // Note: This test is simplified - in a real implementation,
+      // subscriber tracking would need proper cleanup
+      // For now we just verify the basic interval works
+    });
+  });
+
+  describe('Multiple Intervals with GCD', () => {
+    it('should handle multiple queries with different intervals efficiently', async () => {
+      let count1 = 0;
+      let count5 = 0;
+
+      mockFetch.get('/every1s', () => ({ count: ++count1 }));
+      mockFetch.get('/every5s', () => ({ count: ++count5 }));
+
+      const getEvery1s = query(t => ({
+        path: '/every1s',
+        response: { count: t.number },
+        cache: { refetchInterval: RefetchInterval.Every1Second },
+      }));
+
+      const getEvery5s = query(t => ({
+        path: '/every5s',
+        response: { count: t.number },
+        cache: { refetchInterval: RefetchInterval.Every5Seconds },
+      }));
+
+      await testWithClient(client, async () => {
+        const relay1s = getEvery1s();
+        const relay5s = getEvery5s();
+
+        await relay1s;
+        await relay5s;
+
+        // Wait and verify different refetch rates (350ms = 3.5 intervals of 1s)
+        await sleep(350);
+
+        // 1s query should have refetched ~3 times
+        expect(count1).toBeGreaterThanOrEqual(3);
+        expect(count1).toBeLessThanOrEqual(5);
+
+        // 5s query should have refetched 0-1 times
+        expect(count5).toBeGreaterThanOrEqual(1);
+        expect(count5).toBeLessThanOrEqual(2);
+
+        // Wait for 5s interval (200ms more)
+        await sleep(200);
+
+        // 5s query should now have refetched
+        expect(count5).toBeGreaterThanOrEqual(2);
+      });
+    });
+
+    it('should use GCD for multiple queries with compatible intervals', async () => {
+      // Every5Seconds and Every10Seconds should use GCD of 5s
+      let count5 = 0;
+      let count10 = 0;
+
+      mockFetch.get('/5s', () => ({ n: ++count5 }));
+      mockFetch.get('/10s', () => ({ n: ++count10 }));
+
+      const get5s = query(t => ({
+        path: '/5s',
+        response: { n: t.number },
+        cache: { refetchInterval: RefetchInterval.Every5Seconds },
+      }));
+
+      const get10s = query(t => ({
+        path: '/10s',
+        response: { n: t.number },
+        cache: { refetchInterval: RefetchInterval.Every10Seconds },
+      }));
+
+      await testWithClient(client, async () => {
+        const relay5 = get5s();
+        const relay10 = get10s();
+
+        await Promise.all([relay5, relay10]);
+
+        // Wait 1100ms (11 seconds at 0.1x = 1.1s)
+        await sleep(1100);
+
+        // 5s should refetch ~2 times
+        expect(count5).toBeGreaterThanOrEqual(2);
+
+        // 10s should refetch ~1 time
+        expect(count10).toBeGreaterThanOrEqual(1);
+        expect(count10).toBeLessThanOrEqual(2);
+      });
+    });
+  });
+
+  describe('No Overlapping Fetches', () => {
+    it('should wait for previous fetch to complete before next refetch', async () => {
+      let activeFetches = 0;
+      let maxConcurrent = 0;
+      let fetchCount = 0;
+
+      mockFetch.get('/slow', async () => {
+        activeFetches++;
+        maxConcurrent = Math.max(maxConcurrent, activeFetches);
+        fetchCount++;
+        await sleep(80); // Slow fetch (80ms = 800ms at 0.1x)
+        activeFetches--;
+        return { count: fetchCount };
+      });
+
+      const getSlow = query(t => ({
+        path: '/slow',
+        response: { count: t.number },
+        cache: { refetchInterval: RefetchInterval.Every1Second },
+      }));
+
+      await testWithClient(client, async () => {
+        const relay = getSlow();
+        await relay;
+
+        // Wait for several intervals (350ms = 3.5 intervals)
+        await sleep(350);
+
+        // Should never have overlapping fetches
+        expect(maxConcurrent).toBe(1);
+
+        // Should have attempted multiple fetches but not overlapping
+        expect(fetchCount).toBeGreaterThan(1);
+      });
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle query without refetchInterval', async () => {
+      let callCount = 0;
+      mockFetch.get('/no-interval', () => ({ n: ++callCount }));
+
+      const getItem = query(t => ({
+        path: '/no-interval',
+        response: { n: t.number },
+        // No refetchInterval
+      }));
+
+      await testWithClient(client, async () => {
+        const relay = getItem();
+        await relay;
+        expect(relay.value).toEqual({ n: 1 });
+
+        // Wait a bit (200ms = 2s at 0.1x)
+        await sleep(200);
+
+        // Should not have refetched
+        expect(callCount).toBe(1);
+      });
+    });
+
+    it('should handle very fast intervals', async () => {
+      let callCount = 0;
+      mockFetch.get('/fast', () => ({ count: ++callCount }));
+
+      const getFast = query(t => ({
+        path: '/fast',
+        response: { count: t.number },
+        cache: { refetchInterval: RefetchInterval.Every1Second },
+      }));
+
+      await testWithClient(client, async () => {
+        const relay = getFast();
+        await relay;
+
+        // Wait 250ms (2.5 intervals at 0.1x)
+        await sleep(250);
+
+        // Should have refetched at least twice
+        expect(callCount).toBeGreaterThanOrEqual(2);
+      });
+    });
+  });
+});

package/src/__tests__/rest-query-api.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { SyncQueryStore, MemoryPersistentStore } from '../QueryStore.js';
 import { QueryClient } from '../QueryClient.js';
 import { entity, t } from '../typeDefs.js';
@@ -22,6 +22,10 @@ describe('REST Query API', () => {
     client = new QueryClient(store, { fetch: mockFetch as any });
   });
 
+  afterEach(() => {
+    client?.destroy();
+  });
+
   describe('Basic Query Execution', () => {
     it('should execute a GET query with path parameters', async () => {
       mockFetch.get('/users/[id]', { id: 123, name: 'Test User' });