ts-ioc-container 72.1.0 → 72.3.0

package/lib/hooks/hook.ts

@@ -0,0 +1,89 @@
+import { type IHookContext } from './HookContext';
+import { type constructor, type Instance, Is } from '../utils/basic';
+import { resolveConstructor } from '../metadata/target';
+import { getConstructorChain } from '../utils/getConstructorChain';
+import { ProviderOptions } from '../provider/IProvider';
+
+/**
+ * What `@inject(...)` and `injectProp(...)` take: a function of the resolution
+ * context returning the value to inject. Usually built with `by(...)` or `arg(...)`.
+ */
+export type InjectFn<T = unknown> = (options: ProviderOptions) => T;
+
+/** A hook as a function of its context. Must return `void` or `Promise<void>`. */
+export type HookFn<T extends IHookContext = IHookContext> = (context: T) => void | Promise<void>;
+
+/** A hook as a class resolved from the scope; its `execute` receives the context. */
+export interface HookClass<T extends IHookContext = IHookContext> {
+  execute(context: Omit<T, 'scope'>): void | Promise<void>;
+}
+
+/** Anything `@hook(...)` accepts: a {@link HookFn} or a {@link HookClass} constructor. */
+export type HookType<T extends IHookContext = IHookContext> = HookFn<T> | constructor<HookClass<T>>;
+
+/** The hooks of one class under one key, by member name: one hook per member (compose with `sequential` / `parallel`). */
+export type HooksOfClass = Map<string, HookType>;
+
+const isHookClassConstructor = <C extends IHookContext>(
+  execute: HookFn<C> | constructor<HookClass<C>>,
+): execute is constructor<HookClass<C>> => {
+  return Is.constructor(execute) && execute.prototype.execute;
+};
+
+/** Normalizes a {@link HookType} to a {@link HookFn}; a hook class is resolved from the context's scope. */
+export const toHookFn = <C extends IHookContext>(execute: HookFn<C> | constructor<HookClass<C>>): HookFn<C> =>
+  isHookClassConstructor(execute) ? (context) => context.scope.resolve(execute).execute(context) : execute;
+
+/**
+ * Reads the hooks declared under `key`, merging hooks declared on parent classes.
+ * Hooks are collected from base to derived, so a derived class's hook for the
+ * same member replaces the parent's.
+ *
+ * `target` is an instance or its class, a proxy of either included - it is
+ * normalized by `resolveConstructor`, so callers never unwrap it themselves.
+ *
+ * The merge runs on every call and returns a fresh map. Hook metadata is fixed
+ * once a class is defined, so a caller which reads it often can wrap this in
+ * `memoize` (`HookCollector` already does).
+ */
+export function getHooks(target: Instance | constructor<unknown>, key: string | symbol): HooksOfClass {
+  const merged: HooksOfClass = new Map();
+  for (const ctor of getConstructorChain(resolveConstructor(target)).reverse()) {
+    const ownHooks: HooksOfClass | undefined = Reflect.getOwnMetadata(key, ctor);
+    if (ownHooks) {
+      for (const [methodName, fn] of ownHooks) {
+        merged.set(methodName, fn);
+      }
+    }
+  }
+  return merged;
+}
+
+/** Whether `target` (an instance or class, proxies included) declares any hook under `key`. */
+export function hasHooks(target: Instance | constructor<unknown>, key: string | symbol): boolean {
+  return getConstructorChain(resolveConstructor(target)).some((ctor) => Reflect.hasOwnMetadata(key, ctor));
+}
+
+/**
+ * Method/property decorator that declares a hook under `key`. The library only
+ * stores it: collect with `new HookCollector({ key })` and run the actions
+ * yourself. A member carries exactly one hook per key - decorating it twice
+ * replaces the earlier hook; compose several with `sequential(...)` / `parallel(...)`.
+ *
+ * @example
+ * const onInit = (fn: HookType) => hook('onInit', fn);
+ *
+ * class Service {
+ *   @onInit((ctx) => {
+ *     ctx.invokeMethod({ args: ctx.resolveArgs() });
+ *   })
+ *   init() {}
+ * }
+ */
+export const hook = (key: string | symbol, fn: HookType) => (target: object, propertyKey: string | symbol) => {
+  const hooks: HooksOfClass = Reflect.hasOwnMetadata(key, target.constructor)
+    ? Reflect.getOwnMetadata(key, target.constructor)
+    : new Map();
+  hooks.set(propertyKey as string, fn);
+  Reflect.defineMetadata(key, hooks, target.constructor);
+};

