@carno.js/live 1.8.0

package/test/use-live-action.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, test } from 'bun:test';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { LiveClient, storeKey, type LiveSocket } from '../src/client/core';
+import { LiveProvider, useLiveAction } from '../src/client/react';
+import type { LiveDescriptor } from '../src/shared/descriptor';
+
+interface Card {
+    id: string;
+    title: string;
+}
+
+const listDescriptor = {
+    method: 'get',
+    path: '/cards',
+    resourceId: 'BoardController.list',
+    live: { shared: 'public', key: 'id' }
+} as LiveDescriptor<{ response: Card[] }>;
+
+class SilentSocket implements LiveSocket {
+    onopen: (() => void) | null = null;
+    onmessage: ((event: { data: string }) => void) | null = null;
+    onclose: (() => void) | null = null;
+    onerror: ((error: unknown) => void) | null = null;
+    send(): void {}
+    close(): void {}
+}
+
+function clientWithBoard() {
+    const inputs = { params: {}, query: {}, body: undefined };
+    const client = new LiveClient({
+        url: 'ws://test/live',
+        socketFactory: () => new SilentSocket(),
+        hydrate: {
+            [storeKey('BoardController.list', inputs)]: {
+                data: [{ id: '1', title: 'Ada' }],
+                hash: 'h1'
+            }
+        }
+    });
+
+    const store = client.store<Card[]>('BoardController.list', inputs);
+    store.subscribe(() => {});
+
+    return { client, store };
+}
+
+/** Render once so the hook runs, and hand the produced action back out. */
+function actionFrom(client: LiveClient, build: () => (dto: any) => Promise<any>) {
+    let captured: ((dto: any) => Promise<any>) | null = null;
+
+    function Probe() {
+        captured = build();
+        return null;
+    }
+
+    renderToStaticMarkup(createElement(LiveProvider, { client }, createElement(Probe)));
+
+    return captured!;
+}
+
+describe('useLiveAction', () => {
+    test('applies the overlay while the action is in flight and drops it after', async () => {
+        const { client, store } = clientWithBoard();
+        const seen: unknown[] = [];
+        let release: (() => void) | null = null;
+
+        const send = actionFrom(client, () =>
+            useLiveAction(
+                (dto: { title: string }) =>
+                    new Promise<Card>(resolve => {
+                        release = () => resolve({ id: '2', title: dto.title });
+                    }),
+                {
+                    optimistic: [{
+                        on: listDescriptor,
+                        apply: (draft, dto) => {
+                            draft.push({ id: 'temp', title: dto.title });
+                        }
+                    }]
+                }
+            )
+        );
+
+        const pending = send({ title: 'Linus' });
+        seen.push(store.getSnapshot().data);
+
+        release!();
+        await pending;
+        seen.push(store.getSnapshot().data);
+
+        expect(seen[0]).toEqual([{ id: '1', title: 'Ada' }, { id: 'temp', title: 'Linus' }]);
+        expect(seen[1]).toEqual([{ id: '1', title: 'Ada' }]);
+    });
+
+    test('drops the overlay when the action fails', async () => {
+        const { client, store } = clientWithBoard();
+
+        const send = actionFrom(client, () =>
+            useLiveAction(
+                async () => {
+                    throw new Error('rejected by the server');
+                },
+                {
+                    optimistic: [{
+                        on: listDescriptor,
+                        apply: draft => {
+                            draft.push({ id: 'temp', title: 'never' });
+                        }
+                    }]
+                }
+            )
+        );
+
+        await expect(send({})).rejects.toThrow('rejected by the server');
+        expect(store.getSnapshot().data).toEqual([{ id: '1', title: 'Ada' }]);
+    });
+
+    test('an action with no optimistic entry just runs', async () => {
+        const { client, store } = clientWithBoard();
+
+        const send = actionFrom(client, () => useLiveAction(async (dto: { title: string }) => dto.title));
+
+        await expect(send({ title: 'plain' })).resolves.toBe('plain');
+        expect(store.getSnapshot().data).toEqual([{ id: '1', title: 'Ada' }]);
+    });
+});

