@composed-di/core 0.5.0-alpha

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Error thrown when there is an issue during the initialization or configuration of a ServiceModule.
+ * This can include circular dependencies or missing dependencies that are detected during module creation.
+ */
+export declare class ServiceModuleInitError extends Error {
+    name: string;
+    constructor(message: string);
+}
+/**
+ * Error thrown when a requested service cannot be found within the ServiceModule.
+ * This typically occurs when no factory has been registered for the given ServiceKey.
+ */
+export declare class ServiceFactoryNotFoundError extends Error {
+    name: string;
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,IAAI,SAA4B;gBAEpB,OAAO,EAAE,MAAM;CAG5B;AAED;;;GAGG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,IAAI,SAAiC;gBAEzB,OAAO,EAAE,MAAM;CAG5B"}

package/dist/errors.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceFactoryNotFoundError = exports.ServiceModuleInitError = void 0;
+/**
+ * Error thrown when there is an issue during the initialization or configuration of a ServiceModule.
+ * This can include circular dependencies or missing dependencies that are detected during module creation.
+ */
+class ServiceModuleInitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ServiceModuleInitError';
+    }
+}
+exports.ServiceModuleInitError = ServiceModuleInitError;
+/**
+ * Error thrown when a requested service cannot be found within the ServiceModule.
+ * This typically occurs when no factory has been registered for the given ServiceKey.
+ */
+class ServiceFactoryNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ServiceFactoryNotFoundError';
+    }
+}
+exports.ServiceFactoryNotFoundError = ServiceFactoryNotFoundError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,MAAa,sBAAuB,SAAQ,KAAK;IAG/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QAHjB,SAAI,GAAG,wBAAwB,CAAC;IAIhC,CAAC;CACF;AAND,wDAMC;AAED;;;GAGG;AACH,MAAa,2BAA4B,SAAQ,KAAK;IAGpD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QAHjB,SAAI,GAAG,6BAA6B,CAAC;IAIrC,CAAC;CACF;AAND,kEAMC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './serviceKey';
+export * from './serviceModule';
+export * from './serviceFactory';
+export * from './serviceScope';
+export * from './serviceSelector';
+export * from './serviceEventListener';
+export * from './errors';
+export * from './utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./serviceKey"), exports);
+__exportStar(require("./serviceModule"), exports);
+__exportStar(require("./serviceFactory"), exports);
+__exportStar(require("./serviceScope"), exports);
+__exportStar(require("./serviceSelector"), exports);
+__exportStar(require("./serviceEventListener"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./utils"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B;AAC7B,kDAAgC;AAChC,mDAAiC;AACjC,iDAA+B;AAC/B,oDAAkC;AAClC,yDAAuC;AACvC,2CAAyB;AACzB,0CAAwB"}

package/dist/serviceEventListener.d.ts

@@ -0,0 +1,120 @@
+import type { ServiceKey } from './serviceKey';
+/**
+ * A handle representing a single in-flight operation (initialization,
+ * disposal, or method call), returned by a ServiceEventListener when the
+ * operation starts.
+ *
+ * Exactly one of `end` or `error` is invoked when the operation finishes,
+ * so implementations can close over per-call state (start time, an
+ * OpenTelemetry span, a correlation id) without any bookkeeping to pair
+ * concurrent start/finish events.
+ */
+export interface EventSpan {
+    /**
+     * Invoked when the operation completes successfully. For methods that
+     * return a promise, this fires when the promise resolves, not when the
+     * method returns.
+     *
+     * Whether to retain or log the outcome is the implementation's choice;
+     * the value is passed by reference, so implementations must not mutate it.
+     *
+     * @param outcome - The outcome of the operation. Present for method call
+     * spans (the return or resolved value) and initialize spans (the service
+     * instance), absent for dispose spans.
+     * @return void
+     */
+    end?(outcome?: EventOutcome): void;
+    /**
+     * Invoked when the operation throws or rejects. Terminal like `end`;
+     * the two are mutually exclusive. The error is rethrown to the caller
+     * after this is invoked.
+     *
+     * @param error - The error object or value that was thrown or rejected.
+     * @return void
+     */
+    error?(error: unknown): void;
+}
+/**
+ * The successful outcome of an operation, delivered to EventSpan.end.
+ * Future fields (e.g. a correlation id) are added here rather than as
+ * extra parameters.
+ */
+export interface EventOutcome {
+    /**
+     * The value produced by the operation: the return value for synchronous
+     * methods, or the resolved value for methods returning a promise.
+     */
+    result: unknown;
+}
+/**
+ * Context of a service initialization, delivered to onInitialize.
+ * Future fields are added here rather than as extra parameters.
+ */
+export interface InitializeContext {
+    /**
+     * The unique identifier of the service that is being initialized.
+     */
+    key: ServiceKey<unknown>;
+}
+/**
+ * Context of a service disposal, delivered to onDispose.
+ * Future fields are added here rather than as extra parameters.
+ */
+export interface DisposeContext {
+    /**
+     * The unique identifier of the service that is being disposed.
+     */
+    key: ServiceKey<unknown>;
+}
+/**
+ * Context of a method invocation, delivered to onMethodCall.
+ * Future fields are added here rather than as extra parameters.
+ */
+export interface MethodCallContext {
+    /**
+     * The unique identifier of the service the method belongs to.
+     */
+    key: ServiceKey<unknown>;
+    /**
+     * The name of the method that is being called.
+     */
+    methodName: string;
+    /**
+     * The arguments the method was invoked with, passed by reference;
+     * implementations must not mutate them.
+     */
+    args: readonly unknown[];
+}
+/**
+ * Interface for listening to service events. Implement this interface to
+ * observe lifecycle events and method calls of services in a module.
+ *
+ * Each method is invoked when the corresponding operation starts and may
+ * return an EventSpan that is notified when that operation finishes.
+ * Returning nothing opts out of completion tracking for that call.
+ */
+export interface ServiceEventListener {
+    /**
+     * Invoked at the start of the initialization process for a specific service.
+     *
+     * @param context - Context of the initialization, including the service key.
+     * @return An EventSpan notified when initialization finishes, or void.
+     */
+    onInitialize?(context: InitializeContext): EventSpan | void;
+    /**
+     * Invoked when the disposal process for a service starts.
+     *
+     * @param context - Context of the disposal, including the service key.
+     * @return An EventSpan notified when disposal finishes, or void.
+     */
+    onDispose?(context: DisposeContext): EventSpan | void;
+    /**
+     * Invoked when a method call starts on a service instance.
+     *
+     * @param context - Context of the invocation, including the service key,
+     * the method name, and its arguments.
+     * @return An EventSpan notified when the call finishes, or void.
+     */
+    onMethodCall?(context: MethodCallContext): EventSpan | void;
+}
+//# sourceMappingURL=serviceEventListener.d.ts.map

package/dist/serviceEventListener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serviceEventListener.d.ts","sourceRoot":"","sources":["../src/serviceEventListener.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAEnC;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;IAEzB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,CAAC;IAE5D;;;;;OAKG;IACH,SAAS,CAAC,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,CAAC;IAEtD;;;;;;OAMG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,CAAC;CAC7D"}

package/dist/serviceEventListener.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=serviceEventListener.js.map

package/dist/serviceEventListener.js.map

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

package/dist/serviceFactory.d.ts

@@ -0,0 +1,36 @@
+import { ServiceKey, ServiceSelectorKey } from './serviceKey';
+import { ServiceScope } from './serviceScope';
+import { ServiceSelector } from './serviceSelector';
+type ServiceType<T> = T extends ServiceSelectorKey<infer U> ? ServiceSelector<U> : T extends ServiceKey<infer U> ? U : never;
+type DependencyTypes<T extends readonly ServiceKey<unknown>[]> = {
+    [K in keyof T]: ServiceType<T[K]>;
+};
+export declare abstract class ServiceFactory<const T, const D extends readonly ServiceKey<unknown>[] = []> {
+    abstract provides: ServiceKey<T>;
+    abstract dependsOn: D;
+    abstract scope?: ServiceScope;
+    abstract initialize: (...dependencies: DependencyTypes<D>) => T | Promise<T>;
+    abstract dispose?: () => void;
+    /**
+     * Creates a singleton service factory that ensures a single instance of the provided service is initialized
+     * and used throughout the scope lifecycle.
+     */
+    static singleton<const T, const D extends readonly ServiceKey<unknown>[] = []>({ scope, provides, dependsOn, initialize, dispose, }: {
+        scope?: ServiceScope;
+        provides: ServiceKey<T>;
+        dependsOn?: D;
+        initialize: (...dependencies: DependencyTypes<D>) => T | Promise<T>;
+        dispose?: (instance: T) => void;
+    }): ServiceFactory<T, D>;
+    /**
+     * Creates a one-shot service factory that initializes a new instance of the provided service
+     * every time it is requested.
+     */
+    static oneShot<const T, const D extends readonly ServiceKey<unknown>[] = []>({ provides, dependsOn, initialize, }: {
+        provides: ServiceKey<T>;
+        dependsOn: D;
+        initialize: (...dependencies: DependencyTypes<D>) => T | Promise<T>;
+    }): ServiceFactory<T, D>;
+}
+export {};
+//# sourceMappingURL=serviceFactory.d.ts.map

package/dist/serviceFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serviceFactory.d.ts","sourceRoot":"","sources":["../src/serviceFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,KAAK,WAAW,CAAC,CAAC,IAChB,CAAC,SAAS,kBAAkB,CAAC,MAAM,CAAC,CAAC,GACjC,eAAe,CAAC,CAAC,CAAC,GAClB,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GAC3B,CAAC,GACD,KAAK,CAAC;AAGd,KAAK,eAAe,CAAC,CAAC,SAAS,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI;KAC9D,CAAC,IAAI,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAClC,CAAC;AAEF,8BAAsB,cAAc,CAClC,KAAK,CAAC,CAAC,EACP,KAAK,CAAC,CAAC,SAAS,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE;IAEnD,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,CAAC,GAAG,YAAY,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAE9B;;;OAGG;IACH,MAAM,CAAC,SAAS,CACd,KAAK,CAAC,CAAC,EACP,KAAK,CAAC,CAAC,SAAS,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,EACnD,EACA,KAAK,EACL,QAAQ,EACR,SAA8B,EAC9B,UAAU,EACV,OAAkB,GACnB,EAAE;QACD,KAAK,CAAC,EAAE,YAAY,CAAC;QACrB,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;QACxB,SAAS,CAAC,EAAE,CAAC,CAAC;QACd,UAAU,EAAE,CAAC,GAAG,YAAY,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACpE,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC;KACjC,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC;IAsCxB;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,SAAS,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,EAAE,EAC3E,QAAQ,EACR,SAAS,EACT,UAAU,GACX,EAAE;QACD,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;QACxB,SAAS,EAAE,CAAC,CAAC;QACb,UAAU,EAAE,CAAC,GAAG,YAAY,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;KACrE,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC;CAOzB"}

package/dist/serviceFactory.js

@@ -0,0 +1,68 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceFactory = void 0;
+class ServiceFactory {
+    /**
+     * Creates a singleton service factory that ensures a single instance of the provided service is initialized
+     * and used throughout the scope lifecycle.
+     */
+    static singleton({ scope, provides, dependsOn = [], initialize, dispose = () => { }, }) {
+        let promisedInstance;
+        let resolvedInstance;
+        return {
+            scope,
+            provides,
+            dependsOn,
+            initialize(...dependencies) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    if (resolvedInstance !== undefined) {
+                        return resolvedInstance;
+                    }
+                    if (promisedInstance !== undefined) {
+                        return promisedInstance;
+                    }
+                    // Store the reference to the promise so that concurrent requests can wait for it
+                    promisedInstance = (() => __awaiter(this, void 0, void 0, function* () {
+                        try {
+                            resolvedInstance = yield initialize(...dependencies);
+                            return resolvedInstance;
+                        }
+                        finally {
+                            promisedInstance = undefined;
+                        }
+                    }))();
+                    return promisedInstance;
+                });
+            },
+            dispose() {
+                if (resolvedInstance !== undefined) {
+                    dispose(resolvedInstance);
+                    resolvedInstance = undefined;
+                }
+                promisedInstance = undefined;
+            },
+        };
+    }
+    /**
+     * Creates a one-shot service factory that initializes a new instance of the provided service
+     * every time it is requested.
+     */
+    static oneShot({ provides, dependsOn, initialize, }) {
+        return {
+            provides,
+            dependsOn,
+            initialize,
+        };
+    }
+}
+exports.ServiceFactory = ServiceFactory;
+//# sourceMappingURL=serviceFactory.js.map

