@carno.js/live 1.8.0

package/test/acceptance.test.ts

@@ -0,0 +1,306 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { BaseEntity, Entity, PrimaryKey, Property, statementObserver } from '../../orm/dist/index.js';
+import { withDatabase } from '../../orm/dist/testing/with-database.js';
+import { Controller, Get, Query } from '@carno.js/core';
+import { createTestHarness } from '../../core/dist/testing/TestHarness.js';
+import { Live } from '../src/decorators/Live';
+import { LivePlugin } from '../src/LivePlugin';
+import { resetLiveRuntime } from '../src/runtime';
+import type { ServerMessage } from '../src/shared/protocol';
+
+const TABLE_STATEMENTS = [
+    'CREATE TABLE live_tasks (id SERIAL PRIMARY KEY, title TEXT NOT NULL, tenant TEXT NOT NULL, touched_at TIMESTAMP NULL);'
+];
+
+@Entity({ tableName: 'live_tasks' })
+class Task extends BaseEntity<Task> {
+    @PrimaryKey()
+    id!: number;
+
+    @Property()
+    title!: string;
+
+    @Property()
+    tenant!: string;
+
+    @Property({ nullable: true })
+    touchedAt?: Date;
+}
+
+@Controller('/tasks')
+class TasksController {
+    @Get('/')
+    @Live({ key: 'id', shared: 'public' })
+    async list(@Query('tenant') tenant: string) {
+        const tasks = await Task.find({ tenant }, { fields: ['id', 'title'] as any });
+        return tasks.map(task => ({ id: task.id, title: task.title }));
+    }
+}
+
+/** Minimal protocol client over a real WebSocket. */
+class ProbeClient {
+    private readonly socket: WebSocket;
+    readonly received: ServerMessage[] = [];
+
+    private constructor(socket: WebSocket) {
+        this.socket = socket;
+        socket.onmessage = event => this.received.push(JSON.parse(String(event.data)));
+    }
+
+    static connect(port: number): Promise<ProbeClient> {
+        return new Promise((resolve, reject) => {
+            const socket = new WebSocket(`ws://127.0.0.1:${port}/live`);
+            socket.onopen = () => resolve(new ProbeClient(socket));
+            socket.onerror = reject;
+        });
+    }
+
+    send(message: unknown): void {
+        this.socket.send(JSON.stringify(message));
+    }
+
+    close(): void {
+        this.socket.close();
+    }
+
+    /** Wait for a message matching `predicate`, or fail after `timeoutMs`. */
+    async wait(predicate: (message: ServerMessage) => boolean, timeoutMs = 2000): Promise<ServerMessage> {
+        const deadline = Date.now() + timeoutMs;
+
+        while (Date.now() < deadline) {
+            const found = this.received.find(predicate);
+
+            if (found) {
+                return found;
+            }
+
+            await new Promise(resolve => setTimeout(resolve, 10));
+        }
+
+        throw new Error(`Timed out. Received: ${JSON.stringify(this.received)}`);
+    }
+}
+
+afterEach(() => {
+    statementObserver.reset();
+    resetLiveRuntime();
+});
+
+describe('Live Resources acceptance', () => {
+    test('an ORM write reaches a subscriber with no broadcast code (criteria 1, 4, 5)', async () => {
+        await withDatabase(TABLE_STATEMENTS, async () => {
+            const harness = await createTestHarness({
+                plugins: [LivePlugin.create({ controllers: [TasksController], config: { coalesceMs: 5 } })],
+                listen: true
+            });
+
+            try {
+                await Task.create({ title: 'first', tenant: 'acme' });
+
+                const probe = await ProbeClient.connect(harness.port!);
+                probe.send({ t: 'sub', sid: 'a', resource: 'TasksController.list', inputs: { params: {}, query: { tenant: 'acme' } } });
+
+                const snapshot = await probe.wait(message => message.t === 'snapshot');
+                expect((snapshot as any).data).toEqual([{ id: expect.any(Number), title: 'first' }]);
+
+                // Criterion 1: nothing below mentions the socket.
+                await Task.create({ title: 'second', tenant: 'acme' });
+
+                const patch = await probe.wait(message => message.t === 'patch');
+
+                // Criterion 4, by proxy: a keyed upsert, not a whole-array set.
+                expect((patch as any).ops.every((op: any) => op.op === 'upsert' || op.op === 'order')).toBe(true);
+
+                // Criterion 5: a write to a column the resource never selected.
+                const before = probe.received.length;
+                const [task] = await Task.find({ title: 'first' });
+                await Task.update({ id: task.id }, { touchedAt: new Date() });
+                await new Promise(resolve => setTimeout(resolve, 200));
+
+                expect(probe.received.length).toBe(before);
+
+                probe.close();
+            } finally {
+                await harness.close();
+            }
+        });
+    });
+
+    test('does not publish an uncommitted write that is later rolled back', async () => {
+        await withDatabase(TABLE_STATEMENTS, async context => {
+            const harness = await createTestHarness({
+                plugins: [LivePlugin.create({ controllers: [TasksController], config: { coalesceMs: 5 } })],
+                listen: true
+            });
+
+            let probe: ProbeClient | undefined;
+
+            try {
+                const task = await Task.create({ title: 'before transaction', tenant: 'acme' });
+                probe = await ProbeClient.connect(harness.port!);
+                probe.send({
+                    t: 'sub',
+                    sid: 'a',
+                    resource: 'TasksController.list',
+                    inputs: { params: {}, query: { tenant: 'acme' } }
+                });
+                await probe.wait(message => message.t === 'snapshot');
+
+                let failureMessage = '';
+                let patchBeforeRollback = false;
+
+                try {
+                    await context.orm.transaction(async () => {
+                        await Task.update({ id: task.id }, { title: 'should be rolled back' });
+
+                        // Keep the transaction open long enough for an eager
+                        // invalidation implementation to recompute and publish.
+                        await new Promise(resolve => setTimeout(resolve, 50));
+                        patchBeforeRollback = probe!.received.some(message => message.t === 'patch');
+                        throw new Error('rollback live write');
+                    });
+                } catch (error) {
+                    failureMessage = (error as Error).message;
+                }
+
+                expect(failureMessage).toBe('rollback live write');
+                expect(patchBeforeRollback).toBe(false);
+                await new Promise(resolve => setTimeout(resolve, 50));
+                expect(probe.received.some(message => message.t === 'patch')).toBe(false);
+
+                const persisted = await context.executeSql(
+                    `SELECT title FROM live_tasks WHERE id = ${task.id}`
+                );
+                expect(persisted.rows[0].title).toBe('before transaction');
+            } finally {
+                probe?.close();
+                await harness.close();
+            }
+        });
+    });
+
+    test('publishes a transactional write only after commit', async () => {
+        await withDatabase(TABLE_STATEMENTS, async context => {
+            const harness = await createTestHarness({
+                plugins: [LivePlugin.create({ controllers: [TasksController], config: { coalesceMs: 5 } })],
+                listen: true
+            });
+
+            let probe: ProbeClient | undefined;
+
+            try {
+                const task = await Task.create({ title: 'before commit', tenant: 'acme' });
+                probe = await ProbeClient.connect(harness.port!);
+                probe.send({
+                    t: 'sub',
+                    sid: 'a',
+                    resource: 'TasksController.list',
+                    inputs: { params: {}, query: { tenant: 'acme' } }
+                });
+                await probe.wait(message => message.t === 'snapshot');
+
+                let patchBeforeCommit = false;
+
+                await context.orm.transaction(async () => {
+                    await Task.update({ id: task.id }, { title: 'after commit' });
+                    await new Promise(resolve => setTimeout(resolve, 50));
+                    patchBeforeCommit = probe!.received.some(message => message.t === 'patch');
+                });
+
+                expect(patchBeforeCommit).toBe(false);
+                const patch = await probe.wait(message => message.t === 'patch');
+                expect((patch as any).ops).toEqual(expect.arrayContaining([
+                    expect.objectContaining({ op: 'upsert' })
+                ]));
+            } finally {
+                probe?.close();
+                await harness.close();
+            }
+        });
+    });
+
+    test('resubscribing with the current hash retransmits nothing (criterion 3)', async () => {
+        await withDatabase(TABLE_STATEMENTS, async () => {
+            const harness = await createTestHarness({
+                plugins: [LivePlugin.create({ controllers: [TasksController], config: { coalesceMs: 5 } })],
+                listen: true
+            });
+
+            try {
+                await Task.create({ title: 'only', tenant: 'acme' });
+
+                const first = await ProbeClient.connect(harness.port!);
+                first.send({ t: 'sub', sid: 'a', resource: 'TasksController.list', inputs: { params: {}, query: { tenant: 'acme' } } });
+                const snapshot = await first.wait(message => message.t === 'snapshot');
+                first.close();
+
+                const second = await ProbeClient.connect(harness.port!);
+                second.send({
+                    t: 'sub',
+                    sid: 'a',
+                    resource: 'TasksController.list',
+                    inputs: { params: {}, query: { tenant: 'acme' } },
+                    hash: (snapshot as any).hash
+                });
+
+                const current = await second.wait(message => message.t === 'current');
+                expect((current as any).data).toBeUndefined();
+
+                second.close();
+            } finally {
+                await harness.close();
+            }
+        });
+    });
+
+    test('the same route still answers plain JSON (criterion 6)', async () => {
+        await withDatabase(TABLE_STATEMENTS, async () => {
+            const harness = await createTestHarness({
+                plugins: [LivePlugin.create({ controllers: [TasksController] })],
+                listen: true
+            });
+
+            try {
+                await Task.create({ title: 'over http', tenant: 'acme' });
+
+                const response = await harness.get('/tasks?tenant=acme');
+
+                expect(response.status).toBe(200);
+                expect(await response.json()).toEqual([{ id: expect.any(Number), title: 'over http' }]);
+            } finally {
+                await harness.close();
+            }
+        });
+    });
+
+    test('two tenants subscribing the same resource never share an instance (criterion 8)', async () => {
+        await withDatabase(TABLE_STATEMENTS, async () => {
+            const harness = await createTestHarness({
+                plugins: [LivePlugin.create({ controllers: [TasksController], config: { coalesceMs: 5 } })],
+                listen: true
+            });
+
+            try {
+                await Task.create({ title: 'acme-only', tenant: 'acme' });
+                await Task.create({ title: 'globex-only', tenant: 'globex' });
+
+                const acme = await ProbeClient.connect(harness.port!);
+                const globex = await ProbeClient.connect(harness.port!);
+
+                acme.send({ t: 'sub', sid: 'a', resource: 'TasksController.list', inputs: { params: {}, query: { tenant: 'acme' } } });
+                globex.send({ t: 'sub', sid: 'a', resource: 'TasksController.list', inputs: { params: {}, query: { tenant: 'globex' } } });
+
+                const acmeSnapshot = await acme.wait(message => message.t === 'snapshot');
+                const globexSnapshot = await globex.wait(message => message.t === 'snapshot');
+
+                expect((acmeSnapshot as any).data).toEqual([{ id: expect.any(Number), title: 'acme-only' }]);
+                expect((globexSnapshot as any).data).toEqual([{ id: expect.any(Number), title: 'globex-only' }]);
+
+                acme.close();
+                globex.close();
+            } finally {
+                await harness.close();
+            }
+        });
+    });
+});

