@codefast/di 0.10.1 → 0.12.0

package/dist/container/binding-builders.js

@@ -1,305 +0,0 @@
-import { clearBindingFrame, createBindingSlot, DEFAULT_BINDING_SLOT, generateBindingId, NO_INSTANCE, } from "#core/binding";
-import { mergingConstraintRequirements } from "#core/constraint-requirement";
-import { slotName } from "#core/tag";
-import { tokenName } from "#core/token";
-import { ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, SelfBindingRequiresClassError, } from "#errors/errors";
-import { normalizeToDescriptor } from "#injection/descriptor";
-/** One criterion per key: re-tagging the same key replaces it rather than asking for both values. */
-function updateSlotTag(slot, criterion) {
-    const tags = [...slot.tags];
-    const existingIndex = tags.findIndex((existing) => existing.key === criterion.key);
-    if (existingIndex === -1) {
-        tags.push(criterion);
-    }
-    else {
-        tags[existingIndex] = criterion;
-    }
-    return createBindingSlot(tags);
-}
-// ── BindingChain ─────────────────────────────────────────────────────────────────────────────────────────────────────
-/**
- * The one builder behind `bind()` and every `to*()` return type — and the binding it registers.
- *
- * @remarks The binding fields come first, in the order every binding shares, and the chain's own
- * bookkeeping follows as private fields; `to*()` fills the fields in place and hands this object to
- * the registry, so a plain bind is one allocation. Refinements write the registered object: a scope
- * or hook in place, a slot or predicate through the registry so its indexes follow.
- *
- * @since 0.5.0-canary.8
- */
-export class BindingChain {
-    // The binding. Every field, every kind, written in this order and nowhere else: one hidden class.
-    kind = "constant";
-    identifier = generateBindingId();
-    inFlight = false;
-    frame = undefined;
-    instance = NO_INSTANCE;
-    token;
-    slot = DEFAULT_BINDING_SLOT;
-    predicate = undefined;
-    isMany = false;
-    scope = "singleton";
-    target = undefined;
-    factory = undefined;
-    deps = undefined;
-    value = undefined;
-    activationHook = undefined;
-    deactivationHook = undefined;
-    // The chain. Set by the first `to*()`, which is the only one a chain accepts.
-    #isRegistered = false;
-    // Allocated only by a chain that actually displaces something — most never do.
-    #displacedByChain;
-    // Registry version after this chain's last write — a mismatch means someone else wrote in between.
-    #versionAfterLastWrite = -1;
-    #registration;
-    constructor(token, registration) {
-        this.token = token;
-        this.#registration = registration;
-    }
-    /** This object as the registry and the resolver see it: the value type erased once, here. */
-    get #binding() {
-        return this;
-    }
-    /** Loud failure for a refinement before `to*()`. */
-    #requireRegistered() {
-        if (!this.#isRegistered) {
-            throw new ChainNotRegisteredError(tokenName(this.token));
-        }
-    }
-    /** Loud failure for a second `to*()`, raised before the first one's fields can be overwritten. */
-    #requireUnregistered() {
-        if (this.#isRegistered) {
-            throw new ChainAlreadyRegisteredError(tokenName(this.token));
-        }
-    }
-    #register(kind, scope) {
-        this.kind = kind;
-        this.scope = scope;
-        this.#isRegistered = true;
-        this.#commit(undefined);
-        return this;
-    }
-    // ── Registration ───────────────────────────────────────────────────────────────────────────────────────────────────
-    to(type) {
-        this.#requireUnregistered();
-        this.target = type;
-        return this.#register("class", "transient");
-    }
-    toSelf() {
-        this.#requireUnregistered();
-        if (typeof this.token !== "function") {
-            throw new SelfBindingRequiresClassError(tokenName(this.token));
-        }
-        this.target = this.token;
-        return this.#register("class", "transient");
-    }
-    toConstantValue(value) {
-        this.#requireUnregistered();
-        this.value = value;
-        return this.#register("constant", "singleton");
-    }
-    toDynamic(factory) {
-        this.#requireUnregistered();
-        this.factory = factory;
-        return this.#register("dynamic", "transient");
-    }
-    toDynamicAsync(factory) {
-        this.#requireUnregistered();
-        this.factory = factory;
-        return this.#register("dynamic-async", "transient");
-    }
-    toResolved(factory, deps) {
-        this.#requireUnregistered();
-        this.factory = factory;
-        this.deps = deps.map((dependency) => normalizeToDescriptor(dependency));
-        return this.#register("resolved", "transient");
-    }
-    toResolvedAsync(factory, deps) {
-        this.#requireUnregistered();
-        this.factory = factory;
-        this.deps = deps.map((dependency) => normalizeToDescriptor(dependency));
-        return this.#register("resolved-async", "transient");
-    }
-    toAlias(target) {
-        this.#requireUnregistered();
-        this.target = target;
-        return this.#register("alias", "transient");
-    }
-    // ── Refinement ─────────────────────────────────────────────────────────────────────────────────────────────────────
-    /**
-     * Whether this chain provably still owns the registry's last write with nothing parked.
-     *
-     * @remarks When it does, a refinement rewrites the live binding in place; otherwise `#reslot`
-     * re-checks liveness and restores what the new shape frees.
-     */
-    get #isProvablyLive() {
-        return this.#registration.registry.version === this.#versionAfterLastWrite && this.#displacedByChain === undefined;
-    }
-    /** Stamps this chain's last-write version after a mutation it made in place. */
-    #recordWrite() {
-        this.#versionAfterLastWrite = this.#registration.registry.version;
-    }
-    /** Bumps the registry for an index-neutral mutation (scope, hook) and records this chain's write. */
-    #touchAndRecordWrite() {
-        this.#registration.registry.touch();
-        this.#recordWrite();
-    }
-    // Slot and predicate are what the registry indexes on, so a re-slot takes the binding out of the
-    // registry, rewrites the two fields while it is out, and registers it again — same object, same id.
-    #reslot(slot, predicate) {
-        this.#requireRegistered();
-        this.#commit(() => {
-            this.slot = slot;
-            this.predicate = predicate;
-            // The frame reports the slot, so a resolve before this call memoized the previous one.
-            clearBindingFrame(this.#binding);
-        });
-        return this;
-    }
-    #withScope(scope) {
-        this.#requireRegistered();
-        if (this.scope !== scope) {
-            // An instance cached under the old scope must not survive the change — a later flip back
-            // to that scope would resurrect it.
-            this.#registration.scope.deleteSingleton(this.#binding);
-            this.#registration.scope.deleteScoped(this.identifier);
-            this.scope = scope;
-        }
-        // The frame reports the scope, so a resolve before this call memoized the previous one.
-        clearBindingFrame(this.#binding);
-        this.#touchAndRecordWrite();
-        return this;
-    }
-    // SPEC calls a candidate a binding that passes *all* of a chain's predicates, and the chain type
-    // reads as refinement, so a second `when()` narrows rather than replaces.
-    when(predicate) {
-        this.#requireRegistered();
-        const previous = this.predicate;
-        // The composite carries both sides' requirements, so validate() still sees them.
-        const narrowed = previous === undefined
-            ? predicate
-            : mergingConstraintRequirements((ctx) => previous(ctx) && predicate(ctx), previous, predicate);
-        // The slot is unchanged, so a provably-live binding just takes the predicate in place.
-        if (this.#isProvablyLive) {
-            this.#registration.registry.setPredicate(this.#binding, narrowed);
-            this.#recordWrite();
-            return this;
-        }
-        return this.#reslot(this.slot, narrowed);
-    }
-    whenNamed(name) {
-        return this.whenTagged(slotName.of(name));
-    }
-    whenTagged(criterion) {
-        this.#requireRegistered();
-        if (this.isMany) {
-            throw new ManyBindingSlotError(tokenName(this.token));
-        }
-        return this.#reslot(updateSlotTag(this.slot, criterion), this.predicate);
-    }
-    many() {
-        this.#requireRegistered();
-        if (this.slot.tags.length !== 0) {
-            throw new ManyBindingSlotError(tokenName(this.token));
-        }
-        if (this.isMany) {
-            return this;
-        }
-        // A provably-live binding takes membership in place; the registry only moves it out of the lone
-        // map. Otherwise `#commit` re-checks liveness and restores what the freed slot lets back in.
-        if (this.#isProvablyLive) {
-            this.#registration.registry.setMany(this.#binding);
-            this.#recordWrite();
-            return this;
-        }
-        this.#commit(() => {
-            this.isMany = true;
-        });
-        return this;
-    }
-    whenDefault() {
-        // The default slot is what a fresh registration already has, so there is nothing to re-slot —
-        // but an unregistered chain must fail here exactly as it does in every other refinement.
-        this.#requireRegistered();
-        return this;
-    }
-    singleton() {
-        return this.#withScope("singleton");
-    }
-    transient() {
-        return this.#withScope("transient");
-    }
-    scoped() {
-        return this.#withScope("scoped");
-    }
-    onActivation(fn) {
-        this.#requireRegistered();
-        this.activationHook = fn;
-        this.#touchAndRecordWrite();
-        return this;
-    }
-    onDeactivation(fn) {
-        this.#requireRegistered();
-        this.deactivationHook = fn;
-        this.#touchAndRecordWrite();
-        return this;
-    }
-    id() {
-        this.#requireRegistered();
-        return this.identifier;
-    }
-    // ── Registry ───────────────────────────────────────────────────────────────────────────────────────────────────────
-    /**
-     * Registers this binding; with `rewrite` given, first takes the live binding out, rewrites it, and
-     * registers it again.
-     *
-     * @remarks A `when*()` that follows `to*()` re-slots an already-live binding and can displace one
-     * the final shape would never conflict with. Those stay parked in `#displacedByChain` until the
-     * chain settles, then get restored.
-     */
-    #commit(rewrite) {
-        const { registry, moduleBindingIds } = this.#registration;
-        const registered = this.#binding;
-        if (rewrite !== undefined) {
-            // A registry someone else wrote since this chain's last write invalidates the parked
-            // snapshot: restoring it could undo an unbind or shadow a newer binding.
-            if (registry.version !== this.#versionAfterLastWrite) {
-                this.#displacedByChain = undefined;
-            }
-            if (!registry.reslot(registered, rewrite)) {
-                // The chain's binding is no longer live (unbound or displaced) — a refinement must not
-                // resurrect it, so the chain goes inert against the registry.
-                this.#displacedByChain = undefined;
-                this.#versionAfterLastWrite = registry.version;
-                return;
-            }
-        }
-        else {
-            // Each `to*()` starts its own registration, so anything a previous one displaced is not this
-            // registration's to restore.
-            this.#displacedByChain = undefined;
-        }
-        const displaced = registry.add(registered);
-        if (displaced !== undefined) {
-            (this.#displacedByChain ??= []).push(displaced);
-        }
-        if (rewrite !== undefined && this.#displacedByChain !== undefined) {
-            this.#restoreNonConflicting(this.#displacedByChain);
-        }
-        if (rewrite === undefined && moduleBindingIds !== undefined) {
-            moduleBindingIds.push(this.identifier);
-        }
-        this.#versionAfterLastWrite = registry.version;
-    }
-    #restoreNonConflicting(displaced) {
-        for (let index = displaced.length - 1; index >= 0; index -= 1) {
-            const candidate = displaced[index];
-            // A restore must never displace: a slot that has been re-occupied keeps its occupant, and
-            // the candidate stays parked.
-            if (!this.#registration.registry.hasSlotOccupant(candidate)) {
-                this.#registration.registry.add(candidate);
-                displaced.splice(index, 1);
-            }
-        }
-    }
-}

