ts-ioc-container 72.1.0 → 72.3.0

package/esm/token/SingleToken.js

@@ -1,57 +1,12 @@
-import { forwardArgs, InjectionToken } from './InjectionToken.js';
-export class SingleToken extends InjectionToken {
-    token;
-    _getArgsFn;
-    _isLazy;
-    constructor(token, { getArgsFn = forwardArgs, isLazy = false, tags = [], } = {}) {
-        super(tags);
-        this.token = token;
-        this._getArgsFn = getArgsFn;
-        this._isLazy = isLazy;
-    }
+import { BindableToken } from './BindableToken.js';
+export class SingleToken extends BindableToken {
     select(fn) {
         return (s) => fn(this.resolve(s));
     }
-    resolve(s, { args = [], lazy } = {}) {
-        return s.resolve(this.token, {
-            args: this._getArgsFn({ scope: s, args }),
-            lazy: this._isLazy || lazy,
-        });
+    resolve(s, options) {
+        return s.resolve(this.token, this.toResolveOptions(s, options));
     }
-    bindTo(r) {
+    bindKey(r) {
         r.bindToKey(this.token);
     }
-    args(...newArgs) {
-        const parentFn = this._getArgsFn;
-        return new SingleToken(this.token, {
-            getArgsFn: (options) => [...parentFn(options), ...newArgs],
-            isLazy: this._isLazy,
-            tags: this.getTags(),
-        });
-    }
-    argsFn(fn) {
-        const parentFn = this._getArgsFn;
-        return new SingleToken(this.token, {
-            getArgsFn: (options) => [...parentFn(options), ...fn(options.scope)],
-            isLazy: this._isLazy,
-            tags: this.getTags(),
-        });
-    }
-    lazy() {
-        return new SingleToken(this.token, {
-            getArgsFn: this._getArgsFn,
-            isLazy: true,
-            tags: this.getTags(),
-        });
-    }
-    addTags(...tags) {
-        return new SingleToken(this.token, {
-            getArgsFn: this._getArgsFn,
-            isLazy: this._isLazy,
-            tags: [...this.getTags(), ...tags],
-        });
-    }
-    toString() {
-        return this.token.toString();
-    }
 }

package/esm/token/ToggleFeatureToken.js

@@ -0,0 +1,6 @@
+import { MultiVariantFeatureToken } from './MultiVariantFeatureToken.js';
+export class ToggleFeatureToken extends MultiVariantFeatureToken {
+    evaluate(flags, context) {
+        return { enabled: flags.isEnabled(this.flag, context) };
+    }
+}

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));
+  }
+}

package/lib/container/Container.ts

