katagami 2.1.0 → 2.2.0

package/README.md

@@ -26,6 +26,7 @@ Lightweight TypeScript DI container with full type inference.
 | 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
 
@@ -70,15 +71,16 @@ Decorator-based DI requires `experimentalDecorators` and `emitDecoratorMetadata`
 
 ### Tree-shakeable
 
-Katagami is split into subpath exports. Import only what you use — `katagami/scope` and `katagami/disposable` are completely eliminated from the bundle if not imported. Combined with `sideEffects: false`, bundlers can remove every unused byte.
+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 and disposable are not included in the bundle
+// 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
@@ -340,17 +342,59 @@ 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` and `katagami/disposable` are completely excluded from the bundle. The package declares `sideEffects: false`, so bundlers can safely eliminate any unused code.
+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 and disposable are not included in the bundle
+// 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
@@ -522,6 +566,10 @@ Resolves and returns the instance for the given token. Behaves the same as `Cont
 
 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`
+
+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`. The returned type is narrowed to `DisposableContainer` or `DisposableScope`, which only expose `resolve` and `tryResolve` — registration methods are excluded at the type level.

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
@@ -86,8 +93,8 @@ export declare class Container<T = Record<never, never>, Sync extends AbstractCo
     /**
      * Apply all registrations from another container (module) to this container.
      *
-     * Copies only registration entries (factory + lifetime). Singleton instance caches
-     * are not shared — each container manages its own.
+     * 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
@@ -96,6 +103,7 @@ export declare class Container<T = Record<never, never>, Sync extends AbstractCo
     /**
      * 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.
      *
@@ -120,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.
@@ -129,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

@@ -5,7 +5,7 @@ import type { Scope } from '../scope';
 /**
  * A container wrapped with `disposable()`.
  *
- * Only `resolve` and `tryResolve` are available at the type level.
+ * 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.
  *
@@ -22,7 +22,7 @@ export interface DisposableContainer<T = Record<never, never>, Sync extends Abst
 /**
  * A scope wrapped with `disposable()`.
  *
- * Only `resolve` and `tryResolve` are available at the type level.
+ * 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
@@ -41,7 +41,7 @@ export interface DisposableScope<T = Record<never, never>, Sync extends Abstract
  * 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` and `tryResolve`,
+ * 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

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) {
@@ -106,8 +106,8 @@ class Container {
     return this.addRegistration(token, factory, "scoped");
   }
   use(source) {
-    for (const [token, registration] of source[INTERNALS].registrations) {
-      this.registrations.set(token, registration);
+    for (const [token, registrations] of source[INTERNALS].registrations) {
+      this.registrations.set(token, [...registrations]);
     }
     return this;
   }
@@ -117,21 +117,28 @@ class Container {
   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.`);
     }
@@ -142,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 { 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';

package/dist/index.js

@@ -14,22 +14,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) {
@@ -42,8 +42,8 @@ class Container {
     return this.addRegistration(token, factory, "scoped");
   }
   use(source) {
-    for (const [token, registration] of source[INTERNALS].registrations) {
-      this.registrations.set(token, registration);
+    for (const [token, registrations] of source[INTERNALS].registrations) {
+      this.registrations.set(token, [...registrations]);
     }
     return this;
   }
@@ -53,21 +53,28 @@ class Container {
   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.`);
     }
@@ -78,15 +85,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/internal.d.ts

@@ -14,12 +14,12 @@ export declare const INTERNALS: unique symbol;
  * @internal
  */
 export interface ContainerInternals {
-    /** All registrations (singleton / transient / scoped). */
-    readonly registrations: Map<unknown, Registration>;
-    /** Instance cache used during resolution (Container: singletons, Scope: singletonInstances). */
-    readonly instances: Map<unknown, unknown>;
-    /** Instances owned by this container / scope (disposal target). */
-    readonly ownInstances: Map<unknown, unknown>;
+    /** All registrations (singleton / transient / scoped). Each token maps to an array of registrations. */
+    readonly registrations: Map<unknown, Registration[]>;
+    /** Singleton cache keyed by Registration object (Container: singletons, Scope: shared with parent). */
+    readonly singletonCache: Map<Registration, unknown>;
+    /** Instances owned by this container / scope (disposal target), keyed by Registration object. */
+    readonly ownCache: Map<Registration, unknown>;
     /** Whether this container / scope has been disposed. */
     isDisposed(): boolean;
     /** Mark this container / scope as disposed. */

package/dist/lazy/index.cjs

@@ -0,0 +1,88 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+// src/lazy/index.ts
+var exports_lazy = {};
+__export(exports_lazy, {
+  lazy: () => lazy
+});
+module.exports = __toCommonJS(exports_lazy);
+function lazy(source, token) {
+  let instance;
+  let resolved = false;
+  const ensureResolved = () => {
+    if (!resolved) {
+      instance = source.resolve(token);
+      resolved = true;
+    }
+    return instance;
+  };
+  const proxyTarget = Object.create(null);
+  return new Proxy(proxyTarget, {
+    defineProperty(_, prop, desc) {
+      return Reflect.defineProperty(ensureResolved(), prop, desc);
+    },
+    deleteProperty(_, prop) {
+      return Reflect.deleteProperty(ensureResolved(), prop);
+    },
+    get(_, prop) {
+      const target = ensureResolved();
+      const value = Reflect.get(target, prop, target);
+      if (typeof value === "function") {
+        return value.bind(target);
+      }
+      return value;
+    },
+    getOwnPropertyDescriptor(_, prop) {
+      return Reflect.getOwnPropertyDescriptor(ensureResolved(), prop);
+    },
+    getPrototypeOf() {
+      return Reflect.getPrototypeOf(ensureResolved());
+    },
+    has(_, prop) {
+      return Reflect.has(ensureResolved(), prop);
+    },
+    isExtensible() {
+      return Reflect.isExtensible(ensureResolved());
+    },
+    ownKeys() {
+      return Reflect.ownKeys(ensureResolved());
+    },
+    preventExtensions() {
+      Reflect.preventExtensions(ensureResolved());
+      Reflect.preventExtensions(proxyTarget);
+      return true;
+    },
+    set(_, prop, value) {
+      return Reflect.set(ensureResolved(), prop, value, ensureResolved());
+    },
+    setPrototypeOf(_, proto) {
+      return Reflect.setPrototypeOf(ensureResolved(), proto);
+    }
+  });
+}

package/dist/lazy/index.d.ts

@@ -0,0 +1,35 @@
+import type { Container } from '../container';
+import type { DisposableContainer, DisposableScope } from '../disposable';
+import type { AbstractConstructor } from '../resolver';
+import type { Scope } from '../scope';
+/**
+ * Create a lazy proxy that defers resolution until the first property access.
+ *
+ * The returned object looks and behaves like `V`, but the underlying instance
+ * is not created until a property is read, written, or otherwise accessed.
+ * Once resolved the instance is cached — subsequent accesses hit the cache.
+ *
+ * Only **sync class tokens** are supported. Async tokens and PropertyKey tokens
+ * are rejected at the type level.
+ *
+ * @param source A Container, Scope, DisposableContainer, or DisposableScope
+ * @param token  A sync class constructor token
+ * @returns A proxy that transparently forwards to the lazily-resolved instance
+ *
+ * @example
+ * ```ts
+ * import { createContainer } from 'katagami';
+ * import { lazy } from 'katagami/lazy';
+ *
+ * const container = createContainer()
+ *   .registerSingleton(HeavyService, () => new HeavyService());
+ *
+ * const service = lazy(container, HeavyService);
+ * // Instance is NOT created yet
+ * service.doSomething(); // resolved here, then cached
+ * ```
+ */
+export declare function lazy<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, V>(source: Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>, token: AbstractConstructor<V> & Sync): V;
+export declare function lazy<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, V>(source: Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>, token: AbstractConstructor<V> & (Sync | ScopedSync)): V;
+export declare function lazy<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, V>(source: DisposableContainer<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>, token: AbstractConstructor<V> & Sync): V;
+export declare function lazy<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, V>(source: DisposableScope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>, token: AbstractConstructor<V> & (Sync | ScopedSync)): V;

package/dist/lazy/index.js

@@ -0,0 +1,58 @@
+// src/lazy/index.ts
+function lazy(source, token) {
+  let instance;
+  let resolved = false;
+  const ensureResolved = () => {
+    if (!resolved) {
+      instance = source.resolve(token);
+      resolved = true;
+    }
+    return instance;
+  };
+  const proxyTarget = Object.create(null);
+  return new Proxy(proxyTarget, {
+    defineProperty(_, prop, desc) {
+      return Reflect.defineProperty(ensureResolved(), prop, desc);
+    },
+    deleteProperty(_, prop) {
+      return Reflect.deleteProperty(ensureResolved(), prop);
+    },
+    get(_, prop) {
+      const target = ensureResolved();
+      const value = Reflect.get(target, prop, target);
+      if (typeof value === "function") {
+        return value.bind(target);
+      }
+      return value;
+    },
+    getOwnPropertyDescriptor(_, prop) {
+      return Reflect.getOwnPropertyDescriptor(ensureResolved(), prop);
+    },
+    getPrototypeOf() {
+      return Reflect.getPrototypeOf(ensureResolved());
+    },
+    has(_, prop) {
+      return Reflect.has(ensureResolved(), prop);
+    },
+    isExtensible() {
+      return Reflect.isExtensible(ensureResolved());
+    },
+    ownKeys() {
+      return Reflect.ownKeys(ensureResolved());
+    },
+    preventExtensions() {
+      Reflect.preventExtensions(ensureResolved());
+      Reflect.preventExtensions(proxyTarget);
+      return true;
+    },
+    set(_, prop, value) {
+      return Reflect.set(ensureResolved(), prop, value, ensureResolved());
+    },
+    setPrototypeOf(_, proto) {
+      return Reflect.setPrototypeOf(ensureResolved(), proto);
+    }
+  });
+}
+export {
+  lazy
+};

package/dist/resolver/index.d.ts

@@ -30,6 +30,31 @@ export interface Resolver<T, Sync extends AbstractConstructor = AbstractConstruc
     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 registrations for the token.
+     *
+     * @param token A registered token
+     * @returns An array of instances associated with the token
+     */
+    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;
 }
 /**
  * Lifetime of a registration.

package/dist/scope/index.cjs

@@ -76,29 +76,29 @@ function createScope(source) {
   if (internals.isDisposed()) {
     throw new ContainerError("Cannot create a scope from a disposed container.");
   }
-  return new Scope(internals.registrations, internals.instances);
+  return new Scope(internals.registrations, internals.singletonCache);
 }
 
 class Scope {
   registrations;
-  singletonInstances;
-  scopedInstances;
+  singletonCache;
+  scopedCache;
   resolvingTokens;
   disposed = false;
   [INTERNALS];
-  constructor(registrations, singletonInstances) {
+  constructor(registrations, singletonCache) {
     this.registrations = registrations;
-    this.singletonInstances = singletonInstances;
-    this.scopedInstances = new Map;
+    this.singletonCache = singletonCache;
+    this.scopedCache = new Map;
     this.resolvingTokens = new Set;
     this[INTERNALS] = {
-      instances: this.singletonInstances,
       isDisposed: () => this.disposed,
       markDisposed: () => {
         this.disposed = true;
       },
-      ownInstances: this.scopedInstances,
-      registrations: this.registrations
+      ownCache: this.scopedCache,
+      registrations: this.registrations,
+      singletonCache: this.singletonCache
     };
   }
   resolve(token) {
@@ -107,25 +107,32 @@ class Scope {
   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 scope.");
     }
-    const singletonCached = this.singletonInstances.get(token);
+    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 singletonCached = this.singletonCache.get(registration);
     if (singletonCached !== undefined) {
       return singletonCached;
     }
-    const scopedCached = this.scopedInstances.get(token);
+    const scopedCached = this.scopedCache.get(registration);
     if (scopedCached !== undefined) {
       return scopedCached;
     }
-    const registration = this.registrations.get(token);
-    if (registration === undefined) {
-      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)}`);
     }
@@ -133,13 +140,51 @@ class Scope {
     try {
       const instance = registration.factory(this);
       if (registration.lifetime === "singleton") {
-        this.singletonInstances.set(token, instance);
+        this.singletonCache.set(registration, instance);
       } else if (registration.lifetime === "scoped") {
-        this.scopedInstances.set(token, instance);
+        this.scopedCache.set(registration, instance);
       }
       return instance;
     } finally {
       this.resolvingTokens.delete(token);
     }
   }
+  resolveAllTokens(token, required) {
+    if (this.disposed) {
+      throw new ContainerError("Cannot resolve from a disposed scope.");
+    }
+    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 singletonCached = this.singletonCache.get(registration);
+        if (singletonCached !== undefined) {
+          return singletonCached;
+        }
+        const scopedCached = this.scopedCache.get(registration);
+        if (scopedCached !== undefined) {
+          return scopedCached;
+        }
+        const instance = reg.factory(this);
+        if (reg.lifetime === "singleton") {
+          this.singletonCache.set(registration, instance);
+        } else if (reg.lifetime === "scoped") {
+          this.scopedCache.set(registration, instance);
+        }
+        return instance;
+      });
+    } finally {
+      this.resolvingTokens.delete(token);
+    }
+  }
 }

package/dist/scope/index.d.ts

@@ -32,8 +32,8 @@ export declare function createScope<T, Sync extends AbstractConstructor, Async e
  */
 export declare class Scope<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 singletonInstances;
