bunsane 0.3.0 → 0.3.2

package/tests/unit/database/cancellable.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Unit tests for `database/cancellable.ts` — the shared `runWithSignal`
+ * helper extracted from Entity.ts so every framework call-site uses the
+ * same abort-on-cancel pattern.
+ */
+import { describe, test, expect } from 'bun:test';
+import { runWithSignal } from '../../../database/cancellable';
+
+function makeFakeQuery<T>(opts: { delayMs?: number; value?: T; rejectWith?: Error }) {
+    let cancelFn: () => void = () => {};
+    const promise: any = new Promise<T>((resolve, reject) => {
+        const handle = setTimeout(() => {
+            if (opts.rejectWith) reject(opts.rejectWith);
+            else resolve(opts.value as T);
+        }, opts.delayMs ?? 1);
+        cancelFn = () => {
+            clearTimeout(handle);
+            promise.cancelled = true;
+            reject(Object.assign(new Error('Query cancelled'), { name: 'AbortError' }));
+        };
+    });
+    // Swallow unhandled rejection when the helper throws on pre-abort before
+    // awaiting `q`. Real Bun SQL Query objects don't surface this as an
+    // unhandled rejection because the runtime captures the cancel reason.
+    promise.catch(() => {});
+    promise.cancel = cancelFn;
+    promise.cancelled = false;
+    return promise;
+}
+
+describe('runWithSignal', () => {
+    test('resolves normally without signal', async () => {
+        const q = makeFakeQuery({ value: [1, 2, 3] });
+        const r = await runWithSignal<number[]>(q);
+        expect(r).toEqual([1, 2, 3]);
+    });
+
+    test('resolves normally when signal never fires', async () => {
+        const controller = new AbortController();
+        const q = makeFakeQuery({ value: 'done' });
+        const r = await runWithSignal<string>(q, controller.signal);
+        expect(r).toBe('done');
+    });
+
+    test('rejects immediately when signal is pre-aborted', async () => {
+        const controller = new AbortController();
+        controller.abort(new Error('pre-aborted'));
+        const q = makeFakeQuery({ delayMs: 5000 });
+        await expect(runWithSignal(q, controller.signal)).rejects.toBeDefined();
+        // Cancelling the underlying query is best-effort; verify cancel ran.
+        expect(q.cancelled).toBe(true);
+    });
+
+    test('cancels query mid-flight when signal aborts', async () => {
+        const controller = new AbortController();
+        const q = makeFakeQuery({ delayMs: 5000 });
+        queueMicrotask(() => controller.abort(new Error('mid-flight')));
+
+        await expect(runWithSignal(q, controller.signal)).rejects.toBeDefined();
+        expect(q.cancelled).toBe(true);
+    });
+
+    test('removes abort listener on success', async () => {
+        const controller = new AbortController();
+        let listenerCount = 0;
+        const origAdd = controller.signal.addEventListener.bind(controller.signal);
+        const origRemove = controller.signal.removeEventListener.bind(controller.signal);
+        controller.signal.addEventListener = ((...args: any[]) => {
+            listenerCount++;
+            return (origAdd as any)(...args);
+        }) as any;
+        controller.signal.removeEventListener = ((...args: any[]) => {
+            listenerCount--;
+            return (origRemove as any)(...args);
+        }) as any;
+
+        const q = makeFakeQuery({ value: 1 });
+        await runWithSignal(q, controller.signal);
+        expect(listenerCount).toBe(0);
+    });
+});

package/tests/unit/database/instrumentedDb.test.ts

