ts-ioc-container 72.1.0 → 72.3.0

package/lib/container/IContainer.ts

@@ -0,0 +1,159 @@
+import { type IProvider, ResolveOptions } from '../provider/IProvider';
+import { type IRegistration } from '../registration/IRegistration';
+import { IInjector, type WithArgs } from '../injector/IInjector';
+import { type constructor, Instance } from '../utils/basic';
+import { type ITypedEvent } from '../utils/TypedEvent';
+
+/** A registration key: a string or a symbol. */
+export type DependencyKey = string | symbol;
+/** Narrows `target` to a {@link DependencyKey}. */
+export function isDependencyKey(target: unknown): target is DependencyKey {
+  return typeof target === 'symbol' || typeof target === 'string';
+}
+
+/** A scope label (`'application'`, `'request'`, ...) matched by `scope(...)` rules. */
+export type Tag = string;
+type WithTags = { tags: Tag[] };
+type WithChild = { child: Tagged };
+type WithExcludedKeys = { excludedKeys: DependencyKey[] };
+/** Something carrying tags: a scope or a token. */
+export interface Tagged {
+  hasTag(tag: Tag): boolean;
+  addTags(...tags: Tag[]): void;
+}
+
+/** Options of `resolve`: runtime `args`, `lazy`, and the invoking `child` scope. */
+export type ResolveOneOptions = ResolveOptions & Partial<WithChild>;
+/** Options of `resolveByAlias`: like {@link ResolveOneOptions}, plus keys to exclude. */
+export type ResolveManyOptions = ResolveOneOptions & Partial<WithExcludedKeys>;
+/** Something that resolves a key or a class. */
+export interface Resolvable {
+  resolve<T>(key: constructor<T> | DependencyKey, options?: ResolveOneOptions): T;
+}
+
+/**
+ * A reusable bundle of registrations or event subscriptions applied with
+ * `container.useModule(module)`. A plain object with `applyTo` is enough.
+ *
+ * @example
+ * const loggingModule: IContainerModule = {
+ *   applyTo: (container) => container.addRegistration(Registration.fromClass(Logger)),
+ * };
+ */
+export interface IContainerModule {
+  applyTo(container: IContainer): void;
+}
+/** Options of `createScope`: the child scope's `tags`. */
+export type CreateScopeOptions = Partial<WithTags>;
+export type AutoResolveOptions = Partial<WithArgs>;
+export type RegisterOptions = { aliases?: DependencyKey[] };
+
+/**
+ * Scope event hooks - the container's own domain: a scope was created, a scope
+ * was disposed. The listener type of `IContainer.scopeCreated` / `scopeDisposed`.
+ *
+ * The other two hook domains live with the abstraction which raises them:
+ * injector hooks on `IInjector` (`InjectorHook`), provider hooks on
+ * {@link IProvider} (`ProviderHook`). An injector is configured before it is
+ * passed to a container's constructor, so a container never hands its injector
+ * out.
+ */
+export type ScopeHook = (scope: IContainer) => void;
+
+/**
+ * Scope event hook for a registration landing in a scope: a provider entered
+ * the provider map under `key`. Registration is always of a provider, so the
+ * name says only what varies. The listener type of `IContainer.registered`.
+ */
+export type RegisteredHook = (provider: IProvider, key: DependencyKey, scope: IContainer) => void;
+
+/** A dependency injection scope. See {@link Container}. */
+export interface IContainer extends Tagged {
+  readonly isDisposed: boolean;
+
+  /**
+   * Raised once a scope this container created is fully registered and attached.
+   * The subscriber's side only - a container raises its own scope events.
+   */
+  readonly scopeCreated: ITypedEvent<[IContainer]>;
+
+  /**
+   * Raised by this container as it disposes, before its providers and instances go.
+   */
+  readonly scopeDisposed: ITypedEvent<[IContainer]>;
+
+  /**
+   * Raised once a provider is registered here under a resolvable key.
+   */
+  readonly registered: ITypedEvent<[IProvider, DependencyKey, IContainer]>;
+
+  /** Low-level: puts `value` under `key` in this scope only. Prefer `addRegistration`. */
+  register(key: DependencyKey, value: IProvider, options?: RegisterOptions): this;
+
+  /** Registers here if the registration's scope rules match, and remembers it for future child scopes. */
+  addRegistration(registration: IRegistration): this;
+
+  /** Registrations added to this scope and its parents - what `createScope` copies. */
+  getRegistrations(): IRegistration[];
+
+  /** Whether a provider is registered under `key` in this scope (parents are not checked). */
+  hasRegistration(key: DependencyKey): boolean;
+
+  /** Whether a provider carrying `alias` is registered in this scope or a parent. Never throws for a missing alias. */
+  hasAlias(alias: DependencyKey): boolean;
+
+  /**
+   * Resolves a key, or constructs a class with the injector. Takes a key or a
+   * class, not a token: for a token call `token.resolve(scope)`.
+   *
+   * @example
+   * scope.resolve<ILogger>('ILogger');
+   * scope.resolve(App, { args: ['tenant-1'] });
+   */
+  resolve<T>(target: constructor<T> | DependencyKey, options?: ResolveOneOptions): T;
+
+  /** Resolves every accessible dependency registered under `alias`, in this scope and its parents. */
+  resolveByAlias<T>(alias: DependencyKey, options?: ResolveManyOptions): T[];
+
+  /** Resolves one dependency registered under `alias`, looking here first and then in parents. */
+  resolveOneByAlias<T>(alias: DependencyKey, options?: ResolveOneOptions): T;
+
+  /**
+   * Creates a child scope and copies into it the registrations whose scope
+   * rules match its tags. Registrations added later are not copied into it.
+   *
+   * @example
+   * const request = app.createScope({ tags: ['request'] });
+   */
+  createScope(options?: CreateScopeOptions): IContainer;
+
+  /** Resolves every provider marked with `autoResolve()`. */
+  autoResolve(options?: AutoResolveOptions): this;
+
+  /** Direct child scopes that are still alive. */
+  getScopes(): IContainer[];
+
+  /** Detaches a child scope; called by the child on dispose. */
+  removeScope(child: IContainer): void;
+
+  /** Applies a module to this scope. */
+  useModule(module: IContainerModule): this;
+
+  /** The parent scope, if any. */
+  getParent(): IContainer | undefined;
+
+  /** Instances constructed in this scope, and in child scopes when `cascade` is true. */
+  getInstances(cascade?: boolean): Instance[];
+
+  /** Whether this scope tracks `instance`. */
+  hasInstance(instance: Instance): boolean;
+
+  /** Raises `scopeDisposed`, drops providers and instances, and detaches from the parent. Child scopes are not disposed. */
+  dispose(): void;
+
+  /** Tracks an instance in this scope; called by the injector. */
+  addInstance(instance: Instance): void;
+
+  /** The injector shared by this scope tree, e.g. to subscribe to `onConstructed`. */
+  getInjector(): IInjector;
+}

