@signalium/query 0.0.0

package/src/__tests__/path-interpolation.test.ts

@@ -0,0 +1,225 @@
+import { describe, it, expect } from 'vitest';
+import { createPathInterpolator } from '../pathInterpolator.js';
+
+describe('createPathInterpolator', () => {
+  describe('basic path interpolation', () => {
+    it('should interpolate a single parameter', () => {
+      const interpolate = createPathInterpolator('/users/[userId]');
+      const result = interpolate({ userId: '123' });
+      expect(result).toBe('/users/123');
+    });
+
+    it('should interpolate multiple parameters', () => {
+      const interpolate = createPathInterpolator('/users/[userId]/posts/[postId]');
+      const result = interpolate({ userId: '123', postId: '456' });
+      expect(result).toBe('/users/123/posts/456');
+    });
+
+    it('should handle consecutive parameters', () => {
+      const interpolate = createPathInterpolator('/items/[category][subcategory]');
+      const result = interpolate({ category: 'books', subcategory: 'fiction' });
+      expect(result).toBe('/items/booksfiction');
+    });
+
+    it('should handle path with no parameters', () => {
+      const interpolate = createPathInterpolator('/static/path');
+      const result = interpolate({});
+      expect(result).toBe('/static/path');
+    });
+
+    it('should handle path starting with parameter', () => {
+      const interpolate = createPathInterpolator('[tenant]/users/[userId]');
+      const result = interpolate({ tenant: 'acme', userId: '123' });
+      expect(result).toBe('acme/users/123');
+    });
+
+    it('should handle path ending with parameter', () => {
+      const interpolate = createPathInterpolator('/users/[userId]');
+      const result = interpolate({ userId: '123' });
+      expect(result).toBe('/users/123');
+    });
+  });
+
+  describe('URL encoding', () => {
+    it('should URL-encode special characters in path parameters', () => {
+      const interpolate = createPathInterpolator('/users/[userId]');
+      const result = interpolate({ userId: 'user@example.com' });
+      expect(result).toBe('/users/user%40example.com');
+    });
+
+    it('should URL-encode spaces', () => {
+      const interpolate = createPathInterpolator('/search/[query]');
+      const result = interpolate({ query: 'hello world' });
+      expect(result).toBe('/search/hello%20world');
+    });
+
+    it('should URL-encode forward slashes', () => {
+      const interpolate = createPathInterpolator('/files/[path]');
+      const result = interpolate({ path: 'folder/subfolder/file.txt' });
+      expect(result).toBe('/files/folder%2Fsubfolder%2Ffile.txt');
+    });
+
+    it('should handle unicode characters', () => {
+      const interpolate = createPathInterpolator('/items/[name]');
+      const result = interpolate({ name: '日本語' });
+      expect(result).toBe('/items/%E6%97%A5%E6%9C%AC%E8%AA%9E');
+    });
+  });
+
+  describe('query string parameters', () => {
+    it('should append extra parameters as query string', () => {
+      const interpolate = createPathInterpolator('/users/[userId]');
+      const result = interpolate({ userId: '123', page: 2, limit: 10 });
+      expect(result).toBe('/users/123?page=2&limit=10');
+    });
+
+    it('should append all non-path parameters as query string', () => {
+      const interpolate = createPathInterpolator('/users/[userId]/posts/[postId]');
+      const result = interpolate({
+        userId: '123',
+        postId: '456',
+        page: 2,
+        limit: 10,
+        sort: 'desc',
+      });
+      expect(result).toBe('/users/123/posts/456?page=2&limit=10&sort=desc');
+    });
+
+    it('should handle only query parameters when path has no params', () => {
+      const interpolate = createPathInterpolator('/search');
+      const result = interpolate({ q: 'test', page: 1 });
+      expect(result).toBe('/search?q=test&page=1');
+    });
+
+    it('should skip undefined query parameters', () => {
+      const interpolate = createPathInterpolator('/users/[userId]');
+      const result = interpolate({ userId: '123', page: 2, limit: undefined });
+      expect(result).toBe('/users/123?page=2');
+    });
+
+    it('should include null and empty string values in query params', () => {
+      const interpolate = createPathInterpolator('/users/[userId]');
+      const result = interpolate({ userId: '123', filter: null, name: '' });
+      expect(result).toBe('/users/123?filter=null&name=');
+    });
+
+    it('should handle boolean query parameters', () => {
+      const interpolate = createPathInterpolator('/items');
+      const result = interpolate({ active: true, deleted: false });
+      expect(result).toBe('/items?active=true&deleted=false');
+    });
+
+    it('should handle numeric query parameters', () => {
+      const interpolate = createPathInterpolator('/items');
+      const result = interpolate({ id: 0, count: 100 });
+      expect(result).toBe('/items?id=0&count=100');
+    });
+  });
+
+  describe('type coercion', () => {
+    it('should convert numeric path parameters to string', () => {
+      const interpolate = createPathInterpolator('/users/[userId]');
+      const result = interpolate({ userId: 123 });
+      expect(result).toBe('/users/123');
+    });
+
+    it('should convert boolean path parameters to string', () => {
+      const interpolate = createPathInterpolator('/settings/[enabled]');
+      const result = interpolate({ enabled: true });
+      expect(result).toBe('/settings/true');
+    });
+
+    it('should convert null path parameters to string', () => {
+      const interpolate = createPathInterpolator('/items/[id]');
+      const result = interpolate({ id: null });
+      expect(result).toBe('/items/null');
+    });
+
+    it('should handle object conversion to string', () => {
+      const interpolate = createPathInterpolator('/items/[id]');
+      const result = interpolate({ id: { value: 123 } });
+      expect(result).toBe('/items/%5Bobject%20Object%5D');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty path template', () => {
+      const interpolate = createPathInterpolator('');
+      const result = interpolate({});
+      expect(result).toBe('');
+    });
+
+    it('should handle empty params object', () => {
+      const interpolate = createPathInterpolator('/users/[userId]/posts/[postId]');
+      const result = interpolate({});
+      expect(result).toBe('/users/undefined/posts/undefined');
+    });
+
+    it('should handle missing path parameter values', () => {
+      const interpolate = createPathInterpolator('/users/[userId]/posts/[postId]');
+      const result = interpolate({ userId: '123' });
+      expect(result).toBe('/users/123/posts/undefined');
+    });
+
+    it('should handle parameter names with underscores', () => {
+      const interpolate = createPathInterpolator('/users/[user_id]');
+      const result = interpolate({ user_id: '123' });
+      expect(result).toBe('/users/123');
+    });
+
+    it('should handle parameter names with hyphens', () => {
+      const interpolate = createPathInterpolator('/users/[user-id]');
+      const result = interpolate({ 'user-id': '123' });
+      expect(result).toBe('/users/123');
+    });
+
+    it('should handle parameter names with numbers', () => {
+      const interpolate = createPathInterpolator('/items/[item1]/[item2]');
+      const result = interpolate({ item1: 'first', item2: 'second' });
+      expect(result).toBe('/items/first/second');
+    });
+
+    it('should be reusable for multiple interpolations', () => {
+      const interpolate = createPathInterpolator('/users/[userId]');
+
+      const result1 = interpolate({ userId: '123' });
+      const result2 = interpolate({ userId: '456' });
+      const result3 = interpolate({ userId: '789', page: 1 });
+
+      expect(result1).toBe('/users/123');
+      expect(result2).toBe('/users/456');
+      expect(result3).toBe('/users/789?page=1');
+    });
+
+    it('should handle complex real-world example', () => {
+      const interpolate = createPathInterpolator('/api/v1/tenants/[tenantId]/users/[userId]/documents/[documentId]');
+      const result = interpolate({
+        tenantId: 'acme-corp',
+        userId: 'user@example.com',
+        documentId: '12345',
+        version: 2,
+        format: 'pdf',
+        download: true,
+      });
+      expect(result).toBe(
+        '/api/v1/tenants/acme-corp/users/user%40example.com/documents/12345?version=2&format=pdf&download=true',
+      );
+    });
+  });
+
+  describe('performance characteristics', () => {
+    it('should create the interpolator once and reuse it efficiently', () => {
+      const interpolate = createPathInterpolator('/users/[userId]/posts/[postId]');
+
+      // Simulate multiple calls (as would happen in production)
+      const results = [];
+      for (let i = 0; i < 1000; i++) {
+        results.push(interpolate({ userId: `user${i}`, postId: `post${i}` }));
+      }
+
+      expect(results[0]).toBe('/users/user0/posts/post0');
+      expect(results[999]).toBe('/users/user999/posts/post999');
+      expect(results.length).toBe(1000);
+    });
+  });
+});

