@codefast/di 0.7.1 → 0.8.1

package/src/core/binding-scope.ts

@@ -1,15 +0,0 @@
-import type { Binding } from "#/core/binding";
-import type { BindingScope } from "#/core/types";
-
-/**
- * The scope a binding resolves under.
- *
- * @remarks Every kind declares one — an alias declares `transient`, since it defers scoping to the
- * binding it points at — so this is a field read, kept as a named function because it is the
- * vocabulary validation and introspection speak.
- *
- * @since 0.3.16-canary.0
- */
-export function effectiveBindingScope(binding: Binding): BindingScope {
-  return binding.scope;
-}

package/src/core/binding.ts

@@ -1,477 +0,0 @@
-import type { BindingTag, TagKeyMask } from "#/core/tag";
-import { NO_TAG_KEYS } from "#/core/tag";
-import type { Token } from "#/core/token";
-import type {
-  ActivationHandler,
-  BindingIdentifier,
-  BindingScope,
-  Constructor,
-  DeactivationHandler,
-  ResolutionContext,
-  ResolutionFrame,
-  BindingConstraint,
-} from "#/core/types";
-import type { InjectableDependency, InjectionDescriptor, ResolvedDependencyValue } from "#/injection/descriptor";
-
-// ── BindingSlot ──────────────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * The name-plus-tags coordinate a binding registers under and a request matches against.
- *
- * @since 0.3.16-canary.0
- */
-export interface BindingSlot {
-  readonly name: string | undefined;
-  readonly tags: ReadonlyArray<BindingTag>;
-  /** OR of this slot's tag keys, so the subset test is one word compare. */
-  readonly keyMask: TagKeyMask;
-}
-
-/**
- * Returns whether two slots carry the same name and tag set, in any tag order.
- *
- * @since 0.3.16-canary.0
- */
-export function bindingSlotEquals(left: BindingSlot, right: BindingSlot): boolean {
-  if (left.name !== right.name || left.keyMask !== right.keyMask || left.tags.length !== right.tags.length) {
-    return false;
-  }
-  for (const criterion of left.tags) {
-    if (!right.tags.includes(criterion)) {
-      return false;
-    }
-  }
-  return true;
-}
-
-/**
- * Cached singleton absent — distinguishes "not resolved yet" from a cached `undefined`.
- *
- * @since 0.5.0-canary.8
- */
-export const NO_INSTANCE: unique symbol = Symbol("di:no-instance");
-
-/**
- * The slot every unconstrained binding shares.
- *
- * @remarks Tags are frozen where they are built (here and in the builder's re-tag), never per
- * binding: frames and snapshots alias the array, so a caller's write throws instead of corrupting
- * the registry.
- *
- * @since 0.3.16-canary.0
- */
-export const DEFAULT_BINDING_SLOT: BindingSlot = { name: undefined, tags: Object.freeze([]), keyMask: NO_TAG_KEYS };
-
-/**
- * Formats a slot for diagnostics — `default`, or its `name:`/`tag:` parts.
- *
- * @since 0.3.16-canary.0
- */
-export function bindingSlotToString(slot: BindingSlot): string {
-  if (slot.name === undefined && slot.tags.length === 0) {
-    return "default";
-  }
-  const parts: Array<string> = [];
-  if (slot.name !== undefined) {
-    parts.push(`name:${slot.name}`);
-  }
-  for (const criterion of slot.tags) {
-    parts.push(`tag:${criterion.key.name}=${String(criterion.value)}`);
-  }
-  return parts.join(",");
-}
-
-// ── BindingBase ──────────────────────────────────────────────────────────────────────────────────────────────────────
-
-interface BindingBase<Value> {
-  readonly id: BindingIdentifier;
-  /**
-   * True while this binding's factory is executing on the current synchronous call stack.
-   *
-   * @remarks Both cycle guards that can use an `O(1)` flag read this — the sync transient-dynamic
-   * lane and the async cascade lane — because synchronous code does not interleave, so the flag *is*
-   * exact path membership. Not optional: `createBinding` always sets it, and a field that may be
-   * absent is a field that can cost the shared hidden class. Resolver-owned; callers never set it.
-   */
-  inFlight: boolean;
-  /**
-   * Memoized resolution frame for this binding. Its contents derive only from immutable binding
-   * fields, so it is computed once on first resolve and reused instead of a per-resolver Map
-   * lookup on every hop.
-   *
-   * @remarks Resolver-owned bookkeeping — `registry.add` normalizes it, so callers never set it.
-   */
-  frame: ResolutionFrame | undefined;
-  /**
-   * Cached singleton instance, or {@link NO_INSTANCE}.
-   *
-   * @remarks A binding belongs to exactly one container, so its singleton slot is per-binding —
-   * a field read replaces a keyed lookup on the hottest resolve shape there is.
-   */
-  instance: unknown;
-  readonly token: Token<Value> | Constructor<Value>;
-  readonly slot: BindingSlot;
-  readonly predicate?: BindingConstraint | undefined;
-}
-
-type BindingBaseKeys = keyof BindingBase<unknown>;
-
-/**
- * The lifecycle hooks every kind but `alias` may carry.
- *
- * @remarks Declared as **methods**, not function-typed properties, so their parameters compare
- * bivariantly and `Binding<Value>` stays assignable to `Binding`. The engine erases the value type at
- * every lane boundary regardless; the public `ActivationHandler` / `DeactivationHandler` keep strict
- * checking, which is where a user's handler is actually verified. Not `readonly`: a fluent chain
- * refines both in place — see {@link RefinableBindingFields}.
- */
-interface BindingLifecycleHooks<Value> {
-  onActivation?(ctx: ResolutionContext, instance: Value): Value | Promise<Value>;
-  onDeactivation?(instance: Value): void | Promise<void>;
-}
-
-// ── Binding kinds ────────────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * A binding that instantiates a constructor.
- *
- * @since 0.3.16-canary.0
- */
-export interface ClassBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
-  readonly kind: "class";
-  readonly target: Constructor<Value>;
-  readonly scope: BindingScope;
-}
-
-/**
- * A binding that computes its value with a synchronous factory.
- *
- * @since 0.3.16-canary.0
- */
-export interface DynamicBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
-  readonly kind: "dynamic";
-  readonly factory: (ctx: ResolutionContext) => Value;
-  readonly scope: BindingScope;
-}
-
-/**
- * A binding whose factory returns a promise of the value.
- *
- * @since 0.3.16-canary.0
- */
-export interface DynamicAsyncBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
-  readonly kind: "dynamic-async";
-  readonly factory: (ctx: ResolutionContext) => Promise<Value>;
-  readonly scope: BindingScope;
-}
-
-/**
- * A binding whose factory is called with its declared dependencies already resolved.
- *
- * @since 0.3.16-canary.0
- */
-export interface ResolvedBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
-  readonly kind: "resolved";
-  readonly factory: (...args: Array<unknown>) => Value;
-  readonly deps: ReadonlyArray<InjectionDescriptor>;
-  readonly scope: BindingScope;
-}
-
-/**
- * The async form of {@link ResolvedBinding} — the factory returns a promise.
- *
- * @since 0.3.16-canary.0
- */
-export interface ResolvedAsyncBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
-  readonly kind: "resolved-async";
-  readonly factory: (...args: Array<unknown>) => Promise<Value>;
-  readonly deps: ReadonlyArray<InjectionDescriptor>;
-  readonly scope: BindingScope;
-}
-
-/**
- * A binding that hands out one fixed value, so its scope is always `singleton`.
- *
- * @since 0.3.16-canary.0
- */
-export interface ConstantBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
-  readonly kind: "constant";
-  readonly value: Value;
-  readonly scope: "singleton";
-}
-
-/**
- * A binding that defers to whatever binding its target token selects.
- *
- * @since 0.3.16-canary.0
- */
-export interface AliasBinding<Value> extends BindingBase<Value> {
-  readonly kind: "alias";
-  readonly target: Token<Value> | Constructor<Value>;
-  /**
-   * Always `transient` — an alias defers scoping to the binding it points at.
-   *
-   * @remarks Declared so `scope` is present on every kind, which is what lets the engine read it
-   * as a plain field instead of testing for the one kind that lacks it.
-   */
-  readonly scope: "transient";
-}
-
-/**
- * Every binding shape the engine resolves, discriminated by `kind`.
- *
- * @since 0.3.16-canary.0
- */
-export type Binding<Value = unknown> =
-  | ClassBinding<Value>
-  | DynamicBinding<Value>
-  | DynamicAsyncBinding<Value>
-  | ResolvedBinding<Value>
-  | ResolvedAsyncBinding<Value>
-  | ConstantBinding<Value>
-  | AliasBinding<Value>;
-
-/** `Omit` applied per union member, since a bare `Omit` would collapse the union into one shape. */
-type DistributiveOmit<Union, Keys extends PropertyKey> = Union extends unknown ? Omit<Union, Keys> : never;
-
-/**
- * Builder-only payload before `id`, `token`, `slot`, and `predicate` are applied.
- *
- * @remarks Derived rather than listed: a new binding kind joins this the moment it joins
- * {@link Binding}, so the two unions cannot diverge.
- *
- * @since 0.3.16-canary.0
- */
-export type PartialBinding<Value> = DistributiveOmit<Binding<Value>, BindingBaseKeys>;
-
-// ── ID generation ────────────────────────────────────────────────────────────────────────────────────────────────────
-
-let bindingIdCounter = 0;
-/**
- * Returns a process-unique identifier for a new binding.
- *
- * @since 0.3.16-canary.0
- */
-export function generateBindingId(): BindingIdentifier {
-  return String(++bindingIdCounter) as BindingIdentifier;
-}
-
-// ── Construction ─────────────────────────────────────────────────────────────────────────────────────────────────────
-
-/** Every key any member declares — a bare `keyof` on a union gives only the shared ones. */
-type KeysOfUnion<Union> = Union extends unknown ? keyof Union : never;
-
-// Superset of every kind's fields, so one literal can copy any binding shape.
-type BindingFieldName = KeysOfUnion<Binding<unknown>>;
-
-/**
- * Completeness guard for {@link createBinding}'s literal.
- *
- * @remarks The literal is `satisfies` this, so a field added to any binding kind that the literal
- * forgets to write is a compile error rather than a binding silently missing it.
- */
-type ConstructedBindingFields = Record<BindingFieldName, unknown>;
-
-type BindingFieldSuperset = {
-  readonly kind: Binding["kind"];
-  readonly instance?: unknown;
-  readonly scope: BindingScope;
-  readonly target?: unknown;
-  readonly factory?: unknown;
-  readonly deps?: unknown;
-  readonly value?: unknown;
-  readonly onActivation?: unknown;
-  readonly onDeactivation?: unknown;
-};
-
-/**
- * The single construction site for bindings — one literal, one V8 hidden class.
- *
- * @remarks Field order is fixed and this is the only construction site, so every binding shares one
- * hidden class. Reordering the fields, or adding a second site, gives that up.
- *
- * @param source - the kind-specific payload, or an existing binding to re-slot
- * @param token - the key requests resolve the binding by
- * @param slot - the name + tags a request must match to select this binding
- * @param predicate - a custom constraint, or `undefined` for none
- * @param id - reuse a caller's id to keep a fluent chain's `id()` stable across refinements
- *
- * @since 0.5.0-canary.8
- */
-export function createBinding<Value>(
-  source: PartialBinding<Value> | Binding<Value>,
-  token: Token<Value> | Constructor<Value>,
-  slot: BindingSlot,
-  predicate: BindingConstraint | undefined,
-  id: BindingIdentifier = generateBindingId(),
-): Binding<Value> {
-  const fields = source as BindingFieldSuperset;
-  return {
-    kind: fields.kind,
-    id,
-    inFlight: false,
-    frame: undefined,
-    // An `in` probe, not `??`: a re-slotted singleton may legitimately hold a cached `undefined`.
-    instance: "instance" in fields ? fields.instance : NO_INSTANCE,
-    token,
-    slot,
-    predicate,
-    scope: fields.scope,
-    target: fields.target,
-    factory: fields.factory,
-    deps: fields.deps,
-    value: fields.value,
-    onActivation: fields.onActivation,
-    onDeactivation: fields.onDeactivation,
-  } satisfies ConstructedBindingFields as Binding<Value>;
-}
-
-/**
- * Writable view of the only fields a fluent chain may refine after registration.
- *
- * @remarks No registry index is keyed on these, so a builder that owns the registered object
- * can write them directly instead of re-registering. `token`, `slot`, `predicate` and `id`
- * are excluded on purpose — changing those means re-indexing.
- *
- * @since 0.5.0-canary.8
- */
-export interface RefinableBindingFields<Value> {
-  onActivation: ActivationHandler<Value> | undefined;
-  onDeactivation: DeactivationHandler<Value> | undefined;
-  scope: BindingScope;
-}
-
-/**
- * Narrows a registered binding to the fields a fluent chain may still refine.
- *
- * @since 0.5.0-canary.8
- */
-export function refinableFields<Value>(binding: Binding<Value>): RefinableBindingFields<Value> {
-  return binding as RefinableBindingFields<Value>;
-}
-
-/**
- * Writable view of the memoized frame, which is a cache rather than part of a binding's identity.
- *
- * @remarks Named for the same reason as {@link RefinableBindingFields}: a write view stated once
- * cannot drift from `Binding`, where an inline cast at each site can.
- */
-interface MemoizedFrameField {
-  frame: ResolutionFrame | undefined;
-}
-
-/**
- * Drops the memoized resolution frame, for a refinement that changes what the frame reports.
- *
- * @remarks `scope` is the only field a chain writes in place that the frame derives from — a
- * re-slot builds a fresh binding, whose frame starts empty anyway.
- *
- * @since 0.5.0-canary.9
- */
-export function clearBindingFrame<Value>(binding: Binding<Value>): void {
-  (binding as MemoizedFrameField).frame = undefined;
-}
-
-// ── Builder interfaces ───────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * Common slot-constraint + id methods shared by all concrete binding builders.
- *
- * @since 0.3.16-canary.0
- */
-export interface SlotConstrainedBuilder {
-  when(predicate: BindingConstraint): this;
-  whenNamed(name: string): this;
-  whenTagged(criterion: BindingTag): this;
-  whenDefault(): this;
-  id(): BindingIdentifier;
-}
-
-/**
- * The `to*` step of the fluent chain, choosing what a token resolves to.
- *
- * @since 0.3.16-canary.0
- */
-export interface BindToBuilder<Value> {
-  to(type: Constructor<Value>): BindingBuilder<Value>;
-  toSelf(): BindingBuilder<Value>;
-  toConstantValue(value: Value): ConstantBindingBuilder<Value>;
-  toDynamic(factory: (ctx: ResolutionContext) => Value): BindingBuilder<Value>;
-  toDynamicAsync(factory: (ctx: ResolutionContext) => Promise<Value>): BindingBuilder<Value>;
-  toResolved<const Deps extends ReadonlyArray<InjectableDependency>>(
-    factory: (...args: { [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]> }) => Value,
-    deps: Deps,
-  ): BindingBuilder<Value>;
-  toResolvedAsync<const Deps extends ReadonlyArray<InjectableDependency>>(
-    factory: (...args: { [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]> }) => Promise<Value>,
-    deps: Deps,
-  ): BindingBuilder<Value>;
-  toAlias(target: Token<Value> | Constructor<Value>): AliasBindingBuilder;
-}
-
-/**
- * The scope-selection step of the fluent chain.
- *
- * @since 0.3.16-canary.0
- */
-export interface BindingBuilder<Value> extends SlotConstrainedBuilder {
-  singleton(): SingletonBindingBuilder<Value>;
-  transient(): TransientBindingBuilder<Value>;
-  scoped(): ScopedBindingBuilder<Value>;
-}
-
-/**
- * The fluent chain for a constant — lifecycle hooks only, since the scope is fixed.
- *
- * @since 0.3.16-canary.0
- */
-export interface ConstantBindingBuilder<Value> extends SlotConstrainedBuilder {
-  onActivation(fn: ActivationHandler<Value>): SingletonLifecycleBuilder<Value>;
-  onDeactivation(fn: DeactivationHandler<Value>): SingletonLifecycleBuilder<Value>;
-}
-
-/**
- * The fluent chain for an alias — slot constraints only, since scoping belongs to the target.
- *
- * @since 0.3.16-canary.0
- */
-export interface AliasBindingBuilder extends SlotConstrainedBuilder {}
-
-/**
- * The fluent chain after `singleton()`, where both lifecycle hooks stay available.
- *
- * @since 0.3.16-canary.0
- */
-export interface SingletonBindingBuilder<Value> {
-  onActivation(fn: ActivationHandler<Value>): this;
-  onDeactivation(fn: DeactivationHandler<Value>): this;
-  id(): BindingIdentifier;
-}
-
-/**
- * The fluent chain after `transient()`, where activation is the one lifecycle hook offered.
- *
- * @since 0.3.16-canary.0
- */
-export interface TransientBindingBuilder<Value> {
-  onActivation(fn: ActivationHandler<Value>): this;
-  id(): BindingIdentifier;
-}
-
-/**
- * The fluent chain after `scoped()`, sharing the `transient()` surface.
- *
- * @since 0.3.16-canary.0
- */
-export interface ScopedBindingBuilder<Value> extends TransientBindingBuilder<Value> {}
-
-/**
- * The fluent chain a constant enters once a lifecycle hook is added.
- *
- * @since 0.3.16-canary.0
- */
-export interface SingletonLifecycleBuilder<Value> {
-  onActivation(fn: ActivationHandler<Value>): this;
-  onDeactivation(fn: DeactivationHandler<Value>): this;
-  id(): BindingIdentifier;
-}

