bunsane 0.2.10 → 0.3.1

package/tests/integration/entity/Entity.saveTimeout.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Integration tests for Entity.save timeout and cancellation behavior.
+ *
+ * Regression coverage for the production incident where Entity.save's wall-
+ * clock timeout rejected the outer Promise but left the underlying Bun SQL
+ * transaction mid-flight. Under pgbouncer transaction-mode pooling this
+ * leaked backend PostgreSQL sessions into `idle in transaction` state,
+ * exhausting the pool.
+ *
+ * These tests prove the invariants the fix must uphold:
+ *   1. An aborted save leaves no partial rows — Bun SQL's transaction callback
+ *      throws, auto-ROLLBACK fires, backend connection is released.
+ *   2. The connection pool stays healthy after repeated aborts — subsequent
+ *      saves on fresh entities still succeed.
+ *   3. A save with no abort still commits normally.
+ *
+ * The wall-clock DB_QUERY_TIMEOUT path is module-cached at import time so it
+ * is not exercised here directly. Manual verification on a real Postgres +
+ * pgbouncer stack (with query_wait_timeout short enough to fire) should
+ * confirm pg_stat_activity shows no `idle in transaction` backends after
+ * this test suite runs. See the handoff doc (2026-04-18) for the repro steps.
+ */
+import { describe, test, expect, beforeAll } from 'bun:test';
+import { Entity } from '../../../core/Entity';
+import db from '../../../database';
+import { TestUser } from '../../fixtures/components';
+import { createTestContext, ensureComponentsRegistered } from '../../utils';
+
+describe('Entity.save timeout and cancellation', () => {
+    const ctx = createTestContext();
+
+    beforeAll(async () => {
+        await ensureComponentsRegistered(TestUser);
+    });
+
+    test('aborted doSave does not leave partial rows (transaction rolls back)', async () => {
+        const entity = ctx.tracker.create();
+        entity.add(TestUser, { name: 'aborted', email: 'a@example.com', age: 1 });
+
+        const controller = new AbortController();
+        // Abort immediately — the first in-flight query will be cancelled,
+        // the transaction callback throws, Bun SQL issues ROLLBACK.
+        queueMicrotask(() => controller.abort(new Error('simulated save timeout')));
+
+        const result = db.transaction(async (trx) => {
+            await entity.doSave(trx, controller.signal);
+        });
+
+        await expect(result).rejects.toBeDefined();
+
+        // Entity must NOT exist — rollback invariant.
+        const rows = await db`SELECT id FROM entities WHERE id = ${entity.id}`;
+        expect(rows.length).toBe(0);
+    });
+
+    test('connection pool stays healthy after multiple aborted saves', async () => {
+        // Repeatedly abort saves — if connections leaked, subsequent saves
+        // would eventually block on pool acquire.
+        for (let i = 0; i < 8; i++) {
+            const entity = Entity.Create();
+            entity.add(TestUser, { name: `aborted-${i}`, email: `a${i}@e.com`, age: i });
+
+            const controller = new AbortController();
+            queueMicrotask(() => controller.abort(new Error('simulated timeout')));
+
+            await db.transaction(async (trx) => {
+                await entity.doSave(trx, controller.signal);
+            }).catch(() => { /* expected */ });
+        }
+
+        // A fresh save must still succeed on the pool that serviced the aborts.
+        const healthy = ctx.tracker.create();
+        healthy.add(TestUser, { name: 'healthy', email: 'h@e.com', age: 99 });
+        await healthy.save();
+
+        expect(healthy._persisted).toBe(true);
+
+        const rows = await db`SELECT id FROM entities WHERE id = ${healthy.id}`;
+        expect(rows.length).toBe(1);
+    });
+
+    test('doSave without signal behaves normally (backwards compatible)', async () => {
+        const entity = ctx.tracker.create();
+        entity.add(TestUser, { name: 'no-signal', email: 'n@e.com', age: 5 });
+
+        await db.transaction(async (trx) => {
+            await entity.doSave(trx); // no signal passed
+        });
+
+        const rows = await db`SELECT id FROM entities WHERE id = ${entity.id}`;
+        expect(rows.length).toBe(1);
+    });
+
+    test('save() resolves even if post-commit cache work is slow (fire-and-forget)', async () => {
+        // Cache handler is queued via queueMicrotask; save() must resolve as
+        // soon as the DB transaction commits. We assert save resolves quickly
+        // even though handleCacheAfterSave is awaited separately.
+        const entity = ctx.tracker.create();
+        entity.add(TestUser, { name: 'fast', email: 'f@e.com', age: 10 });
+
+        const start = performance.now();
+        await entity.save();
+        const elapsed = performance.now() - start;
+
+        expect(entity._persisted).toBe(true);
+        // Generous bound — if cache were blocking save, timings under load
+        // could stretch past the budget. This just guards gross regressions.
+        expect(elapsed).toBeLessThan(5000);
+    });
+});

package/tests/unit/cache/CacheManager.test.ts

@@ -141,6 +141,26 @@ describe('CacheManager', () => {
             expect(result).toBeNull();
         });
 
+        test('invalidateEntities clears entity + all component caches for a batch', async () => {
+            const provider = cacheManager.getProvider();
+            // Two entities, each with cached entity entry + one component
+            await provider.set('entity:e1', 'e1', 3600000);
+            await provider.set('entity:e2', 'e2', 3600000);
+            await provider.set('component:e1:t1', { data: 'a' }, 3600000);
+            await provider.set('component:e2:t1', { data: 'b' }, 3600000);
+
+            await cacheManager.invalidateEntities(['e1', 'e2']);
+
+            expect(await cacheManager.getEntity('e1')).toBeNull();
+            expect(await cacheManager.getEntity('e2')).toBeNull();
+            expect(await cacheManager.getComponentsByEntity('e1', 't1')).toBeNull();
+            expect(await cacheManager.getComponentsByEntity('e2', 't1')).toBeNull();
+        });
+
+        test('invalidateEntities is a noop for empty list', async () => {
+            await expect(cacheManager.invalidateEntities([])).resolves.toBeUndefined();
+        });
+
         test('getEntities returns null for missing entities', async () => {
             const results = await cacheManager.getEntities(['id1', 'id2', 'id3']);
             expect(results.length).toBe(3);

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('   ');
         });
     });
 

