@codefast/di 0.5.0-canary.7 → 0.5.0-canary.8

package/src/binding.ts

@@ -40,6 +40,13 @@ export function bindingSlotEquals(left: BindingSlot, right: BindingSlot): boolea
   return true;
 }
 
+/**
+ * Cached singleton absent — distinguishes "not resolved yet" from a cached `undefined`.
+ *
+ * @since 0.5.0-canary.8
+ */
+export const NO_INSTANCE: unique symbol = Symbol("di:no-instance");
+
 /**
  * @since 0.3.16-canary.0
  */
@@ -67,12 +74,10 @@ export function bindingSlotToString(slot: BindingSlot): string {
 interface BindingBase<Value> {
   readonly id: BindingIdentifier;
   /**
-   * True while this binding's factory is on the sync resolution stack. The sync resolver marks
-   * it on enter and clears it on exit, making cycle detection an O(1) field read with no hashing,
-   * no path scan, and no side table. Sync resolution is single-threaded, so the flag is exactly
-   * path membership; the async lane keeps its own per-path check because chains can interleave.
+   * True while this binding's factory is on the sync resolution stack — the sync lane's cycle check.
    *
-   * @remarks Resolver-owned bookkeeping — `registry.add` normalizes it, so callers never set it.
+   * @remarks Resolver-owned bookkeeping; callers never set it. See `ARCHITECTURE.md` for why the
+   * sync and async lanes detect cycles differently.
    */
   inFlight?: boolean | undefined;
   /**
@@ -83,6 +88,13 @@ interface BindingBase<Value> {
    * @remarks Resolver-owned bookkeeping — `registry.add` normalizes it, so callers never set it.
    */
   frame?: ResolutionFrame | undefined;
+  /**
+   * Cached singleton instance, or {@link NO_INSTANCE}.
+   *
+   * @remarks A binding belongs to exactly one container, so its singleton slot is per-binding —
+   * a field read replaces a keyed lookup on the hottest resolve shape there is.
+   */
+  instance?: unknown;
   readonly token: Token<Value> | Constructor<Value>;
   readonly slot: BindingSlot;
   readonly predicate?: ((ctx: ConstraintContext) => boolean) | undefined;
@@ -204,6 +216,93 @@ export function generateBindingId(): BindingIdentifier {
   return String(++bindingIdCounter) as BindingIdentifier;
 }
 
+// ── Construction ──────────────────────────────────────────────────────────────
+
+// Superset of every kind's fields, so one literal can copy any binding shape.
+/** Union of every key any binding kind declares — `keyof` a union would give the intersection. */
+type BindingFieldName = Binding<unknown> extends infer Kind ? (Kind extends unknown ? keyof Kind : never) : never;
+
+/**
+ * Completeness guard for {@link createBinding}'s literal.
+ *
+ * @remarks The literal is `satisfies` this, so a field added to any binding kind that the literal
+ * forgets to write is a compile error rather than a binding silently missing it.
+ */
+type ConstructedBindingFields = Record<BindingFieldName, unknown>;
+
+type BindingFieldSuperset = {
+  readonly kind: Binding["kind"];
+  readonly instance?: unknown;
+  readonly scope?: unknown;
+  readonly target?: unknown;
+  readonly factory?: unknown;
+  readonly deps?: unknown;
+  readonly value?: unknown;
+  readonly onActivation?: unknown;
+  readonly onDeactivation?: unknown;
+};
+
+/**
+ * The single construction site for bindings — one literal, one V8 hidden class.
+ *
+ * @see `ARCHITECTURE.md` — why the field order and the single site are load-bearing.
+ *
+ * @param source - the kind-specific payload, or an existing binding to re-slot
+ * @param id - reuse a caller's id to keep a fluent chain's `id()` stable across refinements
+ *
+ * @since 0.5.0-canary.8
+ */
+export function createBinding<Value>(
+  source: PartialBinding<Value> | Binding<Value>,
+  token: Token<Value> | Constructor<Value>,
+  slot: BindingSlot,
+  predicate: ((ctx: ConstraintContext) => boolean) | undefined,
+  id: BindingIdentifier = generateBindingId(),
+): Binding<Value> {
+  const fields = source as BindingFieldSuperset;
+  return {
+    kind: fields.kind,
+    id,
+    inFlight: false,
+    frame: undefined,
+    instance: (source as { instance?: unknown }).instance ?? NO_INSTANCE,
+    token,
+    slot,
+    predicate,
+    scope: fields.scope,
+    target: fields.target,
+    factory: fields.factory,
+    deps: fields.deps,
+    value: fields.value,
+    onActivation: fields.onActivation,
+    onDeactivation: fields.onDeactivation,
+  } satisfies ConstructedBindingFields as Binding<Value>;
+}
+
+/**
+ * Writable view of the only fields a fluent chain may refine after registration.
+ *
+ * @remarks No registry index is keyed on these, so a builder that owns the registered object
+ * can write them directly instead of re-registering. `token`, `slot`, `predicate` and `id`
+ * are excluded on purpose — changing those means re-indexing.
+ *
+ * @since 0.5.0-canary.8
+ */
+export interface RefinableBindingFields<Value> {
+  onActivation: ActivationHandler<Value> | undefined;
+  onDeactivation: DeactivationHandler<Value> | undefined;
+  scope: BindingScope;
+}
+
+/**
+ * Narrows a registered binding to the fields a fluent chain may still refine.
+ *
+ * @since 0.5.0-canary.8
+ */
+export function refinableFields<Value>(binding: Binding<Value>): RefinableBindingFields<Value> {
+  return binding as RefinableBindingFields<Value>;
+}
+
 // ── Builder interfaces ────────────────────────────────────────────────────────
 
 /**

package/src/constructor-type.ts

@@ -1,9 +1,8 @@
 /**
- * A class (newable) that produces `Value`. Rest parameters are `never[]` so
- * real classes with typed constructors remain assignable under
- * `strictFunctionTypes` (unlike `unknown[]`, which is not assignable from
- * narrower parameter types). Runtime construction still uses the real shape;
- * this alias is the DI “class token” surface only.
+ * A class token: newable, producing `Value`.
+ *
+ * @remarks Rest parameters are `never[]` so classes with typed constructors stay assignable under
+ * `strictFunctionTypes`. Construction uses the real shape; this alias is the token surface only.
  *
  * @since 0.3.16-canary.0
  */