ts-ioc-container 72.1.0 → 72.3.0

package/lib/metadata/parameter.ts

@@ -0,0 +1,60 @@
+import { resolveConstructor } from './target';
+
+/** Decorator that writes parameter metadata under `key`; `mapFn` receives the previous value. */
+export const addParamMeta =
+  (key: string | symbol, mapFn: (prev: unknown) => unknown): ParameterDecorator =>
+  (target, _, parameterIndex) => {
+    const metadata: unknown[] = Reflect.getOwnMetadata(key, target) ?? [];
+    metadata[parameterIndex] = mapFn(metadata[parameterIndex]);
+    Reflect.defineMetadata(key, metadata, target);
+  };
+/** Reads parameter metadata written by `addParamMeta`. */
+export const getParamMeta = (key: string | symbol, target: object): unknown[] => {
+  return (Reflect.getOwnMetadata(key, resolveConstructor(target)) as unknown[]) ?? [];
+};
+
+/** Decorator that attaches a `key` -> `label` pair to a parameter. */
+export const addParamLabel = (key: string, label: string) =>
+  addParamMeta('label', (prev: unknown) => {
+    const map = (prev as Map<string, string> | undefined) ?? new Map<string, string>();
+    return map.set(key, label);
+  });
+/** Reads the labels written by `addParamLabel`. */
+export const getParamLabels = (target: object, parameterIndex: number): Map<string, string> => {
+  const all = getParamMeta('label', target);
+  return (all[parameterIndex] as Map<string, string> | undefined) ?? new Map();
+};
+
+/** Decorator that attaches a tag to a parameter. */
+export const addParamTag = (tag: string) =>
+  addParamMeta('tag', (prev: unknown) => {
+    const set = (prev as Set<string> | undefined) ?? new Set<string>();
+    return set.add(tag);
+  });
+/** Reads the tags written by `addParamTag`. */
+export const getParamTags = (target: object, parameterIndex: number): Set<string> => {
+  const all = getParamMeta('tag', target);
+  return (all[parameterIndex] as Set<string> | undefined) ?? new Set();
+};
+
+/**
+ * Applies several parameter decorators as one, so a stack repeated on many
+ * parameters can be given a name:
+ *
+ * ```typescript
+ * const fromConfig = <T>(key: string, map: MapFn<IConfig, T>) =>
+ *   createComposeParameterDecorator(inject(pipe(by(ConfigToken), map)), addParamLabel('config', key));
+ * ```
+ *
+ * Decorators are applied bottom-up, exactly as stacking them would be, so
+ * `@createComposeParameterDecorator(a, b)` behaves like `@a @b`. A parameter
+ * decorator returns nothing, so there is nothing to thread - each one is called
+ * with the same target, property key and parameter index.
+ */
+export const createComposeParameterDecorator =
+  (...decorators: ParameterDecorator[]): ParameterDecorator =>
+  (target, propertyKey, parameterIndex) => {
+    for (let i = decorators.length - 1; i >= 0; i--) {
+      decorators[i](target, propertyKey, parameterIndex);
+    }
+  };

package/lib/metadata/target.ts

@@ -0,0 +1,25 @@
+import { type constructor, type Instance, Is } from '../utils/basic';
+import { unwrapProxy } from '../utils/ProxyRegistry';
+
+/**
+ * The class behind `target`: `target` itself when it is already a constructor,
+ * otherwise the constructor of the instance.
+ *
+ * `target` may be a proxy (a `lazy()` provider hands one out), and it is
+ * unwrapped before either branch, because metadata is defined on the real class
+ * and a proxy is never that class. A proxied class misses the lookup outright,
+ * standing in for the very object metadata is keyed by; a proxied instance would
+ * only answer `constructor` correctly if its handler forwards the read, which a
+ * custom one need not do.
+ *
+ * The branch tests for a constructor rather than for an instance: `Is.instance`
+ * asks for an *own* `constructor` property, which a prototype has and an
+ * instance does not - its own `constructor` lives one level up the chain.
+ *
+ * Every metadata read goes through here, so callers pass whatever they hold - a
+ * class, an instance, or a proxy of either - and never unwrap by hand.
+ */
+export function resolveConstructor(target: constructor<unknown> | Instance): constructor<unknown> {
+  const value = unwrapProxy(target);
+  return Is.constructor(value) ? value : (value.constructor as constructor<unknown>);
+}