package/lib/errors/ArgumentNotFoundError.ts

@@ -0,0 +1,13 @@
+import { ContainerError } from './ContainerError';
+
+/** Thrown by `findOrFail` when no runtime arg matches the predicate. Code `IOC_ARGUMENT_NOT_FOUND`. */
+export class ArgumentNotFoundError extends ContainerError {
+  name = 'ArgumentNotFoundError';
+  readonly code = 'IOC_ARGUMENT_NOT_FOUND';
+
+  constructor(message = 'Argument not found') {
+    super(message);
+
+    Object.setPrototypeOf(this, ArgumentNotFoundError.prototype);
+  }
+}

package/lib/errors/CannonSingletonApplyTwiceError.ts

@@ -0,0 +1,6 @@
+import { CannotApplySingletonTwiceError } from './CannotApplySingletonTwiceError';
+
+/** @deprecated Misspelled name kept for compatibility. Use {@link CannotApplySingletonTwiceError}. */
+export const CannonSingletonApplyTwiceError = CannotApplySingletonTwiceError;
+/** @deprecated Misspelled name kept for compatibility. Use {@link CannotApplySingletonTwiceError}. */
+export type CannonSingletonApplyTwiceError = CannotApplySingletonTwiceError;

package/lib/errors/CannotApplySingletonTwiceError.ts

@@ -0,0 +1,22 @@
+import { ContainerError } from './ContainerError';
+
+/** Thrown when `singleton()` is applied twice to one provider. Code `IOC_SINGLETON_APPLIED_TWICE`. */
+export class CannotApplySingletonTwiceError extends ContainerError {
+  name = 'CannotApplySingletonTwiceError';
+  readonly code = 'IOC_SINGLETON_APPLIED_TWICE';
+
+  constructor(message?: string) {
+    super(message);
+
+    Object.setPrototypeOf(this, CannotApplySingletonTwiceError.prototype);
+  }
+
+  /**
+   * @throws {CannotApplySingletonTwiceError} when `isTrue` is falsy.
+   */
+  static assert(isTrue: boolean, failMessage: string) {
+    if (!isTrue) {
+      throw new CannotApplySingletonTwiceError(failMessage);
+    }
+  }
+}

