inwire 2.1.2 → 2.1.3

package/README.md

@@ -106,7 +106,8 @@ app.db; // safe to use, fully initialized
 - **Smart errors** — 7 error types, each with `hint`, `details`, and fuzzy matching ("did you mean `userService`?"). Designed for both humans and LLMs to parse.
 - **Built-in introspection** — `inspect()` returns a serializable JSON graph. Feed it to an LLM, render it in a dashboard, or use `health()` to catch scope mismatches at runtime.
 - **Runtime agnostic** — pure ES2022. No decorators, no `reflect-metadata`, no compiler plugins. Works in Node.js, Deno, Bun, Cloudflare Workers, Vercel Edge, and browsers.
-- **Tiny** — 3.2 KB gzip, zero dependencies.
+- **Clean internals** — Clean Architecture, SOLID, single-responsibility files. Open any file, understand it, change it without fear.
+- **Tiny** — ~4 KB gzip, zero dependencies.
 
 ## Features
 
@@ -346,23 +347,31 @@ detectDuplicateKeys(authModule, userModule);
 
 ## Architecture
 
+Clean Architecture / SOLID internals. The dependency rule is enforced: `domain/` has zero imports from other layers.
+
 ```
 src/
-  index.ts                       # barrel export
-  domain/
-    types.ts                     # interfaces, types, RESERVED_KEYS
-    errors.ts                    # 7 error classes + ScopeMismatchWarning
-    lifecycle.ts                 # OnInit / OnDestroy interfaces
+  index.ts                       # public barrel — only file consumers import
+  domain/                        # pure contracts — no framework deps
+    types.ts                     # interfaces (IResolver, ICycleDetector, IDependencyTracker, IValidator)
+    errors.ts                    # 7 error classes + 2 warning types, each with hint + details
+    lifecycle.ts                 # OnInit / OnDestroy (duck-typed)
     validation.ts                # Validator, detectDuplicateKeys, Levenshtein
-  infrastructure/
-    resolver.ts                  # Resolver (Proxy handler, cache, cycle detection)
-    transient.ts                 # transient() marker
-  application/
-    container-builder.ts         # ContainerBuilder class + container() function
-    container-proxy.ts           # buildContainerProxy + scope/extend inline
+  infrastructure/                # low-level mechanisms — depends on domain/ only
+    resolver.ts                  # lazy resolution, singleton cache, parent chain
+    cycle-detector.ts            # circular dependency detection
+    dependency-tracker.ts        # tracking Proxy + dependency graph builder
+    transient.ts                 # transient() marker (Symbol-based)
+  application/                   # use cases + orchestration — depends on domain/ + infrastructure/
+    container-builder.ts         # fluent builder + container() factory
+    container-proxy.ts           # Proxy construction, scope/extend/reset
+    preloader.ts                 # topological sort (Kahn) + parallel onInit
+    disposer.ts                  # reverse-order onDestroy + cleanup
     introspection.ts             # inspect, describe, health, toString
 ```
 
