ts-ioc-container 72.1.0 → 72.3.0

package/lib/select.ts

@@ -0,0 +1,33 @@
+import { type CreateScopeOptions } from './container/IContainer';
+import { toGroupAlias } from './token/GroupAliasToken';
+import { FunctionToken } from './token/FunctionToken';
+import { GroupInstanceToken, InstancePredicate } from './token/GroupInstanceToken';
+import { toToken } from './token/toToken';
+
+/**
+ * Shortcuts for common tokens.
+ *
+ * - `select.token(x)` - `toToken(x)`
+ * - `select.alias('Key')` - a {@link GroupAliasToken}
+ * - `select.instances(predicate)` - instances already created in the scope
+ * - `select.scope.current` - the resolving scope itself
+ * - `select.scope.create({ tags })` - a new child scope
+ *
+ * @example
+ * class Handler {
+ *   constructor(@inject(by(select.scope.current)) private scope: IContainer) {}
+ * }
+ */
+export const select = {
+  alias: toGroupAlias,
+
+  token: toToken,
+
+  instances: (predicate: InstancePredicate = () => true) => new GroupInstanceToken(predicate),
+
+  scope: {
+    current: new FunctionToken(({ scope }) => scope),
+
+    create: (options: CreateScopeOptions) => new FunctionToken(({ scope }) => scope.createScope(options)),
+  },
+};

package/lib/token/BindToken.ts

@@ -0,0 +1,13 @@
+import { IRegistration } from '../registration/IRegistration';
+
+import { Is } from '../utils/basic';
+
+/** A token that can bind a registration to itself (a key or an alias). */
+export interface BindToken<T = any> {
+  bindTo(r: IRegistration<T>): void;
+}
+
+/** Narrows `token` to a {@link BindToken}. */
+export function isBindToken(token: unknown): token is BindToken {
+  return !Is.nullish(token) && typeof token === 'object' && 'bindTo' in token;
+}

package/lib/token/BindableToken.ts

