ts-ioc-container 72.0.0 → 72.2.0

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,235 @@
+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. A bare key or token
+ * is shorthand for `bindTo(...)`. Without a key the class name is used.
+ *
+ * @example
+ * @register(bindTo(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.
+ *
+ * @example
+ * @register(bindTo(ILoggerToken))
+ * class Logger {}
+ *
+ * @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;
+  }
+}

package/lib/select.ts

@@ -0,0 +1,33 @@
+import { type CreateScopeOptions } from './container/IContainer';
+import { toGroupAlias } from './token/GroupAliasToken';
+import { FunctionToken } from './token/FunctionToken';
+import { GroupInstanceToken, InstancePredicate } from './token/GroupInstanceToken';
+import { toToken } from './token/toToken';
+
+/**
+ * Shortcuts for common tokens.
+ *
+ * - `select.token(x)` - `toToken(x)`
+ * - `select.alias('Key')` - a {@link GroupAliasToken}
+ * - `select.instances(predicate)` - instances already created in the scope
+ * - `select.scope.current` - the resolving scope itself
+ * - `select.scope.create({ tags })` - a new child scope
+ *
+ * @example
+ * class Handler {
+ *   constructor(@inject(by(select.scope.current)) private scope: IContainer) {}
+ * }
+ */
+export const select = {
+  alias: toGroupAlias,
+
+  token: toToken,
+
+  instances: (predicate: InstancePredicate = () => true) => new GroupInstanceToken(predicate),
+
+  scope: {
+    current: new FunctionToken(({ scope }) => scope),
+
+    create: (options: CreateScopeOptions) => new FunctionToken(({ scope }) => scope.createScope(options)),
+  },
+};

package/lib/token/BindToken.ts

@@ -0,0 +1,13 @@
+import { IRegistration } from '../registration/IRegistration';
+
+import { Is } from '../utils/basic';
+
+/** A token that can bind a registration to itself (a key or an alias). */
+export interface BindToken<T = any> {
+  bindTo(r: IRegistration<T>): void;
+}
+
+/** Narrows `token` to a {@link BindToken}. */
+export function isBindToken(token: unknown): token is BindToken {
+  return !Is.nullish(token) && typeof token === 'object' && 'bindTo' in token;
+}

package/lib/token/ClassToken.ts

@@ -0,0 +1,72 @@
+import { IContainer } from '../container/IContainer';
+import { forwardArgs, InjectionToken } from './InjectionToken';
+import { type constructor, Serializable } from '../utils/basic';
+import { ArgsFn, ResolveOptions } from '../provider/IProvider';
+
+/** A token for a class: resolves it through the scope's injector. `toToken(Class)` creates one. */
+export class ClassToken<T = any> extends InjectionToken<T> implements Serializable {
+  private readonly _getArgsFn: ArgsFn;
+  private readonly _isLazy: boolean;
+
+  constructor(
+    private readonly target: constructor<T>,
+    {
+      getArgsFn = forwardArgs,
+      isLazy = false,
+      tags = [],
+    }: { getArgsFn?: ArgsFn; isLazy?: boolean; tags?: string[] } = {},
+  ) {
+    super(tags);
+    this._getArgsFn = getArgsFn;
+    this._isLazy = isLazy;
+  }
+
+  select<R>(fn: (target: T) => R) {
+    return (s: IContainer) => fn(this.resolve(s));
+  }
+
+  resolve(s: IContainer, { args = [], lazy }: ResolveOptions = {}): T {
+    return s.resolve(this.target, {
+      args: this._getArgsFn({ scope: s, args }),
+      lazy: this._isLazy || lazy,
+    });
+  }
+
+  args(...newArgs: unknown[]) {
+    const parentFn = this._getArgsFn;
+    return new ClassToken<T>(this.target, {
+      getArgsFn: (options) => [...parentFn(options), ...newArgs],
+      isLazy: this._isLazy,
+      tags: this.getTags(),
+    });
+  }
+
+  argsFn(fn: (s: IContainer) => unknown[]) {
+    const parentFn = this._getArgsFn;
+    return new ClassToken<T>(this.target, {
+      getArgsFn: (options) => [...parentFn(options), ...fn(options.scope)],
+      isLazy: this._isLazy,
+      tags: this.getTags(),
+    });
+  }
+
+  lazy() {
+    return new ClassToken<T>(this.target, {
+      getArgsFn: this._getArgsFn,
+      isLazy: true,
+      tags: this.getTags(),
+    });
+  }
+
+  addTags(...tags: string[]): ClassToken<T> {
+    return new ClassToken<T>(this.target, {
+      getArgsFn: this._getArgsFn,
+      isLazy: this._isLazy,
+      tags: [...this.getTags(), ...tags],
+    });
+  }
+
+  toString(): string {
+    return this.target.name;
+  }
+}

package/lib/token/ConstantToken.ts

@@ -0,0 +1,50 @@
+import type { IContainer } from '../container/IContainer';
+import { InjectionToken } from './InjectionToken';
+import { MethodNotImplementedError } from '../errors/MethodNotImplementedError';
+import { Serializable } from '../utils/basic';
+
+/** A token that always resolves to a fixed value. It takes no args and cannot be lazy. */
+export class ConstantToken<T = any> extends InjectionToken<T> implements Serializable {
+  constructor(
+    private readonly token: T,
+    { tags = [] }: { tags?: string[] } = {},
+  ) {
+    super(tags);
+  }
+
+  resolve(s: IContainer): T {
+    return this.token;
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — a constant token cannot receive static args.
+   */
+  args(...deps: unknown[]): InjectionToken<T> {
+    throw new MethodNotImplementedError('ConstantToken.args is not implemented');
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — a constant token cannot receive resolved args.
+   */
+  argsFn(getArgsFn: (s: IContainer) => unknown[]): InjectionToken<T> {
+    throw new MethodNotImplementedError('ConstantToken.argsFn is not implemented');
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — a constant token cannot be made lazy.
+   */
+  lazy(): InjectionToken<T> {
+    throw new MethodNotImplementedError('ConstantToken.lazy is not implemented');
+  }
+
+  addTags(...tags: string[]): ConstantToken<T> {
+    return new ConstantToken<T>(this.token, { tags: [...this.getTags(), ...tags] });
+  }
+
+  /**
+   * @throws {MethodNotImplementedError} always — a constant token has no underlying key.
+   */
+  toString(): string {
+    throw new MethodNotImplementedError('ConstantToken.toString is not implemented');
+  }
+}