@lppedd/di-wise-neo 0.3.2 → 0.5.0

package/dist/es/index.d.mts

@@ -3,11 +3,11 @@
  */
 interface Type<A> {
     /**
-     * Name of the type.
+     * The name of the type.
      */
     readonly name: string;
     /**
-     * Create an intersection type from another type.
+     * Creates an intersection type from another type.
      *
      * @example
      * ```ts
@@ -19,7 +19,7 @@ interface Type<A> {
      */
     inter<B>(typeName: string, B: Type<B>): Type<A & B>;
     /**
-     * Create a union type from another type.
+     * Creates a union type from another type.
      *
      * @example
      * ```ts
@@ -37,7 +37,6 @@ interface Type<A> {
 interface Constructor<Instance extends object> {
     new (...args: any[]): Instance;
     readonly name: string;
-    readonly length: number;
 }
 /**
  * Token type.
@@ -48,11 +47,11 @@ type Token<Value = any> = [Value] extends [object] ? Type<Value> | Constructor<V
  */
 type Tokens<Value = any> = [Token<Value>, ...Token<Value>[]];
 /**
- * Create a type token.
+ * Creates a type token.
  *
  * @example
  * ```ts
- * const Spell = createType<Spell>("Spell");
+ * const ISpell = createType<Spell>("Spell");
  * ```
  *
  * @__NO_SIDE_EFFECTS__
@@ -65,31 +64,33 @@ declare function createType<T>(typeName: string): Type<T>;
 interface ClassProvider<Instance extends object> {
     readonly useClass: Constructor<Instance>;
 }
-/**
- * Provides a value for a token via another existing token.
- */
-interface ExistingProvider<Value> {
-    readonly useExisting: Token<Value>;
-}
 /**
  * Provides a value for a token via a factory function.
  *
- * The factory function runs inside the injection context
- * and can thus access dependencies via {@link inject}.
+ * The factory function runs inside the injection context and can
+ * thus access dependencies via {@link inject}-like functions.
  */
 interface FactoryProvider<Value> {
     readonly useFactory: (...args: []) => Value;
 }
 /**
- * Provides a direct - already constructed - value for a token.
+ * Provides a static - already constructed - value for a token.
  */
 interface ValueProvider<T> {
     readonly useValue: T;
 }
+/**
+ * Aliases another registered token.
+ *
+ * Resolving this token will return the value of the aliased one.
+ */
+interface ExistingProvider<Value> {
+    readonly useExisting: Token<Value>;
+}
 /**
  * A token provider.
  */
-type Provider<Value = any> = ClassProvider<Value & object> | ExistingProvider<Value> | FactoryProvider<Value> | ValueProvider<Value>;
+type Provider<Value = any> = ClassProvider<Value & object> | FactoryProvider<Value> | ValueProvider<Value> | ExistingProvider<Value>;
 
 declare const Scope: {
     readonly Inherited: "Inherited";
@@ -212,35 +213,87 @@ interface Container {
      * Returns whether the token is registered in this container or in parent containers, if any.
      */
     isRegistered(token: Token): boolean;
+    /**
+     * Registers a concrete class, where the class acts as its own token.
+     *
+     * Tokens provided via the {@link Injectable} decorator applied to the class
+     * are also registered as aliases.
+     *
+     * The default registration scope is determined by the {@link Scoped} decorator,
+     * if present.
+     */
+    registerClass<Instance extends object>(Class: Constructor<Instance>): void;
+    /**
+     * Registers a concrete class with a token.
+     *
+     * The default registration scope is determined by the {@link Scoped} decorator
+     * applied to the class, if present, but it can be overridden by passing explicit
+     * registration options.
+     */
+    registerClass<Instance extends object, ProvidedInstance extends Instance>(token: Token<Instance>, Class: Constructor<ProvidedInstance>, options?: RegistrationOptions): void;
+    /**
+     * Registers a token whose value is produced by a factory function.
+     *
+     * The factory function runs inside the injection context and can
+     * thus access dependencies via {@link inject}-like functions.
+     */
+    registerFactory<Value, ProvidedValue extends Value>(token: Token<Value>, factory: (...args: []) => ProvidedValue, options?: RegistrationOptions): void;
+    /**
+     * Registers a token with a fixed value.
+     *
+     * The provided value is returned as-is when the token is resolved (scopes do not apply).
+     */
+    registerValue<Value, ProvidedValue extends Value>(token: Token<Value>, value: ProvidedValue): void;
+    /**
+     * Registers one or more tokens as aliases for a target token.
+     *
+     * When an alias is resolved, the target token is resolved instead.
+     */
+    registerAlias<Value, ProvidedValue extends Value>(targetToken: Token<ProvidedValue>, aliasTokens: Tokens<Value>): void;
     /**
      * Registers a {@link ClassProvider}, using the class itself as its token.
      *
-     * Tokens provided to the {@link Injectable} decorator applied to the class
-     * are also registered as aliases. The scope is determined by the {@link Scoped}
-     * decorator, if present.
+     * Tokens provided via the {@link Injectable} decorator applied to the class
+     * are also registered as aliases.
+     *
+     * The scope is determined by the {@link Scoped} decorator, if present.
+     *
+     * @see registerClass
      */
-    register<Instance extends object>(Class: Constructor<Instance>): this;
+    register<Instance extends object>(Class: Constructor<Instance>): Container;
     /**
      * Registers a {@link ClassProvider} with a token.
+     *
+     * The default registration scope is determined by the {@link Scoped} decorator
+     * applied to the provided class, if present, but it can be overridden by
+     * passing explicit registration options.
+     *
+     * @see registerClass
      */
-    register<Instance extends object, ProviderInstance extends Instance>(token: Token<Instance>, provider: ClassProvider<ProviderInstance>, options?: RegistrationOptions): this;
+    register<Instance extends object, ProviderInstance extends Instance>(token: Token<Instance>, provider: ClassProvider<ProviderInstance>, options?: RegistrationOptions): Container;
     /**
      * Registers a {@link FactoryProvider} with a token.
+     *
+     * @see registerFactory
      */
-    register<Value, ProviderValue extends Value>(token: Token<Value>, provider: FactoryProvider<ProviderValue>, options?: RegistrationOptions): this;
+    register<Value, ProviderValue extends Value>(token: Token<Value>, provider: FactoryProvider<ProviderValue>, options?: RegistrationOptions): Container;
     /**
      * Registers an {@link ExistingProvider} with a token.
      *
      * The token will alias the one set in `useExisting`.
+     *
+     * @see registerAlias
      */
-    register<Value, ProviderValue extends Value>(token: Token<Value>, provider: ExistingProvider<ProviderValue>): this;
+    register<Value, ProviderValue extends Value>(token: Token<Value>, provider: ExistingProvider<ProviderValue>): Container;
     /**
      * Registers a {@link ValueProvider} with a token.
      *
      * Values provided via `useValue` are never cached (scopes do not apply)
      * and are simply returned as-is.
+     *
+     * @see registerValue
      */
-    register<Value, ProviderValue extends Value>(token: Token<Value>, provider: ValueProvider<ProviderValue>): this;
+    register<Value, ProviderValue extends Value>(token: Token<Value>, provider: ValueProvider<ProviderValue>): Container;
     /**
      * Removes all registrations for the given token from the container's internal registry.
      *
@@ -364,12 +417,12 @@ interface Container {
 declare function createContainer(options?: Partial<ContainerOptions>): Container;
 
 /**
- * Class decorator for enabling auto-registration of an unregistered class
- * when first resolving it from the container.
+ * Class decorator that enables auto-registration of an unregistered class,
+ * when the class is first resolved from the container.
  *
  * @example
  * ```ts
- * @AutoRegister()
+ * @AutoRegister
  * class Wizard {}
  *
  * const wizard = container.resolve(Wizard);
@@ -378,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>>;
@@ -387,9 +461,14 @@ interface TokenRef<Value = any> {
     readonly getRefToken: () => Token<Value>;
 }
 /**
- * Allows referencing a token that is declared later in the file by wrapping it in a function.
+ * Allows referencing tokens that are declared later in the file by wrapping them
+ * in a lazily evaluated function.
  */
 declare function forwardRef<Value>(token: () => Tokens<Value>): TokensRef<Value>;
+/**
+ * Allows referencing a token that is declared later in the file by wrapping it
+ * in a lazily evaluated function.
+ */
 declare function forwardRef<Value>(token: () => Token<Value>): TokenRef<Value>;
 
 /**
@@ -424,8 +503,8 @@ declare function Inject<Value>(token: Token<Value>): ParameterDecorator;
 declare function Inject<Value>(tokens: TokenRef<Value>): ParameterDecorator;
 
 /**
- * Class decorator for registering additional aliasing tokens for the decorated type
- * when registering it.
+ * Class decorator that registers additional aliasing tokens for the decorated type,
+ * when the type is first registered in the container.
  *
  * The container uses {@link ExistingProvider} under the hood.
  *
@@ -437,8 +516,8 @@ declare function Inject<Value>(tokens: TokenRef<Value>): ParameterDecorator;
  */
 declare function Injectable<This extends object, Value extends This>(...tokens: Tokens<Value>): ClassDecorator;
 /**
- * Class decorator for registering additional aliasing tokens for the decorated type
- * when registering it.
+ * Class decorator that registers additional aliasing tokens for the decorated type,
+ * when the type is first registered in the container.
  *
  * The container uses {@link ExistingProvider} under the hood.
  *
@@ -718,7 +797,7 @@ declare const Injector: Type<Injector>;
  */
 interface MiddlewareComposer {
     /**
-     * Add a middleware function to the composer.
+     * 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;
 }
@@ -744,7 +823,7 @@ interface Middleware {
     (composer: MiddlewareComposer, api: Readonly<Container>): void;
 }
 /**
- * Apply middleware functions to a container.
+ * Applies middleware functions to a container.
  *
  * Middlewares are applied in array order, but execute in reverse order.
  *
@@ -768,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/es/index.mjs

@@ -207,10 +207,6 @@ function isClassProvider(provider) {
     return "useClass" in provider;
 }
 // @internal
-function isExistingProvider(provider) {
-    return "useExisting" in provider;
-}
-// @internal
 function isFactoryProvider(provider) {
     return "useFactory" in provider;
 }
@@ -218,6 +214,10 @@ function isFactoryProvider(provider) {
 function isValueProvider(provider) {
     return "useValue" in provider;
 }
+// @internal
+function isExistingProvider(provider) {
+    return "useExisting" in provider;
+}
 
 const Scope = {
     Inherited: "Inherited",
@@ -229,11 +229,11 @@ const Scope = {
 /**
  * Type API.
  */ /**
- * Create a type token.
+ * Creates a type token.
  *
  * @example
  * ```ts
- * const Spell = createType<Spell>("Spell");
+ * const ISpell = createType<Spell>("Spell");
  * ```
  *
  * @__NO_SIDE_EFFECTS__
@@ -279,8 +279,8 @@ function getTypeName(value) {
 // @internal
 class TokenRegistry {
     constructor(parent){
-        this.parent = parent;
         this.myMap = new Map();
+        this.myParent = parent;
     }
     get(token) {
         // To clarify, at(-1) means we take the last added registration for this token
@@ -333,7 +333,7 @@ class TokenRegistry {
     }
     getAllFromParent(token) {
         const registrations = this.myMap.get(token);
-        return registrations || this.parent?.getAllFromParent(token);
+        return registrations || this.myParent?.getAllFromParent(token);
     }
 }
 // @internal
@@ -384,12 +384,11 @@ function isDisposable(value) {
 
 /**
  * The default implementation of a di-wise-neo {@link Container}.
- */ class DefaultContainer {
-    constructor(myParent, options){
-        this.myParent = myParent;
-        // eslint-disable-next-line no-use-before-define
+ */ class ContainerImpl {
+    constructor(parent, options){
         this.myChildren = new Set();
         this.myDisposed = false;
+        this.myParent = parent;
         this.myOptions = {
             autoRegister: false,
             defaultScope: Scope.Inherited,
@@ -413,7 +412,7 @@ function isDisposable(value) {
     }
     createChild(options) {
         this.checkDisposed();
-        const container = new DefaultContainer(this, {
+        const container = new ContainerImpl(this, {
             ...this.myOptions,
             ...options
         });
@@ -460,20 +459,51 @@ function isDisposable(value) {
         this.checkDisposed();
         return this.myTokenRegistry.get(token) !== undefined;
     }
+    registerClass(token, Class, options) {
+        // This mess will go away once/if we remove the register method
+        // in favor of the multiple specialized ones
+        if (Class) {
+            const ctor = Class ?? token;
+            this.register(token, {
+                useClass: ctor
+            }, options);
+        } else {
+            this.register(token);
+        }
+    }
+    registerFactory(token, factory, options) {
+        this.register(token, {
+            useFactory: factory
+        }, options);
+    }
+    registerValue(token, value) {
+        this.register(token, {
+            useValue: value
+        });
+    }
+    registerAlias(targetToken, aliasTokens) {
+        // De-duplicate tokens
+        for (const alias of new Set(aliasTokens)){
+            this.register(alias, {
+                useExisting: targetToken
+            });
+        }
+    }
     register(...args) {
         this.checkDisposed();
         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()){
@@ -483,21 +513,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`);
@@ -785,16 +823,16 @@ function isDisposable(value) {
     autoRegister: false,
     defaultScope: Scope.Inherited
 }) {
-    return new DefaultContainer(undefined, options);
+    return new ContainerImpl(undefined, options);
 }
 
 /**
- * Class decorator for enabling auto-registration of an unregistered class
- * when first resolving it from the container.
+ * Class decorator that enables auto-registration of an unregistered class,
+ * when the class is first resolved from the container.
  *
  * @example
  * ```ts
- * @AutoRegister()
+ * @AutoRegister
  * class Wizard {}
  *
  * const wizard = container.resolve(Wizard);
@@ -802,11 +840,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) {
@@ -990,7 +1049,7 @@ function OptionalAll(token) {
 });
 
 /**
- * Apply middleware functions to a container.
+ * Applies middleware functions to a container.
  *
  * Middlewares are applied in array order, but execute in reverse order.
  *
@@ -1033,5 +1092,5 @@ function OptionalAll(token) {
     return 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 };
 //# sourceMappingURL=index.mjs.map