package/lib/hooks/injectProp.ts

@@ -0,0 +1,14 @@
+import { HookFn, InjectFn } from './hook';
+
+/**
+ * Injects a dependency into the decorated property.
+ *
+ * `fn` is an `InjectFn`, exactly as for `@inject`: it receives the resolution
+ * context and returns the value to assign, so `injectProp(({ scope }) =>
+ * scope.resolve('key'))` assigns the dependency and `injectProp(pipe(fn, sanitize()))`
+ * a mapped one.
+ */
+export const injectProp =
+  <T>(fn: InjectFn<T>): HookFn =>
+  (context) =>
+    context.setProperty(fn);

package/lib/index.ts

@@ -0,0 +1,197 @@
+// Containers
+export {
+  type IContainer,
+  type Resolvable,
+  type IContainerModule,
+  type DependencyKey,
+  type Tag,
+  type Tagged,
+  type ResolveOneOptions,
+  type ResolveManyOptions,
+  type ScopeHook,
+  type RegisteredHook,
+  type AutoResolveOptions,
+  isDependencyKey,
+} from './container/IContainer';
+export { Container } from './container/Container';
+export { AutoResolveModule } from './container/AutoResolveModule';
+export { EmptyContainer } from './container/EmptyContainer';
+
+// Injectors
+export {
+  type IInjector,
+  type InjectOptions,
+  type WithScope,
+  type WithArgs,
+  type IInjectFnResolver,
+  type IInjectorModule,
+  type InjectorHook,
+  Injector,
+} from './injector/IInjector';
+export { MetadataInjector, inject, arg, args, argsFn, by, resolveArgs } from './injector/MetadataInjector';
+export { SimpleInjector } from './injector/SimpleInjector';
+export { ProxyInjector } from './injector/ProxyInjector';
+
+// Providers
+export {
+  type ResolveDependency,
+  type IProvider,
+  type DecorateFn,
+  type ArgsFn,
+  type ProviderOptions,
+  type ResolveOptions,
+  type GetCacheKey,
+  type ScopeAccessOptions,
+  type ScopeAccessRule,
+  type ProviderHook,
+} from './provider/IProvider';
+export { Provider } from './provider/Provider';
+
+// Registrations
+export {
+  type IRegistration,
+  type ReturnTypeOfRegistration,
+  type ScopeMatchRule,
+  type ProviderPipe,
+  type Bindable,
+  type ProviderMapper,
+  type RegistrationMapper,
+  isProviderPipe,
+  registerPipe,
+  toBindToken,
+  toProviderFn,
+  toRegistrationFn,
+  register,
+  bindTo,
+  scope,
+  scopeAccess,
+  lazy,
+  autoResolve,
+  singleton,
+  decorate,
+  appendArgs,
+  appendArgsFn,
+  onResolve,
+} from './registration/IRegistration';
+export { Registration } from './registration/Registration';
+
+// Errors
+export { ContainerError } from './errors/ContainerError';
+export { DependencyNotFoundError } from './errors/DependencyNotFoundError';
+export { ContainerNotFoundError } from './errors/ContainerNotFoundError';
+export { DependencyMissingKeyError } from './errors/DependencyMissingKeyError';
+export { MethodNotImplementedError } from './errors/MethodNotImplementedError';
+export { ContainerDisposedError } from './errors/ContainerDisposedError';
+export { ProviderDisposedError } from './errors/ProviderDisposedError';
+export { CannotApplySingletonTwiceError } from './errors/CannotApplySingletonTwiceError';
+export { CannonSingletonApplyTwiceError } from './errors/CannonSingletonApplyTwiceError';
+export { UnsupportedTokenTypeError } from './errors/UnsupportedTokenTypeError';
+export { TypedEventDisposedError } from './errors/TypedEventDisposedError';
+export { ArgumentNotFoundError } from './errors/ArgumentNotFoundError';
+
+// Hooks
+export {
+  getHooks,
+  hook,
+  hasHooks,
+  toHookFn,
+  type HookFn,
+  type HookClass,
+  type HookType,
+  type InjectFn,
+  type HooksOfClass,
+} from './hooks/hook';
+export {
+  HookContext,
+  createHookContextFactory,
+  createHookExecutionContext,
+  type CreateHookExecutionContext,
+  type IHookContext,
+} from './hooks/HookContext';
+export { injectProp } from './hooks/injectProp';
+export { sequential, parallel, oncePerInstance, type ResolvedObjectHook } from './hooks/combinators';
+export {
+  HookCollector,
+  toTask,
+  type HookAction,
+  type HookCollectionContext,
+  type HookCollectorOptions,
+  type HookCollectorProps,
+  type MapHookExecutionContext,
+} from './hooks/HookCollector';
+
+// Tokens
+export { InjectionToken, isInjectionToken, forwardArgs } from './token/InjectionToken';
+export { type Injectable, toToken, argToToken } from './token/toToken';
+export { GroupAliasToken, toGroupAlias } from './token/GroupAliasToken';
+export { SingleAliasToken, toSingleAlias } from './token/SingleAliasToken';
+export { ClassToken } from './token/ClassToken';
+export { BindableToken, type BindableTokenOptions } from './token/BindableToken';
+export { SingleToken } from './token/SingleToken';
+export { FunctionToken } from './token/FunctionToken';
+export { ConstantToken } from './token/ConstantToken';
+export { type InstancePredicate, GroupInstanceToken } from './token/GroupInstanceToken';
+export {
+  MultiVariantFeatureToken,
+  type FeatureTokenOptions,
+  type FeatureEvaluation,
+} from './token/MultiVariantFeatureToken';
+export { ToggleFeatureToken } from './token/ToggleFeatureToken';
+
+// Feature flags
+export {
+  type IFeatureFlags,
+  type FeatureContext,
+  type FeatureVariant,
+  IFeatureFlagsToken,
+  IFeatureContextToken,
+} from './feature/IFeatureFlags';
+
+// Metadata
+export { resolveConstructor } from './metadata/target';
+export {
+  addClassMeta,
+  getClassMeta,
+  addClassLabel,
+  getClassLabels,
+  addClassTag,
+  getClassTags,
+  createComposeClassDecorator,
+} from './metadata/class';
+export {
+  addParamMeta,
+  getParamMeta,
+  addParamLabel,
+  getParamLabels,
+  addParamTag,
+  getParamTags,
+  createComposeParameterDecorator,
+} from './metadata/parameter';
+export {
+  addMethodMeta,
+  getMethodMeta,
+  addMethodLabel,
+  getMethodLabels,
+  addMethodTag,
+  getMethodTags,
+  createComposeMethodDecorator,
+} from './metadata/method';
+export { handleError, handleAsyncError, type HandleErrorParams } from './utils/errorHandler';
+export { runInOrder, runAtOnce, type Task } from './utils/task';
+export { throttle } from './utils/throttle';
+export { debounce } from './utils/debounce';
+export { shallowCache } from './utils/shallowCache';
+export { once } from './utils/once';
+export { memoize } from './utils/memoize';
+export { getConstructorChain } from './utils/getConstructorChain';
+export { TypedEvent, type ITypedEvent, type TypedEventListener, type Unsubscribe } from './utils/TypedEvent';
+
+// Execution
+export { type ExecutionContext } from './ExecutionContext';
+
+// Utils
+export { select } from './select';
+export { pipe, type MapFn } from './utils/fp';
+export { findOrFail, type Predicate } from './utils/array';
+export { ProxyRegistry, unwrapProxy, type IProxyRegistry } from './utils/ProxyRegistry';
+export { type Branded, type constructor, type Instance, type Serializable, Is, isSerializable } from './utils/basic';