-    private readonly scopedInstances;
+    private readonly singletonCache;
+    private readonly scopedCache;
     private readonly resolvingTokens;
     private disposed;
     /**
@@ -42,7 +42,7 @@ export declare class Scope<T = Record<never, never>, Sync extends AbstractConstr
      * @internal
      */
     readonly [INTERNALS]: ContainerInternals;
-    constructor(registrations: Map<unknown, Registration>, singletonInstances: Map<unknown, unknown>);
+    constructor(registrations: Map<unknown, Registration[]>, singletonCache: Map<Registration, unknown>);
     /**
      * Resolve an instance for the given token.
      *
@@ -71,12 +71,49 @@ export declare class Scope<T = Record<never, never>, Sync extends AbstractConstr
     tryResolve<K extends keyof (T & ScopedT)>(token: K): (T & ScopedT)[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 | ScopedAsync)): Promise<V>[];
+    resolveAll<V>(token: AbstractConstructor<V> & (Sync | ScopedSync)): V[];
+    resolveAll<K extends keyof (T & ScopedT)>(token: K): (T & ScopedT)[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 scope) 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 | ScopedAsync)): Promise<V>[] | undefined;
+    tryResolveAll<V>(token: AbstractConstructor<V> & (Sync | ScopedSync)): V[] | undefined;
+    tryResolveAll<K extends keyof (T & ScopedT)>(token: K): (T & ScopedT)[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.
      * @returns The resolved instance, or undefined if not registered and required is false
      */
     private resolveToken;
