opinionated-machine 5.1.0 → 5.2.0

package/dist/lib/testing/sseInjectClient.d.ts

@@ -0,0 +1,173 @@
+import type { FastifyInstance } from 'fastify';
+import { type ParsedSSEEvent } from '../sse/sseParser.ts';
+import type { SSEConnectOptions, SSETestConnection } from './sseTestTypes.ts';
+/**
+ * Response from a Fastify inject() call for SSE.
+ */
+export type SSEInjectResponse = {
+    statusCode: number;
+    headers: Record<string, string | string[] | undefined>;
+    body: string;
+};
+/**
+ * SSE connection object returned by SSEInjectClient.
+ *
+ * Represents a completed SSE response from Fastify's inject().
+ * Since inject() waits for the complete response, all events
+ * are available immediately after construction.
+ */
+export declare class SSEInjectConnection implements SSETestConnection {
+    private readonly receivedEvents;
+    private readonly response;
+    constructor(response: SSEInjectResponse);
+    /**
+     * Wait for a specific event by name.
+     * Since inject() returns the complete response, this searches
+     * the already-received events.
+     */
+    waitForEvent(eventName: string, timeout?: number): Promise<ParsedSSEEvent>;
+    /**
+     * Wait for a specific number of events.
+     * Since inject() returns the complete response, this checks
+     * the already-received events.
+     */
+    waitForEvents(count: number, timeout?: number): Promise<ParsedSSEEvent[]>;
+    /**
+     * Get all events received in the response.
+     */
+    getReceivedEvents(): ParsedSSEEvent[];
+    /**
+     * Close the connection. No-op for inject connections since
+     * the response is already complete.
+     */
+    close(): void;
+    /**
+     * Check if the connection has been closed.
+     * Always returns true for inject connections since response is complete.
+     */
+    isClosed(): boolean;
+    /**
+     * Get the HTTP status code from the response.
+     */
+    getStatusCode(): number;
+    /**
+     * Get the response headers.
+     */
+    getHeaders(): Record<string, string | string[] | undefined>;
+}
+/**
+ * SSE client using Fastify's inject() for testing SSE endpoints.
+ *
+ * This client uses Fastify's `inject()` method which simulates HTTP requests
+ * without network overhead. The key characteristic is that `inject()` waits
+ * for the **complete response** before returning, meaning:
+ *
+ * - All events are available immediately after connect() returns
+ * - The SSE handler must close the connection for connect() to complete
+ * - Best suited for SSE streams that have a defined end
+ *
+ * **Ideal for testing:**
+ * - OpenAI-style streaming (POST with body, streams tokens, then closes)
+ * - Short-lived streams that complete after sending all events
+ * - Endpoints where you want to test the full response at once
+ *
+ * **When to use SSEInjectClient vs SSEHttpClient:**
+ *
+ * | SSEInjectClient (this class)        | SSEHttpClient                        |
+ * |-------------------------------------|--------------------------------------|
+ * | Fastify's inject() (no network)     | Real HTTP connection via fetch()    |
+ * | All events returned at once         | Events arrive incrementally         |
+ * | Handler must close the connection   | Connection can stay open            |
+ * | Works without starting server       | Requires running server (listen())  |
+ * | Use for: OpenAI-style, completions  | Use for: notifications, chat, feeds |
+ *
+ * @example
+ * ```typescript
+ * // Testing OpenAI-style chat completion streaming
+ * const client = new SSEInjectClient(app)
+ *
+ * // POST request that streams response and closes
+ * const conn = await client.connectWithBody(
+ *   '/api/chat/completions',
+ *   { model: 'gpt-4', messages: [{ role: 'user', content: 'Hello' }], stream: true }
+ * )
+ *
+ * // connect() returns after handler closes - all events are available
+ * expect(conn.getStatusCode()).toBe(200)
+ *
+ * // Get all events that were streamed
+ * const events = conn.getReceivedEvents()
+ * expect(events[events.length - 1].event).toBe('done')
+ *
+ * // Parse the streamed content
+ * const chunks = events
+ *   .filter(e => e.event === 'chunk')
+ *   .map(e => JSON.parse(e.data).content)
+ * const fullResponse = chunks.join('')
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Testing GET SSE endpoint
+ * const client = new SSEInjectClient(app)
+ * const conn = await client.connect('/api/export/progress', {
+ *   headers: { authorization: 'Bearer token' }
+ * })
+ *
+ * // Wait for specific event type
+ * const completeEvent = await conn.waitForEvent('complete')
+ * expect(JSON.parse(completeEvent.data)).toMatchObject({ status: 'success' })
+ * ```
+ */
+export declare class SSEInjectClient {
+    private readonly app;
+    /**
+     * Create a new SSE inject client.
+     * @param app - Fastify instance (does not need to be listening)
+     */
+    constructor(app: FastifyInstance<any, any, any, any>);
+    /**
+     * Send a GET request to an SSE endpoint.
+     *
+     * Returns when the SSE handler closes the connection.
+     * All events are then available via getReceivedEvents().
+     *
+     * @param url - The endpoint URL (e.g., '/api/stream')
+     * @param options - Optional headers
+     * @returns Connection object with all received events
+     *
+     * @example
+     * ```typescript
+     * const conn = await client.connect('/api/notifications/stream', {
+     *   headers: { authorization: 'Bearer token' }
+     * })
+     * const events = conn.getReceivedEvents()
+     * ```
+     */
+    connect(url: string, options?: Omit<SSEConnectOptions, 'method' | 'body'>): Promise<SSEInjectConnection>;
+    /**
+     * Send a POST/PUT/PATCH request to an SSE endpoint with a body.
+     *
+     * This is the typical pattern for OpenAI-style streaming APIs where
+     * you send a request body and receive a streamed response.
+     *
+     * Returns when the SSE handler closes the connection.
+     * All events are then available via getReceivedEvents().
+     *
+     * @param url - The endpoint URL (e.g., '/api/chat/completions')
+     * @param body - Request body (will be JSON stringified)
+     * @param options - Optional method (defaults to POST) and headers
+     * @returns Connection object with all received events
+     *
+     * @example
+     * ```typescript
+     * const conn = await client.connectWithBody(
+     *   '/api/chat/completions',
+     *   { model: 'gpt-4', messages: [...], stream: true },
+     *   { headers: { authorization: 'Bearer sk-...' } }
+     * )
+     * const chunks = conn.getReceivedEvents().filter(e => e.event === 'chunk')
+     * ```
+     */
+    connectWithBody(url: string, body: unknown, options?: Omit<SSEConnectOptions, 'body'>): Promise<SSEInjectConnection>;
+}

