ts-ioc-container 72.1.0 → 72.3.0

package/lib/token/MultiVariantFeatureToken.ts

@@ -0,0 +1,160 @@
+import { type DependencyKey, type IContainer } from '../container/IContainer';
+import { forwardArgs, InjectionToken } from './InjectionToken';
+import { type ArgsFn, type ResolveOptions } from '../provider/IProvider';
+import { type Serializable } from '../utils/basic';
+import { ProxyRegistry } from '../utils/ProxyRegistry';
+import { DependencyNotFoundError } from '../errors/DependencyNotFoundError';
+import {
+  type FeatureContext,
+  type IFeatureFlags,
+  IFeatureContextToken,
+  IFeatureFlagsToken,
+} from '../feature/IFeatureFlags';
+
+export type FeatureTokenOptions = { getArgsFn?: ArgsFn; isLazy?: boolean; tags?: string[] };
+
+/** What a feature token reads from its flag: whether it is on, and the named variant served, if any. */
+export type FeatureEvaluation<V extends string = string> = { enabled: boolean; variant?: V };
+
+/**
+ * A dependency switched by a multi-variant feature flag. The implementations
+ * decide where they belong - a bindable token declares itself
+ *
+ * - a named variant with `variantOf(feature, name)`: used while the flag serves `name`;
+ * - the primary variant with `primaryVariantOf(feature)`: used while the flag is
+ *   on and no named variant implementation matches;
+ * - the fallback with `fallbackOf(feature)`: used otherwise - the flag is off,
+ *   or its client throws.
+ *
+ * A flag always has a fallback: resolving a feature without one registered fails.
+ *
+ * `flag` is the flag's name on the flag service. `V` narrows the variant names
+ * implementations may claim. The flag client comes from `IFeatureFlagsToken`
+ * and the context from `IFeatureContextToken`, both resolved from the resolving
+ * scope, on every resolution.
+ *
+ * Subclasses change only how the served variant is evaluated - see
+ * `ToggleFeatureToken`, the on/off case.
+ *
+ * @example
+ * const CheckoutButtonToken = new MultiVariantFeatureToken<IButton, 'blue' | 'green'>('checkout-button');
+ *
+ * @register(new SingleToken<IButton>('GreyButton').fallbackOf(CheckoutButtonToken))
+ * class GreyButton implements IButton {}
+ *
+ * @register(new SingleToken<IButton>('BlueButton').variantOf(CheckoutButtonToken, 'blue'))
+ * class BlueButton implements IButton {}
+ *
+ * @register(new SingleToken<IButton>('GreenButton').primaryVariantOf(CheckoutButtonToken))
+ * class GreenButton implements IButton {}
+ */
+export class MultiVariantFeatureToken<T = any, V extends string = string>
+  extends InjectionToken<T>
+  implements Serializable
+{
+  private readonly _getArgsFn: ArgsFn;
+  private readonly _isLazy: boolean;
+
+  constructor(
+    readonly flag: string,
+    { getArgsFn = forwardArgs, isLazy = false, tags = [] }: FeatureTokenOptions = {},
+  ) {
+    super(tags);
+    this._getArgsFn = getArgsFn;
+    this._isLazy = isLazy;
+  }
+
+  /** The alias an implementation of the variant `name` is bound to. Declare it with `token.variantOf(feature, name)`. */
+  variantAlias(name: V): DependencyKey {
+    return `feature:${this.flag}:variant:${name}`;
+  }
+
+  /** The alias the primary variant is bound to. Declare it with `token.primaryVariantOf(feature)`. */
+  primaryAlias(): DependencyKey {
+    return `feature:${this.flag}:primary`;
+  }
+
+  /** The alias the fallback is bound to. Declare it with `token.fallbackOf(feature)`. */
+  fallbackAlias(): DependencyKey {
+    return `feature:${this.flag}:fallback`;
+  }
+
+  /**
+   * @throws {DependencyNotFoundError} when the flag has no fallback, or the flag client, the feature context or the selected implementation cannot be resolved.
+   * @throws {ContainerDisposedError} when `s` has already been disposed.
+   */
+  resolve(s: IContainer, { args = [], lazy }: ResolveOptions = {}): T {
+    const resolveSelected = () =>
+      s.resolveOneByAlias<T>(this.selectAlias(s), { args: this._getArgsFn({ scope: s, args }) });
+    return ProxyRegistry.getInstance().toLazyIf(resolveSelected as () => T & object, this._isLazy || lazy);
+  }
+
+  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.flag;
+  }
+
+  /** Whether the flag is on for `context`, and the named variant it serves, if any. */
+  protected evaluate(flags: IFeatureFlags, context: FeatureContext): FeatureEvaluation<V> {
+    const served = flags.getVariant(this.flag, context);
+    return served.enabled
+      ? { enabled: true, variant: served.name as V }
+      : { enabled: flags.isEnabled(this.flag, context) };
+  }
+
+  private copy(overrides: FeatureTokenOptions): this {
+    const Self = this.constructor as new (flag: string, options: FeatureTokenOptions) => this;
+    return new Self(this.flag, {
+      getArgsFn: this._getArgsFn,
+      isLazy: this._isLazy,
+      tags: this.getTags(),
+      ...overrides,
+    });
+  }
+
+  /**
+   * The alias of the served variant's implementation, or of the fallback.
+   *
+   * @throws {DependencyNotFoundError} when the flag has no fallback, or the flag client or the feature context cannot be resolved.
+   */
+  private selectAlias(s: IContainer): DependencyKey {
+    const fallback = this.fallbackAlias();
+    if (!s.hasAlias(fallback)) {
+      throw new DependencyNotFoundError(
+        `Feature flag "${this.flag}" has no fallback: a flag always has one. ` +
+          `Register it with @register(token.fallbackOf(feature)) in this scope or a parent.`,
+      );
+    }
+
+    const flags = IFeatureFlagsToken.resolve(s);
+    const context = IFeatureContextToken.resolve(s);
+    let served: FeatureEvaluation<V> = { enabled: false };
+    try {
+      served = this.evaluate(flags, context);
+    } catch {
+      // A flag always has a fallback: a failing client serves it.
+    }
+    const candidates = [
+      served.variant === undefined ? undefined : this.variantAlias(served.variant),
+      served.enabled ? this.primaryAlias() : undefined,
+    ];
+    return candidates.find((alias) => alias !== undefined && s.hasAlias(alias)) ?? fallback;
+  }
+}

