@codefast/di 0.10.1 → 0.12.0

package/dist/core/binding.d.ts

@@ -1,7 +1,7 @@
 import type { BindingTag, TagKeyMask } 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";
+import type { BindingConstraint, BindingIdentifier, BindingScope, Constructor, ResolutionContext, ResolutionFrame } from "#core/types";
+import type { InjectionDescriptor } from "#injection/descriptor";
 /**
  * The criterion set a binding registers under and a request matches against.
  *
@@ -32,6 +32,14 @@ export declare function createBindingSlot(tags: ReadonlyArray<BindingTag>): Bind
  * @since 0.3.16-canary.0
  */
 export declare function bindingSlotEquals(left: BindingSlot, right: BindingSlot): boolean;
+/**
+ * Returns the slot with one criterion added, replacing any earlier criterion of the same key.
+ *
+ * @remarks One criterion per key: re-tagging a key replaces it rather than asking for both values.
+ *
+ * @since 0.11.0
+ */
+export declare function withSlotCriterion(slot: BindingSlot, criterion: BindingTag): BindingSlot;
 /**
  * Cached singleton absent — distinguishes "not resolved yet" from a cached `undefined`.
  *
@@ -48,6 +56,15 @@ export declare const NO_INSTANCE: unique symbol;
  * @since 0.3.16-canary.0
  */
 export declare const DEFAULT_BINDING_SLOT: BindingSlot;
+/**
+ * Renders a tag value for a diagnostic, never throwing.
+ *
+ * @remarks A tag value is caller data — a bigint, a null-prototype object, a throwing `toString` —
+ * so stringifying it must not become the error that masks the real one.
+ *
+ * @since 0.11.0
+ */
+export declare function stringifyTagValue(value: unknown): string;
 /**
  * Formats a slot for diagnostics — `default`, or its `name:`/`tag:` parts.
  *
@@ -57,12 +74,13 @@ export declare function bindingSlotToString(slot: BindingSlot): string;
 interface BindingBase<Value> {
     readonly identifier: BindingIdentifier;
     /**
-     * True while this binding's factory is executing on the current synchronous call stack.
+     * True while this binding is being resolved 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: the binding builder always initializes it, and a field that
-     * may be absent is a field that can cost the shared hidden class. Resolver-owned; callers never set it.
+     * @remarks Every synchronous cycle guard reads this flag and nothing else: synchronous code does not
+     * interleave, so the flag *is* exact path membership at any depth. The async lanes hold it only for a
+     * factory's synchronous prefix, or for the seeded path a synchronous call from an async level runs
+     * over. Not optional: the binding builder always initializes 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;
     /**
@@ -73,6 +91,21 @@ interface BindingBase<Value> {
      * @remarks Resolver-owned bookkeeping — `registry.add` normalizes it, so callers never set it.
      */
     frame: ResolutionFrame | undefined;
+    /**
+     * The context a transient factory root is handed, built once per binding: the root's path is its own frame
+     * alone, so every resolve of the root reads the same one.
+     *
+     * @remarks Resolver-owned bookkeeping, cleared with the frame it is built over.
+     */
+    rootContext: ResolutionContext | undefined;
+    /**
+     * The activation need last computed for this binding, stamped with the versions it was computed
+     * under, or {@link NO_ACTIVATION_STAMP}.
+     *
+     * @remarks Resolver-owned bookkeeping: a field the level reads beats a per-resolver map that a
+     * container resolving each binding once would build and never read again.
+     */
+    activationStamp: number;
     /**
      * Cached singleton instance, or {@link NO_INSTANCE}.
      *
@@ -80,6 +113,13 @@ interface BindingBase<Value> {
      * a field read replaces a keyed lookup on the hottest resolve shape there is.
      */
     instance: unknown;
+    /**
+     * The key every container's scoped cache files this binding's instance under.
+     *
+     * @remarks Chain-owned. It starts as the binding's id, and a scope verb that changes the scope mints a new one, so
+     * a scoped instance any child cached under an earlier scope is never found again. The id itself stays stable.
+     */
+    scopedCacheKey: BindingIdentifier;
     readonly token: Token<Value> | Constructor<Value>;
     readonly slot: BindingSlot;
     readonly predicate?: BindingConstraint | undefined;
