@codefast/di 0.8.0 → 0.8.1

package/src/injection/descriptor.ts

@@ -1,218 +0,0 @@
-/** The one shape every declared dependency is normalised to, whatever channel declared it. */
-import type { Token } from "#/core/token";
-import type { BindingTag, Constructor, TokenValue } from "#/core/types";
-import type { DependencySlot } from "#/injection/resolve-options";
-
-/**
- * Slot-selection options — a name and tags — a declared dependency narrows its binding with.
- *
- * @since 0.3.16-canary.0
- */
-export interface InjectOptions {
-  name?: string | undefined;
-  /**
-   * Single-tag shorthand, equivalent to listing the one pair in `tags`.
-   *
-   * @remarks Folded into `tags` when the descriptor is built, so nothing downstream sees two
-   * spellings of one request. Giving both is a request for every pair across the two.
-   */
-  tag?: BindingTag | undefined;
-  tags?: ReadonlyArray<BindingTag> | undefined;
-}
-
-/**
- * One dependency a `toResolved` factory or an `@inject` accessor declares.
- *
- * @remarks Extends {@link DependencySlot} so the two dependency sources stay literally one shape,
- * narrowing only `token` to carry the value type a factory's parameter is checked against.
- *
- * @since 0.3.16-canary.0
- */
-export interface InjectionDescriptor<out Value = unknown> extends DependencySlot {
-  readonly token: Token<Value> | Constructor<Value>;
-}
-
-/**
- * A dependency as declared: a bare token, a class, or a full injection descriptor.
- *
- * @since 0.3.16-canary.0
- */
-export type InjectableDependency<Value = unknown> = Token<Value> | Constructor<Value> | InjectionDescriptor<Value>;
-
-/**
- * The value a factory receives for one declared dependency.
- *
- * @remarks `optional()` and `injectAll()` fold their effect into the descriptor's own type
- * parameter, so reading it back is enough; bare tokens fall through to {@link TokenValue}.
- *
- * @since 0.5.0-canary.7
- */
-export type ResolvedDependencyValue<Dependency> = Dependency extends { readonly multi: true }
-  ? Array<DescribedValue<Dependency>>
-  : Dependency extends { readonly optional: true }
-    ? DescribedValue<Dependency> | undefined
-    : DescribedValue<Dependency>;
-
-/**
- * The value a dependency's own type parameter carries, before its flags are read.
- *
- * @remarks Split out because a hand-written descriptor states its flags and its value type
- * separately, and only the flags are load-bearing: `{ token: Plugin, multi: true }` says `Plugin`
- * and delivers `Array<Plugin>`. `injectAll()` and `optional()` already fold their effect in, so the
- * flags find an array or an optional there and leave it alone.
- */
-type DescribedValue<Dependency> = Dependency extends InjectionDescriptor<infer Value> ? Value : TokenValue<Dependency>;
-
-/**
- * Returns whether the value is an `InjectionDescriptor`, dual-role `inject()` functions included.
- *
- * @since 0.3.16-canary.0
- */
-export function isInjectionDescriptor(value: unknown): value is InjectionDescriptor {
-  if (value === null || value === undefined) {
-    return false;
-  }
-  const type = typeof value;
-  // inject() returns a function (dual-role), so must check both object and function
-  if (type !== "object" && type !== "function") {
-    return false;
-  }
-  return (
-    "token" in (value as object) &&
-    "optional" in (value as object) &&
-    "multi" in (value as object) &&
-    typeof (value as InjectionDescriptor).optional === "boolean" &&
-    typeof (value as InjectionDescriptor).multi === "boolean"
-  );
-}
-
-/**
- * Normalises a declared dependency to a plain `InjectionDescriptor`.
- *
- * @since 0.3.16-canary.0
- */
-export function normalizeToDescriptor(dependency: InjectableDependency): InjectionDescriptor {
-  if (isInjectionDescriptor(dependency)) {
-    return materializeInjectionDescriptor(dependency);
-  }
-  return { token: dependency, optional: false, multi: false };
-}
-
-/**
- * Dual-role `inject()` values are functions: [[Function]].name must not be treated as a DI slot name.
- * Only enumerable own `name` / `tags` from `Object.defineProperties` are real injection options.
- */
-function materializeInjectionDescriptor(dependency: InjectionDescriptor): InjectionDescriptor {
-  if (typeof dependency !== "function") {
-    return dependency;
-  }
-  const dualRole = dependency as InjectionDescriptor & ((...args: Array<unknown>) => unknown);
-  const base: Pick<InjectionDescriptor, "token" | "optional" | "multi"> = {
-    token: dualRole.token,
-    optional: dualRole.optional,
-    multi: dualRole.multi,
-  };
-  const nameDesc = Object.getOwnPropertyDescriptor(dualRole, "name");
-  const tagsDesc = Object.getOwnPropertyDescriptor(dualRole, "tags");
-  const explicitName = nameDesc?.enumerable === true && typeof nameDesc.value === "string" ? nameDesc.value : undefined;
-  // Annotated because `PropertyDescriptor.value` is `any`, and an `any` reaching the cast below
-  // would make it look checked when nothing checked it.
-  const explicitTags: unknown = tagsDesc?.enumerable === true ? tagsDesc.value : undefined;
-
-  if (explicitName !== undefined && explicitTags !== undefined) {
-    return {
-      ...base,
-      name: explicitName,
-      tags: explicitTags as NonNullable<InjectionDescriptor["tags"]>,
-    };
-  }
-  if (explicitName !== undefined) {
-    return { ...base, name: explicitName };
-  }
-  if (explicitTags !== undefined) {
-    return { ...base, tags: explicitTags as NonNullable<InjectionDescriptor["tags"]> };
-  }
-  return base;
-}
-
-/**
- * The one tag list a request carries, with the single-tag shorthand folded in.
- *
- * @remarks Folding here is what keeps `tag` from reaching `InjectionDescriptor` and everything
- * derived from it, so one request never has two spellings past this point.
- */
-function requestedTagsOf(options: InjectOptions | undefined): ReadonlyArray<BindingTag> | undefined {
-  const shorthand = options?.tag;
-  const listed = options?.tags;
-  if (shorthand === undefined) {
-    return listed;
-  }
-  return listed === undefined || listed.length === 0 ? [shorthand] : [shorthand, ...listed];
-}
-
-function withOptions<DescValue>(
-  base: Pick<InjectionDescriptor<DescValue>, "token" | "optional" | "multi">,
-  options: InjectOptions | undefined,
-): InjectionDescriptor<DescValue> {
-  const tags = requestedTagsOf(options);
-  if (options?.name !== undefined && tags !== undefined) {
-    return { ...base, name: options.name, tags };
-  }
-  if (options?.name !== undefined) {
-    return { ...base, name: options.name };
-  }
-  if (tags !== undefined) {
-    return { ...base, tags };
-  }
-  return base;
-}
-
-/**
- * The descriptor half of `inject()`, shared with the accessor decorator that wraps it.
- *
- * @since 0.6.0
- */
-export function buildInjectionDescriptor<Value>(
-  token: Token<Value> | Constructor<Value>,
-  options?: InjectOptions,
-): InjectionDescriptor<Value> {
-  return withOptions({ token, optional: false, multi: false }, options);
-}
-
-/**
- * Creates a descriptor that resolves to `undefined` instead of throwing when no binding matches.
- *
- * @since 0.3.16-canary.0
- */
-export function optional<Value>(
-  token: Token<Value> | Constructor<Value>,
-  options?: InjectOptions,
-): InjectionDescriptor<Value | undefined> {
-  return withOptions(
-    {
-      token: token as Token<Value | undefined> | Constructor<Value | undefined>,
-      optional: true,
-      multi: false,
-    },
-    options,
-  );
-}
-
-/**
- * Creates a descriptor that resolves every matching binding for the token into an array.
- *
- * @since 0.3.16-canary.0
- */
-export function injectAll<Value>(
-  token: Token<Value> | Constructor<Value>,
-  options?: InjectOptions,
-): InjectionDescriptor<Array<Value>> {
-  return withOptions(
-    {
-      token: token as Token<Array<Value>> | Constructor<Array<Value>>,
-      optional: false,
-      multi: true,
-    },
-    options,
-  );
-}

