katagami 1.1.0

package/dist/index.cjs

@@ -0,0 +1,264 @@
+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/index.ts
+var exports_src = {};
+__export(exports_src, {
+  createContainer: () => createContainer,
+  Scope: () => Scope,
+  ContainerError: () => ContainerError,
+  Container: () => Container
+});
+module.exports = __toCommonJS(exports_src);
+
+// 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(" -> ");
+}
+
+// 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;
+}
+
+class Container {
+  registrations;
+  instances;
+  resolvingTokens;
+  disposed = false;
+  constructor() {
+    this.registrations = new Map;
+    this.instances = new Map;
+    this.resolvingTokens = new Set;
+  }
+  registerSingleton(token, factory) {
+    return this.addRegistration(token, factory, "singleton");
+  }
+  registerTransient(token, factory) {
+    return this.addRegistration(token, factory, "transient");
+  }
+  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);
+  }
+  tryResolve(token) {
+    return this.resolveToken(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) {
+      if (required) {
+        throw new ContainerError(`Token "${tokenToString(token)}" is not registered.`);
+      }
+      return;
+    }
+    if (registration.lifetime === "scoped") {
+      throw new ContainerError(`Cannot resolve scoped token "${tokenToString(token)}" from the root container. Use createScope() to create a scope first.`);
+    }
+    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.instances.set(token, instance);
+      }
+      return instance;
+    } finally {
+      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

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

package/dist/index.js

@@ -0,0 +1,232 @@
+// 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(" -> ");
+}
+
+// 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;
+}
+
+class Container {
+  registrations;
+  instances;
+  resolvingTokens;
+  disposed = false;
+  constructor() {
+    this.registrations = new Map;
+    this.instances = new Map;
+    this.resolvingTokens = new Set;
+  }
+  registerSingleton(token, factory) {
+    return this.addRegistration(token, factory, "singleton");
+  }
+  registerTransient(token, factory) {
+    return this.addRegistration(token, factory, "transient");
+  }
+  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);
+  }
+  tryResolve(token) {
+    return this.resolveToken(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) {
+      if (required) {
+        throw new ContainerError(`Token "${tokenToString(token)}" is not registered.`);
+      }
+      return;
+    }
+    if (registration.lifetime === "scoped") {
+      throw new ContainerError(`Cannot resolve scoped token "${tokenToString(token)}" from the root container. Use createScope() to create a scope first.`);
+    }
+    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.instances.set(token, instance);
+      }
+      return instance;
+    } finally {
+      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;
+  }
+}
+export {
+  createContainer,
+  Scope,
+  ContainerError,
+  Container
+};

package/dist/resolver/index.d.ts

@@ -0,0 +1,68 @@
+export type AbstractConstructor<T = unknown> = abstract new (...args: never[]) => T;
+/**
+ * Resolver passed to factory callbacks.
+ *
+ * @template T PropertyKey-based type map (defined via interface, order-independent)
+ * @template Sync Union of registered sync class constructors (order-dependent)
+ * @template Async Union of registered async class constructors (order-dependent)
+ */
+export interface Resolver<T, Sync extends AbstractConstructor = AbstractConstructor, Async extends AbstractConstructor = never> {
+    /**
+     * Resolve an instance for the given token.
+     *
+     * @param token A registered token
+     * @returns The instance associated with the token
+     */
+    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;
+}
+/**
+ * Lifetime of a registration.
+ */
+export type Lifetime = 'singleton' | 'transient' | 'scoped';
+/**
+ * Factory registration entry.
+ */
+export interface Registration {
+    /**
+     * Factory function.
+     *
+     * @param resolver Resolver
+     * @returns Instance
+     */
+    readonly factory: (resolver: Resolver<never, never>) => unknown;
+    /**
+     * Lifetime of the registration.
+     */
+    readonly lifetime: Lifetime;
+}
+/**
+ * Convert a token to a human-readable string.
+ */
+export declare function tokenToString(token: unknown): string;
+/**
+ * Build a human-readable circular dependency path from the resolving tokens.
+ *
+ * Uses the insertion order of Set to extract only the cycle portion.
+ * e.g. if resolvingTokens is [X, A, B, C] and token is A, returns "A -> B -> C -> A"
+ *
+ * @param resolvingTokens The set of tokens currently being resolved
+ * @param token The token that caused the circular dependency
+ * @returns Formatted cycle path string
+ */
+export declare function buildCircularPath(resolvingTokens: Set<unknown>, token: unknown): string;

