opinionated-machine 5.1.0 → 5.2.0

package/dist/lib/testing/sseTestServer.js

@@ -0,0 +1,108 @@
+import FastifySSEPlugin from '@fastify/sse';
+import fastify, {} from 'fastify';
+/**
+ * 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 class SSETestServer {
+    /** The Fastify instance */
+    app;
+    /** Base URL for the running server (e.g., "http://localhost:3000") */
+    baseUrl;
+    /** Custom resources from setup function */
+    resources;
+    constructor(app, baseUrl, resources) {
+        this.app = app;
+        this.baseUrl = baseUrl;
+        this.resources = resources;
+    }
+    static async create(registerRoutes, options) {
+        // Create Fastify app
+        const app = fastify();
+        // Register SSE plugin (type assertion needed due to @fastify/sse's module.exports pattern)
+        await app.register(FastifySSEPlugin);
+        // Run custom configuration
+        if (options?.configureApp) {
+            await options.configureApp(app);
+        }
+        // Setup custom resources
+        const resources = options?.setup ? await options.setup() : undefined;
+        // Register routes
+        await registerRoutes(app);
+        // Start the server on random port
+        await app.listen({ port: 0 });
+        const address = app.server.address();
+        const baseUrl = typeof address === 'string' ? address : `http://localhost:${address?.port}`;
+        return new SSETestServer(app, baseUrl, resources);
+    }
+    /**
+     * Close the server and cleanup resources.
+     */
+    async close() {
+        await this.app.close();
+    }
+}
+//# sourceMappingURL=sseTestServer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sseTestServer.js","sourceRoot":"","sources":["../../../lib/testing/sseTestServer.ts"],"names":[],"mappings":"AAAA,OAAO,gBAAgB,MAAM,cAAc,CAAA;AAC3C,OAAO,OAAO,EAAE,EAAwB,MAAM,SAAS,CAAA;AAGvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,MAAM,OAAO,aAAa;IACxB,2BAA2B;IAClB,GAAG,CAAiB;IAC7B,sEAAsE;IAC7D,OAAO,CAAQ;IACxB,2CAA2C;IAClC,SAAS,CAAG;IAErB,YAAoB,GAAoB,EAAE,OAAe,EAAE,SAAY;QACrE,IAAI,CAAC,GAAG,GAAG,GAAG,CAAA;QACd,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QACtB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;IAC5B,CAAC;IAkBD,MAAM,CAAC,KAAK,CAAC,MAAM,CACjB,cAA8D,EAC9D,OAAuC;QAEvC,qBAAqB;QACrB,MAAM,GAAG,GAAG,OAAO,EAAE,CAAA;QAErB,2FAA2F;QAC3F,MAAM,GAAG,CAAC,QAAQ,CAAC,gBAAiE,CAAC,CAAA;QAErF,2BAA2B;QAC3B,IAAI,OAAO,EAAE,YAAY,EAAE,CAAC;YAC1B,MAAM,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAA;QACjC,CAAC;QAED,yBAAyB;QACzB,MAAM,SAAS,GAAG,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAE,SAAe,CAAA;QAE3E,kBAAkB;QAClB,MAAM,cAAc,CAAC,GAAG,CAAC,CAAA;QAEzB,kCAAkC;QAClC,MAAM,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAA;QAC7B,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAA;QACpC,MAAM,OAAO,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,oBAAoB,OAAO,EAAE,IAAI,EAAE,CAAA;QAE3F,OAAO,IAAI,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC,CAAA;IACnD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAA;IACxB,CAAC;CACF"}

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

