composed-di 0.2.9 → 0.3.0

package/README.md

@@ -1,141 +1,182 @@
-# lazy-di
-
-A tiny, type-friendly dependency injection helper for composing services via keys and factories.
-
-It provides:
-- ServiceKey<T>: a typed token used to identify a service
-- ServiceFactory<T>: a contract to create a service (with static methods `singleton` and `oneShot`)
-- ServiceModule: a resolver that wires factories, validates dependencies, and provides services
-
-ServiceModule will:
-- detect recursive dependencies (a factory that depends on its own key)
-- detect missing dependencies (a factory that depends on keys that have no factory)
-
-## Install
-
-Install from npm:
-
-- npm: `npm install composed-di`
-- pnpm: `pnpm add composed-di`
-- yarn: `yarn add composed-di`
-
-If you're working on this repo locally, build artifacts are generated under `dist/` by running:
-
-```
-npm run build
-```
-
-## Usage
-
-Below is a minimal example using the public API.
-
-```ts
-import {
-  ServiceKey,
-  ServiceModule,
-  ServiceFactory,
-} from 'composed-di'; // when developing this repo locally, import from './src'
-
-// 1) Define service types
-interface Config {
-  baseUrl: string;
-}
-
-interface Logger {
-  info: (msg: string) => void;
-}
-
-class App {
-  constructor(private config: Config, private logger: Logger) {}
-  start() {
-    this.logger.info(`Starting with baseUrl=${this.config.baseUrl}`);
-  }
-}
-
-// 2) Create keys
-const ConfigKey = new ServiceKey<Config>('Config');
-const LoggerKey = new ServiceKey<Logger>('Logger');
-const AppKey = new ServiceKey<App>('App');
-
-// 3) Create factories (singleton or one-shot)
-const configFactory = ServiceFactory.singleton({
-  provides: ConfigKey,
-  dependsOn: [],
-  initialize: () => {
-    return { baseUrl: 'https://api.example.com' } satisfies Config;
-  },
-});
-
-const loggerFactory = ServiceFactory.singleton({
-  provides: LoggerKey,
-  dependsOn: [],
-  initialize: () => {
-    return console as unknown as Logger;
-  },
-});
-
-const appFactory = ServiceFactory.oneShot({
-  provides: AppKey,
-  dependsOn: [ConfigKey, LoggerKey],
-  initialize: (config, logger) => {
-    return new App(config, logger);
-  },
-});
-
-// 4) Compose a module (you can pass factories and/or other ServiceModule instances)
-const module = ServiceModule.from([configFactory, loggerFactory, appFactory]);
-
-// 5) Resolve and use
-(async () => {
-  const app = await module.get(AppKey);
-  app.start();
-})();
-```
-
-Notes:
-- `ServiceModule.get` resolves dependencies recursively, so factories can depend on other services.
-- If a dependency is missing or recursive, `ServiceModule` throws with a helpful error message.
-
-## Visualizing Dependencies
-
-The library includes utilities to generate a DOT graph representation of your service dependencies, which can be visualized using Graphviz tools.
-
-```ts
-import { ServiceModule, printDotGraph, createDotGraph } from 'composed-di';
-
-// After creating your ServiceModule
-const module = ServiceModule.from([configFactory, loggerFactory, appFactory]);
-
-// Option 1: Print the DOT graph to console with instructions
-printDotGraph(module);
-
-// Option 2: Generate DOT graph with custom options
-const dotGraph = createDotGraph(module, {
-  direction: 'LR',  // 'TB' (top-bottom), 'LR' (left-right), 'BT', 'RL'
-  title: 'My Service Dependencies',
-  highlightLeaves: true,  // Highlight services with no dependencies (green)
-  highlightRoots: true,   // Highlight services with no dependents (orange)
-});
-console.log(dotGraph);
-```
-
-The generated DOT notation can be visualized using:
-- [GraphvizOnline](https://dreampuf.github.io/GraphvizOnline/)
-- [Edotor](https://edotor.net/)
-
-## API
-
-- `class ServiceKey<T>(name: string)` - Creates a typed token to identify a service
-- `abstract class ServiceFactory<T, D extends readonly ServiceKey<unknown>[]>` with:
-  - `provides: ServiceKey<T>` - The service key this factory provides
-  - `dependsOn: D` - Array of service keys this factory depends on
-  - `initialize(...dependencies)` - Creates the service instance
-  - `dispose(instance)` - Cleans up the service instance
-  - `static singleton({ provides, dependsOn?, initialize, dispose? })` - Creates a singleton factory
-  - `static oneShot({ provides, dependsOn, initialize, dispose? })` - Creates a one-shot factory
-- `class ServiceModule` with:
-  - `static from(factoriesOrModules)` - Creates a module from factories and/or other modules
-  - `async get(key)` - Resolves and returns a service by its key
-- `createDotGraph(module, options?)` - Generates DOT notation graph from a ServiceModule
-- `printDotGraph(module)` - Prints DOT graph to console with visualization instructions
-
+# lazy-di
+
+A lightweight, lazy, and typesafe dependency injection library for TypeScript.
+
+## Features
+
+- **Lazy Initialization**: Services are only created when they are actually needed.
+- **Type-Safe**: Full TypeScript support with typed keys and dependency resolution.
+- **Circular Dependency Detection**: Validates your dependency graph at module creation.
+- **Flexible Scoping**: Support for singletons, transient (one-shot) services, and custom scopes.
+- **Runtime Selection**: Dynamically choose between multiple implementations of the same interface.
+- **Async Support**: Native support for asynchronous service initialization.
+- **Visualization**: Built-in support for generating Mermaid and DOT diagrams of your dependency graph.
+
+## Installation
+
+```bash
+npm install lazy-di
+```
+
+## Quick Start
+
+### 1. Define your Service Keys
+
+Service keys are typed tokens that identify your services. They ensure type safety when injecting and retrieving services.
+
+```typescript
+import { ServiceKey } from 'lazy-di';
+
+interface Database {
+  query: (sql: string) => Promise<any>;
+}
+
+export const DatabaseKey = new ServiceKey<Database>('Database');
+
+interface UserService {
+  getUser: (id: string) => Promise<any>;
+}
+
+export const UserServiceKey = new ServiceKey<UserService>('UserService');
+```
+
+### 2. Create Service Factories
+
+Factories define how services are created and what they depend on. `lazy-di` supports both singleton (created once) and one-shot (created every time) services.
+
+```typescript
+import { ServiceFactory } from 'lazy-di';
+import { DatabaseKey, UserServiceKey } from './keys';
+
+const databaseFactory = ServiceFactory.singleton({
+  provides: DatabaseKey,
+  initialize: () => {
+    console.log('Initializing Database...');
+    return {
+      query: async (sql) => ({ id: '1', name: 'John Doe' }),
+    };
+  },
+});
+
+const userServiceFactory = ServiceFactory.singleton({
+  provides: UserServiceKey,
+  dependsOn: [DatabaseKey],
+  initialize: (db) => {
+    // db is automatically typed as Database
+    return {
+      getUser: (id) => db.query(`SELECT * FROM users WHERE id = ${id}`),
+    };
+  },
+});
+```
+
+### 3. Create a Service Module and Get Services
+
+A `ServiceModule` aggregates factories and manages their lifecycle.
+
+```typescript
+import { ServiceModule } from 'lazy-di';
+
+const module = ServiceModule.from([
+  databaseFactory,
+  userServiceFactory
+]);
+
+// At this point, no services have been initialized.
+
+// This will initialize Database and then UserService lazily.
+const userService = await module.get(UserServiceKey);
+const user = await userService.getUser('1');
+```
+
+## Public API
+
+### `ServiceKey<T>`
+
+A unique identifier for a service of type `T`.
+
+```typescript
+const MyKey = new ServiceKey<MyInterface>('MyService');
+```
+
+### `ServiceFactory`
+
+#### `ServiceFactory.singleton(options)`
+Creates a factory for a service that is instantiated only once.
+
+- `provides`: The `ServiceKey` this factory satisfies.
+- `dependsOn`: (Optional) An array of `ServiceKey`s this service depends on.
+- `initialize`: A function that creates the service instance. It receives the resolved dependencies as arguments. Can return a Promise.
+- `dispose`: (Optional) A function called when the service is disposed.
+- `scope`: (Optional) A `ServiceScope` for grouping services.
+
+#### `ServiceFactory.oneShot(options)`
+Creates a factory for a service that is instantiated every time it is requested.
+
+### `ServiceModule`
+
+#### `ServiceModule.from(entries)`
+Creates a module from an array of factories or other `ServiceModule` instances. It automatically detects circular dependencies and missing dependencies.
+
+#### `module.get(key)`
+Retrieves a service instance. Returns a `Promise<T>`.
+
+#### `module.dispose(scope?)`
+Disposes of services. If a `scope` is provided, only services in that scope are disposed.
+
+### `ServiceSelectorKey<T>` and `ServiceSelector<T>`
+
+Useful for choosing between multiple implementations of the same interface at runtime.
+
+```typescript
+const LoggerSelectorKey = new ServiceSelectorKey<Logger>([
+  ConsoleLoggerKey,
+  FileLoggerKey,
+]);
+
+const AppFactory = ServiceFactory.singleton({
+  provides: AppKey,
+  dependsOn: [LoggerSelectorKey],
+  initialize: (loggerSelector) => {
+    return {
+      run: async (useFile: boolean) => {
+        const logger = await loggerSelector.get(
+          useFile ? FileLoggerKey : ConsoleLoggerKey
+        );
+        logger.log('Running...');
+      }
+    };
+  }
+});
+```
+
+### `ServiceScope`
+
+Used to group services for collective disposal.
+
+```typescript
+const MyScope = new ServiceScope('MyScope');
+```
+
+## Visualization
+
+Visualize your dependency graph using Mermaid or DOT format.
+
+```typescript
+import { printMermaidGraph, printDotGraph } from 'lazy-di';
+
+// Outputs a Mermaid diagram string
+printMermaidGraph(module);
+
+// Outputs a DOT diagram string
+printDotGraph(module);
+```
+
+## Error Handling
+
+- `ServiceModuleInitError`: Thrown during `ServiceModule.from()` if the dependency graph is invalid (circular or missing dependencies).
+- `ServiceFactoryNotFoundError`: Thrown by `module.get()` if a requested key is not registered.
+
+## License
+
+MIT

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

@@ -2,5 +2,7 @@ export * from './serviceKey';
 export * from './serviceModule';
 export * from './serviceFactory';
 export * from './serviceScope';
+export * from './serviceSelector';
+export * from './errors';
 export * from './utils';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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,SAAS,CAAC"}
+{"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,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -18,5 +18,7 @@ __exportStar(require("./serviceKey"), exports);
 __exportStar(require("./serviceModule"), exports);
 __exportStar(require("./serviceFactory"), exports);
 __exportStar(require("./serviceScope"), exports);
+__exportStar(require("./serviceSelector"), exports);
+__exportStar(require("./errors"), exports);
 __exportStar(require("./utils"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B;AAC7B,kDAAgC;AAChC,mDAAiC;AACjC,iDAA+B;AAC/B,0CAAwB"}
+{"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,2CAAyB;AACzB,0CAAwB"}

package/dist/serviceFactory.d.ts

@@ -1,6 +1,7 @@
-import { ServiceKey } from './serviceKey';
+import { ServiceKey, ServiceSelectorKey } from './serviceKey';
 import { ServiceScope } from './serviceScope';
-type ServiceType<T> = T extends ServiceKey<infer U> ? U : never;
+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]>;
 };

package/dist/serviceFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serviceFactory.d.ts","sourceRoot":"","sources":["../src/serviceFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAGhE,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;IAuBxB;;;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"}
+{"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

@@ -16,24 +16,39 @@ class ServiceFactory {
      * and used throughout the scope lifecycle.
      */
     static singleton({ scope, provides, dependsOn = [], initialize, dispose = () => { }, }) {
-        let instance;
+        let promisedInstance;
+        let resolvedInstance;
         return {
             scope,
             provides,
             dependsOn,
             initialize(...dependencies) {
                 return __awaiter(this, void 0, void 0, function* () {
-                    if (instance === undefined) {
-                        instance = yield initialize(...dependencies);
+                    if (resolvedInstance !== undefined) {
+                        return resolvedInstance;
                     }
-                    return instance;
+                    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 (instance !== undefined) {
-                    dispose(instance);
-                    instance = undefined;
+                if (resolvedInstance !== undefined) {
+                    dispose(resolvedInstance);
+                    resolvedInstance = undefined;
                 }
+                promisedInstance = undefined;
             },
         };
     }

package/dist/serviceFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"serviceFactory.js","sourceRoot":"","sources":["../src/serviceFactory.ts"],"names":[],"mappings":";;;;;;;;;;;;AAWA,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,QAAuB,CAAC;QAE5B,OAAO;YACL,KAAK;YACL,QAAQ;YACR,SAAS;YACH,UAAU,CAAC,GAAG,YAAgC;;oBAClD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;wBAC3B,QAAQ,GAAG,MAAM,UAAU,CAAC,GAAG,YAAY,CAAC,CAAC;oBAC/C,CAAC;oBAED,OAAO,QAAQ,CAAC;gBAClB,CAAC;aAAA;YACD,OAAO;gBACL,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,OAAO,CAAC,QAAQ,CAAC,CAAC;oBAClB,QAAQ,GAAG,SAAS,CAAC;gBACvB,CAAC;YACH,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;AAvED,wCAuEC"}
+{"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/serviceFactoryWrapper.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=serviceFactoryWrapper.d.ts.map

package/dist/serviceFactoryWrapper.d.ts.map

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

package/dist/serviceFactoryWrapper.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const serviceKey_1 = require("./serviceKey");
+class ServiceResolver {
+    constructor(serviceModule) {
+        this.serviceModule = serviceModule;
+    }
+    get(key) {
+        // TODO: Implement service factory wrapper logic
+        return this.serviceModule.get(key);
+    }
+    static from(keys) {
+        return new serviceKey_1.ServiceKey(`ServiceResolver[${keys}]`);
+    }
+}
+//# sourceMappingURL=serviceFactoryWrapper.js.map

package/dist/serviceFactoryWrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serviceFactoryWrapper.js","sourceRoot":"","sources":["../src/serviceFactoryWrapper.ts"],"names":[],"mappings":";;AAAA,6CAA0C;AAG1C,MAAM,eAAe;IACnB,YAAqB,aAA4B;QAA5B,kBAAa,GAAb,aAAa,CAAe;IAAG,CAAC;IAErD,GAAG,CAAC,GAAkB;QACpB,gDAAgD;QAChD,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;IAED,MAAM,CAAC,IAAI,CAAI,IAAqB;QAClC,OAAO,IAAI,uBAAU,CAAC,mBAAmB,IAAI,GAAG,CAAC,CAAA;IACnD,CAAC;CACF"}

package/dist/serviceKey.d.ts

@@ -1,6 +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

@@ -1 +1 @@
-{"version":3,"file":"serviceKey.d.ts","sourceRoot":"","sources":["../src/serviceKey.ts"],"names":[],"mappings":"AACA,qBAAa,UAAU,CAAC,CAAC;aAGK,IAAI,EAAE,MAAM;IAFxC,SAAgB,MAAM,EAAE,MAAM,CAAC;gBAEH,IAAI,EAAE,MAAM;CAGzC"}
+{"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"}