package/lib/token/SingleAliasToken.ts

@@ -0,0 +1,28 @@
+import { type DependencyKey, type IContainer } from '../container/IContainer';
+import { BindableToken } from './BindableToken';
+import { type IRegistration } from '../registration/IRegistration';
+import { type ResolveOptions } from '../provider/IProvider';
+
+/**
+ * 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 BindableToken<T> {
+  select<R>(fn: (target: T) => R) {
+    return (s: IContainer) => fn(this.resolve(s));
+  }
+
+  /**
+   * @throws {DependencyNotFoundError} when no accessible registration carries the alias.
+   */
+  resolve(s: IContainer, options?: ResolveOptions): T {
+    return s.resolveOneByAlias(this.token, this.toResolveOptions(s, options));
+  }
+
+  protected bindKey(r: IRegistration<T>) {
+    r.bindToAlias(this.token);
+  }
+}
+
+/** Creates a {@link SingleAliasToken} for `token`. */
+export const toSingleAlias = <T>(token: DependencyKey) => new SingleAliasToken<T>(token);

package/lib/token/SingleToken.ts

@@ -0,0 +1,35 @@
+import { type IContainer } from '../container/IContainer';
+import { BindableToken } from './BindableToken';
+import { type IRegistration } from '../registration/IRegistration';
+import { type ResolveOptions } from '../provider/IProvider';
+
+/**
+ * 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(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 BindableToken<T> {
+  select<R>(fn: (target: T) => R) {
+    return (s: IContainer) => fn(this.resolve(s));
+  }
+
+  resolve(s: IContainer, options?: ResolveOptions): T {
+    return s.resolve(this.token, this.toResolveOptions(s, options));
+  }
+
+  protected bindKey(r: IRegistration<T>) {
+    r.bindToKey(this.token);
+  }
+}

package/lib/token/ToggleFeatureToken.ts

@@ -0,0 +1,27 @@
+import { type FeatureEvaluation, MultiVariantFeatureToken } from './MultiVariantFeatureToken';
+import { type FeatureContext, type IFeatureFlags } from '../feature/IFeatureFlags';
+
+/**
+ * The on/off case of {@link MultiVariantFeatureToken}: a flag with no named
+ * variants, only a primary one, served while `isEnabled` says so. Everything
+ * else - the fallback, the context, args and laziness - is the multi-variant
+ * token's.
+ *
+ * @example
+ * const PaymentGatewayToken = new ToggleFeatureToken<IPaymentGateway>('new-checkout');
+ *
+ * @register(new SingleToken<IPaymentGateway>('LegacyGateway').fallbackOf(PaymentGatewayToken))
+ * class LegacyGateway implements IPaymentGateway {}
+ *
+ * @register(new SingleToken<IPaymentGateway>('StripeGateway').primaryVariantOf(PaymentGatewayToken))
+ * class StripeGateway implements IPaymentGateway {}
+ *
+ * class Checkout {
+ *   constructor(@inject(by(PaymentGatewayToken)) gateway: IPaymentGateway) {}
+ * }
+ */
+export class ToggleFeatureToken<T = any> extends MultiVariantFeatureToken<T, never> {
+  protected override evaluate(flags: IFeatureFlags, context: FeatureContext): FeatureEvaluation<never> {
+    return { enabled: flags.isEnabled(this.flag, context) };
+  }
+}

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