@@ -0,0 +1,137 @@
+import { type DependencyKey, type IContainer } from '../container/IContainer';
+import { forwardArgs, InjectionToken } from './InjectionToken';
+import { type BindToken } from './BindToken';
+import { type IRegistration } from '../registration/IRegistration';
+import { type ArgsFn, type ResolveOptions } from '../provider/IProvider';
+import { type Serializable } from '../utils/basic';
+import { type MultiVariantFeatureToken } from './MultiVariantFeatureToken';
+
+// Blocks inference from `name` so it must be one of the feature's variants (TS < 5.4 has no NoInfer).
+type NoInferVariant<V> = [V][V extends unknown ? 0 : never];
+
+/** Internal state of a {@link BindableToken}, propagated by its modifiers. Never pass it from outside. */
+export type BindableTokenOptions = {
+  getArgsFn?: ArgsFn;
+  isLazy?: boolean;
+  tags?: string[];
+  memberships?: DependencyKey[];
+};
+
+/**
+ * Base of every token a registration can be bound to (`SingleToken`,
+ * `SingleAliasToken`, `GroupAliasToken`): a key, the args / lazy / tags state
+ * every modifier copies, and the feature memberships the token declares.
+ *
+ * `T` is the type bound to the token, `R` the type resolving it returns (an
+ * alias group resolves `T[]`). A subclass says only how it binds (`bindKey`)
+ * and how it resolves.
+ */
+export abstract class BindableToken<T = any, R = T> extends InjectionToken<R> implements BindToken<T>, Serializable {
+  private readonly getArgsFn: ArgsFn;
+  private readonly isLazyByDefault: boolean;
+  private readonly memberships: DependencyKey[];
+
+  constructor(
+    readonly token: DependencyKey,
+    { getArgsFn = forwardArgs, isLazy = false, tags = [], memberships = [] }: BindableTokenOptions = {},
+  ) {
+    super(tags);
+    this.getArgsFn = getArgsFn;
+    this.isLazyByDefault = isLazy;
+    this.memberships = memberships;
+  }
+
+  /** Binds `r` under this token, and into every feature this token declared itself a variant or fallback of. */
+  bindTo(r: IRegistration<T>): void {
+    this.bindKey(r);
+    for (const alias of this.memberships) {
+      r.bindToAlias(alias);
+    }
+  }
+
+  /**
+   * Declares the dependency bound to this token the implementation of `feature`
+   * while the flag serves the variant `name`.
+   *
+   * @example
+   * const BlueButtonToken = new SingleToken<IButton>('BlueButton').variantOf(CheckoutButtonToken, 'blue');
+   *
+   * @register(BlueButtonToken)
+   * class BlueButton implements IButton {}
+   */
+  variantOf<V extends string>(feature: MultiVariantFeatureToken<T, V>, name: NoInferVariant<V>): this {
+    return this.copy({ memberships: [...this.memberships, feature.variantAlias(name)] });
+  }
+
+  /**
+   * Declares the dependency bound to this token the primary variant of
+   * `feature`: used while the flag is on and no named variant implementation
+   * matches. The enabled implementation of a `ToggleFeatureToken`.
+   *
+   * @example
+   * const StripeGatewayToken = new SingleToken<IPaymentGateway>('StripeGateway').primaryVariantOf(PaymentGatewayToken);
+   *
+   * @register(StripeGatewayToken)
+   * class StripeGateway implements IPaymentGateway {}
+   */
+  primaryVariantOf(feature: MultiVariantFeatureToken<T, string>): this {
+    return this.copy({ memberships: [...this.memberships, feature.primaryAlias()] });
+  }
+
+  /**
+   * Declares the dependency bound to this token the fallback of `feature`: used
+   * whenever no variant implementation applies - the flag is off, serves
+   * nothing implemented, or its client throws.
+   *
+   * @example
+   * const LegacyGatewayToken = new SingleToken<IPaymentGateway>('LegacyGateway').fallbackOf(PaymentGatewayToken);
+   *
+   * @register(LegacyGatewayToken)
+   * class LegacyGateway implements IPaymentGateway {}
+   */
+  fallbackOf(feature: MultiVariantFeatureToken<T, string>): this {
+    return this.copy({ memberships: [...this.memberships, feature.fallbackAlias()] });
+  }
+
+  args(...newArgs: unknown[]): this {
+    const parentFn = this.getArgsFn;
+    return this.copy({ getArgsFn: (options) => [...parentFn(options), ...newArgs] });
+  }
+
+  argsFn(fn: (s: IContainer) => unknown[]): this {
+    const parentFn = this.getArgsFn;
+    return this.copy({ getArgsFn: (options) => [...parentFn(options), ...fn(options.scope)] });
+  }
+
+  lazy(): this {
+    return this.copy({ isLazy: true });
+  }
+
+  addTags(...tags: string[]): this {
+    return this.copy({ tags: [...this.getTags(), ...tags] });
+  }
+
+  toString(): string {
+    return this.token.toString();
+  }
+
+  /** Binds `r` under this token's own key or alias. */
+  protected abstract bindKey(r: IRegistration<T>): void;
+
+  /** The options a subclass resolves with: runtime args first, then this token's args; lazy if either asks. */
+  protected toResolveOptions(s: IContainer, { args = [], lazy }: ResolveOptions = {}): ResolveOptions {
+    // `lazy` stays undefined unless someone asked, so a provider's own `lazy()` pipe still applies.
+    return { args: this.getArgsFn({ scope: s, args }), lazy: this.isLazyByDefault || lazy };
+  }
+
+  private copy(overrides: BindableTokenOptions): this {
+    const Self = this.constructor as new (token: DependencyKey, options: BindableTokenOptions) => this;
+    return new Self(this.token, {
+      getArgsFn: this.getArgsFn,
+      isLazy: this.isLazyByDefault,
+      tags: this.getTags(),
+      memberships: this.memberships,
+      ...overrides,
+    });
+  }
+}

package/lib/token/ClassToken.ts

