@carno.js/live 1.8.0

package/test/metrics.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, test } from 'bun:test';
+import { LiveMetrics, type MetricSink } from '../src/observability';
+
+function recorder(): MetricSink & { seen: { name: string; value: number; tags?: Record<string, any> }[] } {
+    const seen: { name: string; value: number; tags?: Record<string, any> }[] = [];
+
+    return {
+        seen,
+        onMetric(name, value, tags) { seen.push({ name, value, tags }); }
+    };
+}
+
+describe('LiveMetrics', () => {
+    test('a recompute that produced a patch publishes the count, the duration and the size', () => {
+        const sink = recorder();
+
+        new LiveMetrics(sink).recompute('CardsController.list', true, 3, 12.5);
+
+        expect(sink.seen).toEqual([
+            { name: 'live.recompute', value: 1, tags: { resource: 'CardsController.list', patched: true } },
+            { name: 'live.recompute.ms', value: 12.5, tags: { resource: 'CardsController.list' } },
+            { name: 'live.patch.ops', value: 3, tags: { resource: 'CardsController.list' } }
+        ]);
+    });
+
+    test('a recompute that produced no patch is counted, and publishes no patch size', () => {
+        const sink = recorder();
+
+        new LiveMetrics(sink).recompute('CardsController.list', false, 0, 4);
+
+        expect(sink.seen.map(entry => entry.name)).toEqual(['live.recompute', 'live.recompute.ms']);
+        expect(sink.seen[0].tags).toEqual({ resource: 'CardsController.list', patched: false });
+    });
+
+    test('an invalidation publishes how many keys arrived and how many instances woke', () => {
+        const sink = recorder();
+
+        new LiveMetrics(sink).invalidation(2, 17);
+
+        expect(sink.seen).toEqual([
+            { name: 'live.invalidation.keys', value: 2, tags: undefined },
+            { name: 'live.invalidation.fanout', value: 17, tags: undefined }
+        ]);
+    });
+
+    test('an invalidation that woke nothing still publishes the fan-out', () => {
+        const sink = recorder();
+
+        // Zero fan-out is the healthy case and the interesting one: it is what
+        // a precise graph looks like. Dropping it would bias the average up.
+        new LiveMetrics(sink).invalidation(1, 0);
+
+        expect(sink.seen.find(entry => entry.name === 'live.invalidation.fanout')?.value).toBe(0);
+    });
+
+    test('none() swallows everything without a sink', () => {
+        expect(() => {
+            LiveMetrics.none().recompute('X.y', true, 1, 1);
+            LiveMetrics.none().invalidation(1, 1);
+            LiveMetrics.none().instances(5);
+        }).not.toThrow();
+    });
+
+    test('a sink that throws does not take the caller down', () => {
+        const metrics = new LiveMetrics({
+            onMetric() { throw new Error('the metrics backend is down'); }
+        });
+
+        // Losing a number is acceptable. Losing a recompute is not.
+        expect(() => metrics.recompute('X.y', true, 1, 1)).not.toThrow();
+    });
+});
+
+import { DependencyGraph } from '../src/graph/DependencyGraph';
+import { InProcessBus } from '../src/bus/InProcessBus';
+import { LiveEngine } from '../src/LiveEngine';
+import { ResourceRegistry } from '../src/resource/ResourceRegistry';
+import { directResourceExecutor } from './resource-registry-helper';
+import { SubscriptionRegistry } from '../src/graph/SubscriptionRegistry';
+import { resolveLiveConfig } from '../src/config';
+import { Controller, Get } from '@carno.js/core';
+import { Live } from '../src/decorators/Live';
+
+describe('LiveEngine metrics', () => {
+    test('a recompute that changes nothing publishes patched=false', async () => {
+        let payload = [{ id: 1 }];
+
+        @Controller('/things')
+        class ThingsController {
+            @Get('/')
+            @Live({ shared: 'public', dependsOn: ['orm:things'] })
+            list() { return payload; }
+        }
+
+        const sink = recorder();
+        const resources = new ResourceRegistry();
+        resources.register(ThingsController, new ThingsController(), directResourceExecutor);
+
+        const bus = new InProcessBus();
+        const engine = new LiveEngine(
+            resources,
+            new DependencyGraph(),
+            new SubscriptionRegistry(),
+            bus,
+            { send: () => 1 },
+            resolveLiveConfig({ coalesceMs: 1 }),
+            undefined,
+            new LiveMetrics(sink)
+        );
+
+        engine.start();
+        await engine.subscribe('c1', 's1', 'ThingsController.list', { params: {}, query: {} }, {});
+
+        bus.publish([{ key: 'orm:things', columns: null }]);
+        await new Promise(resolve => setTimeout(resolve, 40));
+
+        const recomputes = sink.seen.filter(entry => entry.name === 'live.recompute');
+        expect(recomputes.some(entry => entry.tags?.patched === false)).toBe(true);
+        expect(sink.seen.some(entry => entry.name === 'live.patch.ops')).toBe(false);
+
+        // And the same invalidation, now producing real change, flips it.
+        payload = [{ id: 1 }, { id: 2 }];
+        bus.publish([{ key: 'orm:things', columns: null }]);
+        await new Promise(resolve => setTimeout(resolve, 40));
+
+        expect(sink.seen.some(entry => entry.name === 'live.patch.ops')).toBe(true);
+        expect(sink.seen.some(entry => entry.name === 'live.invalidation.fanout' && entry.value === 1)).toBe(true);
+
+        engine.stop();
+    });
+});

