katagami 1.1.0 → 2.1.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
 
@@ -8,22 +8,24 @@ Lightweight TypeScript DI container with full type inference.
 [![license](https://img.shields.io/npm/l/katagami)](https://github.com/hiroiku/katagami/blob/master/LICENSE)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/katagami)](https://bundlephobia.com/package/katagami)
 
-> The name comes from 型紙 _(katagami)_ — precision stencil paper used in traditional Japanese dyeing to transfer exact patterns onto fabric. Multiple stencils are layered to compose intricate designs, just as types accumulate through each method-chain call. A stencil needs only paper and a brush, no elaborate machinery — likewise, Katagami requires no decorators or metadata mechanisms and works with any build tool out of the box. And like stencils that work across different fabrics and techniques, Katagami adapts across TypeScript and JavaScript, class tokens and PropertyKey tokens — a hybrid approach to strict, composable DI.
+> The name comes from 型紙 _(katagami)_ — precision stencil paper used in traditional Japanese dyeing to transfer exact patterns onto fabric. Multiple stencils are layered to compose intricate designs, just as types accumulate through each method-chain call. Each stencil is a self-contained piece — chosen only for the current work, the rest left behind — just as subpath exports ensure only the code you use enters your bundle. The cut pattern determines exactly where dye passes and where it is blocked, much like Katagami's type system catches misuse at compile time, not at runtime. And a stencil needs only paper and a brush, no elaborate machinery — likewise, Katagami requires no decorators or metadata mechanisms and works with any build tool out of the box.
 
 ## Features
 
-| Feature                       | Description                                                                                  |
-| ----------------------------- | -------------------------------------------------------------------------------------------- |
-| Full type inference           | Types accumulate through method chaining; unregistered tokens are compile-time errors        |
-| Three lifetimes               | Singleton, Transient, and Scoped with child containers                                       |
-| Async factories               | Promise-returning factories are automatically tracked by the type system                     |
-| Circular dependency detection | Clear error messages with the full cycle path                                                |
-| Disposable support            | TC39 Explicit Resource Management (`Symbol.dispose` / `Symbol.asyncDispose` / `await using`) |
-| Captive dependency prevention | Singleton/Transient factories cannot access scoped tokens; caught at compile time            |
-| Optional resolution           | `tryResolve` returns `undefined` for unregistered tokens instead of throwing                 |
-| Hybrid token strategy         | Class tokens for strict type safety, PropertyKey tokens for flexibility                      |
-| Interface type map            | Pass an interface to `createContainer<T>()` for order-independent registration               |
-| Zero dependencies             | No decorators, no reflect-metadata, no polyfills                                             |
+| Feature                       | Description                                                                                                |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Zero dependencies             | No decorators, no reflect-metadata, no polyfills — works with any bundler out of the box                   |
+| Full type inference           | Types accumulate through method chaining; unregistered tokens are compile-time errors                      |
+| Tree-shakeable                | Subpath exports (`katagami/scope`, `katagami/disposable`) and `sideEffects: false` for minimal bundle size |
+| Captive dependency prevention | Singleton/Transient factories cannot access scoped tokens; caught at compile time                          |
+| Hybrid token strategy         | Class tokens for strict type safety, PropertyKey tokens for flexibility                                    |
+| Interface type map            | Pass an interface to `createContainer<T>()` for order-independent registration                             |
+| Three lifetimes               | Singleton, Transient, and Scoped with child containers                                                     |
+| Disposable support            | TC39 Explicit Resource Management (`Symbol.dispose` / `Symbol.asyncDispose` / `await using`)               |
+| Module composition            | Containers can be composed via `use()` to group and reuse registrations                                    |
+| Async factories               | Promise-returning factories are automatically tracked by the type system                                   |
+| Circular dependency detection | Clear error messages with the full cycle path                                                              |
+| Optional resolution           | `tryResolve` returns `undefined` for unregistered tokens instead of throwing                               |
 
 ## Install
 
@@ -66,6 +68,19 @@ Most TypeScript DI containers rely on decorators, reflect-metadata, or string-ba
 
 Decorator-based DI requires `experimentalDecorators` and `emitDecoratorMetadata` compiler options. Modern build tools such as esbuild and Vite (default configuration) do not support `emitDecoratorMetadata`, and the TC39 standard decorators proposal does not include an equivalent for automatic type metadata emission. Katagami depends on none of these — it works with any build tool out of the box.
 
+### Tree-shakeable
+
+Katagami is split into subpath exports. Import only what you use — `katagami/scope` and `katagami/disposable` 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
+import { createContainer } from 'katagami';
+
+// Import only what you need
+import { createScope } from 'katagami/scope';
+import { disposable } from 'katagami/disposable';
+```
+
 ### Full type inference from class tokens
 
 String-token DI forces you to maintain manual token-to-type mappings. Parameter-name matching breaks under minification. Katagami uses classes directly as tokens, so `resolve` automatically infers the correct return type — synchronous or `Promise` — with no extra annotations.
@@ -112,10 +127,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 +146,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 +160,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
@@ -154,6 +170,53 @@ parentScope.resolve(RequestContext) === childScope.resolve(RequestContext); // f
 parentScope.resolve(DbPool) === childScope.resolve(DbPool); // true
 ```
 
+### Module Composition
+
+Group related registrations into a reusable module by creating a container with `createContainer()`, then apply it to another container with `use()`. Only registration entries are copied — singleton instance caches are not shared.
+
+```ts
+import { createContainer } from 'katagami';
+
+class AuthService {
+	authenticate() {
+		return true;
+	}
+}
+
+class TokenService {
+	issue() {
+		return 'token';
+	}
+}
+
+class UserService {
+	constructor(private auth: AuthService, private tokens: TokenService) {}
+}
+
+// Define a reusable module
+const authModule = createContainer()
+	.registerSingleton(AuthService, () => new AuthService())
+	.registerSingleton(TokenService, () => new TokenService());
+
+// Compose modules
+const container = createContainer()
+	.use(authModule)
+	.registerSingleton(UserService, r => new UserService(r.resolve(AuthService), r.resolve(TokenService)));
+```
+
+Modules can also compose other modules:
+
+```ts
+const infraModule = createContainer().registerSingleton(AuthService, () => new AuthService());
+
+const appModule = createContainer()
+	.use(infraModule)
+	.registerSingleton(UserService, r => new UserService(r.resolve(AuthService), r.resolve(TokenService)));
+
+// appModule includes both AuthService and UserService
+const container = createContainer().use(appModule);
+```
+
 ### Async Factories
 
 Factories that return a `Promise` are automatically tracked by the type system. When you `resolve` an async token, the return type is `Promise<V>` instead of `V`:
@@ -229,10 +292,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 +305,7 @@ 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 +315,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
@@ -264,6 +331,28 @@ const root = createContainer()
 
 Scope disposal only affects scoped instances. Singleton instances are owned by the root container and are disposed when the container itself is disposed.
 
+The `disposable()` wrapper also narrows the returned type so that registration methods (`registerSingleton`, `registerTransient`, `registerScoped`, `use`) are removed at the type level. This prevents accidental registration on a potentially-disposed container:
+
+```ts
+const container = disposable(createContainer().registerSingleton(Connection, () => new Connection()));
+
+container.resolve(Connection); // OK
+container.registerSingleton(/* ... */); // Compile-time error
+```
+
+### 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.
+
+```ts
+// Core only — scope and disposable 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';
+```
+
 ### Interface Type Map
 
 When you pass an interface to `createContainer<T>()`, PropertyKey tokens are typed from the interface rather than accumulated through chaining. This means you can register and resolve tokens in any order:
@@ -393,43 +482,55 @@ const container = createContainer()
 
 Creates a new DI container. Pass an interface as `T` to define the type map for PropertyKey tokens. Pass `ScopedT` to define a separate type map for scoped PropertyKey tokens (order-independent, just like `T`).
 
-### `container.registerSingleton(token, factory)`
+### `Container.prototype.registerSingleton(token, factory)`
 
 Registers a factory as a singleton. The instance is created on the first `resolve` and cached thereafter. Returns the container for method chaining.
 
-### `container.registerTransient(token, factory)`
+### `Container.prototype.registerTransient(token, factory)`
 
 Registers a factory as transient. A new instance is created on every `resolve`. Returns the container for method chaining.
 
-### `container.registerScoped(token, factory)`
+### `Container.prototype.registerScoped(token, factory)`
 
 Registers a factory as scoped. Within a scope, the instance is created on the first `resolve` and cached for that scope. Each scope maintains its own cache. Scoped tokens cannot be resolved from the root container. Returns the container for method chaining.
 
-### `container.resolve(token)`
+### `Container.prototype.use(source)`
+
+Copies all registrations from `source` (another `Container`) into this container. Only factory and lifetime entries are copied — singleton instance caches are not shared. Returns the container for method chaining.
+
+### `Container.prototype.resolve(token)`
 
 Resolves and returns the instance for the given token. Throws `ContainerError` if the token is not registered or if a circular dependency is detected.
 
-### `container.tryResolve(token)` / `scope.tryResolve(token)`
+### `Container.prototype.tryResolve(token)`
 
 Attempts to resolve the instance for the given token. Returns `undefined` if the token is not registered, instead of throwing. Still throws `ContainerError` for circular dependencies or operations on disposed containers/scopes.
 
-### `container.createScope()`
+### `createScope(source)` — `katagami/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.
+
+### `class Scope`
+
+A scoped child container created by `createScope()`.
+
+### `Scope.prototype.resolve(token)`
 
-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.
+Resolves and returns the instance for the given token. Behaves the same as `Container.prototype.resolve`, but can also resolve scoped tokens.
 
-### `Scope`
+### `Scope.prototype.tryResolve(token)`
 
-A scoped child container created by `createScope()`. Provides `resolve(token)`, `tryResolve(token)`, `createScope()` (for nested scopes), and `[Symbol.asyncDispose]()`.
+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.
 
-### `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`. The returned type is narrowed to `DisposableContainer` or `DisposableScope`, which only expose `resolve` and `tryResolve` — registration methods are excluded at the type level.
 
-### `ContainerError`
+### `class ContainerError`
 
 Error class thrown for container failures such as resolving an unregistered token, circular dependencies, or operations on a disposed container/scope.
 
-### `Resolver`
+### `type Resolver`
 
 Type export representing the resolver passed to factory callbacks. Useful when you need to type a function that accepts a resolver parameter.
 

package/dist/container/index.d.ts

@@ -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.
@@ -78,15 +84,15 @@ export declare class Container<T = Record<never, never>, Sync extends AbstractCo
     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).
+     * Apply all registrations from another container (module) to this container.
      *
-     * The scope inherits all registrations from this container.
-     * Singleton instances are shared with the parent, while scoped instances are local to the scope.
+     * Copies only registration entries (factory + lifetime). Singleton instance caches
+     * are not shared — each container manages its own.
      *
-     * @returns A new Scope instance
-     * @throws ContainerError if the container has been disposed
+     * @param source A container whose registrations will be copied into this container
+     * @returns The container for method chaining
      */
-    createScope(): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+    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.
      *
@@ -122,18 +128,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,61 @@
+import type { Container } from '../container';
+import { type ContainerInternals, INTERNALS } from '../internal';
+import type { AbstractConstructor, Resolver } from '../resolver';
+import type { Scope } from '../scope';
+/**
+ * A container wrapped with `disposable()`.
+ *
+ * Only `resolve` and `tryResolve` are available at the type level.
+ * Registration methods (`registerSingleton`, `registerTransient`, `registerScoped`, `use`)
+ * are excluded, preventing accidental registration on a potentially-disposed container.
+ *
+ * @template T PropertyKey-based token type map
+ * @template Sync Union of registered sync class constructors
+ * @template Async Union of registered async class constructors
+ * @template ScopedT PropertyKey-based token type map for scoped registrations
+ * @template ScopedSync Union of scoped sync class constructors
+ * @template ScopedAsync Union of scoped async class constructors
+ */
+export interface DisposableContainer<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, _ScopedT = Record<never, never>, _ScopedSync extends AbstractConstructor = never, _ScopedAsync extends AbstractConstructor = never> extends Resolver<T, Sync, Async>, AsyncDisposable {
+    readonly [INTERNALS]: ContainerInternals;
+}
+/**
+ * A scope wrapped with `disposable()`.
+ *
+ * Only `resolve` and `tryResolve` are available at the type level.
+ *
+ * @template T PropertyKey-based token type map
+ * @template Sync Union of registered sync class constructors
+ * @template Async Union of registered async class constructors
+ * @template ScopedT PropertyKey-based token type map for scoped registrations
+ * @template ScopedSync Union of scoped sync class constructors
+ * @template ScopedAsync Union of scoped async class constructors
+ */
+export interface DisposableScope<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never> extends Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>, AsyncDisposable {
+    readonly [INTERNALS]: ContainerInternals;
+}
+/**
+ * Add async disposal capability to a container or scope.
+ *
+ * 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 is narrowed to only expose `resolve` and `tryResolve`,
+ * preventing registration methods from being called on a potentially-disposed container.
+ *
+ * @param container A Container or Scope to make disposable
+ * @returns The same object with `AsyncDisposable` capability added 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.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 };