package/lib/utils/TypedEvent.ts

@@ -0,0 +1,96 @@
+import { TypedEventDisposedError } from '../errors/TypedEventDisposedError';
+
+export type TypedEventListener<TArgs extends unknown[]> = (...args: TArgs) => void;
+
+export type Unsubscribe = () => void;
+
+/**
+ * The subscriber's side of a {@link TypedEvent}: attach, detach, tear down.
+ * Hand this out instead of the event itself so that only the owner can `emit`.
+ */
+export interface ITypedEvent<TArgs extends unknown[]> {
+  /**
+   * Attaches `listener` and returns a function which detaches it again. A
+   * listener subscribed more than once is still delivered each emission once.
+   *
+   * @throws {TypedEventDisposedError} when the event has already been disposed.
+   */
+  subscribe(listener: TypedEventListener<TArgs>): Unsubscribe;
+
+  /**
+   * Detaches `listener`. Harmless when it is not subscribed, or after `dispose`.
+   */
+  unsubscribe(listener: TypedEventListener<TArgs>): void;
+
+  /**
+   * Detaches every listener and rejects further `subscribe` / `emit` calls.
+   */
+  dispose(): void;
+}
+
+/**
+ * A typed, multi-listener event. `TArgs` is the argument list a listener
+ * receives, so a `TypedEvent<[IContainer]>` accepts `(scope: IContainer) => void`
+ * listeners unchanged.
+ *
+ * Emission delivers to the listeners subscribed at the moment `emit` is called,
+ * in subscription order. A listener detached mid-emission is skipped for the
+ * rest of that emission; one attached mid-emission receives only later ones.
+ */
+export class TypedEvent<TArgs extends unknown[] = []> implements ITypedEvent<TArgs> {
+  private readonly listeners = new Set<TypedEventListener<TArgs>>();
+  private isDisposed = false;
+
+  /**
+   * @throws {TypedEventDisposedError} when the event has already been disposed.
+   */
+  subscribe(listener: TypedEventListener<TArgs>): Unsubscribe {
+    this.validate();
+    this.listeners.add(listener);
+    return () => this.unsubscribe(listener);
+  }
+
+  unsubscribe(listener: TypedEventListener<TArgs>): void {
+    this.listeners.delete(listener);
+  }
+
+  /**
+   * Calls every current listener with `args`. What a listener throws surfaces
+   * out of `emit` and stops delivery to the listeners after it.
+   *
+   * @throws {TypedEventDisposedError} when the event has already been disposed.
+   * @throws {unknown} rethrows whatever a listener threw.
+   */
+  emit(...args: TArgs): void {
+    this.validate();
+    // Iterate a snapshot so a listener can (un)subscribe without disturbing this emission;
+    // a listener detached mid-emission is still skipped for the rest of it.
+    for (const listener of [...this.listeners]) {
+      if (this.listeners.has(listener)) {
+        listener(...args);
+      }
+    }
+  }
+
+  /**
+   * A copy of the current listeners, in subscription order.
+   */
+  getListeners(): TypedEventListener<TArgs>[] {
+    return [...this.listeners];
+  }
+
+  dispose(): void {
+    this.listeners.clear();
+    this.isDisposed = true;
+  }
+
+  /**
+   * @throws {TypedEventDisposedError} when the event has already been disposed.
+   */
+  private validate(): void {
+    TypedEventDisposedError.assert(
+      !this.isDisposed,
+      'TypedEvent is already disposed: its scope was disposed, so it accepts no new listeners.',
+    );
+  }
+}

package/lib/utils/array.ts