package/lib/errors/ContainerDisposedError.ts

@@ -0,0 +1,13 @@
+import { ContainerError } from './ContainerError';
+
+/** Thrown when a disposed scope is used. Code `IOC_CONTAINER_DISPOSED`. */
+export class ContainerDisposedError extends ContainerError {
+  name = 'ContainerDisposedError';
+  readonly code = 'IOC_CONTAINER_DISPOSED';
+
+  constructor(message: string) {
+    super(message);
+
+    Object.setPrototypeOf(this, ContainerDisposedError.prototype);
+  }
+}

package/lib/errors/ContainerError.ts

@@ -0,0 +1,15 @@
+/**
+ * Base class of every error the container throws. `code` is stable across
+ * versions (unlike `message`), so match on it — or on the subclass — rather
+ * than on the text. The codes are listed in the package's AGENTS.md.
+ */
+export abstract class ContainerError extends Error {
+  name = 'ContainerError';
+  readonly code: string = 'IOC_CONTAINER_ERROR';
+
+  protected constructor(message?: string) {
+    super(message);
+
+    Object.setPrototypeOf(this, ContainerError.prototype);
+  }
+}

package/lib/errors/ContainerNotFoundError.ts

@@ -0,0 +1,13 @@
+import { ContainerError } from './ContainerError';
+
+/** Signals that no container is associated with a target. Code `IOC_CONTAINER_NOT_FOUND`. */
+export class ContainerNotFoundError extends ContainerError {
+  name = 'ContainerNotFoundError';
+  readonly code = 'IOC_CONTAINER_NOT_FOUND';
+
+  constructor(message: string) {
+    super(message);
+
+    Object.setPrototypeOf(this, ContainerNotFoundError.prototype);
+  }
+}

package/lib/errors/DependencyMissingKeyError.ts

@@ -0,0 +1,13 @@
+import { ContainerError } from './ContainerError';
+
+/** Thrown when a registration has no binding key. Code `IOC_DEPENDENCY_MISSING_KEY`. */
+export class DependencyMissingKeyError extends ContainerError {
+  name = 'DependencyMissingKeyError';
+  readonly code = 'IOC_DEPENDENCY_MISSING_KEY';
+
+  constructor(message: string) {
+    super(message);
+
+    Object.setPrototypeOf(this, DependencyMissingKeyError.prototype);
+  }
+}

package/lib/errors/DependencyNotFoundError.ts

@@ -0,0 +1,13 @@
+import { ContainerError } from './ContainerError';
+
+/** Thrown when a key or alias is not found in the scope or any parent. Code `IOC_DEPENDENCY_NOT_FOUND`. */
+export class DependencyNotFoundError extends ContainerError {
+  name = 'DependencyNotFoundError';
+  readonly code = 'IOC_DEPENDENCY_NOT_FOUND';
+
+  constructor(message: string) {
+    super(message);
+
+    Object.setPrototypeOf(this, DependencyNotFoundError.prototype);
+  }
+}

package/lib/errors/MethodNotImplementedError.ts

@@ -0,0 +1,13 @@
+import { ContainerError } from './ContainerError';
+
+/** Thrown by a method the object does not support; the message names the class and method. Code `IOC_METHOD_NOT_IMPLEMENTED`. */
+export class MethodNotImplementedError extends ContainerError {
+  name = 'MethodNotImplementedError';
+  readonly code = 'IOC_METHOD_NOT_IMPLEMENTED';
+
+  constructor(message?: string) {
+    super(message);
+
+    Object.setPrototypeOf(this, MethodNotImplementedError.prototype);
+  }
+}

package/lib/errors/ProviderDisposedError.ts