package/src/core/constraint-requirement.ts

@@ -1,94 +0,0 @@
-/** What a constraint needs to exist before it can ever match, so `validate()` can check for it. */
-import type { BindingConstraint } from "#/core/types";
-
-/**
- * Key the requirement is attached under.
- *
- * @remarks A symbol on the predicate rather than a field in the binding: resolution never reads it,
- * so carrying it costs a resolve nothing.
- *
- * @since 0.6.0
- */
-export const CONSTRAINT_REQUIREMENT: unique symbol = Symbol("di:constraint-requirement");
-
-/**
- * The slot name a constraint waits for on an ancestor.
- *
- * @remarks Only names are described. A tag criterion is interned, so a typo cannot produce one that
- * looks valid, while a name is a bare string that nothing checks.
- *
- * @since 0.6.0
- */
-export interface ConstraintRequirement {
-  readonly requires: "ancestorSlotName";
-  readonly name: string;
-  /** The helper that built the predicate, so a report can name what the caller wrote. */
-  readonly helperName: string;
-}
-
-/**
- * Records what a predicate waits for. Called once, where the predicate is built.
- *
- * @since 0.6.0
- */
-export function requiringAncestorSlotName(
-  predicate: BindingConstraint,
-  name: string,
-  helperName: string,
-): BindingConstraint {
-  const requirement: ConstraintRequirement = { requires: "ancestorSlotName", name, helperName };
-  Object.defineProperty(predicate, CONSTRAINT_REQUIREMENT, { value: requirement, enumerable: false });
-  return predicate;
-}
-
-/**
- * The requirement a predicate carries, if it was built by a helper that records one.
- *
- * @remarks A composed predicate may carry several; this answers the first. `validate()` reads
- * {@link constraintRequirementsOf} so no recorded requirement is skipped.
- *
- * @since 0.6.0
- */
-export function constraintRequirementOf(predicate: BindingConstraint): ConstraintRequirement | undefined {
-  return constraintRequirementsOf(predicate)[0];
-}
-
-const NO_REQUIREMENTS: ReadonlyArray<ConstraintRequirement> = [];
-
-/**
- * Every requirement a predicate carries — one from a helper, several from a composed chain.
- *
- * @since 0.6.1
- */
-export function constraintRequirementsOf(predicate: BindingConstraint): ReadonlyArray<ConstraintRequirement> {
-  const payload = (
-    predicate as { [CONSTRAINT_REQUIREMENT]?: ConstraintRequirement | ReadonlyArray<ConstraintRequirement> }
-  )[CONSTRAINT_REQUIREMENT];
-  if (payload === undefined) {
-    return NO_REQUIREMENTS;
-  }
-  return Array.isArray(payload)
-    ? (payload as ReadonlyArray<ConstraintRequirement>)
-    : [payload as ConstraintRequirement];
-}
-
-/**
- * Carries both sides' requirements onto a composed predicate, so chaining does not lose them.
- *
- * @since 0.6.1
- */
-export function mergingConstraintRequirements(
-  composite: BindingConstraint,
-  left: BindingConstraint,
-  right: BindingConstraint,
-): BindingConstraint {
-  const merged = [...constraintRequirementsOf(left), ...constraintRequirementsOf(right)];
-  if (merged.length === 0) {
-    return composite;
-  }
-  Object.defineProperty(composite, CONSTRAINT_REQUIREMENT, {
-    value: merged.length === 1 ? merged[0] : merged,
-    enumerable: false,
-  });
-  return composite;
-}

