@illuma/core 1.3.1 → 1.5.0

package/dist/index.js

@@ -1,5 +1,171 @@
 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 __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+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/lib/plugins/core/plugin-container.ts
+var Illuma;
+var init_plugin_container = __esm({
+  "src/lib/plugins/core/plugin-container.ts"() {
+    "use strict";
+    Illuma = class _Illuma {
+      static {
+        __name(this, "Illuma");
+      }
+      static _diagnostics = /* @__PURE__ */ new Set();
+      static _scanners = [];
+      static _middlewares = [];
+      /** @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.add(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);
+      }
+      /**
+      * Registers a global middleware to be applied during instance creation.
+      * Typically used for cross-cutting concerns like logging, profiling, or custom instantiation logic.
+      * Function should accept instantiation parameters and a `next` function to proceed with the next middleware or actual instantiation.
+      *
+      * @param m - The middleware function to register
+      */
+      static registerGlobalMiddleware(m) {
+        _Illuma._middlewares.push(m);
+      }
+      middlewares = [];
+      registerMiddleware(m) {
+        this.middlewares.push(m);
+      }
+      static onReport(report) {
+        for (const diag of _Illuma._diagnostics) diag.onReport(report);
+      }
+      /**
+      * @internal
+      * Check if diagnostics modules are registered
+      */
+      static hasDiagnostics() {
+        return _Illuma._diagnostics.size > 0;
+      }
+      /**
+      * @internal
+      * Reset all plugin registrations
+      */
+      static __resetPlugins() {
+        _Illuma._diagnostics.clear();
+        _Illuma._scanners.length = 0;
+        _Illuma._middlewares.length = 0;
+      }
+    };
+  }
+});
+
+// src/lib/plugins/core/index.ts
+var init_core = __esm({
+  "src/lib/plugins/core/index.ts"() {
+    "use strict";
+    init_plugin_container();
+  }
+});
+
+// src/lib/plugins/middlewares/diagnostics.middleware.ts
+var performanceDiagnostics;
+var init_diagnostics_middleware = __esm({
+  "src/lib/plugins/middlewares/diagnostics.middleware.ts"() {
+    "use strict";
+    performanceDiagnostics = /* @__PURE__ */ __name((params, next) => {
+      if (!params.deps.size) {
+        return next(params);
+      }
+      const start = performance.now();
+      const instance = next(params);
+      const end = performance.now();
+      const duration = end - start;
+      console.log(`Instantiated ${params.token.name} in ${duration.toFixed(2)} ms`);
+      return instance;
+    }, "performanceDiagnostics");
+  }
+});
+
+// src/lib/plugins/diagnostics/default-impl.ts
+var DiagnosticsDefaultReporter;
+var init_default_impl = __esm({
+  "src/lib/plugins/diagnostics/default-impl.ts"() {
+    "use strict";
+    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/plugins/diagnostics/built-in.ts
+var built_in_exports = {};
+__export(built_in_exports, {
+  __resetDiagnosticsState: () => __resetDiagnosticsState,
+  enableIllumaDiagnostics: () => enableIllumaDiagnostics
+});
+function enableIllumaDiagnostics() {
+  if (state.enabled) return;
+  state.enabled = true;
+  Illuma.extendDiagnostics(new DiagnosticsDefaultReporter());
+  Illuma.registerGlobalMiddleware(performanceDiagnostics);
+}
+function __resetDiagnosticsState() {
+  state.enabled = false;
+}
+var state;
+var init_built_in = __esm({
+  "src/lib/plugins/diagnostics/built-in.ts"() {
+    "use strict";
+    init_core();
+    init_diagnostics_middleware();
+    init_default_impl();
+    state = {
+      enabled: false
+    };
+    __name(enableIllumaDiagnostics, "enableIllumaDiagnostics");
+    __name(__resetDiagnosticsState, "__resetDiagnosticsState");
+  }
+});
 
 // src/lib/api/token.ts
 var NodeBase = class {
@@ -221,41 +387,8 @@ function registerClassAsInjectable(ctor, token) {
 }
 __name(registerClassAsInjectable, "registerClassAsInjectable");
 
-// 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
+init_plugin_container();
 var InjectionContext = class _InjectionContext {
   static {
     __name(this, "InjectionContext");
@@ -355,18 +488,8 @@ function nodeInject(provider, options) {
 }
 __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/container/container.ts
+init_plugin_container();
 
 // src/lib/provider/extractor.ts
 function extractProvider(provider) {
@@ -454,7 +577,34 @@ function isNotTransparentProto(proto) {
 }
 __name(isNotTransparentProto, "isNotTransparentProto");
 
+// 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/provider/tree-node.ts
+function runMiddlewares(middlewares, params) {
+  const ms = middlewares;
+  const next = /* @__PURE__ */ __name((i, current) => {
+    if (i >= ms.length) return current.factory();
+    return ms[i](current, (nextParams) => next(i + 1, nextParams));
+  }, "next");
+  return next(0, params);
+}
+__name(runMiddlewares, "runMiddlewares");
 function retrieverFactory(node, deps, transparentDeps) {
   return (token, optional) => {
     const depNode = deps.get(token);
@@ -472,10 +622,12 @@ var TreeRootNode = class {
     __name(this, "TreeRootNode");
   }
   instant;
+  middlewares;
   _deps = /* @__PURE__ */ new Set();
   _treePool = /* @__PURE__ */ new WeakMap();
-  constructor(instant = true) {
+  constructor(instant = true, middlewares = []) {
     this.instant = instant;
+    this.middlewares = middlewares;
   }
   get dependencies() {
     return this._deps;
@@ -486,14 +638,14 @@ var TreeRootNode = class {
   build() {
     for (const dep of this._deps) {
       if ("token" in dep.proto) this._treePool.set(dep.proto.token, dep);
-      if (this.instant) dep.instantiate(this._treePool);
+      if (this.instant) dep.instantiate(this._treePool, this.middlewares);
       else dep.collectPool(this._treePool);
     }
   }
   find(token) {
     const node = this._treePool.get(token);
     if (!node) return null;
-    if (!this.instant) node.instantiate(this._treePool);
+    if (!this.instant) node.instantiate(this._treePool, this.middlewares);
     return node;
   }
   toString() {
@@ -518,6 +670,10 @@ var TreeNodeSingle = class {
   }
   constructor(proto) {
     this.proto = proto;
+    if (proto.token === Injector) {
+      this._instance = proto.factory();
+      this._resolved = true;
+    }
   }
   addDependency(node) {
     if (node instanceof TreeNodeTransparent) this._transparent.add(node);
@@ -529,14 +685,22 @@ var TreeNodeSingle = class {
     for (const dep of this._transparent) dep.collectPool(pool);
     pool.set(this.proto.token, this);
   }
-  instantiate(pool) {
+  instantiate(pool, middlewares = []) {
     if (this._resolved) return;
-    for (const node of this._deps.values()) node.instantiate(pool);
-    for (const dep of this._transparent) dep.instantiate(pool);
+    for (const node of this._deps.values()) node.instantiate(pool, middlewares);
+    for (const dep of this._transparent) dep.instantiate(pool, middlewares);
     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);
+    const contextFactory = /* @__PURE__ */ __name(() => InjectionContext.instantiate(factory, retriever), "contextFactory");
+    this._instance = runMiddlewares(middlewares, {
+      token: this.proto.token,
+      factory: contextFactory,
+      deps: /* @__PURE__ */ new Set([
+        ...this._deps.keys(),
+        ...Array.from(this._transparent).map((n) => n.proto.parent.token)
+      ])
+    });
     this._resolved = true;
     if (pool) pool.set(this.proto.token, this);
   }
@@ -570,12 +734,20 @@ var TreeNodeTransparent = class _TreeNodeTransparent {
     for (const node of this._deps.values()) node.collectPool(pool);
     for (const dep of this._transparent) dep.collectPool(pool);
   }
-  instantiate(pool) {
+  instantiate(pool, middlewares = []) {
     if (this._resolved) return;
-    for (const dep of this._transparent) dep.instantiate(pool);
-    for (const node of this._deps.values()) node.instantiate(pool);
+    for (const dep of this._transparent) dep.instantiate(pool, middlewares);
+    for (const node of this._deps.values()) node.instantiate(pool, middlewares);
     const retriever = retrieverFactory(this.proto.parent.token, this._deps, this._transparent);
-    this._instance = InjectionContext.instantiate(this.proto.factory, retriever);
+    const refFactory = /* @__PURE__ */ __name(() => InjectionContext.instantiate(this.proto.factory, retriever), "refFactory");
+    this._instance = runMiddlewares(middlewares, {
+      token: this.proto.parent.token,
+      factory: refFactory,
+      deps: /* @__PURE__ */ new Set([
+        ...this._deps.keys(),
+        ...Array.from(this._transparent).map((n) => n.proto.parent.token)
+      ])
+    });
     this._resolved = true;
   }
   toString() {
@@ -598,10 +770,10 @@ var TreeNodeMulti = class _TreeNodeMulti {
     for (const dep of this._deps) dep.collectPool(pool);
     pool.set(this.proto.token, this);
   }
-  instantiate(pool) {
+  instantiate(pool, middlewares = []) {
     if (this._resolved) return;
     for (const dep of this._deps) {
-      dep.instantiate(pool);
+      dep.instantiate(pool, middlewares);
       if (dep instanceof TreeNodeSingle) {
         this.instance.push(dep.instance);
       } else if (dep instanceof _TreeNodeMulti) {
@@ -756,24 +928,6 @@ function resolveTreeNode(rootProto, cache, singleNodes, multiNodes, upstreamGett
 }
 __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/utils/defer.ts
 function injectDefer(provider, options) {
   const injector = nodeInject(Injector);
@@ -883,10 +1037,13 @@ var NodeContainer = class extends Illuma {
   _multiProtoNodes = /* @__PURE__ */ new Map();
   constructor(_opts) {
     super(), this._opts = _opts;
-    this._parent = _opts?.parent;
     if (_opts?.diagnostics) {
-      Illuma.extendDiagnostics(new DiagnosticsDefaultReporter());
+      console.warn("[Illuma] Deprecation Warning: The 'diagnostics' option in iContainerOptions is deprecated and will be removed in future versions. Please use the `enableIllumaDiagnostics` from '@illuma/core/plugins` instead.");
+      const m = (init_built_in(), __toCommonJS(built_in_exports));
+      if (m.enabled) return;
+      m.enableIllumaDiagnostics();
     }
+    this._parent = _opts?.parent;
   }
   /**
   * Registers a provider in the container.
@@ -999,7 +1156,11 @@ var NodeContainer = class extends Illuma {
     return parentNode.findNode(token);
   }
   _buildInjectionTree() {
-    const root = new TreeRootNode(this._opts?.instant);
+    const middlewares = [
+      ...Illuma._middlewares,
+      ...this.collectMiddlewares()
+    ];
+    const root = new TreeRootNode(this._opts?.instant, middlewares);
     const cache = /* @__PURE__ */ new Map();
     const nodes = [
       ...this._protoNodes.values(),
@@ -1016,6 +1177,12 @@ var NodeContainer = class extends Illuma {
     this._multiProtoNodes.clear();
     return root;
   }
+  collectMiddlewares() {
+    return [
+      ...this._parent && "collectMiddlewares" in this._parent && typeof this._parent.collectMiddlewares === "function" ? this._parent.collectMiddlewares() : [],
+      ...this.middlewares
+    ];
+  }
   /**
   * 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}.
@@ -1051,7 +1218,7 @@ var NodeContainer = class extends Illuma {
     if (this._opts?.measurePerformance) {
       console.log(`[Illuma] \u{1F680} Bootstrapped in ${duration.toFixed(2)} ms`);
     }
-    if (this._opts?.diagnostics) {
+    if (this._opts?.diagnostics || Illuma.hasDiagnostics()) {
       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;