@lppedd/di-wise-neo 0.15.0 → 0.16.0

package/dist/cjs/index.d.ts

@@ -274,18 +274,46 @@ type Provider<Value = any> = ClassProvider<Value & object> | FactoryProvider<Val
  * Container creation options.
  */
 interface ContainerOptions {
+    /**
+     * The default scope for registrations.
+     *
+     * @defaultValue Scope.Transient
+     */
+    readonly defaultScope: Scope;
     /**
      * Whether to automatically register an unregistered class when resolving it as a token.
      *
      * @defaultValue false
      */
     readonly autoRegister: boolean;
+}
+/**
+ * Child container creation options.
+ */
+interface ChildContainerOptions extends ContainerOptions {
     /**
-     * The default scope for registrations.
+     * Whether to copy {@link ContainerHook}(s) from the parent container.
      *
-     * @defaultValue Scope.Transient
+     * @defaultValue true
      */
-    readonly defaultScope: Scope;
+    readonly copyHooks: boolean;
+}
+/**
+ * A hook into the lifecycle of a container-managed value.
+ */
+interface ContainerHook {
+    /**
+     * Called when the container provides a value for a {@link Token}.
+     * - For _container_ scoped tokens, it is called only once when the token is first resolved and cached.
+     * - For _resolution_ scoped tokens, it is called once per token resolution graph.
+     * - For _transient_ scoped tokens, it is called each time the token is resolved,
+     *   which might mean multiple times per resolution graph.
+     */
+    readonly onProvide: (value: unknown) => void;
+    /**
+     * Called when a _container_ scoped value is about to be disposed.
+     */
+    readonly onDispose: (value: unknown) => void;
 }
 /**
  * Container API.
@@ -308,7 +336,7 @@ interface Container {
      *
      * You can pass specific options to override the inherited ones.
      */
-    createChild(options?: Partial<ContainerOptions>): Container;
+    createChild(options?: Partial<ChildContainerOptions>): Container;
     /**
      * Clears and returns all distinct cached values from this container's internal registry.
      * Values from {@link ValueProvider} registrations are not included, as they are never cached.
@@ -571,6 +599,18 @@ interface Container {
      * in the container's internal registry.
      */
     tryResolveAll<Value>(token: Token<Value>): Value[];
+    /**
+     * Adds a hook to observe the lifecycle of container-managed values.
+     *
+     * Does nothing if the hook has already been added.
+     */
+    addHook(hook: ContainerHook): void;
+    /**
+     * Removes a previously added hook.
+     *
+     * Does nothing if the hook has not been added yet.
+     */
+    removeHook(hook: ContainerHook): void;
     /**
      * Disposes this container and all its cached values.
      *
@@ -938,6 +978,15 @@ declare function injectAll<Instance extends object>(Class: Constructor<Instance>
  */
 declare function injectAll<Value>(token: Token<Value>): Value[];
 
+/**
+ * Asserts that the current stack frame is within an injection context,
+ * meaning it has access to injection functions (`inject`, `optional`, etc.).
+ *
+ * @param fn The function performing the assertion, or a string name used in the error message.
+ * @throws {Error} If the current stack frame is not within an injection context.
+ */
+declare function assertInjectionContext(fn: Function | string): void;
+
 /**
  * Injector API.
  */
