@lppedd/di-wise-neo 0.4.0 → 0.5.1

package/README.md

@@ -442,7 +442,7 @@ export class ExtensionContext {
 
 ## Behavioral decorators
 
-The library includes two behavioral decorators that influence how classes are registered in the container.
+The library includes three behavioral decorators that influence how classes are registered in the container.
 These decorators attach metadata to the class type, which is then interpreted by the container during registration.
 
 ### `@Scoped`
@@ -476,7 +476,7 @@ In this example, `ExtensionContext` will be registered with **Resolution** scope
 Enables automatic registration of the decorated class if it has not been registered explicitly.
 
 ```ts
-@AutoRegister()
+@AutoRegister
 export class ExtensionContext {
   /* ... */
 }
@@ -485,6 +485,28 @@ export class ExtensionContext {
 container.resolve(ExtensionContext);
 ```
 
+### `@EagerInstantiate`
+
+Marks a class for eager instantiation when registered with **Container** scope.
+
+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)
+export class ExtensionContext {
+  /* ... */
+}
+
+// The container immediately creates and caches the instance
+container.register(ExtensionContext);
+```
+
+> [!WARNING]
+> Eager instantiation requires that all dependencies of the class are already registered in the container.  
+> If they are not, registration will fail.
+
 ## Testing support
 
 Testing is an important part of software development, and dependency injection is meant to make it easier.  

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,7 +431,28 @@ declare function createContainer(options?: Partial<ContainerOptions>): Container
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function AutoRegister(enable?: boolean): ClassDecorator;
+declare function AutoRegister<Ctor extends Constructor<any>>(Class: Ctor): void;
+
+/**
+ * Class decorator that enables eager instantiation of a class when it is registered
+ * in the container with `Scope.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)
+ * class Wizard {}
+ *
+ * // A Wizard 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;
 
 interface TokensRef<Value = any> {
     readonly getRefTokens: () => Set<Token<Value>>;
@@ -826,5 +847,5 @@ interface Middleware {
  */
 declare function applyMiddleware(container: Container, middlewares: Middleware[]): Container;
 
-export { AutoRegister, Inject, InjectAll, Injectable, Injector, Optional, OptionalAll, Scope, Scoped, applyMiddleware, build, createContainer, createType, forwardRef, inject, injectAll, injectBy };
+export { AutoRegister, EagerInstantiate, Inject, InjectAll, Injectable, Injector, Optional, OptionalAll, Scope, Scoped, applyMiddleware, build, createContainer, createType, forwardRef, inject, injectAll, injectBy };
 export type { ClassProvider, Constructor, Container, ContainerOptions, ExistingProvider, FactoryProvider, Middleware, MiddlewareComposer, Provider, RegistrationOptions, Token, TokenRef, Tokens, TokensRef, Type, ValueProvider };

package/dist/cjs/index.js

@@ -496,15 +496,16 @@ function isDisposable(value) {
         if (args.length == 1) {
             const Class = args[0];
             const metadata = getMetadata(Class);
-            // Register the class itself
-            this.myTokenRegistry.set(Class, {
+            const registration = {
                 // The provider is of type ClassProvider, initialized by getMetadata
                 provider: metadata.provider,
                 options: {
-                    scope: metadata.scope
+                    scope: metadata.scope ?? this.myOptions.defaultScope
                 },
                 dependencies: metadata.dependencies
-            });
+            };
+            // Register the class itself
+            this.myTokenRegistry.set(Class, registration);
             // Register the additional tokens specified via class decorators.
             // These tokens will point to the original Class token and will have the same scope.
             for (const token of metadata.tokensRef.getRefTokens()){
@@ -514,21 +515,29 @@ function isDisposable(value) {
                     }
                 });
             }
+            // Eager-instantiate only if the class is container-scoped
+            if (metadata.eagerInstantiate && registration.options?.scope === Scope.Container) {
+                this.resolve(Class);
+            }
         } else {
             const [token, provider, options] = args;
             if (isClassProvider(provider)) {
-                const Class = provider.useClass;
-                const metadata = getMetadata(Class);
-                this.myTokenRegistry.set(token, {
+                const metadata = getMetadata(provider.useClass);
+                const registration = {
                     provider: metadata.provider,
                     options: {
                         // The explicit registration options override what is specified
                         // via class decorators (e.g., @Scoped)
-                        scope: metadata.scope,
+                        scope: metadata.scope ?? this.myOptions.defaultScope,
                         ...options
                     },
                     dependencies: metadata.dependencies
-                });
+                };
+                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);
+                }
             } else {
                 if (isExistingProvider(provider)) {
                     assert(token !== provider.useExisting, `the useExisting token ${token.name} cannot be the same as the token being registered`);
@@ -632,8 +641,16 @@ function isDisposable(value) {
     instantiateClass(Class, optional) {
         const metadata = getMetadata(Class);
         if (metadata.autoRegister ?? this.myOptions.autoRegister) {
-            this.register(Class);
-            return this.resolve(Class);
+            // Temporarily set eagerInstantiate to false to avoid resolving the class two times:
+            // one inside register(), and the other just below
+            const eagerInstantiate = metadata.eagerInstantiate;
+            metadata.eagerInstantiate = false;
+            try {
+                this.register(Class);
+                return this.resolve(Class);
+            } finally{
+                metadata.eagerInstantiate = eagerInstantiate;
+            }
         }
         const scope = this.resolveScope(metadata.scope);
         if (optional && scope === Scope.Container) {
@@ -825,7 +842,7 @@ function isDisposable(value) {
  *
  * @example
  * ```ts
- * @AutoRegister()
+ * @AutoRegister
  * class Wizard {}
  *
  * const wizard = container.resolve(Wizard);
@@ -833,11 +850,32 @@ function isDisposable(value) {
  * ```
  *
  * @__NO_SIDE_EFFECTS__
- */ function AutoRegister(enable = true) {
-    return function(Class) {
-        const metadata = getMetadata(Class);
-        metadata.autoRegister = enable;
-    };
+ */ function AutoRegister(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`.
+ *
+ * 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)
+ * class Wizard {}
+ *
+ * // A Wizard 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 forwardRef(token) {
@@ -1065,6 +1103,7 @@ function OptionalAll(token) {
 }
 
 exports.AutoRegister = AutoRegister;
+exports.EagerInstantiate = EagerInstantiate;
 exports.Inject = Inject;
 exports.InjectAll = InjectAll;
 exports.Injectable = Injectable;