@@ -0,0 +1,22 @@
+import { ContainerError } from './ContainerError';
+
+/** Thrown when a provider of a disposed scope is used. Code `IOC_PROVIDER_DISPOSED`. */
+export class ProviderDisposedError extends ContainerError {
+  name = 'ProviderDisposedError';
+  readonly code = 'IOC_PROVIDER_DISPOSED';
+
+  /**
+   * @throws {ProviderDisposedError} when `isTrue` is falsy.
+   */
+  static assert(isTrue: boolean, failMessage: string) {
+    if (!isTrue) {
+      throw new ProviderDisposedError(failMessage);
+    }
+  }
+
+  constructor(message: string) {
+    super(message);
+
+    Object.setPrototypeOf(this, ProviderDisposedError.prototype);
+  }
+}

package/lib/errors/TypedEventDisposedError.ts

@@ -0,0 +1,22 @@
+import { ContainerError } from './ContainerError';
+
+/** Thrown when subscribing to an event of a disposed scope. Code `IOC_EVENT_DISPOSED`. */
+export class TypedEventDisposedError extends ContainerError {
+  name = 'TypedEventDisposedError';
+  readonly code = 'IOC_EVENT_DISPOSED';
+
+  /**
+   * @throws {TypedEventDisposedError} when `isTrue` is falsy.
+   */
+  static assert(isTrue: boolean, failMessage: string) {
+    if (!isTrue) {
+      throw new TypedEventDisposedError(failMessage);
+    }
+  }
+
+  constructor(message: string) {
+    super(message);
+
+    Object.setPrototypeOf(this, TypedEventDisposedError.prototype);
+  }
+}

package/lib/errors/UnsupportedTokenTypeError.ts

@@ -0,0 +1,13 @@
+import { ContainerError } from './ContainerError';
+
+/** Thrown by `toToken` for a value that is not a token, key, class or function. Code `IOC_UNSUPPORTED_TOKEN_TYPE`. */
+export class UnsupportedTokenTypeError extends ContainerError {
+  name = 'UnsupportedTokenTypeError';
+  readonly code = 'IOC_UNSUPPORTED_TOKEN_TYPE';
+
+  constructor(message: string) {
+    super(message);
+
+    Object.setPrototypeOf(this, UnsupportedTokenTypeError.prototype);
+  }
+}

package/lib/feature/IFeatureFlags.ts

@@ -0,0 +1,44 @@
+import { SingleToken } from '../token/SingleToken';
+
+/**
+ * What a flag is evaluated for - usually the current user. Shaped after the
+ * Unleash context, so an Unleash client accepts it as is.
+ */
+export type FeatureContext = {
+  userId?: string;
+  sessionId?: string;
+  remoteAddress?: string;
+  environment?: string;
+  properties?: Record<string, string | number | undefined>;
+  [key: string]: unknown;
+};
+
+/** A variant served for a flag. Unleash reports `{ name: 'disabled', enabled: false }` for a flag that is off. */
+export type FeatureVariant = { name: string; enabled: boolean };
+
+/**
+ * The flag client feature tokens ask: `getVariant` for a
+ * `MultiVariantFeatureToken`, `isEnabled` for a `ToggleFeatureToken`.
+ * Synchronous, because resolution is. An Unleash client satisfies it
+ * structurally - register the instance itself; an asynchronous client
+ * (OpenFeature server SDK) needs an adapter which evaluates ahead of time and
+ * answers from that snapshot.
+ *
+ * @example
+ * container.addRegistration(Registration.fromValue(unleash).bindTo(IFeatureFlagsToken));
+ */
+export interface IFeatureFlags {
+  isEnabled(name: string, context?: FeatureContext): boolean;
+
+  getVariant(name: string, context?: FeatureContext): FeatureVariant;
+}
+
+/** Where feature tokens find the flag client. */
+export const IFeatureFlagsToken = new SingleToken<IFeatureFlags>('IFeatureFlags');
+
+/**
+ * Where feature tokens find the context to evaluate a flag for. Register it
+ * in the scope that knows the user (e.g. `request`); register `{}` for flags
+ * that do not depend on one.
+ */
+export const IFeatureContextToken = new SingleToken<FeatureContext>('IFeatureContext');

package/lib/hooks/HookCollector.ts

