katagami 2.3.0 → 3.0.1

package/dist/internal.d.cts

@@ -0,0 +1,29 @@
+import type { Registration } from './resolver/index.cjs';
+/**
+ * Symbol used by extension modules (scope, disposable) to access container/scope internals.
+ *
+ * @internal
+ */
+export declare const INTERNALS: unique symbol;
+/** Type-only registration state retained by disposable views. No runtime property is emitted. */
+export declare const TYPE_STATE: unique symbol;
+/**
+ * Internal state exposed via the INTERNALS symbol.
+ *
+ * Both Container and Scope implement this interface so that extension modules
+ * (scope, disposable) can operate on either without importing the concrete class.
+ *
+ * @internal
+ */
+export interface ContainerInternals {
+    /** All registrations (singleton / transient / scoped). Each token maps to an array of registrations. */
+    readonly registrations: Map<unknown, Registration[]>;
+    /** Singleton cache keyed by Registration object (Container: singletons, Scope: shared with parent). */
+    readonly singletonCache: Map<Registration, unknown>;
+    /** Instances owned by this container / scope (disposal target), keyed by Registration object. */
+    readonly ownCache: Map<Registration, unknown>;
+    /** Whether this container / scope has been disposed. */
+    isDisposed(): boolean;
+    /** Mark this container / scope as disposed. */
+    markDisposed(): void;
+}

package/dist/internal.d.ts

@@ -1,10 +1,12 @@
-import type { Registration } from './resolver';
+import type { Registration } from './resolver/index.js';
 /**
  * Symbol used by extension modules (scope, disposable) to access container/scope internals.
  *
  * @internal
  */
 export declare const INTERNALS: unique symbol;
