opinionated-machine 5.1.0 → 6.0.0

package/dist/lib/sse/AbstractSSEController.js

@@ -0,0 +1,228 @@
+import { SSEConnectionSpy } from "./SSEConnectionSpy.js";
+export { SSEConnectionSpy } from "./SSEConnectionSpy.js";
+/**
+ * Abstract base class for SSE controllers.
+ *
+ * Provides connection management, broadcasting, and lifecycle hooks.
+ * Extend this class to create SSE controllers that handle real-time
+ * streaming connections.
+ *
+ * @template APIContracts - Map of route names to SSE route definitions
+ *
+ * @example
+ * ```typescript
+ * class NotificationsSSEController extends AbstractSSEController<typeof contracts> {
+ *   public static contracts = {
+ *     notifications: buildSSERoute({ ... }),
+ *   } as const
+ *
+ *   public buildSSERoutes() {
+ *     return {
+ *       notifications: {
+ *         contract: NotificationsSSEController.contracts.notifications,
+ *         handler: this.handleNotifications,
+ *       },
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class AbstractSSEController {
+    /** Map of connection ID to connection object */
+    connections = new Map();
+    /** Private storage for connection spy */
+    _connectionSpy;
+    /**
+     * SSE controllers must override this constructor and call super with their
+     * dependencies object and the SSE config.
+     *
+     * @param _dependencies - The dependencies object (cradle proxy in awilix)
+     * @param sseConfig - Optional SSE controller configuration
+     *
+     * @example
+     * ```typescript
+     * class MySSEController extends AbstractSSEController<MyContracts> {
+     *   private myService: MyService
+     *
+     *   constructor(deps: { myService: MyService }, sseConfig?: SSEControllerConfig) {
+     *     super(deps, sseConfig)
+     *     this.myService = deps.myService
+     *   }
+     * }
+     * ```
+     */
+    constructor(_dependencies, sseConfig) {
+        if (sseConfig?.enableConnectionSpy) {
+            this._connectionSpy = new SSEConnectionSpy();
+        }
+    }
+    /**
+     * Get the connection spy for testing.
+     * Throws an error if spies are not enabled.
+     * Enable spies by passing `{ enableConnectionSpy: true }` to the constructor.
+     *
+     * @example
+     * ```typescript
+     * // In test, create controller with spy enabled
+     * // Pass dependencies first, then config with enableConnectionSpy
+     * const controller = new MySSEController({}, { enableConnectionSpy: true })
+     *
+     * // Start connection (async)
+     * connectSSE(baseUrl, '/api/stream')
+     *
+     * // Wait for connection - handles race condition
+     * const connection = await controller.connectionSpy.waitForConnection()
+     * ```
+     *
+     * @throws Error if connection spy is not enabled
+     */
+    get connectionSpy() {
+        if (!this._connectionSpy) {
+            throw new Error('Connection spy is not enabled. Pass { enableConnectionSpy: true } to the constructor. ' +
+                'This should only be used in test environments.');
+        }
+        return this._connectionSpy;
+    }
+    /**
+     * Send an event to a specific connection.
+     *
+     * @param connectionId - The connection to send to
+     * @param message - The SSE message to send
+     * @returns true if sent successfully, false if connection not found or closed
+     */
+    async sendEvent(connectionId, message) {
+        const connection = this.connections.get(connectionId);
+        if (!connection) {
+            return false;
+        }
+        try {
+            const reply = connection.reply;
+            // @fastify/sse handles JSON serialization internally, so pass data as-is
+            await reply.sse.send({
+                data: message.data,
+                event: message.event,
+                id: message.id,
+                retry: message.retry,
+            });
+            return true;
+        }
+        catch {
+            // Send failed - connection is likely closed (client disconnected, network error, etc.)
+            // Remove from tracking to prevent further send attempts to a dead connection
+            // Use unregisterConnection to ensure hooks and spy are notified
+            this.unregisterConnection(connectionId);
+            return false;
+        }
+    }
+    /**
+     * Broadcast an event to all connected clients.
+     *
+     * @param message - The SSE message to broadcast
+     * @returns Number of clients the message was sent to
+     */
+    async broadcast(message) {
+        let sent = 0;
+        const connectionIds = Array.from(this.connections.keys());
+        for (const id of connectionIds) {
+            if (await this.sendEvent(id, message)) {
+                sent++;
+            }
+        }
+        return sent;
+    }
+    /**
+     * Broadcast an event to connections matching a predicate.
+     *
+     * @param message - The SSE message to broadcast
+     * @param predicate - Function to filter connections
+     * @returns Number of clients the message was sent to
+     */
+    async broadcastIf(message, predicate) {
+        let sent = 0;
+        for (const [id, connection] of this.connections) {
+            if (predicate(connection) && (await this.sendEvent(id, message))) {
+                sent++;
+            }
+        }
+        return sent;
+    }
+    /**
+     * Get all active connections.
+     */
+    getConnections() {
+        return Array.from(this.connections.values());
+    }
+    /**
+     * Get the number of active connections.
+     */
+    getConnectionCount() {
+        return this.connections.size;
+    }
+    /**
+     * Close a specific connection.
+     *
+     * This gracefully ends the SSE stream by calling the underlying `reply.sse.close()`.
+     * All previously sent data is flushed to the client before the connection terminates.
+     * Use this to signal end-of-stream after sending all events (e.g., in request-response
+     * style streaming like OpenAI completions).
+     *
+     * @param connectionId - The connection to close
+     * @returns true if connection was found and closed
+     */
+    closeConnection(connectionId) {
+        const connection = this.connections.get(connectionId);
+        if (!connection) {
+            return false;
+        }
+        try {
+            const reply = connection.reply;
+            reply.sse.close();
+        }
+        catch {
+            // Connection may already be closed
+        }
+        // Use unregisterConnection to ensure hooks and spy are notified
+        this.unregisterConnection(connectionId);
+        return true;
+    }
+    /**
+     * Close all active connections.
+     * Called during graceful shutdown via asyncDispose.
+     */
+    closeAllConnections() {
+        const connectionIds = Array.from(this.connections.keys());
+        for (const id of connectionIds) {
+            this.closeConnection(id);
+        }
+    }
+    /**
+     * Register a connection (called internally by route builder).
+     * Triggers the onConnectionEstablished hook and spy if defined.
+     * @internal
+     */
+    registerConnection(connection) {
+        this.connections.set(connection.id, connection);
+        this.onConnectionEstablished?.(connection);
+        // Notify spy after hook (so hook can set context before spy sees it)
+        this._connectionSpy?.addConnection(connection);
+    }
+    /**
+     * Unregister a connection (called internally by route builder).
+     * Triggers the onConnectionClosed hook and spy if defined.
+     * This method is idempotent - calling it multiple times for the same
+     * connection ID has no effect after the first call.
+     * @internal
+     */
+    unregisterConnection(connectionId) {
+        const connection = this.connections.get(connectionId);
+        if (!connection) {
+            // Already unregistered or never existed - do nothing (idempotent)
+            return;
+        }
+        this.onConnectionClosed?.(connection);
+        // Notify spy of disconnection
+        this._connectionSpy?.addDisconnection(connectionId);
+        this.connections.delete(connectionId);
+    }
+}
+//# sourceMappingURL=AbstractSSEController.js.map

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

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

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