@@ -0,0 +1,72 @@
+import { IContainer } from '../container/IContainer';
+import { forwardArgs, InjectionToken } from './InjectionToken';
+import { type constructor, Serializable } from '../utils/basic';
+import { ArgsFn, ResolveOptions } from '../provider/IProvider';
+
+/** A token for a class: resolves it through the scope's injector. `toToken(Class)` creates one. */
+export class ClassToken<T = any> extends InjectionToken<T> implements Serializable {
+  private readonly _getArgsFn: ArgsFn;
+  private readonly _isLazy: boolean;
+
+  constructor(
+    private readonly target: constructor<T>,
+    {
+      getArgsFn = forwardArgs,
+      isLazy = false,
+      tags = [],
+    }: { getArgsFn?: ArgsFn; isLazy?: boolean; tags?: string[] } = {},
+  ) {
+    super(tags);
+    this._getArgsFn = getArgsFn;
+    this._isLazy = isLazy;
+  }
+
+  select<R>(fn: (target: T) => R) {
+    return (s: IContainer) => fn(this.resolve(s));
+  }
+
+  resolve(s: IContainer, { args = [], lazy }: ResolveOptions = {}): T {
+    return s.resolve(this.target, {
+      args: this._getArgsFn({ scope: s, args }),
+      lazy: this._isLazy || lazy,
+    });
+  }
+
+  args(...newArgs: unknown[]) {
+    const parentFn = this._getArgsFn;
+    return new ClassToken<T>(this.target, {
+      getArgsFn: (options) => [...parentFn(options), ...newArgs],
+      isLazy: this._isLazy,
+      tags: this.getTags(),
+    });
+  }
+
+  argsFn(fn: (s: IContainer) => unknown[]) {
+    const parentFn = this._getArgsFn;
+    return new ClassToken<T>(this.target, {
+      getArgsFn: (options) => [...parentFn(options), ...fn(options.scope)],
+      isLazy: this._isLazy,
+      tags: this.getTags(),
+    });
+  }
+
+  lazy() {
+    return new ClassToken<T>(this.target, {
+      getArgsFn: this._getArgsFn,
+      isLazy: true,
+      tags: this.getTags(),
+    });
+  }
+
+  addTags(...tags: string[]): ClassToken<T> {
+    return new ClassToken<T>(this.target, {
+      getArgsFn: this._getArgsFn,
+      isLazy: this._isLazy,
+      tags: [...this.getTags(), ...tags],
+    });
+  }
+
+  toString(): string {
+    return this.target.name;
+  }
+}

package/lib/token/ConstantToken.ts

