@carno.js/live 1.8.0

package/test/prefetch.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from 'bun:test';
+import { Controller, Get, Query } from '@carno.js/core';
+import { Live } from '../src/decorators/Live';
+import { ResourceRegistry } from '../src/resource/ResourceRegistry';
+import { prefetchLive } from '../src/resource/prefetch';
+import { hydrationKey, readHydrationPayload, toHydrateMap } from '../src/client/hydrate';
+import { storeKey } from '../src/client/core';
+import { fnv1a64 } from '../src/shared/hash';
+import { canonical } from '../src/shared/canonical';
+import { directResourceExecutor } from './resource-registry-helper';
+
+@Controller('/cards')
+class CardsController {
+    @Get('/')
+    @Live({ shared: 'public', key: 'id' })
+    list(@Query('done') done?: string) {
+        return done === 'true' ? [{ id: 2 }] : [{ id: 1 }, { id: 2 }];
+    }
+}
+
+function registry(): ResourceRegistry {
+    const instance = new ResourceRegistry();
+    instance.register(CardsController, new CardsController(), directResourceExecutor);
+    return instance;
+}
+
+describe('prefetchLive', () => {
+    test('returns the data and the hash the subscription will compare against', async () => {
+        const payload = await prefetchLive(registry(), 'CardsController.list');
+
+        expect(payload.data).toEqual([{ id: 1 }, { id: 2 }]);
+        expect(payload.hash).toBe(fnv1a64(canonical([{ id: 1 }, { id: 2 }])));
+        expect(payload.resourceId).toBe('CardsController.list');
+    });
+
+    test('passes the inputs to the handler', async () => {
+        const payload = await prefetchLive(registry(), 'CardsController.list', { query: { done: 'true' } });
+
+        expect(payload.data).toEqual([{ id: 2 }]);
+    });
+
+    test('normalises the inputs, so the key matches what the client will build', async () => {
+        const payload = await prefetchLive(registry(), 'CardsController.list');
+
+        expect(payload.inputs).toEqual({ params: {}, query: {}, body: undefined });
+        expect(hydrationKey(payload)).toBe(storeKey('CardsController.list', { params: {}, query: {} }));
+    });
+
+    test('refuses a resource that is not registered, naming it', async () => {
+        await expect(prefetchLive(registry(), 'Nope.thing')).rejects.toThrow(/Nope\.thing/);
+    });
+
+    test('does not register an instance anywhere', async () => {
+        // The whole point: a rendered page that nobody subscribes to must not
+        // leave a live instance behind being recomputed forever.
+        const resources = registry();
+        await prefetchLive(resources, 'CardsController.list');
+
+        expect(resources.ids()).toEqual(['CardsController.list']);
+    });
+});
+
+describe('toHydrateMap', () => {
+    test('keys payloads exactly the way LiveClient looks them up', async () => {
+        const resources = registry();
+        const payloads = [
+            await prefetchLive(resources, 'CardsController.list'),
+            await prefetchLive(resources, 'CardsController.list', { query: { done: 'true' } })
+        ];
+
+        const map = toHydrateMap(payloads);
+
+        expect(Object.keys(map).sort()).toEqual([
+            storeKey('CardsController.list', { params: {}, query: {} }),
+            storeKey('CardsController.list', { params: {}, query: { done: 'true' } })
+        ].sort());
+        expect(map[storeKey('CardsController.list', { params: {}, query: {} })].data).toEqual([{ id: 1 }, { id: 2 }]);
+    });
+
+    test('skips structurally invalid islands and keeps later payloads', () => {
+        const valid = {
+            resourceId: 'CardsController.list',
+            inputs: { params: {}, query: {} },
+            data: [{ id: 1 }],
+            hash: 'h1'
+        };
+        const root = {
+            querySelectorAll: () => [
+                { textContent: 'null' },
+                { textContent: '{}' },
+                { textContent: JSON.stringify({ ...valid, inputs: null }) },
+                { textContent: JSON.stringify(valid) }
+            ]
+        } as unknown as ParentNode;
+
+        expect(readHydrationPayload(root)).toEqual(toHydrateMap([valid]));
+    });
+});
+
+describe('hydration end to end', () => {
+    test('a hydrated client subscribes with the hash and never shows pending', async () => {
+        const { LiveClient } = await import('../src/client/core');
+        const payload = await prefetchLive(registry(), 'CardsController.list');
+
+        const sent: string[] = [];
+        const socket = {
+            sent,
+            send(data: string) { 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
+        };
+
+        const client = new LiveClient({
+            url: 'ws://x/live',
+            hydrate: toHydrateMap([payload]),
+            socketFactory: () => socket as any
+        });
+
+        const store = client.store('CardsController.list', { params: {}, query: {} });
+
+        expect(store.getSnapshot()).toEqual({
+            data: [{ id: 1 }, { id: 2 }],
+            pending: false,
+            error: null,
+            stale: false
+        });
+
+        store.subscribe(() => {});
+        socket.onopen?.();
+
+        const sub = JSON.parse(sent.find(raw => raw.includes('"t":"sub"'))!);
+        expect(sub.hash).toBe(payload.hash);
+    });
+});

package/test/react-adapter.test.tsx

@@ -0,0 +1,83 @@
+import { describe, expect, test } from 'bun:test';
+import { createElement } from 'react';
+import { renderToString } from 'react-dom/server';
+import { LiveClient, type LiveSocket } from '../src/client/core';
+import { LiveProvider, useLive } from '../src/client/react';
+
+function silentSocket(): LiveSocket {
+    return {
+        send() {},
+        close() {},
+        onopen: null,
+        onmessage: null,
+        onclose: null,
+        onerror: null
+    };
+}
+
+function clientWith(hydrate: Record<string, { data: unknown; hash: string }>): LiveClient {
+    return new LiveClient({ url: 'ws://test/live', hydrate, socketFactory: silentSocket });
+}
+
+describe('useLive', () => {
+    test('renders hydrated server state on the first pass, with no round trip', () => {
+        const client = clientWith({
+            'UsersController.list|{"body":null,"params":{},"query":{"status":"active"}}': {
+                data: [{ id: 1, name: 'Ada' }],
+                hash: 'h1'
+            }
+        });
+
+        function UserList() {
+            const { data, stale } = useLive<{ id: number; name: string }[]>(
+                'UsersController.list',
+                { query: { status: 'active' } }
+            );
+
+            return createElement(
+                'ul',
+                { 'data-stale': String(stale) },
+                (data ?? []).map(user => createElement('li', { key: user.id }, user.name))
+            );
+        }
+
+        const html = renderToString(
+            createElement(LiveProvider, { client }, createElement(UserList))
+        );
+
+        expect(html).toContain('Ada');
+        expect(html).toContain('data-stale="false"');
+    });
+
+    test('renders the pending state when nothing was hydrated', () => {
+        const client = clientWith({});
+
+        function Pending() {
+            const { pending } = useLive('UsersController.list');
+            return createElement('span', null, pending ? 'loading' : 'ready');
+        }
+
+        const html = renderToString(createElement(LiveProvider, { client }, createElement(Pending)));
+
+        expect(html).toContain('loading');
+    });
+
+    test('the same resource and inputs resolve to the same store instance', () => {
+        const client = clientWith({});
+        const a = client.store('r', { params: {}, query: { x: '1' } });
+        const b = client.store('r', { params: {}, query: { x: '1' } });
+        const c = client.store('r', { params: {}, query: { x: '2' } });
+
+        expect(a).toBe(b);
+        expect(a).not.toBe(c);
+    });
+
+    test('fails loudly outside a provider', () => {
+        function Orphan() {
+            useLive('r');
+            return null;
+        }
+
+        expect(() => renderToString(createElement(Orphan))).toThrow(/LiveProvider/);
+    });
+});

package/test/react-rerender.test.tsx

@@ -0,0 +1,131 @@
+import './happydom';
+import { afterEach, describe, expect, test } from 'bun:test';
+import { act, cleanup, render } from '@testing-library/react';
+import { createElement, useRef } from 'react';
+import { LiveClient, type LiveSocket } from '../src/client/core';
+import { LiveProvider, useLive } from '../src/client/react';
+
+/** A socket the test drives by hand: nothing is sent, everything is injected. */
+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;
+}
+
+afterEach(cleanup);
+
+describe('useLive re-rendering', () => {
+    test('a snapshot after mount re-renders the component with the new data', async () => {
+        const socket = fakeSocket();
+        const client = new LiveClient({ url: 'ws://x/live', socketFactory: () => socket });
+
+        function Cards() {
+            const { data, pending } = useLive<{ id: number }[]>('CardsController.list');
+            return createElement('div', { 'data-testid': 'out' }, pending ? 'pending' : String(data?.length ?? 0));
+        }
+
+        const screen = render(createElement(LiveProvider, { client }, createElement(Cards)));
+
+        expect(screen.getByTestId('out').textContent).toBe('pending');
+
+        await act(async () => {
+            socket.onopen?.();
+            socket.deliver({ t: 'snapshot', sid: 's0', rev: 1, hash: 'h1', data: [{ id: 1 }, { id: 2 }] });
+        });
+
+        expect(screen.getByTestId('out').textContent).toBe('2');
+    });
+
+    test('a message that establishes nothing new does not re-render', async () => {
+        const socket = fakeSocket();
+        const client = new LiveClient({ url: 'ws://x/live', socketFactory: () => socket });
+        let renders = 0;
+
+        function Cards() {
+            renders += 1;
+            const { data } = useLive<{ id: number }[]>('CardsController.list');
+            return createElement('div', { 'data-testid': 'out' }, String(data?.length ?? 0));
+        }
+
+        render(createElement(LiveProvider, { client }, createElement(Cards)));
+
+        await act(async () => {
+            socket.onopen?.();
+            socket.deliver({ t: 'snapshot', sid: 's0', rev: 1, hash: 'h1', data: [{ id: 1 }] });
+        });
+
+        const afterSnapshot = renders;
+
+        // Same data, same flags. The store has to keep the identical state
+        // object here, or useSyncExternalStore re-renders forever.
+        await act(async () => {
+            socket.deliver({ t: 'current', sid: 's0', rev: 1, hash: 'h1' });
+        });
+
+        expect(renders).toBe(afterSnapshot);
+    });
+
+    test('the data object stays referentially identical across a no-op message', async () => {
+        const socket = fakeSocket();
+        const client = new LiveClient({ url: 'ws://x/live', socketFactory: () => socket });
+        const seen: unknown[] = [];
+
+        function Cards() {
+            const { data } = useLive<{ id: number }[]>('CardsController.list');
+            const previous = useRef<unknown>(null);
+
+            if (data !== previous.current) {
+                previous.current = data;
+                seen.push(data);
+            }
+
+            return createElement('div', null, String(data?.length ?? 0));
+        }
+
+        render(createElement(LiveProvider, { client }, createElement(Cards)));
+
+        await act(async () => {
+            socket.onopen?.();
+            socket.deliver({ t: 'snapshot', sid: 's0', rev: 1, hash: 'h1', data: [{ id: 1 }] });
+            socket.deliver({ t: 'current', sid: 's0', rev: 1, hash: 'h1' });
+        });
+
+        // undefined at mount, then the array. A third entry would mean the
+        // store handed out a new object for content that did not change.
+        expect(seen.length).toBe(2);
+    });
+
+    test('unmounting releases the subscription after the grace period', async () => {
+        const socket = fakeSocket();
+        const client = new LiveClient({
+            url: 'ws://x/live',
+            socketFactory: () => socket,
+            unsubGraceMs: 1
+        });
+
+        function Cards() {
+            useLive('CardsController.list');
+            return null;
+        }
+
+        const screen = render(createElement(LiveProvider, { client }, createElement(Cards)));
+
+        await act(async () => { socket.onopen?.(); });
+
+        expect(socket.sent.some(raw => raw.includes('"t":"sub"'))).toBe(true);
+
+        screen.unmount();
+        await new Promise(resolve => setTimeout(resolve, 20));
+
+        expect(socket.sent.some(raw => raw.includes('"t":"unsub"'))).toBe(true);
+    });
+});