@@ -0,0 +1,55 @@
+import type { SSEConnection } from './AbstractSSEController.ts';
+export type SSEConnectionEvent = {
+    type: 'connect' | 'disconnect';
+    connectionId: string;
+    connection?: SSEConnection;
+};
+/**
+ * Connection spy for testing SSE controllers.
+ * Tracks connection and disconnection events separately.
+ */
+export declare class SSEConnectionSpy {
+    private events;
+    private activeConnections;
+    private claimedConnections;
+    private connectionWaiters;
+    private disconnectionWaiters;
+    /** @internal Called when a connection is established */
+    addConnection(connection: SSEConnection): void;
+    /** @internal Called when a connection is closed */
+    addDisconnection(connectionId: string): void;
+    /**
+     * Wait for a connection to be established.
+     *
+     * @param options.timeout - Timeout in milliseconds (default: 5000)
+     * @param options.predicate - Optional predicate to match a specific connection.
+     *   When provided, waits for an unclaimed connection that matches the predicate.
+     *   Connections are "claimed" when returned by waitForConnection, allowing
+     *   multiple sequential waits for the same URL path.
+     *
+     * @example
+     * ```typescript
+     * // Wait for any connection
+     * const conn = await spy.waitForConnection()
+     *
+     * // Wait for a connection with specific URL
+     * const conn = await spy.waitForConnection({
+     *   predicate: (c) => c.request.url.includes('/api/notifications'),
+     * })
+     * ```
+     */
+    waitForConnection(options?: {
+        timeout?: number;
+        predicate?: (connection: SSEConnection) => boolean;
+    }): Promise<SSEConnection>;
+    /** Wait for a specific connection to disconnect */
+    waitForDisconnection(connectionId: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /** Check if a connection is currently active */
+    isConnected(connectionId: string): boolean;
+    /** Get all connection events in order, optionally filtered by connectionId */
+    getEvents(connectionId?: string): SSEConnectionEvent[];
+    /** Clear all events and cancel pending waiters */
+    clear(): void;
+}

package/dist/lib/sse/SSEConnectionSpy.js

@@ -0,0 +1,136 @@
+/**
+ * Connection spy for testing SSE controllers.
+ * Tracks connection and disconnection events separately.
+ */
+export class SSEConnectionSpy {
+    events = [];
+    activeConnections = new Set();
+    claimedConnections = new Set();
+    connectionWaiters = [];
+    disconnectionWaiters = [];
+    /** @internal Called when a connection is established */
+    addConnection(connection) {
+        this.events.push({ type: 'connect', connectionId: connection.id, connection });
+        this.activeConnections.add(connection.id);
+        // Find and resolve first matching connection waiter
+        const waiterIndex = this.connectionWaiters.findIndex((w) => !w.predicate || w.predicate(connection));
+        if (waiterIndex !== -1) {
+            // biome-ignore lint/style/noNonNullAssertion: we just received this index
+            const waiter = this.connectionWaiters[waiterIndex];
+            this.connectionWaiters.splice(waiterIndex, 1);
+            clearTimeout(waiter.timeoutId);
+            this.claimedConnections.add(connection.id);
+            waiter.resolve(connection);
+        }
+    }
+    /** @internal Called when a connection is closed */
+    addDisconnection(connectionId) {
+        this.events.push({ type: 'disconnect', connectionId });
+        this.activeConnections.delete(connectionId);
+        // Resolve all pending disconnection waiters for this connection
+        const matchingWaiters = this.disconnectionWaiters.filter((w) => w.connectionId === connectionId);
+        for (const waiter of matchingWaiters) {
+            clearTimeout(waiter.timeoutId);
+            waiter.resolve();
+        }
+        this.disconnectionWaiters = this.disconnectionWaiters.filter((w) => w.connectionId !== connectionId);
+    }
+    /**
+     * Wait for a connection to be established.
+     *
+     * @param options.timeout - Timeout in milliseconds (default: 5000)
+     * @param options.predicate - Optional predicate to match a specific connection.
+     *   When provided, waits for an unclaimed connection that matches the predicate.
+     *   Connections are "claimed" when returned by waitForConnection, allowing
+     *   multiple sequential waits for the same URL path.
+     *
+     * @example
+     * ```typescript
+     * // Wait for any connection
+     * const conn = await spy.waitForConnection()
+     *
+     * // Wait for a connection with specific URL
+     * const conn = await spy.waitForConnection({
+     *   predicate: (c) => c.request.url.includes('/api/notifications'),
+     * })
+     * ```
+     */
+    waitForConnection(options) {
+        const timeout = options?.timeout ?? 5000;
+        const predicate = options?.predicate;
+        // Check if a matching unclaimed connection already exists (must still be active)
+        const connectEvent = this.events.find((e) => e.type === 'connect' &&
+            e.connection &&
+            !this.claimedConnections.has(e.connection.id) &&
+            this.activeConnections.has(e.connection.id) &&
+            (!predicate || predicate(e.connection)));
+        if (connectEvent?.connection) {
+            this.claimedConnections.add(connectEvent.connection.id);
+            return Promise.resolve(connectEvent.connection);
+        }
+        // No matching connection yet, create a waiter
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                const index = this.connectionWaiters.findIndex((w) => w.resolve === resolve);
+                if (index !== -1) {
+                    this.connectionWaiters.splice(index, 1);
+                }
+                reject(new Error(`Timeout waiting for connection after ${timeout}ms`));
+            }, timeout);
+            this.connectionWaiters.push({ resolve, reject, timeoutId, predicate });
+        });
+    }
+    /** Wait for a specific connection to disconnect */
+    waitForDisconnection(connectionId, options) {
+        const timeout = options?.timeout ?? 5000;
+        // Check if already disconnected
+        const hasDisconnected = this.events.some((e) => e.type === 'disconnect' && e.connectionId === connectionId);
+        if (hasDisconnected) {
+            return Promise.resolve();
+        }
+        // Not disconnected yet, create a waiter
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                connectionId,
+                resolve,
+                reject,
+                timeoutId: setTimeout(() => {
+                    const index = this.disconnectionWaiters.indexOf(waiter);
+                    if (index !== -1) {
+                        this.disconnectionWaiters.splice(index, 1);
+                    }
+                    reject(new Error(`Timeout waiting for disconnection after ${timeout}ms`));
+                }, timeout),
+            };
+            this.disconnectionWaiters.push(waiter);
+        });
+    }
+    /** Check if a connection is currently active */
+    isConnected(connectionId) {
+        return this.activeConnections.has(connectionId);
+    }
+    /** Get all connection events in order, optionally filtered by connectionId */
+    getEvents(connectionId) {
+        if (connectionId === undefined) {
+            return [...this.events];
+        }
+        return this.events.filter((e) => e.connectionId === connectionId);
+    }
+    /** Clear all events and cancel pending waiters */
+    clear() {
+        this.events = [];
+        this.activeConnections.clear();
+        this.claimedConnections.clear();
+        for (const waiter of this.connectionWaiters) {
+            clearTimeout(waiter.timeoutId);
+            waiter.reject(new Error('ConnectionSpy was cleared'));
+        }
+        for (const waiter of this.disconnectionWaiters) {
+            clearTimeout(waiter.timeoutId);
+            waiter.reject(new Error('ConnectionSpy was cleared'));
+        }
+        this.connectionWaiters = [];
+        this.disconnectionWaiters = [];
+    }
+}
+//# sourceMappingURL=SSEConnectionSpy.js.map

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

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

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