package/test/use-live.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from 'bun:test';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { LiveClient, storeKey, type LiveSocket } from '../src/client/core';
+import { LiveProvider, useLive } from '../src/client/react';
+import {
+    normalizeLiveInputs,
+    resourceIdOf,
+    type LiveDescriptor
+} from '../src/shared/descriptor';
+
+interface Card {
+    id: string;
+    title: string;
+}
+
+const listDescriptor = {
+    method: 'get',
+    path: '/cards',
+    resourceId: 'BoardController.list',
+    live: { shared: 'tenant', key: 'id' }
+} as LiveDescriptor<{ query: { status?: string }; response: Card[] }>;
+
+const plainDescriptor = {
+    method: 'post',
+    path: '/cards'
+} as LiveDescriptor<{ body: { title: string }; response: Card }>;
+
+class SilentSocket implements LiveSocket {
+    onopen: (() => void) | null = null;
+    onmessage: ((event: { data: string }) => void) | null = null;
+    onclose: (() => void) | null = null;
+    onerror: ((error: unknown) => void) | null = null;
+    send(): void {}
+    close(): void {}
+}
+
+describe('resourceIdOf', () => {
+    test('returns the id of a live route', () => {
+        expect(resourceIdOf(listDescriptor)).toBe('BoardController.list');
+    });
+
+    test('explains itself when the route is not live', () => {
+        expect(() => resourceIdOf(plainDescriptor)).toThrow(/not a live resource/);
+    });
+});
+
+describe('normalizeLiveInputs', () => {
+    test('fills the three slots', () => {
+        expect(normalizeLiveInputs({ query: { status: 'open' } })).toEqual({
+            params: {},
+            query: { status: 'open' },
+            body: undefined
+        });
+    });
+
+    test('accepts nothing at all', () => {
+        expect(normalizeLiveInputs()).toEqual({ params: {}, query: {}, body: undefined });
+    });
+});
+
+describe('useLive with a descriptor', () => {
+    test('reads the hydrated store for that resource and inputs', () => {
+        const inputs = { params: {}, query: { status: 'open' }, body: undefined };
+        const client = new LiveClient({
+            url: 'ws://test/live',
+            socketFactory: () => new SilentSocket(),
+            hydrate: {
+                [storeKey('BoardController.list', inputs)]: {
+                    data: [{ id: '1', title: 'Ada' }],
+                    hash: 'h1'
+                }
+            }
+        });
+
+        function Board() {
+            const state = useLive(listDescriptor, { query: { status: 'open' } });
+            return createElement('div', null, JSON.stringify(state.data ?? null));
+        }
+
+        const html = renderToStaticMarkup(
+            createElement(LiveProvider, { client }, createElement(Board))
+        );
+
+        expect(html).toContain('Ada');
+    });
+
+    test('the string form from phase 1 still works', () => {
+        const inputs = { params: {}, query: {}, body: undefined };
+        const client = new LiveClient({
+            url: 'ws://test/live',
+            socketFactory: () => new SilentSocket(),
+            hydrate: {
+                [storeKey('BoardController.list', inputs)]: { data: [{ id: '9' }], hash: 'h9' }
+            }
+        });
+
+        function Board() {
+            const state = useLive<{ id: string }[]>('BoardController.list');
+            return createElement('div', null, JSON.stringify(state.data ?? null));
+        }
+
+        const html = renderToStaticMarkup(
+            createElement(LiveProvider, { client }, createElement(Board))
+        );
+
+        expect(html).toContain('&quot;9&quot;');
+    });
+});

