katagami 1.1.0 → 2.0.0

package/README.md

@@ -1,4 +1,4 @@
-[English](./README.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md) | [繁體中文](./README.zh-TW.md) | [简体中文](./README.zh-CN.md) | [Español](./README.es.md) | [Deutsch](./README.de.md) | [Français](./README.fr.md)
+[English](./README.md) | [日本語](./docs/README.ja.md) | [한국어](./docs/README.ko.md) | [繁體中文](./docs/README.zh-TW.md) | [简体中文](./docs/README.zh-CN.md) | [Español](./docs/README.es.md) | [Deutsch](./docs/README.de.md) | [Français](./docs/README.fr.md)
 
 # Katagami
 
@@ -112,10 +112,11 @@ container.resolve(RequestHandler) === container.resolve(RequestHandler); // fals
 
 ### Scoped Lifetime & Child Containers
 
-Scoped registrations behave like singletons within a scope but produce a fresh instance in each new scope. Use `createScope()` to create a child container. Scoped tokens cannot be resolved from the root container.
+Scoped registrations behave like singletons within a scope but produce a fresh instance in each new scope. Import `createScope` from `katagami/scope` to create a child container. Scoped tokens cannot be resolved from the root container.
 
 ```ts
 import { createContainer } from 'katagami';
+import { createScope } from 'katagami/scope';
 
 class DbPool {
 	constructor(public name = 'main') {}
@@ -130,8 +131,8 @@ const root = createContainer()
 	.registerScoped(RequestContext, () => new RequestContext());
 
 // Create a scope for each request
-const scope1 = root.createScope();
-const scope2 = root.createScope();
+const scope1 = createScope(root);
+const scope2 = createScope(root);
 
 // Scoped — same within a scope, different across scopes
 scope1.resolve(RequestContext) === scope1.resolve(RequestContext); // true
@@ -144,8 +145,8 @@ scope1.resolve(DbPool) === scope2.resolve(DbPool); // true
 Scopes can also be nested. Each nested scope has its own scoped instance cache while sharing singletons with its parent:
 
 ```ts
-const parentScope = root.createScope();
-const childScope = parentScope.createScope();
+const parentScope = createScope(root);
+const childScope = createScope(parentScope);
 
 // Each nested scope gets its own scoped instances
 parentScope.resolve(RequestContext) === childScope.resolve(RequestContext); // false
@@ -229,10 +230,11 @@ ContainerError: Circular dependency detected: ServiceX -> ServiceY -> ServiceZ -
 
 ### Disposable Support
 
-Both `Container` and `Scope` implement `AsyncDisposable`. When disposed, managed instances are iterated in reverse creation order (LIFO) and their `[Symbol.asyncDispose]()` or `[Symbol.dispose]()` methods are called automatically.
+Disposal is provided by the `disposable()` wrapper from `katagami/disposable`. Wrapping a container or scope attaches `[Symbol.asyncDispose]`, enabling `await using` syntax. When disposed, owned instances are iterated in reverse creation order (LIFO) and their `[Symbol.asyncDispose]()` or `[Symbol.dispose]()` methods are called automatically.
 
 ```ts
 import { createContainer } from 'katagami';
+import { disposable } from 'katagami/disposable';
 
 class Connection {
 	async [Symbol.asyncDispose]() {
@@ -241,7 +243,9 @@ class Connection {
 }
 
 // Manual disposal
-const container = createContainer().registerSingleton(Connection, () => new Connection());
+const container = disposable(
+	createContainer().registerSingleton(Connection, () => new Connection()),
+);
 
 container.resolve(Connection);
 await container[Symbol.asyncDispose]();
@@ -251,12 +255,15 @@ await container[Symbol.asyncDispose]();
 With `await using`, scopes are automatically disposed at the end of the block:
 
 ```ts
+import { createScope } from 'katagami/scope';
+import { disposable } from 'katagami/disposable';
+
 const root = createContainer()
 	.registerSingleton(DbPool, () => new DbPool())
 	.registerScoped(Connection, () => new Connection());
 
 {
-	await using scope = root.createScope();
+	await using scope = disposable(createScope(root));
 	const conn = scope.resolve(Connection);
 	// ... use conn ...
 } // scope is disposed here — Connection is cleaned up, DbPool is not
@@ -413,17 +420,17 @@ Resolves and returns the instance for the given token. Throws `ContainerError` i
 
 Attempts to resolve the instance for the given token. Returns `undefined` if the token is not registered, instead of throwing. Still throws `ContainerError` for circular dependencies or operations on disposed containers/scopes.
 
