feat!: throw on duplicate keys, add toJSON/size/iterator, configurable fuzzy threshold

BREAKING CHANGE: `detectDuplicateKeys` removed from the public API.
`.add()` and `.addTransient()` now throw `DuplicateKeyError` when a key is
already registered — silent overwrites are gone. Use `.extend()` or `.scope()`
on a built container for intentional overrides.

Closes #3, #5, #6, #7, #8, #9, #11, #12, #19.

- #19 — `DuplicateKeyError` thrown by `add()`/`addTransient()`; `detectDuplicateKeys` removed
- #7 — `Validator` accepts `similarityThreshold` via constructor (default 0.5)
- #5 — `container.toJSON()` returns resolved deps; `JSON.stringify(container)` works
- #6 — `container.size` returns count of registered providers
- #12 — `Symbol.iterator` yields `[key, value]` pairs; `for...of`, spread, `Array.from`
- #8 — coercion edge-case tests (`String(c)`, template literals, loose equality)
- #9 — `structuredClone(inspect())` compatibility tests
- #11 — benchmark suite (`pnpm run bench`) measuring build / resolve / transient / scope / preload
- #3 — Deno + Bun usage examples

Author: axelhamil

CLAUDE.md

@@ -65,9 +65,9 @@ src/
 **What lives here:**
 
 - `types.ts` — all interfaces: `IResolver`, `ICycleDetector`, `IDependencyTracker`, `IValidator`, `IContainer`, `Container<T>`, `Factory<T>`, `RESERVED_KEYS`, `AppDeps` (augmentable global interface for cross-module typing).
-- `errors.ts` — 7 error classes (all extend `ContainerError` with `hint` + `details`) + 2 warning types.
+- `errors.ts` — 8 error classes (all extend `ContainerError` with `hint` + `details`) + 2 warning types.
 - `lifecycle.ts` — `OnInit`/`OnDestroy` interfaces + duck-type guards (`hasOnInit`, `hasOnDestroy`).
-- `validation.ts` — `Validator` class (implements `IValidator`), `detectDuplicateKeys`, Levenshtein distance.
+- `validation.ts` — `Validator` class (configurable `similarityThreshold` via constructor), Levenshtein distance.
 
 **Rules:**
 
@@ -177,8 +177,8 @@ The public API is defined in `src/index.ts`. **If it's not in this list, it's no
 
 Exported:
 
-- **Values:** `container()`, `ContainerBuilder`, `defineModule`, `transient`, `detectDuplicateKeys`.
-- **Errors (values):** `ContainerError`, `CircularDependencyError`, `ContainerConfigError`, `FactoryError`, `ProviderNotFoundError`, `ReservedKeyError`, `UndefinedReturnError`, `AsyncInitErrorWarning`, `ScopeMismatchWarning`.
+- **Values:** `container()`, `ContainerBuilder`, `defineModule`, `transient`.
+- **Errors (values):** `ContainerError`, `CircularDependencyError`, `ContainerConfigError`, `DuplicateKeyError`, `FactoryError`, `ProviderNotFoundError`, `ReservedKeyError`, `UndefinedReturnError`, `AsyncInitErrorWarning`, `ScopeMismatchWarning`.
 - **Types:** `OnInit`, `OnDestroy`, `AppDeps`, `Container`, `IContainer`, `Factory`, `ContainerGraph`, `ContainerHealth`, `ContainerWarning`, `ProviderInfo`, `ScopeOptions`, `Module`, `InferModuleDeps`, `InferModuleBuilt`.
 
 Internal (NOT exported): `Resolver`, `CycleDetector`, `DependencyTracker`, `Preloader`, `Disposer`, `Introspection`, `Validator`, `TRANSIENT_MARKER`.

README.md

@@ -559,27 +559,17 @@ app.health().warnings;
 
 Use `preload()` to surface these as proper errors.
 
-### Duplicate key detection (pre-spread)
+### Duplicate keys
 