@@ -0,0 +1,109 @@
+import type { ExecutionContext } from '../ExecutionContext';
+import { resolveConstructor } from '../metadata/target';
+import { type Task } from '../utils/task';
+import { type Instance } from '../utils/basic';
+import { memoize } from '../utils/memoize';
+import { getHooks, hasHooks, type HookFn, toHookFn } from './hook';
+import { createHookExecutionContext, type CreateHookExecutionContext, type IHookContext } from './HookContext';
+
+/** Transforms each hook context before it is handed to its hook. */
+export type MapHookExecutionContext = (context: IHookContext) => IHookContext;
+
+/**
+ * One decorated member's hook, resolved to a function and bound to the context
+ * it runs against — the model the library hands back, and the whole of what it
+ * says about a hook. The member it came from is `context.methodName`.
+ * Performing it is the caller's business (ADR 0016).
+ */
+export type HookAction = {
+  hook: HookFn;
+  context: IHookContext;
+};
+
+/**
+ * Shapes what is collected: how each action's hook context is built, and which
+ * members take part. A collector carries defaults for all three, so a call
+ * names only what it overrides.
+ */
+export type HookCollectorOptions = {
+  createExecutionContext?: CreateHookExecutionContext;
+  mapExecutionContext?: MapHookExecutionContext;
+  predicate?: (methodName: string) => boolean;
+};
+
+/** What one collection runs in: the scope, plus any per-call overrides of the collector's options. */
+export type HookCollectionContext = ExecutionContext & HookCollectorOptions;
+
+/** Options of `new HookCollector(...)`. */
+export type HookCollectorProps = HookCollectorOptions & {
+  /** The hook key this collector reads: `onConstruct`, `onScopeDisposed`, `onResolved`, or a custom one. */
+  key: string | symbol;
+};
+
+/**
+ * Reads the hooks declared under one key off a target and hands them back as
+ * {@link HookAction}s, in declaration order. It runs nothing: what order the
+ * actions are performed in, what is awaited and where a failure goes are
+ * answered by the caller (ADR 0016).
+ *
+ * Wire it to whichever event should collect — the injector's `onConstructed`,
+ * the scope's `scopeDisposed`, a provider's `onResolved` — the library ships no
+ * module which does that for you (ADR 0018).
+ *
+ * ```typescript
+ * const collector = new HookCollector({ key: 'onStart' });
+ *
+ * container.getInjector().onConstructed((instance, scope) => {
+ *   runInOrder(collector.getActions(instance, { scope }).map(toTask))?.catch(report);
+ * });
+ * ```
+ */
+export class HookCollector {
+  private readonly key: string | symbol;
+  private readonly options: Required<HookCollectorOptions>;
+  // Hook metadata is fixed once a class is defined - decorators have all run by the time
+  // there is an instance to read them off - so the merge runs once per class and key.
+  private readonly hooksOf = memoize(getHooks);
+
+  constructor({
+    key,
+    createExecutionContext = createHookExecutionContext,
+    mapExecutionContext = (context) => context,
+    predicate = () => true,
+  }: HookCollectorProps) {
+    this.key = key;
+    this.options = { createExecutionContext, mapExecutionContext, predicate };
+  }
+
+  hasHooks(target: Instance): boolean {
+    return hasHooks(target, this.key);
+  }
+
+  /** The actions `target` declares under this collector's key — empty when it declares none. */
+  getActions(
+    target: Instance,
+    {
+      scope,
+      createExecutionContext = this.options.createExecutionContext,
+      mapExecutionContext = this.options.mapExecutionContext,
+      predicate = this.options.predicate,
+    }: HookCollectionContext,
+  ): HookAction[] {
+    const actions: HookAction[] = [];
+    for (const [methodName, fn] of this.hooksOf(resolveConstructor(target), this.key)) {
+      if (predicate(methodName)) {
+        actions.push({
+          hook: toHookFn(fn),
+          context: mapExecutionContext(createExecutionContext(target, scope, methodName)),
+        });
+      }
+    }
+    return actions;
+  }
+}
+
+/** The {@link Task} an action runs as: `runInOrder(actions.map(toTask))`, `runAtOnce(actions.map(toTask))`. */
+export const toTask =
+  ({ hook, context }: HookAction): Task =>
+  () =>
+    hook(context);

package/lib/hooks/HookContext.ts