package/tests/unit/scheduler/SchedulerManager.timeBased.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Unit tests for SchedulerManager time-based (entity-less) tasks.
+ * Covers BUNSANE-002: @ScheduledTask without query/componentTarget.
+ */
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { SchedulerManager } from '../../../core/SchedulerManager';
+import { ScheduleInterval } from '../../../types/scheduler.types';
+
+describe('SchedulerManager time-based tasks', () => {
+    let scheduler: SchedulerManager;
+
+    beforeEach(() => {
+        scheduler = SchedulerManager.getInstance();
+        scheduler.updateConfig({
+            enabled: true,
+            enableLogging: false,
+            runOnStart: false,
+            distributedLocking: false,
+            maxConcurrentTasks: 5,
+            defaultTimeout: 5000,
+        });
+    });
+
+    afterEach(async () => {
+        await scheduler.stop().catch(() => {});
+    });
+
+    test('registers task with no query / no componentTarget', () => {
+        let called = 0;
+        const service = {
+            tick: async () => {
+                called++;
+            },
+        };
+
+        expect(() =>
+            scheduler.registerTask({
+                id: 'test.timebased.register',
+                name: 'timebased-register',
+                interval: ScheduleInterval.MINUTE,
+                options: {},
+                service,
+                methodName: 'tick',
+                nextExecution: new Date(),
+                executionCount: 0,
+                isRunning: false,
+                enabled: true,
+            })
+        ).not.toThrow();
+    });
+
+    test('executes handler with no entity argument', async () => {
+        const receivedArgsBox: { args: unknown[] | null } = { args: null };
+        const service = {
+            tick: async (...args: unknown[]) => {
+                receivedArgsBox.args = args;
+            },
+        };
+
+        scheduler.registerTask({
+            id: 'test.timebased.exec',
+            name: 'timebased-exec',
+            interval: ScheduleInterval.MINUTE,
+            options: {},
+            service,
+            methodName: 'tick',
+            nextExecution: new Date(),
+            executionCount: 0,
+            isRunning: false,
+            enabled: true,
+        });
+
+        const ok = await scheduler.executeTaskNow('test.timebased.exec');
+        expect(ok).toBe(true);
+        expect(receivedArgsBox.args).toEqual([]);
+    });
+
+    test('rejects task still missing required fields', () => {
+        const service = { tick: async () => {} };
+        expect(() =>
+            scheduler.registerTask({
+                // missing id
+                name: 'bad',
+                interval: ScheduleInterval.MINUTE,
+                options: {},
+                service,
+                methodName: 'tick',
+                nextExecution: new Date(),
+                executionCount: 0,
+                isRunning: false,
+                enabled: true,
+            } as any)
+        ).toThrow(/missing required fields/);
+    });
+});

package/tests/unit/storage/S3StorageProvider.test.ts

@@ -378,11 +378,9 @@ describe("S3StorageProvider", () => {
 
         it("returns false on failure", async () => {
             const client = createMockS3Client({
-                file: mock(() => ({
-                    arrayBuffer: async () => {
-                        throw new Error("Read failed");
-                    },
-                })),
+                stat: mock(async () => {
+                    throw new Error("Stat failed");
+                }),
             });
             const provider = new S3StorageProvider(
                 { bucket: "my-bucket" },
@@ -413,11 +411,9 @@ describe("S3StorageProvider", () => {
 
         it("returns false if copy fails", async () => {
             const client = createMockS3Client({
-                file: mock(() => ({
-                    arrayBuffer: async () => {
-                        throw new Error("Read failed");
-                    },
-                })),
+                stat: mock(async () => {
+                    throw new Error("Stat failed");
+                }),
             });
             const provider = new S3StorageProvider(
                 { bucket: "my-bucket" },

package/upload/FileValidator.ts

@@ -258,31 +258,34 @@ export class FileValidator {
      * Check if file is potentially dangerous
      */
     public async isDangerous(file: File): Promise<boolean> {
-        // Check for executable file extensions
         const dangerousExtensions = [
             '.exe', '.scr', '.bat', '.cmd', '.com', '.pif', '.vbs', '.js', '.jar',
-            '.sh', '.py', '.pl', '.php', '.asp', '.aspx', '.jsp'
+            '.sh', '.py', '.pl', '.php', '.asp', '.aspx', '.jsp',
+            '.svg',
         ];
+        const dangerousMimeTypes = ['image/svg+xml'];
 
         const extension = this.getFileExtension(file.name);
         if (dangerousExtensions.includes(extension)) {
             return true;
         }
+        if (dangerousMimeTypes.includes(file.type)) {
+            return true;
+        }
 
-        // Check for polyglot files (files that are valid in multiple formats)
         try {
             const buffer = await file.slice(0, 1024).arrayBuffer();
             const bytes = new Uint8Array(buffer);
             const content = new TextDecoder().decode(bytes);
-            
-            // Look for script patterns
+
             const scriptPatterns = [
                 /<script/i,
                 /javascript:/i,
                 /vbscript:/i,
                 /<iframe/i,
                 /<object/i,
-                /<embed/i
+                /<embed/i,
+                /on[a-z]+\s*=/i,
             ];
 
             return scriptPatterns.some(pattern => pattern.test(content));