package/test/angular-adapter.test.ts

@@ -0,0 +1,151 @@
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { DestroyRef, EnvironmentInjector, Injector, runInInjectionContext, signal } from '@angular/core';
+import { LiveClient, type LiveSocket } from '../src/client/core';
+import { LIVE_CLIENT, liveSignal, provideLive, reconcileLiveSignal } from '../src/client/angular';
+import type { LiveDescriptor } from '../src/shared/descriptor';
+
+function fakeSocket(): LiveSocket & { sent: string[]; deliver: (message: unknown) => void } {
+    const socket = {
+        sent: [] as string[],
+        send(data: string) { socket.sent.push(data); },
+        close() {},
+        onopen: null as (() => void) | null,
+        onmessage: null as ((event: { data: string }) => void) | null,
+        onclose: null as (() => void) | null,
+        onerror: null as ((error: unknown) => void) | null,
+        deliver(message: unknown) { socket.onmessage?.({ data: JSON.stringify(message) }); }
+    };
+
+    return socket;
+}
+
+interface CardsRoute {
+    response: { id: number; title: string }[];
+    query: { done?: string };
+}
+
+const cardsList: LiveDescriptor<CardsRoute> = {
+    method: 'get',
+    path: '/cards',
+    resourceId: 'CardsController.list',
+    live: { shared: 'public', key: 'id' }
+};
+
+let socket: ReturnType<typeof fakeSocket>;
+let client: LiveClient;
+let injector: Injector;
+
+beforeEach(() => {
+    socket = fakeSocket();
+    client = new LiveClient({ url: 'ws://x/live', socketFactory: () => socket, unsubGraceMs: 0 });
+    injector = Injector.create({ providers: [provideLive(client)] });
+});
+
+function lastSub(): any {
+    const raw = [...socket.sent].reverse().find(entry => entry.includes('"t":"sub"'));
+    return raw ? JSON.parse(raw) : null;
+}
+
+function host<T>(fn: () => T): T {
+    return runInInjectionContext(injector, fn);
+}
+
+describe('liveSignal', () => {
+    test('starts pending and reads the client from LIVE_CLIENT', () => {
+        const state = host(() => liveSignal(cardsList));
+        reconcileLiveSignal(state);
+
+        expect(injector.get(LIVE_CLIENT)).toBe(client);
+        expect(state()).toEqual({ data: undefined, pending: true, error: null, stale: false });
+    });
+
+    test('a snapshot updates the signal', () => {
+        const state = host(() => liveSignal(cardsList));
+        reconcileLiveSignal(state);
+        socket.onopen?.();
+        socket.deliver({ t: 'snapshot', sid: lastSub().sid, rev: 1, hash: 'h1', data: [{ id: 1, title: 'a' }] });
+
+        expect(state().data).toEqual([{ id: 1, title: 'a' }]);
+        expect(state().pending).toBe(false);
+    });
+
+    test('changing a reactive input resubscribes with the new inputs', async () => {
+        const done = signal('false');
+        const state = host(() =>
+            liveSignal(cardsList, () => ({ query: { done: done() } }))
+        );
+        reconcileLiveSignal(state);
+        socket.onopen?.();
+
+        expect(lastSub().inputs.query).toEqual({ done: 'false' });
+
+        done.set('true');
+        reconcileLiveSignal(state);
+
+        expect(lastSub().inputs.query).toEqual({ done: 'true' });
+        // LiveClient always schedules unsub through setTimeout, even at 0ms.
+        await new Promise(resolve => setTimeout(resolve, 0));
+        expect(socket.sent.filter(raw => raw.includes('"t":"unsub"')).length).toBe(1);
+        void state;
+    });
+
+    test('a reactive input that recomputes to the same value does not resubscribe', () => {
+        const unrelated = signal(0);
+        const state = host(() =>
+            liveSignal(cardsList, () => {
+                void unrelated();
+                return { query: { done: 'false' } };
+            })
+        );
+        reconcileLiveSignal(state);
+        socket.onopen?.();
+        const before = socket.sent.length;
+
+        unrelated.set(1);
+        reconcileLiveSignal(state);
+
+        expect(socket.sent.length).toBe(before);
+        void state;
+    });
+
+    test('destroying the injection context unsubscribes', async () => {
+        const state = host(() => liveSignal(cardsList));
+        reconcileLiveSignal(state);
+        socket.onopen?.();
+
+        (injector as EnvironmentInjector).destroy();
+
+        // LiveClient always schedules unsub through setTimeout, even at 0ms.
+        await new Promise(resolve => setTimeout(resolve, 0));
+        expect(socket.sent.some(raw => raw.includes('"t":"unsub"'))).toBe(true);
+    });
+
+    test('an explicit client wins over the injected one', () => {
+        const otherSocket = fakeSocket();
+        const other = new LiveClient({ url: 'ws://y/live', socketFactory: () => otherSocket });
+
+        const state = host(() => liveSignal(cardsList, undefined, { client: other }));
+        reconcileLiveSignal(state);
+        otherSocket.onopen?.();
+
+        expect(otherSocket.sent.some(raw => raw.includes('"t":"sub"'))).toBe(true);
+        expect(socket.sent).toEqual([]);
+    });
+
+    test('a non-scheduler error from effect is not swallowed', () => {
+        const destroyRef = injector.get(DestroyRef);
+        const broken = {
+            get(token: unknown) {
+                if (token === DestroyRef) {
+                    return destroyRef;
+                }
+
+                throw new Error('boom from injector');
+            }
+        } as Injector;
+
+        expect(() => host(() => liveSignal(cardsList, undefined, { injector: broken }))).toThrow(
+            'boom from injector'
+        );
+    });
+});

