opinionated-machine 5.1.0 → 6.0.0

package/dist/index.d.ts

@@ -4,5 +4,6 @@ export { AbstractTestContextFactory, type CreateTestContextParams, } from './lib
 export type { NestedPartial } from './lib/configUtils.js';
 export { type DependencyInjectionOptions, DIContext, type RegisterDependenciesParams, } from './lib/DIContext.js';
 export { ENABLE_ALL, isAnyMessageQueueConsumerEnabled, isEnqueuedJobWorkersEnabled, isJobQueueEnabled, isMessageQueueConsumerEnabled, isPeriodicJobEnabled, resolveJobQueuesEnabled, } from './lib/diConfigUtils.js';
-export type { EnqueuedJobWorkerModuleOptions, JobQueueModuleOptions, MessageQueueConsumerModuleOptions, PeriodicJobOptions, } from './lib/resolverFunctions.js';
-export { asControllerClass, asEnqueuedJobQueueManagerFunction, asEnqueuedJobWorkerClass, asJobQueueClass, asMessageQueueHandlerClass, asPeriodicJobClass, asPgBossProcessorClass, asRepositoryClass, asServiceClass, asSingletonClass, asSingletonFunction, asUseCaseClass, type EnqueuedJobQueueManager, } from './lib/resolverFunctions.js';
+export * from './lib/resolverFunctions.js';
+export * from './lib/sse/index.js';
+export * from './lib/testing/index.js';

package/dist/index.js

@@ -3,5 +3,9 @@ export { AbstractModule, } from './lib/AbstractModule.js';
 export { AbstractTestContextFactory, } from './lib/AbstractTestContextFactory.js';
 export { DIContext, } from './lib/DIContext.js';
 export { ENABLE_ALL, isAnyMessageQueueConsumerEnabled, isEnqueuedJobWorkersEnabled, isJobQueueEnabled, isMessageQueueConsumerEnabled, isPeriodicJobEnabled, resolveJobQueuesEnabled, } from './lib/diConfigUtils.js';
-export { asControllerClass, asEnqueuedJobQueueManagerFunction, asEnqueuedJobWorkerClass, asJobQueueClass, asMessageQueueHandlerClass, asPeriodicJobClass, asPgBossProcessorClass, asRepositoryClass, asServiceClass, asSingletonClass, asSingletonFunction, asUseCaseClass, } from './lib/resolverFunctions.js';
+export * from './lib/resolverFunctions.js';
+// SSE
+export * from './lib/sse/index.js';
+// SSE testing utilities
+export * from './lib/testing/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAA8B,MAAM,6BAA6B,CAAA;AAC5F,OAAO,EACL,cAAc,GAGf,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,0BAA0B,GAE3B,MAAM,qCAAqC,CAAA;AAE5C,OAAO,EAEL,SAAS,GAEV,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,UAAU,EACV,gCAAgC,EAChC,2BAA2B,EAC3B,iBAAiB,EACjB,6BAA6B,EAC7B,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,wBAAwB,CAAA;AAO/B,OAAO,EACL,iBAAiB,EACjB,iCAAiC,EACjC,wBAAwB,EACxB,eAAe,EACf,0BAA0B,EAC1B,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,GAEf,MAAM,4BAA4B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAA8B,MAAM,6BAA6B,CAAA;AAC5F,OAAO,EACL,cAAc,GAGf,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,0BAA0B,GAE3B,MAAM,qCAAqC,CAAA;AAE5C,OAAO,EAEL,SAAS,GAEV,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,UAAU,EACV,gCAAgC,EAChC,2BAA2B,EAC3B,iBAAiB,EACjB,6BAA6B,EAC7B,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,wBAAwB,CAAA;AAC/B,cAAc,4BAA4B,CAAA;AAC1C,MAAM;AACN,cAAc,oBAAoB,CAAA;AAClC,wBAAwB;AACxB,cAAc,wBAAwB,CAAA"}

package/dist/lib/AbstractController.d.ts

@@ -3,10 +3,10 @@ import type { buildFastifyNoPayloadRoute, buildFastifyPayloadRoute } from '@loka
 import type { z } from 'zod/v4';
 type AnyCommonRouteDefinition = CommonRouteDefinition<any, any, any, any, any, any, any, any>;
 type OptionalZodSchema = z.Schema | undefined;
