contexify/src/resolution/resolver.ts

A TypeScript library providing a powerful dependency injection container with context-based IoC capabilities, inspired by LoopBack's Context system.

import assert from 'assert';

import { DecoratorFactory } from 'metarize';

import { isBindingAddress } from '../binding/binding-filter.js';
import type { BindingAddress } from '../binding/binding-key.js';
import type { Context } from '../context/context.js';
import {
  describeInjectedArguments,
  describeInjectedProperties,
  type Injection,
} from '../inject/inject.js';
import createDebugger from '../utils/debug.js';
import {
  type BoundValue,
  type Constructor,
  type MapObject,
  resolveList,
  resolveMap,
  transformValueOrPromise,
  type ValueOrPromise,
} from '../utils/value-promise.js';

import {
  ResolutionError,
  type ResolutionOptions,
  ResolutionSession,
} from './resolution-session.js';

const debug = createDebugger('contexify:resolver');
const getTargetName = DecoratorFactory.getTargetName;

/**
 * Create an instance of a class which constructor has arguments
 * decorated with `@inject`.
 *
 * The function returns a class when all dependencies were
 * resolved synchronously, or a Promise otherwise.
 *
 * @param ctor - The class constructor to call.
 * @param ctx - The context containing values for `@inject` resolution
 * @param session - Optional session for binding and dependency resolution
 * @param nonInjectedArgs - Optional array of args for non-injected parameters
 */
export function instantiateClass<T extends object>(
  ctor: Constructor<T>,
  ctx: Context,
  session?: ResolutionSession,
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  nonInjectedArgs?: any[]
): ValueOrPromise<T> {
  /* istanbul ignore if */
  if (debug.enabled) {
    debug('Instantiating %s', getTargetName(ctor));
    if (nonInjectedArgs?.length) {
      debug('Non-injected arguments:', nonInjectedArgs);
    }
  }
  const argsOrPromise = resolveInjectedArguments(
    ctor,
    '',
    ctx,
    session,
    nonInjectedArgs
  );
  const propertiesOrPromise = resolveInjectedProperties(ctor, ctx, session);
  const inst: ValueOrPromise<T> = transformValueOrPromise(
    argsOrPromise,
    (args) => {
      /* istanbul ignore if */
      if (debug.enabled) {
        debug('Injected arguments for %s():', ctor.name, args);
      }
      return new ctor(...args);
    }
  );
  return transformValueOrPromise(propertiesOrPromise, (props) => {
    /* istanbul ignore if */
    if (debug.enabled) {
      debug('Injected properties for %s:', ctor.name, props);
    }
    return transformValueOrPromise<T, T>(inst, (obj) =>
      Object.assign(obj, props)
    );
  });
}

/**
 * If the scope of current binding is `SINGLETON`, reset the context
 * to be the one that owns the current binding to make sure a singleton
 * does not have dependencies injected from child contexts unless the
 * injection is for method (excluding constructor) parameters.
 */
function resolveContext(
  ctx: Context,
  injection: Readonly<Injection>,
  session?: ResolutionSession
) {
  const currentBinding = session?.currentBinding;
  if (currentBinding == null) {
    // No current binding
    return ctx;
  }

  const isConstructorOrPropertyInjection =
    // constructor injection
    !injection.member ||
    // property injection
    typeof injection.methodDescriptorOrParameterIndex !== 'number';

  if (isConstructorOrPropertyInjection) {
    // Set context to the resolution context of the current binding for
    // constructor or property injections against a singleton
    ctx = ctx.getResolutionContext(currentBinding)!;
  }
  return ctx;
}

/**
 * Resolve the value or promise for a given injection
 * @param ctx - Context
 * @param injection - Descriptor of the injection
 * @param session - Optional session for binding and dependency resolution
 */
function resolve<T>(
  ctx: Context,
  injection: Readonly<Injection>,
  session?: ResolutionSession
): ValueOrPromise<T> {
  /* istanbul ignore if */
  if (debug.enabled) {
    debug(
      'Resolving an injection:',
      ResolutionSession.describeInjection(injection)
    );
  }

  ctx = resolveContext(ctx, injection, session);
  const resolved = ResolutionSession.runWithInjection(
    (s) => {
      if (injection.resolve) {
        // A custom resolve function is provided
        return injection.resolve(ctx, injection, s);
      }
      // Default to resolve the value from the context by binding key
      assert(
        isBindingAddress(injection.bindingSelector),
        'The binding selector must be an address (string or BindingKey)'
      );
      const key = injection.bindingSelector as BindingAddress;
      const options: ResolutionOptions = {
        session: s,
        ...injection.metadata,
      };
      return ctx.getValueOrPromise(key, options);
    },
    injection,
    session
  );
  return resolved;
}