-### `container.createScope()`
+### `createScope(source)` — `katagami/scope`
 
-Creates a new `Scope` (child container). The scope inherits all registrations from the parent. Singleton instances are shared with the parent, while scoped instances are local to the scope.
+Creates a new `Scope` (child container) from a `Container` or an existing `Scope`. The scope inherits all registrations from the source. Singleton instances are shared with the parent, while scoped instances are local to the scope.
 
 ### `Scope`
 
-A scoped child container created by `createScope()`. Provides `resolve(token)`, `tryResolve(token)`, `createScope()` (for nested scopes), and `[Symbol.asyncDispose]()`.
+A scoped child container created by `createScope()`. Provides `resolve(token)` and `tryResolve(token)`.
 
-### `container[Symbol.asyncDispose]()` / `scope[Symbol.asyncDispose]()`
+### `disposable(container)` — `katagami/disposable`
 
-Disposes all managed instances in reverse creation order (LIFO). Calls `[Symbol.asyncDispose]()` or `[Symbol.dispose]()` on each instance that implements them. Idempotent — subsequent calls are no-ops. After disposal, `resolve()` and `createScope()` will throw `ContainerError`.
+Attaches `[Symbol.asyncDispose]` to a `Container` or `Scope`, enabling `await using` syntax. Disposes all owned instances in reverse creation order (LIFO). Calls `[Symbol.asyncDispose]()` or `[Symbol.dispose]()` on each instance that implements them. Idempotent — subsequent calls are no-ops. After disposal, `resolve()` and `createScope()` will throw `ContainerError`.
 
 ### `ContainerError`
 

package/dist/container/index.d.ts

@@ -1,5 +1,5 @@
+import { type ContainerInternals, INTERNALS } from '../internal';
 import type { AbstractConstructor, Resolver } from '../resolver';
-import { Scope } from '../scope';
 /**
  * Create a new DI container.
  *
@@ -30,11 +30,17 @@ export declare function createContainer<T = Record<never, never>, ScopedT = Reco
  * @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> implements AsyncDisposable {
+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 resolvingTokens;
     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.
@@ -77,16 +83,6 @@ export declare class Container<T = Record<never, never>, Sync extends AbstractCo
     registerScoped<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V): Container<T, Sync, Async, ScopedT, ScopedSync | AbstractConstructor<V>, ScopedAsync>;
     registerScoped<K extends PropertyKey, V>(token: K, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V): Container<T, Sync, Async, Record<K, V> & ScopedT, ScopedSync, ScopedAsync>;
     registerScoped<V>(token: unknown, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
-    /**
-     * Create a new scope (child container).
-     *
-     * The scope inherits all registrations from this container.
-     * Singleton instances are shared with the parent, while scoped instances are local to the scope.
-     *
-     * @returns A new Scope instance
-     * @throws ContainerError if the container has been disposed
-     */
-    createScope(): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
     /**
      * Resolve an instance for the given token.
      *
@@ -122,18 +118,6 @@ export declare class Container<T = Record<never, never>, Sync extends AbstractCo
      * @returns The resolved instance, or undefined if not registered and required is false
      */
     private resolveToken;
