inwire 2.2.1 → 2.3.1

package/README.md

@@ -301,6 +301,101 @@ const full = withDb.module((b) =>
 
 `module()` uses the builder internally for typed `c`, then delegates to `extend()`. Works on `scope()` and `extend()` results too.
 
+#### Deriving the container shape (Zod-style)
+
+You don't need to maintain a manual interface for the container's full shape. Derive it from the container itself, exactly like `z.infer<typeof schema>`:
+
+```typescript
+// container.ts
+import { container } from 'inwire';
+import { authModule } from './modules/auth.module';
+import { billingModule } from './modules/billing.module';
+import { persistenceModule } from './modules/persistence.module';
+
+export const di = container()
+  .addModule(persistenceModule)
+  .addModule(authModule)
+  .addModule(billingModule)
+  .build();
+
+// Single source of truth — derived, never written by hand.
+// Use this as the type for handlers, controllers, etc.
+export type Di = typeof di;
+```
+
+> Note: `Di` is your own type alias, not the global `AppDeps` interface inwire exports for the Pinia-style pattern below. They serve different purposes — `Di` is consumed by your code; `AppDeps` augments inwire's typing.
+
+Each module declares only the contracts it consumes via `<TDeps>` — and those contracts are the **interfaces you already have** in `domain/` or `contracts/` (Clean Architecture, DDD):
+
+```typescript
+// modules/auth.module.ts
+import { defineModule } from 'inwire';
+import type { IUserRepository } from '../contracts/IUserRepository';
+import type { IAuthProvider } from '../contracts/IAuthProvider';
+import { BetterAuthProvider } from '../infrastructure/BetterAuthProvider';
+import { SignInUseCase } from '../application/SignInUseCase';
+
+export const authModule = defineModule<{ IUserRepository: IUserRepository }>()((b) =>
+  b
+    .add('IAuthProvider', (): IAuthProvider => new BetterAuthProvider())
+    .add('SignInUseCase', (c) => new SignInUseCase(c.IUserRepository, c.IAuthProvider)),
+);
+```
+
+Why this is the right pattern:
+- **No shape interface to maintain.** Add a binding anywhere → `Di` grows automatically. Remove one → it shrinks.
+- **No `declare module` augmentation.** No global state, no import side-effects.
+- **Local prerequisites.** A module's `<TDeps>` is its API contract — three lines max, exactly what it needs.
+- **Cross-module references work at build time.** When `authModule` registers `SignInUseCase` that needs `IUserRepository` (provided by `persistenceModule`), the prerequisite check at `addModule()` time enforces the order.
+
+See [examples/05-zod-style-typing.ts](examples/05-zod-style-typing.ts) for a full walk-through with three modules and a derived `Di`.
+
+#### Cross-module forward references (Pinia-style)
+
+When a module needs to consume a binding **provided by another module loaded later**, the local `<TDeps>` pattern can't help — the prerequisite would have to list everything the module sees, defeating the locality. For that case, inwire exposes an augmentable global interface, exactly like Pinia's `PiniaCustomProperties` or Vue's `ComponentCustomProperties`:
+
+```typescript
+import 'inwire';
+
+declare module 'inwire' {
+  interface AppDeps {
+    IUserRepository: IUserRepository;
+    SignInUseCase: SignInUseCase;
+  }
+}
+```
+
+Each module file augments `AppDeps` with the bindings **it provides**. When you call `defineModule()` *without* a `<TDeps>` generic, `c` is typed as the global `AppDeps` — so `c.X` resolves transparently across modules, regardless of declaration order:
+
+```typescript
+// modules/auth.module.ts
+declare module 'inwire' {
+  interface AppDeps {
+    IAuthProvider: IAuthProvider;
+    SignInUseCase: SignInUseCase;
+  }
+}
+
+export const authModule = defineModule()((b) =>
+  b
+    .add('IAuthProvider', (): IAuthProvider => new BetterAuthProvider())
+    .add('SignInUseCase', (c) => new SignInUseCase(c.IUserRepository, c.IAuthProvider)),
+  //                                              ^^^^^^^^^^^^^^^^^^^^
+  //                       provided by another module — type-checked via AppDeps
+);
+```
+
+Trade-off vs `defineModule<TDeps>()`:
+
+| Pattern | You declare | Cross-module forward ref |
+|---|---|---|
+| `defineModule<TDeps>()` | what the module **consumes** (inputs) | no — must be already added |
+| `defineModule()` + `declare module` | what the module **adds** (outputs) | yes — order-independent |
+
+Both patterns coexist. Mix freely — the explicit `<TDeps>` always overrides the global mode for that module. Why two? Because not every project needs the global augmentation, and not every module needs a tight prerequisite list. Pick the one that feels lighter for the file you're writing.
+
+See [examples/06-pinia-augmentation.ts](examples/06-pinia-augmentation.ts) for a full walk-through with two modules cross-referencing each other.
+
 ### Preload
 
 ```typescript
@@ -382,6 +477,8 @@ detectDuplicateKeys(authModule, userModule);
 | [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 |
+| [05-zod-style-typing.ts](examples/05-zod-style-typing.ts) | `npm run example:typing` | `type AppDeps = typeof di` pattern, Clean Arch contracts, no manual interface |
+| [06-pinia-augmentation.ts](examples/06-pinia-augmentation.ts) | `npm run example:pinia` | Cross-module forward references via `declare module 'inwire'`, order-independent typing |
 
 ## Architecture
 

package/dist/index.d.mts

@@ -188,6 +188,28 @@ type Factory<T = unknown> = (container: unknown) => T;
  * Reserved method names on the container that cannot be used as dependency keys.
  */
 declare const RESERVED_KEYS: readonly ["scope", "extend", "module", "preload", "reset", "inspect", "describe", "health", "dispose", "toString"];
+/**
+ * Global, augmentable interface describing the application's dependency shape.
+ *
+ * Empty by default. Each module file augments it with the bindings IT provides,
+ * enabling **cross-module forward references** in factories — `c.X` resolves
+ * even when `X` is added by another module loaded later.
+ *
+ * @example Augment from a module file:
+ * ```typescript
+ * declare module 'inwire' {
+ *   interface AppDeps {
+ *     IUserRepository: IUserRepository;
+ *     SignInUseCase: SignInUseCase;
+ *   }
+ * }
+ * ```
+ *
+ * When `defineModule()` is called without an explicit `<TDeps>` generic, the
+ * builder's `c` parameter is typed as `AppDeps` — the union of every module's
+ * augmentations. TypeScript merges these declarations across files.
+ */
+interface AppDeps {}
 /**
  * Options for creating a scoped container.
  */
@@ -351,6 +373,12 @@ interface ContainerWarning {
 }
 //#endregion
 //#region src/application/container-builder.d.ts
+/**
+ * `T` with the keys of `U` overridden by `U` (no duplicate-key intersection).
+ * Required to avoid `A & A → never` when classes have private members and the
+ * same key is declared in both `T` and `U` (e.g. global AppDeps + module add).
+ */
+type Override<T, U> = Omit<T, keyof U> & U;
 /**
  * Fluent builder that constructs a typed DI container incrementally.
  *
@@ -369,16 +397,22 @@ declare class ContainerBuilder<TContract extends Record<string, any> = Record<st
    * 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>>;
+  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, Override<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>>;
+  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, Override<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.
+   *
+   * `TDepsM` (the module's expected prereqs) is inferred independently from the
+   * builder's current `TBuilt`. Prereq satisfaction is NOT enforced at the type
+   * level on purpose: in global mode (`defineModule()` typed against `AppDeps`)
+   * the prereq surface is the full app, never the partial builder state. The
+   * runtime guarantees correctness via `ProviderNotFoundError` if a key is
+   * missing at resolution time.
    */
-  addModule<TNew extends Record<string, any>>(module: (builder: ContainerBuilder<TContract, TBuilt>) => ContainerBuilder<TContract, TNew>): ContainerBuilder<TContract, TBuilt & TNew>;
+  addModule<TDepsM extends Record<string, any>, TNew extends Record<string, any>>(module: (builder: ContainerBuilder<TContract, TDepsM>) => ContainerBuilder<TContract, TNew>): ContainerBuilder<TContract, Override<TBuilt, TNew>>;
   /**
    * Merges a standalone builder into this one. All factories of `other` are copied.
    * The accumulated type becomes `TBuilt & TOther`, so subsequent factories can
@@ -393,7 +427,7 @@ declare class ContainerBuilder<TContract extends Record<string, any> = Record<st
    * Cross-builder dependencies are resolved at build time. Reserved keys throw.
    * Duplicate keys override silently — same semantics as `.add()` over an existing key.
    */
-  merge<TOther extends Record<string, unknown>>(other: ContainerBuilder<Record<string, unknown>, TOther>): ContainerBuilder<TContract, TBuilt & TOther>;
+  merge<TOther extends Record<string, unknown>>(other: ContainerBuilder<Record<string, unknown>, TOther>): ContainerBuilder<TContract, Override<TBuilt, TOther>>;
   /**
    * Returns the accumulated factories as a plain record.
    * @internal Used by `module()` on the container and `merge()` on builders.
@@ -437,29 +471,49 @@ declare function container<T extends Record<string, any> = Record<string, unknow
  *
  * Use {@link defineModule} to build a `Module` with strong inference.
  */
-type Module<TDeps extends Record<string, any> = {}, TBuilt extends Record<string, any> = TDeps> = (builder: ContainerBuilder<Record<string, unknown>, TDeps>) => ContainerBuilder<Record<string, unknown>, TBuilt>;
+type Module<TDeps extends Record<string, any> = AppDeps, TBuilt extends Record<string, any> = TDeps> = (builder: ContainerBuilder<Record<string, unknown>, TDeps>) => ContainerBuilder<Record<string, unknown>, TBuilt>;
 /**
- * Defines a reusable, strongly-typed module without importing the host's deps interface.
+ * Defines a reusable, strongly-typed module.
  *
- * Pattern: `defineModule<Prerequisites>()(builder => builder.add(...))`.
- * Prerequisites are declared **locally**, not pulled from a global `AppDeps`.
- * The output type is **inferred** from the chained `.add()` calls — no manual signature.
+ * Two modes, picked by whether you pass `<TDeps>` explicitly:
  *
- * @example
+ * - **Global mode** (`defineModule()`, no generic): `c` is typed as `AppDeps`,
+ *   the augmentable global interface. Each module file augments `AppDeps` with
+ *   what it provides via `declare module 'inwire' { interface AppDeps { … } }`.
+ *   Cross-module forward references work transparently — `c.X` resolves even
+ *   when `X` is added by another module.
+ * - **Local mode** (`defineModule<TDeps>()`): `c` is typed as `TDeps`, declared
+ *   locally inline. No global augmentation needed. Use when the module's
+ *   prerequisites are a tight, fixed surface.
+ *
+ * The output type is always **inferred** from the chained `.add()` calls.
+ *
+ * @example Global mode (Pinia-style):
  * ```typescript
- * import { defineModule } from 'inwire';
+ * declare module 'inwire' {
+ *   interface AppDeps {
+ *     IUserRepository: IUserRepository;
+ *     SignInUseCase: SignInUseCase;
+ *   }
+ * }
  *
+ * export const authModule = defineModule()((b) =>
+ *   b
+ *     .add('IUserRepository', () => new DrizzleUserRepository())
+ *     .add('SignInUseCase', (c) => new SignInUseCase(c.IUserRepository, c.IAuthProvider)),
+ *   //                                                                   ^^^^^^^^^^^^^^^
+ *   //                                          provided by another module — typed via AppDeps
+ * );
+ * ```
+ *
+ * @example Local mode (explicit prerequisites):
+ * ```typescript
  * const billingModule = defineModule<{ eventBus: EventBus }>()((b) =>
  *   b.add('subscribeUseCase', (c) => new SubscribeUseCase(c.eventBus)),
  * );
- *
- * const di = container()
- *   .add('eventBus', () => new EventBus())
- *   .addModule(billingModule)
- *   .build();
  * ```
  */
-declare function defineModule<TDeps extends Record<string, any> = {}>(): <TBuilt extends Record<string, any>>(fn: (builder: ContainerBuilder<Record<string, unknown>, TDeps>) => ContainerBuilder<Record<string, unknown>, TBuilt>) => Module<TDeps, TBuilt>;
+declare function defineModule<TDeps extends Record<string, any> = AppDeps>(): <TBuilt extends Record<string, any>>(fn: (builder: ContainerBuilder<Record<string, unknown>, TDeps>) => ContainerBuilder<Record<string, unknown>, TBuilt>) => Module<TDeps, TBuilt>;
 /**
  * Extracts the prerequisite deps of a `Module`.
  */
@@ -525,7 +579,7 @@ declare function detectDuplicateKeys(...modules: Record<string, unknown>[]): str
  * app.requestId; // 'def-456' (different!)
  * ```
  */
-declare function transient<T>(factory: Factory<T>): Factory<T>;
+declare function transient<T, C = unknown>(factory: (container: C) => T): (container: C) => T;
 //#endregion
-export { AsyncInitErrorWarning, CircularDependencyError, type Container, ContainerBuilder, ContainerConfigError, ContainerError, type ContainerGraph, type ContainerHealth, type ContainerWarning, type Factory, FactoryError, type IContainer, type InferModuleBuilt, type InferModuleDeps, type Module, type OnDestroy, type OnInit, type ProviderInfo, ProviderNotFoundError, ReservedKeyError, ScopeMismatchWarning, type ScopeOptions, UndefinedReturnError, container, defineModule, detectDuplicateKeys, transient };
+export { type AppDeps, AsyncInitErrorWarning, CircularDependencyError, type Container, ContainerBuilder, ContainerConfigError, ContainerError, type ContainerGraph, type ContainerHealth, type ContainerWarning, type Factory, FactoryError, type IContainer, type InferModuleBuilt, type InferModuleDeps, type Module, type OnDestroy, type OnInit, type ProviderInfo, ProviderNotFoundError, ReservedKeyError, ScopeMismatchWarning, type ScopeOptions, UndefinedReturnError, container, defineModule, detectDuplicateKeys, transient };
 //# sourceMappingURL=index.d.mts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inwire",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "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",
@@ -20,16 +20,18 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p examples/tsconfig.json",
     "lint": "biome check",
     "lint:fix": "biome check --fix",
     "format": "biome format --write",
     "format:check": "biome format",
-    "check": "biome check && tsc --noEmit",
+    "check": "biome check && pnpm typecheck",
     "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",
+    "example:typing": "tsx examples/05-zod-style-typing.ts",
+    "example:pinia": "tsx examples/06-pinia-augmentation.ts",
     "prepublishOnly": "npm run build"
   },
   "publishConfig": {