yaxa-svelte 2.3.0 → 2.5.0

package/README.md

@@ -295,27 +295,119 @@ export const GET = createApiDocsHandler({
 });
 ```
 
-- **Interactive Reference UI:** Open `/api/docs` in your browser.
+- **Interactive Reference UI:** Open `/api/docs` in your browser (supports `?theme=scalar` (default), `?theme=swagger`, or `?theme=redoc`).
+- **Live Demo:** Try it live on [yaxa.vercel.app/api/docs](https://yaxa.vercel.app/api/docs).
 - **Raw OpenAPI 3.1 JSON:** Request `/api/docs?format=json` or send `Accept: application/json` for SDK generation.
 
 ---
 
+## ⏱️ Embedded Background Workflows & Persistent Job Queue
+
+Persistent, zero-infrastructure background task processing backed by your existing Drizzle database (Postgres or SQLite/Turso). Features atomic row leasing, exponential retry backoff with jitter, Dead-Letter Queue (DLQ), and dual execution models (Serverless Cron or long-running worker):
+
+```ts
+import { enqueueJob, defineWorker, createJobRunner, eventBus } from 'yaxa-svelte/server';
+
+// 1. Decoupled domain events
+eventBus.on('user.created', async ({ userId, email }) => {
+	// 2. Enqueue background job (optionally pass active transaction { tx } for transactional outbox)
+	await enqueueJob(
+		'send-welcome-email',
+		{ userId, email },
+		{
+			delay: '5m', // '30s', '5m', '2h', or ms
+			priority: 10,
+			maxAttempts: 5
+		}
+	);
+});
+
+// 3. Define worker
+const emailWorker = defineWorker({
+	name: 'send-welcome-email',
+	handler: async (payload, { attempt, log }) => {
+		log(`Sending welcome email (attempt ${attempt})`);
+		await sendEmail(payload.email);
+	}
+});
+
+// 4. Run in Serverless Cron (Vercel Cron) or background container
+export const runner = createJobRunner({
+	workers: [emailWorker],
+	batchSize: 10
+});
+
+// In src/routes/api/cron/jobs/+server.ts:
+export const GET = async () => {
+	const result = await runner.processNextBatch();
+	return Response.json(result);
+};
+```
+
+---
+
+## 📡 Real-Time Server-Sent Events (`yaxaSSE`, `broadcast`, & `useSSE`)
+
+Zero-infrastructure real-time communication across serverless and Node.js without third-party subscriptions. Features declarative SSE streaming, automatic keep-alive heartbeats, multi-channel pub/sub broadcasting, and a reactive Svelte 5 client rune with exponential reconnect backoff:
+
+```ts
+// 1. Server-Sent Events Endpoint (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, // Heartbeat ping prevents proxy & Vercel timeouts
+	onConnect: ({ send, user }) => {
+		send('connected', { userId: user.id });
+	}
+});
+
+// 2. Publish from anywhere (Endpoints, Webhooks, Background Workers)
+import { broadcast } from 'yaxa-svelte/server';
+
+await broadcast(`org:${orgId}`, 'invoice.settled', {
+	invoiceId: 'inv_4982',
+	amount: 29.0
+});
+```
+
+```svelte
+<!-- 3. Reactive Svelte 5 Client Rune -->
+<script lang="ts">
+	import { useSSE } from 'yaxa-svelte';
+
+	const stream = useSSE('/api/events');
+
+	// Typed event listeners with automatic cleanup
+	stream.on('invoice.settled', (data) => {
+		toast.success(`Payment settled: $${data.amount}`);
+	});
+</script>
+
+<Badge color={stream.connected ? 'success' : 'neutral'}>
+	{stream.connected ? 'Live Stream' : 'Connecting...'}
+</Badge>
+```
+
+---
+
 ## 📦 Subpath Exports Architecture
 
-| Subpath                 | Description                                                                                                                                                  |
-| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `yaxa-svelte`           | Core UI Primitives, SEO Components, `<Gate />`, Theme System & Composables (`useGate`, `useUpload`, `useToast`, `useClipboard`, etc.)                        |
-| `yaxa-svelte/admin`     | Drizzle ORM Schema Introspection, `<AdminDashboard />`, `createYaxaAdminHook`, `createDrizzleAdmin`, `<DevSandbox />`, `<RecordDrawer />`                    |
-| `yaxa-svelte/server`    | `yaxaEndpoint` Pipeline, Declarative Guards, OpenAPI 3.1 & Scalar/Swagger Docs, RFC 7807, Universal Server Hooks, SEO endpoints, Drizzle DB, Storage & Email |
-| `yaxa-svelte/auth`      | Better-Auth client & server integration (`useAuth`, `<AuthCard />`, `<PasskeyUI />`, `<TwoFactorModal />`, `createYaxaAuth`)                                 |
-| `yaxa-svelte/db`        | Multi-dialect Drizzle ORM clients & schemas for Neon (PostgreSQL) and Turso (SQLite/LibSQL)                                                                  |
-| `yaxa-svelte/polar`     | Polar.sh billing, customer portal sessions, and webhook synchronization                                                                                      |
-| `yaxa-svelte/email`     | Resend transactional email templates with automatic development console fallback                                                                             |
-| `yaxa-svelte/storage`   | AWS S3 and Cloudflare R2 presigned upload URL generators                                                                                                     |
-| `yaxa-svelte/testing`   | Test mocks & utilities (`createMockSiteConfig`, `createMockUser`, `createTestWrapperProps`)                                                                  |
-| `yaxa-svelte/vite`      | Turnkey Vite plugin (`yaxa()`)                                                                                                                               |
-| `yaxa-svelte/yaxa.css`  | Standalone turnkey Tailwind CSS v4 stylesheet with base styling, `@theme`, and scrollbars                                                                    |
-| `yaxa-svelte/theme.css` | Pure Tailwind CSS v4 design tokens, `:root` variables, and harmonic radius scale without `@import 'tailwindcss'`                                             |
+| Subpath                 | Description                                                                                                                                                                                                                |
+| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `yaxa-svelte`           | Core UI Primitives, SEO Components, `<Gate />`, Theme System & Composables (`useGate`, `useUpload`, `useSSE`, `useToast`, `useClipboard`, etc.)                                                                            |
+| `yaxa-svelte/admin`     | Drizzle ORM Schema Introspection, `<AdminDashboard />`, `createYaxaAdminHook`, `createDrizzleAdmin`, `<DevSandbox />`, `<RecordDrawer />`                                                                                  |
+| `yaxa-svelte/server`    | `yaxaEndpoint` Pipeline, Declarative Guards, OpenAPI 3.1 & Scalar Docs, RFC 7807, Real-Time SSE (`yaxaSSE`, `broadcast`), Background Jobs (`enqueueJob`, `createJobRunner`), `eventBus`, Server Hooks, DB, Storage & Email |
+| `yaxa-svelte/auth`      | Better-Auth client & server integration (`useAuth`, `<AuthCard />`, `<PasskeyUI />`, `<TwoFactorModal />`, `createYaxaAuth`)                                                                                               |
+| `yaxa-svelte/db`        | Multi-dialect Drizzle ORM clients & schemas for Neon (PostgreSQL) and Turso (SQLite/LibSQL)                                                                                                                                |
+| `yaxa-svelte/polar`     | Polar.sh billing, customer portal sessions, and webhook synchronization                                                                                                                                                    |
+| `yaxa-svelte/email`     | Resend transactional email templates with automatic development console fallback                                                                                                                                           |
+| `yaxa-svelte/storage`   | AWS S3 and Cloudflare R2 presigned upload URL generators                                                                                                                                                                   |
+| `yaxa-svelte/testing`   | Test mocks & utilities (`createMockSiteConfig`, `createMockUser`, `createTestWrapperProps`)                                                                                                                                |
+| `yaxa-svelte/vite`      | Turnkey Vite plugin (`yaxa()`)                                                                                                                                                                                             |
+| `yaxa-svelte/yaxa.css`  | Standalone turnkey Tailwind CSS v4 stylesheet with base styling, `@theme`, and scrollbars                                                                                                                                  |
+| `yaxa-svelte/theme.css` | Pure Tailwind CSS v4 design tokens, `:root` variables, and harmonic radius scale without `@import 'tailwindcss'`                                                                                                           |
 
 ---
 

package/dist/composables/useSSE.svelte.d.ts

@@ -0,0 +1,53 @@
+export type SSEStatus = 'idle' | 'connecting' | 'connected' | 'error' | 'closed';
+export interface UseSSEOptions {
+    /** Whether the SSE connection is active (defaults to true) */
+    enabled?: boolean;
+    /** Whether to send credentials/cookies with cross-origin requests */
+    withCredentials?: boolean;
+    /** Enable automatic reconnection on disconnect/error (defaults to true) */
+    autoReconnect?: boolean;
+    /** Maximum reconnection attempts before stopping (defaults to 10) */
+    maxRetries?: number;
+    /** Base reconnect delay in ms before exponential backoff (defaults to 1,000ms) */
+    baseDelayMs?: number;
+    /** Maximum delay between reconnect attempts in ms (defaults to 30,000ms) */
+    maxDelayMs?: number;
+    /** Callback invoked when the connection opens */
+    onOpen?: () => void;
+    /** Callback invoked on error */
+    onError?: (err: Event) => void;
+    /** Callback invoked when any message is received */
+    onMessage?: (data: any, event: MessageEvent) => void;
+}
+export type SSEEventHandler<T = any> = (data: T, event: MessageEvent) => void;
+export interface SSEResult {
+    readonly status: SSEStatus;
+    readonly connected: boolean;
+    readonly connecting: boolean;
+    readonly data: any;
+    readonly lastEvent: string | null;
+    readonly error: any;
+    on: <T = any>(event: string, handler: SSEEventHandler<T>) => () => void;
+    close: () => void;
+    reconnect: () => void;
+}
+/**
+ * Idiomatic Svelte 5 Composable Rune for Server-Sent Events (SSE).
+ * Provides automatic reconnect with jitter, typed event subscribers, and automatic teardown.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useSSE } from 'yaxa-svelte';
+ *
+ *   const stream = useSSE('/api/events');
+ *
+ *   stream.on('order.created', (order) => {
+ *     console.log('New order received:', order);
+ *   });
+ * </script>
+ *
+ * <p>Status: {stream.connected ? 'Live' : 'Connecting...'}</p>
+ * ```
+ */
+export declare function useSSE(url: string | (() => string), options?: UseSSEOptions): SSEResult;