package/test/optimistic.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, test } from 'bun:test';
+import { LiveClient, type LiveSocket } from '../src/client/core';
+import type { ClientMessage, ServerMessage } from '../src/shared/protocol';
+
+class FakeSocket implements LiveSocket {
+    onopen: (() => void) | null = null;
+    onmessage: ((event: { data: string }) => void) | null = null;
+    onclose: (() => void) | null = null;
+    onerror: ((error: unknown) => void) | null = null;
+
+    readonly sent: ClientMessage[] = [];
+
+    send(data: string): void {
+        this.sent.push(JSON.parse(data));
+    }
+
+    close(): void {}
+
+    open(): void {
+        this.onopen?.();
+    }
+
+    deliver(message: ServerMessage): void {
+        this.onmessage?.({ data: JSON.stringify(message) });
+    }
+
+    sid(): string {
+        const sub = this.sent.find(message => message.t === 'sub') as { sid: string };
+        return sub.sid;
+    }
+}
+
+function build() {
+    const socket = new FakeSocket();
+    const client = new LiveClient({
+        url: 'ws://test/live',
+        socketFactory: () => socket,
+        unsubGraceMs: 5
+    });
+
+    const store = client.store<{ id: number; title: string }[]>('Cards.list', { params: {}, query: {} });
+    store.subscribe(() => {});
+    socket.open();
+    socket.deliver({
+        t: 'snapshot',
+        sid: socket.sid(),
+        rev: 1,
+        hash: 'h1',
+        data: [{ id: 1, title: 'Ada' }],
+        key: 'id'
+    });
+
+    return { client, socket, store };
+}
+
+describe('optimistic overlay', () => {
+    test('shows the optimistic row before the server knows about it', () => {
+        const { client, store } = build();
+
+        client.overlay('Cards.list', draft => {
+            (draft as { id: number; title: string }[]).push({ id: -1, title: 'pending' });
+        });
+
+        expect(store.getSnapshot().data).toEqual([
+            { id: 1, title: 'Ada' },
+            { id: -1, title: 'pending' }
+        ]);
+    });
+
+    test('removing the overlay goes back to what the server confirmed', () => {
+        const { client, store } = build();
+
+        const remove = client.overlay('Cards.list', draft => {
+            (draft as { id: number; title: string }[]).push({ id: -1, title: 'pending' });
+        });
+        remove();
+
+        expect(store.getSnapshot().data).toEqual([{ id: 1, title: 'Ada' }]);
+    });
+
+    test('a server patch during the action applies underneath the overlay', () => {
+        const { client, socket, store } = build();
+
+        client.overlay('Cards.list', draft => {
+            (draft as { id: number; title: string }[]).push({ id: -1, title: 'pending' });
+        });
+
+        socket.deliver({
+            t: 'patch',
+            sid: socket.sid(),
+            from: 1,
+            to: 2,
+            hash: 'h2',
+            ops: [{ op: 'upsert', path: [], key: 2, index: 1, value: { id: 2, title: 'Linus' } }]
+        });
+
+        // The server's row landed on the confirmed snapshot; the optimistic row
+        // is still projected on top of it.
+        expect(store.getSnapshot().data).toEqual([
+            { id: 1, title: 'Ada' },
+            { id: 2, title: 'Linus' },
+            { id: -1, title: 'pending' }
+        ]);
+    });
+
+    test('the confirmed snapshot survives the overlay being dropped', () => {
+        const { client, socket, store } = build();
+
+        const remove = client.overlay('Cards.list', draft => {
+            (draft as { id: number; title: string }[]).push({ id: -1, title: 'pending' });
+        });
+
+        socket.deliver({
+            t: 'patch',
+            sid: socket.sid(),
+            from: 1,
+            to: 2,
+            hash: 'h2',
+            ops: [{ op: 'upsert', path: [], key: 2, index: 1, value: { id: 2, title: 'Linus' } }]
+        });
+        remove();
+
+        expect(store.getSnapshot().data).toEqual([
+            { id: 1, title: 'Ada' },
+            { id: 2, title: 'Linus' }
+        ]);
+    });
+
+    test('two overlays apply in the order they were added', () => {
+        const { client, store } = build();
+
+        client.overlay('Cards.list', draft => {
+            (draft as { id: number; title: string }[]).push({ id: -1, title: 'first' });
+        });
+        client.overlay('Cards.list', draft => {
+            (draft as { id: number; title: string }[]).push({ id: -2, title: 'second' });
+        });
+
+        expect(store.getSnapshot().data).toEqual([
+            { id: 1, title: 'Ada' },
+            { id: -1, title: 'first' },
+            { id: -2, title: 'second' }
+        ]);
+    });
+
+    test('an overlay for another resource leaves this store alone', () => {
+        const { client, store } = build();
+        const before = store.getSnapshot();
+
+        client.overlay('Cards.other', draft => {
+            (draft as unknown[]).push({ id: -1 });
+        });
+
+        expect(store.getSnapshot()).toBe(before);
+    });
+
+    test('an overlay that throws does not break the store', () => {
+        const { client, store } = build();
+
+        client.overlay('Cards.list', () => {
+            throw new Error('bad optimistic update');
+        });
+
+        expect(store.getSnapshot().data).toEqual([{ id: 1, title: 'Ada' }]);
+    });
+});