@@ -0,0 +1,85 @@
+import type { IContainer } from '../container/IContainer';
+
+import { type Instance } from '../utils/basic';
+import { resolveArgs } from '../injector/MetadataInjector';
+import { type InjectFn } from './hook';
+
+/**
+ * What a hook receives: the `instance`, the `scope` and the decorated member's
+ * name. `invokeMethod({ args: resolveArgs() })` calls the member with its
+ * `@inject` parameters; `setProperty(fn)` assigns it (see `injectProp`).
+ */
+export interface IHookContext {
+  instance: Instance;
+  scope: IContainer;
+  methodName?: string;
+
+  resolveArgs(...args: unknown[]): unknown[];
+
+  invokeMethod(options?: { args?: unknown[] }): unknown;
+
+  setProperty(fn: InjectFn): void;
+
+  getProperty(): unknown;
+
+  setInitialArgs(...args: unknown[]): this;
+
+  getInitialArgs(): unknown[];
+}
+
+/** The default {@link IHookContext}. */
+export class HookContext implements IHookContext {
+  private initialArgs: unknown[] = [];
+
+  constructor(
+    readonly instance: Instance,
+    readonly scope: IContainer,
+    readonly methodName?: string,
+  ) {}
+
+  resolveArgs(...args: unknown[]): unknown[] {
+    return resolveArgs(
+      this.instance,
+      this.methodName,
+    )({
+      scope: this.scope,
+      args: [...this.initialArgs, ...args],
+    });
+  }
+
+  invokeMethod({ args = this.resolveArgs() }: { args?: unknown[] } = {}): unknown {
+    // @ts-ignore
+    return this.instance[this.methodName](...args);
+  }
+
+  setProperty(fn: InjectFn): void {
+    // @ts-ignore
+    this.instance[this.methodName] = fn({ scope: this.scope });
+  }
+
+  getProperty(): unknown {
+    // @ts-ignore
+    return this.instance[this.methodName];
+  }
+
+  setInitialArgs(...args: unknown[]): this {
+    this.initialArgs = args;
+    return this;
+  }
+
+  getInitialArgs(): unknown[] {
+    return this.initialArgs;
+  }
+}
+
+/** Builds the context a hook receives. */
+export type CreateHookExecutionContext = (Target: Instance, scope: IContainer, methodName?: string) => IHookContext;
+/** The default {@link CreateHookExecutionContext}: a {@link HookContext}. */
+export const createHookExecutionContext: CreateHookExecutionContext = (Target, scope, methodName = 'constructor') =>
+  new HookContext(Target, scope, methodName);
+
+/** A {@link CreateHookExecutionContext} whose contexts start with `args` as initial args. */
+export const createHookContextFactory =
+  ({ args = [] }: { args?: unknown[] } = {}): CreateHookExecutionContext =>
+  (Target, scope, methodName) =>
+    createHookExecutionContext(Target, scope, methodName).setInitialArgs(...args);

package/lib/hooks/combinators.ts

@@ -0,0 +1,51 @@
+import type { IContainer } from '../container/IContainer';
+import { runAtOnce, runInOrder } from '../utils/task';
+import { type HookFn, type HookType, toHookFn } from './hook';
+
+/**
+ * A provider hook narrowed to the dependencies that can carry hook metadata.
+ */
+export type ResolvedObjectHook = (dependency: object, scope: IContainer) => void;
+
+/**
+ * Combines hooks into one which runs them in declaration order, staying
+ * synchronous until one returns a promise and awaiting the rest from that point.
+ *
+ * A member carries a single hook, so this is how several are declared together:
+ * `@hook('onConstruct', sequential(validate, persist))`.
+ */
+export const sequential = (...hooks: HookType[]): HookFn => {
+  const fns = hooks.map(toHookFn);
+  return (context) => runInOrder(fns.map((fn) => () => fn(context)));
+};
+
+/**
+ * Combines hooks into one which starts them all at once. Settles when every
+ * hook has; a fully synchronous run returns nothing, like {@link sequential}.
+ *
+ * Use it for hooks of one member which do not depend on each other:
+ * `@hook('onScopeDisposed', parallel(flush, closeSocket))`.
+ */
+export const parallel = (...hooks: HookType[]): HookFn => {
+  const fns = hooks.map(toHookFn);
+  return (context) => runAtOnce(fns.map((fn) => () => fn(context)));
+};
+
+/**
+ * Wraps a hook so it runs a single time per instance, however often the event
+ * it is declared under fires. Composes with the combinators above —
+ * `oncePerInstance(sequential(connect, warmUp))` runs the whole sequence once.
+ */
+export const oncePerInstance = (execute: HookType): HookFn => {
+  const invokedInstances = new WeakSet<object>();
+  const fn = toHookFn(execute);
+
+  return (context) => {
+    if (invokedInstances.has(context.instance)) {
+      return;
+    }
+
+    invokedInstances.add(context.instance);
+    return fn(context);
+  };
+};