opinionated-machine 5.1.0 → 6.0.0

package/dist/lib/sse/sseContracts.js

@@ -0,0 +1,102 @@
+/**
+ * Build a GET SSE route definition (traditional SSE).
+ *
+ * Use this for long-lived connections where the client subscribes
+ * to receive events over time (e.g., notifications, real-time updates).
+ *
+ * @example
+ * ```typescript
+ * const notificationsStream = buildSSERoute({
+ *   path: '/api/notifications/stream',
+ *   params: z.object({}),
+ *   query: z.object({ userId: z.string().uuid() }),
+ *   requestHeaders: z.object({ authorization: z.string() }),
+ *   events: {
+ *     notification: z.object({ id: z.string(), message: z.string() }),
+ *   },
+ * })
+ * ```
+ */
+export function buildSSERoute(config) {
+    return {
+        method: 'GET',
+        path: config.path,
+        params: config.params,
+        query: config.query,
+        requestHeaders: config.requestHeaders,
+        body: undefined,
+        events: config.events,
+        isSSE: true,
+    };
+}
+/**
+ * Build a POST/PUT/PATCH SSE route definition (OpenAI-style streaming API).
+ *
+ * Use this for request-response streaming where the client sends a request
+ * body and receives a stream of events in response (e.g., chat completions).
+ *
+ * @example
+ * ```typescript
+ * const chatCompletionStream = buildPayloadSSERoute({
+ *   method: 'POST',
+ *   path: '/api/ai/chat/completions',
+ *   params: z.object({}),
+ *   query: z.object({}),
+ *   requestHeaders: z.object({ authorization: z.string() }),
+ *   body: z.object({
+ *     model: z.string(),
+ *     messages: z.array(z.object({ role: z.string(), content: z.string() })),
+ *     stream: z.literal(true),
+ *   }),
+ *   events: {
+ *     chunk: z.object({ content: z.string() }),
+ *     done: z.object({ usage: z.object({ tokens: z.number() }) }),
+ *   },
+ * })
+ * ```
+ */
+export function buildPayloadSSERoute(config) {
+    return {
+        method: config.method ?? 'POST',
+        path: config.path,
+        params: config.params,
+        query: config.query,
+        requestHeaders: config.requestHeaders,
+        body: config.body,
+        events: config.events,
+        isSSE: true,
+    };
+}
+/**
+ * Type-inference helper for SSE handlers.
+ *
+ * Similar to `buildFastifyPayloadRoute`, this function provides automatic
+ * type inference for the request and connection parameters based on the contract.
+ *
+ * @example
+ * ```typescript
+ * class MyController extends AbstractSSEController<{ stream: typeof streamContract }> {
+ *   private handleStream = buildSSEHandler(
+ *     streamContract,
+ *     async (request, connection) => {
+ *       // request.body is typed from contract
+ *       // request.query is typed from contract
+ *       const { message } = request.body
+ *     },
+ *   )
+ *
+ *   buildSSERoutes() {
+ *     return {
+ *       stream: {
+ *         contract: streamContract,
+ *         handler: this.handleStream,
+ *       },
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export function buildSSEHandler(_contract, handler) {
+    return handler;
+}
+//# sourceMappingURL=sseContracts.js.map

package/dist/lib/sse/sseContracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sseContracts.js","sourceRoot":"","sources":["../../../lib/sse/sseContracts.ts"],"names":[],"mappings":"AA0FA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAO3B,MAAmE;IAEnE,OAAO;QACL,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,IAAI;KACZ,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,oBAAoB,CAQlC,MAAgF;IAEhF,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,MAAM;QAC/B,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,IAAI;KACZ,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,eAAe,CAC7B,SAAmB,EACnB,OAKC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/lib/sse/sseParser.d.ts

@@ -0,0 +1,167 @@
+/**
+ * SSE (Server-Sent Events) parsing utilities.
+ *
+ * This module provides utilities for parsing SSE event streams according
+ * to the W3C Server-Sent Events specification.
+ *
+ * @see https://html.spec.whatwg.org/multipage/server-sent-events.html
+ *
+ * @module sseParser
+ */
+export type ParsedSSEEvent = {
+    /**
+     * Event ID for client reconnection via Last-Event-ID header.
+     * When the client reconnects, it can send this ID to resume from where it left off.
+     */
+    id?: string;
+    /**
+     * Event type name that maps to EventSource event listeners.
+     * Defaults to 'message' when not specified.
+     */
+    event?: string;
+    /**
+     * Event data payload as a string.
+     * For multi-line data, lines are joined with newlines.
+     * Typically contains JSON that should be parsed by the consumer.
+     */
+    data: string;
+    /**
+     * Reconnection delay hint in milliseconds.
+     * Suggests how long the client should wait before reconnecting.
+     */
+    retry?: number;
+};
+/**
+ * Parse SSE events from a complete text response.
+ *
+ * This function parses a complete SSE response body into individual events.
+ * SSE events are separated by blank lines, and each event can have multiple fields.
+ *
+ * **SSE Format:**
+ * ```
+ * id: event-id
+ * event: event-name
+ * data: line1
+ * data: line2
+ * retry: 3000
+ *
+ * ```
+ *
+ * **Field Rules:**
+ * - `id:` - Event ID for Last-Event-ID reconnection
+ * - `event:` - Event type (defaults to 'message')
+ * - `data:` - Event payload (multiple data lines are joined with newlines)
+ * - `retry:` - Reconnection delay in milliseconds
+ * - Lines starting with `:` are comments and ignored
+ *
+ * @param text - Raw SSE text to parse
+ * @returns Array of parsed events
+ *
+ * @example
+ * ```typescript
+ * // Parse a simple SSE response
+ * const text = `event: message
+ * data: {"text":"hello"}
+ *
+ * event: done
+ * data: {"status":"complete"}
+ *
+ * `
+ * const events = parseSSEEvents(text)
+ * // events = [
+ * //   { event: 'message', data: '{"text":"hello"}' },
+ * //   { event: 'done', data: '{"status":"complete"}' }
+ * // ]
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Parse events with IDs (for reconnection)
+ * const text = `id: 1
+ * event: update
+ * data: {"value":42}
+ *
+ * id: 2
+ * event: update
+ * data: {"value":43}
+ *
+ * `
+ * const events = parseSSEEvents(text)
+ * // Store last ID for reconnection: events[events.length - 1].id
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multi-line data
+ * const text = `event: log
+ * data: Line 1
+ * data: Line 2
+ * data: Line 3
+ *
+ * `
+ * const events = parseSSEEvents(text)
+ * // events[0].data === "Line 1\nLine 2\nLine 3"
+ * ```
+ */
+export declare function parseSSEEvents(text: string): ParsedSSEEvent[];
+/**
+ * Result of incremental SSE buffer parsing.
+ */
+export type ParseSSEBufferResult = {
+    /** Complete events parsed from the buffer */
+    events: ParsedSSEEvent[];
+    /** Remaining incomplete data to prepend to next chunk */
+    remaining: string;
+};
+/**
+ * Parse SSE events incrementally from a buffer.
+ *
+ * This function is designed for streaming scenarios where data arrives
+ * in chunks. It parses complete events and returns any incomplete data
+ * that should be prepended to the next chunk.
+ *
+ * **Usage Pattern:**
+ * 1. Append new chunk to buffer
+ * 2. Call parseSSEBuffer(buffer)
+ * 3. Process the events
+ * 4. Set buffer = remaining for next iteration
+ *
+ * @param buffer - Current buffer containing SSE data
+ * @returns Object with parsed events and remaining incomplete buffer
+ *
+ * @example
+ * ```typescript
+ * // Streaming SSE parsing with fetch
+ * const response = await fetch(url)
+ * const reader = response.body.getReader()
+ * const decoder = new TextDecoder()
+ * let buffer = ''
+ *
+ * while (true) {
+ *   const { done, value } = await reader.read()
+ *   if (done) break
+ *
+ *   buffer += decoder.decode(value, { stream: true })
+ *   const { events, remaining } = parseSSEBuffer(buffer)
+ *   buffer = remaining
+ *
+ *   for (const event of events) {
+ *     console.log('Received:', event.event, JSON.parse(event.data))
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Node.js readable stream
+ * let buffer = ''
+ * stream.on('data', (chunk: Buffer) => {
+ *   buffer += chunk.toString()
+ *   const { events, remaining } = parseSSEBuffer(buffer)
+ *   buffer = remaining
+ *
+ *   events.forEach(event => emit('sse-event', event))
+ * })
+ * ```
+ */
+export declare function parseSSEBuffer(buffer: string): ParseSSEBufferResult;

