@illuma/core 1.0.0

package/dist/testkit.cjs

@@ -0,0 +1,995 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+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/testkit.ts
+var testkit_exports = {};
+__export(testkit_exports, {
+  createTestFactory: () => createTestFactory
+});
+module.exports = __toCommonJS(testkit_exports);
+
+// src/lib/errors.ts
+var InjectionError = class _InjectionError extends Error {
+  static {
+    __name(this, "InjectionError");
+  }
+  code;
+  constructor(code, message) {
+    super(`[i${code}] ${message}`), this.code = code;
+    this.name = "InjectionError";
+  }
+  // Provider errors
+  static duplicate(token) {
+    return new _InjectionError(100, `Duplicate provider for token "${token.toString()}" detected.`);
+  }
+  static duplicateFactory(token) {
+    return new _InjectionError(101, `Tried to re-provide factory for token "${token.toString()}" detected.`);
+  }
+  static invalidCtor(ctor) {
+    return new _InjectionError(102, `Cannot use constructor for token "${ctor.name}". Please make sure to use @nodeInjectable() decorator`);
+  }
+  static invalidProvider(provider) {
+    return new _InjectionError(103, `Cannot use provider as it is neither a NodeToken nor MultiNodeToken nor a valid constructor.:
+${provider}`);
+  }
+  // Alias errors
+  static invalidAlias(alias) {
+    const aliasStr = typeof alias === "function" ? alias.name || "Unknown" : String(alias);
+    return new _InjectionError(200, `Invalid alias target "${aliasStr}". Alias must be a NodeToken, MultiNodeToken, or a class decorated with @NodeInjectable().`);
+  }
+  static loopAlias(alias) {
+    return new _InjectionError(201, `Token "${alias.toString()}" cannot alias itself in a loop.`);
+  }
+  // Bootstrap errors
+  static notBootstrapped() {
+    return new _InjectionError(300, "Cannot retrieve providers before the container has been bootstrapped.");
+  }
+  static bootstrapped() {
+    return new _InjectionError(301, "Cannot modify providers after the container has been bootstrapped.");
+  }
+  static doubleBootstrap() {
+    return new _InjectionError(302, "Container has already been bootstrapped and cannot be bootstrapped again.");
+  }
+  // Retrieval errors
+  static notFound(token) {
+    return new _InjectionError(400, `No provider found for "${token.toString()}".`);
+  }
+  static circularDependency(provider, path) {
+    const providerStr = provider instanceof NodeBase ? provider.toString() : provider.name;
+    const pathStr = path.map((p) => p instanceof NodeBase ? p.toString() : p.name).join(" -> ");
+    return new _InjectionError(401, `Circular dependency detected while resolving "${providerStr}":
+${pathStr}`);
+  }
+  // Instantiation errors
+  static untracked(token, parent) {
+    const tokenStr = token instanceof NodeBase ? token.toString() : token.name;
+    const parentStr = parent instanceof NodeBase ? parent.toString() : parent.name;
+    return new _InjectionError(500, `Cannot instantiate ${parentStr} because it depends on untracked injection ${tokenStr}. Please make sure all injections are properly tracked.`);
+  }
+  static outsideContext(token) {
+    const tokenStr = token instanceof NodeBase ? token.toString() : token.name;
+    return new _InjectionError(501, `Cannot inject "${tokenStr}" outside of an injection context.`);
+  }
+  static calledUtilsOutsideContext() {
+    return new _InjectionError(502, "Cannot call injection utilities outside of an injection context.");
+  }
+  static instanceAccessFailed(token) {
+    return new _InjectionError(503, `Failed to access instance for token "${token.toString()}". It was not properly instantiated.`);
+  }
+  static accessFailed() {
+    return new _InjectionError(504, "Failed to access the requested instance due to an unknown error.");
+  }
+};
+
+// src/lib/api/token.ts
+var NodeBase = class {
+  static {
+    __name(this, "NodeBase");
+  }
+  name;
+  opts;
+  constructor(name, opts) {
+    this.name = name;
+    this.opts = opts;
+  }
+  /** Provides this token with a value */
+  withValue(value) {
+    return {
+      provide: this,
+      value
+    };
+  }
+  /** Provides this token using a factory function */
+  withFactory(factory) {
+    return {
+      provide: this,
+      factory
+    };
+  }
+  /** Provides this token using a class constructor */
+  withClass(ctor) {
+    return {
+      provide: this,
+      useClass: ctor
+    };
+  }
+  /** Creates an alias to another token */
+  withAlias(alias) {
+    return {
+      provide: this,
+      alias
+    };
+  }
+  toString() {
+    return `Token[${this.name}]`;
+  }
+};
+var NodeToken = class extends NodeBase {
+  static {
+    __name(this, "NodeToken");
+  }
+  multi = false;
+  toString() {
+    return `NodeToken[${this.name}]`;
+  }
+};
+var MultiNodeToken = class extends NodeBase {
+  static {
+    __name(this, "MultiNodeToken");
+  }
+  multi = true;
+  toString() {
+    return `MultiNodeToken[${this.name}]`;
+  }
+};
+function isNodeBase(specimen) {
+  return specimen instanceof NodeToken || specimen instanceof MultiNodeToken;
+}
+__name(isNodeBase, "isNodeBase");
+function extractToken(provider, isAlias = false) {
+  let token = null;
+  if (isInjectable(provider)) {
+    token = getInjectableToken(provider);
+  } else if (isNodeBase(provider)) token = provider;
+  if (!token || !isNodeBase(token)) {
+    if (isAlias) throw InjectionError.invalidAlias(provider);
+    throw InjectionError.invalidProvider(JSON.stringify(provider));
+  }
+  return token;
+}
+__name(extractToken, "extractToken");
+
+// src/lib/api/decorator.ts
+var INJECTION_SYMBOL = Symbol("Injectable");
+function isInjectable(ctor) {
+  return typeof ctor === "function" && isConstructor(ctor) && INJECTION_SYMBOL in ctor && ctor[INJECTION_SYMBOL] instanceof NodeToken;
+}
+__name(isInjectable, "isInjectable");
+function getInjectableToken(ctor) {
+  return ctor[INJECTION_SYMBOL];
+}
+__name(getInjectableToken, "getInjectableToken");
+function isConstructor(fn) {
+  return typeof fn === "function" && fn.prototype && fn.prototype.constructor === fn;
+}
+__name(isConstructor, "isConstructor");
+
+// src/lib/plugins/core/plugin-container.ts
+var Illuma = class _Illuma {
+  static {
+    __name(this, "Illuma");
+  }
+  static _diagnostics = [];
+  static _scanners = [];
+  /** @internal */
+  static get contextScanners() {
+    return _Illuma._scanners;
+  }
+  /**
+  * Extends the diagnostics with a new diagnostics module.
+  * These will be run on diagnostics reports after container bootstrap.
+  *
+  * @param m - The diagnostics module instance to add
+  */
+  static extendDiagnostics(m) {
+    _Illuma._diagnostics.push(m);
+  }
+  /**
+  * Extends the context scanners with a new context scanner.
+  * These will be run in injection context scans to detect additional injections (alongside `nodeInject` calls).
+  *
+  * @param scanner - The context scanner instance to add
+  */
+  static extendContextScanner(scanner) {
+    _Illuma._scanners.push(scanner);
+  }
+  static onReport(report) {
+    for (const diag of _Illuma._diagnostics) diag.onReport(report);
+  }
+};
+
+// src/lib/context/context.ts
+var InjectionContext = class _InjectionContext {
+  static {
+    __name(this, "InjectionContext");
+  }
+  static contextOpen = false;
+  static _calls = /* @__PURE__ */ new Set();
+  static injector = null;
+  static _scanners = Illuma.contextScanners;
+  /**
+  * Adds a dependency to the current injection context.
+  * Called by `nodeInject` when a dependency is requested.
+  *
+  * @param node - The injection node representing the dependency
+  * @throws {InjectionError} If called outside of an active injection context
+  */
+  static addDep(node) {
+    if (!_InjectionContext.contextOpen) {
+      throw InjectionError.calledUtilsOutsideContext();
+    }
+    _InjectionContext._calls.add(node);
+  }
+  /**
+  * Opens a new injection context.
+  * Resets the calls set and sets the injector if provided.
+  *
+  * @param injector - Optional injector function to use for resolving dependencies
+  */
+  /**
+  * Scans a factory function for dependencies.
+  * Executes the factory in a dry-run mode to capture `nodeInject` calls.
+  * Also runs registered context scanners.
+  *
+  * @param factory - The factory function to scan
+  * @returns A set of detected injection nodes
+  */
+  static open(injector) {
+    _InjectionContext._calls.clear();
+    _InjectionContext.contextOpen = true;
+    _InjectionContext.injector = injector || null;
+  }
+  static scan(factory) {
+    if (typeof factory !== "function") return /* @__PURE__ */ new Set();
+    _InjectionContext.open();
+    try {
+      factory();
+    } catch {
+    }
+    const scanners = _InjectionContext._scanners;
+    for (const scanner of scanners) {
+      const scanned = scanner.scan(factory);
+      for (const node of scanned) _InjectionContext._calls.add(node);
+    }
+    const injections = _InjectionContext.closeAndReport();
+    return injections;
+  }
+  static instantiate(factory, injector) {
+    _InjectionContext.open(injector);
+    try {
+      return factory();
+    } finally {
+      _InjectionContext.closeAndReport();
+    }
+  }
+  static closeAndReport() {
+    const calls = new Set(_InjectionContext._calls);
+    _InjectionContext.contextOpen = false;
+    _InjectionContext._calls.clear();
+    _InjectionContext.injector = null;
+    return calls;
+  }
+};
+
+// src/lib/api/injection.ts
+function nodeInject(provider, options) {
+  let token = provider;
+  if (isInjectable(provider)) token = getInjectableToken(provider);
+  if (!InjectionContext.contextOpen) {
+    throw InjectionError.outsideContext(token);
+  }
+  if (!isNodeBase(token)) throw InjectionError.invalidProvider(String(token));
+  const injection = {
+    token,
+    optional: options?.optional ?? false
+  };
+  InjectionContext.addDep(injection);
+  if (InjectionContext.injector) {
+    return InjectionContext.injector(token, options?.optional);
+  }
+  return injection;
+}
+__name(nodeInject, "nodeInject");
+
+// src/lib/plugins/diagnostics/default-impl.ts
+var DiagnosticsDefaultReporter = class {
+  static {
+    __name(this, "DiagnosticsDefaultReporter");
+  }
+  onReport(report) {
+    console.log("[Illuma] \u{1F9F9} Diagnostics:");
+    console.log(`  Total: ${report.totalNodes} node(s)`);
+    console.log(`  ${report.unusedNodes.length} were not used while bootstrap:`);
+    for (const node of report.unusedNodes) console.log(`    - ${node.toString()}`);
+  }
+};
+
+// src/lib/provider/extractor.ts
+function extractProvider(provider) {
+  if ("value" in provider) return () => provider.value;
+  if ("factory" in provider) return provider.factory;
+  if ("useClass" in provider) return () => new provider.useClass();
+  if ("alias" in provider) return extractToken(provider.alias, true);
+  throw InjectionError.invalidProvider(JSON.stringify(provider));
+}
+__name(extractProvider, "extractProvider");
+
+// src/lib/provider/proto.ts
+var ProtoNodeSingle = class {
+  static {
+    __name(this, "ProtoNodeSingle");
+  }
+  // Metadata
+  token;
+  injections;
+  // Instantiation
+  factory = null;
+  constructor(token, factory) {
+    this.token = token;
+    this.factory = factory ?? null;
+    this.injections = factory ? InjectionContext.scan(factory) : /* @__PURE__ */ new Set();
+  }
+  hasFactory() {
+    return typeof this.factory === "function";
+  }
+  setFactory(factory) {
+    if (this.factory) throw InjectionError.duplicateFactory(this.token);
+    this.factory = factory;
+    const scanned = InjectionContext.scan(factory);
+    for (const injection of scanned) {
+      this.injections.add(injection);
+    }
+  }
+  toString() {
+    return `ProtoNodeSingle<${this.token.toString()}>`;
+  }
+};
+var ProtoNodeTransparent = class {
+  static {
+    __name(this, "ProtoNodeTransparent");
+  }
+  parent;
+  factory;
+  injections;
+  constructor(parent, factory) {
+    this.parent = parent;
+    this.factory = factory;
+    this.injections = InjectionContext.scan(factory);
+  }
+  toString() {
+    return `ProtoNodeTransparent<${this.factory.name || "anonymous"}>`;
+  }
+};
+var ProtoNodeMulti = class {
+  static {
+    __name(this, "ProtoNodeMulti");
+  }
+  token;
+  singleNodes = /* @__PURE__ */ new Set();
+  multiNodes = /* @__PURE__ */ new Set();
+  transparentNodes = /* @__PURE__ */ new Set();
+  constructor(token) {
+    this.token = token;
+  }
+  addProvider(retriever) {
+    if (retriever instanceof NodeToken) {
+      this.singleNodes.add(retriever);
+    } else if (retriever instanceof MultiNodeToken) {
+      this.multiNodes.add(retriever);
+    } else if (typeof retriever === "function") {
+      const transparentProto = new ProtoNodeTransparent(this, retriever);
+      this.transparentNodes.add(transparentProto);
+    }
+  }
+  toString() {
+    return `ProtoNodeMulti<${this.token.toString()}>`;
+  }
+};
+function isNotTransparentProto(proto) {
+  return !(proto instanceof ProtoNodeTransparent);
+}
+__name(isNotTransparentProto, "isNotTransparentProto");
+
+// src/lib/provider/tree-node.ts
+function retrieverFactory(node, deps, transparentDeps) {
+  return (token, optional) => {
+    const depNode = deps.get(token);
+    if (!depNode && !optional) {
+      const transparent = Array.from(transparentDeps).find((n) => "proto" in n && n.proto.parent.token === token);
+      if (transparent) return transparent.instance;
+      throw InjectionError.untracked(token, node);
+    }
+    return depNode?.instance ?? null;
+  };
+}
+__name(retrieverFactory, "retrieverFactory");
+var TreeRootNode = class {
+  static {
+    __name(this, "TreeRootNode");
+  }
+  _deps = /* @__PURE__ */ new Set();
+  _treePool = /* @__PURE__ */ new Map();
+  get dependencies() {
+    return this._deps;
+  }
+  addDependency(node) {
+    this._deps.add(node);
+  }
+  instantiate() {
+    for (const dep of this._deps) {
+      dep.instantiate(this._treePool);
+      if ("token" in dep.proto) this._treePool.set(dep.proto.token, dep);
+    }
+  }
+  find(token) {
+    const node = this._treePool.get(token);
+    if (!node) return null;
+    return node;
+  }
+  toString() {
+    return "TreeRootNode";
+  }
+};
+var TreeNodeSingle = class {
+  static {
+    __name(this, "TreeNodeSingle");
+  }
+  proto;
+  _transparent = /* @__PURE__ */ new Set();
+  _deps = /* @__PURE__ */ new Map();
+  _instance = null;
+  _resolved = false;
+  allocations = 0;
+  get instance() {
+    if (!this._resolved) {
+      throw InjectionError.instanceAccessFailed(this.proto.token);
+    }
+    return this._instance;
+  }
+  constructor(proto) {
+    this.proto = proto;
+  }
+  addDependency(node) {
+    if (node instanceof TreeNodeTransparent) this._transparent.add(node);
+    else this._deps.set(node.proto.token, node);
+    node.allocations++;
+  }
+  instantiate(pool) {
+    if (this._resolved) return;
+    for (const node of this._deps.values()) node.instantiate(pool);
+    for (const dep of this._transparent) dep.instantiate(pool);
+    const retriever = retrieverFactory(this.proto.token, this._deps, this._transparent);
+    const factory = this.proto.factory ?? this.proto.token.opts?.factory;
+    if (!factory) throw InjectionError.notFound(this.proto.token);
+    this._instance = InjectionContext.instantiate(factory, retriever);
+    this._resolved = true;
+    if (pool) pool.set(this.proto.token, this);
+  }
+  toString() {
+    return `TreeNodeSingle<${this.proto.token.toString()}>`;
+  }
+};
+var TreeNodeTransparent = class _TreeNodeTransparent {
+  static {
+    __name(this, "TreeNodeTransparent");
+  }
+  proto;
+  _transparent = /* @__PURE__ */ new Set();
+  _deps = /* @__PURE__ */ new Map();
+  _instance = null;
+  _resolved = false;
+  allocations = 0;
+  get instance() {
+    if (!this._resolved) throw InjectionError.accessFailed();
+    return this._instance;
+  }
+  constructor(proto) {
+    this.proto = proto;
+  }
+  addDependency(node) {
+    if (node instanceof _TreeNodeTransparent) this._transparent.add(node);
+    else this._deps.set(node.proto.token, node);
+    node.allocations++;
+  }
+  instantiate(pool) {
+    if (this._resolved) return;
+    for (const dep of this._transparent) dep.instantiate(pool);
+    for (const node of this._deps.values()) node.instantiate(pool);
+    const retriever = retrieverFactory(this.proto.parent.token, this._deps, this._transparent);
+    this._instance = InjectionContext.instantiate(this.proto.factory, retriever);
+    this._resolved = true;
+  }
+  toString() {
+    return `TreeNodeTransparent<${this.proto.parent.token.toString()}>`;
+  }
+};
+var TreeNodeMulti = class _TreeNodeMulti {
+  static {
+    __name(this, "TreeNodeMulti");
+  }
+  proto;
+  _deps = /* @__PURE__ */ new Set();
+  instance = [];
+  _resolved = false;
+  allocations = 0;
+  constructor(proto) {
+    this.proto = proto;
+  }
+  instantiate(pool) {
+    if (this._resolved) return;
+    for (const dep of this._deps) {
+      dep.instantiate(pool);
+      if (dep instanceof TreeNodeSingle) {
+        this.instance.push(dep.instance);
+      } else if (dep instanceof _TreeNodeMulti) {
+        this.instance.push(...dep.instance);
+      } else if (dep instanceof TreeNodeTransparent) {
+        this.instance.push(dep.instance);
+      }
+    }
+    this._resolved = true;
+    if (pool) pool.set(this.proto.token, this);
+  }
+  addDependency(...nodes) {
+    for (const node of nodes) {
+      this._deps.add(node);
+      node.allocations++;
+    }
+  }
+  toString() {
+    return `TreeNodeMulti<${this.proto.token.toString()}>`;
+  }
+};
+
+// src/lib/provider/resolver.ts
+function createTreeNode(p) {
+  if (p instanceof ProtoNodeSingle) return new TreeNodeSingle(p);
+  if (p instanceof ProtoNodeMulti) return new TreeNodeMulti(p);
+  if (p instanceof ProtoNodeTransparent) return new TreeNodeTransparent(p);
+  throw new Error("Unknown ProtoNode type");
+}
+__name(createTreeNode, "createTreeNode");
+function resolveTreeNode(rootProto, cache, singleNodes, multiNodes, upstreamGetter) {
+  const inCache = cache.get(rootProto);
+  if (inCache) return inCache;
+  const rootNode = createTreeNode(rootProto);
+  const stack = [
+    {
+      proto: rootProto,
+      node: rootNode,
+      processed: false
+    }
+  ];
+  const visiting = /* @__PURE__ */ new Set();
+  while (stack.length > 0) {
+    let addDependency2 = function(token, optional = false) {
+      if (token instanceof NodeToken) {
+        const p = singleNodes.get(token);
+        if (p) {
+          deps.push(p);
+          return;
+        }
+      } else if (token instanceof MultiNodeToken) {
+        const p = multiNodes.get(token);
+        if (p) {
+          deps.push(p);
+          return;
+        }
+      }
+      const upstream = upstreamGetter?.(token);
+      if (upstream) {
+        deps.push(upstream);
+        return;
+      }
+      if (!optional) {
+        if (isInjectable(token)) {
+          const nodeToken = getInjectableToken(token);
+          throw InjectionError.notFound(nodeToken);
+        }
+        throw InjectionError.notFound(token);
+      }
+    };
+    var addDependency = addDependency2;
+    __name(addDependency2, "addDependency");
+    const frame = stack[stack.length - 1];
+    const { proto, node } = frame;
+    if (frame.processed) {
+      stack.pop();
+      visiting.delete(proto);
+      cache.set(proto, node);
+      continue;
+    }
+    if (visiting.has(proto) && isNotTransparentProto(proto)) {
+      const path = stack.map((f) => f.proto).filter((p) => isNotTransparentProto(p));
+      const index = path.indexOf(proto);
+      const cycle = path.slice(index);
+      const cycleTokens = cycle.map((p) => p.token);
+      throw InjectionError.circularDependency(proto.token, cycleTokens);
+    }
+    visiting.add(proto);
+    frame.processed = true;
+    const deps = [];
+    if (proto instanceof ProtoNodeSingle || proto instanceof ProtoNodeTransparent) {
+      for (const injection of proto.injections) {
+        addDependency2(injection.token, injection.optional);
+      }
+    }
+    if (proto instanceof ProtoNodeMulti) {
+      const parentNodes = upstreamGetter?.(proto.token);
+      if (parentNodes instanceof TreeNodeMulti) {
+        node.addDependency(parentNodes);
+      }
+      for (const single of proto.singleNodes) {
+        let p = singleNodes.get(single);
+        if (!p) {
+          p = new ProtoNodeSingle(single);
+          singleNodes.set(single, p);
+        }
+        deps.push(p);
+      }
+      for (const multi of proto.multiNodes) {
+        let p = multiNodes.get(multi);
+        if (!p) {
+          p = new ProtoNodeMulti(multi);
+          multiNodes.set(multi, p);
+        }
+        deps.push(p);
+      }
+      for (const transparent of proto.transparentNodes) {
+        deps.push(transparent);
+      }
+    }
+    for (const dep of deps) {
+      if (dep instanceof TreeNodeSingle || dep instanceof TreeNodeMulti || dep instanceof TreeNodeTransparent) {
+        node.addDependency(dep);
+        continue;
+      }
+      const depProto = dep;
+      const cached = cache.get(depProto);
+      if (cached) {
+        node.addDependency(cached);
+        continue;
+      }
+      if (visiting.has(depProto) && isNotTransparentProto(depProto)) {
+        const path = stack.map((f) => f.proto).filter((p) => isNotTransparentProto(p));
+        const index = path.indexOf(depProto);
+        const cycle = [
+          ...path.slice(index),
+          depProto
+        ];
+        const cycleTokens = cycle.map((p) => p.token);
+        throw InjectionError.circularDependency(depProto.token, cycleTokens);
+      }
+      const childNode = createTreeNode(depProto);
+      node.addDependency(childNode);
+      stack.push({
+        proto: depProto,
+        node: childNode,
+        processed: false
+      });
+    }
+  }
+  return rootNode;
+}
+__name(resolveTreeNode, "resolveTreeNode");
+
+// src/lib/utils/injector.ts
+var InjectorImpl = class {
+  static {
+    __name(this, "InjectorImpl");
+  }
+  container;
+  constructor(container) {
+    this.container = container;
+  }
+  get(token) {
+    return this.container.get(token);
+  }
+  produce(fn) {
+    return this.container.produce(fn);
+  }
+};
+var Injector = new NodeToken("Injector");
+
+// src/lib/container/container.ts
+var NodeContainer = class extends Illuma {
+  static {
+    __name(this, "NodeContainer");
+  }
+  _opts;
+  _bootstrapped = false;
+  _rootNode;
+  _parent;
+  _protoNodes = /* @__PURE__ */ new Map();
+  _multiProtoNodes = /* @__PURE__ */ new Map();
+  constructor(_opts) {
+    super(), this._opts = _opts;
+    this._parent = _opts?.parent;
+    if (_opts?.diagnostics) {
+      Illuma.extendDiagnostics(new DiagnosticsDefaultReporter());
+    }
+  }
+  /**
+  * Registers a provider in the container.
+  * Must be called before {@link bootstrap}.
+  *
+  * @template T - The type of value being provided
+  * @param provider - The provider configuration (token, class, or provider object)
+  * @throws {InjectionError} If called after bootstrap or if a duplicate provider is detected
+  *
+  * @example
+  * ```typescript
+  * // Provide a value
+  * container.provide({ provide: CONFIG_TOKEN, value: { apiKey: '123' } });
+  *
+  * // Provide a factory
+  * container.provide({ provide: LOGGER_TOKEN, factory: () => new ConsoleLogger() });
+  *
+  * // Provide an injectable class directly
+  * container.provide(UserService);
+  *
+  * // Provide a class override
+  * container.provide({ provide: ServiceClass, useClass: ServiceOverride });
+  * ```
+  */
+  provide(provider) {
+    if (this._bootstrapped) {
+      throw InjectionError.bootstrapped();
+    }
+    if (Array.isArray(provider)) {
+      for (const item of provider) this.provide(item);
+      return;
+    }
+    if (provider instanceof MultiNodeToken) {
+      if (this._multiProtoNodes.has(provider)) {
+        throw InjectionError.duplicate(provider);
+      }
+      const newProto = new ProtoNodeMulti(provider);
+      this._multiProtoNodes.set(provider, newProto);
+      return;
+    }
+    if (provider instanceof NodeToken) {
+      if (this._protoNodes.has(provider)) {
+        throw InjectionError.duplicate(provider);
+      }
+      const proto = new ProtoNodeSingle(provider);
+      this._protoNodes.set(provider, proto);
+      return;
+    }
+    if (typeof provider === "function") {
+      if (!isInjectable(provider)) throw InjectionError.invalidCtor(provider);
+      const token2 = getInjectableToken(provider);
+      if (!(token2 instanceof NodeToken)) throw InjectionError.invalidCtor(provider);
+      const existing = this._protoNodes.get(token2);
+      if (existing?.hasFactory()) throw InjectionError.duplicate(token2);
+      const factory = token2.opts?.factory ?? (() => new provider());
+      if (existing) {
+        existing.setFactory(factory);
+        return;
+      }
+      const proto = new ProtoNodeSingle(token2, factory);
+      this._protoNodes.set(token2, proto);
+      return;
+    }
+    const obj = provider;
+    const token = extractToken(obj.provide);
+    const retriever = extractProvider(obj);
+    if (token instanceof MultiNodeToken) {
+      const multiProto = this._multiProtoNodes.get(token);
+      if (multiProto) {
+        multiProto.addProvider(retriever);
+        return;
+      }
+      const newProto = new ProtoNodeMulti(token);
+      this._multiProtoNodes.set(token, newProto);
+      newProto.addProvider(retriever);
+      return;
+    }
+    if (token instanceof NodeToken) {
+      const existing = this._protoNodes.get(token);
+      if (existing?.hasFactory()) throw InjectionError.duplicate(token);
+      let factory;
+      if (typeof retriever === "function") factory = retriever;
+      if (isNodeBase(retriever)) {
+        if (retriever === token) throw InjectionError.loopAlias(token);
+        factory = /* @__PURE__ */ __name(() => nodeInject(retriever), "factory");
+      }
+      if (existing && factory) {
+        existing.setFactory(factory);
+        return;
+      }
+      const proto = new ProtoNodeSingle(token, factory);
+      this._protoNodes.set(token, proto);
+      return;
+    }
+    throw InjectionError.invalidProvider(JSON.stringify(provider));
+  }
+  findNode(token) {
+    if (!this._rootNode) return null;
+    if (!this._bootstrapped) return null;
+    if (isInjectable(token)) {
+      const node = getInjectableToken(token);
+      return this._rootNode.find(node);
+    }
+    const treeNode = this._rootNode.find(token);
+    return treeNode;
+  }
+  _getFromParent(token) {
+    if (!this._parent) return null;
+    const parentNode = this._parent;
+    return parentNode.findNode(token);
+  }
+  _buildInjectionTree() {
+    const root = new TreeRootNode();
+    const cache = /* @__PURE__ */ new Map();
+    const nodes = [
+      ...this._protoNodes.values(),
+      ...this._multiProtoNodes.values()
+    ];
+    const upstreamGetter = this._getFromParent.bind(this);
+    for (const node of nodes) {
+      if (cache.has(node)) continue;
+      const treeNode = resolveTreeNode(node, cache, this._protoNodes, this._multiProtoNodes, upstreamGetter);
+      root.addDependency(treeNode);
+    }
+    cache.clear();
+    this._protoNodes.clear();
+    this._multiProtoNodes.clear();
+    return root;
+  }
+  /**
+  * Bootstraps the container by resolving the dependency trees and instantiating all providers.
+  * This must be called after all providers are registered and before calling {@link get}.
+  *
+  * The bootstrap process:
+  * 1. Validates all provider registrations
+  * 2. Builds dependency injection trees
+  * 3. Detects circular dependencies in each tree
+  * 4. Instantiates all dependencies in the correct order
+  *
+  * @throws {InjectionError} If the container is already bootstrapped or if circular dependencies are detected
+  *
+  * @example
+  * ```typescript
+  * const container = new NodeContainer();
+  * container.provide(UserService);
+  * container.provide(LoggerService);
+  * container.bootstrap(); // Resolves and instantiates all dependencies
+  * ```
+  */
+  bootstrap() {
+    if (this._bootstrapped) throw InjectionError.doubleBootstrap();
+    const start = performance.now();
+    this.provide({
+      provide: Injector,
+      value: new InjectorImpl(this)
+    });
+    this._rootNode = this._buildInjectionTree();
+    this._rootNode.instantiate();
+    this._bootstrapped = true;
+    const end = performance.now();
+    const duration = end - start;
+    if (this._opts?.measurePerformance) {
+      console.log(`[Illuma] \u{1F680} Bootstrapped in ${duration.toFixed(2)} ms`);
+    }
+    if (this._opts?.diagnostics) {
+      const allNodes = this._rootNode.dependencies.size;
+      const unusedNodes = Array.from(this._rootNode.dependencies).filter((node) => node.allocations === 0).filter((node) => {
+        if (!(node.proto instanceof ProtoNodeSingle)) return true;
+        return node.proto.token !== Injector;
+      });
+      Illuma.onReport({
+        totalNodes: allNodes,
+        unusedNodes,
+        bootstrapDuration: duration
+      });
+    }
+  }
+  get(provider) {
+    if (!this._bootstrapped || !this._rootNode) {
+      throw InjectionError.notBootstrapped();
+    }
+    let token = null;
+    if (typeof provider === "function") {
+      if (!isInjectable(provider)) throw InjectionError.invalidCtor(provider);
+      token = getInjectableToken(provider);
+    }
+    if (isNodeBase(provider)) token = provider;
+    if (!token) {
+      throw InjectionError.invalidProvider(JSON.stringify(provider));
+    }
+    const treeNode = this._rootNode.find(token);
+    if (!treeNode) {
+      const upstream = this._getFromParent(token);
+      if (upstream) return upstream.instance;
+      if (token instanceof MultiNodeToken) return [];
+      throw InjectionError.notFound(token);
+    }
+    return treeNode.instance;
+  }
+  /**
+  * Instantiates a class outside injection context. Primarily used to create instances via Injector.
+  * Class does not get registered in the container and cannot be retrieved via {@link get} or {@link nodeInject}.
+  * Must be called after {@link bootstrap}.
+  *
+  * @template T - The type of the class being instantiated
+  * @param factory - Factory or class constructor to instantiate
+  * @returns A new instance of the class with dependencies injected
+  * @throws {InjectionError} If called before bootstrap or if the constructor is invalid
+  */
+  produce(fn) {
+    if (!this._bootstrapped || !this._rootNode) {
+      throw InjectionError.notBootstrapped();
+    }
+    if (typeof fn !== "function") throw InjectionError.invalidCtor(fn);
+    if (isConstructor(fn) && !isInjectable(fn)) {
+      throw InjectionError.invalidCtor(fn);
+    }
+    const factory = isInjectable(fn) ? () => new fn() : fn;
+    return InjectionContext.instantiate(factory, (t, optional) => {
+      if (!this._rootNode) throw InjectionError.notBootstrapped();
+      const node = this._rootNode.find(t);
+      if (!node && !optional) throw InjectionError.notFound(t);
+      return node ? node.instance : null;
+    });
+  }
+};
+
+// src/lib/testkit/helpers.ts
+function createTestFactory(cfg) {
+  const factorySelf = /* @__PURE__ */ __name(() => {
+    const container = new NodeContainer();
+    if (cfg.provide) container.provide(cfg.provide);
+    container.provide(cfg.target);
+    container.bootstrap();
+    const instance = container.get(cfg.target);
+    const nodeInject2 = /* @__PURE__ */ __name((token, opts) => {
+      try {
+        return container.get(token);
+      } catch (e) {
+        if (e instanceof InjectionError && e.code === 400 && opts?.optional) {
+          return null;
+        }
+        throw e;
+      }
+    }, "nodeInject");
+    return {
+      instance,
+      nodeInject: nodeInject2
+    };
+  }, "factorySelf");
+  return factorySelf;
+}
+__name(createTestFactory, "createTestFactory");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createTestFactory
+});
+//# sourceMappingURL=testkit.cjs.map