package/dist/core/binding-scope.d.ts

@@ -1,12 +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 declare function effectiveBindingScope(binding: Binding): BindingScope;

package/dist/core/binding-scope.js

@@ -1,12 +0,0 @@
-/**
- * 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) {
-    return binding.scope;
-}

package/dist/metadata/verifying-metadata-reader.js

@@ -1,31 +0,0 @@
-/**
- * Wraps a foreign {@link MetadataReader} so its answers are verified before anything dereferences
- * them.
- */
-import { defaultMetadataReader } from "#metadata/symbol-metadata-reader";
-import { verifyAccessorMetadata, verifyConstructorMetadata, verifyLifecycleMetadata, } from "#resolution/cache/class-introspector";
-// Wrapping a wrapper would stack a layer per child container, so each one is remembered.
-const verifyingReaders = new WeakSet();
-/**
- * The reader a container should hand its resolver: verified when it came from outside.
- *
- * @remarks The decorator reader writes the metadata it later reads, so there is nothing to check and
- * nothing to pay — a container that supplies no reader of its own is left on the same code path it
- * has always taken. A supplied reader is a claim, and only its callers can be charged for checking.
- *
- * @since 0.6.0
- */
-export function verifyingMetadataReader(reader) {
-    if (reader === defaultMetadataReader || verifyingReaders.has(reader)) {
-        return reader;
-    }
-    const verifying = {
-        getConstructorMetadata: (target) => verifyConstructorMetadata(reader, target),
-        getLifecycleMetadata: (target) => verifyLifecycleMetadata(reader, target),
-        ...(reader.getAccessorMetadata === undefined
-            ? {}
-            : { getAccessorMetadata: (target) => verifyAccessorMetadata(reader, target) }),
-    };
-    verifyingReaders.add(verifying);
-    return verifying;
-}