package/dist/composables/useSSE.svelte.js

@@ -0,0 +1,209 @@
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+/**
+ * Idiomatic Svelte 5 Composable Rune for Server-Sent Events (SSE).
+ * Provides automatic reconnect with jitter, typed event subscribers, and automatic teardown.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useSSE } from 'yaxa-svelte';
+ *
+ *   const stream = useSSE('/api/events');
+ *
+ *   stream.on('order.created', (order) => {
+ *     console.log('New order received:', order);
+ *   });
+ * </script>
+ *
+ * <p>Status: {stream.connected ? 'Live' : 'Connecting...'}</p>
+ * ```
+ */
+export function useSSE(url, options = {}) {
+    const { enabled = true, withCredentials = false, autoReconnect = true, maxRetries = 10, baseDelayMs = 1000, maxDelayMs = 30000, onOpen, onError, onMessage } = options;
+    let status = $state('idle');
+    let data = $state(null);
+    let lastEvent = $state(null);
+    let error = $state(null);
+    const connected = $derived(status === 'connected');
+    const connecting = $derived(status === 'connecting');
+    const listeners = new SvelteMap();
+    let es = null;
+    let reconnectTimer = null;
+    let retryCount = 0;
+    let manualClose = false;
+    function parseEventData(raw) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+    function dispatchToListeners(eventType, parsed, rawEvent) {
+        const handlers = listeners.get(eventType);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(parsed, rawEvent);
+                }
+                catch (err) {
+                    console.error(`[useSSE Handler Error] Event '${eventType}':`, err);
+                }
+            }
+        }
+    }
+    function cleanupConnection() {
+        if (reconnectTimer) {
+            clearTimeout(reconnectTimer);
+            reconnectTimer = null;
+        }
+        if (es) {
+            es.close();
+            es = null;
+        }
+    }
+    function scheduleReconnect(targetUrl) {
+        if (manualClose || !autoReconnect || retryCount >= maxRetries) {
+            status = 'closed';
+            return;
+        }
+        // Exponential backoff with jitter
+        const delay = Math.min(maxDelayMs, baseDelayMs * Math.pow(1.5, retryCount) + Math.random() * 500);
+        retryCount++;
+        status = 'connecting';
+        reconnectTimer = setTimeout(() => {
+            connect(targetUrl);
+        }, delay);
+    }
+    function connect(targetUrl) {
+        cleanupConnection();
+        if (typeof window === 'undefined' || typeof EventSource === 'undefined') {
+            status = 'idle';
+            return;
+        }
+        status = 'connecting';
+        manualClose = false;
+        try {
+            const source = new EventSource(targetUrl, { withCredentials });
+            es = source;
+            source.onopen = () => {
+                status = 'connected';
+                retryCount = 0;
+                error = null;
+                onOpen?.();
+            };
+            source.onmessage = (event) => {
+                const parsed = parseEventData(event.data);
+                data = parsed;
+                lastEvent = 'message';
+                onMessage?.(parsed, event);
+                dispatchToListeners('message', parsed, event);
+            };
+            source.onerror = (err) => {
+                status = 'error';
+                error = err;
+                onError?.(err);
+                cleanupConnection();
+                scheduleReconnect(targetUrl);
+            };
+            // Re-attach custom event listeners
+            for (const [eventName] of listeners) {
+                if (eventName !== 'message') {
+                    source.addEventListener(eventName, (event) => {
+                        const parsed = parseEventData(event.data);
+                        data = parsed;
+                        lastEvent = eventName;
+                        dispatchToListeners(eventName, parsed, event);
+                    });
+                }
+            }
+        }
+        catch (err) {
+            status = 'error';
+            error = err;
+            scheduleReconnect(targetUrl);
+        }
+    }
+    function close() {
+        manualClose = true;
+        status = 'closed';
+        cleanupConnection();
+    }
+    function reconnect() {
+        manualClose = false;
+        retryCount = 0;
+        const targetUrl = typeof url === 'function' ? url() : url;
+        connect(targetUrl);
+    }
+    function on(event, handler) {
+        let handlers = listeners.get(event);
+        if (!handlers) {
+            handlers = new SvelteSet();
+            listeners.set(event, handlers);
+            // If EventSource is currently connected, register native listener for named event
+            if (es && event !== 'message') {
+                es.addEventListener(event, (evt) => {
+                    const parsed = parseEventData(evt.data);
+                    data = parsed;
+                    lastEvent = event;
+                    dispatchToListeners(event, parsed, evt);
+                });
+            }
+        }
+        handlers.add(handler);
+        return () => {
+            handlers?.delete(handler);
+            if (handlers?.size === 0) {
+                listeners.delete(event);
+            }
+        };
+    }
+    // Svelte 5 effect for automated lifecycle management if called inside a component/effect root
+    try {
+        $effect(() => {
+            const targetUrl = typeof url === 'function' ? url() : url;
+            if (enabled && targetUrl) {
+                connect(targetUrl);
+            }
+            else {
+                close();
+            }
+            return () => {
+                manualClose = true;
+                cleanupConnection();
+            };
+        });
+    }
+    catch {
+        // When called outside an effect root (e.g. In unit tests), connect directly
+        if (enabled) {
+            const targetUrl = typeof url === 'function' ? url() : url;
+            if (targetUrl) {
+                connect(targetUrl);
+            }
+        }
+    }
+    return {
+        get status() {
+            return status;
+        },
+        get connected() {
+            return connected;
+        },
+        get connecting() {
+            return connecting;
+        },
+        get data() {
+            return data;
+        },
+        get lastEvent() {
+            return lastEvent;
+        },
+        get error() {
+            return error;
+        },
+        on,
+        close,
+        reconnect
+    };
+}

