inwire 1.0.2 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # inwire
 
-Zero-ceremony dependency injection for TypeScript. Full inference, no decorators, no tokens. Built-in introspection for AI tooling and debugging.
+Type-safe dependency injection for TypeScript. Builder pattern, full inference, no decorators, no tokens. Built-in introspection for AI tooling and debugging.
 
 [![NPM Version](https://img.shields.io/npm/v/inwire)](https://www.npmjs.com/package/inwire)
 [![CI](https://img.shields.io/github/actions/workflow/status/axelhamil/inwire/ci.yml)](https://github.com/axelhamil/inwire/actions)
@@ -13,27 +13,63 @@ Zero-ceremony dependency injection for TypeScript. Full inference, no decorators
 ## Install
 
 ```bash
-npm/pnpm i inwire
+npm i inwire
 ```
 
 ## Quick Start
 
 ```typescript
-import { createContainer } from 'inwire';
+import { container } from 'inwire';
 
-const container = createContainer({
-  logger: () => new LoggerService(),
-  db: () => new Database(process.env.DB_URL!),
-  userRepo: (c): UserRepository => new PgUserRepo(c.db),
-  userService: (c) => new UserService(c.userRepo, c.logger),
-});
+const app = container()
+  .add('logger', () => new LoggerService())
+  .add('db', (c) => new Database(c.logger))
+  .add('userService', (c) => new UserService(c.db, c.logger))
+  .build();
+
+app.userService; // lazy, singleton, fully typed
+// c.logger in the db factory is typed as LoggerService
+```
+
+Each `.add()` accumulates the type — `c` in every factory knows about all previously registered dependencies.
+
+## Contract Mode (Interface-First)
+
+Pass an interface to the builder to constrain keys and return types at compile time:
+
+```typescript
+interface AppDeps {
+  ILogger: Logger;
+  IDatabase: Database;
+  IUserService: UserService;
+}
 
-container.userService; // lazy, singleton, fully typed
+const app = container<AppDeps>()
+  .add('ILogger', () => new ConsoleLogger())         // key: autocomplete keyof AppDeps
+  .add('IDatabase', (c) => new PgDatabase(c.ILogger)) // return must be Database
+  .add('IUserService', (c) => new UserService(c.IDatabase, c.ILogger))
+  .build();
+
+app.ILogger; // typed as Logger (not ConsoleLogger)
 ```
 
-That's it. Every dependency is a factory function `(container) => instance`. Access a property, get a singleton. TypeScript infers everything.
+The string key acts as a token (like NestJS), but type-safe at compile time.
+
+## Instance Values (Eager)
 
-## ⚠️ Important: Async Lifecycle
+Non-function values are registered eagerly:
+
+```typescript
+const app = container()
+  .add('config', { port: 3000, host: 'localhost' })  // object, not factory — eager
+  .add('db', (c) => new Database(c.config))           // factory — lazy
+  .build();
+```
+
+Convention: `typeof value === 'function'` → factory (lazy). Otherwise → instance (eager, wrapped in `() => value`).
+To register a function as a value: `.add('fn', () => myFunction)`.
+
+## Async Lifecycle
 
 Property access on the container is **synchronous**. If your service implements `onInit()` with an async function, it will be called but **not awaited** — errors are silently swallowed and your service may be used before it's ready.
 
@@ -44,22 +80,20 @@ class Database implements OnInit {
   async onInit() { await this.connect(); }
 }
 
-const container = createContainer({
-  db: () => new Database(),
-});
+const app = container()
+  .add('db', () => new Database())
+  .build();
 
-// ❌ BAD — onInit() fires but is NOT awaited, errors are lost
-container.db;
+// BAD — onInit() fires but is NOT awaited, errors are lost
+app.db;
 
-// ✅ GOOD — onInit() is awaited, errors surface immediately
-await container.preload('db');
-container.db; // safe to use, fully initialized
+// GOOD — onInit() is awaited, errors surface immediately
+await app.preload('db');
+app.db; // safe to use, fully initialized
 ```
 
 ## Why use a DI container?
 
-Most JS/TS projects wire dependencies through direct imports. A DI container gives you three things imports don't:
-
 - **Testability** — swap any dependency for a mock at creation time, no monkey-patching or `jest.mock`
 - **Decoupling** — program against interfaces, not concrete imports; swap implementations without touching consumers
 - **Visibility** — inspect the full dependency graph at runtime, catch scope mismatches, and monitor container health
@@ -68,116 +102,74 @@ Most JS/TS projects wire dependencies through direct imports. A DI container giv
 
 ### Lazy Singletons (default)
 
-Factories run on first access and the result is cached forever. No eager init, no manual wiring.
-
 ```typescript
-const container = createContainer({
-  db: () => new Database(process.env.DB_URL!),
-});
+const app = container()
+  .add('db', () => new Database(process.env.DB_URL!))
+  .build();
 
-container.db; // creates Database
-container.db; // same instance (cached)
+app.db; // creates Database
+app.db; // same instance (cached)
 ```
 
-### Dependency Inversion
+### Transient
 
-Annotate the return type to program against an interface:
+Fresh instance on every access via `addTransient()`:
 
 ```typescript
-const container = createContainer({
-  userRepo: (c): UserRepository => new PgUserRepo(c.db),
-  //            ^^^^^^^^^^^^^^^^^
-  //            contract, not implementation
-});
-
-container.userRepo; // typed as UserRepository
-```
+import { container } from 'inwire';
 
-### Modules = Spread Objects
+const app = container()
+  .add('logger', () => new LoggerService())
+  .addTransient('requestId', () => crypto.randomUUID())
+  .build();
 
-Group related factories into plain objects and spread them:
-
-```typescript
-const dbModule = {
-  db: () => new Database(process.env.DB_URL!),
-  redis: () => new Redis(process.env.REDIS_URL!),
-};
-
-const serviceModule = {
-  userService: (c) => new UserService(c.db),
-};
-
-const container = createContainer({
-  ...dbModule,
-  ...serviceModule,
-});
+app.logger === app.logger;         // true  — singleton
+app.requestId === app.requestId;   // false — new every time
 ```
 
-### Test Overrides
-
-Replace any dependency with a mock at container creation:
+`transient()` wrapper is still available for `scope()`/`extend()`:
 
 ```typescript
-const container = createContainer({
-  ...productionDeps,
-  db: () => new InMemoryDatabase(), // override
+import { transient } from 'inwire';
+
+const extended = app.extend({
+  timestamp: transient(() => Date.now()),
 });
 ```
 
 ### Scopes
 
-Create child containers for request-level isolation. The child inherits all parent singletons and adds its own:
+Create child containers for request-level isolation:
 
 ```typescript
-const container = createContainer({
-  logger: () => new LoggerService(),
-  db: () => new Database(),
-});
+const app = container()
+  .add('logger', () => new LoggerService())
+  .add('db', () => new Database())
+  .build();
 
-// Per-request child container
-const request = container.scope({
+const request = app.scope({
   requestId: () => crypto.randomUUID(),
-  currentUser: () => getCurrentUser(),
+  handler: (c) => new Handler(c.logger),  // c typed as typeof app
 });
 
-request.requestId;   // scoped singleton (unique to this child)
-request.logger;      // inherited from parent
+request.requestId; // scoped singleton
+request.logger;    // inherited from parent
 ```
 
 #### Named Scopes
 
-Pass an options object to name a scope for debugging and introspection:
-
 ```typescript
-const request = container.scope(
+const request = app.scope(
   { requestId: () => crypto.randomUUID() },
   { name: 'request-123' },
 );
 
-String(request);       // "Scope(request-123) { requestId (pending) }"
+String(request);        // "Scope(request-123) { requestId (pending) }"
 request.inspect().name; // "request-123"
 ```
 
-### Transient
-
-By default every dependency is a **singleton** (created once, cached forever). When you need a **fresh instance on every access**, wrap the factory with `transient()`:
-
-```typescript
-import { createContainer, transient } from 'inwire';
-
-const container = createContainer({
-  logger: () => new LoggerService(),                  // singleton (default)
-  requestId: transient(() => crypto.randomUUID()),   // new value every time
-});
-
-container.logger === container.logger;       // true  — same instance
-container.requestId === container.requestId; // false — different every time
-```
-
 ### Lifecycle (onInit / onDestroy / dispose)
 
-Implement `onInit()` for post-creation setup and `onDestroy()` for cleanup:
-
 ```typescript
 import type { OnInit, OnDestroy } from 'inwire';
 
@@ -186,104 +178,108 @@ class Database implements OnInit, OnDestroy {
   async onDestroy() { await this.disconnect(); }
 }
 
-const container = createContainer({
-  db: () => new Database(),
-});
+const app = container()
+  .add('db', () => new Database())
+  .build();
 
-container.db;           // resolves + calls onInit()
-await container.dispose(); // calls onDestroy() on all resolved instances (LIFO order)
+app.db;               // resolves + calls onInit()
+await app.dispose();  // calls onDestroy() on all resolved instances (LIFO order)
 ```
 
-**Async `onInit()` is fire-and-forget during property access.** Because container property access is synchronous, any async `onInit()` runs without being awaited — errors won't surface and the service may not be ready. Use `preload()` to await async initialization. See [⚠️ Important: Async Lifecycle](#️-important-async-lifecycle) above.
-
 ### Extend
 
-Add dependencies to an existing container without mutating it. Existing singletons are shared:
+Add dependencies to an existing container without mutating it:
 
 ```typescript
-const base = createContainer({
-  logger: () => new LoggerService(),
-});
+const base = container()
+  .add('logger', () => new LoggerService())
+  .build();
 
 const extended = base.extend({
-  db: (c) => new Database(c.logger),
+  db: (c) => new Database(c.logger),  // c typed as typeof base
 });
 
 extended.logger; // shared singleton from base
 extended.db;     // new dependency
 ```
 
-> **scope vs extend:** `scope()` creates a parent-child chain — the child delegates unresolved keys to the parent. `extend()` creates a flat container with a merged factory map and shared cache. Use `scope()` for per-request isolation, `extend()` for additive composition.
+> **scope vs extend:** `scope()` creates a parent-child chain. `extend()` creates a flat container with merged factories and shared cache. Use `scope()` for per-request isolation, `extend()` for additive composition.
 
-### Preload
+### Modules
 
-Eagerly resolve specific dependencies at startup (warm-up):
+A module is a function `(builder) => builder` that chains `.add()` calls. `c` is fully typed in every factory.
 
-```typescript
-const container = createContainer({
-  db: () => new Database(),
-  cache: () => new Redis(),
-  logger: () => new LoggerService(),
-});
+#### Pre-build: `addModule()` on the builder
 
-await container.preload('db', 'cache');
-// db and cache are now resolved, logger is still lazy
+```typescript
+import { container, ContainerBuilder } from 'inwire';
+
+function dbModule<T extends { config: { dbUrl: string }; logger: Logger }>(
+  b: ContainerBuilder<Record<string, unknown>, T>,
+) {
+  return b
+    .add('db', (c) => new Database(c.config.dbUrl))
+    .add('cache', (c) => new Redis(c.config.dbUrl));
+}
 
-await container.preload();
-// resolve ALL dependencies at once
+const app = container()
+  .add('config', { dbUrl: 'postgres://...', port: 3000 })
+  .add('logger', () => new Logger())
+  .addModule(dbModule)
+  .build();
 ```
 
-**This is how you safely initialize async services.** See [⚠️ Important: Async Lifecycle](#️-important-async-lifecycle) above.
-
-### Reset
+#### Post-build: `module()` on the container
 
-Invalidate cached singletons to force re-creation on next access:
+Compose modules after `.build()` — same DX, applied to an existing container:
 
 ```typescript
-const container = createContainer({
-  db: () => new Database(),
-  cache: () => new Redis(),
-});
-
-container.db;  // creates Database
-container.reset('db');
-container.db;  // creates a NEW Database instance
+const core = container()
+  .add('config', { dbUrl: 'postgres://...' })
+  .add('logger', () => new Logger())
+  .build();
+
+const withDb = core.module((b) => b
+  .add('db', (c) => new Database(c.config.dbUrl))
+  .add('cache', (c) => new Redis(c.config.dbUrl))
+);
 
-// Other singletons are untouched
-// Reset in a scope does not affect the parent
+// Chainable
+const full = withDb.module((b) => b
+  .add('userService', (c) => new UserService(c.db, c.logger))
+);
 ```
 
-### Introspection
+`module()` uses the builder internally for typed `c`, then delegates to `extend()`. Works on `scope()` and `extend()` results too.
 
-Built-in tools for debugging and AI analysis:
+### Preload
 
 ```typescript
-// Full dependency graph
-container.inspect();
-// { providers: { db: { key: 'db', resolved: true, deps: [], scope: 'singleton' }, ... } }
-
-// Single provider details
-container.describe('userService');
-// { key: 'userService', resolved: true, deps: ['userRepo', 'logger'], scope: 'singleton' }
+await app.preload('db', 'cache'); // resolve specific deps
+await app.preload();              // resolve ALL
+```
 
-// Health check
-container.health();
-// { totalProviders: 4, resolved: ['db', 'logger'], unresolved: ['cache'], warnings: [] }
+### Reset
 
-// Human-readable string
-String(container);
-// "Container { db -> [] (resolved), logger (pending) }"
+```typescript
+app.db;           // creates Database
+app.reset('db');
+app.db;           // creates a NEW Database instance
 ```
 
-Feed the graph to an LLM or diagnostic tool:
+### Introspection
 
 ```typescript
-const graph = JSON.stringify(container.inspect(), null, 2);
+app.inspect();     // full dependency graph (JSON)
+app.describe('db'); // single provider info
+app.health();      // health status + warnings
+String(app);       // human-readable
+```
 
-const response = await anthropic.messages.create({
-  model: 'claude-sonnet-4-5-20250929',
-  messages: [{ role: 'user', content: `Analyze this dependency graph for issues:\n${graph}` }],
-});
+Feed the graph to an LLM:
+
+```typescript
+const graph = JSON.stringify(app.inspect(), null, 2);
 ```
 
 ### Smart Errors
@@ -291,66 +287,91 @@ const response = await anthropic.messages.create({
 7 error types, each with `hint`, `details`, and actionable suggestions:
 
 ```typescript
-// Non-function value
-createContainer({ apiKey: 'sk-123' });
-// ContainerConfigError: 'apiKey' must be a factory function, got string.
-// hint: "Wrap it: apiKey: () => 'sk-123'"
-
 // Reserved key
-createContainer({ inspect: () => 'foo' });
+container().add('inspect', () => 'foo');
 // ReservedKeyError: 'inspect' is a reserved container method.
-// hint: "Rename this dependency, e.g. 'inspectService' or 'myInspect'."
 
 // Missing dependency with fuzzy suggestion
-container.userServce; // typo
-// ProviderNotFoundError: Cannot resolve 'userServce': dependency 'userServce' not found.
-// hint: "Did you mean 'userService'?"
+app.userServce; // typo
+// ProviderNotFoundError: Did you mean 'userService'?
 
 // Circular dependency
-// CircularDependencyError: Circular dependency detected while resolving 'authService'.
-// Cycle: authService -> userService -> authService
-
-// Undefined return
-// UndefinedReturnError: Factory 'db' returned undefined.
-// hint: "Did you forget a return statement?"
-
-// Factory runtime error
-// FactoryError: Factory 'db' threw an error: "Connection refused"
+// CircularDependencyError: Cycle: authService -> userService -> authService
 ```
 
 ### Scope Mismatch Detection
 
-Warns when a singleton depends on a transient (the transient value gets frozen inside the singleton):
-
 ```typescript
-const container = createContainer({
-  requestId: transient(() => crypto.randomUUID()),
-  userService: (c) => new UserService(c.requestId), // singleton depends on transient!
-});
-
-container.health().warnings;
+app.health().warnings;
 // [{ type: 'scope_mismatch', message: "Singleton 'userService' depends on transient 'requestId'." }]
 ```
 
-### Fuzzy Key Suggestion
-
-When a key is not found, Levenshtein-based matching suggests the closest registered key (>= 50% similarity):
+### Duplicate Key Detection
 
 ```typescript
-container.userServce;
-// ProviderNotFoundError: Did you mean 'userService'?
+import { detectDuplicateKeys } from 'inwire';
+
+detectDuplicateKeys(authModule, userModule);
+// ['logger']
 ```
 
-### Duplicate Key Detection
+## Examples
 
-Detect accidental key collisions when spreading modules:
+| Example | Run | Showcases |
+|---|---|---|
+| [01-web-service.ts](examples/01-web-service.ts) | `npm run example:web` | Contract mode, lifecycle, dependency inversion, scope, introspection |
+| [02-modular-testing.ts](examples/02-modular-testing.ts) | `npm run example:test` | Free mode, instance values, test overrides, extend + transient |
+| [03-plugin-system.ts](examples/03-plugin-system.ts) | `npm run example:plugin` | Extend chain, scoped jobs, health, JSON graph for LLM |
+| [04-modules.ts](examples/04-modules.ts) | `npm run example:modules` | addModule, module() post-build, typed reusable modules |
 
-```typescript
-import { detectDuplicateKeys } from 'inwire';
+## Performance
 
-const duplicates = detectDuplicateKeys(authModule, userModule, dbModule);
-// ['logger'] — appears in more than one module
-```
+Performance is not the differentiator — **every lightweight DI container lands in the same ~20 ns range for cached singletons**. The differentiator is what you get on top of that.
+
+### Head-to-head (same scenario: 5-dep chain)
+
+| Library | warm singleton | http handler (3 deps) | build |
+|---|---|---|---|
+| **inwire** | **~22 ns** | **~71 ns** | ~1,840 ns |
+| ioctopus | ~20 ns | ~77 ns | ~530 ns |
+| awilix | ~25 ns | ~74 ns | ~5,820 ns |
+| inversify | ~580 ns | ~1,020 ns | ~10,280 ns |
+
+On the hot path, inwire, ioctopus, and awilix are within measurement noise. Inversify is the outlier at 25x slower — it pays for its planning tree on every resolve.
+
+Build is a cold path (runs once at startup). ioctopus is fastest because it stores raw entries with no validation. inwire sits in the middle — the Proxy setup, validation, and tracking cost ~1.5 μs extra, but that's 1.5 μs you pay once.
+
+**What ~22 ns means in practice:** DI overhead for a full HTTP handler (3 deps) is ~71 ns — faster than `JSON.parse` on a 40-byte string (~130 ns). It's not a factor.
+
+Run yourself: `npm run bench` / `npm run bench:compare` (Node.js v24, V8 13.6).
+
+### What you get for the same performance
+
+| | inwire | ioctopus | awilix | inversify |
+|---|---|---|---|---|
+| `c.db` — native autocomplete | Yes | No | No | No |
+| Full type inference (zero annotations) | Yes | No | No | No |
+| Auto dependency tracking | Yes | No | No | No |
+| Introspection (JSON graph) | Yes | No | No | No |
+| Fuzzy errors ("did you mean?") | Yes | No | No | No |
+| Scope mismatch warnings | Yes | No | No | No |
+| Lifecycle (onInit/onDestroy) | Yes | No | dispose only | No |
+| Decorators required | No | No | No | Yes |
+| Runtime deps | 0 | 0 | 1 | 7 |
+| Bundle (unpacked) | 8.8 KB | 43 KB | 320 KB | 1,466 KB |
+
+### Runtime compatibility
+
+Pure ES2022. No decorators, no `reflect-metadata`, no compiler plugins.
+
+| Runtime | Status |
+|---|---|
+| Node.js | Works |
+| Deno | Works |
+| Bun | Works |
+| Cloudflare Workers | Works |
+| Vercel Edge | Works |
+| Browser | Works |
 
 ## Comparison
 
@@ -358,14 +379,16 @@ const duplicates = detectDuplicateKeys(authModule, userModule, dbModule);
 |---|---|---|---|---|---|
 | Decorators required | No | No | Yes | Yes | Yes |
 | Tokens/symbols | No | No | Yes | Yes | Yes |
-| Full TS inference | Yes | No (manual Cradle) | Partial | Partial | Partial |
+| Full TS inference | Yes (builder) | No (manual Cradle) | Partial | Partial | Partial |
+| Typed `c` in factories | Yes | No | N/A | N/A | N/A |
 | Lazy singletons | Default | Default | Manual | Manual | Manual |
 | Scoped containers | `.scope()` | `.createScope()` | `.createChildContainer()` | `.createChild()` | Module scope |
 | Lifecycle hooks | `onInit`/`onDestroy` | `dispose()` | `beforeResolution`/`afterResolution` | No | `onModuleInit`/`onModuleDestroy` |
 | Introspection | Built-in JSON graph | `.registrations` | `isRegistered()` | No | DevTools |
 | Smart errors | 7 types + hints | Resolution chain | Generic | Generic | Generic |
-| Bundle size (gzip) | ~4.7 KB | ~3.6 KB | ~5.6 KB (+reflect-metadata) | ~50 KB | Framework |
-| Runtime deps | 0 | 1 | 1 (+reflect-metadata) | 2 | Many |
+| Warm singleton | ~22 ns | N/A | N/A | ~580 ns | N/A |
+| Bundle (unpacked) | 8.8 KB | 320 KB | 149 KB (+reflect-metadata) | 1,466 KB | Framework |
+| Runtime deps | 0 | 1 (fast-glob) | 1 (reflect-metadata) | 7 (+reflect-metadata) | Many |
 
 ## Architecture
 
@@ -378,11 +401,11 @@ src/
     lifecycle.ts                 # OnInit / OnDestroy interfaces
     validation.ts                # Validator, detectDuplicateKeys, Levenshtein
   infrastructure/
-    proxy-handler.ts             # Resolver (Proxy handler, cache, cycle detection)
+    resolver.ts                  # Resolver (Proxy handler, cache, cycle detection)
     transient.ts                 # transient() marker
   application/
-    create-container.ts          # createContainer, buildContainerProxy
-    scope.ts                     # createScope (child containers)
+    container-builder.ts         # ContainerBuilder class + container() function
+    container-proxy.ts           # buildContainerProxy + scope/extend inline
     introspection.ts             # inspect, describe, health, toString
 ```
 
@@ -393,58 +416,54 @@ This package ships with [llms.txt](https://llmstxt.org/) files for AI-assisted d
 - **`llms.txt`** — Concise index following the llms.txt standard
 - **`llms-full.txt`** — Complete API reference optimized for LLM context windows
 
-Use them to feed inwire documentation to any LLM or AI coding tool:
-
-```bash
-cat node_modules/inwire/llms-full.txt
-```
-
 Compatible with [Context7](https://context7.com/) and any tool that supports the llms.txt standard.
 
-At runtime, `.inspect()` returns the full dependency graph as serializable JSON — pipe it directly into an LLM for architecture analysis:
-
-```typescript
-const graph = JSON.stringify(container.inspect(), null, 2);
-```
-
 ## API Reference
 
 ### Functions
 
 | Export | Description |
 |---|---|
-| `createContainer(defs)` | Creates a DI container from factory functions |
-| `transient(factory)` | Marks a factory as transient (new instance per access) |
-| `detectDuplicateKeys(...modules)` | Detects duplicate keys across spread modules |
+| `container<T?>()` | Creates a new `ContainerBuilder`. Pass interface `T` for contract mode. |
+| `transient(factory)` | Marks a factory as transient (for scope/extend) |
+| `detectDuplicateKeys(...modules)` | Pre-spread validation — detects duplicate keys |
+
+### ContainerBuilder Methods
+
+| Method | Description |
+|---|---|
+| `.add(key, factory)` | Register a dependency (factory or instance) |
+| `.addTransient(key, factory)` | Register a transient dependency |
+| `.addModule(module)` | Apply a module `(builder) => builder` |
+| `.build()` | Build and return the container |
 
 ### Container Methods
 
 | Method | Description |
 |---|---|
-| `container.scope(extra, options?)` | Creates a child container with additional deps. Pass `{ name }` for debugging |
-| `container.extend(extra)` | Returns a new container with additional deps (shared cache) |
-| `container.preload(...keys)` | Eagerly resolves specific dependencies, or all if no keys given |
-| `container.reset(...keys)` | Invalidates cached singletons, forcing re-creation on next access |
-| `container.inspect()` | Returns the full dependency graph |
-| `container.describe(key)` | Returns info about a single provider |
-| `container.health()` | Returns health status and warnings |
-| `container.dispose()` | Calls `onDestroy()` on all resolved instances |
+| `.scope(extra, options?)` | Creates a child container with additional deps |
+| `.extend(extra)` | Returns a new container with additional deps (shared cache) |
+| `.module(fn)` | Applies a module post-build using the builder for typed `c` |
+| `.preload(...keys)` | Eagerly resolves dependencies |
+| `.reset(...keys)` | Invalidates cached singletons |
+| `.inspect()` | Returns the full dependency graph |
+| `.describe(key)` | Returns info about a single provider |
+| `.health()` | Returns health status and warnings |
+| `.dispose()` | Calls `onDestroy()` on all resolved instances |
 
 ### Types
 
 | Export | Description |
 |---|---|
 | `Container<T>` | Full container type (resolved deps + methods) |
-| `DepsDefinition` | `Record<string, Factory>` |
-| `Factory<T>` | `(container) => T` |
-| `ResolvedDeps<T>` | Extracts return types from a `DepsDefinition` |
+| `ContainerBuilder<TContract, TBuilt>` | Fluent builder class (also used in `module()` callbacks) |
+| `IContainer<T>` | Container methods interface |
 | `OnInit` | Interface with `onInit(): void \| Promise<void>` |
 | `OnDestroy` | Interface with `onDestroy(): void \| Promise<void>` |
 | `ContainerGraph` | Return type of `inspect()` |
 | `ContainerHealth` | Return type of `health()` |
-| `ContainerWarning` | Warning object (`scope_mismatch` \| `duplicate_key`) |
+| `ContainerWarning` | Warning object (`scope_mismatch`) |
 | `ProviderInfo` | Return type of `describe()` |
-| `IContainer<T>` | Container methods interface |
 | `ScopeOptions` | Options for `scope()` (`{ name?: string }`) |
 
 ### Errors

package/dist/index.d.mts

@@ -7,32 +7,11 @@
  * const factory: Factory<MyService> = (c) => new MyService(c.db);
  * ```
  */
-type Factory<T = any> = (container: any) => T;
+type Factory<T = unknown> = (container: unknown) => T;
 /**
- * An object of factory functions — the definition of a container.
- * Each key maps to a factory that produces the dependency.
- *
- * @example
- * ```typescript
- * const deps: DepsDefinition = {
- *   logger: () => new LoggerService(),
- *   db: () => new Database(process.env.DB_URL!),
- *   userRepo: (c) => new PgUserRepo(c.db),
- * };
- * ```
- */
-type DepsDefinition = Record<string, Factory>;
-/**
- * Extracts the resolved types from a deps definition.
- * Maps each key to the return type of its factory function.
- *
- * @example
- * ```typescript
- * type Resolved = ResolvedDeps<{ logger: () => LoggerService }>;
- * // { logger: LoggerService }
- * ```
+ * Reserved method names on the container that cannot be used as dependency keys.
  */
-type ResolvedDeps<T extends DepsDefinition> = { readonly [K in keyof T]: ReturnType<T[K]> };
+declare const RESERVED_KEYS: readonly ["scope", "extend", "module", "preload", "reset", "inspect", "describe", "health", "dispose", "toString"];
 /**
  * Options for creating a scoped container.
  */
@@ -46,18 +25,18 @@ interface ScopeOptions {
  *
  * @example
  * ```typescript
- * const container: Container<{ logger: LoggerService }> = createContainer({
- *   logger: () => new LoggerService(),
- * });
- * container.logger; // LoggerService
- * container.inspect(); // ContainerGraph
+ * const c = container()
+ *   .add('logger', () => new LoggerService())
+ *   .build();
+ * c.logger; // LoggerService
+ * c.inspect(); // ContainerGraph
  * ```
  */
-type Container<T extends Record<string, any> = Record<string, any>> = T & IContainer<T>;
+type Container<T extends Record<string, unknown> = Record<string, unknown>> = T & IContainer<T>;
 /**
  * Container methods interface. Defines the API available on every container.
  */
-interface IContainer<T extends Record<string, any> = Record<string, any>> {
+interface IContainer<T extends Record<string, unknown> = Record<string, unknown>> {
   /**
    * Creates a child container with additional dependencies.
    * Child inherits all parent singletons and can add/override deps.
@@ -66,23 +45,37 @@ interface IContainer<T extends Record<string, any> = Record<string, any>> {
    * ```typescript
    * const request = app.scope({
    *   requestId: () => crypto.randomUUID(),
-   *   currentUser: () => extractUser(req),
+   *   handler: (c) => new Handler(c.logger),  // c typed as parent
    * });
-   * request.requestId; // scoped singleton
-   * request.logger;    // inherited from parent
    * ```
    */
-  scope<E extends DepsDefinition>(extra: E, options?: ScopeOptions): Container<T & ResolvedDeps<E>>;
+  scope<E extends Record<string, (c: T) => unknown>>(extra: E, options?: ScopeOptions): Container<Omit<T, keyof { [K in keyof E]: ReturnType<E[K]> }> & { [K in keyof E]: ReturnType<E[K]> }>;
   /**
    * Returns a new container with additional dependencies.
    * Existing singletons are shared. The original container is not modified.
    *
    * @example
    * ```typescript
-   * const appWithAuth = app.extend(authDeps);
+   * const full = app.extend({
+   *   cache: (c) => new Redis(c.logger),  // c typed as parent
+   * });
+   * ```
+   */
+  extend<E extends Record<string, (c: T) => unknown>>(extra: E): Container<Omit<T, keyof { [K in keyof E]: ReturnType<E[K]> }> & { [K in keyof E]: ReturnType<E[K]> }>;
+  /**
+   * Applies a module post-build using the builder pattern.
+   * Semantically equivalent to `extend()` but uses `ContainerBuilder` for
+   * incremental type accumulation of `c` in factories.
+   *
+   * @example
+   * ```typescript
+   * const withDb = app.module((b) => b
+   *   .add('db', (c) => new Database(c.config))
+   *   .add('cache', (c) => new Redis(c.config))
+   * );
    * ```
    */
-  extend<E extends DepsDefinition>(extra: E): Container<T & ResolvedDeps<E>>;
+  module<TNew extends Record<string, unknown>>(fn: (builder: ContainerBuilder<Record<string, unknown>, T>) => ContainerBuilder<Record<string, unknown>, TNew>): Container<TNew>;
   /**
    * Pre-resolves dependencies (warm-up).
    * Call with specific keys to resolve only those, or without arguments to resolve all.
@@ -114,7 +107,7 @@ interface IContainer<T extends Record<string, any> = Record<string, any>> {
    * // { key: 'userService', resolved: true, deps: ['userRepo', 'logger'], scope: 'singleton' }
    * ```
    */
-  describe(key: keyof T): ProviderInfo;
+  describe(key: keyof T | string): ProviderInfo;
   /**
    * Returns container health status and warnings.
    *
@@ -176,11 +169,125 @@ interface ContainerHealth {
  * A warning detected by the container's runtime analysis.
  */
 interface ContainerWarning {
-  type: 'scope_mismatch' | 'duplicate_key';
+  type: 'scope_mismatch';
   message: string;
   details: Record<string, unknown>;
 }
 //#endregion
+//#region src/application/container-builder.d.ts
+/**
+ * Fluent builder that constructs a typed DI container incrementally.
+ *
+ * Two modes, one class:
+ * - `container<AppDeps>()` — contract mode: keys restricted to `keyof AppDeps`, return types constrained
+ * - `container()` — free mode: keys are any `string`, types inferred freely
+ *
+ * Each `.add()` call accumulates the type so that subsequent factories
+ * receive a fully-typed `c` parameter with all previously registered deps.
+ */
+declare class ContainerBuilder<TContract extends Record<string, unknown> = Record<string, unknown>, TBuilt extends Record<string, unknown> = {}> {
+  private readonly factories;
+  private readonly transientKeys;
+  /**
+   * Registers a dependency — factory (lazy) or instance (eager).
+   *
+   * Convention: `typeof value === 'function'` → factory. Otherwise → instance (wrapped in `() => value`).
+   * To register a function as a value: `add('fn', () => myFunction)`.
+   */
+  add<K extends string & keyof TContract, V extends TContract[K]>(key: K & (K extends (typeof RESERVED_KEYS)[number] ? never : K), factoryOrInstance: ((c: TBuilt) => V) | (V & (V extends Function ? never : V))): ContainerBuilder<TContract, TBuilt & Record<K, V>>;
+  /**
+   * Registers a transient dependency (new instance on every access).
+   */
+  addTransient<K extends string & keyof TContract, V extends TContract[K]>(key: K & (K extends (typeof RESERVED_KEYS)[number] ? never : K), factory: (c: TBuilt) => V): ContainerBuilder<TContract, TBuilt & Record<K, V>>;
+  /**
+   * Applies a module — a function that chains `.add()` calls on this builder.
+   * `c` in the module's factories is fully typed with all previously registered deps.
+   */
+  addModule<TNew extends Record<string, unknown>>(module: (builder: ContainerBuilder<TContract, TBuilt>) => ContainerBuilder<TContract, TNew>): ContainerBuilder<TContract, TNew>;
+  /**
+   * Returns the accumulated factories as a plain record.
+   * @internal Used by `module()` on the container.
+   */
+  _toRecord(): Record<string, Factory>;
+  /**
+   * Builds and returns the final container.
+   */
+  build(): Container<TBuilt>;
+  private validateKey;
+}
+/**
+ * Creates a new container builder.
+ *
+ * @example Contract mode (interface-first):
+ * ```typescript
+ * interface AppDeps { logger: Logger; db: Database }
+ *
+ * const app = container<AppDeps>()
+ *   .add('logger', () => new ConsoleLogger())
+ *   .add('db', (c) => new PgDatabase(c.logger))
+ *   .build()
+ * ```
+ *
+ * @example Free mode:
+ * ```typescript
+ * const app = container()
+ *   .add('logger', () => new ConsoleLogger())
+ *   .add('db', (c) => new PgDatabase(c.logger))
+ *   .build()
+ * ```
+ */
+declare function container<T extends Record<string, unknown> = Record<string, unknown>>(): ContainerBuilder<T>;
+//#endregion
+//#region src/infrastructure/transient.d.ts
+/**
+ * Wraps a factory function to produce a new instance on every access,
+ * instead of the default singleton behavior.
+ *
+ * @example
+ * ```typescript
+ * import { createContainer, transient } from 'inwire';
+ *
+ * const container = createContainer({
+ *   logger: () => new LoggerService(),                  // singleton (default)
+ *   requestId: transient(() => crypto.randomUUID()),   // new instance every access
+ * });
+ *
+ * container.requestId; // 'abc-123'
+ * container.requestId; // 'def-456' (different!)
+ * ```
+ */
+declare function transient<T>(factory: Factory<T>): Factory<T>;
+//#endregion
+//#region src/domain/lifecycle.d.ts
+/**
+ * Implement this interface (or just add an `onInit` method) to run
+ * initialization logic when the dependency is first resolved.
+ *
+ * @example
+ * ```typescript
+ * class Database implements OnInit {
+ *   async onInit() { await this.connect(); }
+ * }
+ * ```
+ */
+interface OnInit {
+  onInit(): void | Promise<void>;
+}
+/**
+ * Implement this interface (or just add an `onDestroy` method) to run
+ * cleanup logic when `container.dispose()` is called.
+ *
+ * @example
+ * ```typescript
+ * class Database implements OnDestroy {
+ *   async onDestroy() { await this.disconnect(); }
+ * }
+ * ```
+ */
+interface OnDestroy {
+  onDestroy(): void | Promise<void>;
+}
+//#endregion
 //#region src/domain/errors.d.ts
 /**
  * Base class for all container errors.
@@ -215,7 +322,10 @@ declare abstract class ContainerError extends Error {
  */
 declare class ContainerConfigError extends ContainerError {
   readonly hint: string;
-  readonly details: Record<string, unknown>;
+  readonly details: {
+    key: string;
+    actualType: string;
+  };
   constructor(key: string, actualType: string);
 }
 /**
@@ -230,7 +340,10 @@ declare class ContainerConfigError extends ContainerError {
  */
 declare class ReservedKeyError extends ContainerError {
   readonly hint: string;
-  readonly details: Record<string, unknown>;
+  readonly details: {
+    key: string;
+    reserved: string[];
+  };
   constructor(key: string, reserved: readonly string[]);
 }
 /**
@@ -246,7 +359,12 @@ declare class ReservedKeyError extends ContainerError {
  */
 declare class ProviderNotFoundError extends ContainerError {
   readonly hint: string;
-  readonly details: Record<string, unknown>;
+  readonly details: {
+    key: string;
+    chain: string[];
+    registered: string[];
+    suggestion: string | undefined;
+  };
   constructor(key: string, chain: string[], registered: string[], suggestion?: string);
 }
 /**
@@ -260,7 +378,11 @@ declare class ProviderNotFoundError extends ContainerError {
  */
 declare class CircularDependencyError extends ContainerError {
   readonly hint: string;
-  readonly details: Record<string, unknown>;
+  readonly details: {
+    key: string;
+    chain: string[];
+    cycle: string;
+  };
   constructor(key: string, chain: string[]);
 }
 /**
@@ -275,7 +397,10 @@ declare class CircularDependencyError extends ContainerError {
  */
 declare class UndefinedReturnError extends ContainerError {
   readonly hint: string;
-  readonly details: Record<string, unknown>;
+  readonly details: {
+    key: string;
+    chain: string[];
+  };
   constructor(key: string, chain: string[]);
 }
 /**
@@ -290,7 +415,11 @@ declare class UndefinedReturnError extends ContainerError {
  */
 declare class FactoryError extends ContainerError {
   readonly hint: string;
-  readonly details: Record<string, unknown>;
+  readonly details: {
+    key: string;
+    chain: string[];
+    originalError: string;
+  };
   readonly originalError: unknown;
   constructor(key: string, chain: string[], originalError: unknown);
 }
@@ -307,80 +436,13 @@ declare class ScopeMismatchWarning implements ContainerWarning {
   readonly type: "scope_mismatch";
   readonly message: string;
   readonly hint: string;
-  readonly details: Record<string, unknown>;
+  readonly details: {
+    singleton: string;
+    transient: string;
+  };
   constructor(singletonKey: string, transientKey: string);
 }
 //#endregion
-//#region src/application/create-container.d.ts
-/**
- * Creates a dependency injection container from an object of factory functions.
- * Each factory receives the container and returns an instance.
- * Dependencies are resolved lazily and cached as singletons by default.
- *
- * @example
- * ```typescript
- * const container = createContainer({
- *   logger: () => new LoggerService(),
- *   db: () => new Database(process.env.DB_URL!),
- *   userRepo: (c): UserRepository => new PgUserRepo(c.db),
- *   userService: (c) => new UserService(c.userRepo, c.logger),
- * });
- *
- * container.userService; // type: UserService — lazy, singleton, fully resolved
- * ```
- */
-declare function createContainer<T extends DepsDefinition>(defs: T): Container<ResolvedDeps<T>>;
-//#endregion
-//#region src/infrastructure/transient.d.ts
-/**
- * Wraps a factory function to produce a new instance on every access,
- * instead of the default singleton behavior.
- *
- * @example
- * ```typescript
- * import { createContainer, transient } from 'inwire';
- *
- * const container = createContainer({
- *   logger: () => new LoggerService(),                  // singleton (default)
- *   requestId: transient(() => crypto.randomUUID()),   // new instance every access
- * });
- *
- * container.requestId; // 'abc-123'
- * container.requestId; // 'def-456' (different!)
- * ```
- */
-declare function transient<T>(factory: Factory<T>): Factory<T>;
-//#endregion
-//#region src/domain/lifecycle.d.ts
-/**
- * Implement this interface (or just add an `onInit` method) to run
- * initialization logic when the dependency is first resolved.
- *
- * @example
- * ```typescript
- * class Database implements OnInit {
- *   async onInit() { await this.connect(); }
- * }
- * ```
- */
-interface OnInit {
-  onInit(): void | Promise<void>;
-}
-/**
- * Implement this interface (or just add an `onDestroy` method) to run
- * cleanup logic when `container.dispose()` is called.
- *
- * @example
- * ```typescript
- * class Database implements OnDestroy {
- *   async onDestroy() { await this.disconnect(); }
- * }
- * ```
- */
-interface OnDestroy {
-  onDestroy(): void | Promise<void>;
-}
-//#endregion
 //#region src/domain/validation.d.ts
 /**
  * Detects duplicate keys across multiple modules (spread objects).
@@ -388,5 +450,5 @@ interface OnDestroy {
  */
 declare function detectDuplicateKeys(...modules: Record<string, unknown>[]): string[];
 //#endregion
-export { CircularDependencyError, type Container, ContainerConfigError, ContainerError, type ContainerGraph, type ContainerHealth, type ContainerWarning, type DepsDefinition, type Factory, FactoryError, type IContainer, type OnDestroy, type OnInit, type ProviderInfo, ProviderNotFoundError, ReservedKeyError, type ResolvedDeps, ScopeMismatchWarning, type ScopeOptions, UndefinedReturnError, createContainer, detectDuplicateKeys, transient };
+export { CircularDependencyError, type Container, ContainerBuilder, ContainerConfigError, ContainerError, type ContainerGraph, type ContainerHealth, type ContainerWarning, FactoryError, type IContainer, type OnDestroy, type OnInit, type ProviderInfo, ProviderNotFoundError, ReservedKeyError, ScopeMismatchWarning, type ScopeOptions, UndefinedReturnError, container, detectDuplicateKeys, transient };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,4 +1,4 @@
-function e(e){return typeof e==`object`&&!!e&&`onInit`in e&&typeof e.onInit==`function`}function t(e){return typeof e==`object`&&!!e&&`onDestroy`in e&&typeof e.onDestroy==`function`}const n=[`scope`,`extend`,`preload`,`reset`,`inspect`,`describe`,`health`,`dispose`,`toString`];var r=class extends Error{constructor(e){super(e),this.name=this.constructor.name}},i=class extends r{hint;details;constructor(e,t){super(`'${e}' must be a factory function, got ${t}.`),this.hint=`Wrap it: ${e}: () => ${JSON.stringify(e===e?`<your ${t} value>`:e)}`,this.details={key:e,actualType:t}}},a=class extends r{hint;details;constructor(e,t){super(`'${e}' is a reserved container method.`),this.hint=`Rename this dependency, e.g. '${e}Service' or 'my${e[0].toUpperCase()}${e.slice(1)}'.`,this.details={key:e,reserved:[...t]}}},o=class extends r{hint;details;constructor(e,t,n,r){let i=t.length>0?`\n\nResolution chain: ${[...t,`${e} (not found)`].join(` -> `)}`:``,a=`\nRegistered keys: [${n.join(`, `)}]`,o=r?`\n\nDid you mean '${r}'?`:``;super(`Cannot resolve '${t[0]??e}': dependency '${e}' not found.${i}${a}${o}`),this.hint=r?`Did you mean '${r}'? Or add '${e}' to your container:\n  createContainer({\n    ...existing,\n    ${e}: (c) => new Your${e[0].toUpperCase()}${e.slice(1)}(/* deps */),\n  });`:`Add '${e}' to your container:\n  createContainer({\n    ...existing,\n    ${e}: (c) => new Your${e[0].toUpperCase()}${e.slice(1)}(/* deps */),\n  });`,this.details={key:e,chain:t,registered:n,suggestion:r}}},s=class extends r{hint;details;constructor(e,t){let n=[...t,e].join(` -> `);super(`Circular dependency detected while resolving '${t[0]}'.\n\nCycle: ${n}`),this.hint=[`To fix:`,`  1. Extract shared logic into a new dependency both can use`,`  2. Restructure so one doesn't depend on the other`,`  3. Use a mediator/event pattern to decouple them`].join(`
-`),this.details={key:e,chain:t,cycle:n}}},c=class extends r{hint;details;constructor(e,t){let n=t.length>1?`\n\nResolution chain: ${t.join(` -> `)}`:``;super(`Factory '${e}' returned undefined.${n}`),this.hint=`Your factory function returned undefined. Did you forget a return statement?`,this.details={key:e,chain:t}}},l=class extends r{hint;details;originalError;constructor(e,t,n){let r=n instanceof Error?n.message:String(n),i=t.length>1?`\n\nResolution chain: ${[...t.slice(0,-1),`${e} (factory threw)`].join(` -> `)}`:``;super(`Factory '${e}' threw an error: "${r}"${i}`),this.hint=`Check the factory function for '${e}'. The error occurred during instantiation.`,this.details={key:e,chain:t,originalError:r},this.originalError=n}},u=class{type=`scope_mismatch`;message;hint;details;constructor(e,t){this.message=`Singleton '${e}' depends on transient '${t}'.`,this.hint=[`The transient value was resolved once and is now frozen inside the singleton.`,`This is almost always a bug.`,``,`To fix:`,`  1. Make '${e}' transient too: transient((c) => new ${e[0].toUpperCase()}${e.slice(1)}(c.${t}))`,`  2. Make '${t}' singleton if it doesn't need to change`,`  3. Inject a factory instead: ${t}Factory: () => () => <your value>`].join(`
-`),this.details={singleton:e,transient:t}}},d=class{validateConfig(e){for(let[t,r]of Object.entries(e)){if(n.includes(t))throw new a(t,n);if(typeof r!=`function`)throw new i(t,typeof r)}}suggestKey(e,t){let n,r=1/0;for(let i of t){let t=p(e,i);t<r&&(r=t,n=i)}if(!n)return;let i=Math.max(e.length,n.length);return 1-r/i>=.5?n:void 0}};function f(...e){let t=new Map,n=[];for(let r of e)for(let e of Object.keys(r)){let r=(t.get(e)??0)+1;t.set(e,r),r===2&&n.push(e)}return n}function p(e,t){let n=e.length,r=t.length;if(n===0)return r;if(r===0)return n;let i=Array(r+1),a=Array(r+1);for(let e=0;e<=r;e++)i[e]=e;for(let o=1;o<=n;o++){a[0]=o;for(let n=1;n<=r;n++){let r=e[o-1]===t[n-1]?0:1;a[n]=Math.min(i[n]+1,a[n-1]+1,i[n-1]+r)}[i,a]=[a,i]}return i[r]}const m=Symbol.for(`inwire:transient`);function h(e){let t=(t=>e(t));return t[m]=!0,t}function g(e){return typeof e==`function`&&m in e&&e[m]===!0}var _=class{factories;cache;resolving=new Set;depGraph=new Map;warnings=[];validator=new d;parent;name;constructor(e,t,n,r){this.factories=e,this.cache=t??new Map,this.parent=n,this.name=r}getName(){return this.name}resolve(t,n=[]){let r=this.factories.get(t);if(r&&!g(r)&&this.cache.has(t))return this.cache.get(t);if(!r){if(this.parent)return this.parent.resolve(t,n);let e=this.getAllRegisteredKeys();throw new o(t,n,e,this.validator.suggestKey(t,e))}if(this.resolving.has(t))throw new s(t,[...n]);this.resolving.add(t);let i=[...n,t];try{let n=[],a=r(this.createTrackingProxy(t,n,i));if(a===void 0)throw new c(t,i);if(this.depGraph.set(t,n),!g(r))for(let e of n){let n=this.getFactory(e);n&&g(n)&&this.warnings.push(new u(t,e))}if(g(r)||this.cache.set(t,a),e(a)){let e=a.onInit();e instanceof Promise&&e.catch(()=>{})}return a}catch(e){throw e instanceof s||e instanceof o||e instanceof c||e instanceof l?e:new l(t,i,e)}finally{this.resolving.delete(t)}}isResolved(e){return this.cache.has(e)}getDepGraph(){return new Map(this.depGraph)}getResolvedKeys(){return[...this.cache.keys()]}getFactories(){return this.factories}getCache(){return this.cache}getWarnings(){return[...this.warnings]}getAllRegisteredKeys(){let e=new Set(this.factories.keys());if(this.parent)for(let t of this.parent.getAllRegisteredKeys())e.add(t);return[...e]}createTrackingProxy(e,t,n){return new Proxy({},{get:(e,r)=>{if(typeof r==`symbol`)return;let i=r;return t.push(i),this.resolve(i,n)}})}getFactory(e){return this.factories.get(e)??this.parent?.getFactory(e)}},v=class{constructor(e){this.resolver=e}inspect(){let e={};for(let[t,n]of this.resolver.getFactories())e[t]={key:t,resolved:this.resolver.isResolved(t),deps:this.resolver.getDepGraph().get(t)??[],scope:g(n)?`transient`:`singleton`};let t=this.resolver.getName();return t?{name:t,providers:e}:{providers:e}}describe(e){let t=this.resolver.getFactories().get(e);return t?{key:e,resolved:this.resolver.isResolved(e),deps:this.resolver.getDepGraph().get(e)??[],scope:g(t)?`transient`:`singleton`}:{key:e,resolved:!1,deps:[],scope:`singleton`}}health(){let e=[...this.resolver.getFactories().keys()],t=this.resolver.getResolvedKeys(),n=new Set(t),r=this.resolver.getWarnings().map(e=>({type:e.type,message:e.message,details:e.details}));return{totalProviders:e.length,resolved:t,unresolved:e.filter(e=>!n.has(e)),warnings:r}}toString(){let e=[];for(let[t]of this.resolver.getFactories()){let n=this.resolver.isResolved(t),r=this.resolver.getDepGraph().get(t),i=r&&r.length>0?` -> [${r.join(`, `)}]`:``,a=n?`(resolved)`:`(pending)`;e.push(`${t}${i} ${a}`)}let t=this.resolver.getName();return`${t?`Scope(${t})`:`Container`} { ${e.join(`, `)} }`}};function y(e,t,n){let r=new Map;for(let[e,n]of Object.entries(t))r.set(e,n);return S(new _(r,new Map,e,n?.name))}const b=new d;function x(e){b.validateConfig(e);let t=new Map;for(let[n,r]of Object.entries(e))t.set(n,r);return S(new _(t))}function S(e){let n=new v(e),r={scope:(t,n)=>y(e,t,n),extend:t=>{b.validateConfig(t);let n=new Map(e.getFactories());for(let[e,r]of Object.entries(t))n.set(e,r);return S(new _(n,new Map(e.getCache())))},preload:async(...t)=>{let n=t.length>0?t:[...e.getFactories().keys()];for(let t of n)e.resolve(t)},reset:(...t)=>{let n=e.getCache();for(let e of t)n.delete(e)},inspect:()=>n.inspect(),describe:e=>n.describe(e),health:()=>n.health(),toString:()=>n.toString(),dispose:async()=>{let n=e.getCache(),r=[...n.entries()].reverse();for(let[,e]of r)t(e)&&await e.onDestroy();n.clear()}};return new Proxy({},{get(t,i){if(typeof i==`symbol`)return i===Symbol.toPrimitive||i===Symbol.toStringTag?()=>n.toString():void 0;let a=i;return a in r?r[a]:e.resolve(a)},has(t,n){if(typeof n==`symbol`)return!1;let i=n;return i in r||e.getFactories().has(i)||e.getAllRegisteredKeys().includes(i)},ownKeys(){return[...e.getAllRegisteredKeys(),...Object.keys(r)]},getOwnPropertyDescriptor(t,n){if(typeof n==`symbol`)return;let i=n;if(i in r||e.getFactories().has(i)||e.getAllRegisteredKeys().includes(i))return{configurable:!0,enumerable:!(i in r),writable:!1}}})}export{s as CircularDependencyError,i as ContainerConfigError,r as ContainerError,l as FactoryError,o as ProviderNotFoundError,a as ReservedKeyError,u as ScopeMismatchWarning,c as UndefinedReturnError,x as createContainer,f as detectDuplicateKeys,h as transient};
+const e=[`scope`,`extend`,`module`,`preload`,`reset`,`inspect`,`describe`,`health`,`dispose`,`toString`];var t=class extends Error{constructor(e){super(e),this.name=this.constructor.name}},n=class extends t{hint;details;constructor(e,t){super(`'${e}' must be a factory function, got ${t}.`),this.hint=`Wrap it: ${e}: () => <your ${t} value>`,this.details={key:e,actualType:t}}},r=class extends t{hint;details;constructor(e,t){super(`'${e}' is a reserved container method.`),this.hint=`Rename this dependency, e.g. '${e}Service' or 'my${e[0].toUpperCase()}${e.slice(1)}'.`,this.details={key:e,reserved:[...t]}}},i=class extends t{hint;details;constructor(e,t,n,r){let i=t.length>0?`\n\nResolution chain: ${[...t,`${e} (not found)`].join(` -> `)}`:``,a=`\nRegistered keys: [${n.join(`, `)}]`,o=r?`\n\nDid you mean '${r}'?`:``;super(`Cannot resolve '${t[0]??e}': dependency '${e}' not found.${i}${a}${o}`),this.hint=r?`Did you mean '${r}'? Or add '${e}' to your container:\n  createContainer({\n    ...existing,\n    ${e}: (c) => new Your${e[0].toUpperCase()}${e.slice(1)}(/* deps */),\n  });`:`Add '${e}' to your container:\n  createContainer({\n    ...existing,\n    ${e}: (c) => new Your${e[0].toUpperCase()}${e.slice(1)}(/* deps */),\n  });`,this.details={key:e,chain:t,registered:n,suggestion:r}}},a=class extends t{hint;details;constructor(e,t){let n=[...t,e].join(` -> `);super(`Circular dependency detected while resolving '${t[0]}'.\n\nCycle: ${n}`),this.hint=[`To fix:`,`  1. Extract shared logic into a new dependency both can use`,`  2. Restructure so one doesn't depend on the other`,`  3. Use a mediator/event pattern to decouple them`].join(`
+`),this.details={key:e,chain:t,cycle:n}}},o=class extends t{hint;details;constructor(e,t){let n=t.length>1?`\n\nResolution chain: ${t.join(` -> `)}`:``;super(`Factory '${e}' returned undefined.${n}`),this.hint=`Your factory function returned undefined. Did you forget a return statement?`,this.details={key:e,chain:t}}},s=class extends t{hint;details;originalError;constructor(e,t,n){let r=n instanceof Error?n.message:String(n),i=t.length>1?`\n\nResolution chain: ${[...t.slice(0,-1),`${e} (factory threw)`].join(` -> `)}`:``;super(`Factory '${e}' threw an error: "${r}"${i}`),this.hint=`Check the factory function for '${e}'. The error occurred during instantiation.`,this.details={key:e,chain:t,originalError:r},this.originalError=n}},c=class{type=`scope_mismatch`;message;hint;details;constructor(e,t){this.message=`Singleton '${e}' depends on transient '${t}'.`,this.hint=[`The transient value was resolved once and is now frozen inside the singleton.`,`This is almost always a bug.`,``,`To fix:`,`  1. Make '${e}' transient too: transient((c) => new ${e[0].toUpperCase()}${e.slice(1)}(c.${t}))`,`  2. Make '${t}' singleton if it doesn't need to change`,`  3. Inject a factory instead: ${t}Factory: () => () => <your value>`].join(`
+`),this.details={singleton:e,transient:t}}};const l=Symbol.for(`inwire:transient`);function u(e){let t=(t=>e(t));return t[l]=!0,t}function d(e){return typeof e==`function`&&l in e&&e[l]===!0}function f(e){return typeof e==`object`&&!!e&&`onInit`in e&&typeof e.onInit==`function`}function p(e){return typeof e==`object`&&!!e&&`onDestroy`in e&&typeof e.onDestroy==`function`}var m=class{validateConfig(t){for(let[i,a]of Object.entries(t)){if(e.includes(i))throw new r(i,e);if(typeof a!=`function`)throw new n(i,typeof a)}}suggestKey(e,t){let n,r=1/0;for(let i of t){let t=g(e,i);t<r&&(r=t,n=i)}if(!n)return;let i=Math.max(e.length,n.length);return 1-r/i>=.5?n:void 0}};function h(...e){let t=new Map,n=[];for(let r of e)for(let e of Object.keys(r)){let r=(t.get(e)??0)+1;t.set(e,r),r===2&&n.push(e)}return n}function g(e,t){let n=e.length,r=t.length;if(n===0)return r;if(r===0)return n;let i=Array(r+1),a=Array(r+1);for(let e=0;e<=r;e++)i[e]=e;for(let o=1;o<=n;o++){a[0]=o;for(let n=1;n<=r;n++){let r=e[o-1]===t[n-1]?0:1;a[n]=Math.min(i[n]+1,a[n-1]+1,i[n-1]+r)}[i,a]=[a,i]}return i[r]}var _=class{factories;cache;resolving=new Set;depGraph=new Map;warnings=[];validator=new m;parent;name;constructor(e,t,n,r){this.factories=e,this.cache=t??new Map,this.parent=n,this.name=r}getName(){return this.name}resolve(e,t=[]){let n=this.factories.get(e);if(n&&!d(n)&&this.cache.has(e))return this.cache.get(e);if(!n){if(this.parent)return this.parent.resolve(e,t);let n=this.getAllRegisteredKeys();throw new i(e,t,n,this.validator.suggestKey(e,n))}if(this.resolving.has(e))throw new a(e,[...t]);this.resolving.add(e);let r=[...t,e];try{let t=[],i=n(this.createTrackingProxy(e,t,r));if(i===void 0)throw new o(e,r);if(this.depGraph.set(e,t),!d(n))for(let n of t){let t=this.getFactory(n);t&&d(t)&&this.warnings.push(new c(e,n))}if(d(n)||this.cache.set(e,i),f(i)){let e=i.onInit();e instanceof Promise&&e.catch(()=>{})}return i}catch(t){throw t instanceof a||t instanceof i||t instanceof o||t instanceof s?t:new s(e,r,t)}finally{this.resolving.delete(e)}}isResolved(e){return this.cache.has(e)}getDepGraph(){return new Map(this.depGraph)}getResolvedKeys(){return[...this.cache.keys()]}getFactories(){return this.factories}getCache(){return this.cache}getWarnings(){return[...this.warnings]}getAllRegisteredKeys(){let e=new Set(this.factories.keys());if(this.parent)for(let t of this.parent.getAllRegisteredKeys())e.add(t);return[...e]}createTrackingProxy(e,t,n){return new Proxy({},{get:(e,r)=>{if(typeof r==`symbol`)return;let i=r;return t.push(i),this.resolve(i,n)}})}getFactory(e){return this.factories.get(e)??this.parent?.getFactory(e)}},v=class{constructor(e){this.resolver=e}inspect(){let e={};for(let[t,n]of this.resolver.getFactories())e[t]={key:t,resolved:this.resolver.isResolved(t),deps:this.resolver.getDepGraph().get(t)??[],scope:d(n)?`transient`:`singleton`};let t=this.resolver.getName();return t?{name:t,providers:e}:{providers:e}}describe(e){let t=this.resolver.getFactories().get(e);return t?{key:e,resolved:this.resolver.isResolved(e),deps:this.resolver.getDepGraph().get(e)??[],scope:d(t)?`transient`:`singleton`}:{key:e,resolved:!1,deps:[],scope:`singleton`}}health(){let e=[...this.resolver.getFactories().keys()],t=this.resolver.getResolvedKeys(),n=new Set(t),r=this.resolver.getWarnings().map(e=>({type:e.type,message:e.message,details:e.details}));return{totalProviders:e.length,resolved:t,unresolved:e.filter(e=>!n.has(e)),warnings:r}}toString(){let e=[];for(let[t]of this.resolver.getFactories()){let n=this.resolver.isResolved(t),r=this.resolver.getDepGraph().get(t),i=r&&r.length>0?` -> [${r.join(`, `)}]`:``,a=n?`(resolved)`:`(pending)`;e.push(`${t}${i} ${a}`)}let t=this.resolver.getName();return`${t?`Scope(${t})`:`Container`} { ${e.join(`, `)} }`}};const y=new m;function b(e,t){let n=new v(e),r={scope:(n,r)=>{let i=new Map;for(let[e,t]of Object.entries(n))i.set(e,t);return b(new _(i,new Map,e,r?.name),t)},extend:n=>{y.validateConfig(n);let r=new Map(e.getFactories());for(let[e,t]of Object.entries(n))r.set(e,t);return b(new _(r,new Map(e.getCache())),t)},module:e=>{if(!t)throw Error(`module() is not available`);let n=e(t());return r.extend(n._toRecord())},preload:async(...t)=>{let n=t.length>0?t:[...e.getFactories().keys()];for(let t of n)e.resolve(t)},reset:(...t)=>{let n=e.getCache();for(let e of t)n.delete(e)},inspect:()=>n.inspect(),describe:e=>n.describe(e),health:()=>n.health(),toString:()=>n.toString(),dispose:async()=>{let t=e.getCache(),n=[...t.entries()].reverse();for(let[,e]of n)p(e)&&await e.onDestroy();t.clear()}};return new Proxy({},{get(t,i){if(typeof i==`symbol`)return i===Symbol.toPrimitive||i===Symbol.toStringTag?()=>n.toString():void 0;let a=i;return a in r?r[a]:e.resolve(a)},has(t,n){if(typeof n==`symbol`)return!1;let i=n;return i in r||e.getFactories().has(i)||e.getAllRegisteredKeys().includes(i)},ownKeys(){return[...e.getAllRegisteredKeys(),...Object.keys(r)]},getOwnPropertyDescriptor(t,n){if(typeof n==`symbol`)return;let i=n;if(i in r||e.getFactories().has(i)||e.getAllRegisteredKeys().includes(i))return{configurable:!0,enumerable:!(i in r),writable:!1}}})}var x=class t{factories=new Map;transientKeys=new Set;add(e,t){return this.validateKey(e),typeof t==`function`?this.factories.set(e,t):this.factories.set(e,()=>t),this}addTransient(e,t){return this.validateKey(e),this.factories.set(e,u(t)),this.transientKeys.add(e),this}addModule(e){return e(this)}_toRecord(){return Object.fromEntries(this.factories)}build(){return b(new _(new Map(this.factories)),()=>new t)}validateKey(t){if(e.includes(t))throw new r(t,e)}};function S(){return new x}export{a as CircularDependencyError,x as ContainerBuilder,n as ContainerConfigError,t as ContainerError,s as FactoryError,i as ProviderNotFoundError,r as ReservedKeyError,c as ScopeMismatchWarning,o as UndefinedReturnError,S as container,h as detectDuplicateKeys,u as transient};
 //# sourceMappingURL=index.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inwire",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Zero-ceremony dependency injection for TypeScript. Full inference, no decorators, no tokens. Built-in introspection for AI tooling.",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -21,6 +21,12 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "lint": "tsc --noEmit",
+    "example:web": "tsx examples/01-web-service.ts",
+    "example:test": "tsx examples/02-modular-testing.ts",
+    "example:plugin": "tsx examples/03-plugin-system.ts",
+    "example:modules": "tsx examples/04-modules.ts",
+    "bench": "tsx benchmarks/bench.ts",
+    "bench:compare": "tsx benchmarks/compare.ts",
     "prepublishOnly": "npm run build"
   },
   "publishConfig": {