package/dist/serviceFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serviceFactory.js","sourceRoot":"","sources":["../src/serviceFactory.ts"],"names":[],"mappings":";;;;;;;;;;;;AAiBA,MAAsB,cAAc;IAUlC;;;OAGG;IACH,MAAM,CAAC,SAAS,CAGd,EACA,KAAK,EACL,QAAQ,EACR,SAAS,GAAG,EAAkB,EAC9B,UAAU,EACV,OAAO,GAAG,GAAG,EAAE,GAAE,CAAC,GAOnB;QACC,IAAI,gBAAwC,CAAC;QAC7C,IAAI,gBAA+B,CAAC;QAEpC,OAAO;YACL,KAAK;YACL,QAAQ;YACR,SAAS;YACH,UAAU,CAAC,GAAG,YAAgC;;oBAClD,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;wBACnC,OAAO,gBAAgB,CAAC;oBAC1B,CAAC;oBAED,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;wBACnC,OAAO,gBAAgB,CAAC;oBAC1B,CAAC;oBAED,iFAAiF;oBACjF,gBAAgB,GAAG,CAAC,GAAS,EAAE;wBAC7B,IAAI,CAAC;4BACH,gBAAgB,GAAG,MAAM,UAAU,CAAC,GAAG,YAAY,CAAC,CAAC;4BACrD,OAAO,gBAAgB,CAAC;wBAC1B,CAAC;gCAAS,CAAC;4BACT,gBAAgB,GAAG,SAAS,CAAC;wBAC/B,CAAC;oBACH,CAAC,CAAA,CAAC,EAAE,CAAC;oBACL,OAAO,gBAAgB,CAAC;gBAC1B,CAAC;aAAA;YACD,OAAO;gBACL,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;oBACnC,OAAO,CAAC,gBAAgB,CAAC,CAAC;oBAC1B,gBAAgB,GAAG,SAAS,CAAC;gBAC/B,CAAC;gBACD,gBAAgB,GAAG,SAAS,CAAC;YAC/B,CAAC;SACF,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,OAAO,CAA+D,EAC3E,QAAQ,EACR,SAAS,EACT,UAAU,GAKX;QACC,OAAO;YACL,QAAQ;YACR,SAAS;YACT,UAAU;SACX,CAAC;IACJ,CAAC;CACF;AAtFD,wCAsFC"}