package/lib/provider/IProvider.ts

@@ -0,0 +1,65 @@
+import { IContainer, Tagged } from '../container/IContainer';
+import { InjectOptions, WithScope } from '../injector/IInjector';
+import { Serializable } from '../utils/basic';
+
+export type WithLazy = { lazy: boolean };
+/**
+ * The resolution context a provider works in: the `scope` resolving, the runtime
+ * `args`, and whether the caller asked for a `lazy` instance. One object, so a
+ * function handed it destructures what it uses (`({ scope, args }) => ...`).
+ */
+export type ProviderOptions = InjectOptions & Partial<WithLazy>;
+/**
+ * `ProviderOptions` as a caller which addresses the scope directly passes them -
+ * `scope.resolve(key, options)`, `token.resolve(scope, options)` - so the scope is
+ * not repeated inside.
+ */
+export type ResolveOptions = Omit<ProviderOptions, keyof WithScope>;
+/** A factory: builds the dependency from the resolution context. What `Registration.fromFn` takes. */
+export type ResolveDependency<T = unknown> = (options: ProviderOptions) => T;
+/** What a {@link ScopeAccessRule} sees: the scope asking, the scope holding the provider, and the runtime args. */
+export type ScopeAccessOptions = { invocationScope: Tagged; providerScope: Tagged; args: unknown[] };
+/** Decides whether a provider may be resolved for an invocation; `prev` is the result of earlier rules. Set with `scopeAccess(...)`. */
+export type ScopeAccessRule = (options: ScopeAccessOptions, prev: boolean) => boolean;
+
+/** Computes args from the resolution context. */
+export type ArgsFn = (options: InjectOptions) => unknown[];
+
+/** Maps runtime args to a `singleton(...)` cache key: one instance per distinct key. */
+export type GetCacheKey = (args: unknown[]) => string | Serializable;
+/** Wraps or replaces a resolved dependency. Used by `decorate(...)`. */
+export type DecorateFn<Instance = any> = (dep: Instance, scope: IContainer) => Instance;
+
+/**
+ * Provider hooks - the provider's own domain: a dependency was resolved.
+ *
+ * Resolution is the provider's business, so the hook list belongs to the
+ * provider. A dependency is not necessarily a constructed instance - a provider
+ * can hand out a value the container never built - so the hook takes `unknown`.
+ */
+export type ProviderHook = (dependency: unknown, scope: IContainer) => void;
+
+/** The factory behind a registration. See {@link Provider}. */
+export interface IProvider<T = any> {
+  resolve(options: ProviderOptions): T;
+
+  hasAccess(options: ScopeAccessOptions): boolean;
+
+  map(...mappers: DecorateFn<T>[]): this;
+
+  addAccessRule(...rules: ScopeAccessRule[]): this;
+
+  addArgsFn(argsFn: ArgsFn): this;
+
+  lazy(): this;
+
+  autoResolve(): this;
+
+  isAutoResolvable(): boolean;
+
+  singleton(getCacheKey?: GetCacheKey): this;
+
+  dispose(): void;
+
+  onResolved(...hooks: ProviderHook[]): this;
+}

package/lib/provider/Provider.ts