package/test/vanilla-adapter.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, test } from 'bun:test';
+import { LiveClient, type LiveSocket } from '../src/client/core';
+import { LiveSlot, liveStore, liveStoreOf } from '../src/client/vanilla';
+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' }
+};
+
+describe('liveStore', () => {
+    test('subscribes on the first listener and reports the snapshot', () => {
+        const socket = fakeSocket();
+        const client = new LiveClient({ url: 'ws://x/live', socketFactory: () => socket });
+        const handle = liveStore(client, cardsList, { query: { done: 'false' } });
+        const seen: unknown[] = [];
+
+        handle.subscribe(state => seen.push(state.data));
+        socket.onopen?.();
+
+        const sub = JSON.parse(socket.sent.find(raw => raw.includes('"t":"sub"'))!);
+        expect(sub.resource).toBe('CardsController.list');
+        expect(sub.inputs.query).toEqual({ done: 'false' });
+
+        socket.deliver({ t: 'snapshot', sid: sub.sid, rev: 1, hash: 'h1', data: [{ id: 1, title: 'a' }] });
+
+        expect(handle.get().data).toEqual([{ id: 1, title: 'a' }]);
+        expect(seen.at(-1)).toEqual([{ id: 1, title: 'a' }]);
+    });
+
+    test('get() works before anyone subscribes', () => {
+        const socket = fakeSocket();
+        const client = new LiveClient({ url: 'ws://x/live', socketFactory: () => socket });
+        const handle = liveStore(client, cardsList);
+
+        expect(handle.get()).toEqual({ data: undefined, pending: true, error: null, stale: false });
+        expect(socket.sent).toEqual([]);
+    });
+
+    test('close() drops the listener without touching the others', () => {
+        const socket = fakeSocket();
+        const client = new LiveClient({ url: 'ws://x/live', socketFactory: () => socket });
+        const first = liveStore(client, cardsList);
+        const second = liveStore(client, cardsList);
+        let firstSaw = 0;
+        let secondSaw = 0;
+
+        first.subscribe(() => { firstSaw += 1; });
+        second.subscribe(() => { secondSaw += 1; });
+        socket.onopen?.();
+
+        const sub = JSON.parse(socket.sent.find(raw => raw.includes('"t":"sub"'))!);
+        first.close();
+        socket.deliver({ t: 'snapshot', sid: sub.sid, rev: 1, hash: 'h1', data: [] });
+
+        expect(firstSaw).toBe(0);
+        expect(secondSaw).toBe(1);
+    });
+
+    test('two handles for the same resource and inputs share one subscription', () => {
+        const socket = fakeSocket();
+        const client = new LiveClient({ url: 'ws://x/live', socketFactory: () => socket });
+
+        liveStore(client, cardsList, { query: { done: 'true' } }).subscribe(() => {});
+        liveStore(client, cardsList, { query: { done: 'true' } }).subscribe(() => {});
+        socket.onopen?.();
+
+        expect(socket.sent.filter(raw => raw.includes('"t":"sub"')).length).toBe(1);
+    });
+
+    test('a plain resource id works without a descriptor', () => {
+        const socket = fakeSocket();
+        const client = new LiveClient({ url: 'ws://x/live', socketFactory: () => socket });
+
+        liveStore<number[]>(client, 'CardsController.list').subscribe(() => {});
+        socket.onopen?.();
+
+        expect(JSON.parse(socket.sent[1]).resource).toBe('CardsController.list');
+    });
+
+    test('a descriptor without @Live() is refused with a message that says what to do', () => {
+        const client = new LiveClient({ url: 'ws://x/live', socketFactory: () => fakeSocket() });
+        const plain: LiveDescriptor<CardsRoute> = { method: 'get', path: '/cards' };
+
+        expect(() => liveStore(client, plain)).toThrow(/not a live resource/);
+    });
+});
+
+describe('liveStoreOf', () => {
+    test('resolves a descriptor to the same store a resource id resolves to', () => {
+        const client = new LiveClient({ url: 'ws://x/live', socketFactory: () => fakeSocket() });
+
+        const fromDescriptor = liveStoreOf(client, cardsList, {});
+        const fromId = liveStoreOf(client, 'CardsController.list', {});
+
+        expect(fromDescriptor).toBe(fromId);
+    });
+});
+
+describe('LiveSlot', () => {
+    test('reports the state of whatever it currently points at', () => {
+        const socket = fakeSocket();
+        const client = new LiveClient({ url: 'ws://x/live', socketFactory: () => socket });
+        const seen: unknown[] = [];
+        const slot = new LiveSlot<{ id: number }[]>(client, state => seen.push(state.data));
+
+        slot.point(cardsList, { query: { done: 'false' } });
+        socket.onopen?.();
+
+        const sub = JSON.parse(socket.sent.find(raw => raw.includes('"t":"sub"'))!);
+        socket.deliver({ t: 'snapshot', sid: sub.sid, rev: 1, hash: 'h1', data: [{ id: 1 }] });
+
+        expect(slot.get().data).toEqual([{ id: 1 }]);
+        expect(seen.at(-1)).toEqual([{ id: 1 }]);
+    });
+
+    test('pointing at the same inputs again is a no-op, not a resubscribe', () => {
+        const socket = fakeSocket();
+        const client = new LiveClient({ url: 'ws://x/live', socketFactory: () => socket });
+        const slot = new LiveSlot(client, () => {});
+
+        slot.point(cardsList, { query: { done: 'false' } });
+        socket.onopen?.();
+        const afterFirst = socket.sent.length;
+
+        // A reactive input that recomputed to the same value must not churn
+        // the subscription: the server would drop and rebuild the instance.
+        slot.point(cardsList, { query: { done: 'false' } });
+
+        expect(socket.sent.length).toBe(afterFirst);
+    });
+
+    test('pointing somewhere new releases the old target before retaining the new one', () => {
+        const socket = fakeSocket();
+        const client = new LiveClient({ url: 'ws://x/live', socketFactory: () => socket, unsubGraceMs: 0 });
+        const slot = new LiveSlot(client, () => {});
+
+        slot.point(cardsList, { query: { done: 'false' } });
+        socket.onopen?.();
+        slot.point(cardsList, { query: { done: 'true' } });
+
+        // Order matters: holding both at once is how a dragged filter walks a
+        // connection into maxInstancesPerConnection.
+        const kinds = socket.sent.map(raw => JSON.parse(raw).t);
+        expect(kinds.filter(kind => kind === 'sub').length).toBe(2);
+        expect(kinds.indexOf('sub')).toBeLessThan(kinds.lastIndexOf('sub'));
+    });
+
+    test('a state message for the old target after a switch is ignored', () => {
+        const socket = fakeSocket();
+        const client = new LiveClient({ url: 'ws://x/live', socketFactory: () => socket });
+        const seen: unknown[] = [];
+        const slot = new LiveSlot<{ id: number }[]>(client, state => seen.push(state.data));
+
+        slot.point(cardsList, { query: { done: 'false' } });
+        socket.onopen?.();
+        const first = JSON.parse(socket.sent.find(raw => raw.includes('"t":"sub"'))!);
+
+        slot.point(cardsList, { query: { done: 'true' } });
+        socket.deliver({ t: 'snapshot', sid: first.sid, rev: 1, hash: 'h1', data: [{ id: 9 }] });
+
+        expect(seen.some(data => JSON.stringify(data) === JSON.stringify([{ id: 9 }]))).toBe(false);
+    });
+
+    test('close() releases whatever it was pointing at', async () => {
+        const socket = fakeSocket();
+        const client = new LiveClient({ url: 'ws://x/live', socketFactory: () => socket, unsubGraceMs: 0 });
+        const slot = new LiveSlot(client, () => {});
+
+        slot.point(cardsList);
+        socket.onopen?.();
+        slot.close();
+
+        // 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);
+    });
+});