-    /**
-     * Dispose all singleton instances managed by this container.
-     *
-     * Iterates through singleton instances in reverse creation order (LIFO) and calls
-     * `[Symbol.asyncDispose]()` or `[Symbol.dispose]()` on each instance that implements them.
-     *
-     * This method is idempotent — subsequent calls after the first are no-ops.
-     * After disposal, `resolve()` and `createScope()` will throw `ContainerError`.
-     *
-     * @throws AggregateError if one or more instances throw during disposal
-     */
-    [Symbol.asyncDispose](): Promise<void>;
     /**
      * Add a registration entry.
      *

package/dist/disposable/index.cjs

@@ -0,0 +1,76 @@
+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/disposable/index.ts
+var exports_disposable = {};
+__export(exports_disposable, {
+  disposable: () => disposable
+});
+module.exports = __toCommonJS(exports_disposable);
+
+// src/internal.ts
+var INTERNALS = Symbol("katagami.internals");
+
+// src/disposable/index.ts
+function disposable(container) {
+  const asyncDispose = async () => {
+    const internals = container[INTERNALS];
+    if (internals.isDisposed()) {
+      return;
+    }
+    internals.markDisposed();
+    const instances = [...internals.ownInstances.values()].reverse();
+    const errors = [];
+    for (const instance of instances) {
+      try {
+        let resolved = instance;
+        if (instance instanceof Promise) {
+          resolved = await instance;
+        }
+        if (resolved != null && typeof resolved === "object") {
+          if (Symbol.asyncDispose in resolved) {
+            await resolved[Symbol.asyncDispose]();
+          } else if (Symbol.dispose in resolved) {
+            resolved[Symbol.dispose]();
+          }
+        }
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    internals.ownInstances.clear();
+    if (errors.length > 0) {
+      throw new AggregateError(errors, "One or more errors occurred during disposal.");
+    }
+  };
+  Object.defineProperty(container, Symbol.asyncDispose, {
+    configurable: true,
+    value: asyncDispose
+  });
+  return container;
+}

package/dist/disposable/index.d.ts

@@ -0,0 +1,24 @@
+import { type ContainerInternals, INTERNALS } from '../internal';
+/**
+ * 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.
+ *
+ * @param container A Container or Scope to make disposable
+ * @returns The same object with `AsyncDisposable` capability added
+ *
+ * @example
+ * ```ts
+ * import { createContainer } from 'katagami';
+ * import { disposable } from 'katagami/disposable';
+ *
+ * await using container = disposable(
+ *   createContainer().registerSingleton(DB, () => new Database())
+ * );
+ * ```
+ */
+export declare function disposable<C extends {
+    readonly [INTERNALS]: ContainerInternals;
+}>(container: C): C & AsyncDisposable;

package/dist/disposable/index.js

@@ -0,0 +1,45 @@
+import {
+  INTERNALS
+} from "../index-jx8b52m0.js";
+
+// src/disposable/index.ts
+function disposable(container) {
+  const asyncDispose = async () => {
+    const internals = container[INTERNALS];
+    if (internals.isDisposed()) {
+      return;
+    }
+    internals.markDisposed();
+    const instances = [...internals.ownInstances.values()].reverse();
+    const errors = [];
+    for (const instance of instances) {
+      try {
+        let resolved = instance;
+        if (instance instanceof Promise) {
+          resolved = await instance;
+        }
+        if (resolved != null && typeof resolved === "object") {
+          if (Symbol.asyncDispose in resolved) {
+            await resolved[Symbol.asyncDispose]();
+          } else if (Symbol.dispose in resolved) {
+            resolved[Symbol.dispose]();
+          }
+        }
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    internals.ownInstances.clear();
+    if (errors.length > 0) {
+      throw new AggregateError(errors, "One or more errors occurred during disposal.");
+    }
+  };
+  Object.defineProperty(container, Symbol.asyncDispose, {
+    configurable: true,
+    value: asyncDispose
+  });
+  return container;
+}
+export {
+  disposable
+};

package/dist/index-g50fxds1.js

@@ -0,0 +1,34 @@
+// src/error/index.ts
+class ContainerError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ContainerError";
+  }
+}
+
+// src/resolver/index.ts
+function tokenToString(token) {
+  if (typeof token === "function") {
+    return token.name || "anonymous function";
+  }
+  if (typeof token === "symbol") {
+    return token.toString();
+  }
+  return String(token);
+}
+function buildCircularPath(resolvingTokens, token) {
+  const path = [];
+  let found = false;
+  for (const t of resolvingTokens) {
+    if (t === token) {
+      found = true;
+    }
+    if (found) {
+      path.push(tokenToString(t));
+    }
+  }
+  path.push(tokenToString(token));
+  return path.join(" -> ");
+}
+
+export { ContainerError, tokenToString, buildCircularPath };

package/dist/index-jx8b52m0.js

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

package/dist/index.cjs

@@ -30,7 +30,6 @@ var __export = (target, all) => {
 var exports_src = {};
 __export(exports_src, {
   createContainer: () => createContainer,
-  Scope: () => Scope,
   ContainerError: () => ContainerError,
   Container: () => Container
 });
@@ -44,6 +43,9 @@ class ContainerError extends Error {
   }
 }
 