package/dist/resolution/path/resolution-path.d.ts

@@ -1,93 +0,0 @@
-import type { BindingIdentifier, ResolutionFrame } from "#core/types";
-/**
- * Where the cycle check switches from a linear frame scan to an attached Set.
- *
- * @remarks Measured rather than guessed: below this depth the linear scan wins, above it the Set does.
- *
- * @since 0.5.0-canary.7
- */
-export declare const RESOLUTION_SET_THRESHOLD = 32;
-/**
- * The token names along a stack plus the frame that closed the cycle — built only to throw.
- *
- * @since 0.6.0
- */
-export declare function cycleNamesOf(resolutionStack: ReadonlyArray<ResolutionFrame>, closingName: string): Array<string>;
-/**
- * Marks a level as in-flight on this stack, throwing if its binding is already an ancestor.
- *
- * @remarks The check keys on binding identity — two distinct tokens may share a display name — and
- * the names an error prints are derived from the frames at the throw site. Unmark by popping the
- * stack plus `set?.delete(frame.bindingId)`. Sync only — the async lane never removes an entry, so
- * it extends a branch instead; see {@link extendResolutionBranch}.
- *
- * @returns the membership set once the stack is deep enough to carry one, else `undefined`.
- *
- * @since 0.5.0-canary.7
- */
-export declare function enterResolutionPath(resolutionStack: Array<ResolutionFrame>, frame: ResolutionFrame): Set<BindingIdentifier> | undefined;
-declare const BRANCH_BRAND: unique symbol;
-/**
- * A resolution stack one async branch owns, so appending to it cannot disturb another branch.
- *
- * @remarks Only {@link extendResolutionBranch} mints one. That is what makes "may this lane append
- * to this array" a question the compiler answers instead of a rule in a doc — a sync frame's stack,
- * which that frame will pop, is a plain `Array<ResolutionFrame>` and cannot reach a level that owns
- * its own.
- *
- * @since 0.5.0-canary.9
- */
-export type OwnedBranchStack = Array<ResolutionFrame> & {
-    readonly [BRANCH_BRAND]: true;
-};
-declare const BRANCH_DEPTH_BRAND: unique symbol;
-/**
- * How many leading entries of a stack belong to one async branch.
- *
- * @remarks Branded so a bare number cannot be passed: a depth from anywhere but this branch silently
- * re-parents a level.
- *
- * @since 0.5.0-canary.9
- */
-export type OwnedBranchDepth = number & {
-    readonly [BRANCH_DEPTH_BRAND]: true;
-};
-/**
- * A stack no async branch owns yet, so its first extension must copy rather than append.
- *
- * @since 0.5.0-canary.9
- */
-export declare const UNOWNED_BRANCH = -1;
-/**
- * How far into a stack one extension may reach: this branch's own depth, or nobody's.
- *
- * @remarks A union rather than a sentinel hidden inside the branded number, so the two cases are
- * visible at every signature that takes one and `=== UNOWNED_BRANCH` narrows to the owned case.
- *
- * @since 0.5.0-canary.9
- */
-export type BranchDepth = OwnedBranchDepth | typeof UNOWNED_BRANCH;
-/**
- * The depth a chain's first level extends from, over an array its caller just minted.
- *
- * @since 0.5.0-canary.9
- */
-export declare const ROOT_BRANCH: OwnedBranchDepth;
-/**
- * A branch's own depth: the length its stack had when this level took it.
- *
- * @since 0.5.0-canary.9
- */
-export declare function branchDepthOf(branch: OwnedBranchStack): OwnedBranchDepth;
-/**
- * Extends one branch of an append-only stack, throwing if the binding is already an ancestor.
- *
- * @remarks The check compares binding ids on the frames; the names an error prints are derived at
- * the throw site. Appends in place while this branch still owns the next slot, and copies its own
- * prefix once a sibling has claimed it. Nothing is ever removed, so no async level has to observe
- * its own settlement to unwind.
- *
- * @since 0.5.0-canary.9
- */
-export declare function extendResolutionBranch(resolutionStack: Array<ResolutionFrame>, branchDepth: BranchDepth, frame: ResolutionFrame): OwnedBranchStack;
-export {};

