@lppedd/di-wise-neo 0.4.0 → 0.5.0

package/README.md

@@ -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,24 @@ 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);
+```
+
 ## 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`);
@@ -825,7 +834,7 @@ function isDisposable(value) {
  *
  * @example
  * ```ts
- * @AutoRegister()
+ * @AutoRegister
  * class Wizard {}
  *
  * const wizard = container.resolve(Wizard);
@@ -833,11 +842,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 +1095,7 @@ function OptionalAll(token) {
 }
 
 exports.AutoRegister = AutoRegister;
+exports.EagerInstantiate = EagerInstantiate;
 exports.Inject = Inject;
 exports.InjectAll = InjectAll;
 exports.Injectable = Injectable;