@@ -0,0 +1,160 @@
+/**
+ * Unit tests for database/instrumentedDb.ts.
+ *
+ * Uses a fake `db` that returns a `cancel()`able promise-like to exercise
+ * the timing + abort path without a real Postgres backend.
+ */
+import { describe, test, expect, beforeEach } from 'bun:test';
+import {
+    timedUnsafe,
+    incrementDataLoaderCall,
+    getDbStats,
+    resetDbStats,
+    type PerRequestCounters,
+} from '../../../database/instrumentedDb';
+
+interface FakeQuery<T> extends Promise<T> {
+    cancel(): void;
+    cancelled: boolean;
+}
+
+function makeFakeDb(opts: { delayMs?: number; rejectWith?: Error; rows?: any[] } = {}) {
+    return {
+        unsafe(_sql: string, _params: any[]): FakeQuery<any[]> {
+            let cancelFn: () => void = () => {};
+            const promise: any = new Promise<any[]>((resolve, reject) => {
+                const handle = setTimeout(() => {
+                    if (opts.rejectWith) reject(opts.rejectWith);
+                    else resolve(opts.rows ?? []);
+                }, opts.delayMs ?? 1);
+                cancelFn = () => {
+                    clearTimeout(handle);
+                    promise.cancelled = true;
+                    reject(Object.assign(new Error('Query cancelled'), { name: 'AbortError' }));
+                };
+            });
+            // Swallow unhandled rejection on pre-abort cancel path.
+            promise.catch(() => {});
+            promise.cancel = cancelFn;
+            promise.cancelled = false;
+            return promise as FakeQuery<any[]>;
+        },
+    };
+}
+
+describe('timedUnsafe', () => {
+    beforeEach(() => resetDbStats());
+
+    test('records totalCount and totalMs on success', async () => {
+        const db = makeFakeDb({ rows: [{ id: 1 }], delayMs: 5 });
+        const result = await timedUnsafe(db as any, 'SELECT 1', []);
+        expect(result).toEqual([{ id: 1 }]);
+
+        const stats = getDbStats();
+        expect(stats.totalCount).toBe(1);
+        expect(stats.totalMs).toBeGreaterThanOrEqual(1);
+        expect(stats.maxMs).toBeGreaterThanOrEqual(1);
+        expect(stats.abortedCount).toBe(0);
+    });
+
+    test('increments dbQueryCount on perRequest counters', async () => {
+        const db = makeFakeDb();
+        const perReq: PerRequestCounters = { dbQueryCount: 0 };
+        await timedUnsafe(db as any, 'SELECT 1', [], undefined, perReq);
+        await timedUnsafe(db as any, 'SELECT 1', [], undefined, perReq);
+        expect(perReq.dbQueryCount).toBe(2);
+    });
+
+    test('aborted query rejects with AbortError and records abortedCount', async () => {
+        const db = makeFakeDb({ delayMs: 1000 });
+        const controller = new AbortController();
+        const promise = timedUnsafe(db as any, 'SELECT pg_sleep(10)', [], controller.signal);
+
+        queueMicrotask(() => controller.abort(new Error('test abort')));
+
+        await expect(promise).rejects.toBeDefined();
+
+        const stats = getDbStats();
+        expect(stats.totalCount).toBe(1);
+        expect(stats.abortedCount).toBe(1);
+    });
+
+    test('pre-aborted signal cancels before await', async () => {
+        const db = makeFakeDb({ delayMs: 1000 });
+        const controller = new AbortController();
+        controller.abort(new Error('pre-aborted'));
+
+        const promise = timedUnsafe(db as any, 'SELECT 1', [], controller.signal);
+        await expect(promise).rejects.toBeDefined();
+
+        const stats = getDbStats();
+        expect(stats.abortedCount).toBe(1);
+    });
+
+    test('slow query above threshold increments slowCount', async () => {
+        // Slow threshold defaults to 500ms; we cannot reasonably wait that long
+        // in a unit test, so we override via env at module load — fall back to
+        // asserting the slow path is reachable by passing a tiny synthetic
+        // delay larger than zero and checking that the slowCount path triggers
+        // only when over threshold. Direct assertion: with default threshold,
+        // a 5ms query should NOT mark slow.
+        const db = makeFakeDb({ delayMs: 5 });
+        await timedUnsafe(db as any, 'SELECT 1', []);
+        const stats = getDbStats();
+        expect(stats.slowCount).toBe(0);
+    });
+});
+
+describe('incrementDataLoaderCall', () => {
+    beforeEach(() => resetDbStats());
+
+    test('increments per-kind global stats', () => {
+        incrementDataLoaderCall('entity');
+        incrementDataLoaderCall('component');
+        incrementDataLoaderCall('component');
+        incrementDataLoaderCall('relation');
+
+        const stats = getDbStats();
+        expect(stats.dataLoaderCalls.entity).toBe(1);
+        expect(stats.dataLoaderCalls.component).toBe(2);
+        expect(stats.dataLoaderCalls.relation).toBe(1);
+    });
+
+    test('increments perRequest.dataLoaderCalls when supplied', () => {
+        const perReq = {
+            dbQueryCount: 0,
+            dataLoaderCalls: { entity: 0, component: 0, relation: 0 },
+        };
+        incrementDataLoaderCall('entity', perReq);
+        incrementDataLoaderCall('component', perReq);
+        incrementDataLoaderCall('component', perReq);
+        expect(perReq.dataLoaderCalls.entity).toBe(1);
+        expect(perReq.dataLoaderCalls.component).toBe(2);
+        expect(perReq.dataLoaderCalls.relation).toBe(0);
+    });
+});
+
+describe('getDbStats', () => {
+    beforeEach(() => resetDbStats());
+
+    test('reports avgMs as totalMs / totalCount', async () => {
+        const db = makeFakeDb({ delayMs: 4 });
+        await timedUnsafe(db as any, 'SELECT 1', []);
+        await timedUnsafe(db as any, 'SELECT 1', []);
+        const stats = getDbStats();
+        expect(stats.totalCount).toBe(2);
+        // avgMs is rounded to 2 decimals while totalMs is integer-rounded,
+        // so allow ±0.5ms tolerance against the unrounded computation.
+        expect(Math.abs(stats.avgMs - stats.totalMs / 2)).toBeLessThan(1);
+    });
+
+    test('returns zero state after reset', () => {
+        const stats = getDbStats();
+        expect(stats.totalCount).toBe(0);
+        expect(stats.totalMs).toBe(0);
+        expect(stats.maxMs).toBe(0);
+        expect(stats.slowCount).toBe(0);
+        expect(stats.abortedCount).toBe(0);
+        expect(stats.dataLoaderCalls).toEqual({ entity: 0, component: 0, relation: 0 });
+    });
+});

