@lppedd/di-wise-neo 0.7.2 → 0.8.1

package/dist/es/index.d.mts

@@ -187,8 +187,6 @@ interface RegistrationOptions {
  *   );
  * }
  * ```
- *
- * @__NO_SIDE_EFFECTS__
  */
 declare function build<Value>(factory: (...args: []) => Value): Type<Value>;
 
@@ -811,6 +809,17 @@ interface Injector {
      * or an empty array if the token is not registered in the container.
      */
     optionalAll<Value>(token: Token<Value>): NonNullable<Value>[];
+    /**
+     * Runs a function inside the injection context of this injector.
+     *
+     * Note that injection functions (`inject`, `injectAll`, `optional`, `optionalAll`)
+     * are only usable synchronously: they cannot be called from asynchronous callbacks
+     * or after any `await` points.
+     *
+     * @param fn The function to be run in the context of this injector.
+     * @returns The return value of the function, if any.
+     */
+    runInContext<ReturnType>(fn: () => ReturnType): ReturnType;
 }
 /**
  * Injector token for dynamic injections.

package/dist/es/index.mjs

@@ -1,3 +1,30 @@
+/**
+ * Type API.
+ */ /**
+ * Creates a type token.
+ *
+ * @example
+ * ```ts
+ * const ISpell = createType<Spell>("Spell");
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */ function createType(typeName) {
+    const type = {
+        name: `Type<${typeName}>`,
+        inter: createType,
+        union: createType,
+        toString () {
+            return type.name;
+        }
+    };
+    return type;
+}
+// @internal
+function isConstructor(token) {
+    return typeof token === "function";
+}
+
 // @internal
 function assert(condition, message) {
     if (!condition) {
@@ -10,7 +37,8 @@ function expectNever(value) {
 }
 // @internal
 function throwUnregisteredError(token) {
-    throw new Error(tag(`unregistered token ${token.name}`));
+    const type = isConstructor(token) ? "class" : "token";
+    throw new Error(tag(`unregistered ${type} ${token.name}`));
 }
 // @internal
 function throwExistingUnregisteredError(sourceToken, targetTokenOrError) {
@@ -29,23 +57,6 @@ function untag(message) {
     return message.startsWith("[di-wise-neo]") ? message.substring(13).trimStart() : message;
 }
 
-// @internal
-function createInjectionContext() {
-    let current = null;
-    function provide(next) {
-        const prev = current;
-        current = next;
-        return ()=>current = prev;
-    }
-    function use() {
-        return current;
-    }
-    return [
-        provide,
-        use
-    ];
-}
-
 // @internal
 function invariant(condition) {
     if (!condition) {
@@ -115,18 +126,33 @@ function createResolution() {
 // @internal
 const [provideInjectionContext, useInjectionContext] = createInjectionContext();
 // @internal
-function ensureInjectionContext(fn) {
+function ensureInjectionContext(name) {
     const context = useInjectionContext();
-    assert(context, `${fn.name}() can only be invoked within an injection context`);
+    assert(context, `${name} can only be invoked within an injection context`);
     return context;
 }
+function createInjectionContext() {
+    let current = null;
+    function provide(next) {
+        const prev = current;
+        current = next;
+        return ()=>current = prev;
+    }
+    function use() {
+        return current;
+    }
+    return [
+        provide,
+        use
+    ];
+}
 
 function inject(token, name) {
-    const context = ensureInjectionContext(inject);
+    const context = ensureInjectionContext("inject()");
     return context.container.resolve(token, name);
 }
 function injectBy(thisArg, token, name) {
-    const context = ensureInjectionContext(injectBy);
+    const context = ensureInjectionContext("injectBy()");
     const resolution = context.resolution;
     const currentFrame = resolution.stack.peek();
     if (!currentFrame) {
@@ -144,7 +170,7 @@ function injectBy(thisArg, token, name) {
 }
 
 function injectAll(token) {
-    const context = ensureInjectionContext(injectAll);
+    const context = ensureInjectionContext("injectAll()");
     return context.container.resolveAll(token);
 }
 
@@ -240,11 +266,11 @@ const classIdentityMap = new WeakMap();
 const metadataMap = new WeakMap();
 
 function optional(token, name) {
-    const context = ensureInjectionContext(optional);
+    const context = ensureInjectionContext("optional()");
     return context.container.resolve(token, true, name);
 }
 function optionalBy(thisArg, token, name) {
-    const context = ensureInjectionContext(optionalBy);
+    const context = ensureInjectionContext("optionalBy()");
     const resolution = context.resolution;
     const currentFrame = resolution.stack.peek();
     if (!currentFrame) {
@@ -262,7 +288,7 @@ function optionalBy(thisArg, token, name) {
 }
 
 function optionalAll(token) {
-    const context = ensureInjectionContext(optionalAll);
+    const context = ensureInjectionContext("optionalAll()");
     return context.container.resolveAll(token, true);
 }
 
@@ -290,33 +316,6 @@ const Scope = {
     Container: "Container"
 };
 
-/**
- * Type API.
- */ /**
- * Creates a type token.
- *
- * @example
- * ```ts
- * const ISpell = createType<Spell>("Spell");
- * ```
- *
- * @__NO_SIDE_EFFECTS__
- */ function createType(typeName) {
-    const type = {
-        name: `Type<${typeName}>`,
-        inter: createType,
-        union: createType,
-        toString () {
-            return type.name;
-        }
-    };
-    return type;
-}
-// @internal
-function isConstructor(token) {
-    return typeof token === "function";
-}
-
 // @internal
 function getTypeName(value) {
     switch(typeof value){
@@ -428,26 +427,9 @@ class TokenRegistry {
 function isBuilder(provider) {
     return builders.has(provider);
 }
-/**
- * Create a one-off type token from a factory function.
- *
- * @example
- * ```ts
- * class Wizard {
- *   wand = inject(
- *     build(() => {
- *       const wand = inject(Wand);
- *       wand.owner = this;
- *       // ...
- *       return wand;
- *     }),
- *   );
- * }
- * ```
- *
- * @__NO_SIDE_EFFECTS__
- */ function build(factory) {
-    const token = createType(`Build<${getTypeName(factory)}>`);
+// @__NO_SIDE_EFFECTS__
+function build(factory, name) {
+    const token = createType(name ?? `Build<${getTypeName(factory)}>`);
     const provider = {
         useFactory: factory
     };
@@ -638,7 +620,7 @@ function isDisposable(value) {
         if (isConstructor(token)) {
             return this.instantiateClass(token, localOptional);
         }
-        return optionalOrName ? undefined : throwUnregisteredError(token);
+        return localOptional ? undefined : throwUnregisteredError(token);
     }
     resolveAll(token, optional) {
         this.checkDisposed();
@@ -1005,10 +987,22 @@ function updateParameterMetadata(decorator, target, propertyKey, parameterIndex,
         updateFn(dependency);
     }
 }
+// Checks that a constructor or method parameter has only one injection decorator.
+// For example, if both `@Inject` and `@Optional` are used, it becomes difficult to
+// understand which one "wins", unless the user is aware of the decorator evaluation order.
+//
+// @internal
+function checkSingleDecorator(dependency, target, propertyKey, parameterIndex) {
+    assert(!dependency.appliedBy, ()=>{
+        const where = propertyKey === undefined ? `${target.name} constructor` : `${target.constructor.name}.${String(propertyKey)}`;
+        return `${where} parameter ${parameterIndex} declares multiple injection decorators, but only one is allowed`;
+    });
+}
 
 function Inject(token) {
     return function(target, propertyKey, parameterIndex) {
         updateParameterMetadata("Inject", target, propertyKey, parameterIndex, (dependency)=>{
+            checkSingleDecorator(dependency, target, propertyKey, parameterIndex);
             dependency.appliedBy = "Inject";
             dependency.tokenRef = isTokenRef(token) ? token : forwardRef(()=>token);
         });
@@ -1038,6 +1032,7 @@ function Inject(token) {
 function InjectAll(token) {
     return function(target, propertyKey, parameterIndex) {
         updateParameterMetadata("InjectAll", target, propertyKey, parameterIndex, (dependency)=>{
+            checkSingleDecorator(dependency, target, propertyKey, parameterIndex);
             dependency.appliedBy = "InjectAll";
             dependency.tokenRef = isTokenRef(token) ? token : forwardRef(()=>token);
         });
@@ -1085,6 +1080,7 @@ function InjectAll(token) {
 function Optional(token) {
     return function(target, propertyKey, parameterIndex) {
         updateParameterMetadata("Optional", target, propertyKey, parameterIndex, (dependency)=>{
+            checkSingleDecorator(dependency, target, propertyKey, parameterIndex);
             dependency.appliedBy = "Optional";
             dependency.tokenRef = isTokenRef(token) ? token : forwardRef(()=>token);
         });
@@ -1094,6 +1090,7 @@ function Optional(token) {
 function OptionalAll(token) {
     return function(target, propertyKey, parameterIndex) {
         updateParameterMetadata("OptionalAll", target, propertyKey, parameterIndex, (dependency)=>{
+            checkSingleDecorator(dependency, target, propertyKey, parameterIndex);
             dependency.appliedBy = "OptionalAll";
             dependency.tokenRef = isTokenRef(token) ? token : forwardRef(()=>token);
         });
@@ -1154,12 +1151,12 @@ function OptionalAll(token) {
  * const wizard = container.resolve(Wizard);
  * wizard.getWand(); // => Wand
  * ```
- */ const Injector = /*@__PURE__*/ build(function Injector() {
-    const context = ensureInjectionContext(Injector);
+ */ const Injector = /*@__PURE__*/ build(()=>{
+    const context = ensureInjectionContext("Injector factory");
     const resolution = context.resolution;
     const dependentFrame = resolution.stack.peek();
     const dependentRef = dependentFrame && resolution.dependents.get(dependentFrame.provider);
-    function withCurrentContext(fn) {
+    const runInContext = (fn)=>{
         if (useInjectionContext()) {
             return fn();
         }
@@ -1171,18 +1168,17 @@ function OptionalAll(token) {
         try {
             return fn();
         } finally{
-            for (const cleanup of cleanups){
-                cleanup?.();
-            }
+            cleanups.forEach((cleanup)=>cleanup?.());
         }
-    }
+    };
     return {
-        inject: (token, name)=>withCurrentContext(()=>inject(token, name)),
-        injectAll: (token)=>withCurrentContext(()=>injectAll(token)),
-        optional: (token, name)=>withCurrentContext(()=>optional(token, name)),
-        optionalAll: (token)=>withCurrentContext(()=>optionalAll(token))
+        inject: (token, name)=>runInContext(()=>inject(token, name)),
+        injectAll: (token)=>runInContext(()=>injectAll(token)),
+        optional: (token, name)=>runInContext(()=>optional(token, name)),
+        optionalAll: (token)=>runInContext(()=>optionalAll(token)),
+        runInContext
     };
-});
+}, "Injector");
 
 /**
  * Applies middleware functions to a container.