katagami 2.3.0 → 3.0.1

package/dist/chunk-J2NYR3SH.js

@@ -0,0 +1,6 @@
+// src/internal.ts
+var INTERNALS = /* @__PURE__ */ Symbol.for("katagami.internals.v3");
+
+export {
+  INTERNALS
+};

package/dist/container/index.d.cts

@@ -0,0 +1,108 @@
+import { type ContainerInternals, INTERNALS } from '../internal.cjs';
+import type { AbstractConstructor, Resolver } from '../resolver/index.cjs';
+/**
+ * Create a new DI container.
+ *
+ * Pass an interface as generic T to fix the PropertyKey token type map upfront (order-independent).
+ * Class tokens are accumulated via registerSingleton/registerTransient method chaining (order-dependent).
+ *
+ * @example
+ * ```ts
+ * interface Services { SampleController: string }
+ * const c = createContainer<Services>()
+ *   .registerSingleton(TextGenerationService, () => new MastraTextGenerationService())
+ *   .registerTransient(GenerateTextUseCase, r => new GenerateTextUseCase(r.resolve(TextGenerationService)));
+ * ```
+ */
+export declare function createContainer<T = Record<never, never>, ScopedT = Record<never, never>>(): Container<T, never, never, ScopedT>;
+/**
+ * Lightweight DI container — registration only.
+ *
+ * Provides type inference through method chaining with registerSingleton/registerTransient/registerScoped.
+ * Resolution is performed through a Scope created via `createScope(container)`.
+ *
+ * Registering the same token multiple times accumulates all factories.
+ *
+ * @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)
+ * @template ScopedT PropertyKey-based token type map for scoped registrations
+ * @template ScopedSync Union of scoped sync class constructors (accumulated via chaining, order-dependent)
+ * @template ScopedAsync Union of scoped async class constructors (accumulated via chaining, order-dependent)
+ */
+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 singletonCache;
+    private disposed;
+    /**
+     * Internal state accessor for extension modules (scope, disposable).
+     *
+     * @internal
+     */
+    readonly [INTERNALS]: ContainerInternals;
+    constructor();
+    /**
+     * 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
+     * @returns The container for method chaining
+     */
+    registerSingleton<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => Promise<V>): Container<T, Sync, Async | AbstractConstructor<V>, ScopedT, ScopedSync, ScopedAsync>;
+    registerSingleton<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<T, Sync | AbstractConstructor<V>, Async, ScopedT, ScopedSync, ScopedAsync>;
+    registerSingleton<K extends PropertyKey, V>(token: K, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<Record<K, V> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+    registerSingleton<V>(token: unknown, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+    /**
+     * 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
+     * @returns The container for method chaining
+     */
+    registerTransient<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => Promise<V>): Container<T, Sync, Async | AbstractConstructor<V>, ScopedT, ScopedSync, ScopedAsync>;
+    registerTransient<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<T, Sync | AbstractConstructor<V>, Async, ScopedT, ScopedSync, ScopedAsync>;
+    registerTransient<K extends PropertyKey, V>(token: K, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<Record<K, V> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+    registerTransient<V>(token: unknown, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+    /**
+     * Register a factory function as scoped for the given token.
+     *
+     * Within a scope, creates the instance on the first resolve and returns the cached value thereafter.
+     * Each scope maintains its own cache, so different scopes produce different instances.
+     * Scoped tokens cannot be resolved from the root container — use createScope() first.
+     *
+     * @param token Any value to use as a token
+     * @param factory Factory function that receives a resolver and returns an instance
+     * @returns The container for method chaining
+     */
+    registerScoped<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => Promise<V>): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync | AbstractConstructor<V>>;
+    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>;
+    /**
+     * Add a registration entry. Accumulates registrations for the same token.
+     *
+     * @param token Token
+     * @param factory Factory function
+     * @param lifetime Lifetime of the registration
+     * @returns The container for method chaining
+     */
+    private addRegistration;
+}

package/dist/container/index.d.ts

@@ -1,5 +1,5 @@
-import { type ContainerInternals, INTERNALS } from '../internal';
-import type { AbstractConstructor, Resolver } from '../resolver';
+import { type ContainerInternals, INTERNALS } from '../internal.js';
+import type { AbstractConstructor, Resolver } from '../resolver/index.js';
 /**
  * Create a new DI container.
  *
@@ -16,15 +16,12 @@ import type { AbstractConstructor, Resolver } from '../resolver';
  */
 export declare function createContainer<T = Record<never, never>, ScopedT = Record<never, never>>(): Container<T, never, never, ScopedT>;
 /**
- * Lightweight DI container.
+ * Lightweight DI container — registration only.
  *
- * Provides type inference through method chaining with registerSingleton/registerTransient/resolve.
- *
- * - 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.
+ * Provides type inference through method chaining with registerSingleton/registerTransient/registerScoped.
+ * Resolution is performed through a Scope created via `createScope(container)`.
  *
  * 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)
@@ -36,7 +33,6 @@ 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 singletonCache;
-    private readonly resolvingTokens;
     private disposed;
     /**
      * Internal state accessor for extension modules (scope, disposable).
@@ -100,79 +96,6 @@ export declare class Container<T = Record<never, never>, Sync extends AbstractCo
      * @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.
-     *
-     * @param token A registered token
-     * @returns The instance associated with the token
-     * @throws ContainerError if the token is not registered
-     */
-    resolve<V>(token: AbstractConstructor<V> & Async): Promise<V>;
-    resolve<V>(token: AbstractConstructor<V> & Sync): V;
-    resolve<K extends keyof T>(token: K): T[K];
-    /**
-     * Try to resolve an instance 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 The instance associated with the token, or `undefined` if not registered
-     */
-    tryResolve<V>(token: AbstractConstructor<V> & Async): Promise<V> | undefined;
-    tryResolve<V>(token: AbstractConstructor<V> & Sync): V | undefined;
-    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.
-     * @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;
     /**
      * Add a registration entry. Accumulates registrations for the same token.
      *

package/dist/disposable/index.cjs

@@ -1,40 +1,31 @@
+"use strict";
 var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
 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
-    });
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
 };
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/disposable/index.ts
-var exports_disposable = {};
-__export(exports_disposable, {
+var disposable_exports = {};
+__export(disposable_exports, {
   disposable: () => disposable
 });
-module.exports = __toCommonJS(exports_disposable);
+module.exports = __toCommonJS(disposable_exports);
 
 // src/internal.ts
-var INTERNALS = Symbol("katagami.internals");
+var INTERNALS = /* @__PURE__ */ Symbol.for("katagami.internals.v3");
 
 // src/disposable/index.ts
 function disposable(container) {

package/dist/disposable/index.d.cts

@@ -0,0 +1,69 @@
+import type { Container } from '../container/index.cjs';
+import { type ContainerInternals, INTERNALS, type TYPE_STATE } from '../internal.cjs';
+import type { AbstractConstructor, Resolver } from '../resolver/index.cjs';
+import type { Scope } from '../scope/index.cjs';
+/**
+ * A container wrapped with `disposable()`.
+ *
+ * Registration methods (`registerSingleton`, `registerTransient`, `registerScoped`, `use`)
+ * are excluded, preventing accidental registration on a potentially-disposed container.
+ * Use `createScope()` to create a scope for resolution.
+ *
+ * @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 AsyncDisposable {
+    readonly [INTERNALS]: ContainerInternals;
+    readonly [TYPE_STATE]?: {
+        readonly kind: 'container';
+        readonly registrations: readonly [T, Sync, Async, ScopedT, ScopedSync, ScopedAsync];
+    };
+}
+/**
+ * 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;
+    readonly [TYPE_STATE]?: {
+        readonly kind: 'scope';
+        readonly registrations: readonly [T, Sync, Async, ScopedT, ScopedSync, ScopedAsync];
+    };
+}
+/**
+ * Add async disposal capability to a container or scope.
+ *
+ * Enables `await using` syntax by attaching `[Symbol.asyncDispose]` to the target.
+ * Disposes owned instances in reverse creation order (LIFO), calling
+ * `[Symbol.asyncDispose]()` or `[Symbol.dispose]()` on each instance that implements them.
+ *
+ * The returned type prevents registration methods from being called on a potentially-disposed container.
+ * For scopes, `resolve`, `tryResolve`, `resolveAll`, and `tryResolveAll` remain available.
+ *
+ * @param container A Container or Scope to make disposable
+ * @returns The same object with `AsyncDisposable` capability added and registration methods removed from the type
+ *
+ * @example
+ * ```ts
+ * import { createContainer } from 'katagami';
+ * import { disposable } from 'katagami/disposable';
+ *
+ * await using container = disposable(
+ *   createContainer().registerSingleton(DB, () => new Database())
+ * );
+ * ```
+ */
+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.d.ts

@@ -1,13 +1,13 @@
-import type { Container } from '../container';
-import { type ContainerInternals, INTERNALS } from '../internal';
-import type { AbstractConstructor, Resolver } from '../resolver';
-import type { Scope } from '../scope';
+import type { Container } from '../container/index.js';
+import { type ContainerInternals, INTERNALS, type TYPE_STATE } from '../internal.js';
+import type { AbstractConstructor, Resolver } from '../resolver/index.js';
+import type { Scope } from '../scope/index.js';
 /**
  * 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.
+ * Use `createScope()` to create a scope for resolution.
  *
  * @template T PropertyKey-based token type map
  * @template Sync Union of registered sync class constructors
@@ -16,8 +16,12 @@ import type { Scope } from '../scope';
  * @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 {
+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 AsyncDisposable {
     readonly [INTERNALS]: ContainerInternals;
+    readonly [TYPE_STATE]?: {
+        readonly kind: 'container';
+        readonly registrations: readonly [T, Sync, Async, ScopedT, ScopedSync, ScopedAsync];
+    };
 }
 /**
  * A scope wrapped with `disposable()`.
@@ -33,6 +37,10 @@ export interface DisposableContainer<T = Record<never, never>, Sync extends Abst
  */
 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;
+    readonly [TYPE_STATE]?: {
+        readonly kind: 'scope';
+        readonly registrations: readonly [T, Sync, Async, ScopedT, ScopedSync, ScopedAsync];
+    };
 }
 /**
  * Add async disposal capability to a container or scope.
@@ -41,8 +49,8 @@ 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`, `tryResolve`, `resolveAll`, and `tryResolveAll`,
- * preventing registration methods from being called on a potentially-disposed container.
+ * The returned type prevents registration methods from being called on a potentially-disposed container.
+ * For scopes, `resolve`, `tryResolve`, `resolveAll`, and `tryResolveAll` remain available.
  *
  * @param container A Container or Scope to make disposable
  * @returns The same object with `AsyncDisposable` capability added and registration methods removed from the type

package/dist/disposable/index.js

@@ -1,6 +1,6 @@
 import {
   INTERNALS
-} from "../index-jx8b52m0.js";
+} from "../chunk-J2NYR3SH.js";
 
 // src/disposable/index.ts
 function disposable(container) {

package/dist/error/index.d.cts

@@ -0,0 +1,11 @@
+/**
+ * Error thrown by the DI container.
+ *
+ * Represents failures in container operations such as resolving an unregistered token.
+ */
+export declare class ContainerError extends Error {
+    /**
+     * @param message Error message
+     */
+    constructor(message: string);
+}