katagami 3.0.0 → 3.0.1

package/docs/articles/ai-coding-agents.md

@@ -0,0 +1,70 @@
+# Type-safe dependency injection for AI coding agents
+
+AI-assisted development still needs a way to check the code it produces. For dependency wiring,
+a useful loop is small: edit the composition root, run TypeScript, read the diagnostics, and repair
+the missing dependency or incorrect lifetime. Katagami makes some of those wiring constraints visible
+to the compiler by accumulating types as dependencies are registered.
+
+## Let registration define the available dependencies
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerSingleton('users', () => ({ find: (id: string) => `user-${id}` }))
+  .registerScoped('handler', r => (id: string) => r.resolve('users').find(id));
+
+createScope(container).resolve('handler')('42');
+```
+
+There is no manually maintained service interface in this example. The first registration adds
+`users` to the type known by the next factory. The second adds `handler` to the scope's visible set.
+Changing `r.resolve('users')` to `r.resolve('user')` produces a type error. Removing the first
+registration also produces a type error at the consumer.
+
+The check is useful for both people and coding agents: the factory's actual dependency is written
+in the same code that TypeScript checks. The compiler can report a problem without starting the app.
+
+## Turn a diagnostic into a repair
+
+```ts
+import { createContainer } from 'katagami';
+
+createContainer()
+  .registerScoped('requestId', () => crypto.randomUUID())
+  // @ts-expect-error — a singleton factory cannot access this scoped dependency
+  .registerSingleton('handler', r => r.resolve('requestId'));
+```
+
+The diagnostic includes `No overload matches this call`. Inspect the failing resolution and its
+lifetime: the factory requests state belonging to one request while asking to be shared as a singleton.
+Register the handler as scoped, or pass the request ID into a shared service's method without storing it.
+
+`@ts-expect-error` is only present to test this intentionally invalid example. It is not the repair.
+In application code, change the wiring, run `npx tsc --noEmit`, then run behavior tests.
+
+## Make the workflow usable
+
+Give the agent the [v3 usage guide](../ai-coding-agents.md), the application's composition root and
+its verification command. Have it use the supplied factory resolver, preserve inferred registration
+types and run the checker after changes. A [runnable request-scope starter](../../examples/request-scope/README.md)
+shows fake injection, concurrent calls and cleanup on both success and failure.
+
+Ordinary constructor or function injection is still a useful baseline. It also gets TypeScript's
+parameter checks and can be enough for small applications. Introduce a container when construction,
+sharing, request scope or module composition is otherwise becoming repetitive.
+
+## State the guarantee accurately
+
+Accumulated literal keys and unique symbols let the checker reject tokens outside the visible
+registered set. A predeclared `createContainer<Services>()` map instead permits forward references
+and does not establish runtime registration completeness. Class tokens follow TypeScript's
+structural typing, so another compatible class may pass the checker while being a different runtime key.
+See [working examples of these boundaries](../type-safety.md).
+
+The compiler cases in this article are tested. We have not measured agent repair success or token
+savings. Those need [controlled repeated trials](https://github.com/hiroiku/katagami/tree/master/benchmarks/agent-wiring),
+including failures and the same tasks, model settings and runtime tests across variants.
+
+Install with `npm install katagami`, then start with the
+[quick start](../../README.md#quick-start) or the [request-scope example](../../examples/request-scope/README.md).

package/docs/articles/request-scope.md

@@ -0,0 +1,48 @@
+# Catch request-scope mistakes at compile time in TypeScript
+
+A service shared by all requests should not retain state from just one request. A DI container
+can make that mistake easier to express if every factory can resolve every dependency. Katagami's
+typed singleton and transient factories receive a resolver that excludes scoped registrations.
+
+## Reproduce the problem
+
+```ts
+import { createContainer } from 'katagami';
+
+createContainer()
+  .registerScoped('request', () => ({ id: crypto.randomUUID() }))
+  // @ts-expect-error — the request belongs to one scope, not a shared singleton
+  .registerSingleton('handler', r => ({ requestId: r.resolve('request').id }));
+```
+
+The checker rejects the resolution of `request`. The fix depends on what the handler should do.
+If it holds request state, give it a scoped lifetime:
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerScoped('request', () => ({ id: crypto.randomUUID() }))
+  .registerScoped('handler', r => ({ requestId: r.resolve('request').id }));
+
+const first = createScope(container);
+const second = createScope(container);
+first.resolve('handler').requestId !== second.resolve('handler').requestId; // true
+```
+
+If the service can be stateless and shared, take request data as a method parameter instead.
+Do not close over another request scope to get around the factory resolver.
+
+## Test what types cannot establish
+
+Type-check the wiring, then check that concurrent requests have distinct IDs, shared infrastructure
+stays shared, and resources are cleaned on rejection as well as success. The
+[request-scope starter](../../examples/request-scope/README.md) and its tests cover these cases.
+
+The compile-time example uses accumulated literal keys. A broad type annotation, predeclared map,
+compatible class token, assertion or captured external resolver can change what is checked.
+The runtime captive-dependency guard also has limits around work resumed after an `await`.
+The [type-safety guide](../type-safety.md) explains the exact scope of the guarantee.
+
+Katagami provides Singleton, Transient and Scoped lifetimes without decorator metadata.
+The [API guide](../guide.md) shows composition, async factories and optional disposal.