package/lib/injector/IInjector.ts

@@ -0,0 +1,88 @@
+import { type IContainer, ResolveOneOptions } from '../container/IContainer';
+import { ProviderOptions } from '../provider/IProvider';
+import { type IProxyRegistry, ProxyRegistry } from '../utils/ProxyRegistry';
+import { type constructor, Instance } from '../utils/basic';
+
+export type WithScope = { scope: IContainer };
+export type WithArgs = { args: unknown[] };
+/**
+ * What an injector needs to build an instance: the scope it is built in, plus
+ * the runtime `args`. The scope travels inside the options rather than beside
+ * them, so every function handed a resolution context - `InjectFn`, `ArgsFn`,
+ * `ResolveDependency`, `IProvider.resolve`, `IInjector.resolve` - takes one
+ * object and destructures what it uses.
+ */
+export type InjectOptions = WithScope & Partial<WithArgs>;
+
+/**
+ * Injector hooks - the injector's own domain: an instance was constructed.
+ *
+ * Construction is the injector's business, so the hook list belongs to the
+ * injector rather than to a scope. One injector is shared by a container and
+ * every scope created from it, so a hook added here observes construction in
+ * all of them.
+ */
+export type InjectorHook = (instance: Instance, scope: IContainer) => void;
+
+/** Builds instances of classes for a scope. Shared by a container and every scope created from it. */
+export interface IInjector {
+  resolve<T>(Target: constructor<T>, options: ProviderOptions): T;
+
+  onConstructed(...hooks: InjectorHook[]): this;
+}
+
+/**
+ * The injector counterpart of `IContainerModule`: an opt-in bundle of injector
+ * hooks, applied to the injector before it is handed to a container.
+ */
+export interface IInjectorModule {
+  applyTo(injector: IInjector): void;
+}
+
+/** Something that resolves a value from a scope. */
+export interface IInjectFnResolver<T> {
+  resolve(s: IContainer, options?: ResolveOneOptions): T;
+}
+
+/**
+ * Base class of the bundled injectors: tracks the instance in the scope, runs
+ * `onConstructed` hooks and handles `lazy`. Subclass it and implement
+ * `createInstance` for a custom injection strategy.
+ */
+export abstract class Injector {
+  private readonly onConstructedHookList: InjectorHook[] = [];
+
+  constructor(private readonly proxyRegistry: IProxyRegistry = ProxyRegistry.getInstance()) {}
+
+  resolve<T>(Target: constructor<T>, { scope, args, lazy }: ProviderOptions): T {
+    // @ts-ignore
+    return this.proxyRegistry.toLazyIf(() => {
+      const instance = this.createInstance(Target, { scope, args }) as Instance;
+      scope.addInstance(instance);
+
+      // Hooks run once the scope tracks the instance, so they observe a scope which owns it.
+      for (const onConstructed of this.onConstructedHookList) {
+        onConstructed(instance, scope);
+      }
+
+      return instance;
+    }, lazy);
+  }
+
+  /**
+   * Hooks run after the constructed instance is handed to the scope, and before
+   * it reaches the caller. A `lazy` resolve returns a proxy first, so its hooks
+   * run when the proxy is first touched.
+   */
+  onConstructed(...hooks: InjectorHook[]): this {
+    this.onConstructedHookList.push(...hooks);
+    return this;
+  }
+
+  useModule(module: IInjectorModule): this {
+    module.applyTo(this);
+    return this;
+  }
+
+  protected abstract createInstance<T>(Target: constructor<T>, options: InjectOptions): T;
+}