package/test/app-emitter.test.ts

@@ -0,0 +1,112 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { statementObserver, type Statement } from '@carno.js/orm';
+import { AppEmitter, WriteDuringComputeError } from '../src/emitters/AppEmitter';
+import { InProcessBus } from '../src/bus/InProcessBus';
+import { DEFAULT_LIVE_CONFIG } from '../src/config';
+import { dependencyContext } from '../src/resource/dependency-context';
+import type { InvalidationEvent } from '../src/graph/types';
+
+afterEach(() => {
+    statementObserver.reset();
+});
+
+function statement(overrides: Partial<Statement<any>>): Statement<any> {
+    return { table: 'users', alias: 'u', primaryKeyColumnName: 'id', ...overrides };
+}
+
+describe('InProcessBus', () => {
+    test('delivers published events to every subscriber', () => {
+        const bus = new InProcessBus();
+        const seen: InvalidationEvent[][] = [];
+        bus.subscribe(events => seen.push(events));
+        bus.subscribe(events => seen.push(events));
+
+        bus.publish([{ key: 'orm:users', columns: null }]);
+
+        expect(seen).toHaveLength(2);
+    });
+
+    test('unsubscribe stops delivery', () => {
+        const bus = new InProcessBus();
+        let calls = 0;
+        const off = bus.subscribe(() => { calls++; });
+
+        bus.publish([{ key: 'a', columns: null }]);
+        off();
+        bus.publish([{ key: 'a', columns: null }]);
+
+        expect(calls).toBe(1);
+    });
+
+    test('one failing subscriber does not stop the others', () => {
+        const bus = new InProcessBus();
+        let reached = false;
+        bus.subscribe(() => { throw new Error('boom'); });
+        bus.subscribe(() => { reached = true; });
+
+        bus.publish([{ key: 'a', columns: null }]);
+
+        expect(reached).toBe(true);
+    });
+});
+
+describe('AppEmitter', () => {
+    test('feeds reads into the active dependency collector', async () => {
+        const emitter = new AppEmitter(new InProcessBus(), DEFAULT_LIVE_CONFIG);
+        emitter.attach();
+
+        const { deps } = await dependencyContext.run(() => {
+            statementObserver.notifyRead(statement({ statement: 'select', where: 'u."id" = 42' }));
+            return Promise.resolve(null);
+        });
+
+        expect(deps).toEqual([{ key: 'orm:users#42', columns: null }]);
+    });
+
+    test('drops reads that happen outside a compute', () => {
+        const emitter = new AppEmitter(new InProcessBus(), DEFAULT_LIVE_CONFIG);
+        emitter.attach();
+
+        expect(() => statementObserver.notifyRead(statement({ statement: 'select' }))).not.toThrow();
+    });
+
+    test('publishes an invalidation for a write', () => {
+        const bus = new InProcessBus();
+        const seen: InvalidationEvent[][] = [];
+        bus.subscribe(events => seen.push(events));
+        new AppEmitter(bus, DEFAULT_LIVE_CONFIG).attach();
+
+        statementObserver.notifyWrite(statement({ statement: 'update', where: 'u."id" = 7', values: { name: 'x' } }));
+
+        expect(seen).toEqual([[{ key: 'orm:users#7', columns: ['name'] }]]);
+    });
+
+    test('refuses a write attempted during a compute', async () => {
+        new AppEmitter(new InProcessBus(), DEFAULT_LIVE_CONFIG).attach();
+
+        await dependencyContext.run(() => {
+            expect(() => statementObserver.notifyWriteAttempt(statement({ statement: 'update' })))
+                .toThrow(WriteDuringComputeError);
+            return Promise.resolve(null);
+        });
+    });
+
+    test('allows writes outside a compute', () => {
+        new AppEmitter(new InProcessBus(), DEFAULT_LIVE_CONFIG).attach();
+
+        expect(() => statementObserver.notifyWriteAttempt(statement({ statement: 'update' }))).not.toThrow();
+    });
+
+    test('detach unhooks the observer', () => {
+        const bus = new InProcessBus();
+        let calls = 0;
+        bus.subscribe(() => { calls++; });
+        const emitter = new AppEmitter(bus, DEFAULT_LIVE_CONFIG);
+
+        emitter.attach();
+        emitter.detach();
+        statementObserver.notifyWrite(statement({ statement: 'update', values: { a: 1 } }));
+
+        expect(calls).toBe(0);
+    });
+});