package/test/resource-registry-helper.ts

@@ -0,0 +1,35 @@
+import type { ParamMetadata } from '@carno.js/core';
+import type { LiveResourceExecutor } from '../src/resource/types';
+
+/** Test-only direct executor for ResourceRegistry unit tests. */
+export const directResourceExecutor: LiveResourceExecutor = async (
+    instance,
+    resource,
+    inputs
+) => instance[resource.handlerName](...buildArgs(resource.params, inputs));
+
+function buildArgs(params: ParamMetadata[], inputs: {
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    body?: unknown;
+}): unknown[] {
+    if (params.length === 0) {
+        return [];
+    }
+
+    const args = new Array<unknown>(Math.max(...params.map(param => param.index)) + 1).fill(undefined);
+
+    for (const param of params) {
+        if (param.type === 'param') {
+            args[param.index] = param.key ? inputs.params[param.key] : inputs.params;
+        } else if (param.type === 'query') {
+            args[param.index] = param.key ? inputs.query[param.key] : inputs.query;
+        } else if (param.type === 'body') {
+            args[param.index] = param.key
+                ? (inputs.body as Record<string, unknown> | undefined)?.[param.key]
+                : inputs.body;
+        }
+    }
+
+    return args;
+}

package/test/resource-registry.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, test } from 'bun:test';
+import { Controller, Ctx, Delete, Get, Param, Query, Req } from '@carno.js/core';
+import { Live } from '../src/decorators/Live';
+import { dependencyContext } from '../src/resource/dependency-context';
+import { LiveValidationError, ResourceRegistry } from '../src/resource/ResourceRegistry';
+import { directResourceExecutor } from './resource-registry-helper';
+
+@Controller('/users')
+class UsersController {
+    @Get('/')
+    @Live({ key: 'id' })
+    list(@Query('status') status: string) {
+        dependencyContext.current()?.add({ key: 'orm:users', columns: ['status'] });
+        return [{ id: 1, status }];
+    }
+
+    @Get('/:id')
+    @Live()
+    get(@Param('id') id: string) {
+        dependencyContext.current()?.add({ key: `orm:users#${id}`, columns: null });
+        return { id };
+    }
+}
+
+@Controller('/bad')
+class WritingController {
+    @Delete('/:id')
+    @Live()
+    remove(@Param('id') id: string) {
+        return { id };
+    }
+}
+
+@Controller('/bad2')
+class RequestController {
+    @Get('/')
+    @Live()
+    read(@Req() req: unknown, @Ctx() ctx: unknown) {
+        return { req, ctx };
+    }
+}
+
+describe('ResourceRegistry.register', () => {
+    test('registers every @Live handler under controller.handler', () => {
+        const registry = new ResourceRegistry();
+        registry.register(UsersController, new UsersController(), directResourceExecutor);
+
+        expect(registry.ids().sort()).toEqual(['UsersController.get', 'UsersController.list']);
+        expect(registry.get('UsersController.list')?.meta.key).toBe('id');
+    });
+
+    test('refuses @Live on a verb that is neither GET nor POST', () => {
+        const registry = new ResourceRegistry();
+
+        expect(() => registry.register(WritingController, new WritingController(), directResourceExecutor))
+            .toThrow(LiveValidationError);
+    });
+
+    test('refuses request-bound parameters that break recomputability', () => {
+        const registry = new ResourceRegistry();
+
+        expect(() => registry.register(RequestController, new RequestController(), directResourceExecutor))
+            .toThrow(/@Req\(\)/);
+    });
+
+    test('refuses two resources with the same id', () => {
+        const registry = new ResourceRegistry();
+        registry.register(UsersController, new UsersController(), directResourceExecutor);
+
+        expect(() => registry.register(UsersController, new UsersController(), directResourceExecutor))
+            .toThrow(/already registered/);
+    });
+});
+
+describe('ResourceRegistry.compute', () => {
+    test('resolves query and param arguments from inputs', async () => {
+        const registry = new ResourceRegistry();
+        registry.register(UsersController, new UsersController(), directResourceExecutor);
+
+        const list = await registry.compute(registry.get('UsersController.list')!, {
+            params: {},
+            query: { status: 'active' }
+        });
+        expect(list.data).toEqual([{ id: 1, status: 'active' }]);
+
+        const one = await registry.compute(registry.get('UsersController.get')!, {
+            params: { id: '42' },
+            query: {}
+        });
+        expect(one.data).toEqual({ id: '42' });
+    });
+
+    test('collects the dependencies registered during the compute', async () => {
+        const registry = new ResourceRegistry();
+        registry.register(UsersController, new UsersController(), directResourceExecutor);
+
+        const result = await registry.compute(registry.get('UsersController.get')!, {
+            params: { id: '42' },
+            query: {}
+        });
+
+        expect(result.deps).toEqual([{ key: 'orm:users#42', columns: null }]);
+    });
+
+    test('seeds the collector with the declared dependsOn keys', async () => {
+        @Controller('/reports')
+        class ReportsController {
+            @Get('/')
+            @Live({ dependsOn: ['app:report:current'] })
+            current() {
+                return { ok: true };
+            }
+        }
+
+        const registry = new ResourceRegistry();
+        registry.register(ReportsController, new ReportsController(), directResourceExecutor);
+
+        const result = await registry.compute(registry.get('ReportsController.current')!, {
+            params: {},
+            query: {}
+        });
+
+        expect(result.deps).toEqual([{ key: 'app:report:current', columns: null }]);
+    });
+
+    test('the collector is inactive outside a compute', () => {
+        expect(dependencyContext.isActive()).toBe(false);
+        expect(dependencyContext.current()).toBeUndefined();
+    });
+
+    test('concurrent computes do not mix dependencies', async () => {
+        const registry = new ResourceRegistry();
+        registry.register(UsersController, new UsersController(), directResourceExecutor);
+        const resource = registry.get('UsersController.get')!;
+
+        const [a, b] = await Promise.all([
+            registry.compute(resource, { params: { id: '1' }, query: {} }),
+            registry.compute(resource, { params: { id: '2' }, query: {} })
+        ]);
+
+        expect(a.deps).toEqual([{ key: 'orm:users#1', columns: null }]);
+        expect(b.deps).toEqual([{ key: 'orm:users#2', columns: null }]);
+    });
+});