@@ -0,0 +1,5 @@
+export { AbstractSSEController, type BuildSSERoutesReturnType, type InferSSERequest, type SSEConnection, type SSEConnectionEvent, type SSEControllerConfig, type SSEHandlerConfig, type SSELogger, type SSEMessage, type SSEPreHandler, type SSERouteHandler, type SSERouteOptions, } from './AbstractSSEController.js';
+export { SSEConnectionSpy } from './SSEConnectionSpy.js';
+export { type AnySSERouteDefinition, buildPayloadSSERoute, buildSSEHandler, buildSSERoute, type PayloadSSERouteConfig, type SSEMethod, type SSERouteConfig, type SSERouteDefinition, } from './sseContracts.js';
+export { type ParsedSSEEvent, type ParseSSEBufferResult, parseSSEBuffer, parseSSEEvents, } from './sseParser.js';
+export { buildFastifySSERoute, type RegisterSSERoutesOptions } from './sseRouteBuilder.js';

package/dist/lib/sse/index.js

@@ -0,0 +1,6 @@
+export { AbstractSSEController, } from './AbstractSSEController.js';
+export { SSEConnectionSpy } from './SSEConnectionSpy.js';
+export { buildPayloadSSERoute, buildSSEHandler, buildSSERoute, } from './sseContracts.js';
+export { parseSSEBuffer, parseSSEEvents, } from './sseParser.js';
+export { buildFastifySSERoute } from './sseRouteBuilder.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/sse/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,GAYtB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAEL,oBAAoB,EACpB,eAAe,EACf,aAAa,GAKd,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAGL,cAAc,EACd,cAAc,GACf,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,oBAAoB,EAAiC,MAAM,sBAAsB,CAAA"}

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

