@codefast/di 0.10.1 → 0.11.0

package/dist/core/binding-declaration.js

@@ -0,0 +1,186 @@
+import { DEFAULT_BINDING_SLOT, withSlotCriterion } from "#core/binding";
+import { slotName } from "#core/tag";
+import { tokenName } from "#core/token";
+import { InvalidBindingDeclarationError, ManyBindingSlotError, SelfBindingRequiresClassError } from "#errors/errors";
+import { normalizeToDescriptor } from "#injection/descriptor";
+// Only this module can mint the symbol, so an entry carrying it was made by `binding()`.
+const declarationBrand = Symbol("di:binding-declaration");
+/** Whether an entry carries the brand `binding()` alone sets, and so every field a declaration holds. */
+function isDeclaredBinding(entry) {
+    // Plain JavaScript can hand over anything, `null` included.
+    return typeof entry === "object" && entry !== null && entry[declarationBrand] === true;
+}
+/**
+ * Narrows a list entry to the declaration it must be, or throws for anything `binding()` did not make.
+ *
+ * @since 0.11.0
+ */
+export function asDeclaredBinding(entry, moduleName, index) {
+    if (!isDeclaredBinding(entry)) {
+        throw new InvalidBindingDeclarationError(`${moduleName}[${String(index)}]`, "the entry is not a declaration made by binding()");
+    }
+    return entry;
+}
+const STRATEGIES = new Set([
+    "to",
+    "toSelf",
+    "toConstantValue",
+    "toDynamic",
+    "toDynamicAsync",
+    "toResolved",
+    "toResolvedAsync",
+    "toAlias",
+]);
+const DEFINITION_KEYS = new Set([
+    ...STRATEGIES,
+    "deps",
+    "whenNamed",
+    "whenTagged",
+    "when",
+    "many",
+    "scope",
+    "onActivation",
+    "onDeactivation",
+]);
+const SCOPES = new Set(["singleton", "transient", "scoped"]);
+function isStrategy(key) {
+    return STRATEGIES.has(key);
+}
+/** `Array.isArray` for a read-only list, which the built-in guard does not narrow. */
+function isReadonlyList(value) {
+    return Array.isArray(value);
+}
+/** The strategy key a definition names, when it names exactly one. */
+function strategyOf(name, definition) {
+    let strategy;
+    for (const key of Object.keys(definition)) {
+        if (!DEFINITION_KEYS.has(key)) {
+            throw new InvalidBindingDeclarationError(name, `\`${key}\` is not a definition key`);
+        }
+        if (isStrategy(key)) {
+            if (strategy !== undefined) {
+                throw new InvalidBindingDeclarationError(name, `it names two strategies, \`${strategy}\` and \`${key}\``);
+            }
+            strategy = key;
+        }
+    }
+    if (strategy === undefined) {
+        throw new InvalidBindingDeclarationError(name, "it names no strategy");
+    }
+    return strategy;
+}
+/** The slot `whenNamed` then each `whenTagged` criterion builds, one chain step at a time. */
+function slotOf(definition) {
+    let slot = DEFAULT_BINDING_SLOT;
+    if (definition.whenNamed !== undefined) {
+        slot = withSlotCriterion(slot, slotName.of(definition.whenNamed));
+    }
+    const tagged = definition.whenTagged;
+    if (tagged !== undefined) {
+        for (const criterion of isReadonlyList(tagged) ? tagged : [tagged]) {
+            slot = withSlotCriterion(slot, criterion);
+        }
+    }
+    return slot;
+}
+// The value type is erased here, once: the overloads above are what a caller is checked against.
+/**
+ * @since 0.11.0
+ */
+export function binding(key, definition) {
+    const name = tokenName(key);
+    const strategy = strategyOf(name, definition);
+    let kind;
+    let target;
+    let factory;
+    let value;
+    let deps;
+    switch (strategy) {
+        case "to":
+            kind = "class";
+            target = definition.to;
+            break;
+        case "toSelf":
+            // Plain JavaScript can pass `toSelf: false`; the type admits `true` alone.
+            if (definition.toSelf !== true) {
+                throw new InvalidBindingDeclarationError(name, "`toSelf` takes `true`");
+            }
+            if (typeof key !== "function") {
+                throw new SelfBindingRequiresClassError(name);
+            }
+            kind = "class";
+            target = key;
+            break;
+        case "toConstantValue":
+            kind = "constant";
+            value = definition.toConstantValue;
+            break;
+        case "toDynamic":
+            kind = "dynamic";
+            factory = definition.toDynamic;
+            break;
+        case "toDynamicAsync":
+            kind = "dynamic-async";
+            factory = definition.toDynamicAsync;
+            break;
+        case "toResolved":
+        case "toResolvedAsync": {
+            const declaredDeps = definition.deps;
+            if (!isReadonlyList(declaredDeps)) {
+                throw new InvalidBindingDeclarationError(name, `\`${strategy}\` needs \`deps\`, an array`);
+            }
+            kind = strategy === "toResolved" ? "resolved" : "resolved-async";
+            factory = strategy === "toResolved" ? definition.toResolved : definition.toResolvedAsync;
+            deps = declaredDeps.map((dependency) => normalizeToDescriptor(dependency));
+            break;
+        }
+        case "toAlias":
+            kind = "alias";
+            target = definition.toAlias;
+            break;
+    }
+    if (deps === undefined && definition.deps !== undefined) {
+        throw new InvalidBindingDeclarationError(name, "`deps` belongs to `toResolved` or `toResolvedAsync`");
+    }
+    let scope = kind === "constant" ? "singleton" : "transient";
+    if (definition.scope !== undefined) {
+        if (kind === "constant" || kind === "alias") {
+            throw new InvalidBindingDeclarationError(name, `\`${strategy}\` takes no \`scope\``);
+        }
+        if (!SCOPES.has(definition.scope)) {
+            throw new InvalidBindingDeclarationError(name, "`scope` is not one of singleton, transient or scoped");
+        }
+        scope = definition.scope;
+    }
+    const { onActivation, onDeactivation } = definition;
+    if (kind === "alias" && (onActivation !== undefined || onDeactivation !== undefined)) {
+        throw new InvalidBindingDeclarationError(name, "`toAlias` takes no lifecycle hook");
+    }
+    if (onDeactivation !== undefined && kind !== "constant" && scope !== "singleton") {
+        throw new InvalidBindingDeclarationError(name, '`onDeactivation` needs `scope: "singleton"`');
+    }
+    if (definition.many !== undefined && definition.many !== true) {
+        throw new InvalidBindingDeclarationError(name, "`many` takes `true`");
+    }
+    const isMany = definition.many === true;
+    const slot = slotOf(definition);
+    if (isMany && slot.tags.length !== 0) {
+        throw new ManyBindingSlotError(name);
+    }
+    const declared = {
+        [declarationBrand]: true,
+        token: key,
+        kind,
+        scope,
+        target,
+        factory,
+        value,
+        deps,
+        slot,
+        predicate: definition.when,
+        isMany,
+        activationHook: onActivation,
+        deactivationHook: onDeactivation,
+    };
+    return declared;
+}