@@ -0,0 +1,315 @@
+import {
+  type AutoResolveOptions,
+  type CreateScopeOptions,
+  type DependencyKey,
+  type IContainer,
+  type IContainerModule,
+  type RegisterOptions,
+  ResolveManyOptions,
+  type ResolveOneOptions,
+  type Tag,
+} from './IContainer';
+import { type IInjector } from '../injector/IInjector';
+import { type IProvider } from '../provider/IProvider';
+import { EmptyContainer } from './EmptyContainer';
+import { type IRegistration } from '../registration/IRegistration';
+import { ContainerDisposedError } from '../errors/ContainerDisposedError';
+import { MetadataInjector } from '../injector/MetadataInjector';
+import { AliasMap } from './AliasMap';
+import { unwrapProxy } from '../utils/ProxyRegistry';
+import { DependencyNotFoundError } from '../errors/DependencyNotFoundError';
+import { constructor, Instance, Is } from '../utils/basic';
+import { Filter as F } from '../utils/array';
+import { type ITypedEvent, TypedEvent } from '../utils/TypedEvent';
+
+/**
+ * A dependency injection scope. Each container is a node in a parent chain:
+ * a key not found here (or denied by `scopeAccess`) is resolved from the parent,
+ * and the root's parent is an {@link EmptyContainer} that throws
+ * `DependencyNotFoundError`. Child scopes come from `createScope({ tags })`,
+ * which copies the matching registrations into the child at that moment.
+ *
+ * @example
+ * const app = new Container({ tags: ['application'] })
+ *   .addRegistration(Registration.fromClass(Logger))
+ *   .addRegistration(Registration.fromValue(config).bindTo('Config'));
+ *
+ * const request = app.createScope({ tags: ['request'] });
+ * const logger = ILoggerToken.resolve(request);
+ * request.dispose();
+ */
+export class Container implements IContainer {
+  isDisposed = false;
+  private parent: IContainer;
+  private scopes: IContainer[] = [];
+  private readonly instances = new Set<Instance>();
+  private registrations: IRegistration[] = [];
+  private readonly tags: Set<Tag>;
+  private readonly providers = new Map<DependencyKey, IProvider>();
+  private readonly aliases = new AliasMap();
+  private readonly injector: IInjector;
+
+  // The concrete events stay private so `emit` is this container's alone; the
+  // public properties expose the subscriber's side only.
+  private readonly scopeCreatedEvent = new TypedEvent<[IContainer]>();
+  private readonly scopeDisposedEvent = new TypedEvent<[IContainer]>();
+  private readonly registeredEvent = new TypedEvent<[IProvider, DependencyKey, IContainer]>();
+  readonly scopeCreated: ITypedEvent<[IContainer]> = this.scopeCreatedEvent;
+  readonly scopeDisposed: ITypedEvent<[IContainer]> = this.scopeDisposedEvent;
+  readonly registered: ITypedEvent<[IProvider, DependencyKey, IContainer]> = this.registeredEvent;
+
+  constructor(
+    options: {
+      injector?: IInjector;
+      parent?: IContainer;
+      tags?: Tag[];
+    } = {},
+  ) {
+    this.injector = options.injector ?? new MetadataInjector();
+    this.parent = options.parent ?? new EmptyContainer();
+    this.tags = new Set(options.tags ?? []);
+  }
+
+  /**
+   * @throws {ContainerDisposedError} when the container has already been disposed.
+   */
+  register(key: DependencyKey, provider: IProvider, { aliases = [] }: RegisterOptions = {}): this {
+    this.validateContainer();
+    this.providers.set(key, provider);
+    this.aliases.setAliasesByKey(key, aliases);
+
+    // Hooks run once the provider and its aliases are in place, so they observe a resolvable key.
+    this.registeredEvent.emit(provider, key, this);
+
+    return this;
+  }
+
+  /**
+   * @throws {ContainerDisposedError} when the container has already been disposed.
+   * @throws {DependencyNotFoundError} when `target` cannot be resolved in this container or any parent scope.
+   */
+  resolve<T>(target: constructor<T> | DependencyKey, { args = [], child = this, lazy }: ResolveOneOptions = {}): T {
+    this.validateContainer();
+
+    if (Is.constructor(target)) {
+      return this.injector.resolve(target, { scope: this, args, lazy });
+    }
+
+    const provider = this.providers.get(target) as IProvider<T> | undefined;
+
+    return provider?.hasAccess({ invocationScope: child, providerScope: this, args })
+      ? provider.resolve({ scope: this, args, lazy })
+      : this.parent.resolve<T>(target, { args, child, lazy });
+  }
+
+  /**
+   * @throws {ContainerDisposedError} when the container has already been disposed.
+   * @throws {DependencyNotFoundError} when a key registered under `alias` has no matching provider.
+   */
+  resolveByAlias<T>(
+    alias: DependencyKey,
+    { args = [], child = this, lazy, excludedKeys = [] }: ResolveManyOptions = {},
+  ): T[] {
+    this.validateContainer();
+
+    const keys: DependencyKey[] = [];
+    const deps: T[] = [];
+    for (const key of this.aliases.getKeysByAlias(alias).filter(F.exclude(excludedKeys))) {
+      const provider = this.findProviderByKeyOrFail<T>(key);
+      if (!provider.hasAccess({ invocationScope: child, providerScope: this, args })) {
+        continue;
+      }
+      keys.push(key);
+      deps.push(provider.resolve({ scope: this, args, lazy }));
+    }
+
+    const parentDeps = this.parent.resolveByAlias<T>(alias, {
+      args,
+      child,
+      lazy,
+      excludedKeys: [...excludedKeys, ...keys],
+    });
+    return [...deps, ...parentDeps];
+  }
+
+  /**
+   * @throws {ContainerDisposedError} when the container has already been disposed.
+   * @throws {DependencyNotFoundError} when `alias` cannot be resolved in this container or any parent scope.
+   */
+  resolveOneByAlias<T>(alias: DependencyKey, { args = [], child = this, lazy }: ResolveOneOptions = {}): T {
+    this.validateContainer();
+
+    const [key] = this.aliases.getKeysByAlias(alias);
+    const provider = key ? this.findProviderByKeyOrFail<T>(key) : undefined;
+
+    return provider?.hasAccess({ invocationScope: child, providerScope: this, args })
+      ? provider.resolve({ scope: this, args, lazy })
+      : this.parent.resolveOneByAlias<T>(alias, { args, child, lazy });
+  }
+
+  /**
+   * @throws {ContainerDisposedError} when the container has already been disposed.
+   */
+  createScope({ tags }: CreateScopeOptions = {}): IContainer {
+    this.validateContainer();
+
+    // Injector hooks need no copying - the child shares this scope's injector, so it shares its hooks.
+    const scope = new Container({ injector: this.injector, parent: this, tags });
+    this.scopeCreatedEvent.getListeners().forEach((hook) => scope.scopeCreatedEvent.subscribe(hook));
+    this.scopeDisposedEvent.getListeners().forEach((hook) => scope.scopeDisposedEvent.subscribe(hook));
+    this.registeredEvent.getListeners().forEach((hook) => scope.registeredEvent.subscribe(hook));
+
+    for (const registration of this.getRegistrations()) {
+      registration.applyTo(scope);
+    }
+    this.scopes.push(scope);
+
+    // Hooks run once the scope is fully registered and attached, so they observe a usable scope.
+    this.scopeCreatedEvent.emit(scope);
+
+    return scope;
+  }
+
+  /**
+   * Eagerly resolves every provider of this scope which was marked with `autoResolve()`.
+   *
+   * `args` are forwarded to each of those providers, exactly as `resolve` forwards them.
+   *
+   * @throws {ContainerDisposedError} when the container has already been disposed.
+   */
+  autoResolve({ args = [] }: AutoResolveOptions = {}): this {
+    this.validateContainer();
+
+    for (const provider of this.providers.values()) {
+      if (provider.isAutoResolvable() && provider.hasAccess({ invocationScope: this, providerScope: this, args })) {
+        provider.resolve({ scope: this, args });
+      }
+    }
+
+    return this;
+  }
+
+  /**
+   * @throws {ContainerDisposedError} when the container has already been disposed.
+   */
+  dispose(): void {
+    this.validateContainer();
+    this.isDisposed = true;
+
+    this.scopeDisposedEvent.emit(this);
+
+    // Detach from parent
+    this.parent.removeScope(this);
+    this.parent = new EmptyContainer();
+
+    // Reset the state
+    for (const provider of this.providers.values()) {
+      provider.dispose();
+    }
+    this.providers.clear();
+    this.aliases.destroy();
+    this.instances.clear();
+    this.registrations = [];
+
+    // Dispose scope events. Injector hooks are not this scope's to clear - the injector outlives it.
+    this.scopeCreatedEvent.dispose();
+    this.scopeDisposedEvent.dispose();
+    this.registeredEvent.dispose();
+  }
+
+  addRegistration(registration: IRegistration): this {
+    this.registrations.push(registration);
+    registration.applyTo(this);
+    return this;
+  }
+
+  getRegistrations(): IRegistration[] {
+    return [...this.parent.getRegistrations(), ...this.registrations];
+  }
+
+  getInjector(): IInjector {
+    return this.injector;
+  }
+
+  hasRegistration(key: DependencyKey): boolean {
+    return this.registrations.some((r) => r.getKeyOrFail() === key) || this.parent.hasRegistration(key);
+  }
+
+  hasAlias(alias: DependencyKey): boolean {
+    return this.aliases.getKeysByAlias(alias).length > 0 || this.parent.hasAlias(alias);
+  }
+
+  addInstance(instance: Instance) {
+    this.instances.add(instance);
+  }
+
+  getScopes() {
+    return [...this.scopes];
+  }
+
+  /**
+   * Whether this scope created `instance`.
+   *
+   * A proxy stands for the object behind it, so it is unwrapped before the
+   * lookup - the container tracks real instances, and a caller asking about a
+   * proxy is asking about its target. Resolving a lazy proxy's target is what
+   * makes that answer possible, so a still-unresolved lazy proxy is resolved
+   * here.
+   */
+  hasInstance(instance: Instance): boolean {
+    return this.instances.has(unwrapProxy(instance));
+  }
+
+  removeScope(child: IContainer): void {
+    this.scopes = this.scopes.filter((s) => s !== child);
+  }
+
+  useModule(module: IContainerModule): this {
+    module.applyTo(this);
+    return this;
+  }
+
+  getParent() {
+    return this.parent;
+  }
+
+  getInstances(cascade: boolean = false) {
+    if (!cascade) {
+      return [...this.instances];
+    }
+    return [...this.instances, ...this.scopes.flatMap((s) => s.getInstances(true))];
+  }
+
+  hasTag(tag: Tag) {
+    return this.tags.has(tag);
+  }
+
+  addTags(...tags: Tag[]) {
+    for (const tag of tags) {
+      this.tags.add(tag);
+    }
+  }
+
+  /**
+   * @throws {ContainerDisposedError} when the container has already been disposed.
+   */
+  private validateContainer(): void {
+    if (this.isDisposed) {
+      throw new ContainerDisposedError(
+        'Container is already disposed: a scope cannot be used after dispose(). Create a new scope.',
+      );
+    }
+  }
+
+  /**
+   * @throws {DependencyNotFoundError} when no provider is registered under `key` in this container.
+   */
+  private findProviderByKeyOrFail<T>(key: DependencyKey): IProvider<T> {
+    if (!this.providers.has(key)) {
+      throw new DependencyNotFoundError(
+        `Provider ${key.toString()} does not exist: an alias points at a key with no provider in this scope.`,
+      );
+    }
+    return this.providers.get(key)!;
+  }
+}