+/** Type-only registration state retained by disposable views. No runtime property is emitted. */
+export declare const TYPE_STATE: unique symbol;
 /**
  * Internal state exposed via the INTERNALS symbol.
  *

package/dist/lazy/index.cjs

@@ -1,37 +1,28 @@
+"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/lazy/index.ts
-var exports_lazy = {};
-__export(exports_lazy, {
+var lazy_exports = {};
+__export(lazy_exports, {
   lazy: () => lazy
 });
-module.exports = __toCommonJS(exports_lazy);
+module.exports = __toCommonJS(lazy_exports);
 function lazy(source, token) {
   let instance;
   let resolved = false;
@@ -42,7 +33,7 @@ function lazy(source, token) {
     }
     return instance;
   };
-  const proxyTarget = Object.create(null);
+  const proxyTarget = /* @__PURE__ */ Object.create(null);
   return new Proxy(proxyTarget, {
     defineProperty(_, prop, desc) {
       return Reflect.defineProperty(ensureResolved(), prop, desc);

package/dist/lazy/index.d.cts

@@ -0,0 +1,33 @@
+import type { DisposableScope } from '../disposable/index.cjs';
+import type { AbstractConstructor } from '../resolver/index.cjs';
+import type { Scope } from '../scope/index.cjs';
+/**
+ * Create a lazy proxy that defers resolution until the first property access.
+ *
+ * The returned object looks and behaves like `V`, but the underlying instance
+ * is not created until a property is read, written, or otherwise accessed.
+ * Once resolved the instance is cached — subsequent accesses hit the cache.
+ *
+ * Only **sync class tokens** are supported. Async tokens and PropertyKey tokens
+ * are rejected at the type level.
+ *
+ * @param source A Scope or DisposableScope
+ * @param token  A sync class constructor token
+ * @returns A proxy that transparently forwards to the lazily-resolved instance
+ *
+ * @example
+ * ```ts
+ * import { createContainer, createScope } from 'katagami';
+ * import { lazy } from 'katagami/lazy';
+ *
+ * const container = createContainer()
+ *   .registerSingleton(HeavyService, () => new HeavyService());
+ *
+ * const scope = createScope(container);
+ * const service = lazy(scope, HeavyService);
+ * // Instance is NOT created yet
+ * service.doSomething(); // resolved here, then cached
+ * ```
+ */
+export declare function lazy<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, V>(source: Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>, token: AbstractConstructor<V> & (Sync | ScopedSync)): V;
+export declare function lazy<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, V>(source: DisposableScope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>, token: AbstractConstructor<V> & (Sync | ScopedSync)): V;

package/dist/lazy/index.d.ts

@@ -1,7 +1,6 @@
-import type { Container } from '../container';
-import type { DisposableContainer, DisposableScope } from '../disposable';
-import type { AbstractConstructor } from '../resolver';
-import type { Scope } from '../scope';
+import type { DisposableScope } from '../disposable/index.js';
+import type { AbstractConstructor } from '../resolver/index.js';
+import type { Scope } from '../scope/index.js';
 /**
  * Create a lazy proxy that defers resolution until the first property access.
  *
@@ -12,24 +11,23 @@ import type { Scope } from '../scope';
  * Only **sync class tokens** are supported. Async tokens and PropertyKey tokens
  * are rejected at the type level.
  *
- * @param source A Container, Scope, DisposableContainer, or DisposableScope
+ * @param source A Scope or DisposableScope
  * @param token  A sync class constructor token
  * @returns A proxy that transparently forwards to the lazily-resolved instance
  *
  * @example
  * ```ts
- * import { createContainer } from 'katagami';
+ * import { createContainer, createScope } from 'katagami';
  * import { lazy } from 'katagami/lazy';
  *
  * const container = createContainer()
  *   .registerSingleton(HeavyService, () => new HeavyService());
  *
- * const service = lazy(container, HeavyService);
+ * const scope = createScope(container);
+ * const service = lazy(scope, HeavyService);
  * // Instance is NOT created yet
  * service.doSomething(); // resolved here, then cached
  * ```
  */
-export declare function lazy<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, V>(source: Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>, token: AbstractConstructor<V> & Sync): V;
 export declare function lazy<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, V>(source: Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>, token: AbstractConstructor<V> & (Sync | ScopedSync)): V;
-export declare function lazy<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, V>(source: DisposableContainer<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>, token: AbstractConstructor<V> & Sync): V;
 export declare function lazy<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, V>(source: DisposableScope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>, token: AbstractConstructor<V> & (Sync | ScopedSync)): V;

package/dist/lazy/index.js

@@ -9,7 +9,7 @@ function lazy(source, token) {
     }
     return instance;
   };
-  const proxyTarget = Object.create(null);
+  const proxyTarget = /* @__PURE__ */ Object.create(null);
   return new Proxy(proxyTarget, {
     defineProperty(_, prop, desc) {
       return Reflect.defineProperty(ensureResolved(), prop, desc);

package/dist/resolver/index.d.cts

@@ -0,0 +1,93 @@
+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;
+    /**
+     * Resolve all instances for the given token.
+     *
+     * Returns an array of instances from all registrations for the token.
+     *
+     * @param token A registered token
+     * @returns An array of instances associated with the token
+     */
+    resolveAll<V>(token: AbstractConstructor<V> & Async): Promise<V>[];
+    resolveAll<V>(token: AbstractConstructor<V> & Sync): V[];
+    resolveAll<K extends keyof T>(token: K): T[K][];
+    /**
+     * Try to resolve all instances for the given token.
+     *
+     * Returns `undefined` instead of throwing when the token is not registered.
+     * Other errors (circular dependency, disposed container) are still thrown.
+     *
+     * @param token A token to resolve
+     * @returns An array of instances associated with the token, or `undefined` if not registered
+     */
+    tryResolveAll<V>(token: AbstractConstructor<V> & Async): Promise<V>[] | undefined;
+    tryResolveAll<V>(token: AbstractConstructor<V> & Sync): V[] | undefined;
+    tryResolveAll<K extends keyof T>(token: K): T[K][] | undefined;
+    tryResolveAll<V>(token: AbstractConstructor<V>): (V | Promise<V>)[] | undefined;
+    tryResolveAll(token: PropertyKey): unknown;
+}
+/**
+ * Lifetime of a registration.
+ */
+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.cts

@@ -0,0 +1,120 @@
+import type { Container } from '../container/index.cjs';
+import type { DisposableContainer, DisposableScope } from '../disposable/index.cjs';
+import { type ContainerInternals, INTERNALS } from '../internal.cjs';
+import type { AbstractConstructor, Registration } from '../resolver/index.cjs';
+/**
+ * Create a new scope (child container) from a Container, Scope, or their disposable variants.
+ *
+ * The scope inherits all registrations from the source.
+ * Singleton instances are shared with the parent, while scoped instances are local to the scope.
+ *
+ * @param source A Container, Scope, DisposableContainer, or DisposableScope to create a child scope from
+ * @returns A new Scope instance
+ * @throws ContainerError if the source has been disposed
+ */
+export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(source: Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(source: Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(source: DisposableContainer<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(source: DisposableScope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+/**
+ * Scoped child container.
+ *
+ * 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> {
+    private readonly registrations;
+    private readonly singletonCache;
+    private readonly scopedCache;
+    private readonly resolvingTokens;
+    private singletonDepth;
+    private disposed;
+    /**
+     * Internal state accessor for extension modules (scope, disposable).
+     *
+     * @internal
+     */
+    readonly [INTERNALS]: ContainerInternals;
+    constructor(registrations: Map<unknown, Registration[]>, singletonCache: Map<Registration, 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;
+    /**
+     * Resolve all instances for the given token.
+     *
+     * Returns an array of instances from all registered factories for the token,
+     * in registration order.
+     *
+     * @param token A registered token
+     * @returns An array of instances associated with the token
+     * @throws ContainerError if the token is not registered
+     */
+    resolveAll<V>(token: AbstractConstructor<V> & (Async | ScopedAsync)): Promise<V>[];
+    resolveAll<V>(token: AbstractConstructor<V> & (Sync | ScopedSync)): V[];
+    resolveAll<K extends keyof (T & ScopedT)>(token: K): (T & ScopedT)[K][];
+    /**
+     * Try to resolve all instances for the given token.
+     *
+     * Returns `undefined` instead of throwing when the token is not registered.
+     * Other errors (circular dependency, disposed scope) are still thrown.
+     *
+     * @param token A token to resolve
+     * @returns An array of instances associated with the token, or `undefined` if not registered
+     */
+    tryResolveAll<V>(token: AbstractConstructor<V> & (Async | ScopedAsync)): Promise<V>[] | undefined;
+    tryResolveAll<V>(token: AbstractConstructor<V> & (Sync | ScopedSync)): V[] | undefined;
+    tryResolveAll<K extends keyof (T & ScopedT)>(token: K): (T & ScopedT)[K][] | undefined;
+    tryResolveAll<V>(token: AbstractConstructor<V>): (V | Promise<V>)[] | undefined;
+    tryResolveAll(token: PropertyKey): unknown;
+    /**
+     * Internal resolution logic shared by resolve and tryResolve.
+     * Resolves the last registered factory for the token.
+     *
+     * @param token Token to resolve
+     * @param required If true, throws when the token is not registered. If false, returns undefined.
+     * @returns The resolved instance, or undefined if not registered and required is false
+     */
+    private resolveToken;
+    /**
+     * Internal resolution logic shared by resolveAll and tryResolveAll.
+     * Resolves all registered factories for the token.
+     *
+     * @param token Token to resolve
+     * @param required If true, throws when the token is not registered. If false, returns undefined.
+     * @returns An array of resolved instances, or undefined if not registered and required is false
+     */
+    private resolveAllTokens;
+}

package/dist/scope/index.d.ts

@@ -1,7 +1,7 @@
-import type { Container } from '../container';
-import type { DisposableContainer, DisposableScope } from '../disposable';
-import { type ContainerInternals, INTERNALS } from '../internal';
-import type { AbstractConstructor, Registration } from '../resolver';
+import type { Container } from '../container/index.js';
+import type { DisposableContainer, DisposableScope } from '../disposable/index.js';
+import { type ContainerInternals, INTERNALS } from '../internal.js';
+import type { AbstractConstructor, Registration } from '../resolver/index.js';
 /**
  * Create a new scope (child container) from a Container, Scope, or their disposable variants.
  *

package/docs/README.de.md

@@ -0,0 +1,65 @@
+[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)
+
+# Katagami
+
+**Typsichere Dependency Injection für TypeScript.**
+
+Mache Abhängigkeiten explizit und prüfbar, auch wenn KI-Coding-Agenten den Code schreiben. Katagami sammelt Typen mit jeder Registrierung, prüft die in einer Factory verfügbaren Tokens und verfolgt asynchrone Rückgaben. Ohne Decorators, reflect-metadata oder Laufzeitabhängigkeiten.
+
+[![npm version](https://img.shields.io/npm/v/katagami)](https://www.npmjs.com/package/katagami)
+
+```sh
+npm install katagami
+```
+
+## Schnellstart
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerSingleton('name', () => 'Ada')
+  .registerScoped('greeting', r => `Hello, ${r.resolve('name')}!`);
+
+const greeting: string = createScope(container).resolve('greeting');
+console.log(greeting);
+```
+
+## Mit KI-Coding-Agenten arbeiten
+
+Der Agent ändert die Abhängigkeiten, führt den TypeScript-Checker aus und korrigiert den Code anhand der Diagnosen. Explizite Factories zeigen Abhängigkeiten als gewöhnlichen TypeScript-Code.
+
+Wenn eine Singleton-Factory auf Scoped-Zustand einer Anfrage zugreift, entsteht beispielsweise ein Typfehler.
+
+```ts
+import { createContainer } from 'katagami';
+
+createContainer()
+  .registerScoped('request', () => ({ id: crypto.randomUUID() }))
+  // @ts-expect-error — singleton factories cannot access scoped tokens
+  .registerSingleton('handler', r => r.resolve('request'));
+```
+
+Registriere handler in diesem Beispiel mit registerScoped. @ts-expect-error prüft das fehlerhafte Beispiel in CI. Korrigiere im Anwendungscode die Lebensdauer und führe npx tsc --noEmit aus, statt den Fehler zu unterdrücken.
+
+## Gesammelte Typen und Garantien
+
+createContainer() sammelt Typen aus Registrierungen. Solange Literalschlüssel und unique-symbol-Typen erhalten bleiben, werden Tokens außerhalb der sichtbaren Registrierungen abgelehnt. Eine manuelle Service-Typzuordnung ist nicht nötig.
+
+Klassentokens folgen struktureller Typisierung: Eine andere kompatible Klasse kann akzeptiert werden. Ein in createContainer<Services>() deklarierter Schlüssel ist ebenfalls im Typ sichtbar, auch ohne tatsächliche Registrierung.
+
+Unterstützt Singleton, Transient und Scoped, Modulkomposition mit use(), asynchrone Factories, optionale und mehrfache Auflösung, Ressourcenfreigabe und verzögerte Auflösung. Bei wenigen Abhängigkeiten reichen oft normale Parameter.
+
+## Anleitungen und ausführbares Beispiel
+
+- [Anleitung für KI-Agenten (Englisch)](./ai-coding-agents.md)
+- [Typgarantien (Englisch)](./type-safety.md)
+- [API und Anwendung (Englisch)](./guide.md)
+- [Starter für Anfrage-Scopes (Englisch)](../examples/request-scope/README.md)
+- [DI auswählen (Englisch)](./choosing-di.md)
+
+CI prüft Typbeispiele und Laufzeittests. Verbesserungen der Reparaturquote von Agenten oder Token-Einsparungen wurden noch nicht gemessen.
+
+Der Name stammt von 型紙, den Papierschablonen der traditionellen japanischen Färberei. Typen sammeln sich wie übereinandergelegte Schablonen.
+
+MIT

package/docs/README.es.md

@@ -0,0 +1,65 @@
+[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)
+
+# Katagami
+
+**Inyección de dependencias con seguridad de tipos para TypeScript.**
+
+Haz explícitas y verificables las dependencias, incluso cuando el código lo escriben agentes de IA. Katagami acumula tipos con cada registro, comprueba los tokens accesibles en cada fábrica y conserva los resultados asíncronos. Sin decoradores, reflect-metadata ni dependencias en tiempo de ejecución.
+
+[![npm version](https://img.shields.io/npm/v/katagami)](https://www.npmjs.com/package/katagami)
+
+```sh
+npm install katagami
+```
+
+## Inicio rápido
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerSingleton('name', () => 'Ada')
+  .registerScoped('greeting', r => `Hello, ${r.resolve('name')}!`);
+
+const greeting: string = createScope(container).resolve('greeting');
+console.log(greeting);
+```
+
+## Uso con agentes de programación de IA
+
+El agente modifica las dependencias, ejecuta el comprobador de TypeScript y corrige el código a partir de los diagnósticos. Las fábricas explícitas muestran las dependencias en código TypeScript normal.
+
+Por ejemplo, acceder a un estado Scoped desde una fábrica Singleton produce un error de tipos.
+
+```ts
+import { createContainer } from 'katagami';
+
+createContainer()
+  .registerScoped('request', () => ({ id: crypto.randomUUID() }))
+  // @ts-expect-error — singleton factories cannot access scoped tokens
+  .registerSingleton('handler', r => r.resolve('request'));
+```
+
+En este ejemplo, registra handler con registerScoped. @ts-expect-error verifica el ejemplo incorrecto en CI; en la aplicación, corrige el ciclo de vida y ejecuta npx tsc --noEmit sin suprimir el error.
+
+## Tipos acumulados y garantías
+
+createContainer() acumula los tipos de los registros. Si se conservan las claves literales y los tipos unique symbol, se rechazan los tokens fuera del conjunto visible de registros. No hace falta un mapa manual de servicios.
+
+Los tokens de clase siguen el tipado estructural: otra clase compatible puede ser aceptada. Una clave declarada en createContainer<Services>() también puede estar disponible en los tipos sin tener un registro real.
+
+Incluye ciclos de vida Singleton, Transient y Scoped, composición con use(), fábricas asíncronas, resolución opcional y múltiple, limpieza de recursos y resolución diferida. Para pocas dependencias, los parámetros normales pueden ser suficientes.
+
+## Guías y ejemplo ejecutable
+
+- [Guía para agentes de IA (inglés)](./ai-coding-agents.md)
+- [Garantías de tipos (inglés)](./type-safety.md)
+- [Guía de uso y API (inglés)](./guide.md)
+- [Ejemplo de ámbitos por petición (inglés)](../examples/request-scope/README.md)
+- [Cómo elegir DI (inglés)](./choosing-di.md)
+
+CI comprueba los ejemplos de tipos y las pruebas de ejecución. No se han medido mejoras en la tasa de reparación de agentes ni ahorro de tokens.
+
+El nombre viene de 型紙, las plantillas de papel de la tintura tradicional japonesa. Los tipos se acumulan como capas de plantillas.
+
+MIT

package/docs/README.fr.md

@@ -0,0 +1,65 @@
+[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)
+
+# Katagami
+
+**Injection de dépendances avec sûreté des types pour TypeScript.**
+
+Rendez les dépendances explicites et vérifiables, même quand des agents de programmation IA écrivent le code. Katagami accumule les types à chaque enregistrement, vérifie les jetons accessibles aux fabriques et suit les retours asynchrones. Sans décorateurs, reflect-metadata ni dépendances à l’exécution.
+
+[![npm version](https://img.shields.io/npm/v/katagami)](https://www.npmjs.com/package/katagami)
+
+```sh
+npm install katagami
+```
+
+## Démarrage rapide
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerSingleton('name', () => 'Ada')
+  .registerScoped('greeting', r => `Hello, ${r.resolve('name')}!`);
+
+const greeting: string = createScope(container).resolve('greeting');
+console.log(greeting);
+```
+
+## Travailler avec des agents de programmation IA
+
+L’agent modifie les dépendances, exécute le vérificateur TypeScript, puis corrige le code à partir des diagnostics. Les fabriques explicites rendent les dépendances visibles dans du code TypeScript ordinaire.
+
+Par exemple, accéder à un état Scoped depuis une fabrique Singleton produit une erreur de type.
+
+```ts
+import { createContainer } from 'katagami';
+
+createContainer()
+  .registerScoped('request', () => ({ id: crypto.randomUUID() }))
+  // @ts-expect-error — singleton factories cannot access scoped tokens
+  .registerSingleton('handler', r => r.resolve('request'));
+```
+
+Dans cet exemple, enregistrez handler avec registerScoped. @ts-expect-error sert à vérifier l’exemple incorrect en CI. Dans l’application, corrigez la durée de vie et lancez npx tsc --noEmit sans masquer l’erreur.
+
+## Types accumulés et garanties
+
+createContainer() accumule les types des enregistrements. En conservant les clés littérales et les types unique symbol, les jetons absents de l’ensemble visible sont rejetés. Aucune table manuelle des types de services n’est nécessaire.
+
+Les jetons de classe suivent le typage structurel : une autre classe compatible peut être acceptée. Une clé déclarée dans createContainer<Services>() peut aussi être visible dans les types sans enregistrement réel.
+
+Prend en charge Singleton, Transient et Scoped, la composition avec use(), les fabriques asynchrones, la résolution optionnelle et multiple, la libération des ressources et la résolution différée. Pour peu de dépendances, des paramètres ordinaires peuvent suffire.
+
+## Guides et exemple exécutable
+
+- [Guide pour agents IA (anglais)](./ai-coding-agents.md)
+- [Garanties de types (anglais)](./type-safety.md)
+- [Guide et API (anglais)](./guide.md)
+- [Exemple de portée par requête (anglais)](../examples/request-scope/README.md)
+- [Choisir une approche DI (anglais)](./choosing-di.md)
+
+Les exemples de types et les tests d’exécution sont vérifiés en CI. Les gains de réussite des agents ou de consommation de tokens n’ont pas encore été mesurés.
+
+Le nom vient de 型紙, les pochoirs de papier de la teinture traditionnelle japonaise. Les types s’accumulent comme des couches de pochoirs.
+
+MIT