package/lib/injector/MetadataInjector.ts

@@ -0,0 +1,100 @@
+import { IInjector, InjectOptions, Injector } from './IInjector';
+import { type constructor, type Instance } from '../utils/basic';
+import { resolveConstructor } from '../metadata/target';
+import { addParamMeta, getParamMeta } from '../metadata/parameter';
+import { ProviderOptions } from '../provider/IProvider';
+import { InjectFn } from '../hooks/hook';
+import { type DependencyKey } from '../container/IContainer';
+import { type InjectionToken } from '../token/InjectionToken';
+import { toToken } from '../token/toToken';
+
+/**
+ * The default injector: builds a class by calling each constructor parameter's
+ * `@inject(...)` function. Parameters without `@inject` receive `undefined`.
+ * Needs `reflect-metadata` imported once at the entrypoint.
+ *
+ * @example
+ * const container = new Container({ injector: new MetadataInjector() });
+ */
+export class MetadataInjector extends Injector implements IInjector {
+  protected createInstance<T>(Target: constructor<T>, { scope, args: deps = [] }: InjectOptions): T {
+    const args = resolveArgs(Target)({ scope, args: deps });
+    return new Target(...args);
+  }
+}
+
+const hookMetaKey = (methodName = 'constructor') => `inject:${methodName}`;
+
+/**
+ * Injects a dependency into a constructor parameter.
+ *
+ * `fn` receives the resolution context - the `scope` the instance is built in and
+ * the runtime `args` it is built with - and returns the value to inject. That is
+ * the whole contract: a token, key or class is resolved with {@link by}, a
+ * runtime argument picked with {@link arg}, and a mapped value is
+ * `pipe(fn, ...mappers)`.
+ *
+ * @example
+ * class App {
+ *   constructor(
+ *     @inject(by(ILoggerToken)) private logger: ILogger,
+ *     @inject(pipe(by(ConfigToken), (c) => c.apiUrl)) private apiUrl: string,
+ *     @inject(arg(0)) private tenantId: string,
+ *   ) {}
+ * }
+ */
+export function inject<T>(fn: InjectFn<T>): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => {
+    addParamMeta(hookMetaKey(propertyKey as string), () => fn)(resolveConstructor(target), propertyKey, parameterIndex);
+  };
+}
+
+/**
+ * The `InjectFn` which resolves `target` - an `InjectionToken`, a `DependencyKey`
+ * or a class - from the scope, handing it the runtime args of the class being
+ * constructed (see "Runtime args flow through tokens" in the README) and the
+ * `lazy` flag: `@inject(by(Token))`, `@inject(by('key'))`, `@inject(by(Logger))`.
+ * Being a function, it composes: `pipe(by(Config), (c) => c.apiUrl)`.
+ *
+ * @throws {UnsupportedTokenTypeError} when `target` is none of the three.
+ */
+export const by = <T>(target: InjectionToken<T> | DependencyKey | constructor<T>): InjectFn<T> => {
+  const token = toToken(target);
+  return ({ scope, ...options }) => token.resolve(scope, options);
+};
+
+/**
+ * Injects the first runtime arg matching `predicate`, or `undefined`.
+ *
+ * @example
+ * constructor(@inject(argsFn((value) => typeof value === 'string')) readonly name: string) {}
+ */
+export const argsFn =
+  <T = unknown>(predicate: (value: unknown, index: number) => boolean): InjectFn<T> =>
+  ({ args = [] }): T =>
+    args.find((value, index) => predicate(value, index)) as T;
+
+/**
+ * Injects the runtime arg at `index`, or `undefined`. Args arrive as passed:
+ * a token in the args list is not resolved.
+ *
+ * @example
+ * constructor(@inject(arg(0)) readonly baseUrl: string) {}
+ * // Token.args('https://api.example.com').resolve(scope)
+ */
+export const arg = <T = unknown>(index: number): InjectFn<T> => argsFn<T>((value, i) => i === index);
+
+/** Injects the whole runtime args array. */
+export const args: InjectFn<unknown[]> = ({ args = [] }) => args;
+
+/**
+ * Resolves the arguments annotated with `@inject` on `target`'s constructor, or on
+ * its `methodName` method, by calling each parameter's `InjectFn` with `options`.
+ *
+ * `target` is the class or any instance of it - a proxy included, since it is
+ * unwrapped on the way to the metadata (see {@link resolveConstructor}).
+ */
+export const resolveArgs = (target: constructor<unknown> | Instance, methodName?: string) => {
+  const fns = getParamMeta(hookMetaKey(methodName), target) as InjectFn[];
+  return (options: ProviderOptions): unknown[] => fns.map((fn) => fn(options));
+};