package/src/injection/resolve-options.ts

@@ -1,201 +0,0 @@
-import type { BindingTag } from "#/core/tag";
-import { slotName, slotNameCriterionOf } from "#/core/tag";
-import type { Token } from "#/core/token";
-import type { Constructor, ResolveOptions } from "#/core/types";
-
-/**
- * What one resolvable dependency declares.
- *
- * @remarks Both dependency sources — a constructor's `ParamMetadata` and a `toResolved`
- * `InjectionDescriptor` — are this shape, which is why one resolve routine serves both.
- *
- * @since 0.5.0-canary.9
- */
-export interface DependencySlot {
-  readonly token: Token<unknown> | Constructor;
-  readonly optional: boolean;
-  readonly multi: boolean;
-  readonly name?: string | undefined;
-  readonly tags?: ReadonlyArray<BindingTag> | undefined;
-}
-
-/**
- * The lone criterion of a request that carries exactly one, whatever its spelling — the shape the
- * registry has a direct index for.
- *
- * @remarks Every spelling answers here, so the index is not something one of them silently misses;
- * a name folds to the reserved `slotName` criterion, making the name lane the tag lane.
- *
- * @since 0.5.0-canary.9
- */
-export function singleCriterionOnlyOf(options: ResolveOptions | undefined): BindingTag | undefined {
-  if (options === undefined) {
-    return undefined;
-  }
-  if (options.name !== undefined) {
-    return loneNameCriterionOf(options);
-  }
-  const listed = options.tags;
-  const shorthand = options.tag;
-  if (shorthand !== undefined) {
-    return listed === undefined || listed.length === 0 ? shorthand : undefined;
-  }
-  return listed !== undefined && listed.length === 1 ? listed[0] : undefined;
-}
-
-/** The name spelling's half of the fold, kept apart so the common body stays small enough to inline. */
-function loneNameCriterionOf(options: ResolveOptions): BindingTag | undefined {
-  // A name next to any tag means the request carries two criteria, which no single index answers.
-  if (options.tag !== undefined || (options.tags !== undefined && options.tags.length > 0)) {
-    return undefined;
-  }
-  // Read, not minted: a request must not retain a name no binding ever declared.
-  return slotNameCriterionOf(options.name as string);
-}
-
-/** Shared core: build a ResolveOptions from already-normalised name + tags. */
-function buildOptions(
-  name: string | undefined,
-  tags: ReadonlyArray<BindingTag> | undefined,
-): ResolveOptions | undefined {
-  if (name === undefined && tags === undefined) {
-    return undefined;
-  }
-  const options: ResolveOptions = {};
-  if (name !== undefined) {
-    options.name = name;
-  }
-  if (tags !== undefined) {
-    options.tags = tags;
-  }
-  return options;
-}
-
-/**
- * Builds a {@link ResolveOptions} safe for `exactOptionalPropertyTypes`:
- * omits keys instead of assigning `undefined`.
- *
- * @since 0.3.16-canary.0
- */
-export function injectionSlotToResolveOptions(
-  injectionSlot: Pick<DependencySlot, "name" | "tags">,
-): ResolveOptions | undefined {
-  return buildOptions(injectionSlot.name, injectionSlot.tags);
-}
-
-/** Where a slot's derived options are memoized, so the same object is handed out every resolve. */
-const MEMOIZED_RESOLVE_OPTIONS: unique symbol = Symbol("di:resolve-options");
-
-/** Where a slot's folded lone criterion is memoized — `null` records "computed: none". */
-const MEMOIZED_SINGLE_CRITERION: unique symbol = Symbol("di:single-criterion");
-
-interface SlotWithMemoizedOptions {
-  [MEMOIZED_RESOLVE_OPTIONS]?: ResolveOptions;
-  [MEMOIZED_SINGLE_CRITERION]?: BindingTag | null;
-}
-
-/**
- * The options a dependency resolves with — one object per slot, since a slot's criteria are fixed
- * when it is declared.
- *
- * @remarks A slot carrying no criterion answers from its two fields, so the common shape never
- * reaches the memo.
- *
- * @since 0.6.0
- */
-export function resolveOptionsForSlot(injectionSlot: DependencySlot): ResolveOptions | undefined {
-  const { name, tags } = injectionSlot;
-  if (name === undefined && tags === undefined) {
-    return undefined;
-  }
-  const slot = injectionSlot as SlotWithMemoizedOptions;
-  const memoized = slot[MEMOIZED_RESOLVE_OPTIONS];
-  return memoized ?? memoizeResolveOptions(slot, name, tags);
-}
-
-/**
- * Builds, freezes and stores a slot's options on first use.
- *
- * @remarks Frozen because one object answers every resolve of the slot and a constraint predicate is
- * handed it. Split out for the `try`: in the caller it would cost the early return its inlining.
- */
-function memoizeResolveOptions(
-  slot: SlotWithMemoizedOptions,
-  name: string | undefined,
-  tags: ReadonlyArray<BindingTag> | undefined,
-): ResolveOptions {
-  const built = Object.freeze(buildOptions(name, tags) as ResolveOptions);
-  try {
-    slot[MEMOIZED_RESOLVE_OPTIONS] = built;
-  } catch {
-    // A frozen slot rebuilds on every hop rather than throwing.
-  }
-  return built;
-}
-
-/**
- * The lone criterion a dependency's fixed criteria fold to, memoized on the slot like its options —
- * `null` means the fold answered "none".
- *
- * @remarks A slot's criteria never change after declaration, so the fold happens once per slot
- * rather than per hop — which is what keeps a named dependency's resolve off the intern map. A
- * lone name whose criterion is not interned yet is left unmemoized: a later `whenNamed` binding
- * mints it, and the next fold must see that.
- *
- * @since 0.8.0
- */
-export function singleCriterionForSlot(injectionSlot: DependencySlot): BindingTag | null {
-  const slot = injectionSlot as SlotWithMemoizedOptions;
-  const memoized = slot[MEMOIZED_SINGLE_CRITERION];
-  if (memoized !== undefined) {
-    return memoized;
-  }
-  const options = resolveOptionsForSlot(injectionSlot);
-  const criterion = singleCriterionOnlyOf(options);
-  const folded = criterion ?? null;
-  if (criterion !== undefined || !isLoneNameOptions(options)) {
-    try {
-      slot[MEMOIZED_SINGLE_CRITERION] = folded;
-    } catch {
-      // A frozen slot re-folds on every hop rather than throwing.
-    }
-  }
-  return folded;
-}
-
-/** A slot request whose only criterion is a name — the one shape whose fold can change after a bind. */
-function isLoneNameOptions(options: ResolveOptions | undefined): boolean {
-  // Slot-derived options never carry the `tag` shorthand — `buildOptions` folds it into `tags`.
-  return (
-    options !== undefined && options.name !== undefined && (options.tags === undefined || options.tags.length === 0)
-  );
-}
-
-/**
- * Resolve options derived from a binding slot (tags may be empty; omits when nothing to match).
- *
- * @remarks Takes the slot structurally rather than as `BindingSlot`, so the slot on a public
- * `BindingSnapshot` — where `name` is an optional property, not a required one holding `undefined` —
- * is accepted by the same call.
- *
- * @since 0.3.16-canary.0
- */
-export function bindingSlotToResolveOptions(bindingSlot: {
-  readonly name?: string | undefined;
-  readonly tags?: ReadonlyArray<BindingTag> | undefined;
-}): ResolveOptions | undefined {
-  const tags = bindingSlot.tags;
-  let name = bindingSlot.name;
-  let criteria: ReadonlyArray<BindingTag> | undefined = tags !== undefined && tags.length > 0 ? tags : undefined;
-  if (criteria !== undefined) {
-    // A reserved criterion folds into `name` — carried in `tags` it would be said twice or, on a
-    // descriptor that spells its name as a tag, not at all.
-    const reserved = criteria.find((criterion) => criterion.key === slotName);
-    if (reserved !== undefined) {
-      name ??= reserved.value as string;
-      const rest = criteria.filter((criterion) => criterion.key !== slotName);
-      criteria = rest.length > 0 ? rest : undefined;
-    }
-  }
-  return buildOptions(name, criteria);
-}