package/src/core/constructor-type.ts

@@ -1,18 +0,0 @@
-/**
- * A class token: newable, producing `Value`.
- *
- * @remarks Rest parameters are `never[]` so classes with typed constructors stay assignable under
- * `strictFunctionTypes`. Construction uses the real shape; this alias is the token surface only.
- *
- * @since 0.3.16-canary.0
- */
-export type Constructor<out Value = unknown> = new (...args: Array<never>) => Value;
-
-/**
- * Class constructor as invoked by the resolver after metadata-driven
- * resolution of `unknown[]` dependencies — separate from {@link Constructor},
- * which is the public assignable class token.
- *
- * @since 0.3.16-canary.0
- */
-export type ConstructorInvocation = new (...args: Array<unknown>) => unknown;

package/src/core/map-upsert.ts

@@ -1,53 +0,0 @@
-/** The two `Map` upsert forms the container indexes on, owned here so the package's Node floor stays put. */
-
-/**
- * Returns the value stored under a key, inserting the given fallback first when the key is absent.
- *
- * @remarks The caller evaluates the fallback either way, so this form fits an insertion that usually
- * misses. Absence is one `get`, which is why the value type excludes `undefined`.
- *
- * @param map - mutated in place on a miss
- * @param key - looked up by the map's own key equality
- * @param value - stored and returned when the key is absent
- *
- * @since 0.7.0
- */
-export function getOrInsert<Key, Value extends {} | null>(
-  map: Map<Key, Value>,
-  key: NoInfer<Key>,
-  value: NoInfer<Value>,
-): Value {
-  const existing = map.get(key);
-  if (existing !== undefined) {
-    return existing;
-  }
-  map.set(key, value);
-  return value;
-}
-
-/**
- * Returns the value stored under a key, computing and inserting a fallback only when the key is absent.
- *
- * @remarks Fits a lookup that usually hits, where an eager fallback would allocate per call; hoist
- * the factory to module scope and no closure is allocated either. Absence is decided as in
- * {@link getOrInsert}.
- *
- * @param map - mutated in place on a miss
- * @param key - looked up by the map's own key equality, and handed to the factory
- * @param create - called only on a miss
- *
- * @since 0.7.0
- */
-export function getOrInsertComputed<Key, Value extends {} | null>(
-  map: Map<Key, Value>,
-  key: NoInfer<Key>,
-  create: (key: NoInfer<Key>) => NoInfer<Value>,
-): Value {
-  const existing = map.get(key);
-  if (existing !== undefined) {
-    return existing;
-  }
-  const created = create(key);
-  map.set(key, created);
-  return created;
-}