package/dist/scope/index.d.ts

@@ -0,0 +1,81 @@
+import type { AbstractConstructor, Registration } from '../resolver';
+/**
+ * Scoped child container.
+ *
+ * Inherits all registrations from the parent container.
+ * Singleton instances are shared with the parent, while scoped instances are local to this scope.
+ * Transient instances are always newly created.
+ *
+ * @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 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> implements AsyncDisposable {
+    private readonly registrations;
+    private readonly singletonInstances;
+    private readonly scopedInstances;
+    private readonly resolvingTokens;
+    private disposed;
+    constructor(registrations: Map<unknown, Registration>, singletonInstances: Map<unknown, unknown>);
+    /**
+     * Resolve an instance for the given token.
+     *
+     * - Singleton: Returns the shared instance from the parent container (creates and caches on first access).
+     * - Scoped: Returns an instance local to this scope (creates and caches on first access within the scope).
+     * - Transient: 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 | ScopedAsync)): Promise<V>;
+    resolve<V>(token: AbstractConstructor<V> & (Sync | ScopedSync)): V;
+    resolve<K extends keyof (T & ScopedT)>(token: K): (T & ScopedT)[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 scope) 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 | ScopedAsync)): Promise<V> | undefined;
+    tryResolve<V>(token: AbstractConstructor<V> & (Sync | ScopedSync)): V | undefined;
+    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;
+    /**
+     * Internal resolution logic shared by resolve and tryResolve.
+     *
+     * @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;
+    /**
+     * Create a nested scope.
+     *
+     * The nested scope shares singleton instances with the parent but has its own scoped instance cache.
+     *
+     * @returns A new Scope instance
+     * @throws ContainerError if the scope has been disposed
+     */
+    createScope(): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+    /**
+     * Dispose all scoped instances managed by this scope.
+     *
+     * Iterates through scoped instances in reverse creation order (LIFO) and calls
+     * `[Symbol.asyncDispose]()` or `[Symbol.dispose]()` on each instance that implements them.
+     * Singleton instances are not disposed as they are owned by the parent container.
+     *
+     * 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>;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "katagami",
+	"version": "1.1.0",
+	"description": "Lightweight DI container for TypeScript and JavaScript — full type inference, no decorators, no reflect-metadata, hybrid class & PropertyKey tokens.",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist"
+	],
+	"keywords": [
+		"dependency-injection",
+		"di container",
+		"di",
+		"container",
+		"ioc",
+		"typescript",
+		"javascript"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/hiroiku/katagami.git"
+	},
+	"scripts": {
+		"clean": "rm -rf dist",
+		"build": "bun run clean && bun run build:types && bun run build:esm && bun run build:cjs",
+		"build:types": "tsc -p tsconfig.build.json",
+		"build:esm": "bun build ./src/index.ts --outdir dist --format esm",
+		"build:cjs": "bun build ./src/index.ts --outfile dist/index.cjs --format cjs",
+		"test": "bun test --coverage --dots",
+		"prepublishOnly": "bun run build",
+		"check": "bun run format",
+		"lint": "biome lint .",
+		"format": "biome check --write .",
+		"verify": "bun run build:types && bun run check && bun run test"
+	},
+	"dependencies": {
+		"@types/bun": "^1.3.8"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.14",
+		"typescript": "^5.9.3"
+	}
+}