inwire 1.0.0

package/dist/index.cjs

@@ -0,0 +1,590 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CircularDependencyError: () => CircularDependencyError,
+  ContainerConfigError: () => ContainerConfigError,
+  ContainerError: () => ContainerError,
+  FactoryError: () => FactoryError,
+  ProviderNotFoundError: () => ProviderNotFoundError,
+  ReservedKeyError: () => ReservedKeyError,
+  ScopeMismatchWarning: () => ScopeMismatchWarning,
+  UndefinedReturnError: () => UndefinedReturnError,
+  createContainer: () => createContainer,
+  detectDuplicateKeys: () => detectDuplicateKeys,
+  transient: () => transient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/domain/lifecycle.ts
+function hasOnInit(value) {
+  return value !== null && typeof value === "object" && "onInit" in value && typeof value.onInit === "function";
+}
+function hasOnDestroy(value) {
+  return value !== null && typeof value === "object" && "onDestroy" in value && typeof value.onDestroy === "function";
+}
+
+// src/domain/types.ts
+var RESERVED_KEYS = [
+  "scope",
+  "extend",
+  "preload",
+  "reset",
+  "inspect",
+  "describe",
+  "health",
+  "dispose",
+  "toString"
+];
+
+// src/domain/errors.ts
+var ContainerError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+};
+var ContainerConfigError = class extends ContainerError {
+  hint;
+  details;
+  constructor(key, actualType) {
+    super(`'${key}' must be a factory function, got ${actualType}.`);
+    this.hint = `Wrap it: ${key}: () => ${JSON.stringify(key === key ? `<your ${actualType} value>` : key)}`;
+    this.details = { key, actualType };
+  }
+};
+var ReservedKeyError = class extends ContainerError {
+  hint;
+  details;
+  constructor(key, reserved) {
+    super(`'${key}' is a reserved container method.`);
+    this.hint = `Rename this dependency, e.g. '${key}Service' or 'my${key[0].toUpperCase()}${key.slice(1)}'.`;
+    this.details = { key, reserved: [...reserved] };
+  }
+};
+var ProviderNotFoundError = class extends ContainerError {
+  hint;
+  details;
+  constructor(key, chain, registered, suggestion) {
+    const chainStr = chain.length > 0 ? `
+
+Resolution chain: ${[...chain, `${key} (not found)`].join(" -> ")}` : "";
+    const registeredStr = `
+Registered keys: [${registered.join(", ")}]`;
+    const suggestionStr = suggestion ? `
+
+Did you mean '${suggestion}'?` : "";
+    super(
+      `Cannot resolve '${chain[0] ?? key}': dependency '${key}' not found.${chainStr}${registeredStr}${suggestionStr}`
+    );
+    this.hint = suggestion ? `Did you mean '${suggestion}'? Or add '${key}' to your container:
+  createContainer({
+    ...existing,
+    ${key}: (c) => new Your${key[0].toUpperCase()}${key.slice(1)}(/* deps */),
+  });` : `Add '${key}' to your container:
+  createContainer({
+    ...existing,
+    ${key}: (c) => new Your${key[0].toUpperCase()}${key.slice(1)}(/* deps */),
+  });`;
+    this.details = { key, chain, registered, suggestion };
+  }
+};
+var CircularDependencyError = class extends ContainerError {
+  hint;
+  details;
+  constructor(key, chain) {
+    const cycle = [...chain, key].join(" -> ");
+    super(
+      `Circular dependency detected while resolving '${chain[0]}'.
+
+Cycle: ${cycle}`
+    );
+    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("\n");
+    this.details = { key, chain, cycle };
+  }
+};
+var UndefinedReturnError = class extends ContainerError {
+  hint;
+  details;
+  constructor(key, chain) {
+    const chainStr = chain.length > 1 ? `
+
+Resolution chain: ${chain.join(" -> ")}` : "";
+    super(`Factory '${key}' returned undefined.${chainStr}`);
+    this.hint = "Your factory function returned undefined. Did you forget a return statement?";
+    this.details = { key, chain };
+  }
+};
+var FactoryError = class extends ContainerError {
+  hint;
+  details;
+  originalError;
+  constructor(key, chain, originalError) {
+    const origMessage = originalError instanceof Error ? originalError.message : String(originalError);
+    const chainStr = chain.length > 1 ? `
+
+Resolution chain: ${[...chain.slice(0, -1), `${key} (factory threw)`].join(" -> ")}` : "";
+    super(`Factory '${key}' threw an error: "${origMessage}"${chainStr}`);
+    this.hint = `Check the factory function for '${key}'. The error occurred during instantiation.`;
+    this.details = { key, chain, originalError: origMessage };
+    this.originalError = originalError;
+  }
+};
+var ScopeMismatchWarning = class {
+  type = "scope_mismatch";
+  message;
+  hint;
+  details;
+  constructor(singletonKey, transientKey) {
+    this.message = `Singleton '${singletonKey}' depends on transient '${transientKey}'.`;
+    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 '${singletonKey}' transient too: transient((c) => new ${singletonKey[0].toUpperCase()}${singletonKey.slice(1)}(c.${transientKey}))`,
+      `  2. Make '${transientKey}' singleton if it doesn't need to change`,
+      `  3. Inject a factory instead: ${transientKey}Factory: () => () => <your value>`
+    ].join("\n");
+    this.details = { singleton: singletonKey, transient: transientKey };
+  }
+};
+
+// src/domain/validation.ts
+var Validator = class {
+  /**
+   * Validates that all values in the config are factory functions
+   * and that no reserved keys are used.
+   */
+  validateConfig(config) {
+    for (const [key, value] of Object.entries(config)) {
+      if (RESERVED_KEYS.includes(key)) {
+        throw new ReservedKeyError(key, RESERVED_KEYS);
+      }
+      if (typeof value !== "function") {
+        throw new ContainerConfigError(key, typeof value);
+      }
+    }
+  }
+  /**
+   * Finds the closest registered key to a missing key using Levenshtein distance.
+   * Returns `undefined` if no close match is found (threshold: 3).
+   *
+   * @example
+   * ```typescript
+   * validator.suggestKey('userRepo', ['userRepository', 'logger', 'db']);
+   * // 'userRepository'
+   * ```
+   */
+  suggestKey(key, registered) {
+    let bestMatch;
+    let bestDistance = Infinity;
+    for (const candidate of registered) {
+      const distance = levenshtein(key, candidate);
+      if (distance < bestDistance) {
+        bestDistance = distance;
+        bestMatch = candidate;
+      }
+    }
+    if (!bestMatch) return void 0;
+    const maxLen = Math.max(key.length, bestMatch.length);
+    const similarity = 1 - bestDistance / maxLen;
+    return similarity >= 0.5 ? bestMatch : void 0;
+  }
+};
+function detectDuplicateKeys(...modules) {
+  const seen = /* @__PURE__ */ new Map();
+  const duplicates = [];
+  for (const mod of modules) {
+    for (const key of Object.keys(mod)) {
+      const count = (seen.get(key) ?? 0) + 1;
+      seen.set(key, count);
+      if (count === 2) {
+        duplicates.push(key);
+      }
+    }
+  }
+  return duplicates;
+}
+function levenshtein(a, b) {
+  const la = a.length;
+  const lb = b.length;
+  if (la === 0) return lb;
+  if (lb === 0) return la;
+  let prev = new Array(lb + 1);
+  let curr = new Array(lb + 1);
+  for (let j = 0; j <= lb; j++) prev[j] = j;
+  for (let i = 1; i <= la; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= lb; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(
+        prev[j] + 1,
+        // deletion
+        curr[j - 1] + 1,
+        // insertion
+        prev[j - 1] + cost
+        // substitution
+      );
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[lb];
+}
+
+// src/infrastructure/transient.ts
+var TRANSIENT_MARKER = /* @__PURE__ */ Symbol.for("inwire:transient");
+function transient(factory) {
+  const wrapper = ((container) => factory(container));
+  wrapper[TRANSIENT_MARKER] = true;
+  return wrapper;
+}
+function isTransient(factory) {
+  return typeof factory === "function" && TRANSIENT_MARKER in factory && factory[TRANSIENT_MARKER] === true;
+}
+
+// src/infrastructure/proxy-handler.ts
+var Resolver = class {
+  factories;
+  cache;
+  resolving = /* @__PURE__ */ new Set();
+  depGraph = /* @__PURE__ */ new Map();
+  warnings = [];
+  validator = new Validator();
+  /** Parent resolver for scoped containers */
+  parent;
+  /** Optional name for debugging/introspection */
+  name;
+  constructor(factories, cache, parent, name) {
+    this.factories = factories;
+    this.cache = cache ?? /* @__PURE__ */ new Map();
+    this.parent = parent;
+    this.name = name;
+  }
+  getName() {
+    return this.name;
+  }
+  /**
+   * Resolves a dependency by key.
+   * - Returns cached singleton if available
+   * - Detects circular dependencies
+   * - Tracks dependencies accessed by each factory
+   * - Calls `onInit()` on newly created instances
+   * - Emits scope mismatch warnings
+   */
+  resolve(key, chain = []) {
+    const factory = this.factories.get(key);
+    if (factory && !isTransient(factory) && this.cache.has(key)) {
+      return this.cache.get(key);
+    }
+    if (!factory) {
+      if (this.parent) {
+        return this.parent.resolve(key, chain);
+      }
+      const allKeys = this.getAllRegisteredKeys();
+      const suggestion = this.validator.suggestKey(key, allKeys);
+      throw new ProviderNotFoundError(key, chain, allKeys, suggestion);
+    }
+    if (this.resolving.has(key)) {
+      throw new CircularDependencyError(key, [...chain]);
+    }
+    this.resolving.add(key);
+    const currentChain = [...chain, key];
+    try {
+      const deps = [];
+      const trackingProxy = this.createTrackingProxy(key, deps, currentChain);
+      const instance = factory(trackingProxy);
+      if (instance === void 0) {
+        throw new UndefinedReturnError(key, currentChain);
+      }
+      this.depGraph.set(key, deps);
+      if (!isTransient(factory)) {
+        for (const dep of deps) {
+          const depFactory = this.getFactory(dep);
+          if (depFactory && isTransient(depFactory)) {
+            this.warnings.push(new ScopeMismatchWarning(key, dep));
+          }
+        }
+      }
+      if (!isTransient(factory)) {
+        this.cache.set(key, instance);
+      }
+      if (hasOnInit(instance)) {
+        const initResult = instance.onInit();
+        if (initResult instanceof Promise) {
+          initResult.catch(() => {
+          });
+        }
+      }
+      return instance;
+    } catch (error) {
+      if (error instanceof CircularDependencyError || error instanceof ProviderNotFoundError || error instanceof UndefinedReturnError || error instanceof FactoryError) {
+        throw error;
+      }
+      throw new FactoryError(key, currentChain, error);
+    } finally {
+      this.resolving.delete(key);
+    }
+  }
+  isResolved(key) {
+    return this.cache.has(key);
+  }
+  getDepGraph() {
+    return new Map(this.depGraph);
+  }
+  getResolvedKeys() {
+    return [...this.cache.keys()];
+  }
+  getFactories() {
+    return this.factories;
+  }
+  getCache() {
+    return this.cache;
+  }
+  getWarnings() {
+    return [...this.warnings];
+  }
+  getAllRegisteredKeys() {
+    const keys = new Set(this.factories.keys());
+    if (this.parent) {
+      for (const key of this.parent.getAllRegisteredKeys()) {
+        keys.add(key);
+      }
+    }
+    return [...keys];
+  }
+  /**
+   * Creates a Proxy that records which keys a factory accesses.
+   * This builds the dependency graph automatically.
+   */
+  createTrackingProxy(factoryKey, deps, chain) {
+    return new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (typeof prop === "symbol") return void 0;
+          const depKey = prop;
+          deps.push(depKey);
+          return this.resolve(depKey, chain);
+        }
+      }
+    );
+  }
+  /** Look up a factory in this resolver or its parent chain. */
+  getFactory(key) {
+    return this.factories.get(key) ?? this.parent?.getFactory(key);
+  }
+};
+
+// src/application/introspection.ts
+var Introspection = class {
+  constructor(resolver) {
+    this.resolver = resolver;
+  }
+  /**
+   * Returns the full dependency graph as a serializable JSON object.
+   */
+  inspect() {
+    const providers = {};
+    for (const [key, factory] of this.resolver.getFactories()) {
+      providers[key] = {
+        key,
+        resolved: this.resolver.isResolved(key),
+        deps: this.resolver.getDepGraph().get(key) ?? [],
+        scope: isTransient(factory) ? "transient" : "singleton"
+      };
+    }
+    const name = this.resolver.getName();
+    return name ? { name, providers } : { providers };
+  }
+  /**
+   * Returns detailed information about a specific provider.
+   */
+  describe(key) {
+    const factory = this.resolver.getFactories().get(key);
+    if (!factory) {
+      return { key, resolved: false, deps: [], scope: "singleton" };
+    }
+    return {
+      key,
+      resolved: this.resolver.isResolved(key),
+      deps: this.resolver.getDepGraph().get(key) ?? [],
+      scope: isTransient(factory) ? "transient" : "singleton"
+    };
+  }
+  /**
+   * Returns container health status with warnings.
+   */
+  health() {
+    const allKeys = [...this.resolver.getFactories().keys()];
+    const resolvedKeys = this.resolver.getResolvedKeys();
+    const resolvedSet = new Set(resolvedKeys);
+    const warnings = this.resolver.getWarnings().map((w) => ({
+      type: w.type,
+      message: w.message,
+      details: w.details
+    }));
+    return {
+      totalProviders: allKeys.length,
+      resolved: resolvedKeys,
+      unresolved: allKeys.filter((k) => !resolvedSet.has(k)),
+      warnings
+    };
+  }
+  /**
+   * Returns a human-readable representation of the container.
+   */
+  toString() {
+    const parts = [];
+    for (const [key] of this.resolver.getFactories()) {
+      const resolved = this.resolver.isResolved(key);
+      const deps = this.resolver.getDepGraph().get(key);
+      const depsStr = deps && deps.length > 0 ? ` -> [${deps.join(", ")}]` : "";
+      const status = resolved ? "(resolved)" : "(pending)";
+      parts.push(`${key}${depsStr} ${status}`);
+    }
+    const name = this.resolver.getName();
+    const label = name ? `Scope(${name})` : "Container";
+    return `${label} { ${parts.join(", ")} }`;
+  }
+};
+
+// src/application/scope.ts
+function createScope(parentResolver, extra, options) {
+  const childFactories = /* @__PURE__ */ new Map();
+  for (const [key, factory] of Object.entries(extra)) {
+    childFactories.set(key, factory);
+  }
+  const childResolver = new Resolver(childFactories, /* @__PURE__ */ new Map(), parentResolver, options?.name);
+  return buildContainerProxy(childResolver);
+}
+
+// src/application/create-container.ts
+var validator = new Validator();
+function createContainer(defs) {
+  validator.validateConfig(defs);
+  const factories = /* @__PURE__ */ new Map();
+  for (const [key, factory] of Object.entries(defs)) {
+    factories.set(key, factory);
+  }
+  const resolver = new Resolver(factories);
+  return buildContainerProxy(resolver);
+}
+function buildContainerProxy(resolver) {
+  const introspection = new Introspection(resolver);
+  const methods = {
+    scope: (extra, options) => createScope(resolver, extra, options),
+    extend: (extra) => {
+      validator.validateConfig(extra);
+      const merged = new Map(resolver.getFactories());
+      for (const [key, factory] of Object.entries(extra)) {
+        merged.set(key, factory);
+      }
+      const newResolver = new Resolver(merged, new Map(resolver.getCache()));
+      return buildContainerProxy(newResolver);
+    },
+    preload: async (...keys) => {
+      const toResolve = keys.length > 0 ? keys : [...resolver.getFactories().keys()];
+      for (const key of toResolve) {
+        resolver.resolve(key);
+      }
+    },
+    reset: (...keys) => {
+      const cache = resolver.getCache();
+      for (const key of keys) {
+        cache.delete(key);
+      }
+    },
+    inspect: () => introspection.inspect(),
+    describe: (key) => introspection.describe(key),
+    health: () => introspection.health(),
+    toString: () => introspection.toString(),
+    dispose: async () => {
+      const cache = resolver.getCache();
+      const entries = [...cache.entries()].reverse();
+      for (const [, instance] of entries) {
+        if (hasOnDestroy(instance)) {
+          await instance.onDestroy();
+        }
+      }
+      cache.clear();
+    }
+  };
+  const proxy = new Proxy(
+    {},
+    {
+      get(_target, prop) {
+        if (typeof prop === "symbol") {
+          if (prop === Symbol.toPrimitive || prop === Symbol.toStringTag) {
+            return () => introspection.toString();
+          }
+          return void 0;
+        }
+        const key = prop;
+        if (key in methods) {
+          return methods[key];
+        }
+        return resolver.resolve(key);
+      },
+      has(_target, prop) {
+        if (typeof prop === "symbol") return false;
+        const key = prop;
+        return key in methods || resolver.getFactories().has(key) || resolver.getAllRegisteredKeys().includes(key);
+      },
+      ownKeys() {
+        return [...resolver.getAllRegisteredKeys(), ...Object.keys(methods)];
+      },
+      getOwnPropertyDescriptor(_target, prop) {
+        if (typeof prop === "symbol") return void 0;
+        const key = prop;
+        if (key in methods || resolver.getFactories().has(key) || resolver.getAllRegisteredKeys().includes(key)) {
+          return {
+            configurable: true,
+            enumerable: key in methods ? false : true,
+            writable: false
+          };
+        }
+        return void 0;
+      }
+    }
+  );
+  return proxy;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CircularDependencyError,
+  ContainerConfigError,
+  ContainerError,
+  FactoryError,
+  ProviderNotFoundError,
+  ReservedKeyError,
+  ScopeMismatchWarning,
+  UndefinedReturnError,
+  createContainer,
+  detectDuplicateKeys,
+  transient
+});
+//# sourceMappingURL=index.cjs.map