package/lib/injector/ProxyInjector.ts

@@ -0,0 +1,31 @@
+import { IInjector, InjectOptions, Injector } from './IInjector';
+import { type constructor } from '../utils/basic';
+
+/**
+ * Injector that passes one proxy object as the first constructor argument:
+ * reading `deps.someKey` resolves `'someKey'`, a property name containing
+ * "alias" resolves by alias, and `deps.args` returns the runtime args. Needs no
+ * decorators or `reflect-metadata`.
+ *
+ * @example
+ * class App {
+ *   constructor({ logger }: { logger: ILogger }) {}
+ * }
+ * new Container({ injector: new ProxyInjector() });
+ */
+export class ProxyInjector extends Injector implements IInjector {
+  protected createInstance<T>(Target: constructor<T>, { scope, args = [] }: InjectOptions): T {
+    const proxy = new Proxy(
+      {},
+      {
+        get(target: {}, prop: string | symbol): any {
+          if (prop === 'args') {
+            return args;
+          }
+          return prop.toString().search(/alias/gi) >= 0 ? scope.resolveByAlias(prop) : scope.resolve(prop);
+        },
+      },
+    );
+    return new Target(proxy);
+  }
+}

package/lib/injector/SimpleInjector.ts

@@ -0,0 +1,20 @@
+import { IInjector, InjectOptions, Injector } from './IInjector';
+import { type constructor } from '../utils/basic';
+
+/**
+ * Injector that passes the scope itself as the first constructor argument,
+ * followed by the runtime args. Needs no decorators or `reflect-metadata`.
+ *
+ * @example
+ * class App {
+ *   constructor(scope: IContainer) {
+ *     this.logger = scope.resolve('Logger');
+ *   }
+ * }
+ * new Container({ injector: new SimpleInjector() });
+ */
+export class SimpleInjector extends Injector implements IInjector {
+  protected createInstance<T>(Target: constructor<T>, { scope, args = [] }: InjectOptions): T {
+    return new Target(scope, ...args);
+  }
+}