-type FastifyPayloadRouteReturnType<RequestBody extends OptionalZodSchema, ResponseBody extends OptionalZodSchema, Path extends OptionalZodSchema, Query extends OptionalZodSchema, Headers extends OptionalZodSchema, ResponseHeaders extends OptionalZodSchema, IsNonJSONResponseExpected extends boolean, IsEmptyResponseExpected extends boolean> = ReturnType<typeof buildFastifyPayloadRoute<RequestBody, ResponseBody, Path, Query, Headers, ResponseHeaders, IsNonJSONResponseExpected, IsEmptyResponseExpected>>;
-type FastifyNoPayloadRouteReturnType<RequestBody extends OptionalZodSchema, Path extends OptionalZodSchema, Query extends OptionalZodSchema, Headers extends OptionalZodSchema, ResponseHeaders extends OptionalZodSchema> = ReturnType<typeof buildFastifyNoPayloadRoute<RequestBody, Path, Query, Headers, ResponseHeaders>>;
+type FastifyPayloadRouteReturnType<RequestBody extends OptionalZodSchema, ResponseBody extends OptionalZodSchema, Path extends OptionalZodSchema, Query extends OptionalZodSchema, Headers extends OptionalZodSchema, ResponseHeaders extends OptionalZodSchema, IsNonJSONResponseExpected extends boolean, IsEmptyResponseExpected extends boolean, ResponseSchemasByStatusCode extends Record<number, any> | undefined> = ReturnType<typeof buildFastifyPayloadRoute<RequestBody, ResponseBody, Path, Query, Headers, ResponseHeaders, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>>;
+type FastifyNoPayloadRouteReturnType<RequestBody extends OptionalZodSchema, Path extends OptionalZodSchema, Query extends OptionalZodSchema, Headers extends OptionalZodSchema, ResponseHeaders extends OptionalZodSchema, ResponseSchemasByStatusCode extends Record<number, any> | undefined> = ReturnType<typeof buildFastifyNoPayloadRoute<RequestBody, Path, Query, Headers, ResponseHeaders, ResponseSchemasByStatusCode>>;
 export type BuildRoutesReturnType<APIContracts extends Record<string, AnyCommonRouteDefinition>> = {
-    [K in keyof APIContracts]: APIContracts[K] extends PayloadRouteDefinition<infer RequestBody, infer ResponseBody, infer Path, infer Query, infer Headers, infer ResponseHeaders, infer IsNonJSONResponseExpected, infer IsEmptyResponseExpected, infer _ResponseSchemasByStatusCode> ? FastifyPayloadRouteReturnType<RequestBody, ResponseBody, Path, Query, Headers, ResponseHeaders, IsNonJSONResponseExpected, IsEmptyResponseExpected> : APIContracts[K] extends GetRouteDefinition<infer GetResponseBody, infer GetPath, infer GetQuery, infer GetHeaders, infer GetResponseHeaders, infer _GetIsNonJSONResponseExpected, infer _GetIsEmptyResponseExpected, infer _GetResponseSchemasByStatusCode> | DeleteRouteDefinition<infer DeleteResponseBody, infer DeletePath, infer DeleteQuery, infer DeleteHeaders, infer DeleteResponseHeaders, infer _DeleteIsNonJSONResponseExpected, infer _DeleteIsEmptyResponseExpected, infer _DeleteResponseSchemasByStatusCode> ? FastifyNoPayloadRouteReturnType<GetResponseBody | DeleteResponseBody, GetPath | DeletePath, GetQuery | DeleteQuery, GetHeaders | DeleteHeaders, GetResponseHeaders | DeleteResponseHeaders> : never;
+    [K in keyof APIContracts]: APIContracts[K] extends PayloadRouteDefinition<infer RequestBody, infer ResponseBody, infer Path, infer Query, infer Headers, infer ResponseHeaders, infer IsNonJSONResponseExpected, infer IsEmptyResponseExpected, infer ResponseSchemasByStatusCode> ? FastifyPayloadRouteReturnType<RequestBody, ResponseBody, Path, Query, Headers, ResponseHeaders, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode> : APIContracts[K] extends GetRouteDefinition<infer GetResponseBody, infer GetPath, infer GetQuery, infer GetHeaders, infer GetResponseHeaders, infer _GetIsNonJSONResponseExpected, infer _GetIsEmptyResponseExpected, infer GetResponseSchemasByStatusCode> | DeleteRouteDefinition<infer DeleteResponseBody, infer DeletePath, infer DeleteQuery, infer DeleteHeaders, infer DeleteResponseHeaders, infer _DeleteIsNonJSONResponseExpected, infer _DeleteIsEmptyResponseExpected, infer DeleteResponseSchemasByStatusCode> ? FastifyNoPayloadRouteReturnType<GetResponseBody | DeleteResponseBody, GetPath | DeletePath, GetQuery | DeleteQuery, GetHeaders | DeleteHeaders, GetResponseHeaders | DeleteResponseHeaders, GetResponseSchemasByStatusCode | DeleteResponseSchemasByStatusCode> : never;
 };
 export declare abstract class AbstractController<APIContracts extends Record<string, AnyCommonRouteDefinition>> {
     abstract buildRoutes(): BuildRoutesReturnType<APIContracts>;

package/dist/lib/AbstractController.js.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractController.js","sourceRoot":"","sources":["../../lib/AbstractController.ts"],"names":[],"mappings":"AAoGA,MAAM,OAAgB,kBAAkB;CAIvC"}
+{"version":3,"file":"AbstractController.js","sourceRoot":"","sources":["../../lib/AbstractController.ts"],"names":[],"mappings":"AAkHA,MAAM,OAAgB,kBAAkB;CAIvC"}

package/dist/lib/AbstractModule.d.ts

@@ -9,5 +9,27 @@ export type MandatoryNameAndRegistrationPair<T> = {
 export type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
 export declare abstract class AbstractModule<ModuleDependencies, ExternalDependencies = never> {
     abstract resolveDependencies(diOptions: DependencyInjectionOptions, externalDependencies: ExternalDependencies): MandatoryNameAndRegistrationPair<ModuleDependencies>;
-    abstract resolveControllers(): MandatoryNameAndRegistrationPair<unknown>;
+    /**
+     * Override to register REST and SSE controllers.
+     * Returns empty object by default - no changes needed for modules without controllers.
+     *
+     * Controllers registered here are automatically added to the DI container.
+     * SSE controllers (created with asSSEControllerClass) are automatically detected
+     * and registered for SSE route handling.
+     *
+     * @param diOptions - DI options (use for test mode detection with asSSEControllerClass)
+     *
+     * @example
+     * ```typescript
+     * public resolveControllers(diOptions: DependencyInjectionOptions) {
+     *   return {
+     *     // REST controller
+     *     usersController: asControllerClass(UsersController),
+     *     // SSE controller (automatically detected via isSSEController flag)
+     *     notificationsSSEController: asSSEControllerClass(NotificationsSSEController, { diOptions }),
+     *   }
+     * }
+     * ```
+     */
+    resolveControllers(_diOptions: DependencyInjectionOptions): MandatoryNameAndRegistrationPair<unknown>;
 }

package/dist/lib/AbstractModule.js

@@ -1,3 +1,28 @@
 export class AbstractModule {
+    /**
+     * Override to register REST and SSE controllers.
+     * Returns empty object by default - no changes needed for modules without controllers.
+     *
+     * Controllers registered here are automatically added to the DI container.
+     * SSE controllers (created with asSSEControllerClass) are automatically detected
+     * and registered for SSE route handling.
+     *
+     * @param diOptions - DI options (use for test mode detection with asSSEControllerClass)
+     *
+     * @example
+     * ```typescript
+     * public resolveControllers(diOptions: DependencyInjectionOptions) {
+     *   return {
+     *     // REST controller
+     *     usersController: asControllerClass(UsersController),
+     *     // SSE controller (automatically detected via isSSEController flag)
+     *     notificationsSSEController: asSSEControllerClass(NotificationsSSEController, { diOptions }),
+     *   }
+     * }
+     * ```
+     */
+    resolveControllers(_diOptions) {
+        return {};
+    }
 }
 //# sourceMappingURL=AbstractModule.js.map

package/dist/lib/AbstractModule.js.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractModule.js","sourceRoot":"","sources":["../../lib/AbstractModule.ts"],"names":[],"mappings":"AAcA,MAAM,OAAgB,cAAc;CAOnC"}
+{"version":3,"file":"AbstractModule.js","sourceRoot":"","sources":["../../lib/AbstractModule.ts"],"names":[],"mappings":"AAcA,MAAM,OAAgB,cAAc;IAMlC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACI,kBAAkB,CACvB,UAAsC;QAEtC,OAAO,EAAE,CAAA;IACX,CAAC;CACF"}

package/dist/lib/DIContext.d.ts

@@ -4,6 +4,7 @@ import type { FastifyInstance } from 'fastify';
 import type { AbstractModule } from './AbstractModule.js';
 import { type NestedPartial } from './configUtils.js';
 import type { ENABLE_ALL } from './diConfigUtils.js';
+import { type RegisterSSERoutesOptions } from './sse/sseRouteBuilder.js';
 export type RegisterDependenciesParams<Dependencies, Config, ExternalDependencies> = {
     modules: readonly AbstractModule<unknown, ExternalDependencies>[];
     secondaryModules?: readonly AbstractModule<unknown, ExternalDependencies>[];
@@ -16,17 +17,51 @@ export type DependencyInjectionOptions = {
     enqueuedJobWorkersEnabled?: false | typeof ENABLE_ALL | string[];
     messageQueueConsumersEnabled?: false | typeof ENABLE_ALL | string[];
     periodicJobsEnabled?: false | typeof ENABLE_ALL | string[];
+    /**
+     * Enable SSE test mode features like connection spying.
+     * Only relevant for SSE controllers. Set to true in test environments.
+     * @default false
+     */
+    isTestMode?: boolean;
 };
 export declare class DIContext<Dependencies extends object, Config extends object, ExternalDependencies = undefined> {
     private readonly options;
     readonly awilixManager: AwilixManager;
     readonly diContainer: AwilixContainer<Dependencies>;
     private readonly controllerResolvers;
+    private readonly sseControllerNames;
     private readonly appConfig;
     constructor(diContainer: AwilixContainer, options: DependencyInjectionOptions, appConfig: Config, awilixManager?: AwilixManager);
     private registerModule;
     registerDependencies(params: RegisterDependenciesParams<Dependencies, Config, ExternalDependencies>, externalDependencies: ExternalDependencies, resolveControllers?: boolean): void;
     registerRoutes(app: FastifyInstance<any, any, any, any>): void;
+    /**
+     * Check if any SSE controllers are registered.
+     * Use this to conditionally call registerSSERoutes().
+     */
+    hasSSEControllers(): boolean;
+    /**
+     * Register SSE routes with the Fastify app.
+     *
+     * Must be called separately from registerRoutes().
+     * Requires @fastify/sse plugin to be registered on the app.
+     *
+     * @param app - Fastify instance with @fastify/sse registered
+     * @param options - Optional configuration for SSE routes
+     *
+     * @example
+     * ```typescript
+     * // Register @fastify/sse plugin first
+     * await app.register(fastifySSE, { heartbeatInterval: 30000 })
+     *
+     * // Then register SSE routes
+     * context.registerSSERoutes(app)
+     * ```
+     */
+    registerSSERoutes(app: FastifyInstance<any, any, any, any>, options?: RegisterSSERoutesOptions): void;
+    private applySSERouteOptions;
+    private applyPreHandlers;
+    private applyRateLimit;
     destroy(): Promise<void>;
     init(): Promise<void>;
 }

package/dist/lib/DIContext.js

@@ -1,11 +1,15 @@
 import { AwilixManager } from 'awilix-manager';
+import { merge } from 'ts-deepmerge';
 import { mergeConfigAndDependencyOverrides } from './configUtils.js';
+import { buildFastifySSERoute } from './sse/sseRouteBuilder.js';
 export class DIContext {
     options;
     awilixManager;
     diContainer;
     // biome-ignore lint/suspicious/noExplicitAny: all controllers are controllers
     controllerResolvers;
+    // SSE controller dependency names (resolved from container to preserve singletons)
+    sseControllerNames;
     appConfig;
     constructor(diContainer, options, appConfig, awilixManager) {
         this.options = options;
@@ -21,6 +25,7 @@ export class DIContext {
                     strictBooleanEnforced: true,
                 });
         this.controllerResolvers = [];
+        this.sseControllerNames = [];
     }
     registerModule(module, targetDiConfig, externalDependencies, resolveControllers, isPrimaryModule) {
         const resolvedDIConfig = module.resolveDependencies(this.options, externalDependencies);
@@ -32,7 +37,20 @@ export class DIContext {
             }
         }
         if (isPrimaryModule && resolveControllers) {
-            this.controllerResolvers.push(...Object.values(module.resolveControllers()));
+            const controllers = module.resolveControllers(this.options);
+            for (const [name, resolver] of Object.entries(controllers)) {
+                // @ts-expect-error isSSEController is a custom property on the resolver
+                if (resolver.isSSEController) {
+                    // SSE controller: register in DI container and track name for route registration
+                    this.sseControllerNames.push(name);
+                    // @ts-expect-error we can't really ensure type-safety here
+                    targetDiConfig[name] = resolver;
+                }
+                else {
+                    // REST controller: add resolver for route registration
+                    this.controllerResolvers.push(resolver);
+                }
+            }
         }
     }
     registerDependencies(params, externalDependencies, resolveControllers = true) {
@@ -68,10 +86,99 @@ export class DIContext {
             const controller = controllerResolver.resolve(this.diContainer);
             const routes = controller.buildRoutes();
             for (const route of Object.values(routes)) {
+                // Cast needed: GET/DELETE routes have body:undefined, POST/PATCH have body:unknown
+                // The union is incompatible with app.route() due to handler contravariance
+                app.route(route);
+            }
+        }
+    }
+    /**
+     * Check if any SSE controllers are registered.
+     * Use this to conditionally call registerSSERoutes().
+     */
+    hasSSEControllers() {
+        return this.sseControllerNames.length > 0;
+    }
+    /**
+     * Register SSE routes with the Fastify app.
+     *
+     * Must be called separately from registerRoutes().
+     * Requires @fastify/sse plugin to be registered on the app.
+     *
+     * @param app - Fastify instance with @fastify/sse registered
+     * @param options - Optional configuration for SSE routes
+     *
+     * @example
+     * ```typescript
+     * // Register @fastify/sse plugin first
+     * await app.register(fastifySSE, { heartbeatInterval: 30000 })
+     *
+     * // Then register SSE routes
+     * context.registerSSERoutes(app)
+     * ```
+     */
+    registerSSERoutes(
+    // biome-ignore lint/suspicious/noExplicitAny: Fastify instance types are complex
+    app, options) {
+        if (!this.hasSSEControllers()) {
+            return;
+        }
+        for (const controllerName of this.sseControllerNames) {
+            // Resolve from container to use the singleton instance
+            const sseController = this.diContainer.resolve(controllerName);
+            const sseRoutes = sseController.buildSSERoutes();
+            for (const routeConfig of Object.values(sseRoutes)) {
+                const route = buildFastifySSERoute(sseController, routeConfig);
+                this.applySSERouteOptions(route, options);
                 app.route(route);
             }
         }
     }
+    applySSERouteOptions(route, options) {
+        if (options?.preHandler) {
+            this.applyPreHandlers(route, options.preHandler);
+        }
+        if (options?.rateLimit) {
+            this.applyRateLimit(route, options.rateLimit);
+        }
+        // Apply SSE-specific options (heartbeatInterval, serializer)
+        if (options?.heartbeatInterval !== undefined || options?.serializer !== undefined) {
+            // biome-ignore lint/suspicious/noExplicitAny: config types vary by plugins
+            const routeWithConfig = route;
+            routeWithConfig.config = merge(routeWithConfig.config || {}, {
+                sse: {
+                    ...(options.heartbeatInterval !== undefined && {
+                        heartbeatInterval: options.heartbeatInterval,
+                    }),
+                    ...(options.serializer !== undefined && { serializer: options.serializer }),
+                },
+            });
+        }
+    }
+    applyPreHandlers(route, globalPreHandler) {
+        const existingPreHandler = route.preHandler;
+        if (!existingPreHandler) {
+            route.preHandler = globalPreHandler;
+            return;
+        }
+        // biome-ignore lint/suspicious/noExplicitAny: preHandler types are complex
+        const handlers = Array.isArray(existingPreHandler)
+            ? existingPreHandler
+            : [existingPreHandler];
+        // biome-ignore lint/suspicious/noExplicitAny: preHandler types are complex
+        const globalHandlers = Array.isArray(globalPreHandler)
+            ? globalPreHandler
+            : [globalPreHandler];
+        route.preHandler = [...globalHandlers, ...handlers];
+    }
+    applyRateLimit(route, rateLimit) {
+        // biome-ignore lint/suspicious/noExplicitAny: config types vary by plugins
+        const routeWithConfig = route;
+        routeWithConfig.config = {
+            ...(routeWithConfig.config || {}),
+            rateLimit,
+        };
+    }
     async destroy() {
         await this.awilixManager.executeDispose();
         await this.diContainer.dispose();

package/dist/lib/DIContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"DIContext.js","sourceRoot":"","sources":["../../lib/DIContext.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAI9C,OAAO,EAAE,iCAAiC,EAAsB,MAAM,kBAAkB,CAAA;AAkBxF,MAAM,OAAO,SAAS;IAKH,OAAO,CAA4B;IACpC,aAAa,CAAe;IAC5B,WAAW,CAA+B;IAC1D,8EAA8E;IAC7D,mBAAmB,CAAiB;IACpC,SAAS,CAAQ;IAElC,YACE,WAA4B,EAC5B,OAAmC,EACnC,SAAiB,EACjB,aAA6B;QAE7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QACtB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAA;QAC9B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;QAC1B,IAAI,CAAC,aAAa;YAChB,aAAa;gBACb,IAAI,aAAa,CAAC;oBAChB,YAAY,EAAE,IAAI;oBAClB,SAAS,EAAE,IAAI;oBACf,WAAW;oBACX,WAAW,EAAE,IAAI;oBACjB,qBAAqB,EAAE,IAAI;iBAC5B,CAAC,CAAA;QACJ,IAAI,CAAC,mBAAmB,GAAG,EAAE,CAAA;IAC/B,CAAC;IAEO,cAAc,CACpB,MAAqD,EACrD,cAAqD,EACrD,oBAA0C,EAC1C,kBAA2B,EAC3B,eAAwB;QAExB,MAAM,gBAAgB,GAAG,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAA;QAEvF,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;YACnC,2DAA2D;YAC3D,IAAI,eAAe,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;gBACpD,2DAA2D;gBAC3D,cAAc,CAAC,GAAG,CAAC,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAA;YAC7C,CAAC;QACH,CAAC;QAED,IAAI,eAAe,IAAI,kBAAkB,EAAE,CAAC;YAC1C,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAC3B,GAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAyB,CACvE,CAAA;QACH,CAAC;IACH,CAAC;IAED,oBAAoB,CAClB,MAA8E,EAC9E,oBAA0C,EAC1C,kBAAkB,GAAG,IAAI;QAEzB,MAAM,eAAe,GAAG,iCAAiC,CACvD,IAAI,CAAC,SAAS,EACd,MAAM,CAAC,kBAAkB,IAAI,QAAQ,EACrC,MAAM,CAAC,eAAe,EACtB,MAAM,CAAC,mBAAmB,IAAI,EAAE,CACjC,CAAA;QACD,MAAM,cAAc,GAA0C,EAAE,CAAA;QAEhE,KAAK,MAAM,aAAa,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YAC3C,IAAI,CAAC,cAAc,CACjB,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,IAAI,CACL,CAAA;QACH,CAAC;QAED,IAAI,MAAM,CAAC,gBAAgB,EAAE,CAAC;YAC5B,KAAK,MAAM,eAAe,IAAI,MAAM,CAAC,gBAAgB,EAAE,CAAC;gBACtD,IAAI,CAAC,cAAc,CACjB,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,CACN,CAAA;YACH,CAAC;QACH,CAAC;QAED,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAA;QAEzC,8BAA8B;QAC9B,0CAA0C;QAC1C,KAAK,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC;YAChF,MAAM,eAAe,GAAG,EAAE,GAAI,gBAAsC,EAAE,CAAA;YAEtE,2CAA2C;YAC3C,MAAM,gBAAgB,GAAG,IAAI,CAAC,WAAW,CAAC,eAAe,CAAC,aAAa,CAAC,CAAA;YACxE,mBAAmB;YACnB,IAAI,eAAe,CAAC,QAAQ,KAAK,gBAAgB,CAAC,QAAQ,EAAE,CAAC;gBAC3D,mBAAmB;gBACnB,eAAe,CAAC,QAAQ,GAAG,gBAAgB,CAAC,QAAQ,CAAA;YACtD,CAAC;YAED,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,aAAa,EAAE,eAAe,CAAC,CAAA;QAC3D,CAAC;IACH,CAAC;IAED,4FAA4F;IAC5F,cAAc,CAAC,GAAwC;QACrD,KAAK,MAAM,kBAAkB,IAAI,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAC1D,wEAAwE;YACxE,MAAM,UAAU,GAA4B,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;YACxF,MAAM,MAAM,GAAG,UAAU,CAAC,WAAW,EAAE,CAAA;YACvC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC1C,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,CAAC,aAAa,CAAC,cAAc,EAAE,CAAA;QACzC,MAAM,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAA;IAClC,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,IAAI,CAAC,aAAa,CAAC,WAAW,EAAE,CAAA;IACxC,CAAC;CACF"}
+{"version":3,"file":"DIContext.js","sourceRoot":"","sources":["../../lib/DIContext.ts"],"names":[],"mappings":"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"}

package/dist/lib/resolverFunctions.d.ts

@@ -4,17 +4,51 @@ import type { DependencyInjectionOptions } from './DIContext.js';
 declare module 'awilix' {
     interface ResolverOptions<T> {
         public?: boolean;
+        isSSEController?: boolean;
     }
 }
 export interface EnqueuedJobQueueManager {
     start(enabled?: string[] | boolean): Promise<void>;
 }
 export declare function asSingletonClass<T = object>(Type: Constructor<T>, opts?: BuildResolverOptions<T>): BuildResolver<T> & DisposableResolver<T>;
+/**
+ * Register a class with an additional config parameter passed to the constructor.
+ * Uses asFunction wrapper internally to pass the config as a second parameter.
+ * Requires PROXY injection mode.
+ *
+ * @example
+ * ```typescript
+ * myService: asClassWithConfig(MyService, { enableFeature: true }),
+ * ```
+ */
+export declare function asClassWithConfig<T = object, Config = unknown>(Type: Constructor<T>, config: Config, opts?: BuildResolverOptions<T>): BuildResolver<T> & DisposableResolver<T>;
 export declare function asSingletonFunction<T>(fn: FunctionReturning<T>, opts?: BuildResolverOptions<T>): BuildResolver<T> & DisposableResolver<T>;
 export declare function asServiceClass<T = object>(Type: Constructor<T>, opts?: BuildResolverOptions<T>): BuildResolver<T> & DisposableResolver<T>;
 export declare function asUseCaseClass<T = object>(Type: Constructor<T>, opts?: BuildResolverOptions<T>): BuildResolver<T> & DisposableResolver<T>;
 export declare function asRepositoryClass<T = object>(Type: Constructor<T>, opts?: BuildResolverOptions<T>): BuildResolver<T> & DisposableResolver<T>;
 export declare function asControllerClass<T = object>(Type: Constructor<T>, opts?: BuildResolverOptions<T>): BuildResolver<T> & DisposableResolver<T>;
+export type SSEControllerModuleOptions = {
+    diOptions: DependencyInjectionOptions;
+};
+/**
+ * Register an SSE controller class with the DI container.
+ *
+ * SSE controllers handle Server-Sent Events connections and require
+ * graceful shutdown to close all active connections.
+ *
+ * When `diOptions.isTestMode` is true, connection spying is enabled
+ * allowing tests to await connections via `controller.connectionSpy`.
+ *
+ * @example
+ * ```typescript
+ * // Without test mode
+ * notificationsSSEController: asSSEControllerClass(NotificationsSSEController),
+ *
+ * // With test mode (enables connection spy)
+ * notificationsSSEController: asSSEControllerClass(NotificationsSSEController, { diOptions }),
+ * ```
+ */
+export declare function asSSEControllerClass<T = object>(Type: Constructor<T>, sseOptions?: SSEControllerModuleOptions, opts?: BuildResolverOptions<T>): BuildResolver<T> & DisposableResolver<T>;
 export type MessageQueueConsumerModuleOptions = {
     queueName: string;
     diOptions: DependencyInjectionOptions;

package/dist/lib/resolverFunctions.js

@@ -6,6 +6,23 @@ export function asSingletonClass(Type, opts) {
         lifetime: 'SINGLETON',
     });
 }
+/**
+ * Register a class with an additional config parameter passed to the constructor.
+ * Uses asFunction wrapper internally to pass the config as a second parameter.
+ * Requires PROXY injection mode.
+ *
+ * @example
+ * ```typescript
+ * myService: asClassWithConfig(MyService, { enableFeature: true }),
+ * ```
+ */
+export function asClassWithConfig(Type, config, opts) {
+    // biome-ignore lint/suspicious/noExplicitAny: Dynamic constructor invocation with cradle proxy
+    return asFunction((cradle) => new Type(cradle, config), {
+        ...opts,
+        lifetime: opts?.lifetime ?? 'SINGLETON',
+    });
+}
 export function asSingletonFunction(fn, opts) {
     return asFunction(fn, {
         ...opts,
@@ -40,6 +57,36 @@ export function asControllerClass(Type, opts) {
         lifetime: 'SINGLETON',
     });
 }
+/**
+ * Register an SSE controller class with the DI container.
+ *
+ * SSE controllers handle Server-Sent Events connections and require
+ * graceful shutdown to close all active connections.
+ *
+ * When `diOptions.isTestMode` is true, connection spying is enabled
+ * allowing tests to await connections via `controller.connectionSpy`.
+ *
+ * @example
+ * ```typescript
+ * // Without test mode
+ * notificationsSSEController: asSSEControllerClass(NotificationsSSEController),
+ *
+ * // With test mode (enables connection spy)
+ * notificationsSSEController: asSSEControllerClass(NotificationsSSEController, { diOptions }),
+ * ```
+ */
+export function asSSEControllerClass(Type, sseOptions, opts) {
+    const enableConnectionSpy = sseOptions?.diOptions.isTestMode ?? false;
+    const sseConfig = enableConnectionSpy ? { enableConnectionSpy: true } : undefined;
+    return asClassWithConfig(Type, sseConfig, {
+        public: false,
+        isSSEController: true,
+        asyncDispose: 'closeAllConnections',
+        asyncDisposePriority: 5, // Close SSE connections early in shutdown
+        ...opts,
+        lifetime: 'SINGLETON',
+    });
+}
 export function asMessageQueueHandlerClass(Type, mqOptions, opts) {
     return asClass(Type, {
         // these follow message-queue-toolkit conventions

package/dist/lib/resolverFunctions.js.map

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

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

@@ -0,0 +1,163 @@
+import { SSEConnectionSpy } from './SSEConnectionSpy.ts';
+import type { AnySSERouteDefinition } from './sseContracts.ts';
+import type { BuildSSERoutesReturnType, SSEConnection, SSEControllerConfig, SSEMessage } from './sseTypes.ts';
+export type { SSEConnectionEvent } from './SSEConnectionSpy.ts';
+export { SSEConnectionSpy } from './SSEConnectionSpy.ts';
+export type { BuildSSERoutesReturnType, InferSSERequest, SSEConnection, SSEControllerConfig, SSEHandlerConfig, SSELogger, SSEMessage, SSEPreHandler, SSERouteHandler, SSERouteOptions, } from './sseTypes.ts';
+/**
+ * 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 declare abstract class AbstractSSEController<APIContracts extends Record<string, AnySSERouteDefinition>> {
+    /** Map of connection ID to connection object */
+    protected connections: Map<string, SSEConnection>;
+    /** Private storage for connection spy */
+    private readonly _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: object, sseConfig?: SSEControllerConfig);
+    /**
+     * 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(): SSEConnectionSpy;
+    /**
+     * Build and return SSE route configurations.
+     * Similar pattern to AbstractController.buildRoutes().
+     */
+    abstract buildSSERoutes(): BuildSSERoutesReturnType<APIContracts>;
+    /**
+     * Controller-level hook called when any connection is established.
+     * Override this method to add global connection handling logic.
+     * This is called AFTER the connection is registered and route-level onConnect.
+     *
+     * @param connection - The newly established connection
+     */
+    protected onConnectionEstablished?(connection: SSEConnection): void;
+    /**
+     * Controller-level hook called when any connection is closed.
+     * Override this method to add global disconnect handling logic.
+     * This is called BEFORE the connection is unregistered and route-level onDisconnect.
+     *
+     * @param connection - The connection being closed
+     */
+    protected onConnectionClosed?(connection: SSEConnection): void;
+    /**
+     * 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
+     */
+    protected sendEvent<T>(connectionId: string, message: SSEMessage<T>): Promise<boolean>;
+    /**
+     * Broadcast an event to all connected clients.
+     *
+     * @param message - The SSE message to broadcast
+     * @returns Number of clients the message was sent to
+     */
+    protected broadcast<T>(message: SSEMessage<T>): Promise<number>;
+    /**
+     * 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
+     */
+    protected broadcastIf<T>(message: SSEMessage<T>, predicate: (connection: SSEConnection) => boolean): Promise<number>;
+    /**
+     * Get all active connections.
+     */
+    protected getConnections(): SSEConnection[];
+    /**
+     * Get the number of active connections.
+     */
+    protected getConnectionCount(): number;
+    /**
+     * 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
+     */
+    protected closeConnection(connectionId: string): boolean;
+    /**
+     * Close all active connections.
+     * Called during graceful shutdown via asyncDispose.
+     */
+    closeAllConnections(): void;
+    /**
+     * Register a connection (called internally by route builder).
+     * Triggers the onConnectionEstablished hook and spy if defined.
+     * @internal
+     */
+    registerConnection(connection: SSEConnection): void;
+    /**
+     * 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: string): void;
+}