katagami 3.0.0 → 3.0.1

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.1",
+	"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 };