@codefast/di 0.7.1 → 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,144 +0,0 @@
-import type { BindingTag } 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;
-}
-
-/**
- * A request whose only criterion is a name — the shape the registry has a direct index for.
- *
- * @since 0.5.0-canary.9
- */
-export function isNameOnlyOptions(options: ResolveOptions): options is ResolveOptions & { name: string } {
-  return (
-    options.name !== undefined && options.tag === undefined && (options.tags === undefined || options.tags.length === 0)
-  );
-}
-
-/**
- * The lone tag of a request that asks for exactly one, written either way — the shape the registry
- * has a direct tag index for.
- *
- * @remarks Both spellings answer here, so the index is not something one of them silently misses.
- *
- * @since 0.5.0-canary.9
- */
-export function singleTagOnlyOf(options: ResolveOptions): BindingTag | undefined {
-  if (options.name !== undefined) {
-    return undefined;
-  }
-  const listed = options.tags;
-  const shorthand = options.tag;
-  if (shorthand !== undefined) {
-    // Both sources present means the request carries two tags, which no single-tag index can answer.
-    return listed === undefined || listed.length === 0 ? shorthand : undefined;
-  }
-  return listed !== undefined && listed.length === 1 ? listed[0] : undefined;
-}
-
-/** 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");
-
-interface SlotWithMemoizedOptions {
-  [MEMOIZED_RESOLVE_OPTIONS]?: ResolveOptions;
-}
-
-/**
- * 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;
-}
-
-/**
- * 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;
-  return buildOptions(bindingSlot.name, tags !== undefined && tags.length > 0 ? tags : undefined);
-}

package/src/introspection/dependency-graph.ts

@@ -1,282 +0,0 @@
-import type { Binding } from "#/core/binding";
-import { effectiveBindingScope } from "#/core/binding-scope";
-import type { BindingRegistry } from "#/core/registry";
-import type { Token } from "#/core/token";
-import { tokenName } from "#/core/token";
-import type { BindingKind, BindingScope, Constructor } from "#/core/types";
-import type { DependencySlot } from "#/injection/resolve-options";
-import { bindingSlotToResolveOptions } from "#/injection/resolve-options";
-import type { MetadataReader } from "#/metadata/metadata-types";
-import { matchesSlot } from "#/resolution/select/binding-select";
-
-// ── Types ────────────────────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * @remarks `kind`/`scope` are `"unbound"` for the placeholder node an optional, currently
- * unsatisfied dependency points at.
- *
- * @since 0.3.16-canary.0
- */
-export interface GraphNode {
-  readonly id: string;
-  readonly tokenName: string;
-  /** Identifies the token itself, so bindings that share a display name stay distinguishable. */
-  readonly tokenKey: string;
-  readonly kind: BindingKind | "unbound";
-  readonly scope: BindingScope | "unbound";
-  readonly fromParent: boolean;
-}
-
-/**
- * @remarks `label` is presentation, assembled for the adapters; read `optional` and `slotName`
- * rather than parsing it.
- *
- * @since 0.3.16-canary.0
- */
-export interface GraphEdge {
-  readonly from: string;
-  readonly to: string;
-  readonly label?: string;
-  readonly optional: boolean;
-  /** The named slot this edge resolves to, when the binding declares one. */
-  readonly slotName?: string;
-}
-
-/**
- * A container's dependency graph as plain JSON — nodes, edges, and whether the parent is included.
- *
- * @since 0.3.16-canary.0
- */
-export interface ContainerGraphJson {
-  readonly nodes: ReadonlyArray<GraphNode>;
-  readonly edges: ReadonlyArray<GraphEdge>;
-  readonly includesParent: boolean;
-}
-
-/**
- * Options controlling what a dependency graph includes.
- *
- * @since 0.3.16-canary.0
- */
-export interface GraphOptions {
-  readonly includeParent?: boolean | undefined;
-}
-
-// ── Builder ──────────────────────────────────────────────────────────────────────────────────────────────────────────
-
-// Tokens are compared by object identity, and a name is free to repeat, so the graph mints its
-// own per-process key. Weakly held: a discarded token takes its key with it.
-const tokenKeys = new WeakMap<object, string>();
-let tokenKeySequence = 0;
-
-function tokenKeyOf(dependency: Token<unknown> | Constructor): string {
-  const existing = tokenKeys.get(dependency);
-
-  if (existing !== undefined) {
-    return existing;
-  }
-
-  tokenKeySequence += 1;
-  const key = `${tokenName(dependency)}@${String(tokenKeySequence)}`;
-
-  tokenKeys.set(dependency, key);
-
-  return key;
-}
-
-// Mirrors filterBindings' slot semantics; predicates need a live resolution context, so the graph
-// keeps every predicate-carrying candidate.
-function matchingTargets(candidates: ReadonlyArray<Binding>, ref: DependencySlot): ReadonlyArray<Binding> {
-  const criterion = bindingSlotToResolveOptions(ref);
-
-  if (ref.multi && criterion === undefined) {
-    return candidates;
-  }
-
-  return candidates.filter((candidate) => matchesSlot(candidate.slot, criterion));
-}
-
-function edgeLabel(ref: DependencySlot, index: number): string {
-  const criterion =
-    ref.name !== undefined
-      ? `name:${ref.name}`
-      : ref.tags !== undefined && ref.tags.length > 0
-        ? `tag:${ref.tags[0]?.key.name}=${String(ref.tags[0]?.value)}`
-        : `[${index}]`;
-
-  return ref.optional ? `${criterion} optional` : criterion;
-}
-
-/** The collections a graph walk fills, so each step of the walk can be a function of its own. */
-interface GraphAccumulator {
-  readonly nodes: Array<GraphNode>;
-  readonly edges: Array<GraphEdge>;
-  // One placeholder node per optional-but-unbound token keeps the declared edge visible.
-  readonly unboundNodeIds: Map<string, string>;
-}
-
-/** Own bindings shadow the fallback, mirroring resolution's upward walk. */
-type BindingLookup = (token: Token<unknown> | Constructor) => ReadonlyArray<Binding>;
-
-function bindingLookup(sourceRegistry: BindingRegistry, fallbackRegistry: BindingRegistry | undefined): BindingLookup {
-  return (token) => {
-    const own = sourceRegistry.getAll(token);
-
-    if (own.length > 0 || fallbackRegistry === undefined) {
-      return own;
-    }
-
-    return fallbackRegistry.getAll(token);
-  };
-}
-
-/** The placeholder node an optional-but-unbound dependency points at, minted once per token. */
-function unboundNodeIdFor(accumulator: GraphAccumulator, dependency: Token<unknown> | Constructor): string {
-  const key = tokenKeyOf(dependency);
-  const existing = accumulator.unboundNodeIds.get(key);
-
-  if (existing !== undefined) {
-    return existing;
-  }
-
-  const id = `unbound:${key}`;
-
-  accumulator.unboundNodeIds.set(key, id);
-  accumulator.nodes.push({
-    id,
-    tokenName: tokenName(dependency),
-    tokenKey: key,
-    kind: "unbound",
-    scope: "unbound",
-    fromParent: false,
-  });
-
-  return id;
-}
-
-function addDependencyEdges(
-  accumulator: GraphAccumulator,
-  from: string,
-  ref: DependencySlot,
-  index: number,
-  lookup: BindingLookup,
-): void {
-  const targets = matchingTargets(lookup(ref.token), ref);
-  const label = edgeLabel(ref, index);
-
-  if (targets.length === 0) {
-    // A required-but-unbound dependency is validate()'s story, not the graph's.
-    if (!ref.optional) {
-      return;
-    }
-
-    accumulator.edges.push({
-      from,
-      to: unboundNodeIdFor(accumulator, ref.token),
-      label,
-      optional: true,
-      ...(ref.name !== undefined ? { slotName: ref.name } : {}),
-    });
-
-    return;
-  }
-
-  for (const target of targets) {
-    // A multi dep with no criterion of its own fans out — each edge names the slot it hits.
-    const slotName = target.slot.name ?? ref.name;
-    const perTargetLabel =
-      ref.multi && ref.name === undefined && slotName !== undefined
-        ? edgeLabel({ ...ref, name: slotName }, index)
-        : label;
-
-    accumulator.edges.push({
-      from,
-      to: target.id,
-      label: perTargetLabel,
-      optional: ref.optional,
-      ...(slotName !== undefined ? { slotName } : {}),
-    });
-  }
-}
-
-/** What one binding declares up front — a class's params, a factory's descriptors, an alias's target. */
-function addBindingEdges(
-  accumulator: GraphAccumulator,
-  binding: Binding,
-  metadataReader: MetadataReader,
-  lookup: BindingLookup,
-): void {
-  if (binding.kind === "class") {
-    const meta = metadataReader.getConstructorMetadata(binding.target);
-
-    if (meta !== undefined) {
-      for (const [index, param] of meta.params.entries()) {
-        addDependencyEdges(accumulator, binding.id, param, index, lookup);
-      }
-    }
-
-    return;
-  }
-
-  if (binding.kind === "resolved" || binding.kind === "resolved-async") {
-    for (const [index, dependency] of binding.deps.entries()) {
-      addDependencyEdges(accumulator, binding.id, dependency, index, lookup);
-    }
-
-    return;
-  }
-
-  if (binding.kind === "alias") {
-    const aliasRef: DependencySlot = { token: binding.target, optional: false, multi: false };
-
-    for (const target of matchingTargets(lookup(binding.target), aliasRef)) {
-      accumulator.edges.push({ from: binding.id, to: target.id, label: "alias", optional: false });
-    }
-  }
-}
-
-function addRegistryBindings(
-  accumulator: GraphAccumulator,
-  sourceRegistry: BindingRegistry,
-  metadataReader: MetadataReader,
-  fromParent: boolean,
-  fallbackRegistry?: BindingRegistry,
-): void {
-  const lookup = bindingLookup(sourceRegistry, fallbackRegistry);
-
-  for (const binding of sourceRegistry.allBindings()) {
-    accumulator.nodes.push({
-      id: binding.id,
-      tokenName: tokenName(binding.token),
-      tokenKey: tokenKeyOf(binding.token),
-      kind: binding.kind,
-      scope: effectiveBindingScope(binding),
-      fromParent,
-    });
-
-    addBindingEdges(accumulator, binding, metadataReader, lookup);
-  }
-}
-
-/**
- * Builds the JSON dependency graph of a registry's bindings, optionally including the parent's.
- *
- * @since 0.3.16-canary.0
- */
-export function buildDependencyGraph(
-  registry: BindingRegistry,
-  metadataReader: MetadataReader,
-  options: GraphOptions | undefined,
-  parentRegistry?: BindingRegistry,
-): ContainerGraphJson {
-  const accumulator: GraphAccumulator = { nodes: [], edges: [], unboundNodeIds: new Map() };
-  const includesParent = options?.includeParent === true;
-
-  addRegistryBindings(accumulator, registry, metadataReader, false, includesParent ? parentRegistry : undefined);
-
-  if (includesParent && parentRegistry !== undefined) {
-    addRegistryBindings(accumulator, parentRegistry, metadataReader, true);
-  }
-
-  return { nodes: accumulator.nodes, edges: accumulator.edges, includesParent };
-}