@@ -0,0 +1,174 @@
+import {
+  type ArgsFn,
+  type DecorateFn,
+  type GetCacheKey,
+  type IProvider,
+  type ProviderOptions,
+  type ResolveDependency,
+  type ScopeAccessOptions,
+  type ScopeAccessRule,
+  type ProviderHook,
+} from './IProvider';
+import type { DependencyKey } from '../container/IContainer';
+import { type constructor, toString } from '../utils/basic';
+import { CannotApplySingletonTwiceError } from '../errors/CannotApplySingletonTwiceError';
+import { ProviderDisposedError } from '../errors/ProviderDisposedError';
+
+/**
+ * The factory behind a registration: creates or returns the dependency and
+ * applies the pipes (`singleton`, `lazy`, `decorate`, args and access rules).
+ * Usually created for you by {@link Registration}; use it directly only for
+ * low-level `container.register(key, provider)` calls.
+ */
+export class Provider<T = any> implements IProvider<T> {
+  static fromClass<T>(Target: constructor<T>): IProvider<T> {
+    return new Provider(({ scope, ...options }) => scope.resolve(Target, options));
+  }
+
+  static fromValue<T>(value: T): IProvider<T> {
+    return new Provider(() => value);
+  }
+
+  static fromKey<T>(key: DependencyKey) {
+    return new Provider<T>(({ scope }) => scope.resolve(key));
+  }
+
+  private readonly argsFnList: ArgsFn[] = [];
+  private readonly accessRules: ScopeAccessRule[] = [];
+  private readonly mappers: DecorateFn<T>[] = [];
+  private isLazy = false;
+  private isAutoResolve = false;
+  private cache = new Map<string, unknown>();
+  private getKey: GetCacheKey | undefined;
+  private isDisposed: boolean = false;
+  private readonly onResolvedHookList: ProviderHook[] = [];
+
+  constructor(private readonly resolveDependency: ResolveDependency<T>) {}
+
+  /**
+   * @throws {ProviderDisposedError} when the provider has already been disposed.
+   * @throws {unknown} rethrows whatever an `onResolved` hook threw.
+   */
+  resolve(options: ProviderOptions): T {
+    ProviderDisposedError.assert(
+      !this.isDisposed,
+      'Provider is already disposed: its scope was disposed. Resolve from a live scope.',
+    );
+
+    if (!this.getKey) {
+      return this.resolveDep(options);
+    }
+
+    const key = toString(this.getKey(options.args ?? []));
+
+    if (!this.cache.has(key)) {
+      this.cache.set(key, this.resolveDep(options));
+    }
+
+    return this.cache.get(key)! as T;
+  }
+
+  /**
+   * @throws {unknown} rethrows whatever an `onResolved` hook threw.
+   */
+  private resolveDep({ scope, args = [], lazy }: ProviderOptions): T {
+    let dependency = this.resolveDependency({
+      scope,
+      args: this.argsFnList.reduce((acc, current) => current({ scope, args: acc }), args),
+      lazy: lazy ?? this.isLazy,
+    });
+    dependency = this.mappers.reduce((acc, current) => current(acc, scope), dependency);
+    for (const onResolved of this.onResolvedHookList) {
+      onResolved(dependency, scope);
+    }
+    return dependency;
+  }
+
+  map(...mappers: DecorateFn<T>[]): this {
+    this.mappers.push(...mappers);
+    return this;
+  }
+
+  addAccessRule(...rules: ScopeAccessRule[]): this {
+    this.accessRules.push(...rules);
+    return this;
+  }
+
+  lazy(): this {
+    this.isLazy = true;
+    return this;
+  }
+
+  autoResolve(): this {
+    this.isAutoResolve = true;
+    return this;
+  }
+
+  /**
+   * @throws {ProviderDisposedError} when the provider has already been disposed.
+   */
+  isAutoResolvable(): boolean {
+    ProviderDisposedError.assert(
+      !this.isDisposed,
+      'Provider is already disposed: its scope was disposed. Resolve from a live scope.',
+    );
+
+    return this.isAutoResolve;
+  }
+
+  addArgsFn(...fns: ArgsFn[]): this {
+    this.argsFnList.push(...fns);
+    return this;
+  }
+
+  /**
+   * @throws {ProviderDisposedError} when the provider has already been disposed.
+   */
+  hasAccess(options: ScopeAccessOptions): boolean {
+    ProviderDisposedError.assert(
+      !this.isDisposed,
+      'Provider is already disposed: its scope was disposed. Resolve from a live scope.',
+    );
+
+    return this.accessRules.reduce((acc, rule) => rule(options, acc), true);
+  }
+
+  /**
+   * @throws {CannotApplySingletonTwiceError} when the provider is already configured as a singleton.
+   */
+  singleton(getCacheKey: GetCacheKey = () => '1'): this {
+    CannotApplySingletonTwiceError.assert(
+      !this.getKey,
+      'Provider is already singleton: singleton() was applied twice to the same provider. Remove the duplicate singleton().',
+    );
+    this.getKey = getCacheKey;
+    return this;
+  }
+
+  /**
+   * Hooks run after every mapper, on each resolved dependency. A singleton provider
+   * caches the dependency, so its hooks run once — on the resolve that filled the cache.
+   */
+  onResolved(...hooks: ProviderHook[]): this {
+    this.onResolvedHookList.push(...hooks);
+    return this;
+  }
+
+  /**
+   * @throws {ProviderDisposedError} when the provider has already been disposed.
+   */
+  dispose(): void {
+    ProviderDisposedError.assert(
+      !this.isDisposed,
+      'Provider is already disposed: its scope was disposed. Resolve from a live scope.',
+    );
+    this.isDisposed = true;
+    this.isAutoResolve = false;
+    this.getKey = undefined;
+    this.cache.clear();
+    this.accessRules.splice(0, this.accessRules.length);
+    this.mappers.splice(0, this.mappers.length);
+    this.argsFnList.splice(0, this.argsFnList.length);
+    this.onResolvedHookList.splice(0, this.onResolvedHookList.length);
+  }
+}