package/dist/lib/testing/sseInjectClient.js

@@ -0,0 +1,234 @@
+import { parseSSEEvents } from "../sse/sseParser.js";
+/**
+ * SSE connection object returned by SSEInjectClient.
+ *
+ * Represents a completed SSE response from Fastify's inject().
+ * Since inject() waits for the complete response, all events
+ * are available immediately after construction.
+ */
+export class SSEInjectConnection {
+    receivedEvents = [];
+    response;
+    constructor(response) {
+        this.response = response;
+        // Parse all events from response body (inject waits for complete response)
+        if (response.body) {
+            const events = parseSSEEvents(response.body);
+            this.receivedEvents.push(...events);
+        }
+    }
+    /**
+     * Wait for a specific event by name.
+     * Since inject() returns the complete response, this searches
+     * the already-received events.
+     */
+    async waitForEvent(eventName, timeout = 5000) {
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeout) {
+            const event = this.receivedEvents.find((e) => e.event === eventName);
+            if (event) {
+                return event;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+        throw new Error(`Timeout waiting for event: ${eventName}`);
+    }
+    /**
+     * Wait for a specific number of events.
+     * Since inject() returns the complete response, this checks
+     * the already-received events.
+     */
+    async waitForEvents(count, timeout = 5000) {
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeout) {
+            if (this.receivedEvents.length >= count) {
+                return this.receivedEvents.slice(0, count);
+            }
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+        throw new Error(`Timeout waiting for ${count} events, received ${this.receivedEvents.length}`);
+    }
+    /**
+     * Get all events received in the response.
+     */
+    getReceivedEvents() {
+        return [...this.receivedEvents];
+    }
+    /**
+     * Close the connection. No-op for inject connections since
+     * the response is already complete.
+     */
+    close() {
+        // No-op - inject() responses are already complete
+    }
+    /**
+     * Check if the connection has been closed.
+     * Always returns true for inject connections since response is complete.
+     */
+    isClosed() {
+        return true;
+    }
+    /**
+     * Get the HTTP status code from the response.
+     */
+    getStatusCode() {
+        return this.response.statusCode;
+    }
+    /**
+     * Get the response headers.
+     */
+    getHeaders() {
+        return this.response.headers;
+    }
+}
+/**
+ * SSE client using Fastify's inject() for testing SSE endpoints.
+ *
+ * This client uses Fastify's `inject()` method which simulates HTTP requests
+ * without network overhead. The key characteristic is that `inject()` waits
+ * for the **complete response** before returning, meaning:
+ *
+ * - All events are available immediately after connect() returns
+ * - The SSE handler must close the connection for connect() to complete
+ * - Best suited for SSE streams that have a defined end
+ *
+ * **Ideal for testing:**
+ * - OpenAI-style streaming (POST with body, streams tokens, then closes)
+ * - Short-lived streams that complete after sending all events
+ * - Endpoints where you want to test the full response at once
+ *
+ * **When to use SSEInjectClient vs SSEHttpClient:**
+ *
+ * | SSEInjectClient (this class)        | SSEHttpClient                        |
+ * |-------------------------------------|--------------------------------------|
+ * | Fastify's inject() (no network)     | Real HTTP connection via fetch()    |
+ * | All events returned at once         | Events arrive incrementally         |
+ * | Handler must close the connection   | Connection can stay open            |
+ * | Works without starting server       | Requires running server (listen())  |
+ * | Use for: OpenAI-style, completions  | Use for: notifications, chat, feeds |
+ *
+ * @example
+ * ```typescript
+ * // Testing OpenAI-style chat completion streaming
+ * const client = new SSEInjectClient(app)
+ *
+ * // POST request that streams response and closes
+ * const conn = await client.connectWithBody(
+ *   '/api/chat/completions',
+ *   { model: 'gpt-4', messages: [{ role: 'user', content: 'Hello' }], stream: true }
+ * )
+ *
+ * // connect() returns after handler closes - all events are available
+ * expect(conn.getStatusCode()).toBe(200)
+ *
+ * // Get all events that were streamed
+ * const events = conn.getReceivedEvents()
+ * expect(events[events.length - 1].event).toBe('done')
+ *
+ * // Parse the streamed content
+ * const chunks = events
+ *   .filter(e => e.event === 'chunk')
+ *   .map(e => JSON.parse(e.data).content)
+ * const fullResponse = chunks.join('')
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Testing GET SSE endpoint
+ * const client = new SSEInjectClient(app)
+ * const conn = await client.connect('/api/export/progress', {
+ *   headers: { authorization: 'Bearer token' }
+ * })
+ *
+ * // Wait for specific event type
+ * const completeEvent = await conn.waitForEvent('complete')
+ * expect(JSON.parse(completeEvent.data)).toMatchObject({ status: 'success' })
+ * ```
+ */
+export class SSEInjectClient {
+    // biome-ignore lint/suspicious/noExplicitAny: Fastify instance types are complex
+    app;
+    /**
+     * Create a new SSE inject client.
+     * @param app - Fastify instance (does not need to be listening)
+     */
+    // biome-ignore lint/suspicious/noExplicitAny: Fastify instance types are complex
+    constructor(app) {
+        this.app = app;
+    }
+    /**
+     * Send a GET request to an SSE endpoint.
+     *
+     * Returns when the SSE handler closes the connection.
+     * All events are then available via getReceivedEvents().
+     *
+     * @param url - The endpoint URL (e.g., '/api/stream')
+     * @param options - Optional headers
+     * @returns Connection object with all received events
+     *
+     * @example
+     * ```typescript
+     * const conn = await client.connect('/api/notifications/stream', {
+     *   headers: { authorization: 'Bearer token' }
+     * })
+     * const events = conn.getReceivedEvents()
+     * ```
+     */
+    async connect(url, options) {
+        const response = await this.app.inject({
+            method: 'GET',
+            url,
+            headers: {
+                accept: 'text/event-stream',
+                ...options?.headers,
+            },
+        });
+        return new SSEInjectConnection({
+            statusCode: response.statusCode,
+            headers: response.headers,
+            body: response.body,
+        });
+    }
+    /**
+     * Send a POST/PUT/PATCH request to an SSE endpoint with a body.
+     *
+     * This is the typical pattern for OpenAI-style streaming APIs where
+     * you send a request body and receive a streamed response.
+     *
+     * Returns when the SSE handler closes the connection.
+     * All events are then available via getReceivedEvents().
+     *
+     * @param url - The endpoint URL (e.g., '/api/chat/completions')
+     * @param body - Request body (will be JSON stringified)
+     * @param options - Optional method (defaults to POST) and headers
+     * @returns Connection object with all received events
+     *
+     * @example
+     * ```typescript
+     * const conn = await client.connectWithBody(
+     *   '/api/chat/completions',
+     *   { model: 'gpt-4', messages: [...], stream: true },
+     *   { headers: { authorization: 'Bearer sk-...' } }
+     * )
+     * const chunks = conn.getReceivedEvents().filter(e => e.event === 'chunk')
+     * ```
+     */
+    async connectWithBody(url, body, options) {
+        const response = await this.app.inject({
+            method: options?.method ?? 'POST',
+            url,
+            headers: {
+                accept: 'text/event-stream',
+                'content-type': 'application/json',
+                ...options?.headers,
+            },
+            payload: JSON.stringify(body),
+        });
+        return new SSEInjectConnection({
+            statusCode: response.statusCode,
+            headers: response.headers,
+            body: response.body,
+        });
+    }
+}
+//# sourceMappingURL=sseInjectClient.js.map

package/dist/lib/testing/sseInjectClient.js.map

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

package/dist/lib/testing/sseInjectHelpers.d.ts

@@ -0,0 +1,59 @@
+import type { FastifyInstance } from 'fastify';
+import type { z } from 'zod';
+import type { SSERouteDefinition } from '../sse/sseContracts.ts';
+import type { InjectPayloadSSEOptions, InjectSSEOptions, InjectSSEResult } from './sseTestTypes.ts';
+/**
+ * Build URL from contract path and params.
+ * @internal
+ */
+export declare function buildUrl<Contract extends {
+    path: string;
+}>(contract: Contract, params?: Record<string, string>, query?: Record<string, unknown>): string;
+/**
+ * Inject a GET SSE request using a contract definition.
+ *
+ * Best for testing SSE endpoints that complete (streaming responses).
+ * For long-lived connections, use `connectSSE` with a real HTTP server.
+ *
+ * @param app - Fastify instance
+ * @param contract - SSE route contract
+ * @param options - Request options (params, query, headers)
+ *
+ * @example
+ * ```typescript
+ * const { closed } = injectSSE(app, streamContract, {
+ *   query: { userId: 'user-123' },
+ * })
+ * const result = await closed
+ * const events = parseSSEEvents(result.body)
+ * ```
+ */
+export declare function injectSSE<Contract extends SSERouteDefinition<'GET', string, z.ZodTypeAny, z.ZodTypeAny, z.ZodTypeAny, undefined, Record<string, z.ZodTypeAny>>>(app: FastifyInstance<any, any, any, any>, contract: Contract, options?: InjectSSEOptions<Contract>): InjectSSEResult;
+/**
+ * Inject a POST/PUT/PATCH SSE request using a contract definition.
+ *
+ * This helper is designed for testing OpenAI-style streaming APIs where
+ * the request includes a body and the response streams events.
+ *
+ * @param app - Fastify instance
+ * @param contract - SSE route contract with body
+ * @param options - Request options (params, query, headers, body)
+ *
+ * @example
+ * ```typescript
+ * // Fire the SSE request
+ * const { closed } = injectPayloadSSE(app, chatCompletionContract, {
+ *   body: { message: 'Hello', stream: true },
+ *   headers: { authorization: 'Bearer token' },
+ * })
+ *
+ * // Wait for streaming to complete and get full response
+ * const result = await closed
+ * const events = parseSSEEvents(result.body)
+ *
+ * expect(events).toContainEqual(
+ *   expect.objectContaining({ event: 'chunk' })
+ * )
+ * ```
+ */
+export declare function injectPayloadSSE<Contract extends SSERouteDefinition<'POST' | 'PUT' | 'PATCH', string, z.ZodTypeAny, z.ZodTypeAny, z.ZodTypeAny, z.ZodTypeAny, Record<string, z.ZodTypeAny>>>(app: FastifyInstance<any, any, any, any>, contract: Contract, options: InjectPayloadSSEOptions<Contract>): InjectSSEResult;

package/dist/lib/testing/sseInjectHelpers.js

@@ -0,0 +1,117 @@
+/**
+ * Build URL from contract path and params.
+ * @internal
+ */
+export function buildUrl(contract, params, query) {
+    let url = contract.path;
+    // Substitute path params
+    if (params) {
+        for (const [key, value] of Object.entries(params)) {
+            url = url.replace(`:${key}`, encodeURIComponent(String(value)));
+        }
+    }
+    // Add query string
+    if (query && Object.keys(query).length > 0) {
+        const searchParams = new URLSearchParams();
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined && value !== null) {
+                searchParams.append(key, String(value));
+            }
+        }
+        const queryString = searchParams.toString();
+        if (queryString) {
+            url = `${url}?${queryString}`;
+        }
+    }
+    return url;
+}
+/**
+ * Inject a GET SSE request using a contract definition.
+ *
+ * Best for testing SSE endpoints that complete (streaming responses).
+ * For long-lived connections, use `connectSSE` with a real HTTP server.
+ *
+ * @param app - Fastify instance
+ * @param contract - SSE route contract
+ * @param options - Request options (params, query, headers)
+ *
+ * @example
+ * ```typescript
+ * const { closed } = injectSSE(app, streamContract, {
+ *   query: { userId: 'user-123' },
+ * })
+ * const result = await closed
+ * const events = parseSSEEvents(result.body)
+ * ```
+ */
+export function injectSSE(
+// biome-ignore lint/suspicious/noExplicitAny: Fastify instance types are complex
+app, contract, options) {
+    const url = buildUrl(contract, options?.params, options?.query);
+    // Start the request - this promise resolves when connection closes
+    const closed = app
+        .inject({
+        method: 'GET',
+        url,
+        headers: {
+            accept: 'text/event-stream',
+            ...options?.headers,
+        },
+    })
+        .then((res) => ({
+        statusCode: res.statusCode,
+        headers: res.headers,
+        body: res.body,
+    }));
+    return { closed };
+}
+/**
+ * Inject a POST/PUT/PATCH SSE request using a contract definition.
+ *
+ * This helper is designed for testing OpenAI-style streaming APIs where
+ * the request includes a body and the response streams events.
+ *
+ * @param app - Fastify instance
+ * @param contract - SSE route contract with body
+ * @param options - Request options (params, query, headers, body)
+ *
+ * @example
+ * ```typescript
+ * // Fire the SSE request
+ * const { closed } = injectPayloadSSE(app, chatCompletionContract, {
+ *   body: { message: 'Hello', stream: true },
+ *   headers: { authorization: 'Bearer token' },
+ * })
+ *
+ * // Wait for streaming to complete and get full response
+ * const result = await closed
+ * const events = parseSSEEvents(result.body)
+ *
+ * expect(events).toContainEqual(
+ *   expect.objectContaining({ event: 'chunk' })
+ * )
+ * ```
+ */
+export function injectPayloadSSE(
+// biome-ignore lint/suspicious/noExplicitAny: Fastify instance types are complex
+app, contract, options) {
+    const url = buildUrl(contract, options.params, options.query);
+    const closed = app
+        .inject({
+        method: contract.method,
+        url,
+        headers: {
+            accept: 'text/event-stream',
+            'content-type': 'application/json',
+            ...options.headers,
+        },
+        payload: JSON.stringify(options.body),
+    })
+        .then((res) => ({
+        statusCode: res.statusCode,
+        headers: res.headers,
+        body: res.body,
+    }));
+    return { closed };
+}
+//# sourceMappingURL=sseInjectHelpers.js.map