@@ -0,0 +1,106 @@
+import type { FastifyInstance } from 'fastify';
+import type { z } from 'zod';
+import type { AnySSERouteDefinition } from '../sse/sseContracts.ts';
+import type { ParsedSSEEvent } from '../sse/sseParser.ts';
+/**
+ * Represents an active SSE test connection (inject-based).
+ *
+ * This interface is used with Fastify's inject() for testing SSE endpoints
+ * synchronously. For long-lived connections, use SSEHttpClient instead.
+ */
+export interface SSETestConnection {
+    /**
+     * Wait for a specific event by name.
+     * @param eventName - The event name to wait for
+     * @param timeout - Timeout in milliseconds (default: 5000)
+     */
+    waitForEvent(eventName: string, timeout?: number): Promise<ParsedSSEEvent>;
+    /**
+     * Wait for a specific number of events.
+     * @param count - Number of events to wait for
+     * @param timeout - Timeout in milliseconds (default: 5000)
+     */
+    waitForEvents(count: number, timeout?: number): Promise<ParsedSSEEvent[]>;
+    /**
+     * Get all events received so far.
+     */
+    getReceivedEvents(): ParsedSSEEvent[];
+    /**
+     * Close the connection.
+     */
+    close(): void;
+    /**
+     * Check if connection is closed.
+     */
+    isClosed(): boolean;
+    /**
+     * Get the HTTP response status code.
+     */
+    getStatusCode(): number;
+    /**
+     * Get response headers.
+     */
+    getHeaders(): Record<string, string | string[] | undefined>;
+}
+/**
+ * Options for establishing an SSE connection.
+ */
+export type SSEConnectOptions = {
+    headers?: Record<string, string>;
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH';
+    body?: unknown;
+};
+/**
+ * Options for injectSSE (GET SSE routes).
+ */
+export type InjectSSEOptions<Contract extends AnySSERouteDefinition> = {
+    params?: z.infer<Contract['params']>;
+    query?: z.infer<Contract['query']>;
+    headers?: z.infer<Contract['requestHeaders']>;
+};
+/**
+ * Options for injectPayloadSSE (POST/PUT/PATCH SSE routes).
+ */
+export type InjectPayloadSSEOptions<Contract extends AnySSERouteDefinition> = {
+    params?: z.infer<Contract['params']>;
+    query?: z.infer<Contract['query']>;
+    headers?: z.infer<Contract['requestHeaders']>;
+    body: Contract['body'] extends z.ZodTypeAny ? z.infer<Contract['body']> : never;
+};
+/**
+ * SSE response data.
+ */
+export type SSEResponse = {
+    statusCode: number;
+    headers: Record<string, string | string[] | undefined>;
+    body: string;
+};
+/**
+ * Result of an SSE inject call.
+ *
+ * Note: Fastify's inject() waits for the full response, so these helpers
+ * work best for streaming that completes (OpenAI-style). For long-lived
+ * SSE connections, use `SSEHttpClient` with a real HTTP server instead.
+ */
+export type InjectSSEResult = {
+    /**
+     * Resolves when the response completes with the full SSE body.
+     * Parse the body with `parseSSEEvents()` to get individual events.
+     */
+    closed: Promise<SSEResponse>;
+};
+/**
+ * Options for creating an SSE test server.
+ */
+export type CreateSSETestServerOptions<T> = {
+    /**
+     * Configure the Fastify instance before SSE routes are registered.
+     * Use this to add plugins, validators, etc.
+     */
+    configureApp?: (app: FastifyInstance<any, any, any, any>) => void | Promise<void>;
+    /**
+     * Custom setup function that returns resources to be cleaned up.
+     * The returned value will be passed to the cleanup function.
+     */
+    setup?: () => T | Promise<T>;
+};