@@ -0,0 +1,50 @@
+import type { IContainer } from '../container/IContainer';
+import { InjectionToken } from './InjectionToken';
+import { MethodNotImplementedError } from '../errors/MethodNotImplementedError';
+import { Serializable } from '../utils/basic';
+
+/** A token that always resolves to a fixed value. It takes no args and cannot be lazy. */
+export class ConstantToken<T = any> extends InjectionToken<T> implements Serializable {
+  constructor(
+    private readonly token: T,
+    { tags = [] }: { tags?: string[] } = {},
+  ) {
+    super(tags);
+  }
+
+  resolve(s: IContainer): T {
+    return this.token;
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — a constant token cannot receive static args.
+   */
+  args(...deps: unknown[]): InjectionToken<T> {
+    throw new MethodNotImplementedError('ConstantToken.args is not implemented');
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — a constant token cannot receive resolved args.
+   */
+  argsFn(getArgsFn: (s: IContainer) => unknown[]): InjectionToken<T> {
+    throw new MethodNotImplementedError('ConstantToken.argsFn is not implemented');
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — a constant token cannot be made lazy.
+   */
+  lazy(): InjectionToken<T> {
+    throw new MethodNotImplementedError('ConstantToken.lazy is not implemented');
+  }
+
+  addTags(...tags: string[]): ConstantToken<T> {
+    return new ConstantToken<T>(this.token, { tags: [...this.getTags(), ...tags] });
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — a constant token has no underlying key.
+   */
+  toString(): string {
+    throw new MethodNotImplementedError('ConstantToken.toString is not implemented');
+  }
+}

package/lib/token/FunctionToken.ts

@@ -0,0 +1,79 @@
+import type { IContainer } from '../container/IContainer';
+import { forwardArgs, InjectionToken } from './InjectionToken';
+import { InjectFn } from '../hooks/hook';
+import { ArgsFn, ResolveOptions } from '../provider/IProvider';
+import { MethodNotImplementedError } from '../errors/MethodNotImplementedError';
+import { Serializable } from '../utils/basic';
+
+/**
+ * A token that resolves by calling an `InjectFn` with the resolution context.
+ *
+ * @example
+ * const CurrentScope = new FunctionToken(({ scope }) => scope);
+ */
+export class FunctionToken<T = any> extends InjectionToken<T> implements Serializable {
+  private readonly _getArgsFn: ArgsFn;
+  private readonly _isLazy: boolean;
+
+  constructor(
+    private readonly fn: InjectFn<T>,
+    {
+      getArgsFn = forwardArgs,
+      isLazy = false,
+      tags = [],
+    }: { getArgsFn?: ArgsFn; isLazy?: boolean; tags?: string[] } = {},
+  ) {
+    super(tags);
+    this._getArgsFn = getArgsFn;
+    this._isLazy = isLazy;
+  }
+
+  resolve(s: IContainer, { args = [], lazy }: ResolveOptions = {}): T {
+    return this.fn({
+      scope: s,
+      args: this._getArgsFn({ scope: s, args }),
+      lazy: this._isLazy || lazy,
+    });
+  }
+
+  args(...newArgs: unknown[]): InjectionToken<T> {
+    const parentFn = this._getArgsFn;
+    return new FunctionToken<T>(this.fn, {
+      getArgsFn: (options) => [...parentFn(options), ...newArgs],
+      isLazy: this._isLazy,
+      tags: this.getTags(),
+    });
+  }
+
+  argsFn(fn: (s: IContainer) => unknown[]): InjectionToken<T> {
+    const parentFn = this._getArgsFn;
+    return new FunctionToken<T>(this.fn, {
+      getArgsFn: (options) => [...parentFn(options), ...fn(options.scope)],
+      isLazy: this._isLazy,
+      tags: this.getTags(),
+    });
+  }
+
+  lazy(): InjectionToken<T> {
+    return new FunctionToken<T>(this.fn, {
+      getArgsFn: this._getArgsFn,
+      isLazy: true,
+      tags: this.getTags(),
+    });
+  }
+
+  addTags(...tags: string[]): FunctionToken<T> {
+    return new FunctionToken<T>(this.fn, {
+      getArgsFn: this._getArgsFn,
+      isLazy: this._isLazy,
+      tags: [...this.getTags(), ...tags],
+    });
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — a function token has no underlying key.
+   */
+  toString(): string {
+    throw new MethodNotImplementedError('FunctionToken.toString is not implemented');
+  }
+}

package/lib/token/GroupAliasToken.ts

@@ -0,0 +1,33 @@
+import { type DependencyKey, type IContainer } from '../container/IContainer';
+import { BindableToken } from './BindableToken';
+import { type IRegistration } from '../registration/IRegistration';
+import { type ResolveOptions } from '../provider/IProvider';
+
+/**
+ * A token for every dependency registered under an alias. As a `@register(...)`
+ * target it adds the alias; resolving returns all matches as an array.
+ *
+ * @example
+ * const IMiddlewareToken = toGroupAlias<IMiddleware>('IMiddleware');
+ *
+ * @register(IMiddlewareToken)
+ * class Auth implements IMiddleware {}
+ *
+ * IMiddlewareToken.resolve(scope); // IMiddleware[]
+ */
+export class GroupAliasToken<T = any> extends BindableToken<T, T[]> {
+  select<R>(fn: (target: T[]) => R[]) {
+    return (s: IContainer) => fn(this.resolve(s));
+  }
+
+  resolve(s: IContainer, options?: ResolveOptions): T[] {
+    return s.resolveByAlias(this.token, this.toResolveOptions(s, options));
+  }
+
+  protected bindKey(r: IRegistration<T>) {
+    r.bindToAlias(this.token);
+  }
+}
+
+/** Creates a {@link GroupAliasToken} for `token`. */
+export const toGroupAlias = <T>(token: DependencyKey) => new GroupAliasToken<T>(token);

package/lib/token/GroupInstanceToken.ts

@@ -0,0 +1,70 @@
+import { InjectionToken } from './InjectionToken';
+import type { IContainer } from '../container/IContainer';
+import { MethodNotImplementedError } from '../errors/MethodNotImplementedError';
+
+import { Instance, Serializable } from '../utils/basic';
+
+/** Selects instances for a {@link GroupInstanceToken}. */
+export type InstancePredicate = (dep: unknown) => boolean;
+
+/**
+ * Resolves the instances already created in a scope (and, by default, its
+ * child scopes) that match a predicate. Created by `select.instances(...)`.
+ */
+export class GroupInstanceToken extends InjectionToken<Instance[]> implements Serializable {
+  private isCascade: boolean;
+
+  constructor(
+    private predicate: InstancePredicate,
+    { tags = [], isCascade = true }: { tags?: string[]; isCascade?: boolean } = {},
+  ) {
+    super(tags);
+    this.isCascade = isCascade;
+  }
+
+  select<R>(fn: (target: Instance) => R) {
+    return (s: IContainer) => this.resolve(s).map(fn);
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — a group instance token cannot receive static args.
+   */
+  args(...deps: unknown[]): this {
+    throw new MethodNotImplementedError('GroupInstanceToken.args is not implemented');
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — a group instance token cannot receive resolved args.
+   */
+  argsFn(getArgsFn: (s: IContainer) => unknown[]): InjectionToken<Instance[]> {
+    throw new MethodNotImplementedError('GroupInstanceToken.argsFn is not implemented');
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — a group instance token cannot be made lazy.
+   */
+  lazy(): InjectionToken<Instance[]> {
+    throw new MethodNotImplementedError('GroupInstanceToken.lazy is not implemented');
+  }
+
+  /** Whether instances of child scopes are included (default `true`). */
+  cascade(isTrue: boolean): this {
+    this.isCascade = isTrue;
+    return this;
+  }
+
+  resolve(c: IContainer): Instance[] {
+    return c.getInstances(this.isCascade).filter(this.predicate);
+  }
+
+  addTags(...tags: string[]): GroupInstanceToken {
+    return new GroupInstanceToken(this.predicate, { tags: [...this.getTags(), ...tags], isCascade: this.isCascade });
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — a group instance token has no underlying key.
+   */
+  toString(): string {
+    throw new MethodNotImplementedError('GroupInstanceToken.toString is not implemented');
+  }
+}

package/lib/token/InjectionToken.ts

@@ -0,0 +1,46 @@
+import { type IContainer, type Tag } from '../container/IContainer';
+import { ArgsFn, ResolveOptions } from '../provider/IProvider';
+import { Is } from '../utils/basic';
+
+/**
+ * The default `getArgsFn` of every token: the runtime `args` a token is
+ * resolved with reach the provider as they are, and `token.args(...)` /
+ * `token.argsFn(...)` append after them.
+ */
+export const forwardArgs: ArgsFn = ({ args = [] }) => args;
+
+/** Base class of every token: something resolvable from a scope that can be specialized with args, lazy and tags. */
+export abstract class InjectionToken<T = any> {
+  private readonly tags: Set<Tag>;
+
+  protected constructor(tags: Tag[] = []) {
+    this.tags = new Set(tags);
+  }
+
+  abstract resolve(s: IContainer, options?: ResolveOptions): T;
+  abstract args(...deps: unknown[]): InjectionToken<T>;
+  abstract argsFn(getArgsFn: (s: IContainer) => unknown[]): InjectionToken<T>;
+  abstract lazy(): InjectionToken<T>;
+  abstract addTags(...tags: Tag[]): InjectionToken<T>;
+
+  hasTag(tag: Tag): boolean {
+    return this.tags.has(tag);
+  }
+
+  protected getTags(): Tag[] {
+    return [...this.tags];
+  }
+}
+
+/** Narrows `target` to an {@link InjectionToken}. */
+export function isInjectionToken<T = any>(target: unknown): target is InjectionToken<T> {
+  return (
+    Is.object(target) &&
+    'resolve' in target &&
+    'args' in target &&
+    'argsFn' in target &&
+    'lazy' in target &&
+    'hasTag' in target &&
+    'addTags' in target
+  );
+}