+// src/internal.ts
+var INTERNALS = Symbol("katagami.internals");
+
 // src/resolver/index.ts
 function tokenToString(token) {
   if (typeof token === "function") {
@@ -69,97 +71,6 @@ function buildCircularPath(resolvingTokens, token) {
   return path.join(" -> ");
 }
 
-// src/scope/index.ts
-class Scope {
-  registrations;
-  singletonInstances;
-  scopedInstances;
-  resolvingTokens;
-  disposed = false;
-  constructor(registrations, singletonInstances) {
-    this.registrations = registrations;
-    this.singletonInstances = singletonInstances;
-    this.scopedInstances = new Map;
-    this.resolvingTokens = new Set;
-  }
-  resolve(token) {
-    return this.resolveToken(token, true);
-  }
-  tryResolve(token) {
-    return this.resolveToken(token, false);
-  }
-  resolveToken(token, required) {
-    if (this.disposed) {
-      throw new ContainerError("Cannot resolve from a disposed scope.");
-    }
-    const singletonCached = this.singletonInstances.get(token);
-    if (singletonCached !== undefined) {
-      return singletonCached;
-    }
-    const scopedCached = this.scopedInstances.get(token);
-    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)}`);
-    }
-    this.resolvingTokens.add(token);
-    try {
-      const instance = registration.factory(this);
-      if (registration.lifetime === "singleton") {
-        this.singletonInstances.set(token, instance);
-      } else if (registration.lifetime === "scoped") {
-        this.scopedInstances.set(token, instance);
-      }
-      return instance;
-    } finally {
-      this.resolvingTokens.delete(token);
-    }
-  }
-  createScope() {
-    if (this.disposed) {
-      throw new ContainerError("Cannot create a scope from a disposed scope.");
-    }
-    return new Scope(this.registrations, this.singletonInstances);
-  }
-  async[Symbol.asyncDispose]() {
-    if (this.disposed) {
-      return;
-    }
-    this.disposed = true;
-    const instances = [...this.scopedInstances.values()].reverse();
-    const errors = [];
-    for (const instance of instances) {
-      try {
-        let resolved = instance;
-        if (instance instanceof Promise) {
-          resolved = await instance;
-        }
-        if (resolved != null && typeof resolved === "object") {
-          if (Symbol.asyncDispose in resolved) {
-            await resolved[Symbol.asyncDispose]();
-          } else if (Symbol.dispose in resolved) {
-            resolved[Symbol.dispose]();
-          }
-        }
-      } catch (error) {
-        errors.push(error);
-      }
-    }
-    this.scopedInstances.clear();
-    if (errors.length > 0) {
-      throw new AggregateError(errors, "One or more errors occurred during disposal.");
-    }
-  }
-}
-
 // src/container/index.ts
 function createContainer() {
   return new Container;
@@ -170,10 +81,20 @@ class Container {
   instances;
   resolvingTokens;
   disposed = false;
+  [INTERNALS];
   constructor() {
     this.registrations = new Map;
     this.instances = new Map;
     this.resolvingTokens = new Set;
+    this[INTERNALS] = {
+      instances: this.instances,
+      isDisposed: () => this.disposed,
+      markDisposed: () => {
+        this.disposed = true;
+      },
+      ownInstances: this.instances,
+      registrations: this.registrations
+    };
   }
   registerSingleton(token, factory) {
     return this.addRegistration(token, factory, "singleton");
@@ -184,12 +105,6 @@ class Container {
   registerScoped(token, factory) {
     return this.addRegistration(token, factory, "scoped");
   }
-  createScope() {
-    if (this.disposed) {
-      throw new ContainerError("Cannot create a scope from a disposed container.");
-    }
-    return new Scope(this.registrations, this.instances);
-  }
   resolve(token) {
     return this.resolveToken(token, true);
   }
@@ -228,35 +143,6 @@ class Container {
       this.resolvingTokens.delete(token);
     }
   }
-  async[Symbol.asyncDispose]() {
-    if (this.disposed) {
-      return;
-    }
-    this.disposed = true;
-    const instances = [...this.instances.values()].reverse();
-    const errors = [];
-    for (const instance of instances) {
-      try {
-        let resolved = instance;
-        if (instance instanceof Promise) {
-          resolved = await instance;
-        }
-        if (resolved != null && typeof resolved === "object") {
-          if (Symbol.asyncDispose in resolved) {
-            await resolved[Symbol.asyncDispose]();
-          } else if (Symbol.dispose in resolved) {
-            resolved[Symbol.dispose]();
-          }
-        }
-      } catch (error) {
-        errors.push(error);
-      }
-    }
-    this.instances.clear();
-    if (errors.length > 0) {
-      throw new AggregateError(errors, "One or more errors occurred during disposal.");
-    }
-  }
   addRegistration(token, factory, lifetime) {
     this.registrations.set(token, { factory, lifetime });
     return this;

package/dist/index.d.ts

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