yaxa-svelte 2.3.0 → 2.5.0

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;
+}

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

@@ -0,0 +1,116 @@
+import type { RequestEvent } from '@sveltejs/kit';
+import type { Guard } from '../endpoint/types';
+/**
+ * Structured Server-Sent Event message payload.
+ */
+export interface SSEMessage<T = unknown> {
+    /** Optional unique event ID for client Last-Event-ID tracking */
+    id?: string;
+    /** Optional named event type (defaults to 'message') */
+    event?: string;
+    /** Payload data to transmit. Objects/arrays are JSON-encoded automatically */
+    data: T;
+    /** Optional reconnection delay in milliseconds suggested to the client */
+    retry?: number;
+}
+/**
+ * Context provided to onConnect and event callbacks.
+ */
+export interface SSEClientContext {
+    /** Unique connection ID */
+    connectionId: string;
+    /** Active channel name */
+    channel: string;
+    /** The incoming SvelteKit RequestEvent */
+    event: RequestEvent;
+    /** Resolved user from guards/locals */
+    user?: any;
+    /** Active organization ID from guards/locals */
+    orgId?: string | null;
+    /** Send an SSE message directly to this client */
+    send: <T = unknown>(eventOrMessage: string | SSEMessage<T>, data?: T) => boolean;
+    /** Explicitly close this SSE connection */
+    close: () => void;
+}
+/**
+ * Configuration options for yaxaSSE endpoint handler.
+ */
+export interface YaxaSSEOptions {
+    /** Summary for OpenAPI documentation */
+    summary?: string;
+    /** Description for OpenAPI documentation */
+    description?: string;
+    /**
+     * Declarative guards executed before establishing the SSE connection.
+     * If a guard fails, an RFC 7807 Problem Details response (e.g. 401, 403, 429) is returned.
+     */
+    guards?: Guard[];
+    /**
+     * Channel name to subscribe this client to. Can be a static string or a dynamic function
+     * of the incoming RequestEvent (e.g. `(event) => \`org:\${event.locals.orgId}\``).
+     * Defaults to `'default'`.
+     */
+    channel?: string | ((event: RequestEvent) => string | Promise<string>);
+    /**
+     * Keep-alive ping interval in milliseconds to prevent reverse proxies, firewalls,
+     * and serverless platforms (e.g. Vercel) from terminating idle connections.
+     * Set to 0 to disable. Defaults to 15,000ms (15s).
+     */
+    keepAliveIntervalMs?: number;
+    /**
+     * Custom comment or payload for keep-alive pings.
+     * Defaults to `: ping\n\n`.
+     */
+    keepAliveComment?: string;
+    /**
+     * Hook called immediately after connection establishment and headers transmission.
+     */
+    onConnect?: (ctx: SSEClientContext) => void | Promise<void>;
+    /**
+     * Hook called when the client disconnects or the request is aborted.
+     */
+    onDisconnect?: (ctx: Omit<SSEClientContext, 'send' | 'close'>) => void | Promise<void>;
+    /**
+     * Custom broadcaster instance. If omitted, uses the global broadcaster singleton.
+     */
+    broadcaster?: Broadcaster;
+}
+/**
+ * Broadcast message contract.
+ */
+export interface BroadcastMessage<T = unknown> {
+    channel: string;
+    event: string;
+    payload: T;
+    id?: string;
+}
+/**
+ * Broadcaster subscription callback.
+ */
+export type BroadcastSubscriber<T = unknown> = (msg: BroadcastMessage<T>) => void;
+/**
+ * Broadcaster adapter interface.
+ * Can be implemented by MemoryBroadcaster, RedisBroadcaster, ValkeyBroadcaster, etc.
+ */
+export interface Broadcaster {
+    /**
+     * Publish an event to all subscribers listening on the specified channel.
+     */
+    publish: <T = unknown>(channel: string, event: string, payload: T, id?: string) => Promise<void> | void;
+    /**
+     * Subscribe to events on a specific channel. Returns an unsubscribe function.
+     */
+    subscribe: <T = unknown>(channel: string, subscriber: BroadcastSubscriber<T>) => () => void;
+    /**
+     * Unsubscribe a callback from a channel.
+     */
+    unsubscribe: <T = unknown>(channel: string, subscriber: BroadcastSubscriber<T>) => void;
+    /**
+     * Returns current number of active subscribers on a channel (optional).
+     */
+    subscriberCount?: (channel: string) => number;
+    /**
+     * Remove all subscribers across all channels.
+     */
+    clear?: () => void;
+}

package/dist/server/realtime/types.js

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

package/dist/testing/index.d.ts

@@ -85,6 +85,8 @@ export interface MockRequestEventOptions {
     params?: Record<string, string>;
     locals?: Record<string, any>;
     cookies?: Record<string, string>;
+    signal?: AbortSignal;
+    request?: Request;
 }
 /**
  * Creates a mocked typed SvelteKit RequestEvent for unit testing endpoints and server hooks.

package/dist/testing/index.js

@@ -124,11 +124,13 @@ export function createMockRequestEvent(options = {}) {
             }
         }
     }
-    const request = new Request(url.toString(), {
-        method,
-        headers,
-        body: method !== 'GET' && method !== 'HEAD' ? bodyContent : undefined
-    });
+    const request = options.request ||
+        new Request(url.toString(), {
+            method,
+            headers,
+            body: method !== 'GET' && method !== 'HEAD' ? bodyContent : undefined,
+            signal: options.signal
+        });
     const cookieStore = new Map(Object.entries(options.cookies || {}));
     const cookies = {
         get: (name) => cookieStore.get(name),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaxa-svelte",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "The Intuitive Svelte UI Library — Nuxt UI v4 equivalent for SvelteKit 2 & 3 & Svelte 5 with automated SEO, dynamic OpenGraph cards, sitemaps, robots.txt, and Tailwind CSS v4.",
   "license": "MIT",
   "homepage": "https://yaxa.vercel.app",