package/lib/registration/IRegistration.ts

@@ -0,0 +1,242 @@
+import { type DependencyKey, type IContainer, type IContainerModule, isDependencyKey } from '../container/IContainer';
+import type { ArgsFn, DecorateFn, GetCacheKey, IProvider, ProviderHook, ScopeAccessRule } from '../provider/IProvider';
+import { SingleToken } from '../token/SingleToken';
+import { BindToken } from '../token/BindToken';
+import { MapFn } from '../utils/fp';
+import { addClassMeta, getClassMeta } from '../metadata/class';
+import { type constructor } from '../utils/basic';
+
+/**
+ * Decides whether a registration is copied into a scope when that scope is
+ * created (or when the registration is added). `prev` is the result of the
+ * rules before it, so rules chain. Set with {@link scope} or `registration.when(...)`.
+ *
+ * @example
+ * const onlyRequest: ScopeMatchRule = (s) => s.hasTag('request');
+ */
+export type ScopeMatchRule = (s: IContainer, prev: boolean) => boolean;
+
+/**
+ * A provider transform usable in both places: `registration.pipe(...)` calls
+ * `mapProvider`, `@register(...)` calls `mapRegistration`. Build one with
+ * {@link registerPipe}; `singleton()`, `lazy()`, `scopeAccess()` etc. are all pipes.
+ */
+export interface ProviderPipe<T = unknown> {
+  mapProvider(p: IProvider<T>): IProvider<T>;
+
+  mapRegistration(r: IRegistration<T>): IRegistration<T>;
+}
+
+/** Narrows `obj` to a {@link ProviderPipe}. */
+export const isProviderPipe = <T>(obj: unknown): obj is ProviderPipe<T> =>
+  obj !== null && typeof obj === 'object' && 'mapProvider' in obj;
+
+/**
+ * Turns a provider transform into a {@link ProviderPipe}, so it works both in
+ * `@register(...)` and in `registration.pipe(...)`.
+ *
+ * @example
+ * const cached = <T>() => registerPipe<T>((p) => p.singleton());
+ *
+ * @register(bindTo('Cache'), cached())
+ * class Cache {}
+ */
+export const registerPipe = <T>(mapProvider: (p: IProvider<T>) => IProvider<T>): ProviderPipe<T> => ({
+  mapProvider,
+  mapRegistration: (r) => r.pipe(mapProvider),
+});
+
+/**
+ * Anything that can name a binding key: a raw key, or a token that knows how to bind itself.
+ */
+export type Bindable<T = any> = DependencyKey | BindToken<T>;
+
+/** Normalizes a {@link Bindable}: a raw key becomes a `SingleToken`, a token is returned as is. */
+export const toBindToken = <T>(target: Bindable<T>): BindToken<T> =>
+  isDependencyKey(target) ? new SingleToken<T>(target) : target;
+
+/**
+ * Everything accepted at provider level - by `IRegistration.pipe(...)`.
+ */
+export type ProviderMapper<T = any> = MapFn<IProvider<T>> | ProviderPipe<T>;
+
+/** Normalizes a {@link ProviderMapper} to a plain provider transform. */
+export const toProviderFn = <T>(mapper: ProviderMapper<T>): MapFn<IProvider<T>> =>
+  isProviderPipe<T>(mapper) ? mapper.mapProvider.bind(mapper) : mapper;
+
+/**
+ * Everything accepted at registration level - by `@register(...)`.
+ */
+export type RegistrationMapper<T = any> = MapFn<IRegistration<T>> | ProviderPipe<T> | Bindable<T>;
+
+/** Normalizes a {@link RegistrationMapper} to a plain registration transform (a `Bindable` becomes `bindTo(...)`). */
+export const toRegistrationFn = <T>(mapper: RegistrationMapper<T>): MapFn<IRegistration<T>> => {
+  if (typeof mapper === 'function') return mapper;
+  if (isProviderPipe<T>(mapper)) return (r) => mapper.mapRegistration(r);
+  return bindTo(mapper);
+};
+
+/**
+ * A recipe for putting one provider into matching scopes. Created with
+ * `Registration.fromClass` / `fromValue` / `fromFn` / `fromKey` and added with
+ * `container.addRegistration(...)`; `applyTo(scope)` registers the provider
+ * when the scope rules match.
+ */
+export interface IRegistration<T = any> extends IContainerModule {
+  getKeyOrFail(): DependencyKey;
+
+  when(...predicates: ScopeMatchRule[]): this;
+
+  bindToKey(key: DependencyKey): this;
+
+  bindTo(key: Bindable): this;
+
+  pipe(...mappers: ProviderMapper<T>[]): this;
+
+  bindToAlias(alias: DependencyKey): this;
+}
+
+/** The dependency type `T` of an `IRegistration<T>`. */
+export type ReturnTypeOfRegistration<T> = T extends IRegistration<infer R> ? R : never;
+
+const METADATA_KEY = 'registration';
+/** Reads the registration transforms written on a class by {@link register}. */
+export const getTransformers = (Target: constructor<unknown>) =>
+  getClassMeta<MapFn<IRegistration>[]>(Target, METADATA_KEY) ?? [];
+
+/**
+ * Class decorator that configures how `Registration.fromClass(Target)` registers
+ * the class: binding keys, scope rules and provider pipes. Without a key the
+ * class name is used.
+ *
+ * Pass a key or a token directly - `@register(ILoggerToken)`, `@register('ILogger')`.
+ * It is bound exactly as `bindTo(...)` would bind it, so wrapping it in
+ * `bindTo(...)` here is redundant; `bindTo` is for the fluent
+ * `Registration...` chain.
+ *
+ * @example
+ * @register(ILoggerToken, scope((s) => s.hasTag('application')), singleton())
+ * class Logger implements ILogger {}
+ *
+ * container.addRegistration(Registration.fromClass(Logger));
+ */
+export const register = (...mappers: RegistrationMapper[]) =>
+  addClassMeta(METADATA_KEY, (acc: MapFn<IRegistration>[] | undefined) => {
+    const result = mappers.map((m) => toRegistrationFn(m));
+    return acc ? [...result, ...acc] : result;
+  });
+
+/**
+ * Binds a registration to one or more keys or tokens. A `SingleToken` binds its
+ * key; an alias token (`toSingleAlias`, `toGroupAlias`) adds an alias.
+ *
+ * Inside `@register(...)` pass the token itself instead - `@register(ILoggerToken)`
+ * binds it the same way, so `@register(bindTo(ILoggerToken))` is redundant.
+ *
+ * @example
+ * Registration.fromClass(Logger).bindTo(ILoggerToken);
+ *
+ * @example
+ * Registration.fromValue(config).bindTo('Config');
+ */
+export const bindTo =
+  (...tokens: Bindable[]): MapFn<IRegistration> =>
+  (r) => {
+    for (const token of tokens) {
+      toBindToken(token).bindTo(r);
+    }
+    return r;
+  };
+
+/**
+ * Limits which scopes a registration is copied into. Without it, a registration
+ * lands in every scope, so a `singleton()` becomes one instance per scope.
+ *
+ * @example
+ * @register(bindTo('Repo'), scope((s) => s.hasTag('request')))
+ * class Repo {}
+ */
+export const scope =
+  (...rules: ScopeMatchRule[]): MapFn<IRegistration> =>
+  (r) =>
+    r.when(...rules);
+
+/**
+ * Appends fixed values after the runtime args handed to the provider.
+ *
+ * @example
+ * @register(bindTo('Client'), appendArgs('https://api.example.com'))
+ * class Client {
+ *   constructor(@inject(arg(0)) readonly baseUrl: string) {}
+ * }
+ */
+export const appendArgs = <T>(...extraArgs: unknown[]) =>
+  registerPipe<T>((p) => p.addArgsFn(({ args = [] }) => [...args, ...extraArgs]));
+
+/**
+ * Appends values computed at resolve time after the runtime args.
+ *
+ * @example
+ * @register(bindTo('Client'), appendArgsFn(({ scope }) => [scope.resolve('API_URL')]))
+ * class Client {}
+ */
+export const appendArgsFn = <T>(fn: ArgsFn) =>
+  registerPipe<T>((p) => p.addArgsFn((options) => [...(options.args ?? []), ...fn(options)]));
+
+/**
+ * Controls from which scopes the provider may be resolved (unlike {@link scope},
+ * which controls where it is registered). A denied lookup falls through to the parent.
+ *
+ * @example
+ * @register(bindTo('Admin'), scopeAccess(({ invocationScope }) => invocationScope.hasTag('admin')))
+ * class AdminService {}
+ */
+export const scopeAccess = <T>(rule: ScopeAccessRule) => registerPipe<T>((p) => p.addAccessRule(rule));
+
+/**
+ * Resolves the dependency as a proxy that constructs the real instance on first
+ * member access.
+ *
+ * @example
+ * @register(bindTo('Heavy'), lazy())
+ * class HeavyService {}
+ */
+export const lazy = <T>() => registerPipe<T>((p) => p.lazy());
+
+/**
+ * Marks the provider for eager resolution when the scope is set up; needs
+ * `container.useModule(new AutoResolveModule())`.
+ */
+export const autoResolve = <T>() => registerPipe<T>((p) => p.autoResolve());
+
+/**
+ * Wraps or replaces the resolved dependency. Order relative to `lazy()` decides
+ * whether the proxy or the real instance is decorated.
+ *
+ * @example
+ * @register(bindTo('Api'), decorate((api, scope) => new LoggingApi(api)))
+ * class Api {}
+ */
+export const decorate = (...fns: DecorateFn[]) => registerPipe((p) => p.map(...fns));
+
+/**
+ * Caches the dependency per provider, which means per scope the registration
+ * was copied into (combine with {@link scope}). `getCacheKey` receives the
+ * runtime args and caches one instance per distinct key.
+ *
+ * @example
+ * @register(bindTo('Db'), scope((s) => s.hasTag('application')), singleton())
+ * class Db {}
+ *
+ * @example
+ * // one instance per tenant id passed as the first runtime arg
+ * @register(bindTo('TenantDb'), singleton(([tenantId]) => String(tenantId)))
+ * class TenantDb {}
+ */
+export const singleton = <T = unknown>(getCacheKey?: GetCacheKey) => registerPipe<T>((p) => p.singleton(getCacheKey));
+
+/**
+ * Registration-level form of `IProvider.onResolved`: attaches provider hooks to
+ * the piped registration's provider.
+ */
+export const onResolve = <T = unknown>(...hooks: ProviderHook[]) => registerPipe<T>((p) => p.onResolved(...hooks));