package/test/vue-adapter.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, test } from 'bun:test';
+import { effectScope, nextTick, ref } from 'vue';
+import { LiveClient, type LiveSocket } from '../src/client/core';
+import { useLiveQuery } from '../src/client/vue';
+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' }
+};
+
+function harness() {
+    const socket = fakeSocket();
+    const client = new LiveClient({ url: 'ws://x/live', socketFactory: () => socket, unsubGraceMs: 0 });
+    const scope = effectScope();
+
+    const lastSub = () => {
+        const raw = [...socket.sent].reverse().find(entry => entry.includes('"t":"sub"'));
+        return raw ? JSON.parse(raw) : null;
+    };
+
+    return { socket, client, scope, lastSub };
+}
+
+describe('useLiveQuery', () => {
+    test('starts pending and fills in from a snapshot', () => {
+        const { socket, client, scope, lastSub } = harness();
+        const state = scope.run(() => useLiveQuery(cardsList, undefined, { client }))!;
+
+        expect(state.value.pending).toBe(true);
+
+        socket.onopen?.();
+        socket.deliver({ t: 'snapshot', sid: lastSub().sid, rev: 1, hash: 'h1', data: [{ id: 1, title: 'a' }] });
+
+        expect(state.value.data).toEqual([{ id: 1, title: 'a' }]);
+        expect(state.value.pending).toBe(false);
+        scope.stop();
+    });
+
+    test('changing a reactive input resubscribes', async () => {
+        const { socket, client, scope, lastSub } = harness();
+        const done = ref('false');
+
+        scope.run(() => useLiveQuery(cardsList, () => ({ query: { done: done.value } }), { client }));
+        socket.onopen?.();
+
+        expect(lastSub().inputs.query).toEqual({ done: 'false' });
+
+        done.value = 'true';
+        await nextTick();
+        // LiveClient always schedules unsub through setTimeout, even at 0ms.
+        await new Promise(resolve => setTimeout(resolve, 0));
+
+        expect(lastSub().inputs.query).toEqual({ done: 'true' });
+        expect(socket.sent.filter(raw => raw.includes('"t":"unsub"')).length).toBe(1);
+        scope.stop();
+    });
+
+    test('a reactive input that recomputes to the same value does not resubscribe', async () => {
+        const { socket, client, scope } = harness();
+        const unrelated = ref(0);
+
+        scope.run(() => useLiveQuery(cardsList, () => {
+            void unrelated.value;
+            return { query: { done: 'false' } };
+        }, { client }));
+        socket.onopen?.();
+        const before = socket.sent.length;
+
+        unrelated.value = 1;
+        await nextTick();
+
+        expect(socket.sent.length).toBe(before);
+        scope.stop();
+    });
+
+    test('stopping the scope unsubscribes', async () => {
+        const { socket, client, scope } = harness();
+
+        scope.run(() => useLiveQuery(cardsList, undefined, { client }));
+        socket.onopen?.();
+        scope.stop();
+
+        // 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('the ref is shallow: the state object is replaced, never mutated', () => {
+        const { socket, client, scope, lastSub } = harness();
+        const state = scope.run(() => useLiveQuery(cardsList, undefined, { client }))!;
+        const first = state.value;
+
+        socket.onopen?.();
+        socket.deliver({ t: 'snapshot', sid: lastSub().sid, rev: 1, hash: 'h1', data: [] });
+
+        expect(state.value).not.toBe(first);
+        scope.stop();
+    });
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"],
+  "references": [
+    { "path": "../core" },
+    { "path": "../orm" },
+    { "path": "../websocket" }
+  ],
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "composite": true
+  }
+}