@lppedd/di-wise-neo 0.22.0 → 0.23.0

package/dist/cjs/index.d.ts

@@ -682,8 +682,10 @@ 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 immediately create and cache the instance of the class,
- * instead of deferring instantiation until the first resolution.
+ * 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
@@ -691,7 +693,7 @@ declare function AutoRegister<This extends object>(): ClassDecorator<This>;
  * class Wizard {}
  *
  * // Wizard is registered with Container scope, and an instance
- * // is immediately created and cached by the container
+ * // is created and cached immediately by the container
  * container.register(Wizard);
  * ```
  */
@@ -702,8 +704,9 @@ declare function EagerInstantiate<This extends object>(): ClassDecorator<This>;
  *
  * Throws an error if:
  * - The class is not registered in the container.
- * - A circular dependency is detected. Use function injection with {@link injectBy}
- *   if resolving circular dependencies is necessary.
+ * - A circular dependency is detected.
+ *
+ * Use {@link injectBy} when you need to resolve circular dependencies.
  */
 declare function Inject<Instance extends object>(Class: Constructor<Instance>): ParameterDecorator;
 /**
@@ -711,8 +714,9 @@ declare function Inject<Instance extends object>(Class: Constructor<Instance>):
  *
  * Throws an error if:
  * - The token is not registered in the container.
- * - A circular dependency is detected. Use function injection with {@link injectBy}
- *   if resolving circular dependencies is necessary.
+ * - A circular dependency is detected.
+ *
+ * Use {@link injectBy} when you need to resolve circular dependencies.
  */
 declare function Inject<Value>(token: Token<Value>): ParameterDecorator;
 /**
@@ -723,8 +727,9 @@ declare function Inject<Value>(token: Token<Value>): ParameterDecorator;
  *
  * Throws an error if:
  * - The token is not registered in the container.
- * - A circular dependency is detected. Use function injection with {@link injectBy}
- *   if resolving circular dependencies is necessary.
+ * - A circular dependency is detected.
+ *
+ * Use function injection with {@link injectBy} when you need to resolve circular dependencies.
  *
  * Example:
  * ```ts
@@ -833,17 +838,18 @@ declare function InjectAll<Value>(token: Token<Value>): ParameterDecorator;
 declare function InjectAll<Value>(tokens: TokenRef<Value>): ParameterDecorator;
 
 /**
- * Qualifies a class or an injected parameter with a unique name.
+ * Qualifies a class or an injected parameter with a name.
  *
- * This allows the container to distinguish between multiple implementations
- * of the same interface or type during registration and injection.
+ * On a class, the name is used when registering that class with the container.
+ * On a parameter, the name selects a named registration or alias during injection.
+ *
+ * This is useful when multiple registrations exist for the same token.
  *
  * Example:
  * ```ts
  * @Named("dumbledore")
  * class Dumbledore implements Wizard {}
  *
- * // Register Dumbledore with Type<Wizard>
  * container.register(IWizard, { useClass: Dumbledore });
  * const dumbledore = container.resolve(IWizard, "dumbledore");
  * ```
@@ -855,7 +861,7 @@ declare function Named<This extends object>(name: string): ClassDecorator<This>
  * or `undefined` if the class is not registered in the container.
  *
  * Throws an error if a circular dependency is detected. Use function injection
- * with {@link optionalBy} if resolving circular dependencies is necessary.
+ * with {@link optionalBy} when you need to resolve circular dependencies.
  */
 declare function Optional<Instance extends object>(Class: Constructor<Instance>): ParameterDecorator;
 /**
@@ -863,7 +869,7 @@ declare function Optional<Instance extends object>(Class: Constructor<Instance>)
  * or `undefined` if the token is not registered in the container.
  *
  * Throws an error if a circular dependency is detected. Use function injection
- * with {@link optionalBy} if resolving circular dependencies is necessary.
+ * with {@link optionalBy} when you need to resolve circular dependencies.
  */
 declare function Optional<Value>(token: Token<Value>): ParameterDecorator;
 /**
@@ -874,7 +880,7 @@ declare function Optional<Value>(token: Token<Value>): ParameterDecorator;
  * the {@link tokenRef} helper function.
  *
  * Throws an error if a circular dependency is detected. Use function injection
- * with {@link optionalBy} if resolving circular dependencies is necessary.
+ * with {@link optionalBy} when you need to resolve circular dependencies.
  *
  * Example:
  * ```ts
@@ -924,6 +930,50 @@ 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>(): 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>(): 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>(): ClassDecorator<This>;
 /**
  * Class decorator for setting the scope of the decorated type when registering it.
  *
@@ -1162,7 +1212,7 @@ declare function setClassIdentityMapping<T extends object>(transformedClass: Con
  * or `undefined` if the class is not registered in the container.
  *
  * Throws an error if a circular dependency is detected.
- * Use {@link optionalBy} if resolving circular dependencies is necessary.
+ * Use {@link optionalBy} when you need to resolve circular dependencies.
  */
 declare function optional<Instance extends object>(Class: Constructor<Instance>, name?: string): Instance | undefined;
 /**
@@ -1170,7 +1220,7 @@ declare function optional<Instance extends object>(Class: Constructor<Instance>,
  * or `undefined` if the token is not registered in the container.
  *
  * Throws an error if a circular dependency is detected.
- * Use {@link optionalBy} if resolving circular dependencies is necessary.
+ * Use {@link optionalBy} when you need to resolve circular dependencies.
  */
 declare function optional<Value>(token: Token<Value>, name?: string): Value | undefined;
 
