ts-ioc-container 72.0.0 → 72.2.0

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,92 @@
+import { DependencyKey, IContainer } from '../container/IContainer';
+import { forwardArgs, InjectionToken } from './InjectionToken';
+import { IRegistration } from '../registration/IRegistration';
+import { BindToken } from './BindToken';
+import { ArgsFn, ResolveOptions } from '../provider/IProvider';
+import { Serializable } from '../utils/basic';
+
+/**
+ * A token for every dependency registered under an alias. As a `bindTo(...)`
+ * target it adds the alias; resolving returns all matches as an array.
+ *
+ * @example
+ * const IMiddlewareToken = toGroupAlias<IMiddleware>('IMiddleware');
+ *
+ * @register(bindTo(IMiddlewareToken))
+ * class Auth implements IMiddleware {}
+ *
+ * IMiddlewareToken.resolve(scope); // IMiddleware[]
+ */
+export class GroupAliasToken<T = any> extends InjectionToken<T[]> implements BindToken<T>, Serializable {
+  private readonly _getArgsFn: ArgsFn;
+  private readonly _isLazy: boolean;
+
+  constructor(
+    readonly token: DependencyKey,
+    {
+      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.resolveByAlias(this.token, {
+      args: this._getArgsFn({ scope: s, args }),
+      lazy: this._isLazy || lazy,
+    });
+  }
+
+  bindTo(r: IRegistration<T>) {
+    r.bindToAlias(this.token);
+  }
+
+  args(...newArgs: unknown[]) {
+    const parentFn = this._getArgsFn;
+    return new GroupAliasToken<T>(this.token, {
+      getArgsFn: (options) => [...parentFn(options), ...newArgs],
+      isLazy: this._isLazy,
+      tags: this.getTags(),
+    });
+  }
+
+  argsFn(fn: (s: IContainer) => unknown[]) {
+    const parentFn = this._getArgsFn;
+    return new GroupAliasToken<T>(this.token, {
+      getArgsFn: (options) => [...parentFn(options), ...fn(options.scope)],
+      isLazy: this._isLazy,
+      tags: this.getTags(),
+    });
+  }
+
+  lazy() {
+    return new GroupAliasToken<T>(this.token, {
+      getArgsFn: this._getArgsFn,
+      isLazy: true,
+      tags: this.getTags(),
+    });
+  }
+
+  addTags(...tags: string[]): GroupAliasToken<T> {
+    return new GroupAliasToken<T>(this.token, {
+      getArgsFn: this._getArgsFn,
+      isLazy: this._isLazy,
+      tags: [...this.getTags(), ...tags],
+    });
+  }
+
+  toString(): string {
+    return this.token.toString();
+  }
+}
+
+/** 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
+  );
+}

package/lib/token/SingleAliasToken.ts

@@ -0,0 +1,84 @@
+import { DependencyKey, IContainer } from '../container/IContainer';
+import { forwardArgs, InjectionToken } from './InjectionToken';
+import { IRegistration } from '../registration/IRegistration';
+import { BindToken } from './BindToken';
+import { ArgsFn, ResolveOptions } from '../provider/IProvider';
+import { Serializable } from '../utils/basic';
+
+/**
+ * Like {@link GroupAliasToken}, but resolves exactly one dependency registered
+ * under the alias, and throws `DependencyNotFoundError` when there is none.
+ */
+export class SingleAliasToken<T = any> extends InjectionToken<T> implements BindToken<T>, Serializable {
+  private readonly _getArgsFn: ArgsFn;
+  private readonly _isLazy: boolean;
+
+  constructor(
+    readonly token: DependencyKey,
+    {
+      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.resolveOneByAlias(this.token, {
+      args: this._getArgsFn({ scope: s, args }),
+      lazy: this._isLazy || lazy,
+    });
+  }
+
+  bindTo(r: IRegistration<T>) {
+    r.bindToAlias(this.token);
+  }
+
+  args(...newArgs: unknown[]) {
+    const parentFn = this._getArgsFn;
+    return new SingleAliasToken<T>(this.token, {
+      getArgsFn: (options) => [...parentFn(options), ...newArgs],
+      isLazy: this._isLazy,
+      tags: this.getTags(),
+    });
+  }
+
+  argsFn(fn: (s: IContainer) => unknown[]) {
+    const parentFn = this._getArgsFn;
+    return new SingleAliasToken<T>(this.token, {
+      getArgsFn: (options) => [...parentFn(options), ...fn(options.scope)],
+      isLazy: this._isLazy,
+      tags: this.getTags(),
+    });
+  }
+
+  lazy() {
+    return new SingleAliasToken<T>(this.token, {
+      getArgsFn: this._getArgsFn,
+      isLazy: true,
+      tags: this.getTags(),
+    });
+  }
+
+  addTags(...tags: string[]): SingleAliasToken<T> {
+    return new SingleAliasToken<T>(this.token, {
+      getArgsFn: this._getArgsFn,
+      isLazy: this._isLazy,
+      tags: [...this.getTags(), ...tags],
+    });
+  }
+
+  toString(): string {
+    return this.token.toString();
+  }
+}
+
+/** Creates a {@link SingleAliasToken} for `token`. */
+export const toSingleAlias = <T>(token: DependencyKey) => new SingleAliasToken<T>(token);

package/lib/token/SingleToken.ts

@@ -0,0 +1,93 @@
+import { DependencyKey, IContainer } from '../container/IContainer';
+import { forwardArgs, InjectionToken } from './InjectionToken';
+import { IRegistration } from '../registration/IRegistration';
+import { ArgsFn, ResolveOptions } from '../provider/IProvider';
+import { Serializable } from '../utils/basic';
+
+/**
+ * A typed handle for one dependency key - the usual way to name a dependency.
+ * `args(...)`, `argsFn(...)` and `lazy()` return a new token and never change
+ * this one, so one token can be specialized per injection site.
+ *
+ * @example
+ * const ILoggerToken = new SingleToken<ILogger>('ILogger');
+ *
+ * @register(bindTo(ILoggerToken))
+ * class Logger implements ILogger {}
+ *
+ * class App {
+ *   constructor(@inject(by(ILoggerToken)) logger: ILogger) {}
+ * }
+ * ILoggerToken.resolve(scope);
+ * ILoggerToken.args('prefix').lazy().resolve(scope);
+ */
+export class SingleToken<T = any> extends InjectionToken<T> implements Serializable {
+  private readonly _getArgsFn: ArgsFn;
+  private readonly _isLazy: boolean;
+
+  constructor(
+    public token: DependencyKey,
+    {
+      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.token, {
+      args: this._getArgsFn({ scope: s, args }),
+      lazy: this._isLazy || lazy,
+    });
+  }
+
+  bindTo(r: IRegistration<T>) {
+    r.bindToKey(this.token);
+  }
+
+  args(...newArgs: unknown[]) {
+    const parentFn = this._getArgsFn;
+    return new SingleToken<T>(this.token, {
+      getArgsFn: (options) => [...parentFn(options), ...newArgs],
+      isLazy: this._isLazy,
+      tags: this.getTags(),
+    });
+  }
+
+  argsFn(fn: (s: IContainer) => unknown[]) {
+    const parentFn = this._getArgsFn;
+    return new SingleToken<T>(this.token, {
+      getArgsFn: (options) => [...parentFn(options), ...fn(options.scope)],
+      isLazy: this._isLazy,
+      tags: this.getTags(),
+    });
+  }
+
+  lazy() {
+    return new SingleToken<T>(this.token, {
+      getArgsFn: this._getArgsFn,
+      isLazy: true,
+      tags: this.getTags(),
+    });
+  }
+
+  addTags(...tags: string[]): SingleToken<T> {
+    return new SingleToken<T>(this.token, {
+      getArgsFn: this._getArgsFn,
+      isLazy: this._isLazy,
+      tags: [...this.getTags(), ...tags],
+    });
+  }
+
+  toString(): string {
+    return this.token.toString();
+  }
+}

package/lib/token/toToken.ts

@@ -0,0 +1,46 @@
+import { DependencyKey, isDependencyKey } from '../container/IContainer';
+import { SingleToken } from './SingleToken';
+import { ClassToken } from './ClassToken';
+import { FunctionToken } from './FunctionToken';
+import { UnsupportedTokenTypeError } from '../errors/UnsupportedTokenTypeError';
+import { InjectionToken, isInjectionToken } from './InjectionToken';
+import { InjectFn } from '../hooks/hook';
+import { type constructor, Is } from '../utils/basic';
+import { ConstantToken } from './ConstantToken';
+
+/** Anything `toToken(...)` turns into a token: a token, a key, a class or an `InjectFn`. */
+export type Injectable<T = any> = InjectFn<T> | InjectionToken<T> | DependencyKey | constructor<T>;
+
+/**
+ * @throws {UnsupportedTokenTypeError} when `token` is not an `InjectionToken`, a `DependencyKey`, a constructor, or a function.
+ */
+export const toToken = <T = any>(token: Injectable<T>): InjectionToken<T> => {
+  if (token instanceof InjectionToken) {
+    return token;
+  }
+
+  if (isDependencyKey(token)) {
+    return new SingleToken(token);
+  }
+
+  if (Is.constructor(token)) {
+    return new ClassToken(token);
+  }
+
+  if (typeof token === 'function') {
+    return new FunctionToken(token as InjectFn<T>);
+  }
+
+  throw new UnsupportedTokenTypeError(
+    `Unknown token ${token}: expected an InjectionToken, a DependencyKey (string | symbol), a class or a function.`,
+  );
+};
+
+/**
+ * Wraps a runtime argument so it can be resolved uniformly: an `InjectionToken`
+ * is returned as-is, anything else becomes a `ConstantToken` of itself. The
+ * library never applies it to the args list - a call site that wants
+ * "resolve tokens, pass literals through" does so explicitly, e.g.
+ * `@inject(({ scope, args = [] }) => argToToken(args[0]).resolve(scope))`.
+ */
+export const argToToken = <T = unknown>(v: T): InjectionToken<T> => (isInjectionToken<T>(v) ? v : new ConstantToken(v));

package/lib/utils/ProxyRegistry.ts

@@ -0,0 +1,149 @@
+type ProxyState<T extends object> = {
+  getTarget: () => T;
+};
+
+/**
+ * The proxy operations the library depends on. Depend on this rather than on
+ * {@link ProxyRegistry} itself, so a caller can substitute its own
+ * implementation - the concrete registry is a singleton and cannot be
+ * constructed a second time.
+ */
+export interface IProxyRegistry {
+  /**
+   * Returns the real object behind `value`, unwrapping proxies stacked to any
+   * depth. A value that is not a proxy is returned as is.
+   *
+   * The library calls this itself wherever a proxy would give the wrong answer -
+   * every read of class metadata (see `resolveConstructor`, `getHooks`,
+   * `resolveArgs`) and every identity check against a tracked instance (see
+   * `IContainer.hasInstance`). Pass the container's own values to those APIs as
+   * they come; unwrapping by hand is for code that needs the real object for its
+   * own reasons.
+   */
+  unwrap<T extends object>(value: T): T;
+
+  createProxy<T extends object>(target: T, handler?: ProxyHandler<T>): T;
+
+  /**
+   * Creates a proxy that resolves its target on first access and caches it.
+   */
+  createLazyProxy<T extends object>(resolveInstance: () => T): T;
+
+  /**
+   * Wraps `resolveInstance` in a lazy proxy when `isLazy`, otherwise calls it
+   * right away.
+   */
+  toLazyIf<T extends object>(resolveInstance: () => T, isLazy?: boolean): T;
+}
+
+/**
+ * Creates proxies and tracks them, so a proxy can be traced back to the real
+ * object it stands for. The library's own {@link IProxyRegistry}.
+ *
+ * Process-wide singleton: a proxy created anywhere must be unwrappable
+ * everywhere, and the registry holds no configuration that would justify a
+ * second instance. Obtain it with {@link ProxyRegistry.getInstance}.
+ *
+ * Entries are held weakly - a proxy that becomes unreachable is collected along
+ * with its state.
+ */
+export class ProxyRegistry implements IProxyRegistry {
+  private static instance?: ProxyRegistry;
+
+  private readonly states = new WeakMap<object, ProxyState<object>>();
+
+  private constructor() {}
+
+  static getInstance(): ProxyRegistry {
+    ProxyRegistry.instance ??= new ProxyRegistry();
+    return ProxyRegistry.instance;
+  }
+
+  /**
+   * Returns the real object behind `value`, unwrapping proxies stacked to any
+   * depth. A value that is not a proxy is returned as is.
+   */
+  unwrap<T extends object>(value: T): T {
+    return this.isProxy(value) ? this.getTarget(value) : value;
+  }
+
+  createProxy<T extends object>(target: T, handler: ProxyHandler<T> = {}): T {
+    const proxy = new Proxy(target, handler);
+    return this.register(proxy, { getTarget: () => target });
+  }
+
+  /**
+   * Creates a proxy that resolves its target on first access and caches it.
+   * The target is unwrapped on resolution, so wrapping a lazy proxy in another
+   * lazy proxy never stacks beyond one level.
+   */
+  createLazyProxy<T extends object>(resolveInstance: () => T): T {
+    let instance: T | undefined;
+    const state: ProxyState<T> = {
+      getTarget: () => {
+        instance = instance ?? this.unwrap(resolveInstance());
+        return instance;
+      },
+    };
+
+    const proxy = new Proxy(
+      {},
+      {
+        get: (_, prop) => {
+          const target = state.getTarget();
+          // @ts-ignore
+          return target[prop];
+        },
+        // The proxy stands in for the target, so writes must reach it. Without this
+        // the empty object above would absorb them - including writes a method makes
+        // to `this` when it is called through the proxy.
+        set: (_, prop, value) => {
+          const target = state.getTarget();
+          // @ts-ignore
+          target[prop] = value;
+          return true;
+        },
+      },
+    ) as T;
+
+    return this.register(proxy, state);
+  }
+
+  /**
+   * Wraps `resolveInstance` in a lazy proxy when `isLazy`, otherwise calls it
+   * right away.
+   */
+  toLazyIf<T extends object>(resolveInstance: () => T, isLazy: boolean = false): T {
+    return isLazy ? this.createLazyProxy(resolveInstance) : resolveInstance();
+  }
+
+  private isProxy(value: object): boolean {
+    return this.states.has(value);
+  }
+
+  private getTarget<T extends object>(value: T): T {
+    const target = this.states.get(value)!.getTarget() as T;
+    return this.unwrap(target);
+  }
+
+  private register<T extends object>(proxy: T, state: ProxyState<T>): T {
+    this.states.set(proxy, state as ProxyState<object>);
+    return proxy;
+  }
+}
+
+/**
+ * The real object behind `value`, unwrapping proxies stacked to any depth. A
+ * value that is not a proxy is returned as is.
+ *
+ * A shortcut for `ProxyRegistry.getInstance().unwrap(value)` - the registry is a
+ * process-wide singleton, so unwrapping never needs an instance of its own. The
+ * library already unwraps wherever a proxy would give the wrong answer (reading
+ * class metadata, and `IContainer.hasInstance`), so reach for this only when
+ * your own code needs the real object - an identity check of your own, or
+ * bypassing a lazy proxy on purpose.
+ *
+ * Note that unwrapping a lazy proxy resolves its target, which is the point:
+ * there is no real object to hand back until it does.
+ */
+export const unwrapProxy = <T extends object>(value: T): T => ProxyRegistry.getInstance().unwrap(value);