navi-di 1.1.2 → 1.2.0

package/README.md

@@ -17,7 +17,9 @@ The current implementation focuses on a compact core:
 
 - `@Service()` registers classes in the default container.
 - `@Inject()` wires decorated class fields from the active container.
+- `@InjectMany()` wires all matching bindings into a decorated class field.
 - `Container.of()` resolves services from the default container or from named containers.
+- `container.ofChild()` creates hierarchical child containers.
 - `singleton`, `container`, and `transient` scopes control instance lifetime.
 - Circular graphs and missing services fail with explicit runtime errors.
 
@@ -27,11 +29,15 @@ The repository is no longer just scaffolding. The source and tests currently cov
 
 - class registration through `@Service()`;
 - field injection through `@Inject()`;
+- multi-field injection through `@InjectMany()`;
 - named containers via `Container.of(id)`;
-- default-container fallback for named containers;
+- hierarchical child containers via `container.ofChild(id)` and `Container.ofChild(id, parent)`;
+- ancestor lookup across container hierarchies;
 - per-container caching for `container` scope;
 - shared instances for `singleton` scope;
 - fresh instances for `transient` scope;
+- multi-binding registration through `container.add()` and `@Service({ multiple: true })`;
+- multi-binding resolution through `container.getMany()`;
 - cache reset and registration reset through `container.reset()`;
 - error handling for circular dependencies, missing services, and invalid container operations.
 
@@ -53,10 +59,11 @@ Runtime exports:
 - `Container`
 - `Service`
 - `Inject`
+- `InjectMany`
 - `Token`
 
 `Container` exposes the runtime API for resolution and low-level registration,
-including `of()`, `get()`, `set()`, `has()`, `remove()`, and `reset()`.
+including `of()`, `ofChild()`, `get()`, `getMany()`, `set()`, `add()`, `has()`, `remove()`, and `reset()`.
 
 Type-only exports:
 
@@ -102,8 +109,8 @@ How resolution works:
 The default scope. One instance is cached per container.
 
 - repeated `get()` calls in the same container reuse the same instance;
-- named containers receive their own isolated instance;
-- named containers lazily clone container-scoped registrations from the default container on first access.
+- child containers receive their own isolated instance;
+- child containers lazily clone ancestor registrations on first access.
 
 ### `singleton`
 
@@ -116,22 +123,28 @@ One shared instance across all containers.
 
 A new instance is created on every `get()` call.
 
-## Named containers
+## Hierarchical containers
 
-Use named containers when you want isolated request, job, or unit-of-work state.
+Use containers when you want isolated request, job, or unit-of-work state.
 
 ```ts
 const requestA = Container.of('request-a');
 const requestB = Container.of('request-b');
+
+const tenant = Container.of('tenant-a');
+const request = tenant.ofChild('tenant-a-request');
 ```
 
 Current behavior:
 
 - `Container.of()` and `Container.of('default')` return the same default container;
 - `Container.of('name')` reuses the same named container for the same id;
-- named containers fall back to registrations stored in the default container;
-- `container` scope becomes container-local after first resolution in a named container;
-- `singleton` scope stays shared across the whole registry.
+- `Container.of('name')` creates a child of the default container when the container does not exist yet;
+- `Container.ofChild(id, parent)` and `parent.ofChild(id)` create deeper hierarchies;
+- containers resolve single bindings from the nearest ancestor that owns them;
+- `container` scope becomes container-local after first resolution in a descendant container;
+- `singleton` scope stays shared from the root container;
+- disposing a parent container also disposes its descendants.
 
 ## Decorators
 
@@ -149,6 +162,7 @@ Options supported today:
 
 - `id?: ServiceIdentifier`
 - `scope?: 'singleton' | 'container' | 'transient'`
+- `multiple?: boolean`
 
 Example with a custom id:
 
@@ -177,6 +191,16 @@ Current characteristics:
 - injected fields are defined as writable and configurable own properties on the created instance;
 - injected fields are assigned after construction, so they are not available inside constructors or field initializers.
 