package/dist/resolution/path/resolution-path.js

@@ -1,116 +0,0 @@
-/** Cycle-detection bookkeeping carried on the resolution stack itself. */
-import { CircularDependencyError } from "#errors/errors";
-const RESOLUTION_SET_KEY = Symbol("di:resolution-set");
-/**
- * Where the cycle check switches from a linear frame scan to an attached Set.
- *
- * @remarks Measured rather than guessed: below this depth the linear scan wins, above it the Set does.
- *
- * @since 0.5.0-canary.7
- */
-export const RESOLUTION_SET_THRESHOLD = 32;
-/**
- * The token names along a stack plus the frame that closed the cycle — built only to throw.
- *
- * @since 0.6.0
- */
-export function cycleNamesOf(resolutionStack, closingName) {
-    const names = new Array(resolutionStack.length + 1);
-    for (let index = 0; index < resolutionStack.length; index += 1) {
-        names[index] = resolutionStack[index].tokenName;
-    }
-    names[resolutionStack.length] = closingName;
-    return names;
-}
-/**
- * Marks a level as in-flight on this stack, throwing if its binding is already an ancestor.
- *
- * @remarks The check keys on binding identity — two distinct tokens may share a display name — and
- * the names an error prints are derived from the frames at the throw site. Unmark by popping the
- * stack plus `set?.delete(frame.bindingId)`. Sync only — the async lane never removes an entry, so
- * it extends a branch instead; see {@link extendResolutionBranch}.
- *
- * @returns the membership set once the stack is deep enough to carry one, else `undefined`.
- *
- * @since 0.5.0-canary.7
- */
-export function enterResolutionPath(resolutionStack, frame) {
-    const stackWithSet = resolutionStack;
-    let resolutionSet = stackWithSet[RESOLUTION_SET_KEY];
-    // A live set mirrors the stack exactly, so a size that disagrees means it is holding ids of
-    // frames that unwound: the ones already on the stack when it attached were handed no set to
-    // delete from. Dropped rather than repaired, because the next deep frame rebuilds it.
-    if (resolutionSet !== undefined && resolutionSet.size !== resolutionStack.length) {
-        resolutionSet = undefined;
-        stackWithSet[RESOLUTION_SET_KEY] = undefined;
-    }
-    if (resolutionSet === undefined && resolutionStack.length >= RESOLUTION_SET_THRESHOLD) {
-        resolutionSet = new Set();
-        for (let index = 0; index < resolutionStack.length; index += 1) {
-            resolutionSet.add(resolutionStack[index].bindingId);
-        }
-        stackWithSet[RESOLUTION_SET_KEY] = resolutionSet;
-    }
-    if (resolutionSet === undefined) {
-        for (let index = 0; index < resolutionStack.length; index += 1) {
-            if (resolutionStack[index].bindingId === frame.bindingId) {
-                throw new CircularDependencyError(cycleNamesOf(resolutionStack, frame.tokenName));
-            }
-        }
-    }
-    else if (resolutionSet.has(frame.bindingId)) {
-        throw new CircularDependencyError(cycleNamesOf(resolutionStack, frame.tokenName));
-    }
-    resolutionStack.push(frame);
-    resolutionSet?.add(frame.bindingId);
-    return resolutionSet;
-}
-/**
- * A stack no async branch owns yet, so its first extension must copy rather than append.
- *
- * @since 0.5.0-canary.9
- */
-export const UNOWNED_BRANCH = -1;
-/**
- * The depth a chain's first level extends from, over an array its caller just minted.
- *
- * @since 0.5.0-canary.9
- */
-export const ROOT_BRANCH = 0;
-/**
- * A branch's own depth: the length its stack had when this level took it.
- *
- * @since 0.5.0-canary.9
- */
-export function branchDepthOf(branch) {
-    return branch.length;
-}
-/**
- * Extends one branch of an append-only stack, throwing if the binding is already an ancestor.
- *
- * @remarks The check compares binding ids on the frames; the names an error prints are derived at
- * the throw site. Appends in place while this branch still owns the next slot, and copies its own
- * prefix once a sibling has claimed it. Nothing is ever removed, so no async level has to observe
- * its own settlement to unwind.
- *
- * @since 0.5.0-canary.9
- */
-export function extendResolutionBranch(resolutionStack, branchDepth, frame) {
-    const depth = branchDepth === UNOWNED_BRANCH ? resolutionStack.length : branchDepth;
-    for (let index = 0; index < depth; index += 1) {
-        if (resolutionStack[index].bindingId === frame.bindingId) {
-            throw new CircularDependencyError(cycleNamesOf(resolutionStack.slice(0, depth), frame.tokenName));
-        }
-    }
-    // An unowned array belongs to a sync frame that will pop it, or carries a membership Set this
-    // lane cannot keep true; copying is what makes the branch's own appends safe.
-    if (branchDepth === resolutionStack.length) {
-        // The sole mint: appending in place needs a depth that came from a branch already owned, or
-        // ROOT_BRANCH over an array its caller minted for this chain alone.
-        resolutionStack.push(frame);
-        return resolutionStack;
-    }
-    const branch = resolutionStack.slice(0, depth);
-    branch.push(frame);
-    return branch;
-}