package/lib/metadata/class.ts

@@ -0,0 +1,50 @@
+import { resolveConstructor } from './target';
+
+/** Decorator that writes class metadata under `key`; `mapFn` receives the previous value. */
+export const addClassMeta =
+  <T>(key: string | symbol, mapFn: (prev: T | undefined) => T): ClassDecorator =>
+  (target) => {
+    const value: T | undefined = Reflect.getOwnMetadata(key, target);
+    Reflect.defineMetadata(key, mapFn(value), target);
+  };
+
+/** Reads class metadata written by `addClassMeta`. */
+export function getClassMeta<T>(target: object, key: string | symbol): T | undefined {
+  return Reflect.getOwnMetadata(key, resolveConstructor(target));
+}
+
+/** Decorator that attaches a `key` -> `label` pair to a class. */
+export const addClassLabel = (key: string, label: string) =>
+  addClassMeta('label', (prev: Map<string, string> = new Map()) => prev.set(key, label));
+/** Reads the labels written by `addClassLabel`. */
+export const getClassLabels = (target: object): Map<string, string> => getClassMeta(target, 'label') ?? new Map();
+
+/** Decorator that attaches a tag to a class. */
+export const addClassTag = (tag: string) => addClassMeta('tag', (prev: Set<string> = new Set()) => prev.add(tag));
+/** Reads the tags written by `addClassTag`. */
+export const getClassTags = (target: object): Set<string> => getClassMeta(target, 'tag') ?? new Set();
+
+/**
+ * Applies several class decorators as one, so a stack repeated on many classes
+ * can be given a name:
+ *
+ * ```typescript
+ * const repository = <T>(token: SingleToken<T>, ...mappers: RegistrationMapper<T>[]) =>
+ *   createComposeClassDecorator(
+ *     register(IRepositoryToken, token, addMediator(token), ...mappers),
+ *     addClassMeta('injection-token', () => token),
+ *   );
+ * ```
+ *
+ * Decorators are applied bottom-up, exactly as stacking them would be, so
+ * `@createComposeClassDecorator(a, b)` behaves like `@a @b` - moving a stack into one
+ * call never changes which decorator writes its metadata first.
+ *
+ * A decorator which returns a replacement class hands it to the next one, and
+ * the last replacement is returned - the same threading the runtime does for a
+ * stack.
+ */
+export const createComposeClassDecorator =
+  (...decorators: ClassDecorator[]): ClassDecorator =>
+  (target) =>
+    decorators.reduceRight((acc, decorate) => decorate(acc) ?? acc, target);

