@illuma/core 1.0.0 → 1.2.1

package/CHANGELOG.md

@@ -7,40 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
-## 1.7.0 - 2025-12-28
+## 1.2.1 - 2026-01-10
 
-## 1.6.3 - 2025-12-27
+## 1.2.0 - 2026-01-10
 
-## 1.6.2 - 2025-12-27
-
-## 1.6.1 - 2025-12-27
-
-## 1.6.0 - 2025-12-27
-
-## 1.5.3 - 2025-12-10
-
-## 1.5.2 - 2025-12-10
-
-## 1.5.1 - 2025-12-10
-
-## 1.5.0 - 2025-12-08
-
-## 1.4.0 - 2025-12-08
-
-## 1.3.0 - 2025-12-07
-
-## 1.2.0 - 2025-11-26
-
-## 1.1.2 - 2025-11-23
-
-## 1.1.1 - 2025-11-23
-
-## 1.1.0 - 2025-11-23
-
-## 1.0.3 - 2025-11-22
-
-## 1.0.2 - 2025-11-22
-
-## 1.0.1 - 2025-11-22
-
-## 1.0.0 - 2026-01-01
+## 1.1.0 - 2026-01-07

package/README.md

@@ -23,6 +23,12 @@ A lightweight, type-safe dependency injection container for TypeScript. Zero dep
 npm install @illuma/core
 ```
 
+## 🤝 Compatibility
+
+Anything that supports ES2015+ (ES6+).
+Practically the library is compatible with Node.js (v14+) and all modern browsers.
+For older environments, consider using a transpiler like Babel or TypeScript or provide polyfills as needed.
+
 ## 🚀 Quick Start
 
 ```typescript

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ILLUMA_ERR_CODES: () => ERR_CODES,
   INJECTION_SYMBOL: () => INJECTION_SYMBOL,
   InjectionContext: () => InjectionContext,
   InjectionError: () => InjectionError,