package/dist/lib/testing/sseTestTypes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sseTestTypes.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sseTestTypes.js","sourceRoot":"","sources":["../../../lib/testing/sseTestTypes.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,78 +1,80 @@
-{
-    "name": "opinionated-machine",
-    "version": "5.1.0",
-    "description": "Very opinionated DI framework for fastify, built on top of awilix ",
-    "type": "module",
-    "license": "MIT",
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
-    "exports": {
-        ".": "./dist/index.js",
-        "./package.json": "./package.json"
-    },
-    "maintainers": [
-        {
-            "name": "Igor Savin",
-            "email": "kibertoad@gmail.com"
-        }
-    ],
-    "scripts": {
-        "build": "rimraf dist && tsc -p tsconfig.build.json",
-        "lint": "biome check . && tsc",
-        "lint:fix": "biome check --write .",
-        "test": "vitest --typecheck",
-        "test:ci": "npm run test -- --coverage",
-        "prepublishOnly": "npm run build"
-    },
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/kibertoad/opinionated-machine.git"
-    },
-    "dependencies": {
-        "ts-deepmerge": "^7.0.3"
-    },
-    "peerDependencies": {
-        "@lokalise/fastify-api-contracts": ">=5.0.0",
-        "@lokalise/api-contracts": ">=6.0.0",
-        "awilix": ">=12.0.0",
-        "awilix-manager": ">=6.0.0",
-        "fastify": ">=5.0.0",
-        "fastify-type-provider-zod": ">=6.1.0",
-        "zod": ">=4.1.12"
-    },
-    "devDependencies": {
-        "@types/node": "^22.19.1",
-        "@biomejs/biome": "2.3.8",
-        "@lokalise/biome-config": "^3.1.0",
-        "@lokalise/fastify-api-contracts": "^5.0.0",
-        "@lokalise/tsconfig": "^3.0.0",
-        "@lokalise/api-contracts": "^6.1.0",
-        "@vitest/coverage-v8": "^4.0.15",
-        "awilix": "^12.0.5",
-        "awilix-manager": "^6.1.0",
-        "fastify": "^5.6.2",
-        "fastify-type-provider-zod": "^6.1.0",
-        "vitest": "^4.0.15",
-        "rimraf": "^6.1.0",
-        "typescript": "^5.9.3",
-        "zod": "^4.1.13"
-    },
-    "private": false,
-    "publishConfig": {
-        "access": "public"
-    },
-    "keywords": [
-        "dependency",
-        "injection",
-        "opinionated",
-        "awilix",
-        "di",
-        "fastify"
-    ],
-    "homepage": "https://github.com/kibertoad/opinionated-machine",
-    "files": [
-        "README.md",
-        "LICENSE",
-        "dist/*"
-    ]
-}
+{
+    "name": "opinionated-machine",
+    "version": "5.2.0",
+    "description": "Very opinionated DI framework for fastify, built on top of awilix ",
+    "type": "module",
+    "license": "MIT",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": "./dist/index.js",
+        "./package.json": "./package.json"
+    },
+    "maintainers": [
+        {
+            "name": "Igor Savin",
+            "email": "kibertoad@gmail.com"
+        }
+    ],
+    "scripts": {
+        "build": "rimraf dist && tsc -p tsconfig.build.json",
+        "lint": "biome check . && tsc",
+        "lint:fix": "biome check --write .",
+        "test": "vitest --typecheck",
+        "test:ci": "npm run test -- --coverage",
+        "prepublishOnly": "npm run build"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/kibertoad/opinionated-machine.git"
+    },
+    "dependencies": {
+        "@fastify/sse": "^0.4.0",
+        "fast-querystring": "^1.1.2",
+        "ts-deepmerge": "^7.0.3"
+    },
+    "peerDependencies": {
+        "@lokalise/fastify-api-contracts": ">=5.0.0",
+        "@lokalise/api-contracts": ">=6.0.0",
+        "awilix": ">=12.0.0",
+        "awilix-manager": ">=6.0.0",
+        "fastify": ">=5.0.0",
+        "fastify-type-provider-zod": ">=6.1.0",
+        "zod": ">=4.1.12"
+    },
+    "devDependencies": {
+        "@types/node": "^22.19.7",
+        "@biomejs/biome": "2.3.11",
+        "@lokalise/biome-config": "^3.1.1",
+        "@lokalise/fastify-api-contracts": "^5.0.0",
+        "@lokalise/tsconfig": "^3.1.0",
+        "@lokalise/api-contracts": "^6.1.0",
+        "@vitest/coverage-v8": "^4.0.17",
+        "awilix": "^12.0.5",
+        "awilix-manager": "^6.3.0",
+        "fastify": "^5.7.0",
+        "fastify-type-provider-zod": "^6.1.0",
+        "vitest": "^4.0.17",
+        "rimraf": "^6.1.2",
+        "typescript": "^5.9.3",
+        "zod": "^4.3.5"
+    },
+    "private": false,
+    "publishConfig": {
+        "access": "public"
+    },
+    "keywords": [
+        "dependency",
+        "injection",
+        "opinionated",
+        "awilix",
+        "di",
+        "fastify"
+    ],
+    "homepage": "https://github.com/kibertoad/opinionated-machine",
+    "files": [
+        "README.md",
+        "LICENSE",
+        "dist/*"
+    ]
+}