package/tests/unit/entity/Entity.components.test.ts

@@ -187,6 +187,79 @@ describe('Entity Component Management', () => {
 
             expect(data?.createdAt).toBe('2024-01-15T10:30:00.000Z');
         });
+
+        test('serializableData throws descriptive error on invalid Date', () => {
+            const entity = new Entity();
+            entity.add(TestOrder, {
+                orderNumber: 'ORD-002',
+                total: 50,
+                status: 'pending',
+                createdAt: new Date('not-a-date')
+            });
+
+            const component = entity.getInMemory(TestOrder);
+            expect(() => component?.serializableData()).toThrow(
+                /Invalid Date for property 'createdAt' on component 'TestOrder'/
+            );
+        });
+
+        test('serializableData throws on Date type mismatch', () => {
+            const entity = new Entity();
+            entity.add(TestOrder, {
+                orderNumber: 'ORD-003',
+                total: 50,
+                status: 'pending',
+                createdAt: '2024-01-15' as any
+            });
+
+            const component = entity.getInMemory(TestOrder);
+            expect(() => component?.serializableData()).toThrow(
+                /Type mismatch for property 'createdAt' on component 'TestOrder': expected Date, got string/
+            );
+        });
+
+        test('serializableData throws on NaN number', () => {
+            const entity = new Entity();
+            entity.add(TestOrder, {
+                orderNumber: 'ORD-004',
+                total: NaN,
+                status: 'pending',
+                createdAt: new Date()
+            });
+
+            const component = entity.getInMemory(TestOrder);
+            expect(() => component?.serializableData()).toThrow(
+                /Invalid number for property 'total' on component 'TestOrder'/
+            );
+        });
+
+        test('serializableData throws on Infinity number', () => {
+            const entity = new Entity();
+            entity.add(TestOrder, {
+                orderNumber: 'ORD-005',
+                total: Infinity,
+                status: 'pending',
+                createdAt: new Date()
+            });
+
+            const component = entity.getInMemory(TestOrder);
+            expect(() => component?.serializableData()).toThrow(
+                /Invalid number for property 'total' on component 'TestOrder'/
+            );
+        });
+
+        test('serializableData allows null/undefined for nullable Date/Number', () => {
+            const entity = new Entity();
+            entity.add(TestOrder, {
+                orderNumber: 'ORD-006',
+                total: 0,
+                status: 'pending',
+                createdAt: null as any
+            });
+
+            const component = entity.getInMemory(TestOrder);
+            expect(() => component?.serializableData()).not.toThrow();
+        });
     });
 
     describe('component state', () => {

package/tests/unit/entity/Entity.drainSideEffects.test.ts

@@ -0,0 +1,51 @@
+/**
+ * BUNSANE-001 defensive harness: verify Entity.drainPendingSideEffects()
+ * awaits post-commit work scheduled via queueMicrotask from save(), so
+ * tests under PGlite can settle prior-file background work before
+ * asserting against freshly-committed state.
+ */
+import { describe, test, expect, beforeAll } from 'bun:test';
+import { Entity } from '../../../core/Entity';
+import { BaseComponent } from '../../../core/components/BaseComponent';
+import { Component, CompData } from '../../../core/components/Decorators';
+import { ensureComponentsRegistered } from '../../utils';
+
+@Component
+class DrainMarker extends BaseComponent {
+    @CompData()
+    value: string = '';
+}
+
+describe('Entity.drainPendingSideEffects', () => {
+    beforeAll(async () => {
+        await ensureComponentsRegistered(DrainMarker);
+    });
+
+    test('no-op when nothing is pending', async () => {
+        await expect(Entity.drainPendingSideEffects(100)).resolves.toBeUndefined();
+    });
+
+    test('awaits post-commit side effects scheduled by save()', async () => {
+        const saved = Entity.Create();
+        saved.add(DrainMarker, { value: 'pending' });
+        await saved.save();
+
+        // runPostCommitSideEffects is queued as a microtask. drain() must
+        // settle it before returning.
+        await Entity.drainPendingSideEffects(2_000);
+
+        // A second drain is a no-op.
+        await Entity.drainPendingSideEffects(100);
+    });
+
+    test('bounded by timeout, returns even if drain exceeds it', async () => {
+        const saved = Entity.Create();
+        saved.add(DrainMarker, { value: 'bounded' });
+        await saved.save();
+
+        const start = Date.now();
+        await Entity.drainPendingSideEffects(1);
+        const elapsed = Date.now() - start;
+        expect(elapsed).toBeLessThan(500);
+    });
+});

package/tests/unit/entity/Entity.reload.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Unit tests for Entity.reload (BUNSANE-006).
+ * Ensures in-memory component state is discarded and re-hydrated from DB.
+ */
+import { describe, test, expect, beforeAll } from 'bun:test';
+import { Entity } from '../../../core/Entity';
+import { BaseComponent } from '../../../core/components/BaseComponent';
+import { Component, CompData } from '../../../core/components/Decorators';
+import { ensureComponentsRegistered } from '../../utils';
+import db from '../../../database';
+
+@Component
+class ReloadStatus extends BaseComponent {
+    @CompData()
+    value: string = '';
+}
+
+describe('Entity.reload', () => {
+    beforeAll(async () => {
+        await ensureComponentsRegistered(ReloadStatus);
+    });
+
+    test('no-op on entity without a valid id', async () => {
+        const entity = new Entity('');
+        await expect(entity.reload()).resolves.toBe(entity);
+    });
+
+    test('refreshes in-memory data after raw-SQL write', async () => {
+        const saved = Entity.Create();
+        saved.add(ReloadStatus, { value: 'before' });
+        await saved.save();
+
+        const typeId = new ReloadStatus().getTypeID();
+
+        // Write new value via raw SQL — bypasses entity cache invalidation.
+        await db.unsafe(
+            `UPDATE components SET data = data || '{"value":"after"}'::jsonb
+             WHERE entity_id = $1 AND type_id = $2`,
+            [saved.id, typeId]
+        );
+
+        // In-memory copy still holds stale value.
+        expect(saved.getInMemory(ReloadStatus)?.value).toBe('before');
+
+        const returned = await saved.reload();
+        expect(returned).toBe(saved);
+        expect(saved.getInMemory(ReloadStatus)?.value).toBe('after');
+    });
+
+    test('hydrates a bare Entity instance from DB', async () => {
+        const saved = Entity.Create();
+        saved.add(ReloadStatus, { value: 'hydrated' });
+        await saved.save();
+
+        const bare = new Entity(saved.id);
+        expect(bare.componentList().length).toBe(0);
+
+        await bare.reload();
+
+        expect(bare.hasInMemory(ReloadStatus)).toBe(true);
+        expect(bare.getInMemory(ReloadStatus)?.value).toBe('hydrated');
+    });
+});

package/tests/unit/entity/Entity.requireComponents.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Unit tests for Entity.requireComponents (BUNSANE-003).
+ * Ensures ComponentTargetHook includeComponents matching sees tag
+ * components that weren't eagerly loaded.
+ */
+import { describe, test, expect, beforeAll } from 'bun:test';
+import { Entity } from '../../../core/Entity';
+import { BaseComponent } from '../../../core/components/BaseComponent';
+import { Component, CompData } from '../../../core/components/Decorators';
+import { TestUser } from '../../fixtures/components';
+import { ensureComponentsRegistered } from '../../utils';
+
+@Component
+class ReqTag extends BaseComponent {}
+
+@Component
+class ReqData extends BaseComponent {
+    @CompData()
+    value: string = '';
+}
+
+describe('Entity.requireComponents', () => {
+    beforeAll(async () => {
+        await ensureComponentsRegistered(TestUser, ReqTag, ReqData);
+    });
+
+    test('no-op for empty list', async () => {
+        const entity = Entity.Create();
+        await expect(entity.requireComponents([])).resolves.toBeUndefined();
+        expect(entity.componentList().length).toBe(0);
+    });
+
+    test('does nothing when components already in memory', async () => {
+        const entity = Entity.Create();
+        entity.add(ReqTag);
+        const before = entity.componentList().length;
+        await entity.requireComponents([ReqTag]);
+        expect(entity.componentList().length).toBe(before);
+    });
+
+    test('hydrates missing components from DB after save', async () => {
+        const saved = Entity.Create();
+        saved.add(ReqTag);
+        saved.add(ReqData, { value: 'hello' });
+        await saved.save();
+
+        const loaded = new Entity(saved.id);
+        expect(loaded.componentList().length).toBe(0);
+
+        await loaded.requireComponents([ReqTag, ReqData]);
+
+        expect(loaded.hasInMemory(ReqTag)).toBe(true);
+        expect(loaded.hasInMemory(ReqData)).toBe(true);
+        expect(loaded.getInMemory(ReqData)?.value).toBe('hello');
+    });
+
+    test('only fetches missing components, not already-loaded ones', async () => {
+        const saved = Entity.Create();
+        saved.add(ReqTag);
+        saved.add(ReqData, { value: 'mix' });
+        await saved.save();
+
+        const loaded = new Entity(saved.id);
+        await loaded.requireComponents([ReqData]);
+        expect(loaded.hasInMemory(ReqData)).toBe(true);
+        expect(loaded.hasInMemory(ReqTag)).toBe(false);
+
+        await loaded.requireComponents([ReqTag, ReqData]);
+        expect(loaded.hasInMemory(ReqTag)).toBe(true);
+        expect(loaded.getInMemory(ReqData)?.value).toBe('mix');
+    });
+});

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

@@ -0,0 +1,69 @@
+/**
+ * Empty-string filter support. JSONB text extraction (c.data->>'field')
+ * returns text, so `= ''` / `!= ''` / LIKE against empty string are
+ * legitimate. UUID-cast path is gated on a regex that empty cannot match.
+ */
+import { describe, test, expect, beforeAll } from 'bun:test';
+import { Entity } from '../../../core/Entity';
+import { BaseComponent } from '../../../core/components/BaseComponent';
+import { Component, CompData } from '../../../core/components/Decorators';
+import { Query, FilterOp } from '../../../query/Query';
+import { ensureComponentsRegistered } from '../../utils';
+
+@Component
+class EmptyableNote extends BaseComponent {
+    @CompData()
+    value: string = '';
+}
+
+describe('Query empty-string filter', () => {
+    beforeAll(async () => {
+        await ensureComponentsRegistered(EmptyableNote);
+    });
+
+    test('Query.filter accepts empty-string value without throwing', () => {
+        expect(() => Query.filter('value', FilterOp.EQ, '')).not.toThrow();
+        const f = Query.filter('value', FilterOp.EQ, '');
+        expect(f.value).toBe('');
+    });
+
+    test('Query.filter accepts whitespace-only value without throwing', () => {
+        expect(() => Query.filter('value', FilterOp.EQ, '   ')).not.toThrow();
+    });
+
+    test('.with(C, filter EQ "") executes and returns matching rows', async () => {
+        const withEmpty = Entity.Create();
+        withEmpty.add(EmptyableNote, { value: '' });
+        await withEmpty.save();
+
+        const withData = Entity.Create();
+        withData.add(EmptyableNote, { value: 'not empty' });
+        await withData.save();
+
+        const rows = await new Query()
+            .with(EmptyableNote, Query.filters(Query.filter('value', FilterOp.EQ, '')))
+            .exec();
+
+        const ids = rows.map(e => e.id);
+        expect(ids).toContain(withEmpty.id);
+        expect(ids).not.toContain(withData.id);
+    });
+
+    test('.with(C, filter != "") excludes rows with empty value', async () => {
+        const withEmpty = Entity.Create();
+        withEmpty.add(EmptyableNote, { value: '' });
+        await withEmpty.save();
+
+        const withData = Entity.Create();
+        withData.add(EmptyableNote, { value: 'populated' });
+        await withData.save();
+
+        const rows = await new Query()
+            .with(EmptyableNote, Query.filters(Query.filter('value', FilterOp.NEQ, '')))
+            .exec();
+
+        const ids = rows.map(e => e.id);
+        expect(ids).toContain(withData.id);
+        expect(ids).not.toContain(withEmpty.id);
+    });
+});

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

@@ -192,12 +192,14 @@ describe('Query', () => {
             expect(filter.value).toBe('John');
         });
 
-        test('throws for empty string value', () => {
-            expect(() => Query.filter('name', FilterOp.EQ, '')).toThrow();
+        test('accepts empty string value', () => {
+            const filter = Query.filter('name', FilterOp.EQ, '');
+            expect(filter.value).toBe('');
         });
 
-        test('throws for whitespace value', () => {
-            expect(() => Query.filter('name', FilterOp.EQ, '   ')).toThrow();
+        test('accepts whitespace value', () => {
+            const filter = Query.filter('name', FilterOp.EQ, '   ');
+            expect(filter.value).toBe('   ');
         });
     });