-`detectDuplicateKeys` operates on **plain factory records** (`Record<string, Factory>`), not on `Module` functions returned by `defineModule()`. Use it when composing pre-built binding objects:
+`.add()` and `.addTransient()` throw `DuplicateKeyError` if the key is already registered — no silent overwrites:
 
 ```typescript
-import { detectDuplicateKeys } from 'inwire';
-
-const authBindings = {
-  logger: () => new Logger(),
-  session: () => new Session(),
-};
-const userBindings = {
-  logger: () => new Logger(), // duplicate
-  user: () => new User(),
-};
-
-detectDuplicateKeys(authBindings, userBindings);
-// ['logger']
+container()
+  .add('logger', () => new ConsoleLogger())
+  .add('logger', () => new FileLogger()); // throws DuplicateKeyError
 ```
 
-> For `defineModule()`-based modules, the type system already prevents same-key collisions across `.addModule()` calls at compile time — no runtime check needed.
+For **intentional** overrides (test doubles, plugins, environment-specific bindings), use `.extend()` or `.scope()` on a built container — both are documented override mechanisms.
 
 ### All error types
 
@@ -588,6 +578,7 @@ detectDuplicateKeys(authBindings, userBindings);
 | `ContainerError` | Base class for all errors. Every subclass carries `hint` + `details`. |
 | `ContainerConfigError` | Non-function value passed to `scope()` / `extend()` deps |
 | `ReservedKeyError` | Reserved method name used as a key |
+| `DuplicateKeyError` | `.add()` or `.addTransient()` called twice with the same key |
 | `ProviderNotFoundError` | Key not registered (with fuzzy suggestion) |
 | `CircularDependencyError` | Cycle detected during resolution |
 | `UndefinedReturnError` | Factory returned `undefined` |