package/dist/serviceKey.d.ts

@@ -0,0 +1,90 @@
+import { ServiceSelector } from './serviceSelector';
+/**
+ * A typed token used to identify and retrieve a service from a ServiceModule.
+ *
+ * ServiceKey acts as a unique identifier for a service type, allowing type-safe
+ * dependency injection. Each key has a unique symbol to ensure identity comparison
+ * works correctly even if two keys have the same name.
+ *
+ * @template T The type of service this key identifies.
+ *
+ * @example
+ * ```ts
+ * interface Logger {
+ *   log: (msg: string) => void;
+ * }
+ *
+ * const LoggerKey = new ServiceKey<Logger>('Logger');
+ *
+ * // Use with ServiceFactory and ServiceModule
+ * const loggerFactory = ServiceFactory.singleton({
+ *   provides: LoggerKey,
+ *   dependsOn: [],
+ *   initialize: () => console,
+ * });
+ *
+ * const module = ServiceModule.from([loggerFactory]);
+ * const logger = await module.get(LoggerKey);
+ * ```
+ */
+export declare class ServiceKey<T> {
+    readonly name: string;
+    /**
+     * A unique symbol that identifies this service key.
+     * Used internally for identity comparison between keys.
+     */
+    readonly symbol: symbol;
+    /**
+     * Creates a new ServiceKey with the given name.
+     *
+     * @param name A human-readable name for the service, used in error messages and debugging.
+     */
+    constructor(name: string);
+}
+/**
+ * A specialized ServiceKey that groups multiple ServiceKeys of the same type,
+ * allowing a service to depend on a selector that can retrieve any of the grouped services.
+ *
+ * When used in a factory's `dependsOn` array, the factory's `initialize` callback
+ * receives a `ServiceSelector<T>` instance instead of a direct service instance.
+ * This enables runtime selection between multiple implementations of the same interface.
+ *
+ * @template T The common type shared by all service keys in this selector.
+ *
+ * @example
+ * ```ts
+ * interface Logger {
+ *   log: (msg: string) => void;
+ * }
+ *
+ * const ConsoleLoggerKey = new ServiceKey<Logger>('ConsoleLogger');
+ * const FileLoggerKey = new ServiceKey<Logger>('FileLogger');
+ *
+ * // Group multiple logger implementations under one selector
+ * const LoggerSelectorKey = new ServiceSelectorKey<Logger>([
+ *   ConsoleLoggerKey,
+ *   FileLoggerKey,
+ * ]);
+ *
+ * // Use in a factory's dependsOn array
+ * const appFactory = ServiceFactory.singleton({
+ *   provides: AppKey,
+ *   dependsOn: [LoggerSelectorKey] as const,
+ *   initialize: (loggerSelector: ServiceSelector<Logger>) => {
+ *     // loggerSelector.get(ConsoleLoggerKey) or loggerSelector.get(FileLoggerKey)
+ *     return new App(loggerSelector);
+ *   },
+ * });
+ * ```
+ */
+export declare class ServiceSelectorKey<T> extends ServiceKey<ServiceSelector<T>> {
+    readonly values: ServiceKey<T>[];
+    /**
+     * Creates a new ServiceSelectorKey that groups the provided service keys.
+     *
+     * @param values An array of ServiceKeys that this selector can provide access to.
+     *               All keys must be registered in the ServiceModule for dependency validation to pass.
+     */
+    constructor(values: ServiceKey<T>[]);
+}
+//# sourceMappingURL=serviceKey.d.ts.map

