bunsane 0.1.4 → 0.2.0

package/tests/unit/query/FilterBuilder.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Unit tests for FilterBuilder utility functions
+ */
+import { describe, test, expect } from 'bun:test';
+import { buildJSONPath, composeFilters, type FilterBuilder, type FilterResult } from '../../../query/FilterBuilder';
+
+describe('FilterBuilder', () => {
+    describe('buildJSONPath()', () => {
+        test('builds simple field path', () => {
+            const result = buildJSONPath('name', 'c');
+            expect(result).toBe("c.data->>'name'");
+        });
+
+        test('builds nested field path', () => {
+            const result = buildJSONPath('location.latitude', 'c');
+            expect(result).toBe("c.data->'location'->>'latitude'");
+        });
+
+        test('builds deeply nested path', () => {
+            const result = buildJSONPath('device.location.coordinates.latitude', 'c');
+            expect(result).toBe("c.data->'device'->'location'->'coordinates'->>'latitude'");
+        });
+
+        test('uses provided alias', () => {
+            const result = buildJSONPath('field', 'comp');
+            expect(result).toBe("comp.data->>'field'");
+        });
+    });
+
+    describe('composeFilters()', () => {
+        test('throws for empty array', () => {
+            expect(() => composeFilters([])).toThrow('Cannot compose empty array of filter builders');
+        });
+
+        test('composes single builder', () => {
+            const mockBuilder: FilterBuilder = () => ({
+                sql: 'field = $1',
+                addedParams: 1
+            });
+
+            const composed = composeFilters([mockBuilder]);
+            const result = composed(
+                { field: 'test', operator: 'EQ', value: 'value' },
+                'c',
+                {} as any
+            );
+
+            expect(result.sql).toBe('(field = $1)');
+            expect(result.addedParams).toBe(1);
+        });
+
+        test('composes multiple builders with AND', () => {
+            const builder1: FilterBuilder = () => ({
+                sql: 'field1 = $1',
+                addedParams: 1
+            });
+            const builder2: FilterBuilder = () => ({
+                sql: 'field2 > $2',
+                addedParams: 1
+            });
+
+            const composed = composeFilters([builder1, builder2]);
+            const result = composed(
+                { field: 'test', operator: 'EQ', value: 'value' },
+                'c',
+                {} as any
+            );
+
+            expect(result.sql).toBe('(field1 = $1) AND (field2 > $2)');
+            expect(result.addedParams).toBe(2);
+        });
+
+        test('handles empty SQL from builder', () => {
+            const builder1: FilterBuilder = () => ({
+                sql: 'field1 = $1',
+                addedParams: 1
+            });
+            const builder2: FilterBuilder = () => ({
+                sql: '',
+                addedParams: 0
+            });
+
+            const composed = composeFilters([builder1, builder2]);
+            const result = composed(
+                { field: 'test', operator: 'EQ', value: 'value' },
+                'c',
+                {} as any
+            );
+
+            expect(result.sql).toBe('(field1 = $1)');
+            expect(result.addedParams).toBe(1);
+        });
+
+        test('handles whitespace-only SQL', () => {
+            const builder: FilterBuilder = () => ({
+                sql: '   ',
+                addedParams: 0
+            });
+
+            const composed = composeFilters([builder]);
+            const result = composed(
+                { field: 'test', operator: 'EQ', value: 'value' },
+                'c',
+                {} as any
+            );
+
+            expect(result.sql).toBe('');
+            expect(result.addedParams).toBe(0);
+        });
+    });
+});

package/tests/unit/query/Query.test.ts