package/dist/composables/useSSE.test.d.ts

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

package/dist/composables/useSSE.test.js

@@ -0,0 +1,122 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { useSSE } from './useSSE.svelte';
+class MockEventSource {
+    url;
+    withCredentials;
+    onopen = null;
+    onmessage = null;
+    onerror = null;
+    listeners = new Map();
+    readyState = 0;
+    static instances = [];
+    constructor(url, init) {
+        this.url = url;
+        this.withCredentials = init?.withCredentials;
+        MockEventSource.instances.push(this);
+    }
+    addEventListener(type, handler) {
+        let handlers = this.listeners.get(type);
+        if (!handlers) {
+            handlers = new Set();
+            this.listeners.set(type, handlers);
+        }
+        handlers.add(handler);
+    }
+    removeEventListener(type, handler) {
+        this.listeners.get(type)?.delete(handler);
+    }
+    close() {
+        this.readyState = 2;
+    }
+    simulateOpen() {
+        this.readyState = 1;
+        this.onopen?.();
+    }
+    simulateMessage(data, type = 'message') {
+        const rawData = typeof data === 'object' ? JSON.stringify(data) : String(data);
+        const evt = { data: rawData, type };
+        if (type === 'message') {
+            this.onmessage?.(evt);
+        }
+        const handlers = this.listeners.get(type);
+        if (handlers) {
+            for (const handler of handlers) {
+                handler(evt);
+            }
+        }
+    }
+    simulateError(err = new Event('error')) {
+        this.onerror?.(err);
+    }
+}
+describe('useSSE Composable Rune', () => {
+    beforeEach(() => {
+        MockEventSource.instances = [];
+        vi.stubGlobal('EventSource', MockEventSource);
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        vi.restoreAllMocks();
+    });
+    it('initializes with connecting or connected state when EventSource exists', () => {
+        const sse = useSSE('/api/events', { enabled: true });
+        expect(sse.status).toBe('connecting');
+        expect(sse.connecting).toBe(true);
+        expect(sse.connected).toBe(false);
+        expect(MockEventSource.instances.length).toBe(1);
+        const instance = MockEventSource.instances[0];
+        expect(instance.url).toBe('/api/events');
+        instance.simulateOpen();
+        expect(sse.status).toBe('connected');
+        expect(sse.connected).toBe(true);
+        expect(sse.connecting).toBe(false);
+    });
+    it('handles message events and parses JSON data reactively', () => {
+        const onMessage = vi.fn();
+        const sse = useSSE('/api/events', { onMessage });
+        const instance = MockEventSource.instances[0];
+        instance.simulateOpen();
+        instance.simulateMessage({ user: 'Alice', score: 100 });
+        expect(sse.data).toEqual({ user: 'Alice', score: 100 });
+        expect(sse.lastEvent).toBe('message');
+        expect(onMessage).toHaveBeenCalledWith({ user: 'Alice', score: 100 }, expect.any(Object));
+    });
+    it('subscribes to custom named events via .on(eventName, handler)', () => {
+        const sse = useSSE('/api/events');
+        const instance = MockEventSource.instances[0];
+        instance.simulateOpen();
+        const orderHandler = vi.fn();
+        const unsubscribe = sse.on('order.paid', orderHandler);
+        instance.simulateMessage({ orderId: 'ord_99', total: 29.5 }, 'order.paid');
+        expect(orderHandler).toHaveBeenCalledTimes(1);
+        expect(orderHandler).toHaveBeenCalledWith({ orderId: 'ord_99', total: 29.5 }, expect.any(Object));
+        expect(sse.lastEvent).toBe('order.paid');
+        // Test unsubscribe
+        unsubscribe();
+        instance.simulateMessage({ orderId: 'ord_100', total: 10 }, 'order.paid');
+        expect(orderHandler).toHaveBeenCalledTimes(1);
+    });
+    it('closes the connection cleanly on .close()', () => {
+        const sse = useSSE('/api/events');
+        const instance = MockEventSource.instances[0];
+        instance.simulateOpen();
+        sse.close();
+        expect(sse.status).toBe('closed');
+        expect(sse.connected).toBe(false);
+        expect(instance.readyState).toBe(2);
+    });
+    it('reconnects when .reconnect() is invoked', () => {
+        const sse = useSSE('/api/events');
+        expect(MockEventSource.instances.length).toBe(1);
+        sse.close();
+        expect(sse.status).toBe('closed');
+        sse.reconnect();
+        expect(MockEventSource.instances.length).toBe(2);
+        expect(sse.status).toBe('connecting');
+    });
+    it('stays idle when enabled is false', () => {
+        const sse = useSSE('/api/events', { enabled: false });
+        expect(sse.status).toBe('idle');
+        expect(MockEventSource.instances.length).toBe(0);
+    });
+});