package/dist/serviceKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serviceKey.d.ts","sourceRoot":"","sources":["../src/serviceKey.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,UAAU,CAAC,CAAC;aAYK,IAAI,EAAE,MAAM;IAXxC;;;OAGG;IACH,SAAgB,MAAM,EAAE,MAAM,CAAC;IAE/B;;;;OAIG;gBACyB,IAAI,EAAE,MAAM;CAGzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,kBAAkB,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAO3D,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE;IAN5C;;;;;OAKG;gBACkB,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE;CAG7C"}

package/dist/serviceKey.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceSelectorKey = exports.ServiceKey = void 0;
+/**
+ * A typed token used to identify and retrieve a service from a ServiceModule.
+ *
+ * ServiceKey acts as a unique identifier for a service type, allowing type-safe
+ * dependency injection. Each key has a unique symbol to ensure identity comparison
+ * works correctly even if two keys have the same name.
+ *
+ * @template T The type of service this key identifies.
+ *
+ * @example
+ * ```ts
+ * interface Logger {
+ *   log: (msg: string) => void;
+ * }
+ *
+ * const LoggerKey = new ServiceKey<Logger>('Logger');
+ *
+ * // Use with ServiceFactory and ServiceModule
+ * const loggerFactory = ServiceFactory.singleton({
+ *   provides: LoggerKey,
+ *   dependsOn: [],
+ *   initialize: () => console,
+ * });
+ *
+ * const module = ServiceModule.from([loggerFactory]);
+ * const logger = await module.get(LoggerKey);
+ * ```
+ */
+class ServiceKey {
+    /**
+     * Creates a new ServiceKey with the given name.
+     *
+     * @param name A human-readable name for the service, used in error messages and debugging.
+     */
+    constructor(name) {
+        this.name = name;
+        this.symbol = Symbol(name);
+    }
+}
+exports.ServiceKey = ServiceKey;
+/**
+ * A specialized ServiceKey that groups multiple ServiceKeys of the same type,
+ * allowing a service to depend on a selector that can retrieve any of the grouped services.
+ *
+ * When used in a factory's `dependsOn` array, the factory's `initialize` callback
+ * receives a `ServiceSelector<T>` instance instead of a direct service instance.
+ * This enables runtime selection between multiple implementations of the same interface.
+ *
+ * @template T The common type shared by all service keys in this selector.
+ *
+ * @example
+ * ```ts
+ * interface Logger {
+ *   log: (msg: string) => void;
+ * }
+ *
+ * const ConsoleLoggerKey = new ServiceKey<Logger>('ConsoleLogger');
+ * const FileLoggerKey = new ServiceKey<Logger>('FileLogger');
+ *
+ * // Group multiple logger implementations under one selector
+ * const LoggerSelectorKey = new ServiceSelectorKey<Logger>([
+ *   ConsoleLoggerKey,
+ *   FileLoggerKey,
+ * ]);
+ *
+ * // Use in a factory's dependsOn array
+ * const appFactory = ServiceFactory.singleton({
+ *   provides: AppKey,
+ *   dependsOn: [LoggerSelectorKey] as const,
+ *   initialize: (loggerSelector: ServiceSelector<Logger>) => {
+ *     // loggerSelector.get(ConsoleLoggerKey) or loggerSelector.get(FileLoggerKey)
+ *     return new App(loggerSelector);
+ *   },
+ * });
+ * ```
+ */
+class ServiceSelectorKey extends ServiceKey {
+    /**
+     * Creates a new ServiceSelectorKey that groups the provided service keys.
+     *
+     * @param values An array of ServiceKeys that this selector can provide access to.
+     *               All keys must be registered in the ServiceModule for dependency validation to pass.
+     */
+    constructor(values) {
+        super(`ServiceSelector[${values}]`);
+        this.values = values;
+    }
+}
+exports.ServiceSelectorKey = ServiceSelectorKey;
+//# sourceMappingURL=serviceKey.js.map