@@ -34,6 +35,7 @@ __export(index_exports, {
   extractToken: () => extractToken,
   getInjectableToken: () => getInjectableToken,
   injectAsync: () => injectAsync,
+  injectDefer: () => injectDefer,
   injectEntryAsync: () => injectEntryAsync,
   injectGroupAsync: () => injectGroupAsync,
   isConstructor: () => isConstructor,
@@ -45,6 +47,29 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/lib/errors.ts
+var ERR_CODES = {
+  // Provider errors
+  DUPLICATE_PROVIDER: 100,
+  DUPLICATE_FACTORY: 101,
+  INVALID_CTOR: 102,
+  INVALID_PROVIDER: 103,
+  // Alias errors
+  INVALID_ALIAS: 200,
+  LOOP_ALIAS: 201,
+  // Bootstrap errors
+  NOT_BOOTSTRAPPED: 300,
+  BOOTSTRAPPED: 301,
+  DOUBLE_BOOTSTRAP: 302,
+  // Retrieval errors
+  NOT_FOUND: 400,
+  CIRCULAR_DEPENDENCY: 401,
+  // Instantiation errors
+  UNTRACKED: 500,
+  OUTSIDE_CONTEXT: 501,
+  CALLED_UTILS_OUTSIDE_CONTEXT: 502,
+  INSTANCE_ACCESS_FAILED: 503,
+  ACCESS_FAILED: 504
+};
 var InjectionError = class _InjectionError extends Error {
   static {
     __name(this, "InjectionError");
@@ -56,66 +81,70 @@ var InjectionError = class _InjectionError extends Error {
   }
   // Provider errors
   static duplicate(token) {
-    return new _InjectionError(100, `Duplicate provider for token "${token.toString()}" detected.`);
+    return new _InjectionError(ERR_CODES.DUPLICATE_PROVIDER, `Duplicate provider for token "${token.toString()}" detected.`);
   }
   static duplicateFactory(token) {
-    return new _InjectionError(101, `Tried to re-provide factory for token "${token.toString()}" detected.`);
+    return new _InjectionError(ERR_CODES.DUPLICATE_FACTORY, `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`);
+    return new _InjectionError(ERR_CODES.INVALID_CTOR, `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.:
+    return new _InjectionError(ERR_CODES.INVALID_PROVIDER, `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().`);
+    return new _InjectionError(ERR_CODES.INVALID_ALIAS, `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.`);
+    return new _InjectionError(ERR_CODES.LOOP_ALIAS, `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.");
+    return new _InjectionError(ERR_CODES.NOT_BOOTSTRAPPED, "Cannot retrieve providers before the container has been bootstrapped.");
   }
   static bootstrapped() {
-    return new _InjectionError(301, "Cannot modify providers after the container has been bootstrapped.");
+    return new _InjectionError(ERR_CODES.BOOTSTRAPPED, "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.");
+    return new _InjectionError(ERR_CODES.DOUBLE_BOOTSTRAP, "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()}".`);
+    return new _InjectionError(ERR_CODES.NOT_FOUND, `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}":
+    return new _InjectionError(ERR_CODES.CIRCULAR_DEPENDENCY, `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.`);
+    return new _InjectionError(ERR_CODES.UNTRACKED, `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.`);
+    return new _InjectionError(ERR_CODES.OUTSIDE_CONTEXT, `Cannot inject "${tokenStr}" outside of an injection context.`);
   }
   static calledUtilsOutsideContext() {
-    return new _InjectionError(502, "Cannot call injection utilities outside of an injection context.");
+    return new _InjectionError(ERR_CODES.CALLED_UTILS_OUTSIDE_CONTEXT, "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.`);
+    return new _InjectionError(ERR_CODES.INSTANCE_ACCESS_FAILED, `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.");
+    return new _InjectionError(ERR_CODES.ACCESS_FAILED, "Failed to access the requested instance due to an unknown error.");
   }
 };
+function isNotFoundError(error) {
+  return error instanceof InjectionError && error.code === ERR_CODES.NOT_FOUND;
+}
+__name(isNotFoundError, "isNotFoundError");
 
 // src/lib/api/token.ts
 var NodeBase = class {
@@ -335,6 +364,13 @@ var InjectionContext = class _InjectionContext {
   }
 };
 
+// src/lib/api/proxy.ts
+var SHAPE_SHIFTER = new Proxy(() => {
+}, {
+  get: /* @__PURE__ */ __name(() => SHAPE_SHIFTER, "get"),
+  apply: /* @__PURE__ */ __name(() => SHAPE_SHIFTER, "apply")
+});
+
 // src/lib/api/injection.ts
 function nodeInject(provider, options) {
   let token = provider;
@@ -351,7 +387,7 @@ function nodeInject(provider, options) {
   if (InjectionContext.injector) {
     return InjectionContext.injector(token, options?.optional);
   }
-  return injection;
+  return SHAPE_SHIFTER;
 }
 __name(nodeInject, "nodeInject");
 
@@ -471,23 +507,29 @@ var TreeRootNode = class {
   static {
     __name(this, "TreeRootNode");
   }
+  instant;
   _deps = /* @__PURE__ */ new Set();
   _treePool = /* @__PURE__ */ new Map();
+  constructor(instant = true) {
+    this.instant = instant;
+  }
   get dependencies() {
     return this._deps;
   }
   addDependency(node) {
     this._deps.add(node);
   }
-  instantiate() {
+  build() {
     for (const dep of this._deps) {
-      dep.instantiate(this._treePool);
       if ("token" in dep.proto) this._treePool.set(dep.proto.token, dep);
+      if (this.instant) dep.instantiate(this._treePool);
+      else dep.collectPool(this._treePool);
     }
   }
   find(token) {
     const node = this._treePool.get(token);
     if (!node) return null;
+    if (!this.instant) node.instantiate(this._treePool);
     return node;
   }
   toString() {
@@ -518,6 +560,11 @@ var TreeNodeSingle = class {
     else this._deps.set(node.proto.token, node);
     node.allocations++;
   }
+  collectPool(pool) {
+    for (const node of this._deps.values()) node.collectPool(pool);
+    for (const dep of this._transparent) dep.collectPool(pool);
+    pool.set(this.proto.token, this);
+  }
   instantiate(pool) {
     if (this._resolved) return;
     for (const node of this._deps.values()) node.instantiate(pool);
@@ -555,6 +602,10 @@ var TreeNodeTransparent = class _TreeNodeTransparent {
     else this._deps.set(node.proto.token, node);
     node.allocations++;
   }
+  collectPool(pool) {
+    for (const node of this._deps.values()) node.collectPool(pool);
+    for (const dep of this._transparent) dep.collectPool(pool);
+  }
   instantiate(pool) {
     if (this._resolved) return;
     for (const dep of this._transparent) dep.instantiate(pool);
@@ -579,6 +630,10 @@ var TreeNodeMulti = class _TreeNodeMulti {
   constructor(proto) {
     this.proto = proto;
   }
+  collectPool(pool) {
+    for (const dep of this._deps) dep.collectPool(pool);
+    pool.set(this.proto.token, this);
+  }
   instantiate(pool) {
     if (this._resolved) return;
     for (const dep of this._deps) {
@@ -755,6 +810,37 @@ var InjectorImpl = class {
 };
 var Injector = new NodeToken("Injector");
 
+// src/lib/utils/defer.ts
+function injectDefer(provider, options) {
+  const injector = nodeInject(Injector);
+  let token = provider;
+  if (isInjectable(provider)) token = getInjectableToken(provider);
+  if (!isNodeBase(token)) throw InjectionError.invalidProvider(String(token));
+  let resolved = false;
+  let instance = SHAPE_SHIFTER;
+  return () => {
+    if (resolved) return instance;
+    if (options?.optional) {
+      try {
+        instance = injector.get(token);
+        resolved = true;
+        return instance;
+      } catch (e) {
+        if (isNotFoundError(e)) {
+          resolved = true;
+          instance = null;
+          return instance;
+        }
+        throw e;
+      }
+    }
+    instance = injector.get(token);
+    resolved = true;
+    return instance;
+  };
+}
+__name(injectDefer, "injectDefer");
+
 // src/lib/utils/inheritance.ts
 function injectGroupAsync(fn, opts) {
   const { container: parent } = nodeInject(Injector);
@@ -949,7 +1035,7 @@ var NodeContainer = class extends Illuma {
     return parentNode.findNode(token);
   }
   _buildInjectionTree() {
-    const root = new TreeRootNode();
+    const root = new TreeRootNode(this._opts?.instant);
     const cache = /* @__PURE__ */ new Map();
     const nodes = [
       ...this._protoNodes.values(),
@@ -994,7 +1080,7 @@ var NodeContainer = class extends Illuma {
       value: new InjectorImpl(this)
     });
     this._rootNode = this._buildInjectionTree();
-    this._rootNode.instantiate();
+    this._rootNode.build();
     this._bootstrapped = true;
     const end = performance.now();
     const duration = end - start;
@@ -1065,6 +1151,7 @@ var NodeContainer = class extends Illuma {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ILLUMA_ERR_CODES,
   INJECTION_SYMBOL,
   InjectionContext,
   InjectionError,
@@ -1078,6 +1165,7 @@ var NodeContainer = class extends Illuma {
   extractToken,
   getInjectableToken,
   injectAsync,
+  injectDefer,
   injectEntryAsync,
   injectGroupAsync,
   isConstructor,