package/src/__tests__/reactivity.test.ts

@@ -0,0 +1,420 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { SyncQueryStore, MemoryPersistentStore } from '../QueryStore.js';
+import { QueryClient, QueryClientContext } from '../QueryClient.js';
+import { entity, t } from '../typeDefs.js';
+import { query } from '../query.js';
+import { watcher, withContexts, reactive } from 'signalium';
+import { createMockFetch, testWithClient } from './utils.js';
+
+/**
+ * Signalium Reactivity Tests
+ *
+ * Tests relay lifecycle, reactive computations, watcher behavior,
+ * and entity update propagation.
+ */
+
+describe('Signalium Reactivity', () => {
+  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 });
+  });
+
+  describe('Relay Lifecycle', () => {
+    it('should start relay in pending state', async () => {
+      mockFetch.get('/item', { data: 'test' }, { delay: 100 });
+
+      await testWithClient(client, async () => {
+        const getItem = query(t => ({
+          path: '/item',
+          response: { data: t.string },
+        }));
+
+        const relay = getItem();
+
+        // Relay should exist and be in pending state
+        expect(relay).toBeDefined();
+        expect(relay.isPending).toBe(true);
+      });
+    });
+
+    it('should transition to resolved state with data', async () => {
+      mockFetch.get('/item', { data: 'test' });
+
+      await testWithClient(client, async () => {
+        const getItem = query(t => ({
+          path: '/item',
+          response: { data: t.string },
+        }));
+
+        const relay = getItem();
+        await relay;
+
+        expect(relay.isResolved).toBe(true);
+        expect(relay.isReady).toBe(true);
+        expect(relay.isPending).toBe(false);
+        expect(relay.value).toEqual({ data: 'test' });
+      });
+    });
+
+    it('should transition to error state on failure', async () => {
+      const error = new Error('Failed to fetch');
+      mockFetch.get('/item', null, { error });
+
+      await testWithClient(client, async () => {
+        const getItem = query(t => ({
+          path: '/item',
+          response: { data: t.string },
+        }));
+
+        const relay = getItem();
+        await expect(relay).rejects.toThrow('Failed to fetch');
+
+        expect(relay.isRejected).toBe(true);
+        expect(relay.error).toBe(error);
+      });
+    });
+  });
+
+  describe('Reactive Computations', () => {
+    it('should support reactive functions depending on query relay', async () => {
+      mockFetch.get('/counter', { count: 5 });
+
+      await testWithClient(client, async () => {
+        const getCounter = query(t => ({
+          path: '/counter',
+          response: { count: t.number },
+        }));
+
+        const relay = getCounter();
+
+        // Create a reactive function that depends on the relay
+        const doubled = reactive(() => {
+          if (relay.isReady) {
+            return relay.value.count * 2;
+          }
+          return 0;
+        });
+
+        await relay;
+
+        // Wait for reactive computation
+        const result = doubled();
+
+        expect(result).toBe(10);
+      });
+    });
+
+    it('should support nested reactive functions', async () => {
+      mockFetch.get('/value', { value: 10 });
+
+      await testWithClient(client, async () => {
+        const getValue = query(t => ({
+          path: '/value',
+          response: { value: t.number },
+        }));
+
+        const relay = getValue();
+
+        const doubled = reactive(() => {
+          if (relay.isReady) {
+            return relay.value.value * 2;
+          }
+          return 0;
+        });
+
+        const tripled = reactive(() => {
+          return doubled() * 1.5;
+        });
+
+        await relay;
+
+        expect(doubled()).toBe(20);
+        expect(tripled()).toBe(30);
+      });
+    });
+
+    it('should support conditional reactivity', async () => {
+      mockFetch.get('/config', { value: 5, shouldDouble: true });
+
+      await testWithClient(client, async () => {
+        const getConfig = query(t => ({
+          path: '/config',
+          response: { value: t.number, shouldDouble: t.boolean },
+        }));
+
+        const relay = getConfig();
+
+        const computed = reactive(() => {
+          if (relay.isReady) {
+            const config = relay.value;
+            return config.shouldDouble ? config.value * 2 : config.value;
+          }
+          return 0;
+        });
+
+        await relay;
+
+        expect(computed()).toBe(10);
+      });
+    });
+  });
+
+  describe('Promise State Tracking', () => {
+    it('should track isPending state', async () => {
+      mockFetch.get('/item', { data: 'test' }, { delay: 50 });
+
+      await testWithClient(client, async () => {
+        const getItem = query(t => ({
+          path: '/item',
+          response: { data: t.string },
+        }));
+
+        const relay = getItem();
+
+        // Initially should be pending
+        expect(relay.isPending).toBe(true);
+
+        await relay;
+
+        // After resolution should not be pending
+        expect(relay.isPending).toBe(false);
+        expect(relay.isSettled).toBe(true);
+      });
+    });
+
+    it('should track isReady state correctly', async () => {
+      mockFetch.get('/item', { data: 'test' });
+
+      await testWithClient(client, async () => {
+        const getItem = query(t => ({
+          path: '/item',
+          response: { data: t.string },
+        }));
+
+        const relay = getItem();
+
+        await relay;
+
+        // After resolution should be ready
+        expect(relay.isReady).toBe(true);
+        expect(relay.value).toEqual({ data: 'test' });
+      });
+    });
+
+    it('should track isResolved state', async () => {
+      mockFetch.get('/item', { success: true });
+
+      await testWithClient(client, async () => {
+        const getItem = query(t => ({
+          path: '/item',
+          response: { success: t.boolean },
+        }));
+
+        const relay = getItem();
+        await relay;
+
+        expect(relay.isResolved).toBe(true);
+        expect(relay.isRejected).toBe(false);
+      });
+    });
+
+    it('should track isRejected state', async () => {
+      mockFetch.get('/item', null, { error: new Error('Failed') });
+
+      await testWithClient(client, async () => {
+        const getItem = query(t => ({
+          path: '/item',
+          response: { success: t.boolean },
+        }));
+
+        const relay = getItem();
+        await expect(relay).rejects.toThrow('Failed');
+
+        expect(relay.isRejected).toBe(true);
+        expect(relay.isResolved).toBe(false);
+      });
+    });
+  });
+
+  describe('Reactive Query Patterns', () => {
+    it('should support query results in reactive computations', async () => {
+      mockFetch.get('/users', {
+        users: [
+          { id: 1, name: 'Alice' },
+          { id: 2, name: 'Bob' },
+        ],
+      });
+
+      await testWithClient(client, async () => {
+        const getUsers = query(t => ({
+          path: '/users',
+          response: {
+            users: t.array(t.object({ id: t.number, name: t.string })),
+          },
+        }));
+
+        const relay = getUsers();
+
+        const userCount = reactive(() => {
+          if (relay.isReady) {
+            return relay.value.users.length;
+          }
+          return 0;
+        });
+
+        const firstUserName = reactive(() => {
+          if (relay.isReady && relay.value.users.length > 0) {
+            return relay.value.users[0].name;
+          }
+          return 'Unknown';
+        });
+
+        await relay;
+
+        expect(userCount()).toBe(2);
+        expect(firstUserName()).toBe('Alice');
+      });
+    });
+
+    it('should handle conditional query access', async () => {
+      mockFetch.get('/config', { enabled: true, data: 'test' });
+
+      await testWithClient(client, async () => {
+        const getConfig = query(t => ({
+          path: '/config',
+          response: { enabled: t.boolean, data: t.string },
+        }));
+
+        const relay = getConfig();
+
+        const result = reactive(() => {
+          if (relay.isReady) {
+            const config = relay.value;
+            // Conditional access - only read data if enabled
+            return config.enabled ? config.data : 'disabled';
+          }
+          return 'loading';
+        });
+
+        expect(result()).toBe('loading');
+
+        await relay;
+
+        expect(result()).toBe('test');
+      });
+    });
+  });
+
+  describe('Concurrent Query Handling', () => {
+    it('should handle concurrent queries without interference', async () => {
+      // Set up mocks for different IDs
+      mockFetch.get('/items/1', { url: '/items/1', timestamp: Date.now() });
+      mockFetch.get('/items/2', { url: '/items/2', timestamp: Date.now() });
+      mockFetch.get('/items/3', { url: '/items/3', timestamp: Date.now() });
+
+      await testWithClient(client, async () => {
+        const getItem = query(t => ({
+          path: '/items/[id]',
+          response: { url: t.string, timestamp: t.number },
+        }));
+
+        // Start multiple concurrent queries
+        const relay1 = getItem({ id: '1' });
+        const relay2 = getItem({ id: '2' });
+        const relay3 = getItem({ id: '3' });
+
+        const [result1, result2, result3] = await Promise.all([relay1, relay2, relay3]);
+
+        expect(result1.url).toContain('/items/1');
+        expect(result2.url).toContain('/items/2');
+        expect(result3.url).toContain('/items/3');
+      });
+    });
+
+    it('should deduplicate concurrent identical requests', async () => {
+      // Set up single mock with delay - should only be called once
+      mockFetch.get('/item', { count: 1 }, { delay: 50 });
+
+      await testWithClient(client, async () => {
+        const getItem = query(t => ({
+          path: '/item',
+          response: { count: t.number },
+        }));
+
+        // Start multiple concurrent identical requests
+        const relay1 = getItem();
+        const relay2 = getItem();
+        const relay3 = getItem();
+
+        // Should be same relay
+        expect(relay1).toBe(relay2);
+        expect(relay2).toBe(relay3);
+
+        const [result1, result2, result3] = await Promise.all([relay1, relay2, relay3]);
+
+        // Should only fetch once
+        expect(mockFetch.calls).toHaveLength(1);
+
+        // All should have same result
+        expect(result1).toEqual(result2);
+        expect(result2).toEqual(result3);
+      });
+    });
+  });
+
+  describe('Error State Reactivity', () => {
+    it('should notify watchers on error', async () => {
+      const error = new Error('Network error');
+      mockFetch.get('/item', null, { error });
+
+      await testWithClient(client, async () => {
+        const getItem = query(t => ({
+          path: '/item',
+          response: { data: t.string },
+        }));
+
+        const relay = getItem();
+        let errorCaught = false;
+
+        const w = watcher(() => {
+          if (relay.isRejected) {
+            errorCaught = true;
+          }
+        });
+
+        const unsub = w.addListener(() => {});
+
+        await expect(relay).rejects.toThrow('Network error');
+        await new Promise(resolve => setTimeout(resolve, 10));
+
+        expect(errorCaught).toBe(true);
+
+        unsub();
+      });
+    });
+
+    it('should expose error object on relay', async () => {
+      const error = new Error('Custom error');
+      mockFetch.get('/item', null, { error });
+
+      await testWithClient(client, async () => {
+        const getItem = query(t => ({
+          path: '/item',
+          response: { data: t.string },
+        }));
+
+        const relay = getItem();
+        await expect(relay).rejects.toThrow('Custom error');
+
+        expect(relay.error).toBe(error);
+      });
+    });
+  });
+});