@@ -620,7 +611,6 @@ detectDuplicateKeys(authBindings, userBindings);
 | `ContainerBuilder` | class | Fluent builder class (rarely instantiated directly — `container()` is the entry point). Exported for type-only use and advanced composition. |
 | `defineModule<TDeps?>()(fn)` | function | Defines a typed reusable module. See [Modules reference](#modules-reference). |
 | `transient(factory)` | function | Marks a factory as transient (for `scope()` / `extend()`). |
-| `detectDuplicateKeys(...records)` | function | Returns keys that appear in more than one factory record (`Record<string, Factory>`). |
 
 ### Builder methods
 
@@ -646,6 +636,9 @@ detectDuplicateKeys(authBindings, userBindings);
 | `.health()` | Health snapshot + warnings (`ContainerHealth`). |
 | `.dispose()` | LIFO `onDestroy()` on all resolved instances. |
 | `[Symbol.asyncDispose]()` | Alias of `.dispose()` — enables `await using container = ...` (ES2023). |
+| `.size` | `readonly number` — count of registered providers. |
+| `.toJSON()` | Plain object of currently resolved (cached) deps. Does **not** trigger lazy resolution. Makes `JSON.stringify(container)` work. |
+| `[Symbol.iterator]()` | Yields `[key, value]` pairs for every registered provider. Triggers lazy resolution. Enables `for...of`, spread, `Array.from`. |
 
 ### Types
 
@@ -680,7 +673,7 @@ src/
     types/internal.ts            # IResolver, ICycleDetector, IDependencyTracker, IValidator
     errors.ts                    # 7 error classes + 2 warnings, each with hint + details
     lifecycle.ts                 # OnInit / OnDestroy (duck-typed)
-    validation.ts                # Validator, detectDuplicateKeys, Levenshtein
+    validation.ts                # Validator (configurable similarity threshold), Levenshtein
   infrastructure/                # mechanisms — depends on domain/ only
     resolver.ts                  # lazy resolution, singleton cache, parent chain
     cycle-detector.ts            # circular dependency detection

benchmarks/resolution.ts

@@ -0,0 +1,175 @@
+/**
+ * inwire — Resolution performance benchmarks
+ *
+ * Measures: build time, first resolution (cold), subsequent resolution (cached singleton),
+ * transient resolution (no cache), scope creation, and preload() time.
+ *
+ * Sizes: 10, 100, 1000 providers.
+ *
+ * Run: pnpm run bench
+ */
+
+import { performance } from 'node:perf_hooks';
+import { container, transient } from '../src/index.js';
+
+const SIZES = [10, 100, 1000] as const;
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function median(values: number[]): number {
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 !== 0
+    ? (sorted[mid] ?? 0)
+    : ((sorted[mid - 1] ?? 0) + (sorted[mid] ?? 0)) / 2;
+}
+
+function fmt(ns: number): string {
+  if (ns < 1_000) return `${ns.toFixed(1)} ns`;
+  if (ns < 1_000_000) return `${(ns / 1_000).toFixed(2)} µs`;
+  return `${(ns / 1_000_000).toFixed(2)} ms`;
+}
+
+/** Run fn() for `iters` iterations, return durations in nanoseconds. */
+function measure(fn: () => void, iters: number): number[] {
+  const results: number[] = [];
+  for (let i = 0; i < iters; i++) {
+    const start = performance.now();
+    fn();
+    results.push((performance.now() - start) * 1_000_000);
+  }
+  return results;
+}
+
+// ── Container factories ───────────────────────────────────────────────────────
+
+function buildFlat(n: number) {
+  let b = container() as any;
+  for (let i = 0; i < n; i++) {
+    b = b.add(`svc${i}`, () => ({ value: i }));
+  }
+  return b;
+}
+
+function buildTransient(n: number) {
+  let b = container() as any;
+  for (let i = 0; i < n; i++) {
+    b = b.add(
+      `svc${i}`,
+      transient(() => ({ value: i })),
+    );
+  }
+  return b;
+}
+
+// ── Benchmark suite ───────────────────────────────────────────────────────────
+
+interface BenchRow {
+  size: number;
+  'build (median)': string;
+  'cold resolve (median)': string;
+  'cached resolve (median)': string;
+  'transient resolve (median)': string;
+  'scope create (median)': string;
+  'preload (median)': string;
+}
+
+async function runForSize(n: number): Promise<BenchRow> {
+  const BUILD_ITERS = 100;
+  const RESOLVE_ITERS = 10_000;
+  const TRANSIENT_ITERS = 1_000;
+  const SCOPE_ITERS = 100;
+  const PRELOAD_ITERS = n === 1000 ? 10 : 100;
+
+  // ── Build time ──────────────────────────────────────────────────────────────
+  buildFlat(n).build(); // warm up
+  const buildTimes = measure(() => buildFlat(n).build(), BUILD_ITERS);
+
+  // ── Cold resolution — rebuilds container each time (includes build cost) ───
+  {
+    const c = buildFlat(n).build() as any;
+    void c.svc0; // warm up
+  }
+  const coldTimes = measure(() => {
+    const c = buildFlat(n).build() as any;
+    void c.svc0;
+  }, BUILD_ITERS);
+
+  // ── Cached singleton resolution ─────────────────────────────────────────────
+  const cachedC = buildFlat(n).build() as any;
+  void cachedC.svc0; // prime + warm up
+  void cachedC.svc0;
+  const cachedTimes = measure(() => {
+    void cachedC.svc0;
+  }, RESOLVE_ITERS);
+
+  // ── Transient resolution ────────────────────────────────────────────────────
+  const transientC = buildTransient(n).build() as any;
+  void transientC.svc0; // warm up
+  const transientTimes = measure(() => {
+    void transientC.svc0;
+  }, TRANSIENT_ITERS);
+
+  // ── Scope creation ──────────────────────────────────────────────────────────
+  const scopeBase = buildFlat(n).build();
+  void scopeBase.svc0; // ensure parent resolver is initialized
+  const scopeOverride = { scopedVal: () => ({ v: 1 }) } as any;
+  scopeBase.scope(scopeOverride); // warm up
+  const scopeTimes = measure(() => {
+    scopeBase.scope(scopeOverride);
+  }, SCOPE_ITERS);
+
+  // ── Preload ─────────────────────────────────────────────────────────────────
+  {
+    const c = buildFlat(n).build();
+    await c.preload(); // warm up
+  }
+  const preloadTimes: number[] = [];
+  for (let i = 0; i < PRELOAD_ITERS; i++) {
+    const c = buildFlat(n).build();
+    const start = performance.now();
+    await c.preload();
+    preloadTimes.push((performance.now() - start) * 1_000_000);
+  }
+
+  return {
+    size: n,
+    'build (median)': fmt(median(buildTimes)),
+    'cold resolve (median)': fmt(median(coldTimes)),
+    'cached resolve (median)': fmt(median(cachedTimes)),
+    'transient resolve (median)': fmt(median(transientTimes)),
+    'scope create (median)': fmt(median(scopeTimes)),
+    'preload (median)': fmt(median(preloadTimes)),
+  };
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  console.log('\n inwire — Resolution Performance Benchmarks');
+  console.log(' ==========================================\n');
+
+  const results: BenchRow[] = [];
+
+  for (const n of SIZES) {
+    process.stdout.write(` Running size=${n}...`);
+    const row = await runForSize(n);
+    results.push(row);
+    process.stdout.write(' done\n');
+  }
+
+  console.log('');
+  console.table(results);
+
+  console.log('\n Notes:');
+  console.log('  - All durations are median over multiple iterations (warmed up).');
+  console.log('  - "cold resolve" rebuilds the container each time — includes build overhead.');
+  console.log('  - "cached resolve" accesses an already-resolved singleton (pure Proxy overhead).');
+  console.log('  - "transient resolve" always creates a new instance (no cache).');
+  console.log('  - "preload" resolves all N providers eagerly in topological order.\n');
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

examples/07-deno.ts

@@ -0,0 +1,68 @@
+// Deno usage: deno run --allow-env examples/07-deno.ts
+// In Deno, replace the import below with: import { container, transient } from 'npm:inwire@^3';
+/**
+ * Example 07 — Deno runtime
+ *
+ * Showcases: container(), .add(), transient(), .build(), OnInit/OnDestroy lifecycle.
+ * Run locally in Node/Bun for type-checking; swap the specifier to `npm:inwire@^3` for Deno.
+ */
+import { container, transient } from '../src/index.js';
+
+// ── Services ────────────────────────────────────────────────────────────────
+
+interface ICache {
+  get(key: string): string | undefined;
+  set(key: string, value: string): void;
+}
+
+class InMemoryCache implements ICache {
+  private store = new Map<string, string>();
+
+  onInit() {
+    console.log('[Cache] ready');
+  }
+
+  onDestroy() {
+    this.store.clear();
+    console.log('[Cache] cleared');
+  }
+
+  get(key: string) {
+    return this.store.get(key);
+  }
+
+  set(key: string, value: string) {
+    this.store.set(key, value);
+  }
+}
+
+// ── Container ────────────────────────────────────────────────────────────────
+
+const app = container()
+  .add('config', { env: 'deno', version: '1.0.0' })
+  .add('cache', (): ICache => new InMemoryCache())
+  // transient: a new request context is created on each access
+  .addTransient(
+    'requestId',
+    transient(() => crypto.randomUUID()),
+  )
+  .build();
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  console.log(`env: ${app.config.env}`);
+
+  // OnInit triggered on first access
+  app.cache.set('greeting', 'hello from Deno');
+  console.log(`cache hit: ${app.cache.get('greeting')}`);
+
+  // transient: each access returns a fresh value
+  const id1 = app.requestId;
+  const id2 = app.requestId;
+  console.log(`transient ids differ: ${id1 !== id2}`);
+
+  await app.dispose();
+}
+
+main().catch(console.error);