package/docs/articles/without-decorators.md

@@ -0,0 +1,54 @@
+# TypeScript dependency injection without decorators
+
+Dependency injection can be ordinary TypeScript: a factory receives a resolver and explicitly
+constructs a service. Katagami uses this model and has no runtime package dependencies, decorator
+compiler flags or reflect-metadata requirement.
+
+```sh
+npm install katagami
+```
+
+## Start with a factory
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+class Logger {
+  log(message: string) { console.log(message); }
+}
+class Greeting {
+  constructor(private logger: Logger) {}
+  say(name: string) { this.logger.log(`Hello, ${name}!`); }
+}
+
+const container = createContainer()
+  .registerSingleton(Logger, () => new Logger())
+  .registerTransient(Greeting, r => new Greeting(r.resolve(Logger)));
+
+createScope(container).resolve(Greeting).say('Ada');
+```
+
+The registration chain determines which class types the next factory can resolve. Class tokens
+are convenient when the classes are structurally distinguishable. Literal keys or unique symbols
+are also supported; see [token identity and type guarantees](../type-safety.md).
+
+## Substitute infrastructure in a test
+
+Factories can accept infrastructure as ordinary parameters. The
+[request-scope starter](../../examples/request-scope/README.md) takes a `UserRepository` argument.
+Its tests pass a small fake that returns a known name, then check the greeting. No global container
+or decorator setup is required.
+
+For larger compositions, group registrations in a container and copy them with `use()`.
+Apply the fake module before resolving anything. `use()` replaces matching registration entries;
+it is mutable composition, not automatic file loading or a snapshot API.
+
+## Choose only the lifecycle features you need
+
+Core imports come from `katagami`. Add cleanup from `katagami/disposable` or synchronous class-based
+lazy resolution from `katagami/lazy` when needed. Those entry points are separate so bundlers can
+omit unused implementations. Cleanup uses the host's disposal symbols; it does not provide a polyfill.
+
+For a small application, manual constructor parameters may remain the simplest choice.
+The [DI decision guide](../choosing-di.md) explains when accumulated registration types and request
+scopes are useful and links to other containers' own documentation.

package/docs/choosing-di.md

@@ -0,0 +1,30 @@
+# Choosing a TypeScript dependency injection approach
+
+Choose based on the application's wiring and lifecycle needs. There is no measured claim here
+that Katagami is faster, safer in every scenario, or more effective for every coding agent.
+
+| Approach | Consider it when | What to account for |
+| --- | --- | --- |
+| Ordinary constructor/function parameters | A small number of dependencies is easy to wire by hand | Your code owns construction, sharing and cleanup; TypeScript still checks parameter types |
+| Katagami | You want explicit factories, accumulated registration types and request scopes | Preserve narrow token types; understand structural class identity and predeclared-map limits |
+| Your framework's existing DI | The application already uses a framework container | Its conventions and lifecycle integrations may avoid maintaining a second container |
+| Awilix | Its registration, injection and loading conventions fit your app | Read its own TypeScript and strict-mode documentation for guarantees and configuration |
+| InversifyJS | Its class-oriented binding model and ecosystem fit your app | Follow its current setup instructions, including metadata requirements where applicable |
+
+Katagami's concrete distinction is that the default registration chain accumulates a resolver's
+visible token set. For literal keys or unique symbols, a missing token is rejected before execution.
+That is a useful check for both human-written and AI-generated wiring. It does not establish that
+other libraries lack type safety, and it does not eliminate runtime tests.
+
+Start with the [runnable starter](../examples/request-scope/README.md),
+[guarantee examples](./type-safety.md) and [composition guide](./guide.md#composition-and-test-substitution).
+
+Primary references, reviewed 2026-09-11:
+
+- [Awilix's maintained README](https://github.com/jeffijoe/awilix#readme), including TypeScript and strict mode.
+- [InversifyJS getting started](https://inversify.io/docs/introduction/getting-started/).
+- [TypeScript type compatibility](https://www.typescriptlang.org/docs/handbook/type-compatibility).
+
+The previous broad feature matrix was replaced with this decision guide. Replacing registrations
+with `use()` is explicit composition; Katagami does not implement automatic module discovery,
+immutable containers or a dedicated snapshot/restore API.

package/docs/growth/baseline-2026-09-11.json

@@ -0,0 +1,68 @@
+{
+	"collectedAt": "2026-09-11T10:53:46.834Z",
+	"package": "katagami",
+	"npm": {
+		"week": {
+			"downloads": 2,
+			"start": "2026-09-03",
+			"end": "2026-09-09",
+			"package": "katagami"
+		},
+		"month": {
+			"downloads": 109,
+			"start": "2026-08-11",
+			"end": "2026-09-09",
+			"package": "katagami"
+		},
+		"nonOverlappingWeeks": [
+			{
+				"start": "2026-07-16",
+				"end": "2026-07-22",
+				"downloads": 2
+			},
+			{
+				"start": "2026-07-23",
+				"end": "2026-07-29",
+				"downloads": 15
+			},
+			{
+				"start": "2026-07-30",
+				"end": "2026-08-05",
+				"downloads": 8
+			},
+			{
+				"start": "2026-08-06",
+				"end": "2026-08-12",
+				"downloads": 57
+			},
+			{
+				"start": "2026-08-13",
+				"end": "2026-08-19",
+				"downloads": 48
+			},
+			{
+				"start": "2026-08-20",
+				"end": "2026-08-26",
+				"downloads": 15
+			},
+			{
+				"start": "2026-08-27",
+				"end": "2026-09-02",
+				"downloads": 14
+			},
+			{
+				"start": "2026-09-03",
+				"end": "2026-09-09",
+				"downloads": 2
+			}
+		]
+	},
+	"github": {
+		"stars": 4,
+		"forks": 0,
+		"topics": [],
+		"homepage": null,
+		"pushedAt": "2026-02-09T11:30:14Z"
+	},
+	"errors": []
+}

package/docs/growth/github-metadata.json

@@ -0,0 +1,13 @@
+{
+	"description": "Type-safe dependency injection for TypeScript, with inferred types and scope checks for AI-assisted development. No decorators or reflect-metadata.",
+	"homepage": "https://github.com/hiroiku/katagami#readme",
+	"topics": [
+		"typescript",
+		"dependency-injection",
+		"di-container",
+		"type-safety",
+		"type-inference",
+		"ai-assisted-development",
+		"coding-agents"
+	]
+}

package/docs/growth/rollout.md

@@ -0,0 +1,77 @@
+# Katagami discovery and adoption rollout
+
+## Positioning and audience
+
+Type-safe dependency injection for TypeScript, with compiler feedback for AI-assisted development.
+The first audience is developers building a new TypeScript application with coding agents who need
+explicit dependency wiring, fake injection or request state. Avoid forcing a container into tiny apps.
+
+## Release assets
+
+- English and seven localized README entry points.
+- npm description/keywords and [GitHub metadata](./github-metadata.json).
+- [AI guide](../ai-coding-agents.md), [type guarantees](../type-safety.md), [API guide](../guide.md).
+- [Runnable starter](../../examples/request-scope/README.md) with checked examples.
+- [AI coding article](../articles/ai-coding-agents.md), [request scopes](../articles/request-scope.md),
+  [decorator-free DI](../articles/without-decorators.md) and a [Japanese Zenn draft](../articles/ai-coding-agents.ja.md).
+- [Evaluation protocol](../../benchmarks/agent-wiring/README.md) and results summarizer; agent benefits remain unmeasured.
+
+## First four weeks
+
+| Period | Action | Evidence to retain |
+| --- | --- | --- |
+| Week 1 | Ship checks, README, package metadata and starter; update GitHub Topics | Released version, CI run and public metrics snapshot |
+| Week 2 | Publish the worked-example article on the owner's chosen blog/Zenn account; adapt relative links to the published location | URL, date, channel and campaign label |
+| Weeks 3–4 | Observe 3–5 willing developers using the starter with their usual agent | Task attempted, first-run outcome, diagnostic confusion, whether they keep using it |
+| Weekly | Capture npm trends and, locally, owner-only repository traffic | Non-overlapping date ranges and unavailable data recorded as null |
+| After four weeks | Compare the funnel and fix the largest observed obstacle | Evidence for discovery, first successful use, continued use; no attribution from downloads alone |
+
+Publishing destinations and interview participants are selected by the owner. The article files
+are ready for adaptation, but an external publication or a participant interview must be recorded
+only after it actually happens. Do not post or message people without authorization for that destination.
+
+## Collect metrics
+
+```sh
+bun run metrics --output metrics.local/public.json
+bun run metrics --traffic --output metrics.local/owner-traffic.json
+```
+
+The second command requires authenticated owner access through `gh` and contains private traffic
+data. `metrics.local/` is ignored by Git. Do not commit those snapshots. Public release baselines can
+be recorded separately under this directory. Re-run weekly: GitHub traffic is a short rolling window.
+
+Track npm totals across four weeks using the non-overlapping weekly buckets, then compare with
+the preceding four weeks. Downloads are not unique users or installations and can include automation.
+Traffic, clones and external adoption reports provide different evidence; none alone is a conversion rate.
+Where the chosen publication platform supports it, use a per-channel campaign link to a page with
+analytics. GitHub alone does not provide complete visit-to-install attribution.
+
+## Interview script
+
+Ask a consenting participant to add a service and a fake to the starter using their normal agent.
+Observe rather than coach the first attempt. Record:
+
+1. What made the package seem relevant, and what almost stopped installation?
+2. Did the first run work? Which command or prerequisite was unclear?
+3. Could the agent fix a missing registration and an incorrect scope without suppressions?
+4. Were error messages actionable? Which documentation did the participant or agent actually read?
+5. Would the participant use it in a real project? Follow up on continued use with their consent.
+
+Record observations without names or private code unless the participant agrees. A suggested
+invitation, for an owner-approved channel:
+
+> TypeScriptのDIコンテナKatagamiの導入体験を改善しています。普段使っているAIエージェントで
+> 小さなサンプルにサービスとテスト用の依存を追加する、20分ほどの試用に協力いただける方を探しています。
+> うまく動かない点や分かりにくい点を知りたいです。公開コードだけで参加できます。
+
+## Search and claim hygiene
+
+Keep the description specific to dependency injection. Link guides from the README and use actual
+examples for queries about AI coding agents, request scopes and DI without decorators. `llms.txt`
+is a navigation aid, not a promised ranking boost.
+
+Sources: [npm discovery metadata](https://docs.npmjs.com/files/package.json/),
+[npm README publication](https://docs.npmjs.com/about-package-readme-files/),
+[GitHub Topics](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics),
+[Google AI search guidance](https://developers.google.com/search/docs/appearance/ai-features).

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 |