@codefast/di 0.10.0 → 0.11.0

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

@@ -0,0 +1,120 @@
+/**
+ * A binding written as data: `binding()` checks a definition once and normalises it into the
+ * declaration a declared module files when it loads.
+ */
+import type { BindingSlot } from "#core/binding";
+import type { BindingTag } from "#core/tag";
+import type { Token } from "#core/token";
+import type { ActivationHandler, BindingConstraint, BindingKind, BindingScope, Constructor, DeactivationHandler, ResolutionContext } from "#core/types";
+import type { InjectableDependency, InjectionDescriptor, ResolvedDependencyValue } from "#injection/descriptor";
+type Never<Keys extends PropertyKey> = {
+    readonly [Key in Keys]?: never;
+};
+type StrategyKey = "to" | "toSelf" | "toConstantValue" | "toDynamic" | "toDynamicAsync" | "toResolved" | "toResolvedAsync" | "toAlias" | "deps";
+type ResolvedParameters<Deps extends ReadonlyArray<InjectableDependency>> = {
+    [Index in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[Index]>;
+};
+/** Where the binding sits: a name and criteria, or a collection member, which has no slot to take. */
+type SlotDefinition<Names extends string> = ({
+    readonly whenNamed?: Names | undefined;
+    readonly whenTagged?: BindingTag | ReadonlyArray<BindingTag> | undefined;
+} & Never<"many">) | ({
+    readonly many: true;
+} & Never<"whenNamed" | "whenTagged">);
+/** How long an instance lives, and the hooks that lifetime allows. */
+type LifetimeDefinition<Value> = {
+    readonly scope: "singleton";
+    readonly onActivation?: ActivationHandler<Value> | undefined;
+    readonly onDeactivation?: DeactivationHandler<Value> | undefined;
+} | ({
+    readonly scope?: "transient" | "scoped" | undefined;
+    readonly onActivation?: ActivationHandler<Value> | undefined;
+} & Never<"onDeactivation">);
+type BuiltDefinition<Value, Deps extends ReadonlyArray<InjectableDependency>> = ({
+    readonly to: Constructor<Value>;
+} & Never<Exclude<StrategyKey, "to">>) | ({
+    readonly toDynamic: (ctx: ResolutionContext) => Value;
+} & Never<Exclude<StrategyKey, "toDynamic">>) | ({
+    readonly toDynamicAsync: (ctx: ResolutionContext) => Promise<Value>;
+} & Never<Exclude<StrategyKey, "toDynamicAsync">>) | ({
+    readonly toResolved: (...args: ResolvedParameters<Deps>) => Value;
+    readonly deps: Deps;
+} & Never<Exclude<StrategyKey, "toResolved" | "deps">>) | ({
+    readonly toResolvedAsync: (...args: ResolvedParameters<Deps>) => Promise<Value>;
+    readonly deps: Deps;
+} & Never<Exclude<StrategyKey, "toResolvedAsync" | "deps">>);
+type ConstantDefinition<Value> = {
+    readonly toConstantValue: Value;
+    readonly onActivation?: ActivationHandler<Value> | undefined;
+    readonly onDeactivation?: DeactivationHandler<Value> | undefined;
+} & Never<Exclude<StrategyKey, "toConstantValue"> | "scope">;
+type AliasDefinition<Value> = {
+    readonly toAlias: Token<Value> | Constructor<Value>;
+} & Never<Exclude<StrategyKey, "toAlias"> | "scope" | "onActivation" | "onDeactivation">;
+type SelfDefinition<Value> = {
+    readonly toSelf: true;
+} & Never<Exclude<StrategyKey, "toSelf">> & LifetimeDefinition<Value> & SlotDefinition<string> & {
+    readonly when?: BindingConstraint | undefined;
+};
+/**
+ * One binding spelled with the fluent chain's vocabulary: a single strategy key, then the slot,
+ * `when`, `many`, `scope` and hooks that strategy allows.
+ *
+ * @typeParam Names - The slot names `whenNamed` accepts, the token's own.
+ * @typeParam Deps - The dependencies `toResolved` and `toResolvedAsync` infer their parameters from.
+ *
+ * @since 0.11.0
+ */
+export type BindingDefinition<Value, Names extends string = string, Deps extends ReadonlyArray<InjectableDependency> = ReadonlyArray<InjectableDependency>> = ((BuiltDefinition<Value, Deps> & LifetimeDefinition<Value>) | ConstantDefinition<Value> | AliasDefinition<Value>) & SlotDefinition<Names> & {
+    readonly when?: BindingConstraint | undefined;
+};
+declare const declarationBrand: unique symbol;
+/**
+ * A checked, normalised binding that `Module.fromBindings` groups into a declared module.
+ *
+ * @remarks Opaque: only `binding()` makes one, so a declared module that was built can always load.
+ *
+ * @since 0.11.0
+ */
+export interface BindingDeclaration {
+    readonly [declarationBrand]: true;
+}
+/**
+ * The runtime form of a `BindingDeclaration`: the binding fields a container copies into each binding it registers.
+ *
+ * @remarks Built at one site in `binding()`, so every declaration shares a hidden class.
+ *
+ * @since 0.11.0
+ */
+export interface DeclaredBinding extends BindingDeclaration {
+    readonly token: Token<unknown> | Constructor;
+    readonly kind: BindingKind;
+    readonly scope: BindingScope;
+    readonly target: unknown;
+    readonly factory: unknown;
+    readonly value: unknown;
+    readonly deps: ReadonlyArray<InjectionDescriptor> | undefined;
+    readonly slot: BindingSlot;
+    readonly predicate: BindingConstraint | undefined;
+    readonly isMany: boolean;
+    readonly activationHook: ActivationHandler<unknown> | undefined;
+    readonly deactivationHook: DeactivationHandler<unknown> | undefined;
+}
+/**
+ * Narrows a list entry to the declaration it must be, or throws for anything `binding()` did not make.
+ *
+ * @since 0.11.0
+ */
+export declare function asDeclaredBinding(entry: BindingDeclaration, moduleName: string, index: number): DeclaredBinding;
+/**
+ * Declares one binding for `Module.fromBindings`, checked against the fluent chain's rules where it is written.
+ *
+ * @remarks The key alone decides the value type and the slot names; the definition never widens them.
+ *
+ * @throws `InvalidBindingDeclarationError` for no strategy, several, or a key the strategy does not allow.
+ * @throws `ManyBindingSlotError` for a slot on a collection member.
+ * @throws `SelfBindingRequiresClassError` for `toSelf` on a key that is not a class.
+ */
+export declare function binding<Value, Names extends string, const Deps extends ReadonlyArray<InjectableDependency> = []>(key: Token<Value, Names>, definition: BindingDefinition<NoInfer<Value>, NoInfer<Names>, Deps>): BindingDeclaration;
+export declare function binding<Value, const Deps extends ReadonlyArray<InjectableDependency> = []>(key: Constructor<Value>, definition: BindingDefinition<NoInfer<Value>, string, Deps> | SelfDefinition<NoInfer<Value>>): BindingDeclaration;
+export {};

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-scope.d.ts

@@ -1,5 +1,5 @@
-import type { Binding } from "#/core/binding";
-import type { BindingScope } from "#/core/types";
+import type { Binding } from "#core/binding";
+import type { BindingScope } from "#core/types";
 /**
  * The scope a binding resolves under.
  *

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 { 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";
 /**
  * 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: `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.
+     * @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

@@ -1,4 +1,4 @@
-import { NO_TAG_KEYS, slotName, tagKeyMaskOf } from "#/core/tag";
+import { NO_TAG_KEYS, slotName, tagKeyMaskOf } from "#core/tag";
 /**
  * Builds a slot from its criterion set, deriving the name view and key mask.
  *
@@ -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/constraint-requirement.d.ts

@@ -1,5 +1,5 @@
 /** What a constraint needs to exist before it can ever match, so `validate()` can check for it. */
-import type { BindingConstraint } from "#/core/types";
+import type { BindingConstraint } from "#core/types";
 /**
  * Key the requirement is attached under.
  *

package/dist/core/module.d.ts

@@ -1,11 +1,12 @@
-import type { BindToBuilder } from "#/core/binding";
-import type { Token } from "#/core/token";
-import type { Constructor } from "#/core/types";
+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);
     },