@@ -0,0 +1,308 @@
+/**
+ * Unit tests for Query class
+ * Tests query builder methods and structure
+ */
+import { describe, test, expect, beforeAll } from 'bun:test';
+import { Query, FilterOp } from '../../../query/Query';
+import { TestUser, TestProduct } from '../../fixtures/components';
+import { ensureComponentsRegistered } from '../../utils';
+
+describe('Query', () => {
+    beforeAll(async () => {
+        await ensureComponentsRegistered(TestUser, TestProduct);
+    });
+
+    describe('constructor', () => {
+        test('creates a new query instance', () => {
+            const query = new Query();
+            expect(query).toBeDefined();
+        });
+
+        test('creates query with transaction', () => {
+            // Query accepts optional transaction parameter
+            const query = new Query();
+            expect(query).toBeDefined();
+        });
+    });
+
+    describe('findById()', () => {
+        test('sets up query to find by ID', () => {
+            const query = new Query();
+            const result = query.findById('test-id-123');
+            expect(result).toBe(query); // Returns this for chaining
+        });
+
+        test('throws for empty string id', () => {
+            const query = new Query();
+            expect(() => query.findById('')).toThrow();
+        });
+
+        test('throws for whitespace id', () => {
+            const query = new Query();
+            expect(() => query.findById('   ')).toThrow();
+        });
+    });
+
+    describe('with()', () => {
+        test('adds component requirement to query', () => {
+            const query = new Query();
+            const result = query.with(TestUser);
+            // with() returns same instance for chaining (type changes for type accumulation)
+            expect(result as any).toBe(query as any);
+        });
+
+        test('allows chaining multiple with() calls', () => {
+            const query = new Query();
+            const result = query.with(TestUser).with(TestProduct);
+            expect(result as any).toBe(query as any);
+        });
+
+        test('accepts component with filters', () => {
+            const query = new Query();
+            const result = query.with(TestUser, {
+                filters: [{ field: 'name', operator: FilterOp.EQ, value: 'John' }]
+            });
+            expect(result as any).toBe(query as any);
+        });
+
+        test('accepts array of components with filters', () => {
+            const query = new Query();
+            const result = query.with([
+                { component: TestUser, filters: [{ field: 'age', operator: FilterOp.GT, value: 18 }] },
+                { component: TestProduct, filters: [{ field: 'price', operator: FilterOp.LT, value: 100 }] }
+            ]);
+            expect(result).toBe(query);
+        });
+    });
+
+    describe('without()', () => {
+        test('excludes entities with specified component', () => {
+            const query = new Query();
+            const result = query.with(TestUser).without(TestProduct);
+            expect(result as any).toBe(query as any);
+        });
+    });
+
+    describe('excludeEntityId()', () => {
+        test('excludes specific entity from results', () => {
+            const query = new Query();
+            const result = query.excludeEntityId('entity-to-exclude');
+            expect(result).toBe(query);
+        });
+    });
+
+    describe('populate()', () => {
+        test('enables component population', () => {
+            const query = new Query();
+            const result = query.with(TestUser).populate();
+            expect(result as any).toBe(query as any);
+        });
+    });
+
+    describe('eagerLoadComponents()', () => {
+        test('sets up eager loading for components', () => {
+            const query = new Query();
+            const result = query.with(TestUser).eagerLoadComponents([TestUser, TestProduct]);
+            expect(result as any).toBe(query as any);
+        });
+    });
+
+    describe('eagerLoad()', () => {
+        test('is an alias for eagerLoadComponents', () => {
+            const query = new Query();
+            const result = query.with(TestUser).eagerLoad([TestUser]);
+            expect(result as any).toBe(query as any);
+        });
+    });
+
+    describe('take()', () => {
+        test('sets limit on query results', () => {
+            const query = new Query();
+            const result = query.with(TestUser).take(10);
+            expect(result as any).toBe(query as any);
+        });
+    });
+
+    describe('offset()', () => {
+        test('sets offset for pagination', () => {
+            const query = new Query();
+            const result = query.with(TestUser).offset(20);
+            expect(result as any).toBe(query as any);
+        });
+    });
+
+    describe('sortBy()', () => {
+        test('sets sort order', () => {
+            const query = new Query();
+            const result = query.with(TestUser).sortBy(TestUser, 'name', 'ASC');
+            expect(result as any).toBe(query as any);
+        });
+
+        test('accepts DESC direction', () => {
+            const query = new Query();
+            const result = query.with(TestUser).sortBy(TestUser, 'age', 'DESC');
+            expect(result as any).toBe(query as any);
+        });
+
+        test('accepts nullsFirst option', () => {
+            const query = new Query();
+            const result = query.with(TestUser).sortBy(TestUser, 'bio', 'ASC', true);
+            expect(result as any).toBe(query as any);
+        });
+
+        test('throws if component not in query', () => {
+            const query = new Query();
+            expect(() => query.sortBy(TestUser, 'name')).toThrow();
+        });
+    });
+
+    describe('debugMode()', () => {
+        test('enables debug mode', () => {
+            const query = new Query();
+            const result = query.debugMode(true);
+            expect(result).toBe(query);
+        });
+
+        test('can disable debug mode', () => {
+            const query = new Query();
+            const result = query.debugMode(false);
+            expect(result).toBe(query);
+        });
+    });
+
+    describe('noCache()', () => {
+        test('bypasses prepared statement cache by default', () => {
+            const query = new Query();
+            const result = query.noCache();
+            expect(result).toBe(query);
+        });
+
+        test('accepts cache options', () => {
+            const query = new Query();
+            const result = query.noCache({ preparedStatement: true, component: true });
+            expect(result).toBe(query);
+        });
+    });
+
+    describe('filter()', () => {
+        test('creates filter object', () => {
+            const filter = Query.filter('name', FilterOp.EQ, 'John');
+            expect(filter.field).toBe('name');
+            expect(filter.operator).toBe(FilterOp.EQ);
+            expect(filter.value).toBe('John');
+        });
+
+        test('throws for empty string value', () => {
+            expect(() => Query.filter('name', FilterOp.EQ, '')).toThrow();
+        });
+
+        test('throws for whitespace value', () => {
+            expect(() => Query.filter('name', FilterOp.EQ, '   ')).toThrow();
+        });
+    });
+
+    describe('typedFilter()', () => {
+        test('creates typed filter object', () => {
+            const filter = Query.typedFilter(TestUser, 'name', FilterOp.EQ, 'John');
+            expect(filter.field).toBe('name');
+            expect(filter.operator).toBe(FilterOp.EQ);
+            expect(filter.value).toBe('John');
+        });
+    });
+
+    describe('filters()', () => {
+        test('creates filter options from multiple filters', () => {
+            const filter1 = Query.filter('name', FilterOp.EQ, 'John');
+            const filter2 = Query.filter('age', FilterOp.GT, 18);
+            const options = Query.filters(filter1, filter2);
+
+            expect(options.filters).toBeDefined();
+            expect(options.filters?.length).toBe(2);
+        });
+    });
+
+    describe('FilterOp', () => {
+        test('has all expected operators', () => {
+            expect(FilterOp.EQ).toBeDefined();
+            expect(FilterOp.NEQ).toBeDefined();
+            expect(FilterOp.GT).toBeDefined();
+            expect(FilterOp.GTE).toBeDefined();
+            expect(FilterOp.LT).toBeDefined();
+            expect(FilterOp.LTE).toBeDefined();
+            expect(FilterOp.LIKE).toBeDefined();
+            expect(FilterOp.IN).toBeDefined();
+            expect(FilterOp.NOT_IN).toBeDefined();
+        });
+    });
+
+    describe('chaining', () => {
+        test('supports full query chain', () => {
+            const query = new Query()
+                .with(TestUser, { filters: [Query.filter('age', FilterOp.GTE, 18)] })
+                .with(TestProduct)
+                .without(TestProduct)
+                .take(10)
+                .offset(0)
+                .sortBy(TestUser, 'name')
+                .populate()
+                .debugMode(false)
+                .noCache();
+
+            expect(query).toBeDefined();
+        });
+    });
+
+    describe('sum()', () => {
+        test('throws if component not in query', async () => {
+            const query = new Query();
+            // TestProduct not added via .with()
+            await expect(query.sum(TestProduct, 'price')).rejects.toThrow(
+                /not included in the query/
+            );
+        });
+
+        test('throws if component is not registered', async () => {
+            class UnregisteredComponent {
+                value!: number;
+            }
+            const query = new Query();
+            // @ts-expect-error - Testing with unregistered component
+            await expect(query.sum(UnregisteredComponent, 'value')).rejects.toThrow(
+                /not registered/
+            );
+        });
+
+        test('returns a Promise', () => {
+            const query = new Query().with(TestProduct);
+            const result = query.sum(TestProduct, 'price');
+            expect(result).toBeInstanceOf(Promise);
+        });
+    });
+
+    describe('average()', () => {
+        test('throws if component not in query', async () => {
+            const query = new Query();
+            // TestProduct not added via .with()
+            await expect(query.average(TestProduct, 'price')).rejects.toThrow(
+                /not included in the query/
+            );
+        });
+
+        test('throws if component is not registered', async () => {
+            class UnregisteredComponent {
+                value!: number;
+            }
+            const query = new Query();
+            // @ts-expect-error - Testing with unregistered component
+            await expect(query.average(UnregisteredComponent, 'value')).rejects.toThrow(
+                /not registered/
+            );
+        });
+
+        test('returns a Promise', () => {
+            const query = new Query().with(TestProduct);
+            const result = query.average(TestProduct, 'price');
+            expect(result).toBeInstanceOf(Promise);
+        });
+    });
+});