@@ -188,150 +228,34 @@ export interface AliasBinding<Value> extends BindingBase<Value> {
  */
 export type Binding<Value = unknown> = ClassBinding<Value> | DynamicBinding<Value> | DynamicAsyncBinding<Value> | ResolvedBinding<Value> | ResolvedAsyncBinding<Value> | ConstantBinding<Value> | AliasBinding<Value>;
 /**
- * Returns a process-unique identifier for a new binding.
- *
- * @since 0.3.16-canary.0
- */
-export declare function generateBindingId(): BindingIdentifier;
-/**
- * Writable view of the one selection field a chain may refine without re-registering: nothing
- * indexes on the predicate, so the registry rewrites it in place and re-homes the binding itself.
- *
- * @since 0.10.0
- */
-export interface PredicateField {
-    predicate: BindingConstraint | undefined;
-}
-/**
- * Narrows a registered binding to its predicate for the registry to rewrite.
- *
- * @since 0.10.0
- */
-export declare function writablePredicate(binding: Binding): PredicateField;
-/**
- * Writable view of collection membership, which the registry sets because it decides the binding's map.
- *
- * @since 0.10.0
- */
-export interface MembershipField {
-    isMany: boolean;
-}
-/**
- * Narrows a registered binding to its membership flag for the registry to set.
- *
- * @since 0.10.0
- */
-export declare function writableMembership(binding: Binding): MembershipField;
-/**
- * Drops the memoized resolution frame, for a refinement that changes what the frame reports.
- *
- * @remarks The frame derives from `scope` and `slot`, both of which a chain now writes in place on
- * the registered object, so every such refinement clears it.
- *
- * @since 0.5.0-canary.9
- */
-export declare function clearBindingFrame<Value>(binding: Binding<Value>): void;
-/**
- * Common slot-constraint + id methods shared by all concrete binding builders.
- *
- * @since 0.3.16-canary.0
- */
-export interface SlotConstrainedBuilder<Names extends string = string> {
-    /** Narrows the binding to requests the predicate accepts, evaluated on every resolve. */
-    when(predicate: BindingConstraint): this;
-    /** Declares the binding's slot name, one of the names the token declares. */
-    whenNamed(name: Names): this;
-    /** Declares one criterion of the binding's slot, replacing any earlier criterion of the same key. */
-    whenTagged(criterion: BindingTag): this;
-    /** Keeps the binding on the default slot, the one an unconstrained request selects. */
-    whenDefault(): this;
-    /**
-     * Makes the binding a collection member: one of several the token's `resolveAll` returns, never
-     * what a single `resolve` selects, and outside slot last-wins. It keeps the default slot.
-     */
-    many(): this;
-    /** The identifier this binding is registered under. */
-    id(): BindingIdentifier;
-}
-/**
- * The `to*` step of the fluent chain, choosing what a token resolves to.
+ * The scope a binding resolves under.
  *
- * @since 0.3.16-canary.0
- */
-export interface BindToBuilder<Value, Names extends string = string> {
-    to(type: Constructor<Value>): BindingBuilder<Value, Names>;
-    toSelf(): BindingBuilder<Value, Names>;
-    toConstantValue(value: Value): ConstantBindingBuilder<Value, Names>;
-    toDynamic(factory: (ctx: ResolutionContext) => Value): BindingBuilder<Value, Names>;
-    toDynamicAsync(factory: (ctx: ResolutionContext) => Promise<Value>): BindingBuilder<Value, Names>;
-    toResolved<const Deps extends ReadonlyArray<InjectableDependency>>(factory: (...args: {
-        [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]>;
-    }) => Value, deps: Deps): BindingBuilder<Value, Names>;
-    toResolvedAsync<const Deps extends ReadonlyArray<InjectableDependency>>(factory: (...args: {
-        [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]>;
-    }) => Promise<Value>, deps: Deps): BindingBuilder<Value, Names>;
-    toAlias(target: Token<Value> | Constructor<Value>): AliasBindingBuilder<Names>;
-}
-/**
- * The scope-selection step of the fluent chain.
+ * @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 interface BindingBuilder<Value, Names extends string = string> extends SlotConstrainedBuilder<Names> {
-    singleton(): SingletonBindingBuilder<Value>;
-    transient(): TransientBindingBuilder<Value>;
-    scoped(): ScopedBindingBuilder<Value>;
-}
+export declare function effectiveBindingScope(binding: Binding): BindingScope;
 /**
- * The fluent chain for a constant — lifecycle hooks only, since the scope is fixed.
- *
- * @since 0.3.16-canary.0
- */
-export interface ConstantBindingBuilder<Value, Names extends string = string> extends SlotConstrainedBuilder<Names> {
-    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.
+ * Returns a process-unique identifier for a new binding.
  *
  * @since 0.3.16-canary.0
  */
-export interface AliasBindingBuilder<Names extends string = string> extends SlotConstrainedBuilder<Names> {
-}
+export declare function generateBindingId(): BindingIdentifier;
 /**
- * The fluent chain after `singleton()`, where both lifecycle hooks stay available.
+ * The stamp of a binding whose activation need has not been computed under the current versions.
  *
- * @since 0.3.16-canary.0
+ * @since 0.11.0
  */
-export interface SingletonBindingBuilder<Value> {
-    onActivation(fn: ActivationHandler<Value>): this;
-    onDeactivation(fn: DeactivationHandler<Value>): this;
-    id(): BindingIdentifier;
-}
+export declare const NO_ACTIVATION_STAMP = -1;
 /**
- * The fluent chain after `transient()`, where activation is the one lifecycle hook offered.
+ * Drops the memoized resolution frame, for a scope change that alters what the frame reports.
  *
- * @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.
+ * @remarks The frame derives from `scope` and `slot`; the slot is final once the binding registers, so
+ * only a scope written in place on the registered object clears it.
  *
- * @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
+ * @since 0.5.0-canary.9
  */
-export interface SingletonLifecycleBuilder<Value> {
-    onActivation(fn: ActivationHandler<Value>): this;
-    onDeactivation(fn: DeactivationHandler<Value>): this;
-    id(): BindingIdentifier;
-}
+export declare function clearBindingFrame<Value>(binding: Binding<Value>): void;
 export {};

package/dist/core/binding.js

@@ -36,6 +36,24 @@ export function bindingSlotEquals(left, right) {
     }
     return true;
 }
+/**
+ * Returns the slot with one criterion added, replacing any earlier criterion of the same key.
+ *
+ * @remarks One criterion per key: re-tagging a key replaces it rather than asking for both values.
+ *
+ * @since 0.11.0
+ */
+export function withSlotCriterion(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);
+}
 /**
  * Cached singleton absent — distinguishes "not resolved yet" from a cached `undefined`.
  *
@@ -52,6 +70,22 @@ export const NO_INSTANCE = Symbol("di:no-instance");
  * @since 0.3.16-canary.0
  */
 export const DEFAULT_BINDING_SLOT = { name: undefined, tags: Object.freeze([]), keyMask: NO_TAG_KEYS };