+Each file has a single responsibility. The Resolver receives its collaborators (`CycleDetector`, `DependencyTracker`) via constructor injection — no internal `new`, no hidden coupling. `Preloader`, `Disposer`, and `Introspection` depend on the `IResolver` interface, not the concrete class.
+
 ## LLM / AI Integration
 
 This package ships with [llms.txt](https://llmstxt.org/) files for AI-assisted development:

package/dist/index.d.mts

@@ -1,3 +1,179 @@
+//#region src/domain/errors.d.ts
+/**
+ * Base class for all container errors.
+ * Every error includes a human-readable `hint` and structured `details`
+ * so that AI tools and developers can auto-correct issues.
+ *
+ * @example
+ * ```typescript
+ * try { container.userService; }
+ * catch (e) {
+ *   if (e instanceof ContainerError) {
+ *     console.log(e.hint);    // actionable fix
+ *     console.log(e.details); // structured context
+ *   }
+ * }
+ * ```
+ */
+declare abstract class ContainerError extends Error {
+  abstract readonly hint: string;
+  abstract readonly details: Record<string, unknown>;
+  constructor(message: string);
+}
+/**
+ * Thrown when a non-function value is passed in the deps definition.
+ *
+ * @example
+ * ```typescript
+ * container().add('apiKey', 'sk-123');
+ * // ContainerConfigError: 'apiKey' must be a factory function, got string.
+ * // hint: "Wrap it: apiKey: () => 'sk-123'"
+ * ```
+ */
+declare class ContainerConfigError extends ContainerError {
+  readonly hint: string;
+  readonly details: {
+    key: string;
+    actualType: string;
+  };
+  constructor(key: string, actualType: string);
+}
+/**
+ * Thrown when a reserved container method name is used as a dependency key.
+ *
+ * @example
+ * ```typescript
+ * container().add('inspect', () => 'foo');
+ * // ReservedKeyError: 'inspect' is a reserved container method.
+ * // hint: "Rename this dependency, e.g. 'inspectService' or 'dataInspector'."
+ * ```
+ */
+declare class ReservedKeyError extends ContainerError {
+  readonly hint: string;
+  readonly details: {
+    key: string;
+    reserved: string[];
+  };
+  constructor(key: string, reserved: readonly string[]);
+}
+/**
+ * Thrown when a dependency cannot be found during resolution.
+ * Includes fuzzy suggestion if a similar key exists.
+ *
+ * @example
+ * ```typescript
+ * container.userService;
+ * // ProviderNotFoundError: Cannot resolve 'userService': dependency 'userRepo' not found.
+ * // hint: "Did you mean 'userRepository'?"
+ * ```
+ */
+declare class ProviderNotFoundError extends ContainerError {
+  readonly hint: string;
+  readonly details: {
+    key: string;
+    chain: string[];
+    registered: string[];
+    suggestion: string | undefined;
+  };
+  constructor(key: string, chain: string[], registered: string[], suggestion?: string);
+}
+/**
+ * Thrown when a circular dependency is detected.
+ *
+ * @example
+ * ```typescript
+ * // CircularDependencyError: Circular dependency detected while resolving 'authService'.
+ * // Cycle: authService -> userService -> authService
+ * ```
+ */
+declare class CircularDependencyError extends ContainerError {
+  readonly hint: string;
+  readonly details: {
+    key: string;
+    chain: string[];
+    cycle: string;
+  };
+  constructor(key: string, chain: string[]);
+}
+/**
+ * Thrown when a factory function returns `undefined`.
+ *
+ * @example
+ * ```typescript
+ * container.db;
+ * // UndefinedReturnError: Factory 'db' returned undefined.
+ * // hint: "Did you forget a return statement?"
+ * ```
+ */
+declare class UndefinedReturnError extends ContainerError {
+  readonly hint: string;
+  readonly details: {
+    key: string;
+    chain: string[];
+  };
+  constructor(key: string, chain: string[]);
+}
+/**
+ * Thrown when a factory function throws an error during resolution.
+ * Wraps the original error with resolution context.
+ *
+ * @example
+ * ```typescript
+ * container.db;
+ * // FactoryError: Factory 'db' threw an error: "Connection refused"
+ * ```
+ */
+declare class FactoryError extends ContainerError {
+  readonly hint: string;
+  readonly details: {
+    key: string;
+    chain: string[];
+    originalError: string;
+  };
+  readonly originalError: unknown;
+  constructor(key: string, chain: string[], originalError: unknown);
+}
+/**
+ * Warning emitted when a singleton depends on a transient dependency.
+ * The transient value gets frozen inside the singleton — almost always a bug.
+ *
+ * @example
+ * ```typescript
+ * // ScopeMismatchWarning: Singleton 'userService' depends on transient 'requestId'.
+ * ```
+ */
+declare class ScopeMismatchWarning implements ContainerWarning {
+  readonly type: "scope_mismatch";
+  readonly message: string;
+  readonly hint: string;
+  readonly details: {
+    singleton: string;
+    transient: string;
+  };
+  constructor(singletonKey: string, transientKey: string);
+}
+/**
+ * Warning emitted when an async `onInit()` rejects during lazy resolution.
+ * The error is collected (not thrown) because lazy access is fire-and-forget.
+ * Use `preload()` to await and surface async init errors.
+ *
+ * @example
+ * ```typescript
+ * // health().warnings may include:
+ * // { type: 'async_init_error', message: "onInit() for 'db' rejected: connection refused" }
+ * ```
+ */
+declare class AsyncInitErrorWarning implements ContainerWarning {
+  readonly type: "async_init_error";
+  readonly message: string;
+  readonly hint: string;
+  readonly details: {
+    key: string;
+    error: string;
+  };
+  constructor(key: string, error: unknown);
+}
+//#endregion
 //#region src/domain/types.d.ts
 /**
  * A factory function that receives the container and returns an instance.
@@ -237,182 +413,6 @@ declare class ContainerBuilder<TContract extends Record<string, any> = Record<st
  */
 declare function container<T extends Record<string, any> = Record<string, unknown>>(): ContainerBuilder<T>;
 //#endregion
-//#region src/domain/errors.d.ts
-/**
- * Base class for all container errors.
- * Every error includes a human-readable `hint` and structured `details`
- * so that AI tools and developers can auto-correct issues.
- *
- * @example
- * ```typescript
- * try { container.userService; }
- * catch (e) {
- *   if (e instanceof ContainerError) {
- *     console.log(e.hint);    // actionable fix
- *     console.log(e.details); // structured context
- *   }
- * }
- * ```
- */
-declare abstract class ContainerError extends Error {
-  abstract readonly hint: string;
-  abstract readonly details: Record<string, unknown>;
-  constructor(message: string);
-}
-/**
- * Thrown when a non-function value is passed in the deps definition.
- *
- * @example
- * ```typescript
- * container().add('apiKey', 'sk-123');
- * // ContainerConfigError: 'apiKey' must be a factory function, got string.
- * // hint: "Wrap it: apiKey: () => 'sk-123'"
- * ```
- */
-declare class ContainerConfigError extends ContainerError {
-  readonly hint: string;
-  readonly details: {
-    key: string;
-    actualType: string;
-  };
-  constructor(key: string, actualType: string);
-}
-/**
- * Thrown when a reserved container method name is used as a dependency key.
- *
- * @example
- * ```typescript
- * container().add('inspect', () => 'foo');
- * // ReservedKeyError: 'inspect' is a reserved container method.
- * // hint: "Rename this dependency, e.g. 'inspectService' or 'dataInspector'."
- * ```
- */
-declare class ReservedKeyError extends ContainerError {
-  readonly hint: string;
-  readonly details: {
-    key: string;
-    reserved: string[];
-  };
-  constructor(key: string, reserved: readonly string[]);
-}
-/**
- * Thrown when a dependency cannot be found during resolution.
- * Includes fuzzy suggestion if a similar key exists.
- *
- * @example
- * ```typescript
- * container.userService;
- * // ProviderNotFoundError: Cannot resolve 'userService': dependency 'userRepo' not found.
- * // hint: "Did you mean 'userRepository'?"
- * ```
- */
-declare class ProviderNotFoundError extends ContainerError {
-  readonly hint: string;
-  readonly details: {
-    key: string;
-    chain: string[];
-    registered: string[];
-    suggestion: string | undefined;
-  };
-  constructor(key: string, chain: string[], registered: string[], suggestion?: string);
-}
-/**
- * Thrown when a circular dependency is detected.
- *
- * @example
- * ```typescript
- * // CircularDependencyError: Circular dependency detected while resolving 'authService'.
- * // Cycle: authService -> userService -> authService
- * ```
- */
-declare class CircularDependencyError extends ContainerError {
-  readonly hint: string;
-  readonly details: {
-    key: string;
-    chain: string[];
-    cycle: string;
-  };
-  constructor(key: string, chain: string[]);
-}
-/**
- * Thrown when a factory function returns `undefined`.
- *
- * @example
- * ```typescript
- * container.db;
- * // UndefinedReturnError: Factory 'db' returned undefined.
- * // hint: "Did you forget a return statement?"
- * ```
- */
-declare class UndefinedReturnError extends ContainerError {
-  readonly hint: string;
-  readonly details: {
-    key: string;
-    chain: string[];
-  };
-  constructor(key: string, chain: string[]);
-}
-/**
- * Thrown when a factory function throws an error during resolution.
- * Wraps the original error with resolution context.
- *
- * @example
- * ```typescript
- * container.db;
- * // FactoryError: Factory 'db' threw an error: "Connection refused"
- * ```
- */
-declare class FactoryError extends ContainerError {
-  readonly hint: string;
-  readonly details: {
-    key: string;
-    chain: string[];
-    originalError: string;
-  };
-  readonly originalError: unknown;
-  constructor(key: string, chain: string[], originalError: unknown);
-}
-/**
- * Warning emitted when a singleton depends on a transient dependency.
- * The transient value gets frozen inside the singleton — almost always a bug.
- *
- * @example
- * ```typescript
- * // ScopeMismatchWarning: Singleton 'userService' depends on transient 'requestId'.
- * ```
- */
-declare class ScopeMismatchWarning implements ContainerWarning {
-  readonly type: "scope_mismatch";
-  readonly message: string;
-  readonly hint: string;
-  readonly details: {
-    singleton: string;
-    transient: string;
-  };
-  constructor(singletonKey: string, transientKey: string);
-}
-/**
- * Warning emitted when an async `onInit()` rejects during lazy resolution.
- * The error is collected (not thrown) because lazy access is fire-and-forget.
- * Use `preload()` to await and surface async init errors.
- *
- * @example
- * ```typescript
- * // health().warnings may include:
- * // { type: 'async_init_error', message: "onInit() for 'db' rejected: connection refused" }
- * ```
- */
-declare class AsyncInitErrorWarning implements ContainerWarning {
-  readonly type: "async_init_error";
-  readonly message: string;
-  readonly hint: string;
-  readonly details: {
-    key: string;
-    error: string;
-  };
-  constructor(key: string, error: unknown);
-}
-//#endregion
 //#region src/domain/lifecycle.d.ts
 /**
  * Implement this interface (or just add an `onInit` method) to run

package/dist/index.mjs

@@ -1,4 +1,4 @@
 var e=class extends Error{constructor(e){super(e),this.name=this.constructor.name}},t=class extends e{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}}},n=class extends e{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]}}},r=class extends e{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}`);let s=`.add('${e}', (c) => new ${e[0].toUpperCase()}${e.slice(1)}(/* deps */))`;this.hint=r?`Did you mean '${r}'? Or add '${e}' to your container:\n  container()${s}`:`Add '${e}' to your container:\n  container()${s}`,this.details={key:e,chain:t,registered:n,suggestion:r}}},i=class extends e{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}}},a=class extends e{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}}},o=class extends e{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}},s=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}}},c=class{type=`async_init_error`;message;hint;details;constructor(e,t){let n=t instanceof Error?t.message:String(t);this.message=`onInit() for '${e}' rejected: ${n}`,this.hint=`Use preload('${e}') to await and handle async init errors.`,this.details={key:e,error:n}}};const l=[`scope`,`extend`,`module`,`preload`,`reset`,`inspect`,`describe`,`health`,`dispose`,`toString`];function u(e){return typeof e==`object`&&!!e&&`onInit`in e&&typeof e.onInit==`function`}function d(e){return typeof e==`object`&&!!e&&`onDestroy`in e&&typeof e.onDestroy==`function`}var f=class{validateConfig(e){for(let[r,i]of Object.entries(e)){if(l.includes(r))throw new n(r,l);if(typeof i!=`function`)throw new t(r,typeof i)}}suggestKey(e,t){let n,r=1/0;for(let i of t){let t=m(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 p(...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 m(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 h=Symbol.for(`inwire:transient`);function g(e){let t=(t=>e(t));return t[h]=!0,t}function _(e){return typeof e==`function`&&h in e&&e[h]===!0}var v=class{factories;cache;resolving=new Set;depGraph=new Map;warnings=[];validator=new f;initCalled=new Set;deferOnInit=!1;parent;name;constructor(e,t,n,r,i){this.factories=e,this.cache=t??new Map,this.parent=n,this.name=r,i&&(this.initCalled=new Set(i))}getName(){return this.name}resolve(e,t=[]){let n=this.factories.get(e);if(n&&!_(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 r(e,t,n,this.validator.suggestKey(e,n))}if(this.resolving.has(e))throw new i(e,[...t]);this.resolving.add(e);let l=[...t,e];try{let t=[],r=n(this.createTrackingProxy(t,l));if(r===void 0)throw new a(e,l);if(this.depGraph.set(e,t),!_(n))for(let n of t){let t=this.getFactory(n);t&&_(t)&&this.warnings.push(new s(e,n))}if(_(n)||this.cache.set(e,r),!this.deferOnInit&&!this.initCalled.has(e)&&u(r)){this.initCalled.add(e);let t=r.onInit();t instanceof Promise&&t.catch(t=>{this.warnings.push(new c(e,t))})}return r}catch(t){throw t instanceof i||t instanceof r||t instanceof a||t instanceof o?t:new o(e,l,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]}setDeferOnInit(e){this.deferOnInit=e}async callOnInit(e){if(this.initCalled.has(e)||!this.cache.has(e))return;let t=this.cache.get(e);u(t)&&await t.onInit(),this.initCalled.add(e)}clearInitState(...e){for(let t of e)this.initCalled.delete(t)}clearAllInitState(){this.initCalled.clear()}clearDepGraph(...e){for(let t of e)this.depGraph.delete(t)}clearAllDepGraph(){this.depGraph.clear()}clearWarnings(){this.warnings.length=0}clearWarningsForKeys(...e){let t=new Set(e),n=this.warnings.filter(e=>e.type===`async_init_error`?!t.has(e.details.key):e.type===`scope_mismatch`?!t.has(e.details.singleton)&&!t.has(e.details.transient):!0);this.warnings.length=0,this.warnings.push(...n)}getInitCalled(){return this.initCalled}createTrackingProxy(e,t){return new Proxy({},{get:(n,r)=>{if(typeof r==`symbol`)return;let i=r;return e.push(i),this.resolve(i,t)}})}getFactory(e){return this.factories.get(e)??this.parent?.getFactory(e)}},y=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:_(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:_(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 b=new f;function x(e,t){let n=new Map,r=new Map;for(let e of t)n.set(e,0);for(let i of t){let a=e.get(i)??[];for(let e of a)if(t.has(e)){n.set(i,(n.get(i)??0)+1);let t=r.get(e)??[];t.push(i),r.set(e,t)}}let i=[],a=[...t].filter(e=>n.get(e)===0);for(;a.length>0;){i.push(a);let e=[];for(let t of a)for(let i of r.get(t)??[]){let t=(n.get(i)??1)-1;n.set(i,t),t===0&&e.push(i)}a=e}if(i.reduce((e,t)=>e+t.length,0)<t.size){let e=new Set(i.flat()),n=[...t].filter(t=>!e.has(t));throw Error(`Incomplete topological sort: [${n.join(`, `)}] could not be ordered. This may indicate a cycle in the dependency graph.`)}return i}function S(e,t){let n=new y(e),r={scope:(n,r)=>{b.validateConfig(n);let i=new Map;for(let[e,t]of Object.entries(n))i.set(e,t);return S(new v(i,new Map,e,r?.name),t)},extend:n=>{b.validateConfig(n);let r=new Map(e.getFactories());for(let[e,t]of Object.entries(n))r.set(e,t);return S(new v(r,new Map(e.getCache()),void 0,void 0,e.getInitCalled()),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()],r=new Set(e.getCache().keys());e.setDeferOnInit(!0);try{for(let t of n)e.resolve(t)}catch(t){let n=e.getCache();for(let e of n.keys())r.has(e)||n.delete(e);throw t}finally{e.setDeferOnInit(!1)}let i=e.getDepGraph(),a=new Set,o=e=>{if(!a.has(e)){a.add(e);for(let t of i.get(e)??[])o(t)}};for(let e of n)o(e);let s=x(i,a),c=[];for(let t of s){let n=await Promise.allSettled(t.map(t=>e.callOnInit(t)));for(let e of n)e.status===`rejected`&&c.push(e.reason)}if(c.length===1)throw c[0];if(c.length>1)throw AggregateError(c,`preload() encountered ${c.length} onInit errors`)},reset:(...t)=>{let n=e.getCache();if(t.length===0)n.clear(),e.clearAllInitState(),e.clearAllDepGraph(),e.clearWarnings();else{for(let e of t)n.delete(e);e.clearInitState(...t),e.clearDepGraph(...t),e.clearWarningsForKeys(...t)}},inspect:()=>n.inspect(),describe:e=>n.describe(e),health:()=>n.health(),toString:()=>n.toString(),dispose:async()=>{let t=e.getCache(),n=[...t.entries()].reverse(),r=[];for(let[,e]of n)if(d(e))try{await e.onDestroy()}catch(e){r.push(e)}if(t.clear(),e.clearAllInitState(),e.clearAllDepGraph(),e.clearWarnings(),r.length===1)throw r[0];if(r.length>1)throw AggregateError(r,`dispose() encountered ${r.length} errors`)}};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 C=class e{factories=new Map;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,g(t)),this}addModule(e){return e(this)}_toRecord(){return Object.fromEntries(this.factories)}build(){return S(new v(new Map(this.factories)),()=>new e)}validateKey(e){if(l.includes(e))throw new n(e,l)}};function w(){return new C}export{c as AsyncInitErrorWarning,i as CircularDependencyError,C as ContainerBuilder,t as ContainerConfigError,e as ContainerError,o as FactoryError,r as ProviderNotFoundError,n as ReservedKeyError,s as ScopeMismatchWarning,a as UndefinedReturnError,w as container,p as detectDuplicateKeys,g as transient};
+`),this.details={singleton:e,transient:t}}},c=class{type=`async_init_error`;message;hint;details;constructor(e,t){let n=t instanceof Error?t.message:String(t);this.message=`onInit() for '${e}' rejected: ${n}`,this.hint=`Use preload('${e}') to await and handle async init errors.`,this.details={key:e,error:n}}};const l=[`scope`,`extend`,`module`,`preload`,`reset`,`inspect`,`describe`,`health`,`dispose`,`toString`];var u=class{resolving=new Set;enter(e){this.resolving.add(e)}leave(e){this.resolving.delete(e)}isResolving(e){return this.resolving.has(e)}},d=class{depGraph=new Map;createTrackingProxy(e,t,n){return new Proxy({},{get:(r,i)=>{if(typeof i==`symbol`)return;let a=i;return e.push(a),n(a,t)}})}getDepGraph(){return new Map(this.depGraph)}recordDeps(e,t){this.depGraph.set(e,t)}clearDepGraph(...e){for(let t of e)this.depGraph.delete(t)}clearAllDepGraph(){this.depGraph.clear()}};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(e){for(let[r,i]of Object.entries(e)){if(l.includes(r))throw new n(r,l);if(typeof i!=`function`)throw new t(r,typeof i)}}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]}const _=Symbol.for(`inwire:transient`);function v(e){let t=(t=>e(t));return t[_]=!0,t}function y(e){return typeof e==`function`&&_ in e&&e[_]===!0}var b=class{factories;cache;warnings=[];validator=new m;initCalled;deferOnInit=!1;parent;name;cycleDetector;dependencyTracker;constructor(e){this.factories=e.factories,this.cache=e.cache??new Map,this.parent=e.parent,this.name=e.name,this.initCalled=e.initCalled?new Set(e.initCalled):new Set,this.cycleDetector=e.cycleDetector,this.dependencyTracker=e.dependencyTracker}getName(){return this.name}resolve(e,t=[]){let n=this.factories.get(e);if(n&&!y(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 r(e,t,n,this.validator.suggestKey(e,n))}if(this.cycleDetector.isResolving(e))throw new i(e,[...t]);this.cycleDetector.enter(e);let l=[...t,e];try{let t=[],r=n(this.dependencyTracker.createTrackingProxy(t,l,(e,t)=>this.resolve(e,t)));if(r===void 0)throw new a(e,l);if(this.dependencyTracker.recordDeps(e,t),!y(n))for(let n of t){let t=this.getFactory(n);t&&y(t)&&this.warnings.push(new s(e,n))}if(y(n)||this.cache.set(e,r),!this.deferOnInit&&!this.initCalled.has(e)&&f(r)){this.initCalled.add(e);let t=r.onInit();t instanceof Promise&&t.catch(t=>{this.warnings.push(new c(e,t))})}return r}catch(t){throw t instanceof i||t instanceof r||t instanceof a||t instanceof o?t:new o(e,l,t)}finally{this.cycleDetector.leave(e)}}isResolved(e){return this.cache.has(e)}getDepGraph(){return this.dependencyTracker.getDepGraph()}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]}setDeferOnInit(e){this.deferOnInit=e}async callOnInit(e){if(this.initCalled.has(e)||!this.cache.has(e))return;let t=this.cache.get(e);f(t)&&await t.onInit(),this.initCalled.add(e)}clearInitState(...e){for(let t of e)this.initCalled.delete(t)}clearAllInitState(){this.initCalled.clear()}clearDepGraph(...e){this.dependencyTracker.clearDepGraph(...e)}clearAllDepGraph(){this.dependencyTracker.clearAllDepGraph()}clearWarnings(){this.warnings.length=0}clearWarningsForKeys(...e){let t=new Set(e),n=this.warnings.filter(e=>e.type===`async_init_error`?!t.has(e.details.key):e.type===`scope_mismatch`?!t.has(e.details.singleton)&&!t.has(e.details.transient):!0);this.warnings.length=0,this.warnings.push(...n)}getInitCalled(){return this.initCalled}getFactory(e){return this.factories.get(e)??this.parent?.getFactory(e)}},x=class{constructor(e){this.resolver=e}async dispose(){let e=this.resolver.getCache(),t=[...e.entries()].reverse(),n=[];for(let[,e]of t)if(p(e))try{await e.onDestroy()}catch(e){n.push(e)}if(e.clear(),this.resolver.clearAllInitState(),this.resolver.clearAllDepGraph(),this.resolver.clearWarnings(),n.length===1)throw n[0];if(n.length>1)throw AggregateError(n,`dispose() encountered ${n.length} errors`)}},S=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:y(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:y(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 C(e,t){let n=new Map,r=new Map;for(let e of t)n.set(e,0);for(let i of t){let a=e.get(i)??[];for(let e of a)if(t.has(e)){n.set(i,(n.get(i)??0)+1);let t=r.get(e)??[];t.push(i),r.set(e,t)}}let i=[],a=[...t].filter(e=>n.get(e)===0);for(;a.length>0;){i.push(a);let e=[];for(let t of a)for(let i of r.get(t)??[]){let t=(n.get(i)??1)-1;n.set(i,t),t===0&&e.push(i)}a=e}if(i.reduce((e,t)=>e+t.length,0)<t.size){let e=new Set(i.flat()),n=[...t].filter(t=>!e.has(t));throw Error(`Incomplete topological sort: [${n.join(`, `)}] could not be ordered. This may indicate a cycle in the dependency graph.`)}return i}var w=class{constructor(e){this.resolver=e}async preload(...e){let t=e.length>0?e:[...this.resolver.getFactories().keys()],n=new Set(this.resolver.getCache().keys());this.resolver.setDeferOnInit(!0);try{for(let e of t)this.resolver.resolve(e)}catch(e){let t=this.resolver.getCache();for(let e of t.keys())n.has(e)||t.delete(e);throw e}finally{this.resolver.setDeferOnInit(!1)}let r=this.resolver.getDepGraph(),i=new Set,a=e=>{if(!i.has(e)){i.add(e);for(let t of r.get(e)??[])a(t)}};for(let e of t)a(e);let o=C(r,i),s=[];for(let e of o){let t=await Promise.allSettled(e.map(e=>this.resolver.callOnInit(e)));for(let e of t)e.status===`rejected`&&s.push(e.reason)}if(s.length===1)throw s[0];if(s.length>1)throw AggregateError(s,`preload() encountered ${s.length} onInit errors`)}};const T=new m;function E(e,t){let n=new S(e),r=new w(e),i=new x(e),a={scope:(n,r)=>{T.validateConfig(n);let i=new Map;for(let[e,t]of Object.entries(n))i.set(e,t);return E(new b({factories:i,parent:e,name:r?.name,cycleDetector:new u,dependencyTracker:new d}),t)},extend:n=>{T.validateConfig(n);let r=new Map(e.getFactories());for(let[e,t]of Object.entries(n))r.set(e,t);return E(new b({factories:r,cache:new Map(e.getCache()),initCalled:e.getInitCalled(),cycleDetector:new u,dependencyTracker:new d}),t)},module:e=>{if(!t)throw Error(`module() is not available`);let n=e(t());return a.extend(n._toRecord())},preload:(...e)=>r.preload(...e),reset:(...t)=>{let n=e.getCache();if(t.length===0)n.clear(),e.clearAllInitState(),e.clearAllDepGraph(),e.clearWarnings();else{for(let e of t)n.delete(e);e.clearInitState(...t),e.clearDepGraph(...t),e.clearWarningsForKeys(...t)}},inspect:()=>n.inspect(),describe:e=>n.describe(e),health:()=>n.health(),toString:()=>n.toString(),dispose:()=>i.dispose()};return new Proxy({},{get(t,r){if(typeof r==`symbol`)return r===Symbol.toPrimitive||r===Symbol.toStringTag?()=>n.toString():void 0;let i=r;return i in a?a[i]:e.resolve(i)},has(t,n){if(typeof n==`symbol`)return!1;let r=n;return r in a||e.getFactories().has(r)||e.getAllRegisteredKeys().includes(r)},ownKeys(){return[...e.getAllRegisteredKeys(),...Object.keys(a)]},getOwnPropertyDescriptor(t,n){if(typeof n==`symbol`)return;let r=n;if(r in a||e.getFactories().has(r)||e.getAllRegisteredKeys().includes(r))return{configurable:!0,enumerable:!(r in a),writable:!1}}})}var D=class e{factories=new Map;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,v(t)),this}addModule(e){return e(this)}_toRecord(){return Object.fromEntries(this.factories)}build(){return E(new b({factories:new Map(this.factories),cycleDetector:new u,dependencyTracker:new d}),()=>new e)}validateKey(e){if(l.includes(e))throw new n(e,l)}};function O(){return new D}export{c as AsyncInitErrorWarning,i as CircularDependencyError,D as ContainerBuilder,t as ContainerConfigError,e as ContainerError,o as FactoryError,r as ProviderNotFoundError,n as ReservedKeyError,s as ScopeMismatchWarning,a as UndefinedReturnError,O as container,h as detectDuplicateKeys,v as transient};
 //# sourceMappingURL=index.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inwire",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "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",