ts-ioc-container 72.1.0 → 72.2.0

package/esm/container/EmptyContainer.js

@@ -2,7 +2,7 @@ import { MethodNotImplementedError } from '../errors/MethodNotImplementedError.j
 import { DependencyNotFoundError } from '../errors/DependencyNotFoundError.js';
 export class EmptyContainer {
     get isDisposed() {
-        throw new MethodNotImplementedError();
+        throw new MethodNotImplementedError('EmptyContainer.isDisposed is not implemented');
     }
     addInstance(instance) { }
     getParent() {
@@ -18,25 +18,25 @@ export class EmptyContainer {
         return false;
     }
     createScope() {
-        throw new MethodNotImplementedError();
+        throw new MethodNotImplementedError('EmptyContainer.createScope is not implemented');
     }
     getInjector() {
-        throw new MethodNotImplementedError();
+        throw new MethodNotImplementedError('EmptyContainer.getInjector is not implemented');
     }
     autoResolve(options) {
-        throw new MethodNotImplementedError();
+        throw new MethodNotImplementedError('EmptyContainer.autoResolve is not implemented');
     }
     dispose() {
-        throw new MethodNotImplementedError();
+        throw new MethodNotImplementedError('EmptyContainer.dispose is not implemented');
     }
     register(key, value) {
-        throw new MethodNotImplementedError();
+        throw new MethodNotImplementedError('EmptyContainer.register is not implemented');
     }
     hasTag(tag) {
-        throw new MethodNotImplementedError();
+        throw new MethodNotImplementedError('EmptyContainer.hasTag is not implemented');
     }
     addTags(...tags) {
-        throw new MethodNotImplementedError();
+        throw new MethodNotImplementedError('EmptyContainer.addTags is not implemented');
     }
     getRegistrations() {
         return [];
@@ -46,27 +46,29 @@ export class EmptyContainer {
     }
     removeScope() { }
     useModule(module) {
-        throw new MethodNotImplementedError();
+        throw new MethodNotImplementedError('EmptyContainer.useModule is not implemented');
     }
     addRegistration(registration) {
-        throw new MethodNotImplementedError();
+        throw new MethodNotImplementedError('EmptyContainer.addRegistration is not implemented');
     }
     resolve(key, options) {
-        throw new DependencyNotFoundError(`Cannot find ${key.toString()}`);
+        throw new DependencyNotFoundError(`Cannot find ${key.toString()}: no provider for this key in the resolving scope or any parent. ` +
+            'Check that it is registered, that its scope(...) rule matches this scope, that its scopeAccess(...) rule allows it, ' +
+            'and that it was registered before createScope() (existing child scopes are not updated).');
     }
     resolveByAlias(alias, options) {
         return [];
     }
     resolveOneByAlias(alias, options) {
-        throw new DependencyNotFoundError(`Cannot find alias ${alias.toString()}`);
+        throw new DependencyNotFoundError(`Cannot find alias ${alias.toString()}: no accessible registration carries this alias in the resolving scope or any parent.`);
     }
     get scopeCreated() {
-        throw new MethodNotImplementedError();
+        throw new MethodNotImplementedError('EmptyContainer.scopeCreated is not implemented');
     }
     get scopeDisposed() {
-        throw new MethodNotImplementedError();
+        throw new MethodNotImplementedError('EmptyContainer.scopeDisposed is not implemented');
     }
     get registered() {
-        throw new MethodNotImplementedError();
+        throw new MethodNotImplementedError('EmptyContainer.registered is not implemented');
     }
 }

package/esm/errors/ArgumentNotFoundError.js

@@ -1,6 +1,7 @@
 import { ContainerError } from './ContainerError.js';
 export class ArgumentNotFoundError extends ContainerError {
     name = 'ArgumentNotFoundError';
+    code = 'IOC_ARGUMENT_NOT_FOUND';
     constructor(message = 'Argument not found') {
         super(message);
         Object.setPrototypeOf(this, ArgumentNotFoundError.prototype);

package/esm/errors/CannonSingletonApplyTwiceError.js

@@ -1,13 +1,2 @@
-import { ContainerError } from './ContainerError.js';
-export class CannonSingletonApplyTwiceError extends ContainerError {
-    name = 'CannonSingletonApplyTwiceError';
-    constructor(message) {
-        super(message);
-        Object.setPrototypeOf(this, CannonSingletonApplyTwiceError.prototype);
-    }
-    static assert(isTrue, failMessage) {
-        if (!isTrue) {
-            throw new CannonSingletonApplyTwiceError(failMessage);
-        }
-    }
-}
+import { CannotApplySingletonTwiceError } from './CannotApplySingletonTwiceError.js';
+export const CannonSingletonApplyTwiceError = CannotApplySingletonTwiceError;

package/esm/errors/CannotApplySingletonTwiceError.js

@@ -0,0 +1,14 @@
+import { ContainerError } from './ContainerError.js';
+export class CannotApplySingletonTwiceError extends ContainerError {
+    name = 'CannotApplySingletonTwiceError';
+    code = 'IOC_SINGLETON_APPLIED_TWICE';
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, CannotApplySingletonTwiceError.prototype);
+    }
+    static assert(isTrue, failMessage) {
+        if (!isTrue) {
+            throw new CannotApplySingletonTwiceError(failMessage);
+        }
+    }
+}

package/esm/errors/ContainerDisposedError.js

@@ -1,6 +1,7 @@
 import { ContainerError } from './ContainerError.js';
 export class ContainerDisposedError extends ContainerError {
     name = 'ContainerDisposedError';
+    code = 'IOC_CONTAINER_DISPOSED';
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, ContainerDisposedError.prototype);

package/esm/errors/ContainerError.js

@@ -1,5 +1,6 @@
 export class ContainerError extends Error {
     name = 'ContainerError';
+    code = 'IOC_CONTAINER_ERROR';
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, ContainerError.prototype);

package/esm/errors/ContainerNotFoundError.js

@@ -1,6 +1,7 @@
 import { ContainerError } from './ContainerError.js';
 export class ContainerNotFoundError extends ContainerError {
     name = 'ContainerNotFoundError';
+    code = 'IOC_CONTAINER_NOT_FOUND';
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, ContainerNotFoundError.prototype);

package/esm/errors/DependencyMissingKeyError.js

@@ -1,6 +1,7 @@
 import { ContainerError } from './ContainerError.js';
 export class DependencyMissingKeyError extends ContainerError {
     name = 'DependencyMissingKeyError';
+    code = 'IOC_DEPENDENCY_MISSING_KEY';
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, DependencyMissingKeyError.prototype);

package/esm/errors/DependencyNotFoundError.js

@@ -1,6 +1,7 @@
 import { ContainerError } from './ContainerError.js';
 export class DependencyNotFoundError extends ContainerError {
     name = 'DependencyNotFoundError';
+    code = 'IOC_DEPENDENCY_NOT_FOUND';
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, DependencyNotFoundError.prototype);

package/esm/errors/MethodNotImplementedError.js

@@ -1,6 +1,7 @@
 import { ContainerError } from './ContainerError.js';
 export class MethodNotImplementedError extends ContainerError {
     name = 'MethodNotImplementedError';
+    code = 'IOC_METHOD_NOT_IMPLEMENTED';
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, MethodNotImplementedError.prototype);

package/esm/errors/ProviderDisposedError.js

@@ -1,6 +1,7 @@
 import { ContainerError } from './ContainerError.js';
 export class ProviderDisposedError extends ContainerError {
     name = 'ProviderDisposedError';
+    code = 'IOC_PROVIDER_DISPOSED';
     static assert(isTrue, failMessage) {
         if (!isTrue) {
             throw new ProviderDisposedError(failMessage);

package/esm/errors/TypedEventDisposedError.js

@@ -1,6 +1,7 @@
 import { ContainerError } from './ContainerError.js';
 export class TypedEventDisposedError extends ContainerError {
     name = 'TypedEventDisposedError';
+    code = 'IOC_EVENT_DISPOSED';
     static assert(isTrue, failMessage) {
         if (!isTrue) {
             throw new TypedEventDisposedError(failMessage);

package/esm/errors/UnsupportedTokenTypeError.js

@@ -1,6 +1,7 @@
 import { ContainerError } from './ContainerError.js';
 export class UnsupportedTokenTypeError extends ContainerError {
     name = 'UnsupportedTokenTypeError';
+    code = 'IOC_UNSUPPORTED_TOKEN_TYPE';
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, UnsupportedTokenTypeError.prototype);

package/esm/index.js

@@ -16,6 +16,7 @@ export { DependencyMissingKeyError } from './errors/DependencyMissingKeyError.js
 export { MethodNotImplementedError } from './errors/MethodNotImplementedError.js';
 export { ContainerDisposedError } from './errors/ContainerDisposedError.js';
 export { ProviderDisposedError } from './errors/ProviderDisposedError.js';
+export { CannotApplySingletonTwiceError } from './errors/CannotApplySingletonTwiceError.js';
 export { CannonSingletonApplyTwiceError } from './errors/CannonSingletonApplyTwiceError.js';
 export { UnsupportedTokenTypeError } from './errors/UnsupportedTokenTypeError.js';
 export { TypedEventDisposedError } from './errors/TypedEventDisposedError.js';

package/esm/provider/Provider.js

@@ -1,5 +1,5 @@
 import { toString } from '../utils/basic.js';
-import { CannonSingletonApplyTwiceError } from '../errors/CannonSingletonApplyTwiceError.js';
+import { CannotApplySingletonTwiceError } from '../errors/CannotApplySingletonTwiceError.js';
 import { ProviderDisposedError } from '../errors/ProviderDisposedError.js';
 export class Provider {
     resolveDependency;
@@ -25,7 +25,7 @@ export class Provider {
         this.resolveDependency = resolveDependency;
     }
     resolve(options) {
-        ProviderDisposedError.assert(!this.isDisposed, 'Provider is already disposed');
+        ProviderDisposedError.assert(!this.isDisposed, 'Provider is already disposed: its scope was disposed. Resolve from a live scope.');
         if (!this.getKey) {
             return this.resolveDep(options);
         }
@@ -64,7 +64,7 @@ export class Provider {
         return this;
     }
     isAutoResolvable() {
-        ProviderDisposedError.assert(!this.isDisposed, 'Provider is already disposed');
+        ProviderDisposedError.assert(!this.isDisposed, 'Provider is already disposed: its scope was disposed. Resolve from a live scope.');
         return this.isAutoResolve;
     }
     addArgsFn(...fns) {
@@ -72,11 +72,11 @@ export class Provider {
         return this;
     }
     hasAccess(options) {
-        ProviderDisposedError.assert(!this.isDisposed, 'Provider is already disposed');
+        ProviderDisposedError.assert(!this.isDisposed, 'Provider is already disposed: its scope was disposed. Resolve from a live scope.');
         return this.accessRules.reduce((acc, rule) => rule(options, acc), true);
     }
     singleton(getCacheKey = () => '1') {
-        CannonSingletonApplyTwiceError.assert(!this.getKey, 'Provider is already singleton');
+        CannotApplySingletonTwiceError.assert(!this.getKey, 'Provider is already singleton: singleton() was applied twice to the same provider. Remove the duplicate singleton().');
         this.getKey = getCacheKey;
         return this;
     }
@@ -85,7 +85,7 @@ export class Provider {
         return this;
     }
     dispose() {
-        ProviderDisposedError.assert(!this.isDisposed, 'Provider is already disposed');
+        ProviderDisposedError.assert(!this.isDisposed, 'Provider is already disposed: its scope was disposed. Resolve from a live scope.');
         this.isDisposed = true;
         this.isAutoResolve = false;
         this.getKey = undefined;

package/esm/registration/Registration.js

@@ -59,14 +59,14 @@ export class Registration {
             return;
         }
         if (!this.key) {
-            throw new DependencyMissingKeyError('No key provided for registration');
+            throw new DependencyMissingKeyError('No key provided for registration: bind it with @register(bindTo(...)) or .bindTo(...).');
         }
         const provider = this.mappers.reduce((p, m) => m(p), this.createProvider());
         container.register(this.key, provider, { aliases: [...this.aliases] });
     }
     getKeyOrFail() {
         if (!this.key) {
-            throw new DependencyMissingKeyError('No key provided for registration');
+            throw new DependencyMissingKeyError('No key provided for registration: bind it with @register(bindTo(...)) or .bindTo(...).');
         }
         return this.key;
     }

package/esm/token/ConstantToken.js

@@ -10,18 +10,18 @@ export class ConstantToken extends InjectionToken {
         return this.token;
     }
     args(...deps) {
-        throw new MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError('ConstantToken.args is not implemented');
     }
     argsFn(getArgsFn) {
-        throw new MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError('ConstantToken.argsFn is not implemented');
     }
     lazy() {
-        throw new MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError('ConstantToken.lazy is not implemented');
     }
     addTags(...tags) {
         return new ConstantToken(this.token, { tags: [...this.getTags(), ...tags] });
     }
     toString() {
-        throw new MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError('ConstantToken.toString is not implemented');
     }
 }

package/esm/token/FunctionToken.js

@@ -48,6 +48,6 @@ export class FunctionToken extends InjectionToken {
         });
     }
     toString() {
-        throw new MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError('FunctionToken.toString is not implemented');
     }
 }

package/esm/token/GroupInstanceToken.js

@@ -12,13 +12,13 @@ export class GroupInstanceToken extends InjectionToken {
         return (s) => this.resolve(s).map(fn);
     }
     args(...deps) {
-        throw new MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError('GroupInstanceToken.args is not implemented');
     }
     argsFn(getArgsFn) {
-        throw new MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError('GroupInstanceToken.argsFn is not implemented');
     }
     lazy() {
-        throw new MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError('GroupInstanceToken.lazy is not implemented');
     }
     cascade(isTrue) {
         this.isCascade = isTrue;
@@ -31,6 +31,6 @@ export class GroupInstanceToken extends InjectionToken {
         return new GroupInstanceToken(this.predicate, { tags: [...this.getTags(), ...tags], isCascade: this.isCascade });
     }
     toString() {
-        throw new MethodNotImplementedError('not implemented');
+        throw new MethodNotImplementedError('GroupInstanceToken.toString is not implemented');
     }
 }

package/esm/token/toToken.js

@@ -19,6 +19,6 @@ export const toToken = (token) => {
     if (typeof token === 'function') {
         return new FunctionToken(token);
     }
-    throw new UnsupportedTokenTypeError(`Unknown token ${token}`);
+    throw new UnsupportedTokenTypeError(`Unknown token ${token}: expected an InjectionToken, a DependencyKey (string | symbol), a class or a function.`);
 };
 export const argToToken = (v) => (isInjectionToken(v) ? v : new ConstantToken(v));

package/esm/utils/TypedEvent.js

@@ -26,6 +26,6 @@ export class TypedEvent {
         this.isDisposed = true;
     }
     validate() {
-        TypedEventDisposedError.assert(!this.isDisposed, 'TypedEvent is already disposed');
+        TypedEventDisposedError.assert(!this.isDisposed, 'TypedEvent is already disposed: its scope was disposed, so it accepts no new listeners.');
     }
 }

package/esm/utils/array.js

@@ -8,7 +8,7 @@ export const Filter = {
 export const findOrFail = (predicate) => (args = []) => {
     const index = args.findIndex((arg) => predicate(arg));
     if (index === -1) {
-        throw new ArgumentNotFoundError();
+        throw new ArgumentNotFoundError(`No argument matches the predicate (received ${args.length} args).`);
     }
     return args[index];
 };

package/lib/ExecutionContext.ts

@@ -0,0 +1,6 @@
+import type { IContainer } from './container/IContainer';
+
+/** General execution context passed to callbacks that run within a scope. */
+export interface ExecutionContext {
+  scope: IContainer;
+}

package/lib/container/AliasMap.ts

@@ -0,0 +1,30 @@
+import { type DependencyKey } from './IContainer';
+
+export type Alias = DependencyKey;
+
+export class AliasMap {
+  private readonly aliasToKeySet = new Map<Alias, Set<DependencyKey>>();
+
+  getKeysByAlias(alias: DependencyKey): DependencyKey[] {
+    return [...(this.aliasToKeySet.get(alias) ?? [])];
+  }
+
+  setAliasesByKey(key: DependencyKey, aliases: DependencyKey[]): void {
+    // reset existing key's aliases
+    for (const [alias, keySet] of this.aliasToKeySet) {
+      keySet.delete(key);
+      if (keySet.size === 0) {
+        this.aliasToKeySet.delete(alias);
+      }
+    }
+
+    for (const alias of aliases) {
+      const dependencyKeySet = this.aliasToKeySet.get(alias) ?? new Set();
+      this.aliasToKeySet.set(alias, dependencyKeySet.add(key));
+    }
+  }
+
+  destroy(): void {
+    this.aliasToKeySet.clear();
+  }
+}

package/lib/container/AutoResolveModule.ts

@@ -0,0 +1,24 @@
+import { type AutoResolveOptions, type IContainer, type IContainerModule } from './IContainer';
+
+/**
+ * Enables eager resolution of providers marked with the `autoResolve()` pipe.
+ *
+ * Every scope created after this module is applied resolves its own
+ * auto-resolvable providers as part of `createScope`, so the instances exist
+ * before anyone asks for them. Child scopes inherit the behaviour, so a single
+ * `useModule` call on the root covers the whole scope tree.
+ *
+ * `options.args` are forwarded to every eagerly resolved provider of every such
+ * scope. Pass a per-scope value by calling `scope.autoResolve({ args })`
+ * directly instead.
+ *
+ * The container the module is applied to is not a created scope — call
+ * `container.autoResolve()` explicitly to eagerly resolve its own providers.
+ */
+export class AutoResolveModule implements IContainerModule {
+  constructor(private readonly options: AutoResolveOptions = {}) {}
+
+  applyTo(container: IContainer): void {
+    container.scopeCreated.subscribe((scope) => scope.autoResolve(this.options));
+  }
+}