package/lib/registration/Registration.ts

@@ -0,0 +1,122 @@
+import { DependencyKey, IContainer } from '../container/IContainer';
+import { Provider } from '../provider/Provider';
+import type { IProvider, ResolveDependency } from '../provider/IProvider';
+import { DependencyMissingKeyError } from '../errors/DependencyMissingKeyError';
+import {
+  type Bindable,
+  type IRegistration,
+  type ProviderMapper,
+  type ScopeMatchRule,
+  getTransformers,
+  toBindToken,
+  toProviderFn,
+} from './IRegistration';
+import { type MapFn, pipe } from '../utils/fp';
+import { type constructor, Is } from '../utils/basic';
+
+/**
+ * Builds registrations for `container.addRegistration(...)`. Usually imported as
+ * `Registration as R`.
+ *
+ * - `R.fromClass(Class)` - reads the class's `@register(...)` config; the key
+ *   defaults to the class name.
+ * - `R.fromValue(value).bindTo('Key')` - a constant.
+ * - `R.fromFn(({ scope, args }) => ...).bindTo('Key')` - a factory.
+ * - `R.fromKey('Other').bindTo('Key')` - an alias of another key.
+ *
+ * @example
+ * container
+ *   .addRegistration(R.fromClass(Logger))
+ *   .addRegistration(R.fromValue('https://api.example.com').bindTo('API_URL'))
+ *   .addRegistration(R.fromFn(({ scope }) => new Client(scope.resolve('API_URL'))).bindTo('Client'));
+ */
+export class Registration<T = any> implements IRegistration<T> {
+  static fromClass<T>(Target: constructor<T>, { name }: { name?: string } = {}) {
+    const transform = pipe(...getTransformers(Target));
+    return transform(new Registration(() => Provider.fromClass(Target), name ?? Target.name));
+  }
+
+  static fromValue<T>(value: T) {
+    if (Is.constructor(value)) {
+      const transform = pipe(...getTransformers(value as constructor<T>));
+      return transform(new Registration(() => Provider.fromValue(value), value.name));
+    }
+    return new Registration(() => Provider.fromValue(value));
+  }
+
+  static fromFn<T>(fn: ResolveDependency<T>) {
+    return new Registration(() => new Provider(fn));
+  }
+
+  static fromKey<T>(key: DependencyKey) {
+    return new Registration<T>(() => Provider.fromKey(key));
+  }
+
+  private mappers: MapFn<IProvider<T>>[] = [];
+  private aliases: Set<DependencyKey> = new Set();
+
+  constructor(
+    private createProvider: () => IProvider<T>,
+    public key?: DependencyKey,
+    private scopeRules: ScopeMatchRule[] = [],
+  ) {}
+
+  bindToKey(key: DependencyKey): this {
+    this.key = key;
+    return this;
+  }
+
+  bindToAlias(alias: DependencyKey): this {
+    this.aliases.add(alias);
+    return this;
+  }
+
+  pipe(...mappers: ProviderMapper<T>[]): this {
+    this.mappers.push(...mappers.map(toProviderFn));
+    return this;
+  }
+
+  when(...predicates: ScopeMatchRule[]): this {
+    this.scopeRules.push(...predicates);
+    return this;
+  }
+
+  bindTo(key: Bindable): this {
+    toBindToken(key).bindTo(this);
+    return this;
+  }
+
+  private matchScope(container: IContainer): boolean {
+    return this.scopeRules.reduce((prev, curr) => curr(container, prev), true);
+  }
+
+  /**
+   * @throws {DependencyMissingKeyError} when the registration matches the scope but has no binding key.
+   */
+  applyTo(container: IContainer): void {
+    if (!this.matchScope(container)) {
+      return;
+    }
+
+    if (!this.key) {
+      throw new DependencyMissingKeyError(
+        'No key provided for registration: bind it with @register(bindTo(...)) or .bindTo(...).',
+      );
+    }
+
+    const provider = this.mappers.reduce<IProvider<T>>((p, m) => m(p), this.createProvider());
+    container.register(this.key, provider, { aliases: [...this.aliases] });
+  }
+
+  /**
+   * @throws {DependencyMissingKeyError} when no binding key has been set for this registration.
+   */
+  getKeyOrFail(): DependencyKey {
+    if (!this.key) {
+      throw new DependencyMissingKeyError(
+        'No key provided for registration: bind it with @register(bindTo(...)) or .bindTo(...).',
+      );
+    }
+    return this.key;
+  }
+}