@lppedd/di-wise-neo 0.5.2 → 0.6.0

package/README.md

@@ -3,7 +3,8 @@
 <p align="center">Lightweight, type-safe, flexible dependency injection library for TypeScript and JavaScript</p>
 <div align="center">
 
-[![test](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)
+[![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)
 [![npm](https://img.shields.io/npm/v/@lppedd/di-wise-neo?color=%23de1f1f&logo=npm)](https://www.npmjs.com/package/@lppedd/di-wise-neo)
 [![npm gzipped size](https://img.shields.io/bundlejs/size/@lppedd/di-wise-neo)](https://bundlejs.com/?q=@lppedd/di-wise-neo)
 [![license](https://img.shields.io/github/license/lppedd/di-wise-neo?color=blue)](https://github.com/lppedd/di-wise-neo/blob/main/LICENSE)
@@ -19,7 +20,6 @@
 
 ## Table of Contents
 
-- [Why yet another library](#why-yet-another-library)
 - [Installation](#installation)
 - [API reference](#api-reference)
 - [Ergonomics & Requirements](#ergonomics)
@@ -79,7 +79,7 @@ the use of ECMAScript Stage 3 decorators, which do not support decorating method
 So what's the right move? Forking the best pick and refactoring it to suite my
 production needs.
 
-## Installation
+### Installation
 
 ```sh
 npm i @lppedd/di-wise-neo
@@ -93,11 +93,11 @@ pnpm add @lppedd/di-wise-neo
 yarn add @lppedd/di-wise-neo
 ```
 
-## API reference
+### API reference
 
 You can find the complete API reference at [lppedd.github.io/di-wise-neo](https://lppedd.github.io/di-wise-neo)
 
-## Ergonomics
+### Ergonomics
 
 - Does **not** depend on other libraries
 - Does **not** use [reflect-metadata](https://www.npmjs.com/package/reflect-metadata) to drive decorators
@@ -281,7 +281,9 @@ The container will translate `TaskID` to `PID` before resolving the value.
 
 The primary way to perform dependency injection in **di-wise-neo** is through
 functions like `inject(T)`, `injectAll(T)`, `optional(T)`, and `optionalAll(T)`.
-This approach is recommended because it preserves full type safety.
+
+> [!TIP]
+> Using injection functions is recommended because it preserves type safety.
 
 ### Injection context
 
@@ -473,10 +475,11 @@ In this example, `ExtensionContext` will be registered with **Resolution** scope
 
 ### `@AutoRegister`
 
-Enables automatic registration of the decorated class if it has not been registered explicitly.
+Enables automatic registration of the decorated class when it is resolved,
+if it has not been registered beforehand.
 
 ```ts
-@AutoRegister
+@AutoRegister()
 export class ExtensionContext {
   /* ... */
 }
@@ -487,19 +490,20 @@ container.resolve(ExtensionContext);
 
 ### `@EagerInstantiate`
 
-Marks a class for eager instantiation when registered with **Container** scope.
+Sets the default class scope to **Container** and marks the class for eager instantiation
+upon registration.
 
 This causes the container to immediately create and cache the instance of the class
 at registration time, instead of deferring instantiation until the first resolution.
 
 ```ts
-@EagerInstantiate
-@Scoped(Scope.Container)
+@EagerInstantiate()
 export class ExtensionContext {
   /* ... */
 }
 
-// The container immediately creates and caches the instance
+// ExtensionContext is registered with Container scope,
+// and an instance is immediately created and cached by the container
 container.register(ExtensionContext);
 ```
 

package/dist/cjs/index.d.ts

@@ -422,7 +422,7 @@ declare function createContainer(options?: Partial<ContainerOptions>): Container
  *
  * @example
  * ```ts
- * @AutoRegister
+ * @AutoRegister()
  * class Wizard {}
  *
  * const wizard = container.resolve(Wizard);
@@ -431,28 +431,28 @@ declare function createContainer(options?: Partial<ContainerOptions>): Container
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function AutoRegister<Ctor extends Constructor<any>>(Class: Ctor): void;
+declare function AutoRegister(): ClassDecorator;
 
 /**
- * Class decorator that enables eager instantiation of a class when it is registered
- * in the container with `Scope.Container`.
+ * Class decorator that sets the class scope to **Container** and enables
+ * eager instantiation when the class is registered in the container.
  *
  * This causes the container to immediately create and cache the instance of the class,
  * instead of deferring instantiation until the first resolution.
  *
  * @example
  * ```ts
- * @EagerInstantiate
- * @Scoped(Scope.Container)
+ * @EagerInstantiate()
  * class Wizard {}
  *
- * // A Wizard instance is immediately created and cached by the container
+ * // Wizard is registered with Container scope, and an instance
+ * // is immediately created and cached by the container
  * const wizard = container.register(Wizard);
  * ```
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function EagerInstantiate<Ctor extends Constructor<any>>(Class: Ctor): void;
+declare function EagerInstantiate(): ClassDecorator;
 
 interface TokensRef<Value = any> {
     readonly getRefTokens: () => Set<Token<Value>>;

package/dist/cjs/index.js

@@ -192,6 +192,22 @@ function getMetadata(Class) {
             }
         });
     }
+    if (metadata.provider.useClass !== Class) {
+        // This is part of the class identity mapping API (see setClassIdentityMapping).
+        //
+        // Scenario:
+        // 1. Metadata is created for class A (the original class) because of a parameter decorator.
+        // 2. Later, because of a class decorator that extends the decorated class, a third-party
+        //    registers a class identity mapping from class B to class A, where B is the class
+        //    generated from the class decorator by extending A.
+        //
+        // We must update useClass to be the extender class B so that instances created by the
+        // DI container match the consumer's registered class. Without this update, the DI
+        // system would instantiate the original class A, causing behavior inconsistencies.
+        //
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+        metadata.provider.useClass = Class;
+    }
     return metadata;
 }
 const classIdentityMap = new WeakMap();
@@ -520,7 +536,7 @@ function isDisposable(value) {
                 // The provider is of type ClassProvider, initialized by getMetadata
                 provider: metadata.provider,
                 options: {
-                    scope: metadata.scope ?? this.myOptions.defaultScope
+                    scope: metadata.scope?.value ?? this.myOptions.defaultScope
                 },
                 dependencies: metadata.dependencies
             };
@@ -537,7 +553,7 @@ function isDisposable(value) {
             }
             // Eager-instantiate only if the class is container-scoped
             if (metadata.eagerInstantiate && registration.options?.scope === Scope.Container) {
-                this.resolve(Class);
+                this.resolveProviderValue(registration, registration.provider);
             }
         } else {
             const [token, provider, options] = args;
@@ -548,7 +564,7 @@ function isDisposable(value) {
                     options: {
                         // The explicit registration options override what is specified
                         // via class decorators (e.g., @Scoped)
-                        scope: metadata.scope ?? this.myOptions.defaultScope,
+                        scope: metadata.scope?.value ?? this.myOptions.defaultScope,
                         ...options
                     },
                     dependencies: metadata.dependencies
@@ -556,7 +572,7 @@ function isDisposable(value) {
                 this.myTokenRegistry.set(token, registration);
                 // Eager-instantiate only if the provided class is container-scoped
                 if (metadata.eagerInstantiate && registration.options?.scope === Scope.Container) {
-                    this.resolve(token);
+                    this.resolveProviderValue(registration, registration.provider);
                 }
             } else {
                 if (isExistingProvider(provider)) {
@@ -672,7 +688,7 @@ function isDisposable(value) {
                 metadata.eagerInstantiate = eagerInstantiate;
             }
         }
-        const scope = this.resolveScope(metadata.scope);
+        const scope = this.resolveScope(metadata.scope?.value);
         if (optional && scope === Scope.Container) {
             // It would not be possible to resolve the class in container scope,
             // as that would require prior registration.
@@ -862,7 +878,7 @@ function isDisposable(value) {
  *
  * @example
  * ```ts
- * @AutoRegister
+ * @AutoRegister()
  * class Wizard {}
  *
  * const wizard = container.resolve(Wizard);
@@ -870,32 +886,45 @@ function isDisposable(value) {
  * ```
  *
  * @__NO_SIDE_EFFECTS__
- */ function AutoRegister(Class) {
-    const metadata = getMetadata(Class);
-    metadata.autoRegister = true;
+ */ function AutoRegister() {
+    return function(Class) {
+        const metadata = getMetadata(Class);
+        metadata.autoRegister = true;
+    };
 }
 
 /**
- * Class decorator that enables eager instantiation of a class when it is registered
- * in the container with `Scope.Container`.
+ * Class decorator that sets the class scope to **Container** and enables
+ * eager instantiation when the class is registered in the container.
  *
  * This causes the container to immediately create and cache the instance of the class,
  * instead of deferring instantiation until the first resolution.
  *
  * @example
  * ```ts
- * @EagerInstantiate
- * @Scoped(Scope.Container)
+ * @EagerInstantiate()
  * class Wizard {}
  *
- * // A Wizard instance is immediately created and cached by the container
+ * // Wizard is registered with Container scope, and an instance
+ * // is immediately created and cached by the container
  * const wizard = container.register(Wizard);
  * ```
  *
  * @__NO_SIDE_EFFECTS__
- */ function EagerInstantiate(Class) {
-    const metadata = getMetadata(Class);
-    metadata.eagerInstantiate = true;
+ */ function EagerInstantiate() {
+    return function(Class) {
+        const metadata = getMetadata(Class);
+        const currentScope = metadata.scope;
+        assert(!currentScope || currentScope.value === Scope.Container, ()=>{
+            const { value, appliedBy } = currentScope;
+            return `class ${Class.name}: Scope.${value} was already set by @${appliedBy},\n  ` + `but @EagerInstantiate is trying to set a conflicting Scope.Container.\n  ` + `Only one decorator should set the class scope, or all must agree on the same value.`;
+        });
+        metadata.eagerInstantiate = true;
+        metadata.scope = {
+            value: Scope.Container,
+            appliedBy: "EagerInstantiate"
+        };
+    };
 }
 
 function forwardRef(token) {
@@ -1027,7 +1056,16 @@ function OptionalAll(token) {
  */ function Scoped(scope) {
     return function(Class) {
         const metadata = getMetadata(Class);
-        metadata.scope = scope;
+        const currentScope = metadata.scope;
+        assert(!currentScope || currentScope.value === scope, ()=>{
+            const { value, appliedBy } = currentScope;
+            const by = appliedBy === "Scoped" ? `another @${appliedBy} decorator` : `@${appliedBy}`;
+            return `class ${Class.name}: Scope.${value} was already set by ${by},\n  ` + `but @Scoped is trying to set a conflicting Scope.${scope}.\n  ` + `Only one decorator should set the class scope, or all must agree on the same value.`;
+        });
+        metadata.scope = {
+            value: scope,
+            appliedBy: "Scoped"
+        };
     };
 }