@lppedd/di-wise-neo 0.23.0 → 0.24.0

package/dist/es/index.d.mts

@@ -55,9 +55,13 @@ declare function build<Value>(factory: (...args: []) => Value): Type<Value>;
  */
 interface Type<T> extends ParameterDecorator {
     /**
-     * The name of the type.
+     * The type's presentable name, in the `Type<debugName>` format.
      */
     readonly name: string;
+    /**
+     * The type's debug name, as passed to {@link createType}.
+     */
+    readonly debugName: string;
     /**
      * Ensures that different `Type<T>` types are not structurally compatible.
      *
@@ -66,10 +70,6 @@ interface Type<T> extends ParameterDecorator {
      * @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.
@@ -110,7 +110,7 @@ type Tokens<Value> = [Token<Value>, ...Token<Value>[]];
  * });
  * ```
  */
-declare function createType<T>(typeName: string): Type<T>;
+declare function createType<T>(debugName: string): Type<T>;
 /**
  * Creates a type token with a default {@link Provider} and optional default registration options.
  *
@@ -124,7 +124,7 @@ declare function createType<T>(typeName: string): Type<T>;
  * container.register(ISpell);
  * ```
  */
-declare function createType<T>(typeName: string, provider: Provider<T>, options?: RegistrationOptions): ProviderType<T>;
+declare function createType<T>(debugName: string, provider: Provider<T>, options?: RegistrationOptions): ProviderType<T>;
 
 interface ClassRef<Instance extends object> {
     readonly getRefClass: () => Constructor<Instance>;
@@ -271,8 +271,6 @@ type RequiredNonNullable<T> = {
     [P in keyof T]-?: NonNullable<T[P]>;
 };
 
-type ProviderFor<V> = V extends object ? Provider<V> : Exclude<Provider<V>, ClassProvider<any>>;
-type RegistrationOptionsFor<P> = P extends ValueProvider<any> ? never : RegistrationOptions;
 /**
  * Container creation options.
  */
@@ -412,23 +410,6 @@ interface Container {
      * Registers a token type with a default {@link Provider} and optional default registration options.
      */
     register<Value>(token: ProviderType<Value>): Container;
-    /**
-     * Registers a {@link Provider} with a token or class.
-     *
-     * The provider must be one of:
-     * - {@link ClassProvider} via `useClass`
-     * - {@link FactoryProvider} via `useFactory`
-     * - {@link ValueProvider} via `useValue`
-     * - {@link ExistingProvider} via `useExisting`
-     *
-     * For {@link ClassProvider} registrations, the default scope is determined by the {@link Scoped}
-     * decorator applied to the provided class - if present - or by the {@link ContainerOptions.defaultScope}
-     * value, but it can be overridden by passing explicit registration options.
-     *
-     * For {@link ValueProvider} registrations, the provided value is returned as-is and never cached,
-     * and registration options do not apply.
-     */
-    register<Value, ProviderValue extends Value, Provider extends ProviderFor<ProviderValue>>(token: Token<Value>, provider: ProviderFor<ProviderValue> & Provider, options?: RegistrationOptionsFor<Provider>): Container;
     /**
      * Registers a {@link ClassProvider} with a token.
      *
@@ -663,6 +644,20 @@ interface Container {
  */
 declare function createContainer(options?: ContainerOptions): Container;
 
+/**
+ * Class decorator that enables auto-registration of an unregistered class
+ * when the class is first resolved from the container.
+ *
+ * Example:
+ * ```ts
+ * @AutoRegister
+ * class Wizard {}
+ *
+ * const wizard = container.resolve(Wizard);
+ * container.isRegistered(Wizard); // => true
+ * ```
+ */
+declare function AutoRegister<This extends object, Ctor extends Constructor<This>>(target: Ctor): void;
 /**
  * Class decorator that enables auto-registration of an unregistered class
  * when the class is first resolved from the container.
@@ -675,9 +670,31 @@ declare function createContainer(options?: ContainerOptions): Container;
  * const wizard = container.resolve(Wizard);
  * container.isRegistered(Wizard); // => true
  * ```
+ *
+ * @deprecated Use `@AutoRegister` instead of `AutoRegister()`.
  */
 declare function AutoRegister<This extends object>(): ClassDecorator<This>;
 
+/**
+ * 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 create and cache the instance of the class
+ * immediately, instead of deferring it until the first resolution.
+ *
+ * If the class cannot be resolved at registration time, registration fails.
+ *
+ * Example:
+ * ```ts
+ * @EagerInstantiate
+ * class Wizard {}
+ *
+ * // Wizard is registered with Container scope, and an instance
+ * // is created and cached immediately by the container
+ * container.register(Wizard);
+ * ```
+ */
+declare function EagerInstantiate<This extends object, Ctor extends Constructor<This>>(target: Ctor): void;
 /**
  * Class decorator that sets the class scope to **Container** and enables
  * eager instantiation when the class is registered in the container.
@@ -696,6 +713,8 @@ declare function AutoRegister<This extends object>(): ClassDecorator<This>;
  * // is created and cached immediately by the container
  * container.register(Wizard);
  * ```
+ *
+ * @deprecated Use `@EagerInstantiate` instead of `@EagerInstantiate()`.
  */
 declare function EagerInstantiate<This extends object>(): ClassDecorator<This>;
 
@@ -930,6 +949,21 @@ declare function OptionalAll<Value>(token: Token<Value>): ParameterDecorator;
  */
 declare function OptionalAll<Value>(tokens: TokenRef<Value>): ParameterDecorator;
 
+/**
+ * Class decorator that registers the decorated type with the **Container** scope.
+ *
+ * Use this scope when you want one cached instance per container,
+ * with parent-container lookup fallback.
+ *
+ * Example:
+ * ```ts
+ * @ContainerScoped
+ * class Wizard {
+ *   // ...
+ * }
+ * ```
+ */
+declare function ContainerScoped<This extends object, Ctor extends Constructor<This>>(target: Ctor): void;
 /**
  * Class decorator that registers the decorated type with the **Container** scope.
  *
@@ -943,8 +977,25 @@ declare function OptionalAll<Value>(tokens: TokenRef<Value>): ParameterDecorator
  *   // ...
  * }
  * ```
+ *
+ * @deprecated Use `@ContainerScoped` instead of `@ContainerScoped()`.
  */
 declare function ContainerScoped<This extends object>(): ClassDecorator<This>;
+/**
+ * Class decorator that registers the decorated type with the **Resolution** scope.
+ *
+ * Use this scope when you want one cached instance per resolution graph,
+ * so repeated resolutions within the same request reuse the same value.
+ *
+ * Example:
+ * ```ts
+ * @ResolutionScoped
+ * class Wand {
+ *   // ...
+ * }
+ * ```
+ */
+declare function ResolutionScoped<This extends object, Ctor extends Constructor<This>>(target: Ctor): void;
 /**
  * Class decorator that registers the decorated type with the **Resolution** scope.
  *
@@ -958,8 +1009,24 @@ declare function ContainerScoped<This extends object>(): ClassDecorator<This>;
  *   // ...
  * }
  * ```
+ *
+ * @deprecated Use `@ResolutionScoped` instead of `@ResolutionScoped()`.
  */
 declare function ResolutionScoped<This extends object>(): ClassDecorator<This>;
+/**
+ * Class decorator that registers the decorated type with the **Transient** scope.
+ *
+ * Use this scope when you want a fresh instance every time the class is resolved.
+ *
+ * Example:
+ * ```ts
+ * @TransientScoped
+ * class Wand {
+ *   // ...
+ * }
+ * ```
+ */
+declare function TransientScoped<This extends object, Ctor extends Constructor<This>>(target: Ctor): void;
 /**
  * Class decorator that registers the decorated type with the **Transient** scope.
  *
@@ -972,6 +1039,8 @@ declare function ResolutionScoped<This extends object>(): ClassDecorator<This>;
  *   // ...
  * }
  * ```
+ *
+ * @deprecated Use `@TransientScoped` instead of `@TransientScoped()`.
  */
 declare function TransientScoped<This extends object>(): ClassDecorator<This>;
 /**
@@ -1055,7 +1124,7 @@ declare function injectAll<Value>(token: Token<Value>): Value[];
  * @param Class - The class to resolve.
  * @param name - The name qualifier of the class to resolve.
  */
-declare function injectBy<Instance extends object>(thisArg: any, Class: Constructor<Instance>, name?: string): Instance;
+declare function injectBy<Instance extends object>(thisArg: object, Class: Constructor<Instance>, name?: string): Instance;
 /**
  * Injects the value associated with the given token.
  *
@@ -1079,7 +1148,7 @@ declare function injectBy<Instance extends object>(thisArg: any, Class: Construc
  * @param token - The token to resolve.
  * @param name - The name qualifier of the token to resolve.
  */
-declare function injectBy<Value>(thisArg: any, token: Token<Value>, name?: string): Value;
+declare function injectBy<Value>(thisArg: object, token: Token<Value>, name?: string): Value;
 
 /**
  * Asserts that the current stack frame is within an injection context,
@@ -1250,7 +1319,7 @@ declare function optionalAll<Value>(token: Token<Value>): Value[];
  * @param Class - The class to resolve.
  * @param name - The name qualifier of the class to resolve.
  */
-declare function optionalBy<Instance extends object>(thisArg: any, Class: Constructor<Instance>, name?: string): Instance | undefined;
+declare function optionalBy<Instance extends object>(thisArg: object, Class: Constructor<Instance>, name?: string): Instance | undefined;
 /**
  * Injects the value associated with the given token,
  * or `undefined` if the token is not registered in the container.
@@ -1262,7 +1331,7 @@ declare function optionalBy<Instance extends object>(thisArg: any, Class: Constr
  * @param token - The token to resolve.
  * @param name - The name qualifier of the token to resolve.
  */
-declare function optionalBy<Value>(thisArg: any, token: Token<Value>, name?: string): Value | undefined;
+declare function optionalBy<Value>(thisArg: object, token: Token<Value>, name?: string): Value | undefined;
 
 export { AutoRegister, ContainerScoped, EagerInstantiate, Inject, InjectAll, Injectable, Injector, Named, Optional, OptionalAll, ResolutionScoped, Scope, Scoped, TransientScoped, 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, Type, ValueProvider };

package/dist/es/index.mjs

@@ -52,14 +52,12 @@ function getTokenPath(tokens) {
 function getTokenName(token) {
     return token.name || "<unnamed>";
 }
+// @internal
 function getFullTokenName([token, name]) {
     const tokenName = token ? token.name || "<unnamed>" : "<undefined token>";
-    return name !== undefined ? `${tokenName}["${name}"]` : tokenName;
+    return name !== undefined ? `${tokenName}['${name}']` : tokenName;
 }
 function getCause(error) {
-    if (!error) {
-        return "";
-    }
     const msg = isError(error) ? error.message : String(error);
     return `\n  [cause] ${untag(msg)}`;
 }
@@ -437,24 +435,25 @@ function describeParam(target, methodKey, parameterIndex) {
 }
 
 // @__NO_SIDE_EFFECTS__
-function createType(typeName, provider, options) {
-    const name = `Type<${typeName}>`;
+function createType(debugName, provider, options) {
     const type = (target, propertyKey, parameterIndex)=>{
-        updateParameterMetadata(name, target, propertyKey, parameterIndex, (dependency)=>{
+        updateParameterMetadata(debugName, target, propertyKey, parameterIndex, (dependency)=>{
             checkSingleDecorator(dependency, target, propertyKey, parameterIndex);
             dependency.appliedBy = "Inject";
             dependency.tokenRef = tokenRef(()=>type);
         });
     };
+    const name = `Type<${debugName}>`;
     Object.defineProperty(type, "name", {
         value: name
     });
+    type.debugName = debugName;
+    type.__type = undefined;
+    type.toString = ()=>name;
     if (provider) {
         type.provider = provider;
         type.options = options;
     }
-    type.__type = undefined;
-    type.toString = ()=>name;
     return type;
 }
 // @internal
@@ -511,7 +510,10 @@ class TokenRegistry {
             const name = registration.name;
             if (name !== undefined) {
                 const existing = registrations.filter((r)=>r.name === name);
-                check(existing.length === 0, `token ${getTokenName(token)} with name '${name}' is already registered`);
+                check(existing.length === 0, `token ${getFullTokenName([
+                    token,
+                    name
+                ])} is already registered`);
             }
         } else {
             this.myRegistrations.set(token, registrations = []);
@@ -579,8 +581,8 @@ function isBuilder(provider) {
     return builders.has(provider);
 }
 // @__NO_SIDE_EFFECTS__
-function build(factory, name) {
-    const token = createType(name ?? `Build<${getTypeName(factory)}>`);
+function build(factory, debugName) {
+    const token = createType(debugName ?? `Build<${getTypeName(factory)}>`);
     const provider = {
         useFactory: factory
     };
@@ -1111,47 +1113,18 @@ function isDisposable(value) {
     return new ContainerImpl(undefined, options);
 }
 
-/**
- * Class decorator that enables auto-registration of an unregistered class
- * when the class is first resolved from the container.
- *
- * Example:
- * ```ts
- * @AutoRegister()
- * class Wizard {}
- *
- * const wizard = container.resolve(Wizard);
- * container.isRegistered(Wizard); // => true
- * ```
- */ // @__NO_SIDE_EFFECTS__
-function AutoRegister() {
-    return (Class)=>{
+// @__NO_SIDE_EFFECTS__
+function AutoRegister(target) {
+    const decorator = (Class)=>{
         const metadata = getMetadata(Class);
         metadata.autoRegister = true;
     };
+    return target === undefined ? decorator : decorator(target);
 }
 
-/**
- * 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 create and cache the instance of the class
- * immediately, instead of deferring it until the first resolution.
- *
- * If the class cannot be resolved at registration time, registration fails.
- *
- * Example:
- * ```ts
- * @EagerInstantiate()
- * class Wizard {}
- *
- * // Wizard is registered with Container scope, and an instance
- * // is created and cached immediately by the container
- * container.register(Wizard);
- * ```
- */ // @__NO_SIDE_EFFECTS__
-function EagerInstantiate() {
-    return (Class)=>{
+// @__NO_SIDE_EFFECTS__
+function EagerInstantiate(target) {
+    const decorator = (Class)=>{
         const metadata = getMetadata(Class);
         const currentScope = metadata.scope;
         check(!currentScope || currentScope.value === "Container", ()=>{
@@ -1166,6 +1139,7 @@ function EagerInstantiate() {
             appliedBy: "EagerInstantiate"
         };
     };
+    return target === undefined ? decorator : decorator(target);
 }
 
 // @__NO_SIDE_EFFECTS__
@@ -1275,55 +1249,20 @@ function OptionalAll(token) {
     };
 }
 
-/**
- * Class decorator that registers the decorated type with the **Container** scope.
- *
- * Use this scope when you want one cached instance per container,
- * with parent-container lookup fallback.
- *
- * Example:
- * ```ts
- * @ContainerScoped()
- * class Wizard {
- *   // ...
- * }
- * ```
- */ // @__NO_SIDE_EFFECTS__
-function ContainerScoped() {
-    return scoped("Container", "ContainerScoped");
+// @__NO_SIDE_EFFECTS__
+function ContainerScoped(target) {
+    const decorator = scoped("Container", "ContainerScoped");
+    return target === undefined ? decorator : decorator(target);
 }
-/**
- * Class decorator that registers the decorated type with the **Resolution** scope.
- *
- * Use this scope when you want one cached instance per resolution graph,
- * so repeated resolutions within the same request reuse the same value.
- *
- * Example:
- * ```ts
- * @ResolutionScoped()
- * class Wand {
- *   // ...
- * }
- * ```
- */ // @__NO_SIDE_EFFECTS__
-function ResolutionScoped() {
-    return scoped("Resolution", "ResolutionScoped");
+// @__NO_SIDE_EFFECTS__
+function ResolutionScoped(target) {
+    const decorator = scoped("Resolution", "ResolutionScoped");
+    return target === undefined ? decorator : decorator(target);
 }
-/**
- * Class decorator that registers the decorated type with the **Transient** scope.
- *
- * Use this scope when you want a fresh instance every time the class is resolved.
- *
- * Example:
- * ```ts
- * @TransientScoped()
- * class Wand {
- *   // ...
- * }
- * ```
- */ // @__NO_SIDE_EFFECTS__
-function TransientScoped() {
-    return scoped("Transient", "TransientScoped");
+// @__NO_SIDE_EFFECTS__
+function TransientScoped(target) {
+    const decorator = scoped("Transient", "TransientScoped");
+    return target === undefined ? decorator : decorator(target);
 }
 /**
  * Class decorator for setting the scope of the decorated type when registering it.