package/lib/container/EmptyContainer.ts

@@ -0,0 +1,170 @@
+import {
+  type AutoResolveOptions,
+  type DependencyKey,
+  type IContainer,
+  type IContainerModule,
+  type ResolveManyOptions,
+  type ResolveOneOptions,
+  type Tag,
+} from './IContainer';
+import { MethodNotImplementedError } from '../errors/MethodNotImplementedError';
+import { DependencyNotFoundError } from '../errors/DependencyNotFoundError';
+import { type IProvider } from '../provider/IProvider';
+import { type IRegistration } from '../registration/IRegistration';
+import { type constructor, type Instance } from '../utils/basic';
+import { type IInjector } from '../injector/IInjector';
+import { type ITypedEvent } from '../utils/TypedEvent';
+
+/**
+ * Terminates the parent chain of every root {@link Container}: `resolve` throws
+ * `DependencyNotFoundError`, alias lookups return nothing, and every other
+ * method throws `MethodNotImplementedError`. You rarely use it directly.
+ */
+export class EmptyContainer implements IContainer {
+  /**
+   * @throws {MethodNotImplementedError} always — the empty container has no disposal state.
+   */
+  get isDisposed(): boolean {
+    throw new MethodNotImplementedError('EmptyContainer.isDisposed is not implemented');
+  }
+
+  addInstance(instance: Instance) {}
+
+  getParent() {
+    return undefined;
+  }
+
+  getScopes() {
+    return [];
+  }
+
+  getInstances() {
+    return [];
+  }
+
+  hasInstance(instance: Instance): boolean {
+    return false;
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — the empty container cannot create scopes.
+   */
+  createScope(): IContainer {
+    throw new MethodNotImplementedError('EmptyContainer.createScope is not implemented');
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — the empty container constructs nothing, so it has no injector.
+   */
+  getInjector(): IInjector {
+    throw new MethodNotImplementedError('EmptyContainer.getInjector is not implemented');
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — the empty container holds no providers to resolve.
+   */
+  autoResolve(options?: AutoResolveOptions): this {
+    throw new MethodNotImplementedError('EmptyContainer.autoResolve is not implemented');
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — the empty container cannot be disposed.
+   */
+  dispose(): void {
+    throw new MethodNotImplementedError('EmptyContainer.dispose is not implemented');
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — the empty container cannot hold registrations.
+   */
+  register(key: DependencyKey, value: IProvider): this {
+    throw new MethodNotImplementedError('EmptyContainer.register is not implemented');
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — the empty container has no tags.
+   */
+  hasTag(tag: Tag): boolean {
+    throw new MethodNotImplementedError('EmptyContainer.hasTag is not implemented');
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — the empty container has no tags.
+   */
+  addTags(...tags: Tag[]): void {
+    throw new MethodNotImplementedError('EmptyContainer.addTags is not implemented');
+  }
+
+  getRegistrations() {
+    return [];
+  }
+
+  hasRegistration(key: DependencyKey): boolean {
+    return false;
+  }
+
+  hasAlias(alias: DependencyKey): boolean {
+    return false;
+  }
+
+  removeScope(): void {}
+
+  /**
+   * @throws {MethodNotImplementedError} always — the empty container cannot use modules.
+   */
+  useModule(module: IContainerModule): this {
+    throw new MethodNotImplementedError('EmptyContainer.useModule is not implemented');
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — the empty container cannot hold registrations.
+   */
+  addRegistration(registration: IRegistration): this {
+    throw new MethodNotImplementedError('EmptyContainer.addRegistration is not implemented');
+  }
+
+  /**
+   * @throws {DependencyNotFoundError} always — reaching the empty container means `key` was not found in any scope.
+   */
+  resolve<T>(key: constructor<T> | DependencyKey, options?: ResolveOneOptions): T {
+    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<T>(alias: DependencyKey, options?: ResolveManyOptions): T[] {
+    return [];
+  }
+
+  /**
+   * @throws {DependencyNotFoundError} always — reaching the empty container means `alias` was not found in any scope.
+   */
+  resolveOneByAlias<T>(alias: DependencyKey, options?: ResolveOneOptions): T {
+    throw new DependencyNotFoundError(
+      `Cannot find alias ${alias.toString()}: no accessible registration carries this alias in the resolving scope or any parent.`,
+    );
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — the empty container cannot hold hooks.
+   */
+  get scopeCreated(): ITypedEvent<[IContainer]> {
+    throw new MethodNotImplementedError('EmptyContainer.scopeCreated is not implemented');
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — the empty container cannot hold hooks.
+   */
+  get scopeDisposed(): ITypedEvent<[IContainer]> {
+    throw new MethodNotImplementedError('EmptyContainer.scopeDisposed is not implemented');
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — the empty container cannot hold hooks.
+   */
+  get registered(): ITypedEvent<[IProvider, DependencyKey, IContainer]> {
+    throw new MethodNotImplementedError('EmptyContainer.registered is not implemented');
+  }
+}