yaxa-svelte 2.3.0 → 2.5.0

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

@@ -0,0 +1,136 @@
+import type { AnyDb } from '../db';
+import type { JobStatus } from '../db/types';
+/**
+ * Persisted Job record structure.
+ */
+export interface JobRecord<TPayload = any> {
+    id: string;
+    queue: string;
+    name: string;
+    payload: TPayload;
+    status: JobStatus;
+    priority: number;
+    attempts: number;
+    maxAttempts: number;
+    runAt: Date;
+    lockedAt?: Date | null;
+    lockedBy?: string | null;
+    failedReason?: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    completedAt?: Date | null;
+}
+/**
+ * Delay specifier:
+ * - String format: '30s', '5m', '2h', '1d'
+ * - Number: delay in milliseconds
+ * - Date: absolute execution timestamp
+ */
+export type JobDelay = string | number | Date;
+export interface EnqueueJobOptions {
+    /**
+     * Queue partition name (default: 'default').
+     */
+    queue?: string;
+    /**
+     * Execution delay or scheduled Date.
+     */
+    delay?: JobDelay;
+    /**
+     * Job execution priority (higher number = higher priority). Default: 0.
+     */
+    priority?: number;
+    /**
+     * Maximum retry attempts before routing to Dead Letter Queue (DLQ). Default: 3.
+     */
+    maxAttempts?: number;
+    /**
+     * Optional Drizzle transaction object for the Transactional Outbox pattern.
+     */
+    tx?: any;
+    /**
+     * Optional custom Drizzle DB client instance.
+     */
+    db?: AnyDb;
+}
+export interface WorkerContext<TPayload = any> {
+    job: JobRecord<TPayload>;
+    logger: {
+        info: (msg: string, ...args: any[]) => void;
+        warn: (msg: string, ...args: any[]) => void;
+        error: (msg: string, ...args: any[]) => void;
+    };
+}
+export type WorkerHandler<TPayload = any> = (payload: TPayload, context: WorkerContext<TPayload>) => Promise<void> | void;
+export interface WorkerDefinition<TPayload = any> {
+    name: string;
+    handler: WorkerHandler<TPayload>;
+    queue?: string;
+}
+export interface JobRunnerOptions {
+    /**
+     * Drizzle database instance (Neon or Turso).
+     */
+    db?: AnyDb;
+    /**
+     * Database driver ('neon' | 'turso' | 'sqlite').
+     */
+    driver?: 'neon' | 'turso' | 'sqlite';
+    /**
+     * List of registered worker handlers.
+     */
+    workers: WorkerDefinition<any>[];
+    /**
+     * Target queue name to poll (default: 'default').
+     */
+    queue?: string;
+    /**
+     * Maximum jobs to lease and process per batch (default: 10).
+     */
+    batchSize?: number;
+    /**
+     * Polling interval in milliseconds for daemon mode (default: 3000ms).
+     */
+    pollIntervalMs?: number;
+    /**
+     * Lock timeout in milliseconds before a processing job is considered stale (default: 5 minutes).
+     */
+    lockTimeoutMs?: number;
+    /**
+     * Worker instance identifier (default: generated worker id).
+     */
+    workerId?: string;
+}
+export interface JobBatchResult {
+    processed: number;
+    succeeded: number;
+    failed: number;
+}
+export interface JobRunner {
+    /**
+     * Processes the next batch of pending jobs. Perfect for serverless cron endpoints (/api/cron/jobs).
+     */
+    processNextBatch: () => Promise<JobBatchResult>;
+    /**
+     * Starts the continuous background polling loop (for long-lived Node.js servers).
+     */
+    start: () => void;
+    /**
+     * Stops the background polling loop.
+     */
+    stop: () => void;
+    /**
+     * Returns true if the polling runner is currently active.
+     */
+    isRunning: () => boolean;
+}
+export type EventHandler<TData = any> = (data: TData) => Promise<void> | void;
+export interface EventSubscription {
+    unsubscribe: () => void;
+}
+export interface IEventBus {
+    publish: <TData = any>(eventName: string, data: TData) => Promise<void>;
+    subscribe: <TData = any>(eventName: string, handler: EventHandler<TData>) => EventSubscription;
+    once: <TData = any>(eventName: string, handler: EventHandler<TData>) => EventSubscription;
+    clear: () => void;
+}

package/dist/server/jobs/types.js

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

package/dist/server/openapi/handler.js

@@ -78,10 +78,12 @@ function renderRedocHtml(specJson, title) {
  * page (Scalar, Swagger UI, or Redoc) or returns raw OpenAPI 3.1 JSON when ?format=json is requested.
  */
 export function createApiDocsHandler(options = {}) {
-    const theme = options.theme || 'scalar';
+    const defaultTheme = options.theme || 'scalar';
     return async (event) => {
         const { url, request } = event;
         const format = url.searchParams.get('format');
+        const themeQuery = url.searchParams.get('theme');
+        const activeTheme = themeQuery && ['scalar', 'swagger', 'redoc'].includes(themeQuery) ? themeQuery : defaultTheme;
         const acceptHeader = request.headers.get('accept') || '';
         const spec = generateOpenApiSpec(options);
         // If caller requests JSON via query param, accept header, or path ending in .json
@@ -98,10 +100,10 @@ export function createApiDocsHandler(options = {}) {
         // Render Interactive HTML Docs
         const specJson = JSON.stringify(spec);
         let html;
-        if (theme === 'swagger') {
+        if (activeTheme === 'swagger') {
             html = renderSwaggerHtml(specJson, spec.info.title);
         }
-        else if (theme === 'redoc') {
+        else if (activeTheme === 'redoc') {
             html = renderRedocHtml(specJson, spec.info.title);
         }
         else {

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