+/**
+ * Renders a tag value for a diagnostic, never throwing.
+ *
+ * @remarks A tag value is caller data — a bigint, a null-prototype object, a throwing `toString` —
+ * so stringifying it must not become the error that masks the real one.
+ *
+ * @since 0.11.0
+ */
+export function stringifyTagValue(value) {
+    try {
+        return String(value);
+    }
+    catch {
+        return "<unprintable>";
+    }
+}
 /**
  * Formats a slot for diagnostics — `default`, or its `name:`/`tag:` parts.
  *
@@ -70,10 +104,22 @@ export function bindingSlotToString(slot) {
         if (criterion.key === slotName) {
             continue;
         }
-        parts.push(`tag:${criterion.key.name}=${String(criterion.value)}`);
+        parts.push(`tag:${criterion.key.name}=${stringifyTagValue(criterion.value)}`);
     }
     return parts.join(",");
 }
+/**
+ * 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;
+}
 // ── ID generation ────────────────────────────────────────────────────────────────────────────────────────────────────
 let bindingIdCounter = 0;
 /**
@@ -86,29 +132,20 @@ export function generateBindingId() {
     return bindingIdCounter;
 }
 /**
- * Narrows a registered binding to its predicate for the registry to rewrite.
- *
- * @since 0.10.0
- */
-export function writablePredicate(binding) {
-    return binding;
-}
-/**
- * Narrows a registered binding to its membership flag for the registry to set.
+ * The stamp of a binding whose activation need has not been computed under the current versions.
  *
- * @since 0.10.0
+ * @since 0.11.0
  */
-export function writableMembership(binding) {
-    return binding;
-}
+export const NO_ACTIVATION_STAMP = -1;
 /**
- * Drops the memoized resolution frame, for a refinement that changes what the frame reports.
+ * Drops the memoized resolution frame, for a scope change that alters what the frame reports.
  *
- * @remarks The frame derives from `scope` and `slot`, both of which a chain now writes in place on
- * the registered object, so every such refinement clears it.
+ * @remarks The frame derives from `scope` and `slot`; the slot is final once the binding registers, so
+ * only a scope written in place on the registered object clears it.
  *
  * @since 0.5.0-canary.9
  */
 export function clearBindingFrame(binding) {
     binding.frame = undefined;
+    binding.rootContext = undefined;
 }

package/dist/core/module.d.ts