package/test/orm-integration.test.ts

@@ -0,0 +1,75 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { Entity, PrimaryKey, Property, BaseEntity, statementObserver, type Statement } from '../../orm/src';
+import { withDatabase } from '../../orm/src/testing';
+import { readDependencies, writeEvents } from '../src/emitters/statement-keys';
+import { DEFAULT_LIVE_CONFIG } from '../src/config';
+
+const TABLE_STATEMENTS = [
+    'CREATE TABLE live_users (id SERIAL PRIMARY KEY, name TEXT NOT NULL, last_seen_at TIMESTAMP NULL);'
+];
+
+@Entity({ tableName: 'live_users' })
+class LiveUser extends BaseEntity<LiveUser> {
+    @PrimaryKey()
+    id!: number;
+
+    @Property()
+    name!: string;
+
+    @Property({ nullable: true })
+    lastSeenAt?: Date;
+}
+
+afterEach(() => {
+    statementObserver.reset();
+});
+
+describe('statement keys against real ORM output', () => {
+    test('a findOne by primary key yields a row dependency', async () => {
+        await withDatabase(TABLE_STATEMENTS, async () => {
+            const reads: Statement<any>[] = [];
+            statementObserver.onRead(statement => reads.push(statement));
+
+            const created = await LiveUser.create({ name: 'Ada' });
+            await LiveUser.findOne({ id: created.id });
+
+            const select = reads.find(statement => statement.statement === 'select');
+            expect(select).toBeDefined();
+
+            const deps = readDependencies(select!, DEFAULT_LIVE_CONFIG.maxKeysPerRead);
+            expect(deps[0].key).toBe(`orm:live_users#${created.id}`);
+        });
+    });
+
+    test('a write emits the row key with the columns it wrote', async () => {
+        await withDatabase(TABLE_STATEMENTS, async () => {
+            const writes: Statement<any>[] = [];
+            statementObserver.onWrite(statement => writes.push(statement));
+
+            const created = await LiveUser.create({ name: 'Ada' });
+            await LiveUser.update({ id: created.id }, { name: 'Ada Lovelace' });
+
+            const update = writes.find(statement => statement.statement === 'update');
+            expect(update).toBeDefined();
+
+            const events = writeEvents(update!, DEFAULT_LIVE_CONFIG.maxKeysPerRead);
+            expect(events[0].key).toBe(`orm:live_users#${created.id}`);
+            expect(events[0].columns).toContain('name');
+        });
+    });
+
+    test('the generated column list normalizes to bare column names', async () => {
+        await withDatabase(TABLE_STATEMENTS, async () => {
+            const reads: Statement<any>[] = [];
+            statementObserver.onRead(statement => reads.push(statement));
+
+            await LiveUser.find({});
+
+            const select = reads.find(statement => statement.statement === 'select');
+            const deps = readDependencies(select!, DEFAULT_LIVE_CONFIG.maxKeysPerRead);
+
+            expect(deps[0].key).toBe('orm:live_users');
+            expect(deps[0].columns).toEqual(expect.arrayContaining(['id', 'name']));
+        });
+    });
+});