package/tests/unit/scheduler/DistributedLock.test.ts

@@ -0,0 +1,274 @@
+/**
+ * Unit tests for DistributedLock
+ * Tests PostgreSQL advisory lock-based distributed locking functionality
+ *
+ * Note: These tests require a PostgreSQL database connection
+ */
+import { describe, test, expect, beforeEach, afterEach, beforeAll, afterAll } from 'bun:test';
+import { DistributedLock, resetDistributedLock, DEFAULT_LOCK_CONFIG } from '../../../core/scheduler/DistributedLock';
+
+describe('DistributedLock', () => {
+    let lock: DistributedLock;
+
+    beforeEach(() => {
+        // Reset singleton before each test
+        resetDistributedLock();
+        lock = new DistributedLock({
+            enabled: true,
+            enableLogging: false,
+            lockTimeout: 0,
+            retryInterval: 50,
+        });
+    });
+
+    afterEach(async () => {
+        // Release all locks and reset
+        await lock.releaseAll();
+        resetDistributedLock();
+    });
+
+    describe('constructor', () => {
+        test('creates lock with default config', () => {
+            const defaultLock = new DistributedLock();
+            expect(defaultLock).toBeDefined();
+            expect(defaultLock.getConfig().enabled).toBe(DEFAULT_LOCK_CONFIG.enabled);
+            expect(defaultLock.getConfig().lockKeyPrefix).toBe(DEFAULT_LOCK_CONFIG.lockKeyPrefix);
+        });
+
+        test('creates lock with custom config', () => {
+            const customLock = new DistributedLock({
+                enabled: false,
+                lockKeyPrefix: 0x12345678,
+                lockTimeout: 5000,
+            });
+            const config = customLock.getConfig();
+            expect(config.enabled).toBe(false);
+            expect(config.lockKeyPrefix).toBe(0x12345678);
+            expect(config.lockTimeout).toBe(5000);
+        });
+    });
+
+    describe('tryAcquire()', () => {
+        test('acquires lock for new task', async () => {
+            const result = await lock.tryAcquire('test-task-1');
+
+            expect(result.acquired).toBe(true);
+            expect(result.taskId).toBe('test-task-1');
+            expect(result.lockKey).toBeDefined();
+            expect(typeof result.lockKey).toBe('bigint');
+        });
+
+        test('generates consistent lock keys for same task', async () => {
+            const lock2 = new DistributedLock({ enabled: true, enableLogging: false });
+
+            const result1 = await lock.tryAcquire('consistent-task');
+            await lock.release('consistent-task');
+
+            const result2 = await lock2.tryAcquire('consistent-task');
+            await lock2.release('consistent-task');
+
+            expect(result1.lockKey).toBe(result2.lockKey);
+        });
+
+        test('generates different lock keys for different tasks', async () => {
+            const result1 = await lock.tryAcquire('task-a');
+            const result2 = await lock.tryAcquire('task-b');
+
+            expect(result1.lockKey).not.toBe(result2.lockKey);
+
+            await lock.release('task-a');
+            await lock.release('task-b');
+        });
+
+        test('fails to acquire already held lock', async () => {
+            // First instance acquires lock
+            const result1 = await lock.tryAcquire('exclusive-task');
+            expect(result1.acquired).toBe(true);
+
+            // Second instance tries to acquire same lock (simulated with same connection)
+            // Note: In real scenario, this would be a different database session
+            // For unit test, we verify the lock is tracked as held
+            expect(lock.isHeld('exclusive-task')).toBe(true);
+        });
+
+        test('returns true immediately when locking disabled', async () => {
+            const disabledLock = new DistributedLock({ enabled: false });
+
+            const result = await lock.tryAcquire('disabled-test');
+
+            // When disabled, lock is always "acquired" with key 0
+            const disabledResult = await disabledLock.tryAcquire('disabled-test');
+            expect(disabledResult.acquired).toBe(true);
+            expect(disabledResult.lockKey).toBe(0n);
+        });
+
+        test('tracks held locks locally', async () => {
+            expect(lock.getHeldLockCount()).toBe(0);
+
+            await lock.tryAcquire('tracked-task-1');
+            expect(lock.getHeldLockCount()).toBe(1);
+            expect(lock.isHeld('tracked-task-1')).toBe(true);
+
+            await lock.tryAcquire('tracked-task-2');
+            expect(lock.getHeldLockCount()).toBe(2);
+            expect(lock.isHeld('tracked-task-2')).toBe(true);
+        });
+    });
+
+    describe('release()', () => {
+        test('releases held lock', async () => {
+            await lock.tryAcquire('release-test');
+            expect(lock.isHeld('release-test')).toBe(true);
+
+            const released = await lock.release('release-test');
+
+            expect(released).toBe(true);
+            expect(lock.isHeld('release-test')).toBe(false);
+            expect(lock.getHeldLockCount()).toBe(0);
+        });
+
+        test('returns false for non-held lock', async () => {
+            const released = await lock.release('never-acquired');
+
+            // PostgreSQL returns false if lock wasn't held
+            expect(released).toBe(false);
+        });
+
+        test('does nothing when disabled', async () => {
+            const disabledLock = new DistributedLock({ enabled: false });
+
+            const released = await disabledLock.release('any-task');
+
+            expect(released).toBe(true);
+        });
+    });
+
+    describe('releaseAll()', () => {
+        test('releases all held locks', async () => {
+            await lock.tryAcquire('multi-1');
+            await lock.tryAcquire('multi-2');
+            await lock.tryAcquire('multi-3');
+
+            expect(lock.getHeldLockCount()).toBe(3);
+
+            await lock.releaseAll();
+
+            expect(lock.getHeldLockCount()).toBe(0);
+            expect(lock.isHeld('multi-1')).toBe(false);
+            expect(lock.isHeld('multi-2')).toBe(false);
+            expect(lock.isHeld('multi-3')).toBe(false);
+        });
+
+        test('handles empty lock set gracefully', async () => {
+            expect(lock.getHeldLockCount()).toBe(0);
+
+            // Should not throw
+            await lock.releaseAll();
+
+            expect(lock.getHeldLockCount()).toBe(0);
+        });
+    });
+
+    describe('updateConfig()', () => {
+        test('updates configuration', () => {
+            const originalConfig = lock.getConfig();
+
+            lock.updateConfig({
+                enabled: false,
+                lockTimeout: 10000,
+            });
+
+            const newConfig = lock.getConfig();
+            expect(newConfig.enabled).toBe(false);
+            expect(newConfig.lockTimeout).toBe(10000);
+            // Other values should remain
+            expect(newConfig.lockKeyPrefix).toBe(originalConfig.lockKeyPrefix);
+        });
+    });
+
+    describe('isHeld()', () => {
+        test('returns false for never acquired task', () => {
+            expect(lock.isHeld('unknown-task')).toBe(false);
+        });
+
+        test('returns true for acquired task', async () => {
+            await lock.tryAcquire('held-task');
+            expect(lock.isHeld('held-task')).toBe(true);
+        });
+
+        test('returns false after release', async () => {
+            await lock.tryAcquire('was-held-task');
+            expect(lock.isHeld('was-held-task')).toBe(true);
+
+            await lock.release('was-held-task');
+            expect(lock.isHeld('was-held-task')).toBe(false);
+        });
+    });
+
+    describe('lock key generation', () => {
+        test('generates positive bigint keys', async () => {
+            const tasks = ['task-1', 'task-2', 'TaskWithCaps', 'task.with.dots', 'task-with-dashes'];
+
+            for (const task of tasks) {
+                const result = await lock.tryAcquire(task);
+                expect(result.lockKey).toBeGreaterThan(0n);
+                await lock.release(task);
+            }
+        });
+
+        test('handles empty string task id', async () => {
+            const result = await lock.tryAcquire('');
+            expect(result.lockKey).toBeDefined();
+            await lock.release('');
+        });
+
+        test('handles unicode task ids', async () => {
+            const result = await lock.tryAcquire('task-日本語');
+            expect(result.acquired).toBe(true);
+            expect(result.lockKey).toBeGreaterThan(0n);
+            await lock.release('task-日本語');
+        });
+
+        test('handles very long task ids', async () => {
+            const longId = 'a'.repeat(1000);
+            const result = await lock.tryAcquire(longId);
+            expect(result.acquired).toBe(true);
+            expect(result.lockKey).toBeGreaterThan(0n);
+            await lock.release(longId);
+        });
+    });
+});
+
+describe('DistributedLock with timeout', () => {
+    let lock: DistributedLock;
+
+    beforeEach(() => {
+        resetDistributedLock();
+        lock = new DistributedLock({
+            enabled: true,
+            enableLogging: false,
+            lockTimeout: 200, // 200ms timeout
+            retryInterval: 50,
+        });
+    });
+
+    afterEach(async () => {
+        await lock.releaseAll();
+        resetDistributedLock();
+    });
+
+    test('retries until timeout when lock not available', async () => {
+        // This test verifies the retry mechanism is called
+        // In a real multi-instance scenario, we'd test across database sessions
+
+        const startTime = Date.now();
+
+        // First acquire the lock
+        const result1 = await lock.tryAcquire('timeout-task');
+        expect(result1.acquired).toBe(true);
+
+        const elapsed = Date.now() - startTime;
+        // Should return quickly when lock is available
+        expect(elapsed).toBeLessThan(100);
+    });
+});