@@ -0,0 +1,28 @@
+import { ArgumentNotFoundError } from '../errors/ArgumentNotFoundError';
+
+export type Predicate<T> = (value: T) => boolean;
+
+export const Filter = {
+  exclude: <T>(arr: Set<T> | T[]) => {
+    const excludeSet = arr instanceof Array ? new Set(arr) : arr;
+    return (v: T) => !excludeSet.has(v);
+  },
+};
+
+/**
+ * Returns a picker of the first argument in `args` matching `predicate` - the
+ * shape `singleton(getCacheKey)` consumers expect.
+ *
+ * @throws {ArgumentNotFoundError} when no argument matches `predicate`
+ */
+export const findOrFail =
+  <T>(predicate: Predicate<T>) =>
+  (args: unknown[] = []): T => {
+    const index = args.findIndex((arg) => predicate(arg as T));
+
+    if (index === -1) {
+      throw new ArgumentNotFoundError(`No argument matches the predicate (received ${args.length} args).`);
+    }
+
+    return args[index] as T;
+  };

package/lib/utils/basic.ts

@@ -0,0 +1,34 @@
+/** A class that constructs `T`. */
+export type constructor<T> = new (...args: any[]) => T;
+
+/** Something with a meaningful `toString()`, e.g. a token used as a cache key. */
+export interface Serializable {
+  toString(): string;
+}
+
+/**
+ * Tags a structural type with a name, so `Instance` reads as its own type in
+ * signatures and error messages instead of a bare `object`. The tag is optional
+ * on purpose: values stay assignable without a cast.
+ */
+export type Branded<TBrand extends string, T> = T & { readonly __brand?: TBrand };
+
+/**
+ * What the container tracks and reflects on: the object a constructor produced.
+ * Deliberately not a constructor signature - an instance is not its own constructor.
+ */
+export type Instance = Branded<'Instance', object>;
+
+export const Is = {
+  nullish: <T>(value: T | undefined | null): value is null | undefined => value === undefined || value === null,
+  object: (target: unknown): target is object => target !== null && typeof target === 'object',
+  instance: (target: unknown): target is Instance => Object.prototype.hasOwnProperty.call(target, 'constructor'),
+  constructor: (target: unknown): target is constructor<unknown> => typeof target === 'function' && !!target.prototype,
+};
+
+// Every object inherits `Object.prototype.toString`, so only an overridden one counts as serialization.
+export function isSerializable(target: unknown): target is Serializable {
+  return Is.object(target) && typeof target.toString === 'function' && target.toString !== Object.prototype.toString;
+}
+
+export const toString = (target: unknown): string => (isSerializable(target) ? target.toString() : String(target));

package/lib/utils/debounce.ts

@@ -0,0 +1,18 @@
+/** Method decorator: delays the call until `ms` passed without another call (per instance). */
+export const debounce =
+  (ms: number): MethodDecorator =>
+  (target, propertyKey, descriptor: PropertyDescriptor) => {
+    const originalMethod = descriptor.value;
+    const timerMap = new WeakMap<object, ReturnType<typeof setTimeout>>();
+    descriptor.value = function (...args: unknown[]) {
+      const prev = timerMap.get(this);
+      if (prev !== undefined) {
+        clearTimeout(prev);
+      }
+      timerMap.set(
+        this,
+        setTimeout(() => originalMethod.apply(this, args), ms),
+      );
+    };
+    return descriptor;
+  };

package/lib/utils/errorHandler.ts

@@ -0,0 +1,34 @@
+import { resolveConstructor } from '../metadata/target';
+
+/** Receives the error with the class and method it came from. */
+export type HandleErrorParams = (error: unknown, context: { target: string; method: string }) => void;
+
+/** Method decorator: routes a rejection of the async method to `errorHandler` instead of throwing. */
+export const handleAsyncError =
+  (errorHandler: HandleErrorParams): MethodDecorator =>
+  (target, propertyKey, descriptor: PropertyDescriptor) => {
+    const originalMethod = descriptor.value;
+    descriptor.value = async function (...args: unknown[]) {
+      try {
+        return await originalMethod.apply(this, args);
+      } catch (e) {
+        errorHandler(e, { target: resolveConstructor(target).name, method: propertyKey as string });
+      }
+    };
+    return descriptor;
+  };
+
+/** Method decorator: routes a throw of the method to `errorHandler` instead of throwing. */
+export const handleError =
+  (errorHandler: HandleErrorParams): MethodDecorator =>
+  (target, propertyKey, descriptor: PropertyDescriptor) => {
+    const originalMethod = descriptor.value;
+    descriptor.value = function (...args: unknown[]) {
+      try {
+        return originalMethod.apply(this, args);
+      } catch (e) {
+        errorHandler(e, { target: resolveConstructor(target).name, method: propertyKey as string });
+      }
+    };
+    return descriptor;
+  };