@illuma/core 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -7,4 +7,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## 0.2.0 - 2026-01-10
+
 ## 0.1.0 - 2026-01-07

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 {
@@ -478,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() {
@@ -525,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);
@@ -562,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);
@@ -586,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) {
@@ -762,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);
@@ -956,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(),
@@ -1001,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;
@@ -1072,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,
@@ -1085,6 +1165,7 @@ var NodeContainer = class extends Illuma {
   extractToken,
   getInjectableToken,
   injectAsync,
+  injectDefer,
   injectEntryAsync,
   injectGroupAsync,
   isConstructor,