yaxa-svelte 2.4.0 → 2.6.0

package/dist/server/openapi/openapi.test.js

@@ -216,4 +216,17 @@ describe('createApiDocsHandler Endpoint', () => {
         expect(html).toContain('redoc.standalone.js');
         expect(html).toContain('redoc-container');
     });
+    it('allows overriding theme dynamically via ?theme query parameter', async () => {
+        const handler = createApiDocsHandler({
+            title: 'Dynamic Theme Test',
+            theme: 'scalar'
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/docs?theme=swagger'
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        const html = await response.text();
+        expect(html).toContain('swagger-ui-dist');
+    });
 });

package/dist/server/realtime/broadcaster.d.ts

@@ -0,0 +1,31 @@
+import type { Broadcaster, BroadcastSubscriber } from './types';
+/**
+ * In-memory channel broadcaster suitable for single-node deployments and local development.
+ * Supports zero external dependencies with complete error isolation across subscribers.
+ */
+export declare class MemoryBroadcaster implements Broadcaster {
+    private channels;
+    publish<T = unknown>(channel: string, event: string, payload: T, id?: string): void;
+    subscribe<T = unknown>(channel: string, subscriber: BroadcastSubscriber<T>): () => void;
+    unsubscribe<T = unknown>(channel: string, subscriber: BroadcastSubscriber<T>): void;
+    subscriberCount(channel: string): number;
+    clear(): void;
+}
+/**
+ * Global default broadcaster instance.
+ */
+export declare const globalBroadcaster: Broadcaster;
+/**
+ * Creates a broadcaster instance or wraps a custom adapter.
+ */
+export declare function createBroadcaster(customAdapter?: Broadcaster): Broadcaster;
+/**
+ * Broadcast an event to all connected clients on a channel.
+ * Callable from any endpoint, server action, webhook, or background worker.
+ *
+ * @example
+ * ```ts
+ * await broadcast(`org:${orgId}`, 'invoice.paid', { id: 'inv_123', total: 4900 });
+ * ```
+ */
+export declare function broadcast<T = unknown>(channel: string, event: string, payload: T, id?: string, broadcasterInstance?: Broadcaster): Promise<void>;

package/dist/server/realtime/broadcaster.js

@@ -0,0 +1,76 @@
+/**
+ * In-memory channel broadcaster suitable for single-node deployments and local development.
+ * Supports zero external dependencies with complete error isolation across subscribers.
+ */
+export class MemoryBroadcaster {
+    channels = new Map();
+    publish(channel, event, payload, id) {
+        const subscribers = this.channels.get(channel);
+        if (!subscribers || subscribers.size === 0) {
+            return;
+        }
+        const message = {
+            channel,
+            event,
+            payload,
+            id
+        };
+        // Isolate subscriber errors so one failure does not halt remaining subscribers
+        for (const subscriber of subscribers) {
+            try {
+                subscriber(message);
+            }
+            catch (err) {
+                console.error(`[Yaxa Broadcaster Error] Channel '${channel}', Event '${event}':`, err);
+            }
+        }
+    }
+    subscribe(channel, subscriber) {
+        let subscribers = this.channels.get(channel);
+        if (!subscribers) {
+            subscribers = new Set();
+            this.channels.set(channel, subscribers);
+        }
+        subscribers.add(subscriber);
+        return () => {
+            this.unsubscribe(channel, subscriber);
+        };
+    }
+    unsubscribe(channel, subscriber) {
+        const subscribers = this.channels.get(channel);
+        if (subscribers) {
+            subscribers.delete(subscriber);
+            if (subscribers.size === 0) {
+                this.channels.delete(channel);
+            }
+        }
+    }
+    subscriberCount(channel) {
+        return this.channels.get(channel)?.size ?? 0;
+    }
+    clear() {
+        this.channels.clear();
+    }
+}
+/**
+ * Global default broadcaster instance.
+ */
+export const globalBroadcaster = new MemoryBroadcaster();
+/**
+ * Creates a broadcaster instance or wraps a custom adapter.
+ */
+export function createBroadcaster(customAdapter) {
+    return customAdapter || new MemoryBroadcaster();
+}
+/**
+ * Broadcast an event to all connected clients on a channel.
+ * Callable from any endpoint, server action, webhook, or background worker.
+ *
+ * @example
+ * ```ts
+ * await broadcast(`org:${orgId}`, 'invoice.paid', { id: 'inv_123', total: 4900 });
+ * ```
+ */
+export async function broadcast(channel, event, payload, id, broadcasterInstance = globalBroadcaster) {
+    await broadcasterInstance.publish(channel, event, payload, id);
+}