/**
 * Given a function with arguments decorated with `@inject`,
 * return the list of arguments resolved using the values
 * bound in `ctx`.

 * The function returns an argument array when all dependencies were
 * resolved synchronously, or a Promise otherwise.
 *
 * @param target - The class for constructor injection or prototype for method
 * injection
 * @param method - The method name. If set to '', the constructor will
 * be used.
 * @param ctx - The context containing values for `@inject` resolution
 * @param session - Optional session for binding and dependency resolution
 * @param nonInjectedArgs - Optional array of args for non-injected parameters
 */
export function resolveInjectedArguments(
  target: object,
  method: string,
  ctx: Context,
  session?: ResolutionSession,
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  nonInjectedArgs?: any[]
): ValueOrPromise<BoundValue[]> {
  /* istanbul ignore if */
  if (debug.enabled) {
    debug('Resolving injected arguments for %s', getTargetName(target, method));
  }
  const targetWithMethods = <
    { [method: string]: (...args: unknown[]) => unknown }
  >target;
  if (method) {
    assert(
      typeof targetWithMethods[method] === 'function',
      `Method ${method} not found`
    );
  }
  // NOTE: the array may be sparse, i.e.
  //   Object.keys(injectedArgs).length !== injectedArgs.length
  // Example value:
  //   [ , 'key1', , 'key2']
  const injectedArgs = describeInjectedArguments(target, method);
  const extraArgs = nonInjectedArgs ?? [];

  let argLength = DecoratorFactory.getNumberOfParameters(target, method);

  // Please note `injectedArgs` contains `undefined` for non-injected args
  const numberOfInjected = injectedArgs.filter((i) => i != null).length;
  if (argLength < numberOfInjected + extraArgs.length) {
    /**
     * `Function.prototype.length` excludes the rest parameter and only includes
     * parameters before the first one with a default value. For example,
     * `hello(@inject('name') name: string = 'John')` gives 0 for argLength
     */
    argLength = numberOfInjected + extraArgs.length;
  }

  let nonInjectedIndex = 0;
  return resolveList(new Array(argLength), (_val, ix) => {
    // The `val` argument is not used as the resolver only uses `injectedArgs`
    // and `extraArgs` to return the new value
    const injection = ix < injectedArgs.length ? injectedArgs[ix] : undefined;
    if (
      injection == null ||
      (!injection.bindingSelector && !injection.resolve)
    ) {
      if (nonInjectedIndex < extraArgs.length) {
        // Set the argument from the non-injected list
        return extraArgs[nonInjectedIndex++];
      }
      const name = getTargetName(target, method, ix);
      throw new ResolutionError(
        `The argument '${name}' is not decorated for dependency injection ` +
          'but no value was supplied by the caller. Did you forget to apply ' +
          '@inject() to the argument?',
        { context: ctx, options: { session } }
      );
    }

    return resolve(
      ctx,
      injection,
      // Clone the session so that multiple arguments can be resolved in parallel
      ResolutionSession.fork(session)
    );
  });
}

/**
 * Given a class with properties decorated with `@inject`,
 * return the map of properties resolved using the values
 * bound in `ctx`.

 * The function returns an argument array when all dependencies were
 * resolved synchronously, or a Promise otherwise.
 *
 * @param constructor - The class for which properties should be resolved.
 * @param ctx - The context containing values for `@inject` resolution
 * @param session - Optional session for binding and dependency resolution
 */
export function resolveInjectedProperties(
  constructor: Constructor<unknown>,
  ctx: Context,
  session?: ResolutionSession
): ValueOrPromise<MapObject<BoundValue>> {
  /* istanbul ignore if */
  if (debug.enabled) {
    debug('Resolving injected properties for %s', getTargetName(constructor));
  }
  const injectedProperties = describeInjectedProperties(constructor.prototype);

  return resolveMap(injectedProperties, (injection) =>
    resolve(
      ctx,
      injection,
      // Clone the session so that multiple properties can be resolved in parallel
      ResolutionSession.fork(session)
    )
  );
}