package/dist/index.d.ts

@@ -156,6 +156,8 @@ export { useFormAction } from './composables/useFormAction.svelte';
 export type { UseFormActionOptions } from './composables/useFormAction.svelte';
 export { useIdle } from './composables/useIdle.svelte';
 export type { UseIdleOptions } from './composables/useIdle.svelte';
+export { useSSE } from './composables/useSSE.svelte';
+export type { SSEStatus, UseSSEOptions, SSEEventHandler, SSEResult } from './composables/useSSE.svelte';
 export { default as ThemeStudio } from './components/theme/ThemeStudio.svelte';
 export type { ThemeStudioProps } from './components/theme/ThemeStudio.svelte';
 export { theme, themeInitScript, ACCENT_PALETTES, NEUTRAL_PALETTES, FONT_PRESETS, RADIUS_PRESETS, FONT_SIZE_PRESETS, DEFAULT_CHART_COLORS } from './theme/theme.svelte';

package/dist/index.js

@@ -103,6 +103,7 @@ export { Sortable, useSortable } from './composables/useSortable.svelte';
 export { useDataTable } from './composables/useDataTable.svelte';
 export { useFormAction } from './composables/useFormAction.svelte';
 export { useIdle } from './composables/useIdle.svelte';
+export { useSSE } from './composables/useSSE.svelte';
 // Theming & Theme Studio
 export { default as ThemeStudio } from './components/theme/ThemeStudio.svelte';
 export { theme, themeInitScript, ACCENT_PALETTES, NEUTRAL_PALETTES, FONT_PRESETS, RADIUS_PRESETS, FONT_SIZE_PRESETS, DEFAULT_CHART_COLORS } from './theme/theme.svelte';