package/lib/metadata/method.ts

@@ -0,0 +1,47 @@
+import { resolveConstructor } from './target';
+
+/** Decorator that writes method metadata under `key`; `mapFn` receives the previous value. */
+export const addMethodMeta =
+  <T>(key: string, mapFn: (prev: T | undefined) => T): MethodDecorator =>
+  (target, propertyKey) => {
+    const metadata: T | undefined = Reflect.getMetadata(key, target.constructor, propertyKey);
+    Reflect.defineMetadata(key, mapFn(metadata), target.constructor, propertyKey);
+  };
+/** Reads method metadata written by `addMethodMeta`. */
+export const getMethodMeta = (key: string, target: object, propertyKey: string): unknown =>
+  Reflect.getMetadata(key, resolveConstructor(target), propertyKey);
+
+/** Decorator that attaches a `key` -> `label` pair to a method. */
+export const addMethodLabel = (key: string, label: string) =>
+  addMethodMeta('label', (prev: Map<string, string> = new Map()) => prev.set(key, label));
+/** Reads the labels written by `addMethodLabel`. */
+export const getMethodLabels = (target: object, propertyKey: string): Map<string, string> =>
+  (getMethodMeta('label', target, propertyKey) as Map<string, string> | undefined) ?? new Map();
+
+/** Decorator that attaches a tag to a method. */
+export const addMethodTag = (tag: string) => addMethodMeta('tag', (prev: Set<string> = new Set()) => prev.add(tag));
+/** Reads the tags written by `addMethodTag`. */
+export const getMethodTags = (target: object, propertyKey: string): Set<string> =>
+  (getMethodMeta('tag', target, propertyKey) as Set<string> | undefined) ?? new Set();
+
+/**
+ * Applies several method decorators as one, so a stack repeated on many members
+ * can be given a name:
+ *
+ * ```typescript
+ * const handler = (event: string) =>
+ *   createComposeMethodDecorator(addMethodTag('handler'), addMethodMeta('event', () => event));
+ * ```
+ *
+ * Decorators are applied bottom-up, exactly as stacking them would be, so
+ * `@createComposeMethodDecorator(a, b)` behaves like `@a @b`.
+ *
+ * The property descriptor is threaded through the chain the way the runtime
+ * threads it: a decorator which returns a replacement descriptor hands it to the
+ * next one, and the last replacement is returned. That is what makes wrapping
+ * decorators such as `@once` or `@throttle` compose here.
+ */
+export const createComposeMethodDecorator =
+  (...decorators: MethodDecorator[]): MethodDecorator =>
+  (target, propertyKey, descriptor) =>
+    decorators.reduceRight((acc, decorate) => decorate(target, propertyKey, acc) ?? acc, descriptor);