katagami 3.0.0 → 3.0.2

package/docs/guide.md

@@ -0,0 +1,186 @@
+# Katagami usage guide and API
+
+## Compatibility
+
+Katagami publishes ESM, CommonJS and TypeScript declarations, with no runtime dependencies.
+The CI consumer checks run on Node.js 22 and 24; runtime tests and examples also run with Bun.
+Type examples use TypeScript 5.9, `strict: true`, and the `ES2022` and `ESNext.Disposable` libraries.
+Browser APIs in examples, such as `crypto.randomUUID`, additionally need the `DOM` library.
+
+Core DI does not require decorator compiler flags, metadata emission or polyfills.
+The optional disposable entry point uses `Symbol.dispose` / `Symbol.asyncDispose`; the runtime
+must supply those symbols. `await using` requires a compiler/runtime that supports or transforms it.
+Katagami does not provide those polyfills. `lazy` uses JavaScript `Proxy`.
+
+## Lifetimes
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerSingleton('shared', () => ({ value: 0 }))
+  .registerTransient('fresh', () => ({ value: 0 }))
+  .registerScoped('request', () => ({ value: 0 }));
+
+const first = createScope(container);
+const second = createScope(container);
+first.resolve('shared') === second.resolve('shared'); // true
+first.resolve('request') === first.resolve('request'); // true
+first.resolve('request') === second.resolve('request'); // false
+first.resolve('fresh') === first.resolve('fresh'); // false
+```
+
+Factories run when first resolved; transient factories run on each resolution.
+Use `createScope(existingScope)` for another scope with its own scoped cache and shared singletons.
+Singleton and transient factories cannot directly resolve scoped registrations through their typed resolver.
+
+## Class tokens and async factories
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+class Database {
+  query() { return ['Ada']; }
+}
+class UserService {
+  constructor(private db: Database) {}
+  list() { return this.db.query(); }
+}
+
+const container = createContainer()
+  .registerSingleton(Database, async () => new Database())
+  .registerScoped(UserService, async r => new UserService(await r.resolve(Database)));
+
+const service = await createScope(container).resolve(UserService);
+service.list();
+```
+
+Class return types are inferred from constructors. Classes follow TypeScript's structural typing;
+see [token identity](./type-safety.md#class-tokens-use-structural-typing).
+Async factories produce Promise-typed resolutions. Await them explicitly.
+
+## Composition and test substitution
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const infrastructure = createContainer()
+  .registerSingleton('users', () => ({ find: (id: string) => `user-${id}` }));
+const fakeInfrastructure = createContainer()
+  .registerSingleton('users', () => ({ find: (id: string) => `fake-${id}` }));
+
+const testContainer = createContainer()
+  .use(infrastructure)
+  .use(fakeInfrastructure)
+  .registerScoped('handler', r => (id: string) => r.resolve('users').find(id));
+
+createScope(testContainer).resolve('handler')('1'); // fake-1
+```
+
+`use(source)` copies registration entries and replaces entries for matching tokens. It does not
+share the source's singleton cache. Containers are mutable: `register*` and `use` update the container
+and return it with accumulated types. Build the composition before creating or resolving scopes.
+Preserve each token's value type and lifetime when substituting registrations.
+
+## Optional and multiple resolution
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const scope = createScope(createContainer()
+  .registerSingleton('plugin', () => 'first')
+  .registerSingleton('plugin', () => 'second'));
+
+scope.resolve('plugin'); // 'second'
+scope.resolveAll('plugin'); // ['first', 'second']
+scope.tryResolve('optional'); // undefined
+scope.tryResolveAll('optional'); // undefined
+```
+
+Repeated `register*` calls accumulate factories for a token. `resolve` selects the last;
+`resolveAll` returns an array in registration order. For async factories, the array contains promises;
+use `Promise.all`. Keep one consistent value type and lifetime for a token.
+`tryResolve` and `tryResolveAll` accept missing tokens intentionally. They still report circular
+dependencies and operations on disposed scopes.
+
+## Resource cleanup
+
+```ts
+import { createContainer, createScope } from 'katagami';
+import { disposable } from 'katagami/disposable';
+
+const container = createContainer().registerScoped('connection', () => ({
+  query: () => 'ok',
+  [Symbol.dispose]() { console.log('connection closed'); },
+}));
+
+{
+  await using scope = disposable(createScope(container));
+  scope.resolve('connection').query();
+} // the scoped connection is disposed here
+```
+
+`disposable(containerOrScope)` returns a view with `[Symbol.asyncDispose]()` and hides registration
+methods. Disposable scopes retain resolution methods. `createScope` accepts either disposable view
+and retains its registered token types.
+
+Scope disposal cleans its cached scoped instances; container disposal cleans its singleton cache.
+Instances are processed in reverse cache insertion order, asynchronous results are awaited, and
+cleanup errors are combined in an `AggregateError`. Disposal is idempotent. Transient instances
+are not cached or automatically owned: arrange their cleanup explicitly.
+
+## Lazy resolution
+
+```ts
+import { createContainer, createScope } from 'katagami';
+import { lazy } from 'katagami/lazy';
+
+class Report { render() { return 'report'; } }
+const scope = createScope(createContainer().registerSingleton(Report, () => new Report()));
+const report = lazy(scope, Report);
+report.render(); // resolves on first access
+```
+
+`lazy` accepts synchronous class tokens on a scope or disposable scope. It does not accept async
+or PropertyKey tokens. Core imports do not include the lazy or disposable implementation; these
+are separate entry points with `sideEffects: false` for bundlers.
+
+## Predeclared service maps
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+interface Services {
+  greeting: string;
+  name: string;
+}
+const container = createContainer<Services>()
+  .registerSingleton('greeting', r => `Hello, ${r.resolve('name')}`)
+  .registerSingleton('name', () => 'Ada');
+
+createScope(container).resolve('greeting');
+```
+
+The first generic defines non-scoped PropertyKey tokens; the second defines scoped PropertyKey tokens.
+Maps permit forward references. They do not verify that each declared key has a registration.
+Default accumulated registration provides the registration-order checks described in the
+[type-safety guide](./type-safety.md).
+
+## API reference
+
+| API | Behavior |
+| --- | --- |
+| `createContainer<T, ScopedT>()` | Create a registration container; omit type maps to infer them by chaining |
+| `registerSingleton(token, factory)` | Register a shared, cached factory |
+| `registerTransient(token, factory)` | Register a factory called on every resolution |
+| `registerScoped(token, factory)` | Register a factory cached per scope |
+| `use(source)` | Copy another container's registrations, replacing matching token entries |
+| `createScope(source)` | Create a scope from a container, scope or disposable view |
+| `scope.resolve(token)` | Resolve the last registration; fail if missing |
+| `scope.resolveAll(token)` | Resolve every registration for a token |
+| `scope.tryResolve(token)` | Resolve the last registration or return `undefined` |
+| `scope.tryResolveAll(token)` | Resolve all registrations or return `undefined` |
+| `disposable(source)` from `katagami/disposable` | Add async cleanup and return a restricted view |
+| `lazy(scope, classToken)` from `katagami/lazy` | Defer synchronous resolution until first access |
+| `ContainerError` | Runtime error for missing registrations, cycles and invalid scope operations |
+| `Resolver` (type export) | Factory resolver type; retain inferred generics when extracting factories |

package/docs/type-safety.md

@@ -0,0 +1,126 @@
+# Type-safe dependency injection: what Katagami checks
+
+Katagami's default `createContainer()` accumulates types from registrations. With literal keys
+or unique symbols preserved, a resolver can only accept tokens accumulated into its visible
+registration set. No separate service interface is required. Run TypeScript with `strict: true`.
+
+## Accumulated registrations
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const DATABASE = Symbol('database');
+const OTHER_DATABASE = Symbol('database');
+const container = createContainer()
+  .registerSingleton(DATABASE, () => ({ query: () => 'ok' }))
+  .registerSingleton('greeting', () => 'hello');
+
+const scope = createScope(container);
+const greeting: string = scope.resolve('greeting');
+scope.resolve(DATABASE).query();
+// @ts-expect-error — this literal key has not been accumulated
+scope.resolve('missing');
+// @ts-expect-error — the same description does not make two symbols identical
+scope.resolve(OTHER_DATABASE);
+```
+
+Inside a factory, the visible set is the set accumulated **before that registration**.
+Singleton and transient factories receive the non-scoped set. Scoped factories receive both sets.
+Scopes can resolve both. `use()` includes the source module's registration types.
+`disposable()` and nested scopes retain the registration state, including asynchronous results.
+
+| Pattern | Compile-time behavior |
+| --- | --- |
+| Unregistered literal key / distinct unique symbol in accumulated mode | Rejected |
+| A structurally incompatible, unregistered class | Rejected |
+| Scoped literal token in a singleton or transient factory | Rejected |
+| Accessing a service method on an unresolved `Promise<Service>` | Rejected |
+| A key declared in `createContainer<Services>()`, but never registered | Accepted; runtime resolution can fail |
+| An unregistered class structurally compatible with a registered class | Can be accepted; runtime resolution can fail |
+| `tryResolve` of an unregistered token | Intentionally accepted; absence is a normal result |
+
+The checked examples and regression tests establish these specific behaviors. They do not prove
+arbitrary program correctness or an improvement in AI coding performance.
+
+## Class tokens use structural typing
+
+Accumulating a class type does not give TypeScript a nominal identity for each constructor.
+The following compiles in accumulated mode, but throws `ContainerError` if executed:
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+class Registered { value = 1; }
+class NotRegistered { value = 1; }
+
+const scope = createScope(createContainer()
+  .registerSingleton(Registered, () => new Registered()));
+
+scope.resolve(NotRegistered); // Same structure to TypeScript; different runtime Map key
+```
+
+This includes empty classes and can include subclasses. TypeScript checks compatibility;
+the runtime registry checks token identity. When that distinction matters, use unique symbols
+or literal keys, or distinguish class types with separate private member declarations:
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+class Registered {
+  declare private brand: undefined;
+  value = 1;
+}
+class NotRegistered {
+  declare private brand: undefined;
+  value = 1;
+}
+
+const scope = createScope(createContainer()
+  .registerSingleton(Registered, () => new Registered()));
+// @ts-expect-error — these separately declared private members make the types incompatible
+scope.resolve(NotRegistered);
+```
+
+See [TypeScript's type compatibility documentation](https://www.typescriptlang.org/docs/handbook/type-compatibility).
+
+## Predeclared interface maps
+
+`createContainer<Services>()` starts with the declared keys already visible. This enables
+order-independent registration, but that type map is a declaration of intent, not a proof
+that every key has a runtime factory:
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+interface Services { greeting: string; }
+const scope = createScope(createContainer<Services>());
+scope.resolve('greeting'); // Compiles, but throws if executed: no factory was registered
+```
+
+Prefer default accumulated registration when you want registration-order checks.
+Use a predeclared map when order independence is useful and verify the composition in runtime tests.
+
+## Preserve the information the checker needs
+
+- Keep literal tokens narrow. A token widened to `string`, or a broad index signature, loses the finite key set.
+- Keep the return value of each registration chain. Do not replace its inferred type with a broader annotation.
+- Keep a token's value type and lifetime consistent across registrations and `use()` replacements.
+  Katagami is mutable at runtime; arbitrary mutation through aliases is not proven safe by the accumulated type.
+- Use the factory's supplied resolver. Closures over another scope can bypass its lifetime restrictions.
+- Fix the dependency or lifetime; `any`, assertions and suppressions can bypass TypeScript checks.
+- `tryResolve` is for optional dependencies, not a workaround for required registration errors.
+
+## Runtime checks and limits
+
+Runtime checks report missing registrations, disposed scopes and circular resolution paths.
+The captive-dependency guard detects scoped resolution in an active singleton call chain,
+including indirect synchronous calls. It does not prove all lifetime relationships: in particular,
+do not rely on it for work resumed after an `await` or for dependencies captured from another scope.
+Use the typed factory API and runtime tests together.
+
+## Verification
+
+`bun run typecheck` runs the original type tests and the guarantee regressions in
+`src/container/guarantees/typetest.ts`. Negative checks use `@ts-expect-error`, so a previously
+rejected expression becoming accepted makes the check fail. These files are not runtime examples.
+`bun run docs:check` type-checks every TypeScript fence in the maintained Markdown documentation.

package/examples/request-scope/README.md

@@ -0,0 +1,37 @@
+# TypeScript request scopes without decorators
+
+A small starter for an HTTP handler, CLI, or worker: inject a user repository,
+create isolated state for each request, and dispose that state after success or failure.
+It uses Katagami's accumulated literal tokens; no token-to-type interface is needed.
+
+Copy `app.ts`, `demo.ts`, and `tsconfig.json` into a new directory, then run:
+
+```sh
+npm init -y
+npm pkg set type=module
+npm install katagami
+npm install --save-dev typescript
+npx tsc --noEmit
+npx tsc
+node build/demo.js
+```
+
+The demo prints a greeting for Ada and a guest greeting with different request IDs.
+The example is checked on Node.js 22 and 24 in CI and runs on Bun as well.
+It relies on `crypto.randomUUID`, `Symbol.dispose`, and `Symbol.asyncDispose` in the host.
+TypeScript compiles `await using`; Katagami does not install polyfills.
+
+From this repository, run `bun run build`, then `bun examples/request-scope/demo.ts`.
+`bun run test:examples` checks concurrency, fake injection and cleanup on rejection.
+`bun run test:package` also compiles and runs this starter against the packed npm artifact in Node.js.
+
+For an HTTP application, call the returned `greet` function inside the request handler.
+Create the application once, outside the handler. Each call creates and disposes its own scope.
+Pass authentication context explicitly into the application when adding authentication;
+this example does not provide an authentication or authorization system.
+
+Try changing `registerScoped('greeting', ...)` to `registerSingleton('greeting', ...)`.
+`npx tsc --noEmit` will reject `r.resolve('request')`. Restore the scoped registration:
+the greeting captures request state, so it must share that request's lifetime.
+
+See the [AI coding guide](../../docs/ai-coding-agents.md) and [type guarantees](../../docs/type-safety.md).

package/examples/request-scope/app.ts

@@ -0,0 +1,31 @@
+import { createContainer, createScope } from 'katagami';
+import { disposable } from 'katagami/disposable';
+
+export interface UserRepository {
+	findName(id: string): Promise<string | undefined>;
+}
+
+/** Inject infrastructure once; create a separate scope for each request. */
+export function createApp(repository: UserRepository, onCleanup: (id: string) => void = () => {}) {
+	const container = createContainer()
+		.registerSingleton('users', () => repository)
+		.registerScoped('request', () => ({
+			id: crypto.randomUUID(),
+			[Symbol.dispose]() {
+				onCleanup(this.id);
+			},
+		}))
+		.registerScoped('greeting', r => {
+			const users = r.resolve('users');
+			const request = r.resolve('request');
+			return async (userId: string) => ({
+				requestId: request.id,
+				message: `Hello, ${(await users.findName(userId)) ?? 'guest'}!`,
+			});
+		});
+
+	return async (userId: string) => {
+		await using scope = disposable(createScope(container));
+		return await scope.resolve('greeting')(userId);
+	};
+}

package/examples/request-scope/demo.ts

@@ -0,0 +1,10 @@
+import { createApp } from './app.js';
+
+const greet = createApp({
+	async findName(id) {
+		return new Map([['1', 'Ada']]).get(id);
+	},
+});
+
+console.log(await greet('1'));
+console.log(await greet('unknown'));

package/examples/request-scope/tsconfig.json

@@ -0,0 +1,11 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "NodeNext",
+		"moduleResolution": "NodeNext",
+		"lib": ["ES2022", "DOM", "ESNext.Disposable"],
+		"strict": true,
+		"outDir": "build"
+	},
+	"include": ["app.ts", "demo.ts"]
+}

package/llms.txt

@@ -0,0 +1,16 @@
+# Katagami
+
+> Type-safe dependency injection for TypeScript. Accumulated registration types, scope-aware factories and async tracking for AI-assisted development. No decorators or runtime dependencies.
+
+## Documentation
+
+- [Quick start](https://github.com/hiroiku/katagami/blob/master/README.md): installation and a checked example.
+- [AI coding agents](https://github.com/hiroiku/katagami/blob/master/docs/ai-coding-agents.md): workflow, diagnostics and project instructions.
+- [Type safety](https://github.com/hiroiku/katagami/blob/master/docs/type-safety.md): accumulated tokens, structural classes, declared maps and limits.
+- [API guide](https://github.com/hiroiku/katagami/blob/master/docs/guide.md): lifetimes, factories, modules, disposal and lazy resolution.
+- [Request-scope starter](https://github.com/hiroiku/katagami/tree/master/examples/request-scope): a runnable example with fake injection and cleanup.
+- [Choosing DI](https://github.com/hiroiku/katagami/blob/master/docs/choosing-di.md): use cases and trade-offs.
+
+## Optional
+
+- [Evaluation protocol](https://github.com/hiroiku/katagami/tree/master/benchmarks/agent-wiring): test agent outcomes before claiming performance benefits.

package/package.json

@@ -1,41 +1,64 @@
 {
 	"name": "katagami",
-	"version": "3.0.0",
-	"description": "Lightweight DI container for TypeScript and JavaScript — full type inference, no decorators, no reflect-metadata, hybrid class & PropertyKey tokens.",
+	"version": "3.0.2",
+	"description": "Type-safe dependency injection for TypeScript, with inferred types and scope checks for AI-assisted development. No decorators or reflect-metadata.",
 	"license": "MIT",
 	"type": "module",
 	"sideEffects": false,
 	"exports": {
 		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js",
-			"require": "./dist/index.cjs"
+			"import": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			},
+			"require": {
+				"types": "./dist/index.d.cts",
+				"default": "./dist/index.cjs"
+			}
 		},
 		"./disposable": {
-			"types": "./dist/disposable/index.d.ts",
-			"import": "./dist/disposable/index.js",
-			"require": "./dist/disposable/index.cjs"
+			"import": {
+				"types": "./dist/disposable/index.d.ts",
+				"default": "./dist/disposable/index.js"
+			},
+			"require": {
+				"types": "./dist/disposable/index.d.cts",
+				"default": "./dist/disposable/index.cjs"
+			}
 		},
 		"./lazy": {
-			"types": "./dist/lazy/index.d.ts",
-			"import": "./dist/lazy/index.js",
-			"require": "./dist/lazy/index.cjs"
+			"import": {
+				"types": "./dist/lazy/index.d.ts",
+				"default": "./dist/lazy/index.js"
+			},
+			"require": {
+				"types": "./dist/lazy/index.d.cts",
+				"default": "./dist/lazy/index.cjs"
+			}
 		}
 	},
 	"main": "./dist/index.cjs",
 	"module": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"files": [
-		"dist"
+		"dist",
+		"docs",
+		"examples/request-scope",
+		"llms.txt"
 	],
 	"keywords": [
 		"dependency-injection",
-		"di container",
+		"di-container",
 		"di",
-		"container",
 		"ioc",
 		"typescript",
-		"javascript"
+		"javascript",
+		"type-safe",
+		"type-inference",
+		"compile-time",
+		"ai-assisted-development",
+		"ai-coding",
+		"coding-agents"
 	],
 	"repository": {
 		"type": "git",
@@ -44,20 +67,30 @@
 	"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 ./src/disposable/index.ts ./src/lazy/index.ts --outdir dist --format esm --splitting",
-		"build:cjs": "bun build ./src/index.ts --outfile dist/index.cjs --format cjs && bun build ./src/disposable/index.ts --outfile dist/disposable/index.cjs --format cjs && bun build ./src/lazy/index.ts --outfile dist/lazy/index.cjs --format cjs",
+		"build:types": "tsc -p tsconfig.build.json && node scripts/build-cjs-types.mjs",
+		"build:esm": "node scripts/build.mjs esm",
+		"build:cjs": "node scripts/build.mjs cjs",
 		"prepublishOnly": "bun run build",
-		"check": "bun run format",
+		"check": "biome check .",
 		"lint": "biome lint .",
 		"format": "biome check --write .",
-		"verify": "bun run build:types && bun run check && bun test"
-	},
-	"dependencies": {
-		"@types/bun": "^1.3.8"
+		"verify": "bun run check && bun run typecheck && bun run build && bun run test && bun run test:examples && bun run test:package && bun run test:agent-fixtures && bun run docs:check",
+		"typecheck": "tsc -p tsconfig.typecheck.json && tsc -p tsconfig.examples.json",
+		"test": "bun test src",
+		"test:examples": "cd examples && bun test",
+		"test:package": "node scripts/check-package.mjs",
+		"docs:check": "node scripts/check-docs.mjs",
+		"metrics": "node scripts/collect-metrics.mjs",
+		"test:agent-fixtures": "node scripts/run-agent-task.mjs baseline manual && node scripts/run-agent-task.mjs baseline katagami"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.3.14",
+		"@types/bun": "^1.3.8",
+		"esbuild": "0.28.2",
 		"typescript": "^5.9.3"
+	},
+	"homepage": "https://github.com/hiroiku/katagami#readme",
+	"bugs": {
+		"url": "https://github.com/hiroiku/katagami/issues"
 	}
 }

package/dist/index-jx8b52m0.js

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