katagami 2.0.0 → 2.2.0

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) {
@@ -41,27 +41,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.`);
     }
@@ -72,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

@@ -1,18 +1,21 @@
 import type { Container } from '../container';
+import type { DisposableContainer, DisposableScope } from '../disposable';
 import { type ContainerInternals, INTERNALS } from '../internal';
 import type { AbstractConstructor, Registration } from '../resolver';
 /**
- * Create a new scope (child container) from a Container or an existing Scope.
+ * Create a new scope (child container) from a Container, Scope, or their disposable variants.
  *
  * The scope inherits all registrations from the source.
  * Singleton instances are shared with the parent, while scoped instances are local to the scope.
  *
- * @param source A Container or Scope to create a child scope from
+ * @param source A Container, Scope, DisposableContainer, or DisposableScope to create a child scope from
  * @returns A new Scope instance
  * @throws ContainerError if the source has been disposed
  */
 export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(source: Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
 export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(source: Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(source: DisposableContainer<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(source: DisposableScope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
 /**
  * Scoped child container.
  *
@@ -29,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;
     /**
@@ -39,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.
      *
@@ -68,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;
 }