@@ -1,11 +1,12 @@
-import type { BindToBuilder } from "#core/binding";
+import type { BindToBuilder } from "#core/binding-builders";
+import type { BindingDeclaration, DeclaredBinding } from "#core/binding-declaration";
 import type { Token } from "#core/token";
 import type { Constructor } from "#core/types";
 declare const SYNC_MODULE_BRAND: unique symbol;
 declare const ASYNC_MODULE_BRAND: unique symbol;
 /**
- * Key for the module's setup callback. A symbol (not exported from the package root)
- * keeps the container-only member out of consumer-facing autocomplete entirely.
+ * Key for what a module applies when it loads: its setup callback, or a declared module's
+ * declarations. A symbol (not exported from the package root) keeps it out of autocomplete.
  *
  * @since 0.5.0-canary.7
  */
@@ -18,7 +19,7 @@ export declare const MODULE_SETUP: unique symbol;
 export interface SyncModule {
     readonly name: string;
     readonly [SYNC_MODULE_BRAND]: true;
-    readonly [MODULE_SETUP]: (builder: ModuleBuilder) => void;
+    readonly [MODULE_SETUP]: ((builder: ModuleBuilder) => void) | ReadonlyArray<DeclaredBinding>;
 }
 /**
  * A named group of bindings whose setup is async, applied via `loadAsync()`.
@@ -55,6 +56,7 @@ export interface AsyncModuleBuilder {
  */
 export declare const SyncModule: {
     create(name: string, setup: (builder: ModuleBuilder) => void): SyncModule;
+    fromBindings(name: string, declarations: ReadonlyArray<BindingDeclaration>): SyncModule;
 };
 /**
  * The companion factory that creates `AsyncModule` values.
@@ -65,12 +67,13 @@ export declare const AsyncModule: {
     create(name: string, setup: (builder: AsyncModuleBuilder) => Promise<void>): AsyncModule;
 };
 /**
- * The unified module factory — `create` for sync modules, `createAsync` for async ones.
+ * The unified module factory — `create` and `fromBindings` for sync modules, `createAsync` for async ones.
  *
  * @since 0.3.16-canary.0
  */
 export declare const Module: {
     create(name: string, setup: (builder: ModuleBuilder) => void): SyncModule;
+    fromBindings(name: string, declarations: ReadonlyArray<BindingDeclaration>): SyncModule;
     createAsync(name: string, setup: (builder: AsyncModuleBuilder) => Promise<void>): AsyncModule;
 };
 /**

package/dist/core/module.js

@@ -1,9 +1,10 @@
+import { asDeclaredBinding } from "#core/binding-declaration";
 // ── Branded types (runtime symbols for branding) ─────────────────────────────────────────────────────────────────────
 const SYNC_MODULE_BRAND = Symbol("di:sync-module");
 const ASYNC_MODULE_BRAND = Symbol("di:async-module");
 /**
- * Key for the module's setup callback. A symbol (not exported from the package root)
- * keeps the container-only member out of consumer-facing autocomplete entirely.
+ * Key for what a module applies when it loads: its setup callback, or a declared module's
+ * declarations. A symbol (not exported from the package root) keeps it out of autocomplete.
  *
  * @since 0.5.0-canary.7
  */
@@ -22,6 +23,16 @@ export const SyncModule = {
             [MODULE_SETUP]: setup,
         };
     },
+    fromBindings(name, declarations) {
+        // Copied, so a later write to the caller's list cannot change what the module loads. Not frozen:
+        // every load walks this list, and V8 reads a frozen array's elements on a slower path.
+        const declared = declarations.map((declaration, index) => asDeclaredBinding(declaration, name, index));
+        return {
+            name,
+            [SYNC_MODULE_BRAND]: true,
+            [MODULE_SETUP]: declared,
+        };
+    },
 };
 /**
  * The companion factory that creates `AsyncModule` values.
@@ -39,7 +50,7 @@ export const AsyncModule = {
 };
 // ── Module — unified API ─────────────────────────────────────────────────────────────────────────────────────────────
 /**
- * The unified module factory — `create` for sync modules, `createAsync` for async ones.
+ * The unified module factory — `create` and `fromBindings` for sync modules, `createAsync` for async ones.
  *
  * @since 0.3.16-canary.0
  */