@@ -0,0 +1,132 @@
+import type { z } from 'zod';
+import type { SSERouteHandler } from './sseTypes.ts';
+/**
+ * Supported HTTP methods for SSE routes.
+ * While traditional SSE uses GET, modern APIs (e.g., OpenAI) use POST
+ * to send request parameters in the body while streaming responses.
+ */
+export type SSEMethod = 'GET' | 'POST' | 'PUT' | 'PATCH';
+/**
+ * Definition for an SSE route with type-safe contracts.
+ *
+ * @template Method - HTTP method (GET, POST, PUT, PATCH)
+ * @template Path - URL path pattern
+ * @template Params - Path parameters schema
+ * @template Query - Query string parameters schema
+ * @template RequestHeaders - Request headers schema
+ * @template Body - Request body schema (for POST/PUT/PATCH)
+ * @template Events - Map of event name to event data schema
+ */
+export type SSERouteDefinition<Method extends SSEMethod = SSEMethod, Path extends string = string, Params extends z.ZodTypeAny = z.ZodTypeAny, Query extends z.ZodTypeAny = z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny = z.ZodTypeAny, Body extends z.ZodTypeAny | undefined = undefined, Events extends Record<string, z.ZodTypeAny> = Record<string, z.ZodTypeAny>> = {
+    method: Method;
+    path: Path;
+    params: Params;
+    query: Query;
+    requestHeaders: RequestHeaders;
+    body: Body;
+    events: Events;
+    isSSE: true;
+};
+/**
+ * Type representing any SSE route definition (for use in generic constraints)
+ */
+export type AnySSERouteDefinition = SSERouteDefinition<SSEMethod, string, z.ZodTypeAny, z.ZodTypeAny, z.ZodTypeAny, z.ZodTypeAny | undefined, Record<string, z.ZodTypeAny>>;
+/**
+ * Configuration for building a GET SSE route
+ */
+export type SSERouteConfig<Path extends string, Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Events extends Record<string, z.ZodTypeAny>> = {
+    path: Path;
+    params: Params;
+    query: Query;
+    requestHeaders: RequestHeaders;
+    events: Events;
+};
+/**
+ * Configuration for building a POST/PUT/PATCH SSE route with request body
+ */
+export type PayloadSSERouteConfig<Path extends string, Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Body extends z.ZodTypeAny, Events extends Record<string, z.ZodTypeAny>> = {
+    method?: 'POST' | 'PUT' | 'PATCH';
+    path: Path;
+    params: Params;
+    query: Query;
+    requestHeaders: RequestHeaders;
+    body: Body;
+    events: Events;
+};
+/**
+ * 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 declare function buildSSERoute<Path extends string, Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Events extends Record<string, z.ZodTypeAny>>(config: SSERouteConfig<Path, Params, Query, RequestHeaders, Events>): SSERouteDefinition<'GET', Path, Params, Query, RequestHeaders, undefined, Events>;
+/**
+ * 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 declare function buildPayloadSSERoute<Path extends string, Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Body extends z.ZodTypeAny, Events extends Record<string, z.ZodTypeAny>>(config: PayloadSSERouteConfig<Path, Params, Query, RequestHeaders, Body, Events>): SSERouteDefinition<'POST' | 'PUT' | 'PATCH', Path, Params, Query, RequestHeaders, Body, Events>;
+/**
+ * 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 declare function buildSSEHandler<Contract extends AnySSERouteDefinition>(_contract: Contract, handler: SSERouteHandler<z.infer<Contract['params']>, z.infer<Contract['query']>, z.infer<Contract['requestHeaders']>, Contract['body'] extends z.ZodTypeAny ? z.infer<Contract['body']> : undefined>): typeof handler;