package/dist/core/binding.d.ts

@@ -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,28 @@ 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;
+    /**
+     * Where the binding stands in registration order, or {@link UNREGISTERED_ORDER} before its first add.
+     *
+     * @remarks Registry-owned: stamped by the first `add` and kept through every re-slot and restore, so a
+     * binding taken out and put back returns to its place rather than behind later registrations.
+     */
+    registrationOrder: number;
     /**
      * Cached singleton instance, or {@link NO_INSTANCE}.
      *
@@ -222,6 +262,18 @@ export interface MembershipField {
  * @since 0.10.0
  */
 export declare function writableMembership(binding: Binding): MembershipField;
+/**
+ * The stamp of a binding whose activation need has not been computed under the current versions.
+ *
+ * @since 0.11.0
+ */
+export declare const NO_ACTIVATION_STAMP = -1;
+/**
+ * The registration order of a binding no registry has added yet.
+ *
+ * @since 0.11.0
+ */
+export declare const UNREGISTERED_ORDER = -1;
 /**
  * Drops the memoized resolution frame, for a refinement that changes what the frame reports.
  *

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,7 +104,7 @@ 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(",");
 }
@@ -101,6 +135,18 @@ export function writablePredicate(binding) {
 export function writableMembership(binding) {
     return binding;
 }
+/**
+ * The stamp of a binding whose activation need has not been computed under the current versions.
+ *
+ * @since 0.11.0
+ */
+export const NO_ACTIVATION_STAMP = -1;
+/**
+ * The registration order of a binding no registry has added yet.
+ *
+ * @since 0.11.0
+ */
+export const UNREGISTERED_ORDER = -1;
 /**
  * Drops the memoized resolution frame, for a refinement that changes what the frame reports.
  *
@@ -111,4 +157,5 @@ export function writableMembership(binding) {
  */
 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 { 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

@@ -3,9 +3,7 @@ import type { BindingTag } from "#core/tag";
 import type { Token } from "#core/token";
 import type { BindingConstraint, 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;
@@ -49,8 +47,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. */
@@ -77,6 +73,16 @@ 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;
+    /**
+     * Whether any binding for the token carries a `when()` predicate.
+     *
+     * @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.
+     */
+    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;
     /** A token's lone default-slot binding — the first read of every synchronous resolve. */
     getFastDefault(token: Token<unknown> | Constructor): Binding | undefined;
     /**
@@ -101,6 +107,4 @@ export declare class BindingRegistry {
      * binding moves to a record because the lone map holds default-slot bindings with no predicate.
      */
     setPredicate(binding: Binding, predicate: BindingConstraint): void;
-    /** Summarize available slot strings for a token (for error messages). */
-    availableSlotStrings(token: Token<unknown> | Constructor): Array<string>;
 }