@@ -47,6 +58,9 @@ export const Module = {
     create(name, setup) {
         return SyncModule.create(name, setup);
     },
+    fromBindings(name, declarations) {
+        return SyncModule.fromBindings(name, declarations);
+    },
     createAsync(name, setup) {
         return AsyncModule.create(name, setup);
     },

package/dist/core/registry.d.ts

@@ -1,11 +1,9 @@
 import type { Binding } from "#core/binding";
 import type { BindingTag } from "#core/tag";
 import type { Token } from "#core/token";
-import type { BindingConstraint, BindingIdentifier, Constructor } from "#core/types";
+import type { BindingIdentifier, Constructor } from "#core/types";
 /**
- * One container's binding store, indexed by token, binding id, and slot for fast lookup.
- *
- * @since 0.3.16-canary.0
+ * @since 0.11.0
  */
 export declare class BindingRegistry {
     #private;
@@ -13,6 +11,8 @@ export declare class BindingRegistry {
     get version(): number;
     /** Whether a constant has ever been registered here, and so whether teardown has anything to sweep. */
     get hasHeldConstantBinding(): boolean;
+    /** Whether an alias has ever been registered here, and so whether a candidate list can hold one. */
+    get hasHeldAlias(): boolean;
     /** Whether the deferred tagged-slot index has had to be built. */
     get isTaggedIndexBuilt(): boolean;
     /** Whether an id-keyed operation has had to build the id index. */
@@ -49,8 +49,6 @@ export declare class BindingRegistry {
      * to ask, and a lone binding's one-element list is never materialised here.
      */
     getRecorded(token: Token<unknown> | Constructor): ReadonlyArray<Binding>;
-    /** How many bindings a token holds, without materialising a lone binding's list. */
-    countBindings(token: Token<unknown> | Constructor): number;
     /** Get binding by ID. */
     getById(id: BindingIdentifier): Binding | undefined;
     /** Check if any binding exists for token. */
@@ -59,8 +57,6 @@ export declare class BindingRegistry {
     allBindings(): ReadonlyArray<Binding>;
     /** Remove all bindings. Returns all removed. */
     clear(): ReadonlyArray<Binding>;
-    /** Whether a slot-based binding currently occupies `binding`'s slot, so adding it would displace. */
-    hasSlotOccupant(binding: Binding): boolean;
     /**
      * The binding indexed under one criterion.
      *
@@ -77,30 +73,23 @@ export declare class BindingRegistry {
      * against the request — first-criterion bucketing only guarantees each candidate appears once.
      */
     getMultiTagged(token: Token<unknown> | Constructor, criterion: BindingTag): ReadonlyArray<Binding> | undefined;
-    /** A token's lone default-slot binding — the first read of every synchronous resolve. */
-    getFastDefault(token: Token<unknown> | Constructor): Binding | undefined;
     /**
-     * Takes a live binding out of every index, lets `rewrite` change its slot or predicate, and reports
-     * whether it was live; the caller registers it again with `add`.
+     * Whether any binding for the token carries a `when()` predicate.
      *
-     * @remarks The binding keeps its object and its id, so the id index needs no touch and nothing
-     * that holds the object has to be told. `false` means the binding was unbound or displaced since
-     * it registered, and a refinement must not resurrect it.
-     */
-    reslot(binding: Binding, rewrite: () => void): boolean;
-    /**
-     * Marks a live binding as a collection member in place, moving it out of the lone map: a member is
-     * never the token's lone default answer, and nothing else indexes on membership.
+     * @remarks Only a token that keeps a record can hold a predicate — a lone binding is default-slot
+     * with none — so an index fast lane consults this to decline to full selection when the
+     * more-specific rule's predicate step could apply.
      */
-    setMany(binding: Binding): void;
+    hasPredicateCandidate(token: Token<unknown> | Constructor): boolean;
+    /** The binding holding a token's default slot — lone or recorded — or `undefined` when none does. */
+    getDefaultSlotBinding(token: Token<unknown> | Constructor): Binding | undefined;
     /**
-     * Adds a predicate to a live binding in place.
+     * The token's default-slot alias, which forwards a request's criteria to its target, or `undefined`.
      *
-     * @remarks Only ever narrows — `when()` composes with any existing predicate — so the argument is
-     * never absent. Nothing indexes on the predicate, so the binding object and its id stay; a lone
-     * binding moves to a record because the lone map holds default-slot bindings with no predicate.
+     * @remarks A registry that never held an alias answers without probing, so a request missing every slot of a
+     * token pays for forwarding only where forwarding can happen.
      */
-    setPredicate(binding: Binding, predicate: BindingConstraint): void;
-    /** Summarize available slot strings for a token (for error messages). */
-    availableSlotStrings(token: Token<unknown> | Constructor): Array<string>;
+    defaultSlotAlias(token: Token<unknown> | Constructor): Binding | undefined;
+    /** A token's lone default-slot binding — the first read of every synchronous resolve. */
+    getFastDefault(token: Token<unknown> | Constructor): Binding | undefined;
 }