+    /**
+     * 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;
 }

package/dist/scope/index.js

@@ -13,29 +13,29 @@ function createScope(source) {
   if (internals.isDisposed()) {
     throw new ContainerError("Cannot create a scope from a disposed container.");
   }
-  return new Scope(internals.registrations, internals.instances);
+  return new Scope(internals.registrations, internals.singletonCache);
 }
 
 class Scope {
   registrations;
-  singletonInstances;
-  scopedInstances;
+  singletonCache;
+  scopedCache;
   resolvingTokens;
   disposed = false;
   [INTERNALS];
-  constructor(registrations, singletonInstances) {
+  constructor(registrations, singletonCache) {
     this.registrations = registrations;
-    this.singletonInstances = singletonInstances;
-    this.scopedInstances = new Map;
+    this.singletonCache = singletonCache;
+    this.scopedCache = new Map;
     this.resolvingTokens = new Set;
     this[INTERNALS] = {
-      instances: this.singletonInstances,
       isDisposed: () => this.disposed,
       markDisposed: () => {
         this.disposed = true;
       },
-      ownInstances: this.scopedInstances,
-      registrations: this.registrations
+      ownCache: this.scopedCache,
+      registrations: this.registrations,
+      singletonCache: this.singletonCache
     };
   }
   resolve(token) {
@@ -44,25 +44,32 @@ class Scope {
   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 scope.");
     }
-    const singletonCached = this.singletonInstances.get(token);
+    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 singletonCached = this.singletonCache.get(registration);
     if (singletonCached !== undefined) {
       return singletonCached;
     }
-    const scopedCached = this.scopedInstances.get(token);
+    const scopedCached = this.scopedCache.get(registration);
     if (scopedCached !== undefined) {
       return scopedCached;
     }
-    const registration = this.registrations.get(token);
-    if (registration === undefined) {
-      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)}`);
     }
@@ -70,15 +77,53 @@ class Scope {
     try {
       const instance = registration.factory(this);
       if (registration.lifetime === "singleton") {
-        this.singletonInstances.set(token, instance);
+        this.singletonCache.set(registration, instance);
       } else if (registration.lifetime === "scoped") {
-        this.scopedInstances.set(token, instance);
+        this.scopedCache.set(registration, instance);
       }
       return instance;
     } finally {
       this.resolvingTokens.delete(token);
     }
   }
+  resolveAllTokens(token, required) {
+    if (this.disposed) {
+      throw new ContainerError("Cannot resolve from a disposed scope.");
+    }
+    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 singletonCached = this.singletonCache.get(registration);
+        if (singletonCached !== undefined) {
+          return singletonCached;
+        }
+        const scopedCached = this.scopedCache.get(registration);
+        if (scopedCached !== undefined) {
+          return scopedCached;
+        }
+        const instance = reg.factory(this);
+        if (reg.lifetime === "singleton") {
+          this.singletonCache.set(registration, instance);
+        } else if (reg.lifetime === "scoped") {
+          this.scopedCache.set(registration, instance);
+        }
+        return instance;
+      });
+    } finally {
+      this.resolvingTokens.delete(token);
+    }
+  }
 }
 export {
   createScope,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "katagami",
-	"version": "2.1.0",
+	"version": "2.2.0",
 	"description": "Lightweight DI container for TypeScript and JavaScript — full type inference, no decorators, no reflect-metadata, hybrid class & PropertyKey tokens.",
 	"license": "MIT",
 	"type": "module",
@@ -20,6 +20,11 @@
 			"types": "./dist/disposable/index.d.ts",
 			"import": "./dist/disposable/index.js",
 			"require": "./dist/disposable/index.cjs"
+		},
+		"./lazy": {
+			"types": "./dist/lazy/index.d.ts",
+			"import": "./dist/lazy/index.js",
+			"require": "./dist/lazy/index.cjs"
 		}
 	},
 	"main": "./dist/index.cjs",
@@ -45,14 +50,13 @@
 		"clean": "rm -rf dist",
 		"build": "bun run clean && bun run build:types && bun run build:esm && bun run build:cjs",
 		"build:types": "tsc -p tsconfig.build.json",
-		"build:esm": "bun build ./src/index.ts ./src/scope/index.ts ./src/disposable/index.ts --outdir dist --format esm --splitting",
-		"build:cjs": "bun build ./src/index.ts --outfile dist/index.cjs --format cjs && bun build ./src/scope/index.ts --outfile dist/scope/index.cjs --format cjs && bun build ./src/disposable/index.ts --outfile dist/disposable/index.cjs --format cjs",
-		"test": "bun test --coverage --dots",
+		"build:esm": "bun build ./src/index.ts ./src/scope/index.ts ./src/disposable/index.ts ./src/lazy/index.ts --outdir dist --format esm --splitting",
+		"build:cjs": "bun build ./src/index.ts --outfile dist/index.cjs --format cjs && bun build ./src/scope/index.ts --outfile dist/scope/index.cjs --format cjs && bun build ./src/disposable/index.ts --outfile dist/disposable/index.cjs --format cjs && bun build ./src/lazy/index.ts --outfile dist/lazy/index.cjs --format cjs",
 		"prepublishOnly": "bun run build",
 		"check": "bun run format",
 		"lint": "biome lint .",
 		"format": "biome check --write .",
-		"verify": "bun run build:types && bun run check && bun run test"
+		"verify": "bun run build:types && bun run check && bun test"
 	},
 	"dependencies": {
 		"@types/bun": "^1.3.8"