package/test/route-pipeline.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { z } from 'zod';
+import {
+    Body,
+    Controller,
+    Get,
+    Post,
+    Schema,
+    Use,
+    type MiddlewareHandler
+} from '@carno.js/core';
+import { createTestHarness } from '@carno.js/core';
+import { closeLiveRuntime, Live, LivePlugin, LiveService } from '../src';
+
+let controllerCalls = 0;
+const pipelineSteps: string[] = [];
+
+const allowHeader: MiddlewareHandler = ctx => {
+    pipelineSteps.push('global');
+
+    if (ctx.headers.get('x-allow') !== 'yes') {
+        return new Response('forbidden', { status: 403 });
+    }
+};
+
+function nativeFetch(input: string, init?: RequestInit): Promise<Response> {
+    const fetchImpl = (globalThis as { __carnoNativeFetch?: typeof fetch }).__carnoNativeFetch ?? fetch;
+    return fetchImpl(input, init);
+}
+
+@Controller('/guarded')
+@Use(ctx => {
+    pipelineSteps.push('controller');
+    ctx.locals.controller = true;
+})
+class GuardedController {
+    @Get('/')
+    @Use(ctx => {
+        pipelineSteps.push('route');
+        ctx.locals.route = true;
+    })
+    @Live({ shared: 'public' })
+    read() {
+        pipelineSteps.push('handler');
+        controllerCalls += 1;
+        return { ok: true };
+    }
+}
+
+@Schema(z.object({ name: z.string().min(2) }))
+class GreetingDto {
+    name!: string;
+}
+
+@Controller('/greetings')
+class GreetingController {
+    @Post('/search')
+    @Live({ shared: 'public' })
+    search(@Body() dto: GreetingDto) {
+        controllerCalls += 1;
+        return { greeting: `Hello, ${dto.name}` };
+    }
+}
+
+afterEach(async () => {
+    controllerCalls = 0;
+    pipelineSteps.length = 0;
+    await closeLiveRuntime();
+});
+
+describe('Live route pipeline', () => {
+    test('prefetch executes middleware and fails closed without route credentials', async () => {
+        const harness = await createTestHarness({
+            plugins: [LivePlugin.create({
+                controllers: [GuardedController],
+                config: { coalesceMs: 1 }
+            })],
+            config: { globalMiddlewares: [allowHeader] },
+            listen: true
+        });
+
+        try {
+            const http = await nativeFetch(`http://127.0.0.1:${harness.port}/guarded`, {
+                headers: { 'x-allow': 'no' }
+            });
+            expect(http.status).toBe(403);
+
+            const live = harness.resolve(LiveService);
+            await expect(live.prefetch('GuardedController.read')).rejects.toThrow(/403|forbidden/i);
+            expect(controllerCalls).toBe(0);
+
+            pipelineSteps.length = 0;
+            const payload = await live.prefetch(
+                'GuardedController.read',
+                {},
+                { headers: { 'x-allow': 'yes' } }
+            );
+
+            expect(payload.data).toEqual({ ok: true });
+            expect(controllerCalls).toBe(1);
+            expect(pipelineSteps).toEqual(['global', 'controller', 'route', 'handler']);
+        } finally {
+            await harness.close();
+        }
+    });
+
+    test('prefetch applies the same DTO validation as the POST route', async () => {
+        const harness = await createTestHarness({
+            plugins: [LivePlugin.create({
+                controllers: [GreetingController],
+                config: { coalesceMs: 1 }
+            })],
+            config: { globalMiddlewares: [allowHeader] },
+            listen: true
+        });
+
+        try {
+            const http = await nativeFetch(`http://127.0.0.1:${harness.port}/greetings/search`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-allow': 'yes'
+                },
+                body: JSON.stringify({ name: 'A' })
+            });
+            expect(http.status).toBe(400);
+
+            const live = harness.resolve(LiveService);
+            await expect(live.prefetch(
+                'GreetingController.search',
+                { body: { name: 'A' } },
+                { headers: { 'x-allow': 'yes' } }
+            )).rejects.toThrow(/Validation failed/);
+            expect(controllerCalls).toBe(0);
+        } finally {
+            await harness.close();
+        }
+    });
+});