+### `@InjectMany(dependency)`
+
+Marks a decorated class field for multi-binding injection.
+
+Current characteristics:
+
+- resolves every matching multi-binding for the identifier;
+- returns values in ancestor-first, local-last order;
+- uses the same active container as the service being created.
+
 Token example:
 
 ```ts
@@ -215,6 +239,15 @@ Returns the default container or a named container.
 Calling `Container.of(id)` with the same identifier reuses the same container
 instance until that instance is disposed.
 
+When a named container is first created through `Container.of(id)`, its parent is
+the default container.
+
+### `Container.ofChild(id, parent?)`
+
+Creates or reuses a child container under the provided parent container.
+
+You can also call `parent.ofChild(id)` from an existing container instance.
+
 ### `container.get(id)`
 
 Resolves a service by class or service identifier.
@@ -224,6 +257,15 @@ Throws:
 - `ServiceNotFoundError` when no registration exists;
 - `CircularDependencyError` when the current resolution path loops back to an in-progress dependency.
 
+### `container.getMany(id)`
+
+Resolves all multi-bindings registered for a service identifier.
+
+- multi-bindings are aggregated from the root of the hierarchy down to the current container;
+- container-scoped registrations are cached per resolving container;
+- singleton registrations are shared from the root container;
+- returns an empty array when no multi-binding exists.
+
 ### `container.tryGet(id)`
 
 Resolves a service by class or service identifier and returns `undefined` when
@@ -280,6 +322,13 @@ Supported forms today:
 This is the low-level API for manual value, class, and factory registration.
 For decorator-driven classes, prefer `@Service()`.
 
+### `container.add(id, valueOrProvider)`
+
+Appends a value or provider to a multi-binding group.
+
+Supported forms are the same as `container.set(...)`, but registrations are
+collected instead of replaced.
+
 Value example:
 
 ```ts

package/dist/container/container.d.ts

@@ -1,132 +1,56 @@
 import type { ContainerIdentifier, Metadata, ServiceIdentifier, ServiceProvider } from '../types';
