ts-ioc-container 72.0.0 → 72.2.0

package/lib/index.ts

@@ -0,0 +1,181 @@
+// 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 { SingleToken } from './token/SingleToken';
+export { FunctionToken } from './token/FunctionToken';
+export { ConstantToken } from './token/ConstantToken';
+export { type InstancePredicate, GroupInstanceToken } from './token/GroupInstanceToken';
+
+// 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);

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