katagami 2.0.0 → 2.2.0

package/README.md

@@ -8,22 +8,25 @@ Lightweight TypeScript DI container with full type inference.
 [![license](https://img.shields.io/npm/l/katagami)](https://github.com/hiroiku/katagami/blob/master/LICENSE)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/katagami)](https://bundlephobia.com/package/katagami)
 
-> The name comes from 型紙 _(katagami)_ — precision stencil paper used in traditional Japanese dyeing to transfer exact patterns onto fabric. Multiple stencils are layered to compose intricate designs, just as types accumulate through each method-chain call. A stencil needs only paper and a brush, no elaborate machinery — likewise, Katagami requires no decorators or metadata mechanisms and works with any build tool out of the box. And like stencils that work across different fabrics and techniques, Katagami adapts across TypeScript and JavaScript, class tokens and PropertyKey tokens — a hybrid approach to strict, composable DI.
+> The name comes from 型紙 _(katagami)_ — precision stencil paper used in traditional Japanese dyeing to transfer exact patterns onto fabric. Multiple stencils are layered to compose intricate designs, just as types accumulate through each method-chain call. Each stencil is a self-contained piece — chosen only for the current work, the rest left behind — just as subpath exports ensure only the code you use enters your bundle. The cut pattern determines exactly where dye passes and where it is blocked, much like Katagami's type system catches misuse at compile time, not at runtime. And a stencil needs only paper and a brush, no elaborate machinery — likewise, Katagami requires no decorators or metadata mechanisms and works with any build tool out of the box.
 
 ## Features
 
-| Feature                       | Description                                                                                  |
-| ----------------------------- | -------------------------------------------------------------------------------------------- |
-| Full type inference           | Types accumulate through method chaining; unregistered tokens are compile-time errors        |
-| Three lifetimes               | Singleton, Transient, and Scoped with child containers                                       |
-| Async factories               | Promise-returning factories are automatically tracked by the type system                     |
-| Circular dependency detection | Clear error messages with the full cycle path                                                |
-| Disposable support            | TC39 Explicit Resource Management (`Symbol.dispose` / `Symbol.asyncDispose` / `await using`) |
-| Captive dependency prevention | Singleton/Transient factories cannot access scoped tokens; caught at compile time            |
-| Optional resolution           | `tryResolve` returns `undefined` for unregistered tokens instead of throwing                 |
-| Hybrid token strategy         | Class tokens for strict type safety, PropertyKey tokens for flexibility                      |
-| Interface type map            | Pass an interface to `createContainer<T>()` for order-independent registration               |
-| Zero dependencies             | No decorators, no reflect-metadata, no polyfills                                             |
+| Feature                       | Description                                                                                                |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Zero dependencies             | No decorators, no reflect-metadata, no polyfills — works with any bundler out of the box                   |
+| Full type inference           | Types accumulate through method chaining; unregistered tokens are compile-time errors                      |
+| Tree-shakeable                | Subpath exports (`katagami/scope`, `katagami/disposable`) and `sideEffects: false` for minimal bundle size |
+| Captive dependency prevention | Singleton/Transient factories cannot access scoped tokens; caught at compile time                          |
+| Hybrid token strategy         | Class tokens for strict type safety, PropertyKey tokens for flexibility                                    |
+| Interface type map            | Pass an interface to `createContainer<T>()` for order-independent registration                             |
+| Three lifetimes               | Singleton, Transient, and Scoped with child containers                                                     |
+| Disposable support            | TC39 Explicit Resource Management (`Symbol.dispose` / `Symbol.asyncDispose` / `await using`)               |
+| Module composition            | Containers can be composed via `use()` to group and reuse registrations                                    |
+| Async factories               | Promise-returning factories are automatically tracked by the type system                                   |
+| Circular dependency detection | Clear error messages with the full cycle path                                                              |
+| Optional resolution           | `tryResolve` returns `undefined` for unregistered tokens instead of throwing                               |
+| Lazy resolution               | Proxy-based deferred instantiation via `lazy()` from `katagami/lazy`; instance created on first access     |
 
 ## Install
 
@@ -66,6 +69,20 @@ Most TypeScript DI containers rely on decorators, reflect-metadata, or string-ba
 
 Decorator-based DI requires `experimentalDecorators` and `emitDecoratorMetadata` compiler options. Modern build tools such as esbuild and Vite (default configuration) do not support `emitDecoratorMetadata`, and the TC39 standard decorators proposal does not include an equivalent for automatic type metadata emission. Katagami depends on none of these — it works with any build tool out of the box.
 
+### Tree-shakeable
+
+Katagami is split into subpath exports. Import only what you use — `katagami/scope`, `katagami/disposable`, and `katagami/lazy` are completely eliminated from the bundle if not imported. Combined with `sideEffects: false`, bundlers can remove every unused byte.
+
+```ts
+// Core only — scope, disposable, and lazy are not included in the bundle
+import { createContainer } from 'katagami';
+
+// Import only what you need
+import { createScope } from 'katagami/scope';
+import { disposable } from 'katagami/disposable';
+import { lazy } from 'katagami/lazy';
+```
+
 ### Full type inference from class tokens
 
 String-token DI forces you to maintain manual token-to-type mappings. Parameter-name matching breaks under minification. Katagami uses classes directly as tokens, so `resolve` automatically infers the correct return type — synchronous or `Promise` — with no extra annotations.
@@ -155,6 +172,53 @@ parentScope.resolve(RequestContext) === childScope.resolve(RequestContext); // f
 parentScope.resolve(DbPool) === childScope.resolve(DbPool); // true
 ```
 
+### Module Composition
+
+Group related registrations into a reusable module by creating a container with `createContainer()`, then apply it to another container with `use()`. Only registration entries are copied — singleton instance caches are not shared.
+
+```ts
+import { createContainer } from 'katagami';
+
+class AuthService {
+	authenticate() {
+		return true;
+	}
+}
+
+class TokenService {
+	issue() {
+		return 'token';
+	}
+}
+
+class UserService {
+	constructor(private auth: AuthService, private tokens: TokenService) {}
+}
+
+// Define a reusable module
+const authModule = createContainer()
+	.registerSingleton(AuthService, () => new AuthService())
+	.registerSingleton(TokenService, () => new TokenService());
+
+// Compose modules
+const container = createContainer()
+	.use(authModule)
+	.registerSingleton(UserService, r => new UserService(r.resolve(AuthService), r.resolve(TokenService)));
+```
+
+Modules can also compose other modules:
+
+```ts
+const infraModule = createContainer().registerSingleton(AuthService, () => new AuthService());
+
+const appModule = createContainer()
+	.use(infraModule)
+	.registerSingleton(UserService, r => new UserService(r.resolve(AuthService), r.resolve(TokenService)));
+
+// appModule includes both AuthService and UserService
+const container = createContainer().use(appModule);
+```
+
 ### Async Factories
 
 Factories that return a `Promise` are automatically tracked by the type system. When you `resolve` an async token, the return type is `Promise<V>` instead of `V`:
@@ -243,9 +307,7 @@ class Connection {
 }
 
 // Manual disposal
-const container = disposable(
-	createContainer().registerSingleton(Connection, () => new Connection()),
-);
+const container = disposable(createContainer().registerSingleton(Connection, () => new Connection()));
 
 container.resolve(Connection);
 await container[Symbol.asyncDispose]();
@@ -271,6 +333,70 @@ const root = createContainer()
 
 Scope disposal only affects scoped instances. Singleton instances are owned by the root container and are disposed when the container itself is disposed.
 
+The `disposable()` wrapper also narrows the returned type so that registration methods (`registerSingleton`, `registerTransient`, `registerScoped`, `use`) are removed at the type level. This prevents accidental registration on a potentially-disposed container:
+
+```ts
+const container = disposable(createContainer().registerSingleton(Connection, () => new Connection()));
+
+container.resolve(Connection); // OK
+container.registerSingleton(/* ... */); // Compile-time error
+```
+
+### Lazy Resolution
+
+The `lazy()` function from `katagami/lazy` creates a proxy that defers instance creation until the first property access. This is useful for optimizing startup time or breaking circular dependencies.
+
+```ts
+import { createContainer } from 'katagami';
+import { lazy } from 'katagami/lazy';
+
+class HeavyService {
+	constructor() {
+		// expensive initialization
+	}
+	process() {
+		return 'done';
+	}
+}
+
+const container = createContainer().registerSingleton(HeavyService, () => new HeavyService());
+
+const service = lazy(container, HeavyService);
+// HeavyService is NOT instantiated yet
+
+service.process(); // instance created here, then cached
+service.process(); // uses the cached instance
+```
+
+The proxy transparently forwards all property access, method calls, `in` checks, and prototype lookups to the real instance. Methods are automatically bound to the real instance, so `this` works correctly even when destructured.
+
+Only **sync class tokens** are supported. Async tokens and PropertyKey tokens are rejected at the type level because Proxy traps are synchronous.
+
+`lazy()` works with Container, Scope, DisposableContainer, and DisposableScope:
+
+```ts
+import { createScope } from 'katagami/scope';
+
+const root = createContainer().registerScoped(RequestContext, () => new RequestContext());
+const scope = createScope(root);
+
+const ctx = lazy(scope, RequestContext); // deferred scoped resolution
+```
+
+### Tree Shaking
+
+Katagami uses subpath exports to split functionality into independent entry points. If you only need the core container, `katagami/scope`, `katagami/disposable`, and `katagami/lazy` are completely excluded from the bundle. The package declares `sideEffects: false`, so bundlers can safely eliminate any unused code.
+
+```ts
+// Core only — scope, disposable, and lazy are not included in the bundle
+import { createContainer } from 'katagami';
+
+// Import only what you need
+import { createScope } from 'katagami/scope';
+import { disposable } from 'katagami/disposable';
+import { lazy } from 'katagami/lazy';
+```
+
 ### Interface Type Map
 
 When you pass an interface to `createContainer<T>()`, PropertyKey tokens are typed from the interface rather than accumulated through chaining. This means you can register and resolve tokens in any order:
@@ -400,23 +526,27 @@ const container = createContainer()
 
 Creates a new DI container. Pass an interface as `T` to define the type map for PropertyKey tokens. Pass `ScopedT` to define a separate type map for scoped PropertyKey tokens (order-independent, just like `T`).
 
-### `container.registerSingleton(token, factory)`
+### `Container.prototype.registerSingleton(token, factory)`
 
 Registers a factory as a singleton. The instance is created on the first `resolve` and cached thereafter. Returns the container for method chaining.
 
-### `container.registerTransient(token, factory)`
+### `Container.prototype.registerTransient(token, factory)`
 
 Registers a factory as transient. A new instance is created on every `resolve`. Returns the container for method chaining.
 
-### `container.registerScoped(token, factory)`
+### `Container.prototype.registerScoped(token, factory)`
 
 Registers a factory as scoped. Within a scope, the instance is created on the first `resolve` and cached for that scope. Each scope maintains its own cache. Scoped tokens cannot be resolved from the root container. Returns the container for method chaining.
 
-### `container.resolve(token)`
+### `Container.prototype.use(source)`
+
+Copies all registrations from `source` (another `Container`) into this container. Only factory and lifetime entries are copied — singleton instance caches are not shared. Returns the container for method chaining.
+
+### `Container.prototype.resolve(token)`
 
 Resolves and returns the instance for the given token. Throws `ContainerError` if the token is not registered or if a circular dependency is detected.
 
-### `container.tryResolve(token)` / `scope.tryResolve(token)`
+### `Container.prototype.tryResolve(token)`
 
 Attempts to resolve the instance for the given token. Returns `undefined` if the token is not registered, instead of throwing. Still throws `ContainerError` for circular dependencies or operations on disposed containers/scopes.
 
@@ -424,19 +554,31 @@ Attempts to resolve the instance for the given token. Returns `undefined` if the
 
 Creates a new `Scope` (child container) from a `Container` or an existing `Scope`. The scope inherits all registrations from the source. Singleton instances are shared with the parent, while scoped instances are local to the scope.
 
-### `Scope`
+### `class Scope`
+
+A scoped child container created by `createScope()`.
+
+### `Scope.prototype.resolve(token)`
+
+Resolves and returns the instance for the given token. Behaves the same as `Container.prototype.resolve`, but can also resolve scoped tokens.
+
+### `Scope.prototype.tryResolve(token)`
+
+Attempts to resolve the instance for the given token. Returns `undefined` if the token is not registered, instead of throwing. Still throws `ContainerError` for circular dependencies or operations on disposed scopes.
+
+### `lazy(source, token)` — `katagami/lazy`
 
-A scoped child container created by `createScope()`. Provides `resolve(token)` and `tryResolve(token)`.
+Creates a Proxy that defers `resolve()` until the first property access. The resolved instance is cached — subsequent accesses use the cache. Only sync class tokens are supported; async tokens and PropertyKey tokens are rejected at the type level. Works with `Container`, `Scope`, `DisposableContainer`, and `DisposableScope`.
 
 ### `disposable(container)` — `katagami/disposable`
 
-Attaches `[Symbol.asyncDispose]` to a `Container` or `Scope`, enabling `await using` syntax. Disposes all owned instances in reverse creation order (LIFO). Calls `[Symbol.asyncDispose]()` or `[Symbol.dispose]()` on each instance that implements them. Idempotent — subsequent calls are no-ops. After disposal, `resolve()` and `createScope()` will throw `ContainerError`.
+Attaches `[Symbol.asyncDispose]` to a `Container` or `Scope`, enabling `await using` syntax. Disposes all owned instances in reverse creation order (LIFO). Calls `[Symbol.asyncDispose]()` or `[Symbol.dispose]()` on each instance that implements them. Idempotent — subsequent calls are no-ops. After disposal, `resolve()` and `createScope()` will throw `ContainerError`. The returned type is narrowed to `DisposableContainer` or `DisposableScope`, which only expose `resolve` and `tryResolve` — registration methods are excluded at the type level.
 
-### `ContainerError`
+### `class ContainerError`
 
 Error class thrown for container failures such as resolving an unregistered token, circular dependencies, or operations on a disposed container/scope.
 
-### `Resolver`
+### `type Resolver`
 
 Type export representing the resolver passed to factory callbacks. Useful when you need to type a function that accepts a resolver parameter.
 

package/dist/container/index.d.ts

@@ -23,6 +23,9 @@ export declare function createContainer<T = Record<never, never>, ScopedT = Reco
  * - Singleton: Creates the instance on the first resolve and returns the cached value thereafter.
  * - Transient: Creates a new instance via the factory function on every resolve.
  *
+ * Registering the same token multiple times accumulates all factories.
+ * `resolve()` returns the last registered instance, while `resolveAll()` returns all.
+ *
  * @template T PropertyKey-based token type map (defined via interface, order-independent)
  * @template Sync Union of registered sync class constructors (accumulated via chaining, order-dependent)
  * @template Async Union of registered async class constructors (accumulated via chaining, order-dependent)
@@ -32,7 +35,7 @@ export declare function createContainer<T = Record<never, never>, ScopedT = Reco
  */
 export declare class Container<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never> {
     private readonly registrations;
-    private readonly instances;
+    private readonly singletonCache;
     private readonly resolvingTokens;
     private disposed;
     /**
@@ -46,6 +49,8 @@ export declare class Container<T = Record<never, never>, Sync extends AbstractCo
      * Register a factory function as a singleton for the given token.
      *
      * Creates the instance on the first resolve and returns the cached value thereafter.
+     * If the same token is registered multiple times, all factories are accumulated.
+     * `resolve()` returns the last registered instance; `resolveAll()` returns all.
      *
      * @param token Any value to use as a token
      * @param factory Factory function that receives a resolver and returns an instance
@@ -59,6 +64,8 @@ export declare class Container<T = Record<never, never>, Sync extends AbstractCo
      * Register a factory function as transient for the given token.
      *
      * Creates a new instance via the factory function on every resolve.
+     * If the same token is registered multiple times, all factories are accumulated.
+     * `resolve()` returns the last registered instance; `resolveAll()` returns all.
      *
      * @param token Any value to use as a token
      * @param factory Factory function that receives a resolver and returns an instance
@@ -83,9 +90,20 @@ export declare class Container<T = Record<never, never>, Sync extends AbstractCo
     registerScoped<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V): Container<T, Sync, Async, ScopedT, ScopedSync | AbstractConstructor<V>, ScopedAsync>;
     registerScoped<K extends PropertyKey, V>(token: K, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V): Container<T, Sync, Async, Record<K, V> & ScopedT, ScopedSync, ScopedAsync>;
     registerScoped<V>(token: unknown, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+    /**
+     * Apply all registrations from another container (module) to this container.
+     *
+     * Copies registration entries (factory + lifetime) by replacing existing entries for each token.
+     * Singleton instance caches are not shared — each container manages its own.
+     *
+     * @param source A container whose registrations will be copied into this container
+     * @returns The container for method chaining
+     */
+    use<MT, MSync extends AbstractConstructor, MAsync extends AbstractConstructor, MScopedT, MScopedSync extends AbstractConstructor, MScopedAsync extends AbstractConstructor>(source: Container<MT, MSync, MAsync, MScopedT, MScopedSync, MScopedAsync>): Container<T & MT, Sync | MSync, Async | MAsync, ScopedT & MScopedT, ScopedSync | MScopedSync, ScopedAsync | MScopedAsync>;
     /**
      * Resolve an instance for the given token.
      *
+     * Returns the instance from the last registered factory for the token.
      * For singleton registrations, creates the instance on the first call and caches it.
      * For transient registrations, creates a new instance on every call.
      *
@@ -110,8 +128,36 @@ export declare class Container<T = Record<never, never>, Sync extends AbstractCo
     tryResolve<K extends keyof T>(token: K): T[K] | undefined;
     tryResolve<V>(token: AbstractConstructor<V>): V | Promise<V> | undefined;
     tryResolve(token: PropertyKey): unknown;
+    /**
+     * Resolve all instances for the given token.
+     *
+     * Returns an array of instances from all registered factories for the token,
+     * in registration order.
+     *
+     * @param token A registered token
+     * @returns An array of instances associated with the token
+     * @throws ContainerError if the token is not registered
+     */
+    resolveAll<V>(token: AbstractConstructor<V> & Async): Promise<V>[];
+    resolveAll<V>(token: AbstractConstructor<V> & Sync): V[];
+    resolveAll<K extends keyof T>(token: K): T[K][];
+    /**
+     * Try to resolve all instances for the given token.
+     *
+     * Returns `undefined` instead of throwing when the token is not registered.
+     * Other errors (circular dependency, disposed container) are still thrown.
+     *
+     * @param token A token to resolve
+     * @returns An array of instances associated with the token, or `undefined` if not registered
+     */
+    tryResolveAll<V>(token: AbstractConstructor<V> & Async): Promise<V>[] | undefined;
+    tryResolveAll<V>(token: AbstractConstructor<V> & Sync): V[] | undefined;
+    tryResolveAll<K extends keyof T>(token: K): T[K][] | undefined;
+    tryResolveAll<V>(token: AbstractConstructor<V>): (V | Promise<V>)[] | undefined;
+    tryResolveAll(token: PropertyKey): unknown;
     /**
      * Internal resolution logic shared by resolve and tryResolve.
+     * Resolves the last registered factory for the token.
      *
      * @param token Token to resolve
      * @param required If true, throws when the token is not registered. If false, returns undefined.
@@ -119,7 +165,16 @@ export declare class Container<T = Record<never, never>, Sync extends AbstractCo
      */
     private resolveToken;
     /**
-     * Add a registration entry.
+     * Internal resolution logic shared by resolveAll and tryResolveAll.
+     * Resolves all registered factories for the token.
+     *
+     * @param token Token to resolve
+     * @param required If true, throws when the token is not registered. If false, returns undefined.
+     * @returns An array of resolved instances, or undefined if not registered and required is false
+     */
+    private resolveAllTokens;
+    /**
+     * Add a registration entry. Accumulates registrations for the same token.
      *
      * @param token Token
      * @param factory Factory function

package/dist/disposable/index.cjs

@@ -44,7 +44,7 @@ function disposable(container) {
       return;
     }
     internals.markDisposed();
-    const instances = [...internals.ownInstances.values()].reverse();
+    const instances = [...internals.ownCache.values()].reverse();
     const errors = [];
     for (const instance of instances) {
       try {
@@ -63,7 +63,7 @@ function disposable(container) {
         errors.push(error);
       }
     }
-    internals.ownInstances.clear();
+    internals.ownCache.clear();
     if (errors.length > 0) {
       throw new AggregateError(errors, "One or more errors occurred during disposal.");
     }

package/dist/disposable/index.d.ts

@@ -1,4 +1,39 @@
+import type { Container } from '../container';
 import { type ContainerInternals, INTERNALS } from '../internal';
+import type { AbstractConstructor, Resolver } from '../resolver';
+import type { Scope } from '../scope';
+/**
+ * A container wrapped with `disposable()`.
+ *
+ * Only `resolve`, `tryResolve`, `resolveAll`, and `tryResolveAll` are available at the type level.
+ * Registration methods (`registerSingleton`, `registerTransient`, `registerScoped`, `use`)
+ * are excluded, preventing accidental registration on a potentially-disposed container.
+ *
+ * @template T PropertyKey-based token type map
+ * @template Sync Union of registered sync class constructors
+ * @template Async Union of registered async class constructors
+ * @template ScopedT PropertyKey-based token type map for scoped registrations
+ * @template ScopedSync Union of scoped sync class constructors
+ * @template ScopedAsync Union of scoped async class constructors
+ */
+export interface DisposableContainer<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, _ScopedT = Record<never, never>, _ScopedSync extends AbstractConstructor = never, _ScopedAsync extends AbstractConstructor = never> extends Resolver<T, Sync, Async>, AsyncDisposable {
+    readonly [INTERNALS]: ContainerInternals;
+}
+/**
+ * A scope wrapped with `disposable()`.
+ *
+ * Only `resolve`, `tryResolve`, `resolveAll`, and `tryResolveAll` are available at the type level.
+ *
+ * @template T PropertyKey-based token type map
+ * @template Sync Union of registered sync class constructors
+ * @template Async Union of registered async class constructors
+ * @template ScopedT PropertyKey-based token type map for scoped registrations
+ * @template ScopedSync Union of scoped sync class constructors
+ * @template ScopedAsync Union of scoped async class constructors
+ */
+export interface DisposableScope<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never> extends Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>, AsyncDisposable {
+    readonly [INTERNALS]: ContainerInternals;
+}
 /**
  * Add async disposal capability to a container or scope.
  *
@@ -6,8 +41,11 @@ import { type ContainerInternals, INTERNALS } from '../internal';
  * Disposes owned instances in reverse creation order (LIFO), calling
  * `[Symbol.asyncDispose]()` or `[Symbol.dispose]()` on each instance that implements them.
  *
+ * The returned type is narrowed to only expose `resolve`, `tryResolve`, `resolveAll`, and `tryResolveAll`,
+ * preventing registration methods from being called on a potentially-disposed container.
+ *
  * @param container A Container or Scope to make disposable
- * @returns The same object with `AsyncDisposable` capability added
+ * @returns The same object with `AsyncDisposable` capability added and registration methods removed from the type
  *
  * @example
  * ```ts
@@ -19,6 +57,5 @@ import { type ContainerInternals, INTERNALS } from '../internal';
  * );
  * ```
  */
-export declare function disposable<C extends {
-    readonly [INTERNALS]: ContainerInternals;
-}>(container: C): C & AsyncDisposable;
+export declare function disposable<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(container: Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): DisposableContainer<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+export declare function disposable<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(scope: Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): DisposableScope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;

package/dist/disposable/index.js

@@ -10,7 +10,7 @@ function disposable(container) {
       return;
     }
     internals.markDisposed();
-    const instances = [...internals.ownInstances.values()].reverse();
+    const instances = [...internals.ownCache.values()].reverse();
     const errors = [];
     for (const instance of instances) {
       try {
@@ -29,7 +29,7 @@ function disposable(container) {
         errors.push(error);
       }
     }
-    internals.ownInstances.clear();
+    internals.ownCache.clear();
     if (errors.length > 0) {
       throw new AggregateError(errors, "One or more errors occurred during disposal.");
     }

package/dist/index.cjs

@@ -78,22 +78,22 @@ function createContainer() {
 
 class Container {
   registrations;
-  instances;
+  singletonCache;
   resolvingTokens;
   disposed = false;
   [INTERNALS];
   constructor() {
     this.registrations = new Map;
-    this.instances = new Map;
+    this.singletonCache = new Map;
     this.resolvingTokens = new Set;
     this[INTERNALS] = {
-      instances: this.instances,
       isDisposed: () => this.disposed,
       markDisposed: () => {
         this.disposed = true;
       },
-      ownInstances: this.instances,
-      registrations: this.registrations
+      ownCache: this.singletonCache,
+      registrations: this.registrations,
+      singletonCache: this.singletonCache
     };
   }
   registerSingleton(token, factory) {
@@ -105,27 +105,40 @@ class Container {
   registerScoped(token, factory) {
     return this.addRegistration(token, factory, "scoped");
   }
+  use(source) {
+    for (const [token, registrations] of source[INTERNALS].registrations) {
+      this.registrations.set(token, [...registrations]);
+    }
+    return this;
+  }
   resolve(token) {
     return this.resolveToken(token, true);
   }
   tryResolve(token) {
     return this.resolveToken(token, false);
   }
+  resolveAll(token) {
+    return this.resolveAllTokens(token, true);
+  }
+  tryResolveAll(token) {
+    return this.resolveAllTokens(token, false);
+  }
   resolveToken(token, required) {
     if (this.disposed) {
       throw new ContainerError("Cannot resolve from a disposed container.");
     }
-    const cached = this.instances.get(token);
-    if (cached !== undefined) {
-      return cached;
-    }
-    const registration = this.registrations.get(token);
-    if (registration === undefined) {
+    const registrations = this.registrations.get(token);
+    if (registrations === undefined || registrations.length === 0) {
       if (required) {
         throw new ContainerError(`Token "${tokenToString(token)}" is not registered.`);
       }
       return;
     }
+    const registration = registrations[registrations.length - 1];
+    const cached = this.singletonCache.get(registration);
+    if (cached !== undefined) {
+      return cached;
+    }
     if (registration.lifetime === "scoped") {
       throw new ContainerError(`Cannot resolve scoped token "${tokenToString(token)}" from the root container. Use createScope() to create a scope first.`);
     }
@@ -136,15 +149,55 @@ class Container {
     try {
       const instance = registration.factory(this);
       if (registration.lifetime === "singleton") {
-        this.instances.set(token, instance);
+        this.singletonCache.set(registration, instance);
       }
       return instance;
     } finally {
       this.resolvingTokens.delete(token);
     }
   }
+  resolveAllTokens(token, required) {
+    if (this.disposed) {
+      throw new ContainerError("Cannot resolve from a disposed container.");
+    }
+    const registrations = this.registrations.get(token);
+    if (registrations === undefined || registrations.length === 0) {
+      if (required) {
+        throw new ContainerError(`Token "${tokenToString(token)}" is not registered.`);
+      }
+      return;
+    }
+    if (this.resolvingTokens.has(token)) {
+      throw new ContainerError(`Circular dependency detected: ${buildCircularPath(this.resolvingTokens, token)}`);
+    }
+    this.resolvingTokens.add(token);
+    try {
+      return registrations.map((registration) => {
+        const reg = registration;
+        const cached = this.singletonCache.get(registration);
+        if (cached !== undefined) {
+          return cached;
+        }
+        if (reg.lifetime === "scoped") {
+          throw new ContainerError(`Cannot resolve scoped token "${tokenToString(token)}" from the root container. Use createScope() to create a scope first.`);
+        }
+        const instance = reg.factory(this);
+        if (reg.lifetime === "singleton") {
+          this.singletonCache.set(registration, instance);
+        }
+        return instance;
+      });
+    } finally {
+      this.resolvingTokens.delete(token);
+    }
+  }
   addRegistration(token, factory, lifetime) {
-    this.registrations.set(token, { factory, lifetime });
+    const existing = this.registrations.get(token);
+    if (existing !== undefined) {
+      existing.push({ factory, lifetime });
+    } else {
+      this.registrations.set(token, [{ factory, lifetime }]);
+    }
     return this;
   }
 }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { Container, createContainer } from './container';
-export type { disposable } from './disposable';
+export type { DisposableContainer, DisposableScope, disposable } from './disposable';
 export { ContainerError } from './error';
+export type { lazy } from './lazy';
 export type { Resolver } from './resolver';
 export type { createScope, Scope } from './scope';