package/dist/lib/sse/sseParser.js

@@ -0,0 +1,225 @@
+/**
+ * SSE (Server-Sent Events) parsing utilities.
+ *
+ * This module provides utilities for parsing SSE event streams according
+ * to the W3C Server-Sent Events specification.
+ *
+ * @see https://html.spec.whatwg.org/multipage/server-sent-events.html
+ *
+ * @module sseParser
+ */
+/**
+ * A parsed SSE event.
+ *
+ * SSE events consist of optional id, event type, data, and retry fields.
+ * The data field is always present and contains the event payload as a string.
+ *
+ * @example
+ * ```typescript
+ * const event: ParsedSSEEvent = {
+ *   id: 'msg-123',
+ *   event: 'message',
+ *   data: '{"text":"Hello, world!"}',
+ *   retry: 3000,
+ * }
+ *
+ * // Parse the JSON data
+ * const payload = JSON.parse(event.data)
+ * ```
+ */
+/**
+ * Parse a single SSE line and update the event state.
+ * Returns true if a complete event was found (empty line with data).
+ */
+function parseSSELine(line, currentEvent, dataLines) {
+    if (line.startsWith('id:')) {
+        currentEvent.id = line.slice(3).trim();
+    }
+    else if (line.startsWith('event:')) {
+        currentEvent.event = line.slice(6).trim();
+    }
+    else if (line.startsWith('data:')) {
+        dataLines.push(line.slice(5).trim());
+    }
+    else if (line.startsWith('retry:')) {
+        currentEvent.retry = Number.parseInt(line.slice(6).trim(), 10);
+    }
+    else if (line === '' && dataLines.length > 0) {
+        return true; // Event complete
+    }
+    // Comment lines (starting with :) are implicitly ignored
+    return false;
+}
+/**
+ * Parse SSE events from a complete text response.
+ *
+ * This function parses a complete SSE response body into individual events.
+ * SSE events are separated by blank lines, and each event can have multiple fields.
+ *
+ * **SSE Format:**
+ * ```
+ * id: event-id
+ * event: event-name
+ * data: line1
+ * data: line2
+ * retry: 3000
+ *
+ * ```
+ *
+ * **Field Rules:**
+ * - `id:` - Event ID for Last-Event-ID reconnection
+ * - `event:` - Event type (defaults to 'message')
+ * - `data:` - Event payload (multiple data lines are joined with newlines)
+ * - `retry:` - Reconnection delay in milliseconds
+ * - Lines starting with `:` are comments and ignored
+ *
+ * @param text - Raw SSE text to parse
+ * @returns Array of parsed events
+ *
+ * @example
+ * ```typescript
+ * // Parse a simple SSE response
+ * const text = `event: message
+ * data: {"text":"hello"}
+ *
+ * event: done
+ * data: {"status":"complete"}
+ *
+ * `
+ * const events = parseSSEEvents(text)
+ * // events = [
+ * //   { event: 'message', data: '{"text":"hello"}' },
+ * //   { event: 'done', data: '{"status":"complete"}' }
+ * // ]
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Parse events with IDs (for reconnection)
+ * const text = `id: 1
+ * event: update
+ * data: {"value":42}
+ *
+ * id: 2
+ * event: update
+ * data: {"value":43}
+ *
+ * `
+ * const events = parseSSEEvents(text)
+ * // Store last ID for reconnection: events[events.length - 1].id
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multi-line data
+ * const text = `event: log
+ * data: Line 1
+ * data: Line 2
+ * data: Line 3
+ *
+ * `
+ * const events = parseSSEEvents(text)
+ * // events[0].data === "Line 1\nLine 2\nLine 3"
+ * ```
+ */
+export function parseSSEEvents(text) {
+    const events = [];
+    const lines = text.split('\n');
+    let currentEvent = {};
+    let dataLines = [];
+    for (const line of lines) {
+        if (parseSSELine(line, currentEvent, dataLines)) {
+            events.push({
+                ...currentEvent,
+                data: dataLines.join('\n'),
+            });
+            currentEvent = {};
+            dataLines = [];
+        }
+    }
+    // Handle case where stream doesn't end with double newline
+    if (dataLines.length > 0) {
+        events.push({
+            ...currentEvent,
+            data: dataLines.join('\n'),
+        });
+    }
+    return events;
+}
+/**
+ * Parse SSE events incrementally from a buffer.
+ *
+ * This function is designed for streaming scenarios where data arrives
+ * in chunks. It parses complete events and returns any incomplete data
+ * that should be prepended to the next chunk.
+ *
+ * **Usage Pattern:**
+ * 1. Append new chunk to buffer
+ * 2. Call parseSSEBuffer(buffer)
+ * 3. Process the events
+ * 4. Set buffer = remaining for next iteration
+ *
+ * @param buffer - Current buffer containing SSE data
+ * @returns Object with parsed events and remaining incomplete buffer
+ *
+ * @example
+ * ```typescript
+ * // Streaming SSE parsing with fetch
+ * const response = await fetch(url)
+ * const reader = response.body.getReader()
+ * const decoder = new TextDecoder()
+ * let buffer = ''
+ *
+ * while (true) {
+ *   const { done, value } = await reader.read()
+ *   if (done) break
+ *
+ *   buffer += decoder.decode(value, { stream: true })
+ *   const { events, remaining } = parseSSEBuffer(buffer)
+ *   buffer = remaining
+ *
+ *   for (const event of events) {
+ *     console.log('Received:', event.event, JSON.parse(event.data))
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Node.js readable stream
+ * let buffer = ''
+ * stream.on('data', (chunk: Buffer) => {
+ *   buffer += chunk.toString()
+ *   const { events, remaining } = parseSSEBuffer(buffer)
+ *   buffer = remaining
+ *
+ *   events.forEach(event => emit('sse-event', event))
+ * })
+ * ```
+ */
+export function parseSSEBuffer(buffer) {
+    const events = [];
+    const lines = buffer.split('\n');
+    let currentEvent = {};
+    let dataLines = [];
+    let lastCompleteEventEnd = 0;
+    let currentPosition = 0;
+    for (const line of lines) {
+        currentPosition += line.length + 1; // +1 for the \n
+        if (parseSSELine(line, currentEvent, dataLines)) {
+            events.push({
+                ...currentEvent,
+                data: dataLines.join('\n'),
+            });
+            currentEvent = {};
+            dataLines = [];
+            lastCompleteEventEnd = currentPosition;
+        }
+    }
+    // Return remaining incomplete data
+    // Preserve any unconsumed content after the last complete event,
+    // including incomplete events with only id:/event:/retry: lines (not just data: lines)
+    const remaining = lastCompleteEventEnd < buffer.length ? buffer.slice(lastCompleteEventEnd) : '';
+    return { events, remaining };
+}
+//# sourceMappingURL=sseParser.js.map