@@ -1147,5 +1196,5 @@ declare function optionalAll<Instance extends object>(Class: Constructor<Instanc
  */
 declare function optionalAll<Value>(token: Token<Value>): Value[];
 
-export { AutoRegister, EagerInstantiate, Inject, InjectAll, Injectable, Injector, Named, Optional, OptionalAll, Scope, Scoped, applyMiddleware, build, classRef, createContainer, createType, inject, injectAll, injectBy, optional, optionalAll, optionalBy, setClassIdentityMapping, tokenRef };
-export type { ClassProvider, ClassRef, Constructor, Container, ContainerOptions, ExistingProvider, FactoryProvider, Middleware, MiddlewareComposer, Provider, ProviderType, RegistrationOptions, Token, TokenRef, Tokens, TokensRef, Type, ValueProvider };
+export { AutoRegister, EagerInstantiate, Inject, InjectAll, Injectable, Injector, Named, Optional, OptionalAll, Scope, Scoped, applyMiddleware, assertInjectionContext, build, classRef, createContainer, createType, inject, injectAll, injectBy, optional, optionalAll, optionalBy, setClassIdentityMapping, tokenRef };
+export type { ChildContainerOptions, ClassProvider, ClassRef, Constructor, Container, ContainerHook, ContainerOptions, ExistingProvider, FactoryProvider, Middleware, MiddlewareComposer, Provider, ProviderType, RegistrationOptions, Token, TokenRef, Tokens, TokensRef, Type, ValueProvider };

package/dist/cjs/index.js

@@ -34,7 +34,7 @@ function throwResolutionError(tokenInfo, aliases, cause) {
 function throwParameterResolutionError(ctor, methodKey, dependency, cause) {
     const location = getLocation(ctor, methodKey);
     const tokenName = getFullTokenName([
-        dependency.tokenRef.getRefToken(),
+        dependency.tokenRef?.getRefToken(),
         dependency.name
     ]);
     const msg = tag(`failed to resolve dependency for ${location}(parameter #${dependency.index}: ${tokenName})`);
@@ -56,7 +56,7 @@ function getTokenName(token) {
     return token.name || "<unnamed>";
 }
 function getFullTokenName([token, name]) {
-    const tokenName = token.name || "<unnamed>";
+    const tokenName = token ? token.name || "<unnamed>" : "<undefined token>";
     return name ? `${tokenName}["${name}"]` : tokenName;
 }
 function getCause(error) {
@@ -144,6 +144,16 @@ function ensureInjectionContext(name) {
     check(context, `${name} can only be invoked within an injection context`);
     return context;
 }
+/**
+ * Asserts that the current stack frame is within an injection context,
+ * meaning it has access to injection functions (`inject`, `optional`, etc.).
+ *
+ * @param fn The function performing the assertion, or a string name used in the error message.
+ * @throws {Error} If the current stack frame is not within an injection context.
+ */ function assertInjectionContext(fn) {
+    const name = typeof fn === "function" ? `${fn.name || "<unnamed>"}()` : fn;
+    ensureInjectionContext(name);
+}
 function createInjectionContext() {
     let current = null;
     function provide(next) {
@@ -216,15 +226,15 @@ function tokenRef(token) {
 }
 // @internal
 function isClassRef(value) {
-    return value && typeof value === "object" && typeof value.getRefClass === "function";
+    return value != null && typeof value === "object" && typeof value.getRefClass === "function";
 }
 // @internal
 function isTokensRef(value) {
-    return value && typeof value === "object" && typeof value.getRefTokens === "function";
+    return value != null && typeof value === "object" && typeof value.getRefTokens === "function";
 }
 // @internal
 function isTokenRef(value) {
-    return value && typeof value === "object" && typeof value.getRefToken === "function";
+    return value != null && typeof value === "object" && typeof value.getRefToken === "function";
 }
 
 // @internal
@@ -533,21 +543,22 @@ const builders = new WeakSet();
 // @internal
 // @internal
 function isDisposable(value) {
-    return value && typeof value === "object" && typeof value.dispose === "function";
+    return value != null && typeof value === "object" && typeof value.dispose === "function";
 }
 
 /**
  * The default implementation of a di-wise-neo {@link Container}.
  */ class ContainerImpl {
-    constructor(parent, options){
+    constructor(parent, hooks, options){
         this.myChildren = new Set();
         this.myDisposed = false;
         this.myParent = parent;
+        this.myHooks = hooks ?? new Set();
         this.myOptions = {
-            autoRegister: options?.autoRegister ?? false,
-            defaultScope: options?.defaultScope ?? Scope.Transient
+            defaultScope: options?.defaultScope ?? Scope.Transient,
+            autoRegister: options?.autoRegister ?? false
         };
-        this.myTokenRegistry = new TokenRegistry(this.myParent?.myTokenRegistry);
+        this.myTokenRegistry = new TokenRegistry(parent?.myTokenRegistry);
     }
     get registry() {
         return this.myTokenRegistry;
@@ -565,9 +576,10 @@ function isDisposable(value) {
     }
     createChild(options) {
         this.checkDisposed();
-        const container = new ContainerImpl(this, {
-            autoRegister: options?.autoRegister ?? this.myOptions.autoRegister,
-            defaultScope: options?.defaultScope ?? this.myOptions.defaultScope
+        const hooks = options?.copyHooks === false ? undefined : new Set(this.myHooks);
+        const container = new ContainerImpl(this, hooks, {
+            defaultScope: options?.defaultScope ?? this.myOptions.defaultScope,
+            autoRegister: options?.autoRegister ?? this.myOptions.autoRegister
         });
         this.myChildren.add(container);
         return container;
@@ -651,6 +663,12 @@ function isDisposable(value) {
         this.checkDisposed();
         return this.resolveAllToken(token, true);
     }
+    addHook(hook) {
+        this.myHooks.add(hook);
+    }
+    removeHook(hook) {
+        this.myHooks.delete(hook);
+    }
     dispose() {
         if (this.myDisposed) {
             return;
@@ -669,12 +687,14 @@ function isDisposable(value) {
         for (const registration of registrations){
             const value = registration.value?.current;
             if (isDisposable(value) && !disposedRefs.has(value)) {
+                this.notifyDisposeHooks(value);
                 disposedRefs.add(value);
                 value.dispose();
             }
         }
         // Allow values to be GCed
         disposedRefs.clear();
+        this.myHooks.clear();
     }
     registerClass(Class) {
         const metadata = getMetadata(Class);
@@ -703,7 +723,9 @@ function isDisposable(value) {
                 }
             });
         }
-        // Eager-instantiate only if the class is container-scoped
+        // Eager-instantiate only if the class is container-scoped.
+        // Note that we are comparing the scope using the registration configured just above,
+        // which takes into account both the metadata and the container option as a fallback.
         if (metadata.eagerInstantiate && registration.options?.scope === Scope.Container) {
             this.resolveProviderValue(Class, registration);
         }
@@ -725,7 +747,9 @@ function isDisposable(value) {
                 dependencies: metadata.dependencies
             };
             this.myTokenRegistry.set(token, registration);
-            // Eager-instantiate only if the provided class is container-scoped
+            // Eager-instantiate only if the provided class is container-scoped.
+            // Note that we are comparing the scope using the registration configured just above,
+            // which takes into account both the metadata and the container option as a fallback.
             if (metadata.eagerInstantiate && registration.options?.scope === Scope.Container) {
                 this.resolveProviderValue(token, registration);
             }
@@ -839,7 +863,7 @@ function isDisposable(value) {
         }
         if (isFactoryProvider(provider)) {
             const factory = provider.useFactory;
-            return this.resolveScopedValue(token, registration, factory);
+            return this.resolveScopedValue(token, registration, ()=>factory());
         }
         if (isValueProvider(provider)) {
             return provider.useValue;
@@ -888,6 +912,7 @@ function isDisposable(value) {
                         registration.value = {
                             current: value
                         };
+                        this.notifyProvideHooks(value);
                         return value;
                     }
                 case Scope.Resolution:
@@ -901,12 +926,15 @@ function isDisposable(value) {
                         resolution.values.set(provider, {
                             current: value
                         });
+                        this.notifyProvideHooks(value);
                         return value;
                     }
                 case Scope.Transient:
                     {
                         const args = this.resolveCtorDependencies(registration);
-                        return this.injectMethodDependencies(registration, factory(args));
+                        const value = this.injectMethodDependencies(registration, factory(args));
+                        this.notifyProvideHooks(value);
+                        return value;
                     }
             }
         } finally{
@@ -955,6 +983,7 @@ function isDisposable(value) {
         }
         return instance;
     }
+    // Call context: decorator-based injection
     resolveArgs(deps, ctor, instance, methodKey) {
         const sortedDeps = deps.sort((a, b)=>a.index - b.index);
         const args = [];
@@ -967,8 +996,10 @@ function isDisposable(value) {
         }
         return args;
     }
+    // Call context: decorator-based injection
     resolveDependency(dependency, instance) {
-        const token = dependency.tokenRef.getRefToken();
+        const token = dependency.tokenRef?.getRefToken();
+        check(token, `token passed to @${dependency.appliedBy} was undefined (possible circular imports)`);
         const name = dependency.name;
         switch(dependency.appliedBy){
             case "Inject":
@@ -981,6 +1012,16 @@ function isDisposable(value) {
                 return instance ? optionalAll(token) : this.tryResolveAll(token);
         }
     }
+    notifyProvideHooks(value) {
+        for (const hook of this.myHooks){
+            hook.onProvide(value);
+        }
+    }
+    notifyDisposeHooks(value) {
+        for (const hook of this.myHooks){
+            hook.onDispose(value);
+        }
+    }
     checkDisposed() {
         check(!this.myDisposed, "container is disposed");
     }
@@ -989,7 +1030,7 @@ function isDisposable(value) {
 /**
  * Creates a new container.
  */ function createContainer(options) {
-    return new ContainerImpl(undefined, options);
+    return new ContainerImpl(undefined, undefined, options);
 }
 
 /**
@@ -1335,6 +1376,7 @@ exports.OptionalAll = OptionalAll;
 exports.Scope = Scope;
 exports.Scoped = Scoped;
 exports.applyMiddleware = applyMiddleware;
+exports.assertInjectionContext = assertInjectionContext;
 exports.build = build;
 exports.classRef = classRef;
 exports.createContainer = createContainer;