@lppedd/di-wise-neo 0.15.1 → 0.17.0

package/README.md

@@ -8,6 +8,7 @@
 [![status](https://img.shields.io/badge/status-beta-AC29EC)](https://github.com/lppedd/di-wise-neo/blob/main/CHANGELOG.md#0100)
 [![build](https://img.shields.io/github/actions/workflow/status/lppedd/di-wise-neo/test.yml.svg?branch=main)](https://github.com/lppedd/di-wise-neo/actions/workflows/test.yml)
 [![coverage](https://img.shields.io/codecov/c/github/lppedd/di-wise-neo/main?token=R9XZFTQ0BA)](https://app.codecov.io/gh/lppedd/di-wise-neo/tree/main/src)
+[![minified size](https://img.shields.io/bundlejs/size/@lppedd/di-wise-neo)](https://bundlejs.com/?q=@lppedd/di-wise-neo)
 [![license](https://img.shields.io/badge/license-MIT-F7F7F7)](https://github.com/lppedd/di-wise-neo/blob/main/LICENSE)
 
 </div>
@@ -152,9 +153,9 @@ export class ContributionRegistrar {
 
 // Create a new DI container
 const container = createContainer({
-  // Optionally override the default "transient" registration scope.
-  // I prefer to use "container" (a.k.a. singleton) scope, but "transient" is the better default.
-  defaultScope: Scope.Container,
+  // Optionally override the default "Transient" registration scope.
+  // I prefer to use "Container" (a.k.a. Singleton) scope, but "Transient" is the better default.
+  defaultScope: "Container",
 });
 
 // Register our managed dependencies in the container
@@ -211,7 +212,7 @@ An explicit **scope** can be specified using the third argument, when applicable
 If omitted, the default scope is **Transient**.
 
 ```ts
-container.register(token, provider, { scope: Scope.Resolution });
+container.register(token, provider, { scope: "Resolution" });
 ```
 
 ### ClassProvider
@@ -455,13 +456,13 @@ These decorators attach metadata to the class type, which is then interpreted by
 Specifies a default scope for the decorated class:
 
 ```ts
-@Scoped(Scope.Container)
+@Scoped("Container")
 export class ExtensionContext {
   /* ... */
 }
 ```
 
-Applying `@Scoped(Scope.Container)` to the `ExtensionContext` class instructs the DI container
+Applying `@Scoped("Container")` to the `ExtensionContext` class instructs the DI container
 to register it with the **Container** scope by default.
 
 This default can be overridden by explicitly providing registration options:
@@ -470,7 +471,7 @@ This default can be overridden by explicitly providing registration options:
 container.register(
   ExtensionContext,
   { useClass: ExtensionContext },
-  { scope: Scope.Resolution },
+  { scope: "Resolution" },
 );
 ```
 
@@ -483,7 +484,7 @@ to distinguish between multiple implementations of the same type.
 
 ```ts
 @Named("persistent")
-@Scoped(Scope.Container)
+@Scoped("Container")
 export class PersistentSecretStorage implements SecretStorage {
   /* ... */
 }

package/dist/cjs/index.d.ts

@@ -50,7 +50,7 @@ declare function build<Value>(factory: (...args: []) => Value): Type<Value>;
 /**
  * An injectable type `T`.
  */
-interface Type<T> {
+interface Type<T> extends ParameterDecorator {
     /**
      * The name of the type.
      */
@@ -63,6 +63,10 @@ interface Type<T> {
      * @private
      */
     readonly __type: T | undefined;
+    /**
+     * Returns the type's {@link Type.name|name}.
+     */
+    readonly toString: () => string;
 }
 /**
  * An injectable type `T` with a default {@link Provider} and optional default registration options.
@@ -87,11 +91,11 @@ interface Constructor<Instance extends object> {
 /**
  * Token type.
  */
-type Token<Value = any> = [Value] extends [object] ? Type<Value> | Constructor<Value & object> : Type<Value>;
+type Token<Value> = [Value] extends [object] ? Type<Value> | Constructor<Value & object> : Type<Value>;
 /**
  * Describes a {@link Token} array with at least one element.
  */
-type Tokens<Value = any> = [Token<Value>, ...Token<Value>[]];
+type Tokens<Value> = [Token<Value>, ...Token<Value>[]];
 /**
  * Creates a type token.
  *
@@ -122,10 +126,10 @@ declare function createType<T>(typeName: string, provider: Provider<T>, options?
 interface ClassRef<Instance extends object> {
     readonly getRefClass: () => Constructor<Instance>;
 }
-interface TokensRef<Value = any> {
+interface TokensRef<Value> {
     readonly getRefTokens: () => Set<Token<Value>>;
 }
-interface TokenRef<Value = any> {
+interface TokenRef<Value> {
     readonly getRefToken: () => Token<Value>;
 }
 /**
@@ -268,27 +272,60 @@ interface ExistingProvider<Value> {
 /**
  * A token provider.
  */
-type Provider<Value = any> = ClassProvider<Value & object> | FactoryProvider<Value> | ValueProvider<Value> | ExistingProvider<Value>;
+type Provider<Value> = ClassProvider<Value & object> | FactoryProvider<Value> | ValueProvider<Value> | ExistingProvider<Value>;
 
 /**
  * Container creation options.
  */
 interface ContainerOptions {
+    /**
+     * The default scope for registrations.
+     *
+     * @defaultValue 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 {@link Container}.
+ */
+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.
+     *
+     * @param value The provided value.
+     * @param scope The {@link Scope} of the provided value.
+     */
+    readonly onProvide?: (value: unknown, scope: Scope) => void;
+    /**
+     * Called after the container has been disposed.
+     *
+     * @param values The values that were cached by the container.
+     */
+    readonly onDispose?: (values: unknown[]) => void;
 }
 /**
- * Container API.
+ * A Dependency Injection container.
  */
 interface Container {
     /**
@@ -308,7 +345,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.
@@ -324,7 +361,7 @@ interface Container {
      * the cached value is taken from the most recent of those registrations.
      * Otherwise, it may be retrieved from parent containers, if any.
      *
-     * Values are never cached for tokens with _transient_ or _resolution_ scope,
+     * Values are never cached for tokens with **Transient** or **Resolution** scope,
      * or for {@link ValueProvider} registrations.
      */
     getCached<Value>(token: Token<Value>): Value | undefined;
@@ -336,7 +373,7 @@ interface Container {
      * cached values are taken from those registrations.
      * Otherwise, cached values may be retrieved from parent containers, if any.
      *
-     * Values are never cached for tokens with _transient_ or _resolution_ scope,
+     * Values are never cached for tokens with **Transient** or **Resolution** scope,
      * or for {@link ValueProvider} registrations.
      */
     getAllCached<Value>(token: Token<Value>): Value[];
@@ -352,7 +389,7 @@ interface Container {
     /**
      * Returns whether the token is registered in this container or in parent containers, if any.
      */
-    isRegistered(token: Token, name?: string): boolean;
+    isRegistered<Value>(token: Token<Value>, name?: string): boolean;
     /**
      * Registers a {@link ClassProvider}, using the class itself as its token.
      *
@@ -423,7 +460,7 @@ interface Container {
      * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
      * - For {@link ExistingProvider}, the instance is resolved by referring to another registered token.
      *
-     * If the class is registered with _container_ scope, the resolved instance is cached
+     * If the class is registered with **Container** scope, the resolved instance is cached
      * in the container's internal registry.
      */
     resolve<Instance extends object>(Class: Constructor<Instance>, name?: string): Instance;
@@ -441,7 +478,7 @@ interface Container {
      * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
      * - For {@link ExistingProvider}, the value is resolved by referring to another registered token.
      *
-     * If the token is registered with _container_ scope, the resolved value is cached
+     * If the token is registered with **Container** scope, the resolved value is cached
      * in the container's internal registry.
      */
     resolve<Value>(token: Token<Value>, name?: string): Value;
@@ -467,7 +504,7 @@ interface Container {
      * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
      * - For {@link ExistingProvider}, the instance is resolved by referring to another registered token.
      *
-     * If the class is registered with _container_ scope, the resolved instance is cached
+     * If the class is registered with **Container** scope, the resolved instance is cached
      * in the container's internal registry.
      */
     tryResolve<Instance extends object>(Class: Constructor<Instance>, name?: string): Instance | undefined;
@@ -486,7 +523,7 @@ interface Container {
      * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
      * - For {@link ExistingProvider}, the value is resolved by referring to another registered token.
      *
-     * If the token is registered with _container_ scope, the resolved value is cached
+     * If the token is registered with **Container** scope, the resolved value is cached
      * in the container's internal registry.
      */
     tryResolve<Value>(token: Token<Value>, name?: string): Value | undefined;
@@ -509,7 +546,7 @@ interface Container {
      * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
      * - For {@link ExistingProvider}, the instance is resolved by referring to another registered token.
      *
-     * If the class is registered with _container_ scope, the resolved instances are cached
+     * If the class is registered with **Container** scope, the resolved instances are cached
      * in the container's internal registry.
      *
      * A separate instance of the class is created for each provider.
@@ -526,7 +563,7 @@ interface Container {
      * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
      * - For {@link ExistingProvider}, the value is resolved by referring to another registered token.
      *
-     * If the token is registered with _container_ scope, the resolved values are cached
+     * If the token is registered with **Container** scope, the resolved values are cached
      * in the container's internal registry.
      */
     resolveAll<Value>(token: Token<Value>): Value[];
@@ -549,7 +586,7 @@ interface Container {
      * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
      * - For {@link ExistingProvider}, the instance is resolved by referring to another registered token.
      *
-     * If the class is registered with _container_ scope, the resolved instances are cached
+     * If the class is registered with **Container** scope, the resolved instances are cached
      * in the container's internal registry.
      *
      * A separate instance of the class is created for each provider.
@@ -567,10 +604,22 @@ interface Container {
      * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
      * - For {@link ExistingProvider}, the value is resolved by referring to another registered token.
      *
-     * If the token is registered with _container_ scope, the resolved values are cached
+     * If the token is registered with **Container** scope, the resolved values are cached
      * 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.
      *
@@ -837,7 +886,7 @@ declare function OptionalAll<Value>(tokens: TokenRef<Value>): ParameterDecorator
  *
  * @example
  * ```ts
- * @Scoped(Scope.Container)
+ * @Scoped("Container")
  * class Wizard {}
  *
  * container.register(Wizard);
@@ -846,7 +895,7 @@ declare function OptionalAll<Value>(tokens: TokenRef<Value>): ParameterDecorator
  * container.register(
  *   Wizard,
  *   { useClass: Wizard },
- *   { scope: Scope.Container },
+ *   { scope: "Container" },
  * );
  * ```
  *
@@ -872,6 +921,24 @@ declare function inject<Instance extends object>(Class: Constructor<Instance>, n
  *   circular dependencies is necessary.
  */
 declare function inject<Value>(token: Token<Value>, name?: string): Value;
+
+/**
+ * Injects all instances provided by the registrations associated with the given class.
+ *
+ * Throws an error if:
+ * - The class is not registered in the container.
+ * - A circular dependency is detected.
+ */
+declare function injectAll<Instance extends object>(Class: Constructor<Instance>): Instance[];
+/**
+ * Injects all values provided by the registrations associated with the given token.
+ *
+ * Throws an error if:
+ * - The token is not registered in the container.
+ * - A circular dependency is detected.
+ */
+declare function injectAll<Value>(token: Token<Value>): Value[];
+
 /**
  * Injects the instance associated with the given class.
  *
@@ -922,24 +989,33 @@ declare function injectBy<Instance extends object>(thisArg: any, Class: Construc
 declare function injectBy<Value>(thisArg: any, token: Token<Value>, name?: string): Value;
 
 /**
- * Injects all instances provided by the registrations associated with the given class.
- *
- * Throws an error if:
- * - The class is not registered in the container.
- * - A circular dependency is detected.
- */
-declare function injectAll<Instance extends object>(Class: Constructor<Instance>): Instance[];
-/**
- * Injects all values provided by the registrations associated with the given token.
+ * Asserts that the current stack frame is within an injection context,
+ * meaning it has access to injection functions (`inject`, `optional`, etc.).
  *
- * Throws an error if:
- * - The token is not registered in the container.
- * - A circular dependency is detected.
+ * @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 injectAll<Value>(token: Token<Value>): Value[];
+declare function assertInjectionContext(fn: Function | string): void;
 
 /**
- * Injector API.
+ * Allows performing injections outside the normal injection context window.
+ *
+ * @example
+ * ```ts
+ * class Wizard {
+ *   private injector = inject(Injector);
+ *
+ *   // Lazily initialize the wand property
+ *   private wand?: Wand;
+ *
+ *   getWand(): Wand {
+ *     // An injection context does not exist here, but the
+ *     // Injector instance retains and reuse the context
+ *     // that was present at the time of its injection
+ *     return (this.wand ??= this.injector.inject(Wand));
+ *   }
+ * }
+ * ```
  */
 interface Injector {
     /**
@@ -999,21 +1075,23 @@ interface Injector {
     runInContext<ReturnType>(fn: () => ReturnType): ReturnType;
 }
 /**
- * Injector token for dynamic injections.
+ * Allows performing injections outside the normal injection context window.
  *
  * @example
  * ```ts
  * class Wizard {
  *   private injector = inject(Injector);
+ *
+ *   // Lazily initialize the wand property
  *   private wand?: Wand;
  *
  *   getWand(): Wand {
+ *     // An injection context does not exist here, but the
+ *     // Injector instance retains and reuse the context
+ *     // that was present at the time of its injection
  *     return (this.wand ??= this.injector.inject(Wand));
  *   }
  * }
- *
- * const wizard = container.resolve(Wizard);
- * wizard.getWand(); // => Wand
  * ```
  */
 declare const Injector: Type<Injector>;
@@ -1036,61 +1114,6 @@ declare const Injector: Type<Injector>;
  */
 declare function setClassIdentityMapping<T extends object>(transformedClass: Constructor<T>, originalClass: Constructor<T>): void;
 
-/**
- * Composer API for middleware functions.
- */
-interface MiddlewareComposer {
-    /**
-     * Adds a middleware function to the composer.
-     */
-    use<MethodKey extends keyof Container>(key: MethodKey, wrap: Container[MethodKey] extends Function ? (next: Container[MethodKey]) => Container[MethodKey] : never): MiddlewareComposer;
-}
-/**
- * Middleware function that can be used to extend the container.
- *
- * @example
- * ```ts
- * const logger: Middleware = (composer, _api) => {
- *   composer
- *     .use("resolve", (next) => (...args) => {
- *       console.log("resolve", args);
- *       return next(...args);
- *     })
- *     .use("resolveAll", (next) => (...args) => {
- *       console.log("resolveAll", args);
- *       return next(...args);
- *     });
- * };
- * ```
- */
-interface Middleware {
-    (composer: MiddlewareComposer, api: Readonly<Container>): void;
-}
-/**
- * Applies middleware functions to a container.
- *
- * Middlewares are applied in array order but execute in reverse order.
- *
- * @example
- * ```ts
- * const container = applyMiddleware(
- *   createContainer(),
- *   [A, B],
- * );
- * ```
- *
- * The execution order will be:
- *
- * 1. B before
- * 2. A before
- * 3. original function
- * 4. A after
- * 5. B after
- *
- * This allows outer middlewares to wrap and control the behavior of inner middlewares.
- */
-declare function applyMiddleware(container: Container, middlewares: Middleware[]): Container;
-
 /**
  * Injects the instance associated with the given class,
  * or `undefined` if the class is not registered in the container.
@@ -1107,6 +1130,22 @@ declare function optional<Instance extends object>(Class: Constructor<Instance>,
  * Use {@link optionalBy} if resolving circular dependencies is necessary.
  */
 declare function optional<Value>(token: Token<Value>, name?: string): Value | undefined;
+
+/**
+ * Injects all instances provided by the registrations associated with the given class
+ * or an empty array if the class is not registered in the container.
+ *
+ * Throws an error if a circular dependency is detected.
+ */
+declare function optionalAll<Instance extends object>(Class: Constructor<Instance>): Instance[];
+/**
+ * Injects all values provided by the registrations associated with the given token
+ * or an empty array if the token is not registered in the container.
+ *
+ * Throws an error if a circular dependency is detected.
+ */
+declare function optionalAll<Value>(token: Token<Value>): Value[];
+
 /**
  * Injects the instance associated with the given class,
  * or `undefined` if the class is not registered in the container.
@@ -1132,20 +1171,5 @@ declare function optionalBy<Instance extends object>(thisArg: any, Class: Constr
  */
 declare function optionalBy<Value>(thisArg: any, token: Token<Value>, name?: string): Value | undefined;
 
-/**
- * Injects all instances provided by the registrations associated with the given class
- * or an empty array if the class is not registered in the container.
- *
- * Throws an error if a circular dependency is detected.
- */
-declare function optionalAll<Instance extends object>(Class: Constructor<Instance>): Instance[];
-/**
- * Injects all values provided by the registrations associated with the given token
- * or an empty array if the token is not registered in the container.
- *
- * Throws an error if a circular dependency is detected.
- */
-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, assertInjectionContext, build, classRef, createContainer, createType, inject, injectAll, injectBy, optional, optionalAll, optionalBy, setClassIdentityMapping, tokenRef };
+export type { ChildContainerOptions, ClassProvider, ClassRef, Constructor, Container, ContainerHook, ContainerOptions, ExistingProvider, FactoryProvider, Provider, ProviderType, RegistrationOptions, Token, TokenRef, Tokens, TokensRef, Type, ValueProvider };