package/dist/lib/sse/sseParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sseParser.js","sourceRoot":"","sources":["../../../lib/sse/sseParser.ts"],"names":[],"mappings":"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"}

package/dist/lib/sse/sseRouteBuilder.d.ts

@@ -0,0 +1,47 @@
+import type { RouteOptions } from 'fastify';
+import type { AbstractSSEController } from './AbstractSSEController.ts';
+import type { AnySSERouteDefinition } from './sseContracts.ts';
+import type { SSEHandlerConfig } from './sseTypes.ts';
+/**
+ * Build a Fastify route configuration for an SSE endpoint.
+ *
+ * This function creates a route that integrates with @fastify/sse
+ * and the AbstractSSEController connection management.
+ *
+ * @param controller - The SSE controller instance
+ * @param config - The SSE handler configuration
+ * @returns Fastify route options
+ */
+export declare function buildFastifySSERoute<Contract extends AnySSERouteDefinition>(controller: AbstractSSEController<Record<string, AnySSERouteDefinition>>, config: SSEHandlerConfig<Contract>): RouteOptions;
+/**
+ * Options for registering SSE routes globally.
+ */
+export type RegisterSSERoutesOptions = {
+    /**
+     * Heartbeat interval in milliseconds.
+     * @default 30000
+     */
+    heartbeatInterval?: number;
+    /**
+     * Custom serializer for SSE message data.
+     * @default JSON.stringify
+     */
+    serializer?: (data: unknown) => string;
+    /**
+     * Global preHandler hooks applied to all SSE routes.
+     * Use for authentication that should apply to all SSE endpoints.
+     */
+    preHandler?: RouteOptions['preHandler'];
+    /**
+     * Rate limit configuration (requires @fastify/rate-limit to be registered).
+     * If @fastify/rate-limit is not registered, this config is ignored.
+     */
+    rateLimit?: {
+        /** Maximum number of connections */
+        max: number;
+        /** Time window for rate limiting */
+        timeWindow: string | number;
+        /** Custom key generator (e.g., for per-user limits) */
+        keyGenerator?: (request: unknown) => string;
+    };
+};

