ts-ioc-container 72.0.0 → 72.2.0

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/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);
+  };
+};

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