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

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,14 +74,14 @@ 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 executing on the current synchronous call stack.
    *
-   * @remarks Resolver-owned bookkeeping — `registry.add` normalizes it, so callers never set it.
+   * @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.
    */
-  inFlight?: boolean | undefined;
+  inFlight: boolean;
   /**
    * Memoized resolution frame for this binding. Its contents derive only from immutable binding
    * fields, so it is computed once on first resolve and reused instead of a per-resolver Map
@@ -83,6 +90,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;
@@ -90,74 +104,76 @@ interface BindingBase<Value> {
 
 type BindingBaseKeys = keyof BindingBase<unknown>;
 
+/**
+ * The lifecycle hooks every kind but `alias` may carry.
+ *
+ * @remarks Declared as **methods**, not function-typed properties, so their parameters compare
+ * bivariantly and `Binding<Value>` stays assignable to `Binding`. The engine erases the value type at
+ * every lane boundary regardless; the public `ActivationHandler` / `DeactivationHandler` keep strict
+ * checking, which is where a user's handler is actually verified. Not `readonly`: a fluent chain
+ * refines both in place — see {@link RefinableBindingFields}.
+ */
+interface BindingLifecycleHooks<Value> {
+  onActivation?(ctx: ResolutionContext, instance: Value): Value | Promise<Value>;
+  onDeactivation?(instance: Value): void | Promise<void>;
+}
+
 // ── Binding kinds ─────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
  */
-export interface ClassBinding<Value> extends BindingBase<Value> {
+export interface ClassBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
   readonly kind: "class";
   readonly target: Constructor<Value>;
   readonly scope: BindingScope;
-  readonly onActivation?: ActivationHandler<Value> | undefined;
-  readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 
 /**
  * @since 0.3.16-canary.0
  */
-export interface DynamicBinding<Value> extends BindingBase<Value> {
+export interface DynamicBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
   readonly kind: "dynamic";
   readonly factory: (ctx: ResolutionContext) => Value;
   readonly scope: BindingScope;
-  readonly onActivation?: ActivationHandler<Value> | undefined;
-  readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 
 /**
  * @since 0.3.16-canary.0
  */
-export interface DynamicAsyncBinding<Value> extends BindingBase<Value> {
+export interface DynamicAsyncBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
   readonly kind: "dynamic-async";
   readonly factory: (ctx: ResolutionContext) => Promise<Value>;
   readonly scope: BindingScope;
-  readonly onActivation?: ActivationHandler<Value> | undefined;
-  readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 
 /**
  * @since 0.3.16-canary.0
  */
-export interface ResolvedBinding<Value> extends BindingBase<Value> {
+export interface ResolvedBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
   readonly kind: "resolved";
   readonly factory: (...args: Array<unknown>) => Value;
   readonly deps: ReadonlyArray<InjectionDescriptor>;
   readonly scope: BindingScope;
-  readonly onActivation?: ActivationHandler<Value> | undefined;
-  readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 
 /**
  * @since 0.3.16-canary.0
  */
-export interface ResolvedAsyncBinding<Value> extends BindingBase<Value> {
+export interface ResolvedAsyncBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
   readonly kind: "resolved-async";
   readonly factory: (...args: Array<unknown>) => Promise<Value>;
   readonly deps: ReadonlyArray<InjectionDescriptor>;
   readonly scope: BindingScope;
-  readonly onActivation?: ActivationHandler<Value> | undefined;
-  readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 
 /**
  * @since 0.3.16-canary.0
  */
-export interface ConstantBinding<Value> extends BindingBase<Value> {
+export interface ConstantBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
   readonly kind: "constant";
   readonly value: Value;
   readonly scope: "singleton";
-  readonly onActivation?: ActivationHandler<Value> | undefined;
-  readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 
 /**
@@ -166,6 +182,13 @@ export interface ConstantBinding<Value> extends BindingBase<Value> {
 export interface AliasBinding<Value> extends BindingBase<Value> {
   readonly kind: "alias";
   readonly target: Token<Value> | Constructor<Value>;
+  /**
+   * Always `transient` — an alias defers scoping to the binding it points at.
+   *
+   * @remarks Declared so `scope` is present on every kind, which is what lets the engine read it
+   * as a plain field instead of testing for the one kind that lacks it.
+   */
+  readonly scope: "transient";
 }
 
 /**
@@ -204,6 +227,105 @@ 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: BindingScope;
+  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>;
+}
+
+/**
+ * Drops the memoized resolution frame, for a refinement that changes what the frame reports.
+ *
+ * @remarks `scope` is the only field a chain writes in place that the frame derives from — a
+ * re-slot builds a fresh binding, whose frame starts empty anyway.
+ *
+ * @since 0.5.0-canary.9
+ */
+export function clearBindingFrame<Value>(binding: Binding<Value>): void {
+  (binding as { frame: ResolutionFrame | undefined }).frame = undefined;
+}
+
 // ── 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
  */