-/**
- * Resolves services and stores container-local bindings.
- *
- * Containers let you resolve registered services, override values for the
- * current context, and isolate container-scoped services by container.
- */
 export declare class Container {
-    /**
-     * The identifier of this container.
-     *
-     * The default container uses `'default'`, and named containers use the
-     * identifier they were created with.
-     */
     readonly id: ContainerIdentifier;
+    private parentContainer?;
+    private readonly children;
     private metadataMap;
     private bindingMap;
+    private multiMetadataMap;
+    private multiBindingMap;
+    private inheritedMultiMetadataMap;
     private resolving;
     private resolvingPath;
     private disposed;
-    constructor(id: ContainerIdentifier);
+    constructor(id: ContainerIdentifier, parent?: Container);
+    get parent(): Container | undefined;
     private ensureNotDisposed;
     private isDisposable;
-    private canResolveLocally;
-    private canResolve;
     private isValueProvider;
     private isClassProvider;
     private isFactoryProvider;
+    private isRoot;
+    private getRoot;
+    private getLineage;
+    private cloneMetadata;
+    private findBindingOwner;
+    private findMetadataOwner;
+    private canResolve;
     private getClassProviderMetadata;
     private getFactoryProviderMetadata;
-    /**
-     * Returns the default container or a named container.
-     *
-     * Calling this method with the same identifier returns the same container
-     * instance until that instance is disposed.
-     *
-     * @param id The container identifier. Omit this to use the default container.
-     * @returns The matching container instance.
-     */
+    private pushMultiBinding;
+    private pushMultiMetadata;
+    private getOrCreateInheritedMultiMetadata;
+    private defineInjection;
+    private resolveMetadata;
+    private resetMetadataValues;
+    private collectOwnedValues;
+    unlinkParent(): void;
+    hasParent(parent: Container | undefined): boolean;
     static of(id?: ContainerIdentifier): Container;
-    /**
-     * Registers service metadata in this container.
-     *
-     * This is a low-level API for manual registration when you are not using
-     * `@Service()`. Registering a `singleton` on a named container stores it in
-     * the default container so it can be shared across containers.
-     *
-     * @param metadata The service metadata to register.
-     * @returns The current container.
-     */
+    static ofChild(id: ContainerIdentifier, parent?: Container | ContainerIdentifier): Container;
+    ofChild(id: ContainerIdentifier): Container;
     register<T>(metadata: Metadata<T>): this;
-    /**
-     * Returns whether this container has a local registration for an identifier.
-     *
-     * This only checks registrations stored on the current container and does
-     * not indicate whether the identifier can be resolved through fallback.
-     *
-     * @param id The service identifier to check.
-     * @returns `true` when the current container has a local registration.
-     */
     has(id: ServiceIdentifier): boolean;
-    /**
-     * Registers a value or provider for a service identifier.
-     *
-     * Use a plain value to bind an explicit instance, or a provider object to
-     * resolve by class or factory.
-     *
-     * @param id The service identifier to register.
-     * @param valueOrProvider The bound value or provider definition.
-     * @returns The current container.
-     */
     set<T>(id: ServiceIdentifier<T>, value: T): this;
     set<T>(id: ServiceIdentifier<T>, provider: ServiceProvider<T>): this;
-    /**
-     * Removes a local binding or registration from this container.
-     *
-     * @param id The service identifier to remove.
-     * @returns The current container.
-     */
+    add<T>(id: ServiceIdentifier<T>, value: T): this;
+    add<T>(id: ServiceIdentifier<T>, provider: ServiceProvider<T>): this;
     remove(id: ServiceIdentifier): this;
-    /**
-     * Resets services stored in this container.
-     *
-     * Use `'value'` to clear cached instances while keeping registrations, or
-     * `'service'` to remove local registrations and bindings entirely.
-     *
-     * @param strategy The reset strategy to apply.
-     * @returns The current container.
-     */
     reset(strategy?: 'value' | 'service'): this;
-    /**
-     * Resolves a service from this container.
-     *
-     * If the current container does not have a local registration, named
-     * containers can continue resolution through the default container according
-     * to the service scope. Services are instantiated with `new Class()` and do
-     * not support constructor arguments.
-     *
-     * @param id The service identifier to resolve.
-     * @returns The resolved service instance or bound value.
-     * @throws {ServiceNotFoundError} If no service is registered for the identifier.
-     * @throws {CircularDependencyError} If the dependency graph contains a cycle.
-     */
     get<T>(id: ServiceIdentifier<T>): T;
-    /**
-     * Resolves a service if it exists, otherwise returns `undefined`.
-     *
-     * Unlike `get()`, this only suppresses `ServiceNotFoundError`. Other errors,
-     * such as circular dependencies or disposed-container access, still surface.
-     *
-     * @param id The service identifier to resolve.
-     * @returns The resolved value, or `undefined` when the service is missing.
-     */
+    getMany<T>(id: ServiceIdentifier<T>): T[];
     tryGet<T>(id: ServiceIdentifier<T>): T | undefined;
-    /**
-     * Disposes this container instance and clears all local registrations.
-     *
-     * The container becomes unusable after disposal. Cached service instances and
-     * bound values that expose an async or sync `dispose()` method are awaited in
-     * the order they were discovered.
-     */
     dispose(): Promise<void>;
-    private isDefault;
-    /**
-     * Resets a container by its identifier.
-     *
-     * @param containerId The container to reset.
-     * @param options Reset options.
-     */
     static reset(containerId: ContainerIdentifier, options?: {
         strategy?: 'value' | 'service';
     }): void;

package/dist/container/container.js

@@ -1,27 +1,25 @@
 import { CircularDependencyError, ContainerDisposedError, ServiceNotFoundError } from '../errors';
 import { EMPTY_VALUE } from '../types';
 import { ContainerRegistry } from './registry';
-/**
- * Resolves services and stores container-local bindings.
- *
- * Containers let you resolve registered services, override values for the
- * current context, and isolate container-scoped services by container.
- */
 export class Container {
-    /**
-     * The identifier of this container.
-     *
-     * The default container uses `'default'`, and named containers use the
-     * identifier they were created with.
-     */
     id;
+    parentContainer;
+    children = new Set();
     metadataMap = new Map();
     bindingMap = new Map();
+    multiMetadataMap = new Map();
+    multiBindingMap = new Map();
+    inheritedMultiMetadataMap = new Map();
     resolving = new Set();
     resolvingPath = [];
     disposed = false;
-    constructor(id) {
+    constructor(id, parent) {
         this.id = id;
+        this.parentContainer = parent;
+        parent?.children.add(this);
+    }
+    get parent() {
+        return this.parentContainer;
     }
     ensureNotDisposed() {
         if (this.disposed) {
@@ -31,18 +29,6 @@ export class Container {
     isDisposable(value) {
         return typeof value === 'object' && value !== null && 'dispose' in value && typeof value.dispose === 'function';
     }
-    canResolveLocally(id) {
-        return this.bindingMap.has(id) || this.metadataMap.has(id);
-    }
-    canResolve(id) {
-        if (this.canResolveLocally(id)) {
-            return true;
-        }
-        if (this.isDefault()) {
-            return false;
-        }
-        return ContainerRegistry.defaultContainer.canResolveLocally(id);
-    }
     isValueProvider(provider) {
         return typeof provider === 'object' && provider !== null && 'useValue' in provider;
     }
@@ -52,8 +38,39 @@ export class Container {
     isFactoryProvider(provider) {
         return typeof provider === 'object' && provider !== null && 'useFactory' in provider;
     }
-    getClassProviderMetadata(id, provider) {
-        const existingMetadata = this.metadataMap.get(provider.useClass) ?? ContainerRegistry.defaultContainer.metadataMap.get(provider.useClass);
+    isRoot() {
+        return this.parentContainer === undefined;
+    }
+    getRoot() {
+        return this.parentContainer?.getRoot() ?? this;
+    }
+    getLineage() {
+        return this.parentContainer ? [...this.parentContainer.getLineage(), this] : [this];
+    }
+    cloneMetadata(metadata) {
+        return {
+            ...metadata,
+            injections: [...metadata.injections],
+            value: EMPTY_VALUE,
+        };
+    }
+    findBindingOwner(id) {
+        if (this.bindingMap.has(id)) {
+            return this;
+        }
+        return this.parentContainer?.findBindingOwner(id);
+    }
+    findMetadataOwner(id) {
+        if (this.metadataMap.has(id)) {
+            return this;
+        }
+        return this.parentContainer?.findMetadataOwner(id);
+    }
+    canResolve(id) {
+        return this.findBindingOwner(id) !== undefined || this.findMetadataOwner(id) !== undefined;
+    }
+    getClassProviderMetadata(id, provider, multiple = false) {
+        const existingMetadata = this.findMetadataOwner(provider.useClass)?.metadataMap.get(provider.useClass);
         const inheritedInjections = existingMetadata?.Class === provider.useClass ? [...existingMetadata.injections] : [];
         const inheritedScope = existingMetadata?.Class === provider.useClass ? existingMetadata.scope : 'container';
         return {
@@ -63,9 +80,10 @@ export class Container {
             injections: provider.injections ?? inheritedInjections,
             scope: provider.scope ?? inheritedScope,
             value: EMPTY_VALUE,
+            multiple,
         };
     }
-    getFactoryProviderMetadata(id, provider) {
+    getFactoryProviderMetadata(id, provider, multiple = false) {
         return {
             id,
             name: typeof id === 'function' ? id.name : String(id),
@@ -73,17 +91,118 @@ export class Container {
             scope: provider.scope ?? 'container',
             value: EMPTY_VALUE,
             factory: provider.useFactory,
+            multiple,
         };
     }
-    /**
-     * Returns the default container or a named container.
-     *
-     * Calling this method with the same identifier returns the same container
-     * instance until that instance is disposed.
-     *
-     * @param id The container identifier. Omit this to use the default container.
-     * @returns The matching container instance.
-     */
+    pushMultiBinding(id, value) {
+        const bindings = this.multiBindingMap.get(id) ?? [];
+        bindings.push(value);
+        this.multiBindingMap.set(id, bindings);
+    }
+    pushMultiMetadata(id, metadata) {
+        const registrations = this.multiMetadataMap.get(id) ?? [];
+        registrations.push(metadata);
+        this.multiMetadataMap.set(id, registrations);
+    }
+    getOrCreateInheritedMultiMetadata(id, sourceMetadata) {
+        let inheritedRegistrations = this.inheritedMultiMetadataMap.get(id);
+        if (!inheritedRegistrations) {
+            inheritedRegistrations = new Map();
+            this.inheritedMultiMetadataMap.set(id, inheritedRegistrations);
+        }
+        const existingMetadata = inheritedRegistrations.get(sourceMetadata);
+        if (existingMetadata) {
+            return existingMetadata;
+        }
+        const metadata = this.cloneMetadata(sourceMetadata);
+        inheritedRegistrations.set(sourceMetadata, metadata);
+        return metadata;
+    }
+    defineInjection(instance, injection) {
+        const value = injection.multiple ? this.getMany(injection.id) : this.get(injection.id);
+        Object.defineProperty(instance, injection.name, {
+            value,
+            writable: true,
+            configurable: true,
+        });
+    }
+    resolveMetadata(metadata, resolutionContainer) {
+        if (metadata.scope !== 'transient' && metadata.value !== EMPTY_VALUE) {
+            return metadata.value;
+        }
+        if (resolutionContainer.resolving.has(metadata)) {
+            throw new CircularDependencyError([...resolutionContainer.resolvingPath, metadata.id]);
+        }
+        resolutionContainer.resolving.add(metadata);
+        resolutionContainer.resolvingPath.push(metadata.id);
+        try {
+            const instance = metadata.factory ? metadata.factory(resolutionContainer) : new metadata.Class();
+            for (const injection of metadata.injections) {
+                this.defineInjection(instance, injection);
+            }
+            if (metadata.scope !== 'transient') {
+                metadata.value = instance;
+            }
+            return instance;
+        }
+        finally {
+            resolutionContainer.resolving.delete(metadata);
+            resolutionContainer.resolvingPath.pop();
+        }
+    }
+    resetMetadataValues() {
+        this.metadataMap.forEach((metadata) => {
+            metadata.value = EMPTY_VALUE;
+        });
+        this.multiMetadataMap.forEach((registrations) => {
+            registrations.forEach((metadata) => {
+                metadata.value = EMPTY_VALUE;
+            });
+        });
+        this.inheritedMultiMetadataMap.forEach((registrations) => {
+            registrations.forEach((metadata) => {
+                metadata.value = EMPTY_VALUE;
+            });
+        });
+    }
+    collectOwnedValues() {
+        const ownedValues = new Set();
+        this.bindingMap.forEach((value) => {
+            ownedValues.add(value);
+        });
+        this.multiBindingMap.forEach((values) => {
+            values.forEach((value) => {
+                ownedValues.add(value);
+            });
+        });
+        this.metadataMap.forEach((metadata) => {
+            if (metadata.value !== EMPTY_VALUE) {
+                ownedValues.add(metadata.value);
+            }
+        });
+        this.multiMetadataMap.forEach((registrations) => {
+            registrations.forEach((metadata) => {
+                if (metadata.value !== EMPTY_VALUE) {
+                    ownedValues.add(metadata.value);
+                }
+            });
+        });
+        this.inheritedMultiMetadataMap.forEach((registrations) => {
+            registrations.forEach((metadata) => {
+                if (metadata.value !== EMPTY_VALUE) {
+                    ownedValues.add(metadata.value);
+                }
+            });
+        });
+        return ownedValues;
+    }
+    unlinkParent() {
+        this.parentContainer?.children.delete(this);
+        this.parentContainer = undefined;
+    }
+    hasParent(parent) {
+        return this.parentContainer === parent;
+    }
     static of(id = 'default') {
         if (id === 'default') {
             return ContainerRegistry.defaultContainer;
@@ -91,30 +210,41 @@ export class Container {
         if (ContainerRegistry.hasContainer(id)) {
             return ContainerRegistry.getContainer(id);
         }
-        const container = new Container(id);
+        const container = new Container(id, ContainerRegistry.defaultContainer);
         ContainerRegistry.registerContainer(container);
         return container;
     }
-    /**
-     * Registers service metadata in this container.
-     *
-     * This is a low-level API for manual registration when you are not using
-     * `@Service()`. Registering a `singleton` on a named container stores it in
-     * the default container so it can be shared across containers.
-     *
-     * @param metadata The service metadata to register.
-     * @returns The current container.
-     */
+    static ofChild(id, parent = 'default') {
+        const parentContainer = parent instanceof Container ? parent : Container.of(parent);
+        if (id === 'default') {
+            return ContainerRegistry.defaultContainer;
+        }
+        const existingContainer = ContainerRegistry.getContainer(id);
+        if (existingContainer) {
+            if (!existingContainer.hasParent(parentContainer)) {
+                throw new Error(`Container already exists with a different parent: ${String(id)}`);
+            }
+            return existingContainer;
+        }
+        const container = new Container(id, parentContainer);
+        ContainerRegistry.registerContainer(container);
+        return container;
+    }
+    ofChild(id) {
+        return Container.ofChild(id, this);
+    }
     register(metadata) {
         this.ensureNotDisposed();
-        if (metadata.scope === 'singleton' && !this.isDefault()) {
-            ContainerRegistry.defaultContainer.register(metadata);
+        if (metadata.scope === 'singleton' && !this.isRoot()) {
+            this.getRoot().register(metadata);
             this.metadataMap.delete(metadata.id);
             return this;
         }
-        const newMetadata = {
-            ...metadata,
-        };
+        const newMetadata = this.cloneMetadata(metadata);
+        if (newMetadata.multiple) {
+            this.pushMultiMetadata(newMetadata.id, newMetadata);
+            return this;
+        }
         const existingMetadata = this.metadataMap.get(newMetadata.id);
         if (existingMetadata) {
             Object.assign(existingMetadata, newMetadata);
@@ -124,18 +254,13 @@ export class Container {
         }
         return this;
     }
-    /**
-     * Returns whether this container has a local registration for an identifier.
-     *
-     * This only checks registrations stored on the current container and does
-     * not indicate whether the identifier can be resolved through fallback.
-     *
-     * @param id The service identifier to check.
-     * @returns `true` when the current container has a local registration.
-     */
     has(id) {
         this.ensureNotDisposed();
-        return this.bindingMap.has(id) || this.metadataMap.has(id);
+        return (this.bindingMap.has(id) ||
+            this.metadataMap.has(id) ||
+            (this.multiBindingMap.get(id)?.length ?? 0) > 0 ||
+            (this.multiMetadataMap.get(id)?.length ?? 0) > 0 ||
+            (this.inheritedMultiMetadataMap.get(id)?.size ?? 0) > 0);
     }
     set(id, valueOrProvider) {
         this.ensureNotDisposed();
@@ -156,122 +281,100 @@ export class Container {
         this.metadataMap.delete(id);
         return this;
     }
-    /**
-     * Removes a local binding or registration from this container.
-     *
-     * @param id The service identifier to remove.
-     * @returns The current container.
-     */
+    add(id, valueOrProvider) {
+        this.ensureNotDisposed();
+        if (this.isValueProvider(valueOrProvider)) {
+            this.pushMultiBinding(id, valueOrProvider.useValue);
+            return this;
+        }
+        if (this.isClassProvider(valueOrProvider)) {
+            return this.register(this.getClassProviderMetadata(id, valueOrProvider, true));
+        }
+        if (this.isFactoryProvider(valueOrProvider)) {
+            return this.register(this.getFactoryProviderMetadata(id, valueOrProvider, true));
+        }
+        this.pushMultiBinding(id, valueOrProvider);
+        return this;
+    }
     remove(id) {
         this.ensureNotDisposed();
         this.bindingMap.delete(id);
         this.metadataMap.delete(id);
+        this.multiBindingMap.delete(id);
+        this.multiMetadataMap.delete(id);
+        this.inheritedMultiMetadataMap.delete(id);
         return this;
     }
-    /**
-     * Resets services stored in this container.
-     *
-     * Use `'value'` to clear cached instances while keeping registrations, or
-     * `'service'` to remove local registrations and bindings entirely.
-     *
-     * @param strategy The reset strategy to apply.
-     * @returns The current container.
-     */
     reset(strategy = 'value') {
         this.ensureNotDisposed();
         if (strategy === 'value') {
-            this.metadataMap.forEach((metadata) => {
-                metadata.value = EMPTY_VALUE;
-            });
-            return this;
-        }
-        else {
-            this.bindingMap.clear();
-            this.metadataMap.clear();
+            this.resetMetadataValues();
             return this;
         }
+        this.bindingMap.clear();
+        this.metadataMap.clear();
+        this.multiBindingMap.clear();
+        this.multiMetadataMap.clear();
+        this.inheritedMultiMetadataMap.clear();
+        return this;
     }
-    /**
-     * Resolves a service from this container.
-     *
-     * If the current container does not have a local registration, named
-     * containers can continue resolution through the default container according
-     * to the service scope. Services are instantiated with `new Class()` and do
-     * not support constructor arguments.
-     *
-     * @param id The service identifier to resolve.
-     * @returns The resolved service instance or bound value.
-     * @throws {ServiceNotFoundError} If no service is registered for the identifier.
-     * @throws {CircularDependencyError} If the dependency graph contains a cycle.
-     */
     get(id) {
         this.ensureNotDisposed();
         if (this.bindingMap.has(id)) {
             return this.bindingMap.get(id);
         }
-        let metadata = this.metadataMap.get(id);
-        if (!metadata && !this.isDefault()) {
-            if (ContainerRegistry.defaultContainer.bindingMap.has(id)) {
-                return ContainerRegistry.defaultContainer.bindingMap.get(id);
-            }
-            const defaultMetadata = ContainerRegistry.defaultContainer.metadataMap.get(id);
-            if (!defaultMetadata) {
-                throw new ServiceNotFoundError(id);
-            }
-            if (defaultMetadata.scope === 'singleton') {
-                return ContainerRegistry.defaultContainer.get(id);
-            }
-            if (defaultMetadata.scope === 'container') {
-                metadata = {
-                    ...defaultMetadata,
-                    injections: [...defaultMetadata.injections],
-                    value: EMPTY_VALUE,
-                };
-                this.metadataMap.set(id, metadata);
-            }
-            else {
-                metadata = defaultMetadata;
-            }
+        const localMetadata = this.metadataMap.get(id);
+        if (localMetadata) {
+            return this.resolveMetadata(localMetadata, this);
+        }
+        const bindingOwner = this.parentContainer?.findBindingOwner(id);
+        if (bindingOwner) {
+            return bindingOwner.bindingMap.get(id);
         }
-        if (!metadata) {
+        const metadataOwner = this.parentContainer?.findMetadataOwner(id);
+        if (!metadataOwner) {
             throw new ServiceNotFoundError(id);
         }
-        if (metadata.scope !== 'transient' && metadata.value !== EMPTY_VALUE) {
-            return metadata.value;
+        const metadata = metadataOwner.metadataMap.get(id);
+        if (metadata.scope === 'singleton') {
+            return metadataOwner.resolveMetadata(metadata, metadataOwner);
         }
-        if (this.resolving.has(id)) {
-            throw new CircularDependencyError([...this.resolvingPath, id]);
+        if (metadata.scope === 'container') {
+            const localizedMetadata = this.cloneMetadata(metadata);
+            this.metadataMap.set(id, localizedMetadata);
+            return this.resolveMetadata(localizedMetadata, this);
         }
-        this.resolving.add(id);
-        this.resolvingPath.push(id);
-        try {
-            const instance = metadata.factory ? metadata.factory(this) : new metadata.Class();
-            for (const injection of metadata.injections) {
-                Object.defineProperty(instance, injection.name, {
-                    value: this.get(injection.id),
-                    writable: true,
-                    configurable: true,
-                });
+        return this.resolveMetadata(metadata, this);
+    }
+    getMany(id) {
+        this.ensureNotDisposed();
+        const resolved = [];
+        for (const container of this.getLineage()) {
+            const bindings = container.multiBindingMap.get(id) ?? [];
+            resolved.push(...bindings);
+            const registrations = container.multiMetadataMap.get(id);
+            if (!registrations) {
+                continue;
             }
-            if (metadata.scope !== 'transient') {
-                metadata.value = instance;
+            for (const metadata of registrations) {
+                if (container === this) {
+                    resolved.push(this.resolveMetadata(metadata, this));
+                    continue;
+                }
+                if (metadata.scope === 'singleton') {
+                    resolved.push(container.resolveMetadata(metadata, container));
+                    continue;
+                }
+                if (metadata.scope === 'container') {
+                    const localizedMetadata = this.getOrCreateInheritedMultiMetadata(id, metadata);
+                    resolved.push(this.resolveMetadata(localizedMetadata, this));
+                    continue;
+                }
+                resolved.push(this.resolveMetadata(metadata, this));
             }
-            return instance;
         }
-        finally {
-            this.resolving.delete(id);
-            this.resolvingPath.pop();
-        }
-    }
-    /**
-     * Resolves a service if it exists, otherwise returns `undefined`.
-     *
-     * Unlike `get()`, this only suppresses `ServiceNotFoundError`. Other errors,
-     * such as circular dependencies or disposed-container access, still surface.
-     *
-     * @param id The service identifier to resolve.
-     * @returns The resolved value, or `undefined` when the service is missing.
-     */
+        return resolved;
+    }
     tryGet(id) {
         this.ensureNotDisposed();
         if (!this.canResolve(id)) {
@@ -279,30 +382,23 @@ export class Container {
         }
         return this.get(id);
     }
-    /**
-     * Disposes this container instance and clears all local registrations.
-     *
-     * The container becomes unusable after disposal. Cached service instances and
-     * bound values that expose an async or sync `dispose()` method are awaited in
-     * the order they were discovered.
-     */
     async dispose() {
         if (this.disposed) {
             return;
         }
-        const ownedValues = new Set();
-        this.bindingMap.forEach((value) => {
-            ownedValues.add(value);
-        });
-        this.metadataMap.forEach((metadata) => {
-            if (metadata.value !== EMPTY_VALUE) {
-                ownedValues.add(metadata.value);
-            }
-        });
+        const childContainers = [...this.children];
+        for (const child of childContainers) {
+            await child.dispose();
+        }
+        const ownedValues = this.collectOwnedValues();
         this.disposed = true;
         ContainerRegistry.disposeContainer(this);
         this.bindingMap.clear();
         this.metadataMap.clear();
+        this.multiBindingMap.clear();
+        this.multiMetadataMap.clear();
+        this.inheritedMultiMetadataMap.clear();
+        this.children.clear();
         this.resolving.clear();
         this.resolvingPath = [];
         for (const value of ownedValues) {
@@ -311,15 +407,6 @@ export class Container {
             }
         }
     }
-    isDefault() {
-        return this === ContainerRegistry.defaultContainer;
-    }
-    /**
-     * Resets a container by its identifier.
-     *
-     * @param containerId The container to reset.
-     * @param options Reset options.
-     */
     static reset(containerId, options) {
         const container = ContainerRegistry.getContainer(containerId);
         container?.reset(options?.strategy);

package/dist/container/registry.d.ts

@@ -1,52 +1,12 @@
 import type { ContainerIdentifier } from '../types';
 import { Container } from './container';
-/**
- * Stores the default container and all named containers.
- *
- * This registry is the shared source of truth behind `Container.of()` and
- * decorator-based service registration.
- *
- * @internal
- */
 export declare class ContainerRegistry {
     private static defaultContainerInstance?;
     private static readonly containerMap;
-    /**
-     * Returns the canonical default container instance.
-     *
-     * The default container is created lazily the first time it is requested.
-     */
     static get defaultContainer(): Container;
-    /**
-     * Registers a named container in the shared registry.
-     *
-     * @param container The container to register.
-     * @throws {DefaultContainerIdError} If the container uses the reserved `default` id.
-     * @throws {ContainerDuplicatedError} If another container already uses the same id.
-     */
     static registerContainer(container: Container): void;
-    /**
-     * Returns the default container or a named container by identifier.
-     *
-     * @param id The container identifier to resolve.
-     * @returns The default container for `'default'`, or the matching named container if one exists.
-     */
     static getContainer(id: ContainerIdentifier): Container | undefined;
-    /**
-     * Returns whether a container exists for the given identifier.
-     *
-     * The reserved `default` identifier is always treated as present.
-     *
-     * @param id The container identifier to check.
-     * @returns `true` when the container exists in the registry.
-     */
     static hasContainer(id: ContainerIdentifier): boolean;
-    /**
-     * Removes a named container from the registry.
-     *
-     * @param id The named container identifier to remove.
-     * @throws {DefaultContainerIdError} If the reserved `default` id is used.
-     */
     static removeContainer(id: ContainerIdentifier): void;
     static disposeContainer(container: Container): void;
 }

package/dist/container/registry.js

@@ -1,32 +1,12 @@
 import { ContainerDuplicatedError, DefaultContainerIdError } from '../errors';
 import { Container } from './container';
-/**
- * Stores the default container and all named containers.
- *
- * This registry is the shared source of truth behind `Container.of()` and
- * decorator-based service registration.
- *
- * @internal
- */
 export class ContainerRegistry {
     static defaultContainerInstance;
     static containerMap = new Map();
-    /**
-     * Returns the canonical default container instance.
-     *
-     * The default container is created lazily the first time it is requested.
-     */
     static get defaultContainer() {
         this.defaultContainerInstance ??= new Container('default');
         return this.defaultContainerInstance;
     }
-    /**
-     * Registers a named container in the shared registry.
-     *
-     * @param container The container to register.
-     * @throws {DefaultContainerIdError} If the container uses the reserved `default` id.
-     * @throws {ContainerDuplicatedError} If another container already uses the same id.
-     */
     static registerContainer(container) {
         if (container.id === 'default') {
             throw new DefaultContainerIdError();
@@ -36,45 +16,28 @@ export class ContainerRegistry {
         }
         this.containerMap.set(container.id, container);
     }
-    /**
-     * Returns the default container or a named container by identifier.
-     *
-     * @param id The container identifier to resolve.
-     * @returns The default container for `'default'`, or the matching named container if one exists.
-     */
     static getContainer(id) {
         if (id === 'default') {
             return this.defaultContainer;
         }
         return this.containerMap.get(id);
     }
-    /**
-     * Returns whether a container exists for the given identifier.
-     *
-     * The reserved `default` identifier is always treated as present.
-     *
-     * @param id The container identifier to check.
-     * @returns `true` when the container exists in the registry.
-     */
     static hasContainer(id) {
         if (id === 'default') {
             return true;
         }
         return this.containerMap.has(id);
     }
-    /**
-     * Removes a named container from the registry.
-     *
-     * @param id The named container identifier to remove.
-     * @throws {DefaultContainerIdError} If the reserved `default` id is used.
-     */
     static removeContainer(id) {
         if (id === 'default') {
             throw new DefaultContainerIdError();
         }
+        const container = this.containerMap.get(id);
+        container?.unlinkParent();
         this.containerMap.delete(id);
     }
     static disposeContainer(container) {
+        container.unlinkParent();
         if (container.id === 'default') {
             if (this.defaultContainerInstance === container) {
                 this.defaultContainerInstance = undefined;

package/dist/decorators/index.d.ts

@@ -1,2 +1,3 @@
 export { Inject } from './inject';
+export { InjectMany } from './inject-many';
 export { Service } from './service';

package/dist/decorators/index.js

@@ -1,2 +1,3 @@
 export { Inject } from './inject';
+export { InjectMany } from './inject-many';
 export { Service } from './service';

package/dist/decorators/inject-many.d.ts

@@ -0,0 +1,2 @@
+import { type ServiceIdentifier } from '../types';
+export declare function InjectMany<T>(dependency: ServiceIdentifier<T>): (_: undefined, context: ClassFieldDecoratorContext) => void;

package/dist/decorators/inject-many.js

@@ -0,0 +1,11 @@
+import { INJECTION_KEY } from '../types';
+export function InjectMany(dependency) {
+    return function (_, context) {
+        const injections = (context.metadata[INJECTION_KEY] ??= []);
+        injections.push({
+            id: dependency,
+            name: context.name,
+            multiple: true,
+        });
+    };
+}

package/dist/decorators/service.js

@@ -20,6 +20,7 @@ export function Service(idOrOptions) {
             injections,
             scope: options?.scope ?? 'container',
             value: EMPTY_VALUE,
+            multiple: options?.multiple,
         });
     };
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Container } from './container';
-export { Service, Inject } from './decorators';
+export { Service, Inject, InjectMany } from './decorators';
 export { Token } from './tokens';
 export type { AbstractConstructable, Constructable } from './types/constructable.ts';
 export type { ServiceIdentifier } from './types/service.ts';

package/dist/index.js

@@ -1,3 +1,3 @@
 export { Container } from './container';
-export { Service, Inject } from './decorators';
+export { Service, Inject, InjectMany } from './decorators';
 export { Token } from './tokens';

package/dist/types/container.d.ts

@@ -87,6 +87,7 @@ export interface Metadata<T = unknown> {
      * The cached service instance, or `EMPTY_VALUE` when no instance is cached.
      */
     value: T | typeof EMPTY_VALUE;
+    multiple?: boolean;
     /**
      * An optional factory used to create the resolved value.
      */

package/dist/types/injection.d.ts

@@ -11,6 +11,7 @@ export interface InjectionMetadata {
      * The class field that receives the resolved dependency.
      */
     name: string | symbol;
+    multiple?: boolean;
 }
 /**
  * Metadata key used internally to store property injection definitions.

package/dist/types/service.d.ts

@@ -20,4 +20,5 @@ export interface ServiceOption {
      * The lifetime used when the service is resolved.
      */
     scope?: ServiceScope;
+    multiple?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "navi-di",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Dependency injection for standard ECMAScript decorators.",
   "author": "naviary-sanctuary",
   "keywords": [