package/test/patch-engine.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test } from 'bun:test';
+import { PatchEngine } from '../src/patch/PatchEngine';
+
+describe('PatchEngine without a key', () => {
+    const engine = new PatchEngine();
+
+    test('produces no ops for deep-equal values', () => {
+        expect(engine.diff({ a: 1, b: { c: 2 } }, { a: 1, b: { c: 2 } })).toEqual([]);
+    });
+
+    test('sets a changed leaf', () => {
+        expect(engine.diff({ a: 1 }, { a: 2 })).toEqual([{ op: 'set', path: ['a'], value: 2 }]);
+    });
+
+    test('unsets a removed property', () => {
+        expect(engine.diff({ a: 1, b: 2 }, { a: 1 })).toEqual([{ op: 'unset', path: ['b'] }]);
+    });
+
+    test('recurses into nested objects instead of replacing them', () => {
+        expect(engine.diff({ a: { b: 1, c: 2 } }, { a: { b: 9, c: 2 } }))
+            .toEqual([{ op: 'set', path: ['a', 'b'], value: 9 }]);
+    });
+
+    test('replaces an unkeyed array wholesale', () => {
+        expect(engine.diff({ xs: [1, 2] }, { xs: [1, 2, 3] }))
+            .toEqual([{ op: 'set', path: ['xs'], value: [1, 2, 3] }]);
+    });
+});
+
+describe('PatchEngine with a key', () => {
+    const engine = new PatchEngine('id');
+
+    const a = { id: 1, name: 'Ada' };
+    const b = { id: 2, name: 'Bob' };
+    const c = { id: 3, name: 'Cid' };
+
+    test('inserting at the top is an upsert plus an order, not a rebuild', () => {
+        const ops = engine.diff([a, b], [c, a, b]);
+
+        expect(ops).toEqual([
+            { op: 'upsert', path: [], key: 3, index: 0, value: c },
+            { op: 'order', path: [], keys: [3, 1, 2] }
+        ]);
+    });
+
+    test('changing one row touches only that row', () => {
+        const ops = engine.diff([a, b], [a, { id: 2, name: 'Bobby' }]);
+
+        expect(ops).toEqual([
+            { op: 'upsert', path: [], key: 2, index: 1, value: { id: 2, name: 'Bobby' } }
+        ]);
+    });
+
+    test('removing a row emits remove', () => {
+        expect(engine.diff([a, b], [a])).toEqual([{ op: 'remove', path: [], key: 2 }]);
+    });
+
+    test('reordering without changing content emits only order', () => {
+        expect(engine.diff([a, b], [b, a])).toEqual([{ op: 'order', path: [], keys: [2, 1] }]);
+    });
+
+    test('applies keyed diffs to arrays nested in objects', () => {
+        const ops = engine.diff({ users: [a, b] }, { users: [a] });
+        expect(ops).toEqual([{ op: 'remove', path: ['users'], key: 2 }]);
+    });
+
+    test('falls back to a whole-array set when an element lacks the key', () => {
+        const ops = engine.diff([a], [a, { name: 'no id' }]);
+        expect(ops).toEqual([{ op: 'set', path: [], value: [a, { name: 'no id' }] }]);
+    });
+});
+
+describe('PatchEngine.apply', () => {
+    test('round-trips: apply(prev, diff(prev, next)) deep-equals next', () => {
+        const engine = new PatchEngine('id');
+        const cases: [unknown, unknown][] = [
+            [{ a: 1 }, { a: 2 }],
+            [{ a: 1, b: 2 }, { a: 1 }],
+            [{ a: { b: 1 } }, { a: { b: 2, c: 3 } }],
+            [[{ id: 1 }, { id: 2 }], [{ id: 2 }, { id: 1 }]],
+            [[{ id: 1, n: 'a' }], [{ id: 1, n: 'b' }, { id: 2, n: 'c' }]],
+            [{ users: [{ id: 1 }] }, { users: [] }],
+            [{ xs: [1, 2] }, { xs: [3] }]
+        ];
+
+        for (const [prev, next] of cases) {
+            expect(engine.apply(prev, engine.diff(prev, next))).toEqual(next as any);
+        }
+    });
+
+    test('untouched sibling objects keep reference identity', () => {
+        const engine = new PatchEngine();
+        const prev = { left: { deep: { n: 1 } }, right: { n: 2 } };
+        const next = { left: { deep: { n: 1 } }, right: { n: 3 } };
+
+        const applied = engine.apply(prev, engine.diff(prev, next)) as typeof prev;
+
+        expect(applied.left).toBe(prev.left);
+        expect(applied).not.toBe(prev);
+        expect(applied.right).not.toBe(prev.right);
+    });
+
+    test('untouched rows of a keyed list keep reference identity', () => {
+        const engine = new PatchEngine('id');
+        const kept = { id: 1, name: 'Ada' };
+        const prev = [kept, { id: 2, name: 'Bob' }];
+        const next = [kept, { id: 2, name: 'Bobby' }];
+
+        const applied = engine.apply(prev, engine.diff(prev, next)) as typeof prev;
+
+        expect(applied[0]).toBe(kept);
+        expect(applied).not.toBe(prev);
+    });
+
+    test('an empty op list returns the very same root', () => {
+        const engine = new PatchEngine();
+        const prev = { a: 1 };
+
+        expect(engine.apply(prev, [])).toBe(prev);
+    });
+});