@@ -1214,5 +1264,5 @@ declare function optionalBy<Instance extends object>(thisArg: any, Class: Constr
  */
 declare function optionalBy<Value>(thisArg: any, token: Token<Value>, name?: string): Value | undefined;
 
-export { AutoRegister, EagerInstantiate, Inject, InjectAll, Injectable, Injector, Named, Optional, OptionalAll, Scope, Scoped, assertInjectionContext, build, classRef, createContainer, createType, inject, injectAll, injectBy, optional, optionalAll, optionalBy, setClassIdentityMapping, tokenRef };
+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/cjs/index.js

@@ -441,14 +441,13 @@ function describeParam(target, methodKey, parameterIndex) {
 // @__NO_SIDE_EFFECTS__
 function createType(typeName, provider, options) {
     const name = `Type<${typeName}>`;
-    const decorator = (target, propertyKey, parameterIndex)=>{
+    const type = (target, propertyKey, parameterIndex)=>{
         updateParameterMetadata(name, target, propertyKey, parameterIndex, (dependency)=>{
             checkSingleDecorator(dependency, target, propertyKey, parameterIndex);
             dependency.appliedBy = "Inject";
-            dependency.tokenRef = tokenRef(()=>decorator);
+            dependency.tokenRef = tokenRef(()=>type);
         });
     };
-    const type = decorator;
     Object.defineProperty(type, "name", {
         value: name
     });
@@ -1128,7 +1127,7 @@ function isDisposable(value) {
  * ```
  */ // @__NO_SIDE_EFFECTS__
 function AutoRegister() {
-    return function(Class) {
+    return (Class)=>{
         const metadata = getMetadata(Class);
         metadata.autoRegister = true;
     };
@@ -1138,8 +1137,10 @@ function AutoRegister() {
  * 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.
+ * 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
@@ -1147,18 +1148,19 @@ function AutoRegister() {
  * class Wizard {}
  *
  * // Wizard is registered with Container scope, and an instance
- * // is immediately created and cached by the container
+ * // is created and cached immediately by the container
  * container.register(Wizard);
  * ```
  */ // @__NO_SIDE_EFFECTS__
 function EagerInstantiate() {
-    return function(Class) {
+    return (Class)=>{
         const metadata = getMetadata(Class);
         const currentScope = metadata.scope;
         check(!currentScope || currentScope.value === "Container", ()=>{
             const { value, appliedBy } = currentScope;
+            const by = appliedBy === "Scoped" ? `${appliedBy}(${value})` : appliedBy;
             const className = getTokenName(Class);
-            return `class ${className}: 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.`;
+            return `class ${className}: scope ${value} was already set by @${by},\n  ` + `but @EagerInstantiate is trying to set a conflicting scope Container.\n  ` + `Only one decorator should set the class scope, or all must use the same value.`;
         });
         metadata.eagerInstantiate = true;
         metadata.scope = {
@@ -1170,7 +1172,7 @@ function EagerInstantiate() {
 
 // @__NO_SIDE_EFFECTS__
 function Inject(token) {
-    return function(target, propertyKey, parameterIndex) {
+    return (target, propertyKey, parameterIndex)=>{
         updateParameterMetadata("Inject", target, propertyKey, parameterIndex, (dependency)=>{
             checkSingleDecorator(dependency, target, propertyKey, parameterIndex);
             dependency.appliedBy = "Inject";
@@ -1181,7 +1183,7 @@ function Inject(token) {
 
 // @__NO_SIDE_EFFECTS__
 function Injectable(...args) {
-    return function(Class) {
+    return (Class)=>{
         const metadata = getMetadata(Class);
         const arg0 = args[0];
         const ref = isTokenRef(arg0) ? arg0 : tokenRef(()=>args);
@@ -1201,7 +1203,7 @@ function Injectable(...args) {
 
 // @__NO_SIDE_EFFECTS__
 function InjectAll(token) {
-    return function(target, propertyKey, parameterIndex) {
+    return (target, propertyKey, parameterIndex)=>{
         updateParameterMetadata("InjectAll", target, propertyKey, parameterIndex, (dependency)=>{
             checkSingleDecorator(dependency, target, propertyKey, parameterIndex);
             dependency.appliedBy = "InjectAll";
@@ -1212,24 +1214,25 @@ function InjectAll(token) {
 }
 
 /**
- * Qualifies a class or an injected parameter with a unique name.
+ * Qualifies a class or an injected parameter with a name.
+ *
+ * On a class, the name is used when registering that class with the container.
+ * On a parameter, the name selects a named registration or alias during injection.
  *
- * This allows the container to distinguish between multiple implementations
- * of the same interface or type during registration and injection.
+ * This is useful when multiple registrations exist for the same token.
  *
  * Example:
  * ```ts
  * @Named("dumbledore")
  * class Dumbledore implements Wizard {}
  *
- * // Register Dumbledore with Type<Wizard>
  * container.register(IWizard, { useClass: Dumbledore });
  * const dumbledore = container.resolve(IWizard, "dumbledore");
  * ```
  */ // @__NO_SIDE_EFFECTS__
 function Named(name) {
     check(name.trim(), "@Named qualifier must not be empty");
-    return function(target, propertyKey, parameterIndex) {
+    return (target, propertyKey, parameterIndex)=>{
         if (parameterIndex === undefined) {
             // The decorator has been applied to the class
             const Class = target;
@@ -1253,7 +1256,7 @@ function Named(name) {
 
 // @__NO_SIDE_EFFECTS__
 function Optional(token) {
-    return function(target, propertyKey, parameterIndex) {
+    return (target, propertyKey, parameterIndex)=>{
         updateParameterMetadata("Optional", target, propertyKey, parameterIndex, (dependency)=>{
             checkSingleDecorator(dependency, target, propertyKey, parameterIndex);
             dependency.appliedBy = "Optional";
@@ -1264,7 +1267,7 @@ function Optional(token) {
 
 // @__NO_SIDE_EFFECTS__
 function OptionalAll(token) {
-    return function(target, propertyKey, parameterIndex) {
+    return (target, propertyKey, parameterIndex)=>{
         updateParameterMetadata("OptionalAll", target, propertyKey, parameterIndex, (dependency)=>{
             checkSingleDecorator(dependency, target, propertyKey, parameterIndex);
             dependency.appliedBy = "OptionalAll";
@@ -1274,6 +1277,56 @@ 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");
+}
+/**
+ * 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");
+}
+/**
+ * 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");
+}
 /**
  * Class decorator for setting the scope of the decorated type when registering it.
  *
@@ -1295,18 +1348,21 @@ function OptionalAll(token) {
  * ```
  */ // @__NO_SIDE_EFFECTS__
 function Scoped(scope) {
-    return function(Class) {
+    return scoped(scope, "Scoped");
+}
+function scoped(scope, decorator) {
+    return (Class)=>{
         const metadata = getMetadata(Class);
         const currentScope = metadata.scope;
         check(!currentScope || currentScope.value === scope, ()=>{
             const { value, appliedBy } = currentScope;
-            const by = appliedBy === "Scoped" ? `another @${appliedBy} decorator` : `@${appliedBy}`;
+            const by = appliedBy === "Scoped" ? `${appliedBy}(${value})` : appliedBy;
             const className = getTokenName(Class);
-            return `class ${className}: 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.`;
+            return `class ${className}: scope ${value} was already set by @${by},\n  ` + `but @${decorator} is trying to set a conflicting scope ${scope}.\n  ` + `Only one decorator should set the class scope, or all must use the same value.`;
         });
         metadata.scope = {
             value: scope,
-            appliedBy: "Scoped"
+            appliedBy: decorator
         };
     };
 }
@@ -1370,6 +1426,7 @@ const Scope = {
 };
 
 exports.AutoRegister = AutoRegister;
+exports.ContainerScoped = ContainerScoped;
 exports.EagerInstantiate = EagerInstantiate;
 exports.Inject = Inject;
 exports.InjectAll = InjectAll;
@@ -1378,8 +1435,10 @@ exports.Injector = Injector;
 exports.Named = Named;
 exports.Optional = Optional;
 exports.OptionalAll = OptionalAll;
+exports.ResolutionScoped = ResolutionScoped;
 exports.Scope = Scope;
 exports.Scoped = Scoped;
+exports.TransientScoped = TransientScoped;
 exports.assertInjectionContext = assertInjectionContext;
 exports.build = build;
 exports.classRef = classRef;