package/dist/lib/sse/sseRouteBuilder.js

@@ -0,0 +1,114 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * Send replay events from either sync or async iterables.
+ */
+async function sendReplayEvents(sseReply, replayEvents) {
+    // biome-ignore lint/suspicious/noExplicitAny: checking for iterator symbols
+    const iterable = replayEvents;
+    if (typeof iterable[Symbol.asyncIterator] === 'function') {
+        for await (const event of replayEvents) {
+            await sseReply.sse.send(event);
+        }
+    }
+    else if (typeof iterable[Symbol.iterator] === 'function') {
+        for (const event of replayEvents) {
+            await sseReply.sse.send(event);
+        }
+    }
+}
+/**
+ * Build a Fastify route configuration for an SSE endpoint.
+ *
+ * This function creates a route that integrates with @fastify/sse
+ * and the AbstractSSEController connection management.
+ *
+ * @param controller - The SSE controller instance
+ * @param config - The SSE handler configuration
+ * @returns Fastify route options
+ */
+export function buildFastifySSERoute(controller, config) {
+    const { contract, handler, options } = config;
+    const routeOptions = {
+        method: contract.method,
+        url: contract.path,
+        sse: true,
+        schema: {
+            params: contract.params,
+            querystring: contract.query,
+            headers: contract.requestHeaders,
+            ...(contract.body && { body: contract.body }),
+        },
+        handler: async (request, reply) => {
+            const connectionId = randomUUID();
+            // Create connection wrapper
+            const connection = {
+                id: connectionId,
+                request,
+                reply,
+                context: {},
+                connectedAt: new Date(),
+            };
+            // Create a promise that will resolve when the client disconnects
+            // Using request.socket.on('close') as per @fastify/sse documentation
+            const connectionClosed = new Promise((resolve) => {
+                request.socket.on('close', async () => {
+                    try {
+                        await options?.onDisconnect?.(connection);
+                    }
+                    catch (err) {
+                        // Log the error but don't let it prevent cleanup
+                        options?.logger?.error({ err }, 'Error in SSE onDisconnect handler');
+                    }
+                    finally {
+                        // Always unregister the connection and resolve, even if onDisconnect throws
+                        controller.unregisterConnection(connectionId);
+                        resolve();
+                    }
+                });
+            });
+            // Register connection with controller
+            controller.registerConnection(connection);
+            // Tell @fastify/sse to keep the connection open after handler returns
+            // Without this, the plugin closes the connection immediately
+            const sseReply = reply;
+            sseReply.sse.keepAlive();
+            // Send headers + an SSE comment to establish the stream
+            // Without sending initial data, the client may not receive headers properly
+            sseReply.sse.sendHeaders();
+            // SSE comments (lines starting with :) are ignored by clients but establish the stream
+            reply.raw.write(': connected\n\n');
+            // Handle reconnection with Last-Event-ID
+            const lastEventId = request.headers['last-event-id'];
+            if (lastEventId && options?.onReconnect) {
+                try {
+                    const replayEvents = await options.onReconnect(connection, lastEventId);
+                    if (replayEvents) {
+                        await sendReplayEvents(sseReply, replayEvents);
+                    }
+                }
+                catch (err) {
+                    options?.logger?.error({ err, lastEventId }, 'Error in SSE onReconnect handler');
+                }
+            }
+            // Notify connection established
+            try {
+                await options?.onConnect?.(connection);
+            }
+            catch (err) {
+                options?.logger?.error({ err }, 'Error in SSE onConnect handler');
+            }
+            // Call user handler for setup (subscriptions, initial data, etc.)
+            // biome-ignore lint/suspicious/noExplicitAny: Handler types are validated by SSEHandlerConfig
+            await handler(request, connection);
+            // Block the handler until the connection closes
+            // This prevents Fastify from ending the response prematurely
+            await connectionClosed;
+        },
+    };
+    // Add preHandler hooks for authentication
+    if (options?.preHandler) {
+        routeOptions.preHandler = options.preHandler;
+    }
+    return routeOptions;
+}
+//# sourceMappingURL=sseRouteBuilder.js.map

package/dist/lib/sse/sseRouteBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sseRouteBuilder.js","sourceRoot":"","sources":["../../../lib/sse/sseRouteBuilder.ts"],"names":[],"mappings":"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"}