package/dist/lib/testing/sseInjectHelpers.js.map

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

package/dist/lib/testing/sseTestServer.d.ts

@@ -0,0 +1,93 @@
+import { type FastifyInstance } from 'fastify';
+import type { CreateSSETestServerOptions } from './sseTestTypes.ts';
+/**
+ * Test server for SSE e2e testing with automatic setup and cleanup.
+ *
+ * This class simplifies SSE e2e test setup by:
+ * - Creating a Fastify instance with @fastify/sse plugin pre-registered
+ * - Starting a real HTTP server on a random port
+ * - Providing a base URL for making HTTP requests
+ * - Handling cleanup on close()
+ *
+ * **When to use SSETestServer:**
+ * - Testing with `SSEHttpClient` (requires real HTTP server)
+ * - E2E tests that need to verify actual network behavior
+ * - Tests that need to run controller code in a real server context
+ *
+ * **Note:** For simple tests using `SSEInjectClient`, you don't need this class -
+ * you can use the Fastify instance directly without starting a server.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const server = await SSETestServer.create(async (app) => {
+ *   // Register your SSE routes
+ *   app.get('/api/events', async (request, reply) => {
+ *     reply.sse({ event: 'message', data: { hello: 'world' } })
+ *     reply.sseClose()
+ *   })
+ * })
+ *
+ * // Connect using SSEHttpClient
+ * const client = await SSEHttpClient.connect(server.baseUrl, '/api/events')
+ * const events = await client.collectEvents(1)
+ * expect(events[0].event).toBe('message')
+ *
+ * // Cleanup
+ * client.close()
+ * await server.close()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom resources (e.g., DI container, controllers)
+ * const server = await SSETestServer.create(
+ *   async (app) => {
+ *     // Routes can access resources via closure
+ *     myController.registerRoutes(app)
+ *   },
+ *   {
+ *     configureApp: async (app) => {
+ *       // Configure validators, plugins, etc.
+ *       app.setValidatorCompiler(validatorCompiler)
+ *     },
+ *     setup: async () => {
+ *       // Create resources that will be available via server.resources
+ *       const container = createContainer()
+ *       const controller = container.resolve('sseController')
+ *       return { container, controller }
+ *     },
+ *   }
+ * )
+ *
+ * // Access resources to interact with the server
+ * const { controller } = server.resources
+ * controller.broadcastEvent({ event: 'update', data: { value: 42 } })
+ *
+ * await server.close()
+ * ```
+ */
+export declare class SSETestServer<T = undefined> {
+    /** The Fastify instance */
+    readonly app: FastifyInstance;
+    /** Base URL for the running server (e.g., "http://localhost:3000") */
+    readonly baseUrl: string;
+    /** Custom resources from setup function */
+    readonly resources: T;
+    private constructor();
+    /**
+     * Create and start a test server.
+     * @param registerRoutes - Function to register routes on the Fastify instance
+     */
+    static create(registerRoutes: (app: FastifyInstance) => void | Promise<void>): Promise<SSETestServer<undefined>>;
+    /**
+     * Create and start a test server with custom options and resources.
+     * @param registerRoutes - Function to register routes on the Fastify instance
+     * @param options - Configuration options including setup function
+     */
+    static create<T>(registerRoutes: (app: FastifyInstance) => void | Promise<void>, options: CreateSSETestServerOptions<T>): Promise<SSETestServer<T>>;
+    /**
+     * Close the server and cleanup resources.
+     */
+    close(): Promise<void>;
+}