package/dist/server/realtime/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './broadcaster';
+export * from './sse';

package/dist/server/realtime/index.js

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './broadcaster';
+export * from './sse';

package/dist/server/realtime/realtime.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/realtime/realtime.test.js

@@ -0,0 +1,210 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { formatSSEFrame, yaxaSSE } from './sse';
+import { MemoryBroadcaster, broadcast } from './broadcaster';
+import { requireAuth } from '../endpoint/guards';
+import { createMockRequestEvent } from '../../testing/index.js';
+describe('formatSSEFrame', () => {
+    it('formats simple text message without event name', () => {
+        const frame = formatSSEFrame({ data: 'hello world' });
+        expect(frame).toBe('data: hello world\n\n');
+    });
+    it('formats JSON object data and custom event name', () => {
+        const frame = formatSSEFrame({
+            event: 'order.created',
+            data: { id: 123, total: 49.99 }
+        });
+        expect(frame).toContain('event: order.created\n');
+        expect(frame).toContain('data: {"id":123,"total":49.99}\n\n');
+    });
+    it('includes id and retry fields when provided', () => {
+        const frame = formatSSEFrame({
+            id: 'evt_001',
+            event: 'status',
+            retry: 5000,
+            data: 'ok'
+        });
+        expect(frame).toContain('id: evt_001\n');
+        expect(frame).toContain('event: status\n');
+        expect(frame).toContain('retry: 5000\n');
+        expect(frame).toContain('data: ok\n\n');
+    });
+    it('splits multiline strings into multiple data lines per SSE spec', () => {
+        const multiline = 'line 1\nline 2\r\nline 3';
+        const frame = formatSSEFrame({ data: multiline });
+        expect(frame).toBe('data: line 1\ndata: line 2\ndata: line 3\n\n');
+    });
+});
+describe('MemoryBroadcaster Engine', () => {
+    let broadcaster;
+    beforeEach(() => {
+        broadcaster = new MemoryBroadcaster();
+    });
+    afterEach(() => {
+        broadcaster.clear();
+    });
+    it('dispatches published messages only to matching channel subscribers', () => {
+        const channel1Handler = vi.fn();
+        const channel2Handler = vi.fn();
+        broadcaster.subscribe('channel:1', channel1Handler);
+        broadcaster.subscribe('channel:2', channel2Handler);
+        broadcaster.publish('channel:1', 'ping', { test: true });
+        expect(channel1Handler).toHaveBeenCalledTimes(1);
+        expect(channel1Handler).toHaveBeenCalledWith({
+            channel: 'channel:1',
+            event: 'ping',
+            payload: { test: true },
+            id: undefined
+        });
+        expect(channel2Handler).not.toHaveBeenCalled();
+    });
+    it('unsubscribes cleanly using returned cleanup function', () => {
+        const handler = vi.fn();
+        const unsubscribe = broadcaster.subscribe('room:lobby', handler);
+        expect(broadcaster.subscriberCount('room:lobby')).toBe(1);
+        broadcaster.publish('room:lobby', 'msg', 'first');
+        expect(handler).toHaveBeenCalledTimes(1);
+        unsubscribe();
+        expect(broadcaster.subscriberCount('room:lobby')).toBe(0);
+        broadcaster.publish('room:lobby', 'msg', 'second');
+        expect(handler).toHaveBeenCalledTimes(1);
+    });
+    it('isolates subscriber errors without halting other subscribers', () => {
+        const failingSubscriber = vi.fn(() => {
+            throw new Error('Subscriber crashed');
+        });
+        const healthySubscriber = vi.fn();
+        const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        broadcaster.subscribe('alerts', failingSubscriber);
+        broadcaster.subscribe('alerts', healthySubscriber);
+        broadcaster.publish('alerts', 'danger', { level: 'high' });
+        expect(failingSubscriber).toHaveBeenCalledTimes(1);
+        expect(healthySubscriber).toHaveBeenCalledTimes(1);
+        expect(consoleSpy).toHaveBeenCalled();
+        consoleSpy.mockRestore();
+    });
+});
+describe('yaxaSSE Server Handler', () => {
+    let broadcaster;
+    beforeEach(() => {
+        broadcaster = new MemoryBroadcaster();
+    });
+    afterEach(() => {
+        broadcaster.clear();
+    });
+    it('sets standard SSE response headers', async () => {
+        const handler = yaxaSSE({ broadcaster, keepAliveIntervalMs: 0 });
+        const event = createMockRequestEvent({ url: 'http://localhost:5173/api/events' });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-type')).toBe('text/event-stream; charset=utf-8');
+        expect(response.headers.get('cache-control')).toBe('no-cache, no-transform');
+        expect(response.headers.get('connection')).toBe('keep-alive');
+        expect(response.headers.get('x-accel-buffering')).toBe('no');
+        expect(response.body).toBeInstanceOf(ReadableStream);
+    });
+    it('evaluates declarative guards and blocks unauthenticated requests with 401 Problem Details', async () => {
+        const handler = yaxaSSE({
+            guards: [requireAuth()],
+            broadcaster
+        });
+        // Event without authenticated user
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/events',
+            locals: {}
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(401);
+        expect(response.headers.get('content-type')).toContain('application/problem+json');
+        const body = await response.json();
+        expect(body.title).toContain('Unauthorized');
+    });
+    it('invokes onConnect and delivers messages through client send', async () => {
+        let onConnectCalled = false;
+        const handler = yaxaSSE({
+            broadcaster,
+            keepAliveIntervalMs: 0,
+            channel: 'dashboard',
+            onConnect: ({ send }) => {
+                onConnectCalled = true;
+                send('welcome', { initialized: true });
+            }
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/events',
+            locals: { user: { id: 'usr_123', email: 'alex@example.com' } }
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        const { value } = await reader.read();
+        const text = decoder.decode(value);
+        expect(onConnectCalled).toBe(true);
+        expect(text).toContain('event: welcome\n');
+        expect(text).toContain('data: {"initialized":true}\n\n');
+        await reader.cancel();
+    });
+    it('receives events published via broadcast() helper', async () => {
+        const handler = yaxaSSE({
+            broadcaster,
+            keepAliveIntervalMs: 0,
+            channel: 'tenant:acme'
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/events'
+        });
+        const response = await handler(event);
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        // Broadcast an event on the channel
+        await broadcast('tenant:acme', 'kpi.updated', { value: 99.4 }, undefined, broadcaster);
+        const { value } = await reader.read();
+        const text = decoder.decode(value);
+        expect(text).toContain('event: kpi.updated\n');
+        expect(text).toContain('data: {"value":99.4}\n\n');
+        await reader.cancel();
+    });
+    it('resolves dynamic channel from RequestEvent', async () => {
+        const handler = yaxaSSE({
+            broadcaster,
+            keepAliveIntervalMs: 0,
+            channel: (evt) => `user:${evt.locals.user.id}`
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/events',
+            locals: { user: { id: 'usr_abc' } }
+        });
+        const response = await handler(event);
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        // Broadcast to matching dynamic channel
+        await broadcast('user:usr_abc', 'notification', { msg: 'Test' }, undefined, broadcaster);
+        const { value } = await reader.read();
+        const text = decoder.decode(value);
+        expect(text).toContain('event: notification\n');
+        expect(text).toContain('data: {"msg":"Test"}\n\n');
+        await reader.cancel();
+    });
+    it('invokes onDisconnect when stream is cancelled or client aborts', async () => {
+        let disconnected = false;
+        const abortController = new AbortController();
+        const handler = yaxaSSE({
+            broadcaster,
+            keepAliveIntervalMs: 0,
+            channel: 'session',
+            onDisconnect: () => {
+                disconnected = true;
+            }
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/events',
+            signal: abortController.signal
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        // Trigger stream cancel
+        const reader = response.body.getReader();
+        await reader.cancel();
+        expect(disconnected).toBe(true);
+    });
+});

package/dist/server/realtime/sse.d.ts

@@ -0,0 +1,28 @@
+import type { RequestHandler } from '@sveltejs/kit';
+import type { SSEMessage, YaxaSSEOptions } from './types';
+/**
+ * Formats a payload into a valid Server-Sent Events text frame.
+ */
+export declare function formatSSEFrame<T = unknown>(message: SSEMessage<T>): string;
+/**
+ * Creates a turnkey SvelteKit Server-Sent Events (SSE) RequestHandler with
+ * guard evaluation, automatic keep-alive pings, and channel broadcasting.
+ *
+ * @example
+ * ```ts
+ * // src/routes/api/events/+server.ts
+ * import { yaxaSSE, requireAuth } from 'yaxa-svelte/server';
+ *
+ * export const GET = yaxaSSE({
+ *   guards: [requireAuth()],
+ *   channel: (event) => `org:${event.locals.orgId}`,
+ *   keepAliveIntervalMs: 15000,
+ *   onConnect: ({ send }) => {
+ *     send('welcome', { time: Date.now() });
+ *   }
+ * });
+ * ```
+ */
+export declare function yaxaSSE(options?: YaxaSSEOptions): RequestHandler & {
+    _yaxaConfig: any;
+};

package/dist/server/realtime/sse.js

@@ -0,0 +1,225 @@
+import { globalBroadcaster } from './broadcaster';
+import { problemResponse } from '../endpoint/problem';
+/**
+ * Formats a payload into a valid Server-Sent Events text frame.
+ */
+export function formatSSEFrame(message) {
+    let output = '';
+    if (message.id !== undefined) {
+        output += `id: ${message.id}\n`;
+    }
+    if (message.event !== undefined) {
+        output += `event: ${message.event}\n`;
+    }
+    if (message.retry !== undefined) {
+        output += `retry: ${message.retry}\n`;
+    }
+    const dataStr = typeof message.data === 'object' && message.data !== null
+        ? JSON.stringify(message.data)
+        : String(message.data ?? '');
+    // SSE specification requires multiple 'data: ' lines if data contains newlines
+    const lines = dataStr.split(/\r\n|\r|\n/);
+    for (const line of lines) {
+        output += `data: ${line}\n`;
+    }
+    output += '\n';
+    return output;
+}
+/**
+ * Creates a turnkey SvelteKit Server-Sent Events (SSE) RequestHandler with
+ * guard evaluation, automatic keep-alive pings, and channel broadcasting.
+ *
+ * @example
+ * ```ts
+ * // src/routes/api/events/+server.ts
+ * import { yaxaSSE, requireAuth } from 'yaxa-svelte/server';
+ *
+ * export const GET = yaxaSSE({
+ *   guards: [requireAuth()],
+ *   channel: (event) => `org:${event.locals.orgId}`,
+ *   keepAliveIntervalMs: 15000,
+ *   onConnect: ({ send }) => {
+ *     send('welcome', { time: Date.now() });
+ *   }
+ * });
+ * ```
+ */
+export function yaxaSSE(options = {}) {
+    const keepAliveIntervalMs = options.keepAliveIntervalMs ?? 15_000;
+    const keepAliveComment = options.keepAliveComment ?? ': ping\n\n';
+    const broadcaster = options.broadcaster ?? globalBroadcaster;
+    const sseHandler = async (event) => {
+        const { request, locals } = event;
+        // 1. Evaluate guards if configured
+        if (options.guards && options.guards.length > 0) {
+            for (const guard of options.guards) {
+                const result = await guard(event);
+                if (result instanceof Response) {
+                    return result;
+                }
+                if (result && typeof result === 'object' && 'status' in result && 'title' in result) {
+                    return problemResponse(result);
+                }
+                if (result === false) {
+                    return problemResponse({
+                        status: 403,
+                        title: 'Forbidden',
+                        detail: 'Access denied by endpoint guard.'
+                    });
+                }
+            }
+        }
+        // 2. Resolve target channel
+        let channel = 'default';
+        if (typeof options.channel === 'function') {
+            channel = await options.channel(event);
+        }
+        else if (typeof options.channel === 'string' && options.channel.length > 0) {
+            channel = options.channel;
+        }
+        const user = locals?.user ?? null;
+        const orgId = locals?.orgId ?? locals?.org?.id ?? null;
+        const connectionId = `sse_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+        const encoder = new TextEncoder();
+        let unsubscribe = null;
+        let pingTimer = null;
+        let isClosed = false;
+        let clientCloseFn = null;
+        const stream = new ReadableStream({
+            start(controller) {
+                const safeEnqueue = (text) => {
+                    if (isClosed)
+                        return false;
+                    try {
+                        controller.enqueue(encoder.encode(text));
+                        return true;
+                    }
+                    catch {
+                        isClosed = true;
+                        return false;
+                    }
+                };
+                const clientSend = (eventOrMessage, data) => {
+                    if (isClosed)
+                        return false;
+                    let msg;
+                    if (typeof eventOrMessage === 'string') {
+                        msg = { event: eventOrMessage, data: data };
+                    }
+                    else {
+                        msg = eventOrMessage;
+                    }
+                    return safeEnqueue(formatSSEFrame(msg));
+                };
+                const clientClose = () => {
+                    if (isClosed)
+                        return;
+                    isClosed = true;
+                    if (pingTimer) {
+                        clearInterval(pingTimer);
+                        pingTimer = null;
+                    }
+                    if (unsubscribe) {
+                        unsubscribe();
+                        unsubscribe = null;
+                    }
+                    try {
+                        controller.close();
+                    }
+                    catch {
+                        // Stream might already be closed by client
+                    }
+                    if (options.onDisconnect) {
+                        Promise.resolve(options.onDisconnect({
+                            connectionId,
+                            channel,
+                            event,
+                            user,
+                            orgId
+                        })).catch((err) => {
+                            console.error('[Yaxa SSE onDisconnect Error]:', err);
+                        });
+                    }
+                };
+                clientCloseFn = clientClose;
+                // Subscribe client to channel broadcast events
+                unsubscribe = broadcaster.subscribe(channel, (msg) => {
+                    clientSend({
+                        event: msg.event,
+                        data: msg.payload,
+                        id: msg.id
+                    });
+                });
+                // Heartbeat loop to keep connections open through proxies/firewalls
+                if (keepAliveIntervalMs > 0) {
+                    pingTimer = setInterval(() => {
+                        safeEnqueue(keepAliveComment);
+                    }, keepAliveIntervalMs);
+                }
+                // Abort handling when client closes connection or navigates away
+                if (request.signal) {
+                    request.signal.addEventListener('abort', clientClose, { once: true });
+                }
+                // Context provided to onConnect
+                const clientContext = {
+                    connectionId,
+                    channel,
+                    event,
+                    user,
+                    orgId,
+                    send: clientSend,
+                    close: clientClose
+                };
+                // Invoke onConnect callback
+                if (options.onConnect) {
+                    Promise.resolve(options.onConnect(clientContext)).catch((err) => {
+                        console.error('[Yaxa SSE onConnect Error]:', err);
+                    });
+                }
+            },
+            cancel() {
+                if (clientCloseFn) {
+                    clientCloseFn();
+                }
+                else {
+                    isClosed = true;
+                    if (pingTimer) {
+                        clearInterval(pingTimer);
+                        pingTimer = null;
+                    }
+                    if (unsubscribe) {
+                        unsubscribe();
+                        unsubscribe = null;
+                    }
+                }
+            }
+        });
+        return new Response(stream, {
+            status: 200,
+            headers: {
+                'content-type': 'text/event-stream; charset=utf-8',
+                'cache-control': 'no-cache, no-transform',
+                connection: 'keep-alive',
+                'x-accel-buffering': 'no'
+            }
+        });
+    };
+    sseHandler._yaxaConfig = {
+        summary: options.summary || 'Server-Sent Events Stream',
+        description: options.description ||
+            'Real-time Server-Sent Events stream with multi-channel pub/sub and keep-alive heartbeats.',
+        guards: options.guards,
+        status: 200,
+        responses: {
+            '200': {
+                description: 'Active event stream',
+                content: {
+                    'text/event-stream': {
+                        schema: { type: 'string' }
+                    }
+                }
+            }
+        }
+    };
+    return sseHandler;
+}