package/dist/serviceKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serviceKey.js","sourceRoot":"","sources":["../src/serviceKey.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAa,UAAU;IAOrB;;;;OAIG;IACH,YAA4B,IAAY;QAAZ,SAAI,GAAJ,IAAI,CAAQ;QACtC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;CACF;AAfD,gCAeC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAa,kBAAsB,SAAQ,UAA8B;IACvE;;;;;OAKG;IACH,YAAqB,MAAuB;QAC1C,KAAK,CAAC,mBAAmB,MAAM,GAAG,CAAC,CAAC;QADjB,WAAM,GAAN,MAAM,CAAiB;IAE5C,CAAC;CACF;AAVD,gDAUC"}

package/dist/serviceModule.d.ts

@@ -0,0 +1,71 @@
+import { ServiceKey } from './serviceKey';
+import { ServiceFactory } from './serviceFactory';
+import { ServiceScope } from './serviceScope';
+import type { ServiceEventListener } from './serviceEventListener';
+type GenericFactory = ServiceFactory<unknown, readonly ServiceKey<any>[]>;
+/**
+ * ServiceModule is a container for service factories and manages dependency resolution.
+ *
+ * It provides a way to retrieve service instances based on their ServiceKey,
+ * ensuring that all dependencies are resolved and initialized in the correct order.
+ * It also handles circular dependency detection and missing dependency validation
+ * at the time of module creation.
+ */
+export declare class ServiceModule {
+    readonly factories: GenericFactory[];
+    /**
+     * Private constructor to enforce module creation through the `static from` method.
+     *
+     * @param factories An array of service factories that this module will manage.
+     */
+    private constructor();
+    /**
+     * Retrieves an instance for the given ServiceKey.
+     *
+     * @param key - The key of the service to retrieve.
+     * @return A promise that resolves to the service instance.
+     * @throws {ServiceFactoryNotFoundError} If no suitable factory is found for the given key.
+     */
+    get<T>(key: ServiceKey<T>): Promise<T>;
+    /**
+     * Retrieves the value associated with the given service key or returns null if the service is not found.
+     *
+     * @param key - The key used to retrieve the associated service.
+     * @return A promise that resolves to the service value if found, or null if the service is not found.
+     */
+    getOrNull<T>(key: ServiceKey<T>): Promise<T | null>;
+    /**
+     * Disposes of service factories within the specified scope or all factories if no scope is provided.
+     *
+     * This method is useful for cleaning up resources and instances held by service factories,
+     * such as singleton factories, as they may hold database connections or other resources that need to be released.
+     *
+     * @param scope The scope to filter the factories to be disposed.
+     * If not provided, all factories are disposed of.
+     * @return No return value.
+     */
+    dispose(scope?: ServiceScope): void;
+    /**
+     * Creates a new ServiceModule instance by aggregating and deduplicating a list of
+     * ServiceModule or GenericFactory instances.
+     * If multiple factories provide the same
+     * ServiceKey, the last one in the list takes precedence.
+     *
+     * When a listener is provided, every factory is wrapped with instrumentation:
+     * the listener is notified when a service is initialized or disposed and when
+     * a method is called on a service instance, and may return an EventSpan per
+     * operation to observe its completion. Service instances are wrapped in a
+     * Proxy to observe method calls, and errors are rethrown after being
+     * reported, so behavior is otherwise unchanged.
+     *
+     * @param entries - An array of ServiceModule or GenericFactory
+     * instances to be processed into a single ServiceModule.
+     * @param listener - An optional ServiceEventListener notified of service
+     * lifecycle events and method calls in the resulting module.
+     * @return A new ServiceModule containing the deduplicated factories.
+     * @throws {ServiceModuleInitError} If circular or missing dependencies are detected during module creation.
+     */
+    static from(entries: (ServiceModule | GenericFactory)[], listener?: ServiceEventListener): ServiceModule;
+}
+export {};
+//# sourceMappingURL=serviceModule.d.ts.map

package/dist/serviceModule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serviceModule.d.ts","sourceRoot":"","sources":["../src/serviceModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAsB,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEnE,KAAK,cAAc,GAAG,cAAc,CAAC,OAAO,EAAE,SAAS,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAG1E;;;;;;;GAOG;AACH,qBAAa,aAAa;IAMJ,QAAQ,CAAC,SAAS,EAAE,cAAc,EAAE;IALxD;;;;OAIG;IACH,OAAO;IAOP;;;;;;OAMG;IACU,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA2BnD;;;;;OAKG;IACU,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAWhE;;;;;;;;;OASG;IACI,OAAO,CAAC,KAAK,CAAC,EAAE,YAAY;IAQnC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,IAAI,CACT,OAAO,EAAE,CAAC,aAAa,GAAG,cAAc,CAAC,EAAE,EAC3C,QAAQ,CAAC,EAAE,oBAAoB,GAC9B,aAAa;CAsBjB"}