package/test/pg-bus.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, test } from 'bun:test';
+import { PgNotifyBus, chunkEvents } from '../src/bus/PgNotifyBus';
+import { PgListener, type ListenableSql } from '../src/emitters/pg-listener';
+import type { InvalidationEvent } from '../src/graph/types';
+
+/** Stands in for the Postgres notification bus, shared by several connections. */
+class FakeBroker {
+    private readonly handlers = new Map<string, Set<(payload: string) => void>>();
+
+    connection(): ListenableSql {
+        const broker = this;
+        const own = new Set<{ channel: string; handler: (payload: string) => void }>();
+
+        return {
+            async listen(channel: string, onNotify: (payload: string) => void): Promise<void> {
+                let bucket = broker.handlers.get(channel);
+
+                if (!bucket) {
+                    bucket = new Set();
+                    broker.handlers.set(channel, bucket);
+                }
+
+                bucket.add(onNotify);
+                own.add({ channel, handler: onNotify });
+            },
+            async notify(channel: string, payload = ''): Promise<void> {
+                // Postgres delivers to every listening session, sender included.
+                for (const handler of [...(broker.handlers.get(channel) ?? [])]) {
+                    handler(payload);
+                }
+            },
+            async unsafe(): Promise<void> {},
+            async close(): Promise<void> {
+                for (const entry of own) {
+                    broker.handlers.get(entry.channel)?.delete(entry.handler);
+                }
+
+                own.clear();
+            }
+        };
+    }
+}
+
+function node(broker: FakeBroker, nodeId: string) {
+    const received: InvalidationEvent[] = [];
+    const bus = new PgNotifyBus({
+        url: 'postgres://ignored',
+        channel: 'carno_test_bus',
+        nodeId,
+        listener: new PgListener({
+            url: 'postgres://ignored',
+            heartbeatMs: 0,
+            sqlFactory: () => broker.connection()
+        })
+    });
+
+    bus.subscribe(events => received.push(...events));
+
+    return { bus, received };
+}
+
+describe('chunkEvents', () => {
+    test('keeps everything in one frame when it fits', () => {
+        const frames = chunkEvents([{ key: 'orm:users#1', columns: null }], 'n1', 7000);
+
+        expect(frames).toHaveLength(1);
+        expect(JSON.parse(frames[0])).toEqual({ n: 'n1', e: [{ key: 'orm:users#1', columns: null }] });
+    });
+
+    test('splits into frames under the ceiling', () => {
+        const events = Array.from({ length: 50 }, (_, index) => ({
+            key: `orm:users#${index}`,
+            columns: ['name', 'email']
+        }));
+
+        const frames = chunkEvents(events, 'n1', 400);
+
+        expect(frames.length).toBeGreaterThan(1);
+
+        for (const frame of frames) {
+            expect(Buffer.byteLength(frame, 'utf8')).toBeLessThanOrEqual(400);
+        }
+
+        expect(frames.flatMap(frame => JSON.parse(frame).e)).toEqual(events);
+    });
+
+    test('one oversized event degrades to its table instead of overflowing', () => {
+        const frames = chunkEvents(
+            [{ key: 'orm:users#1', columns: Array.from({ length: 200 }, (_, i) => `column_${i}`) }],
+            'n1',
+            300
+        );
+
+        expect(frames).toHaveLength(1);
+        expect(JSON.parse(frames[0]).e).toEqual([{ key: 'orm:users', columns: null }]);
+    });
+});
+
+describe('PgNotifyBus', () => {
+    test('an invalidation published on one node arrives on the other', async () => {
+        const broker = new FakeBroker();
+        const a = node(broker, 'a');
+        const b = node(broker, 'b');
+
+        await a.bus.start();
+        await b.bus.start();
+
+        a.bus.publish([{ key: 'orm:users#1', columns: ['name'] }]);
+        await new Promise(resolve => setTimeout(resolve, 10));
+
+        expect(b.received).toEqual([{ key: 'orm:users#1', columns: ['name'] }]);
+
+        await a.bus.stop();
+        await b.bus.stop();
+    });
+
+    test('the publishing node delivers locally exactly once', async () => {
+        const broker = new FakeBroker();
+        const a = node(broker, 'a');
+
+        await a.bus.start();
+        a.bus.publish([{ key: 'orm:users#1', columns: null }]);
+        await new Promise(resolve => setTimeout(resolve, 10));
+
+        // Postgres echoes the notification back to the sender; the node id is
+        // what keeps it from becoming a second invalidation.
+        expect(a.received).toEqual([{ key: 'orm:users#1', columns: null }]);
+
+        await a.bus.stop();
+    });
+
+    test('publishLocal stays on this node', async () => {
+        const broker = new FakeBroker();
+        const a = node(broker, 'a');
+        const b = node(broker, 'b');
+
+        await a.bus.start();
+        await b.bus.start();
+
+        a.bus.publishLocal([{ key: 'orm:users#1', columns: null }]);
+        await new Promise(resolve => setTimeout(resolve, 10));
+
+        expect(a.received).toHaveLength(1);
+        expect(b.received).toHaveLength(0);
+
+        await a.bus.stop();
+        await b.bus.stop();
+    });
+
+    test('garbage on the channel is ignored', async () => {
+        const broker = new FakeBroker();
+        const a = node(broker, 'a');
+
+        await a.bus.start();
+        await broker.connection().notify('carno_test_bus', 'not json');
+        await new Promise(resolve => setTimeout(resolve, 10));
+
+        expect(a.received).toHaveLength(0);
+
+        await a.bus.stop();
+    });
+});