@alloy-js/core 0.23.0-dev.1 → 0.23.0-dev.8

package/src/resource.ts

@@ -101,26 +101,35 @@ export function createResource<T, U>(
         }),
     );
   } else {
-    effect(() => {
-      let input: T;
-      if (isRef(getter)) {
-        input = getter.value;
-      } else {
-        input = getter();
-      }
-      const promise = (fetcher as (input: T) => Promise<U>)(input);
-      trackPromise(promise);
-      promise.then(
-        (result) => {
-          resource.data = result;
-          resource.loading = false;
-        },
-        (error) => {
-          resource.error = error;
-          resource.loading = false;
+    effect(
+      () => {
+        let input: T;
+        if (isRef(getter)) {
+          input = getter.value;
+        } else {
+          input = getter();
+        }
+        const promise = (fetcher as (input: T) => Promise<U>)(input);
+        trackPromise(promise);
+        promise.then(
+          (result) => {
+            resource.data = result;
+            resource.loading = false;
+          },
+          (error) => {
+            resource.error = error;
+            resource.loading = false;
+          },
+        );
+      },
+      undefined,
+      {
+        debug: {
+          name: "resource:fetch",
+          type: "resource",
         },
-      );
-    });
+      },
+    );
   }
 
   return resource;

package/src/scheduler.ts

@@ -1,4 +1,5 @@
 import { ReactiveEffect } from "@vue/reactivity";
+import { debug } from "./debug/index.js";
 
 export interface QueueJob {
   run(): void;
@@ -6,6 +7,10 @@ export interface QueueJob {
 const immediateQueue = new Set<QueueJob>();
 const queue = new Set<QueueJob>();
 const pendingPromises = new Set<Promise<any>>();
+let waitForSignalPromise: Promise<void> | null = null;
+let resolveWaitForSignal: (() => void) | null = null;
+let jobSignalPromise: Promise<void> | null = null;
+let resolveJobSignal: (() => void) | null = null;
 
 export function scheduler(immediate = false) {
   return function (this: ReactiveEffect) {
@@ -19,12 +24,17 @@ export function queueJob(job: QueueJob | (() => void), immediate = false) {
   if (typeof job === "function") {
     job = { run: job };
   }
-
   if (immediate) {
     immediateQueue.add(job);
   } else {
     queue.add(job);
   }
+
+  if (resolveJobSignal) {
+    resolveJobSignal();
+    resolveJobSignal = null;
+    jobSignalPromise = null;
+  }
 }
 
 /**
@@ -51,6 +61,33 @@ export function flushJobs() {
       "Asynchronous jobs were found but render was called synchronously. Use `renderAsync` instead.",
     );
   }
+
+  debug.render.flushJobsComplete();
+}
+
+export function waitForSignal(): Promise<void> {
+  if (!waitForSignalPromise) {
+    waitForSignalPromise = new Promise<void>((resolve) => {
+      resolveWaitForSignal = resolve;
+    });
+    pendingPromises.add(waitForSignalPromise);
+  }
+  return waitForSignalPromise;
+}
+
+export function signalSchedulerWait() {
+  if (resolveWaitForSignal) {
+    resolveWaitForSignal();
+    resolveWaitForSignal = null;
+  }
+  if (waitForSignalPromise) {
+    pendingPromises.delete(waitForSignalPromise);
+  }
+  waitForSignalPromise = null;
+}
+
+export function isWaitingForSignal() {
+  return waitForSignalPromise !== null;
 }
 
 export async function flushJobsAsync() {
@@ -67,9 +104,24 @@ export async function flushJobsAsync() {
       break;
     }
 
-    // Wait for all current promises to complete
-    await Promise.allSettled(Array.from(pendingPromises));
+    if (!jobSignalPromise) {
+      jobSignalPromise = new Promise<void>((resolve) => {
+        resolveJobSignal = resolve;
+      });
+    }
+
+    // Wait for either pending promises to complete or new jobs to arrive
+    await Promise.race([
+      Promise.allSettled(Array.from(pendingPromises)),
+      jobSignalPromise,
+    ]);
+
+    // Clear the job signal after each iteration so we create a new one next time
+    jobSignalPromise = null;
+    resolveJobSignal = null;
   }
+
+  debug.render.flushJobsComplete();
 }
 
 function takeJob() {

package/src/symbols/basic-symbol.ts

@@ -1,3 +1,4 @@
+import { createSymbol } from "../binder.js";
 import { OutputSymbol } from "./output-symbol.js";
 
 /**
@@ -16,7 +17,11 @@ export class BasicSymbol extends OutputSymbol {
 
   copy() {
     const options = this.getCopyOptions();
-    const copiedSymbol = new BasicSymbol(this.name, undefined, options);
+    const binder = this.binder;
+    const copiedSymbol = createSymbol(BasicSymbol, this.name, undefined, {
+      ...options,
+      binder,
+    });
     this.initializeCopy(copiedSymbol);
 
     return copiedSymbol;

package/src/symbols/decl.ts

@@ -1,4 +1,5 @@
 import { toRef } from "@vue/reactivity";
+import { createSymbol } from "../binder.js";
 import { useScope } from "../context/scope.js";
 import { Namekey } from "../refkey.js";
 import { createComponent } from "../runtime/component.js";
@@ -18,7 +19,10 @@ export function decl(namekey: Namekey) {
         `Cannot declare symbol in non-basic scope: ${currentScope.constructor.name}. Use a language-specific 'decl' function instead.`,
       );
     }
-    const symbol = new BasicSymbol(namekey, currentScope.symbols);
+    const binder = currentScope.binder;
+    const symbol = createSymbol(BasicSymbol, namekey, currentScope.symbols, {
+      binder,
+    });
 
     return toRef(symbol, "name");
   }, {});

package/src/symbols/output-scope.ts

@@ -1,5 +1,4 @@
 import {
-  effect,
   reactive,
   ReactiveFlags,
   shallowReactive,
@@ -11,8 +10,7 @@ import {
 import type { Binder } from "../binder.js";
 import { useBinder } from "../context/binder.js";
 import { inspect } from "../inspect.js";
-import { untrack } from "../reactivity.js";
-import { formatScope, trace, traceEffect, TracePhase } from "../tracer.js";
+import { effect, untrack } from "../reactivity.js";
 import { OutputDeclarationSpace, OutputSpace } from "./output-space.js";
 import { OutputSymbol } from "./output-symbol.js";
 
@@ -154,7 +152,7 @@ export abstract class OutputScope {
     return this.#binder;
   }
 
-  [ReactiveFlags.SKIP] = this;
+  [ReactiveFlags.SKIP] = true;
 
   constructor(
     name: string,
@@ -167,9 +165,20 @@ export abstract class OutputScope {
     this.#binder = options.binder ?? useBinder();
     this.#children = shallowReactive(new Set());
     this.#parent = parentScope;
-    effect(() => {
-      this.#setOwnerSymbol(options.ownerSymbol?.movedTo ?? options.ownerSymbol);
-    });
+    effect(
+      () => {
+        this.#setOwnerSymbol(
+          options.ownerSymbol?.movedTo ?? options.ownerSymbol,
+        );
+      },
+      undefined,
+      {
+        debug: {
+          name: "outputScope:ownerSymbol",
+          type: "symbol",
+        },
+      },
+    );
 
     if (this.#parent) {
       this.#parent.children.add(this);
@@ -184,12 +193,8 @@ export abstract class OutputScope {
       ]),
     );
 
+    // Notify binder so resolution tracking works even without createScope
     this.#binder?.notifyScopeCreated(this);
-
-    trace(TracePhase.scope.create, () => `${formatScope(this)}`);
-    traceEffect(TracePhase.scope.update, () => {
-      return `${formatScope(this)}`;
-    });
   }
 
   /**
@@ -215,6 +220,10 @@ export abstract class OutputScope {
     return this.#ownerSymbol;
   }
 
+  get debugInfo(): Record<string, unknown> {
+    return {};
+  }
+
   #setOwnerSymbol(value: OutputSymbol | undefined) {
     const old = this.#ownerSymbol;
     this.#ownerSymbol = value;

package/src/symbols/output-symbol.ts

@@ -12,17 +12,19 @@ import {
 } from "@vue/reactivity";
 import type { Binder } from "../binder.js";
 import { useBinder } from "../context/binder.js";
+import { debug, TracePhase } from "../debug/index.js";
 import { inspect } from "../inspect.js";
 import { NamePolicyGetter } from "../name-policy.js";
 import { untrack } from "../reactivity.js";
-import { Namekey, type Refkey } from "../refkey.js";
 import {
-  formatSymbol,
-  formatSymbolName,
-  trace,
-  traceEffect,
-  TracePhase,
-} from "../tracer.js";
+  isMemberRefkey,
+  isNamekey,
+  isSymbolRefkey,
+  Namekey,
+  toRefkey,
+  type Refkey,
+} from "../refkey.js";
+import { formatSymbolName } from "../tracer.js";
 import {
   OutputDeclarationSpace,
   OutputMemberSpace,
@@ -459,6 +461,10 @@ export abstract class OutputSymbol {
     return this.#isTyped;
   }
 
+  get debugInfo(): Record<string, unknown> {
+    return {};
+  }
+
   #namePolicy: NamePolicyGetter | undefined;
   get namePolicy() {
     return this.#namePolicy;
@@ -552,10 +558,7 @@ export abstract class OutputSymbol {
       ]),
     );
 
-    trace(TracePhase.symbol.create, () => `${formatSymbol(this)}`);
-    traceEffect(TracePhase.symbol.update, () => {
-      return `${formatSymbol(this)}`;
-    });
+    // Notify binder so resolution tracking works even without createSymbol
     this.#binder?.notifySymbolCreated(this);
   }
 
@@ -570,7 +573,7 @@ export abstract class OutputSymbol {
   }
 
   delete() {
-    trace(TracePhase.symbol.delete, () => `${formatSymbolName(this)}`);
+    debug.trace(TracePhase.symbol.delete, () => `${formatSymbolName(this)}`);
     if (this.#spaces) {
       this.#spaces.forEach((space) => space.delete(this));
     }
@@ -677,3 +680,21 @@ export abstract class OutputSymbol {
     return untrack(() => `${this.constructor.name} "${this.name}"[${this.id}]`);
   }
 }
+
+function _formatRefkey(refkey: Refkey): string {
+  if (isNamekey(refkey)) {
+    return `name:${refkey.name}`;
+  }
+  if (isMemberRefkey(refkey)) {
+    const base = _formatRefkey(toRefkey(refkey.base));
+    const member =
+      typeof refkey.member === "string" ?
+        refkey.member
+      : _formatRefkey(toRefkey(refkey.member));
+    return `member:${base}.${member}`;
+  }
+  if (isSymbolRefkey(refkey)) {
+    return `key:${refkey.key}`;
+  }
+  return "refkey";
+}

package/src/symbols/symbol-flow.ts

@@ -3,7 +3,8 @@ import { Context, effect, getContext, onCleanup } from "../reactivity.js";
 
 import { MemberContext } from "../context/member-scope.js";
 import { ScopeContext } from "../context/scope.js";
-import { formatSymbolName, trace, TracePhase } from "../tracer.js";
+import { debug, TracePhase } from "../debug/index.js";
+import { formatSymbolName } from "../tracer.js";
 import { OutputSymbol } from "./output-symbol.js";
 
 export interface TakeSymbolCallback {
@@ -19,16 +20,25 @@ export function takeSymbols(cb?: (symbol: OutputSymbol) => void) {
   context.takesSymbols = true;
   context.takenSymbols = shallowReactive(new Set<OutputSymbol>());
   if (cb) {
-    effect<Set<OutputSymbol>>((oldSymbols) => {
-      for (const symbol of context.takenSymbols!) {
-        if (oldSymbols && oldSymbols.has(symbol)) {
-          continue;
+    effect<Set<OutputSymbol>>(
+      (oldSymbols) => {
+        for (const symbol of context.takenSymbols!) {
+          if (oldSymbols && oldSymbols.has(symbol)) {
+            continue;
+          }
+          cb(symbol);
         }
-        cb(symbol);
-      }
 
-      return new Set(context.takenSymbols!);
-    });
+        return new Set(context.takenSymbols!);
+      },
+      undefined,
+      {
+        debug: {
+          name: "symbolFlow:takeSymbols",
+          type: "symbol",
+        },
+      },
+    );
   }
   return context.takenSymbols;
 }
@@ -37,9 +47,9 @@ export function emitSymbol(
   symbol: OutputSymbol | Ref<OutputSymbol | undefined>,
 ) {
   if (isRef(symbol)) {
-    trace(TracePhase.symbol.flow, () => `Emitting ref to symbol`);
+    debug.trace(TracePhase.symbol.flow, () => `Emitting ref to symbol`);
   } else {
-    trace(
+    debug.trace(
       TracePhase.symbol.flow,
       () => `Emitting symbol ${formatSymbolName(symbol)}`,
     );
@@ -58,7 +68,7 @@ export function emitSymbol(
       (context.context[ScopeContext.id] || context.context[MemberContext.id])
     ) {
       // don't cross scope boundaries.
-      trace(
+      debug.trace(
         TracePhase.symbol.flow,
         () => `Not emitting symbol across scope boundary`,
       );
@@ -69,27 +79,39 @@ export function emitSymbol(
   }
 
   if (!symbolTaker) {
-    trace(TracePhase.symbol.flow, () => `No symbol taker found, not emitting`);
+    debug.trace(
+      TracePhase.symbol.flow,
+      () => `No symbol taker found, not emitting`,
+    );
     return;
   }
 
   if (isRef(symbol)) {
-    effect<OutputSymbol | undefined>((prevSymbol) => {
-      onCleanup(() => {
-        if (symbol.value) {
-          symbolTaker.takenSymbols!.delete(symbol.value);
+    effect<OutputSymbol | undefined>(
+      (prevSymbol) => {
+        onCleanup(() => {
+          if (symbol.value) {
+            symbolTaker.takenSymbols!.delete(symbol.value);
+          }
+        });
+        if (symbol.value === undefined) {
+          symbolTaker.takenSymbols!.delete(prevSymbol!);
+          return undefined;
+        } else {
+          symbolTaker.takenSymbols!.add(symbol.value);
+          return symbol.value;
         }
-      });
-      if (symbol.value === undefined) {
-        symbolTaker.takenSymbols!.delete(prevSymbol!);
-        return undefined;
-      } else {
-        symbolTaker.takenSymbols!.add(symbol.value);
-        return symbol.value;
-      }
-    });
+      },
+      undefined,
+      {
+        debug: {
+          name: "symbolFlow:emitRef",
+          type: "symbol",
+        },
+      },
+    );
   } else {
-    trace(
+    debug.trace(
       TracePhase.symbol.flow,
       () =>
         `Emitting symbol ${formatSymbolName(symbol)} taken by ${symbolTaker.componentOwner?.name ?? "unknown component"}`,
@@ -103,19 +125,28 @@ export function emitSymbol(
 
 export function moveTakenMembersTo(baseSymbol: OutputSymbol) {
   const taken = takeSymbols();
-  effect(() => {
-    for (const symbol of taken) {
-      if (symbol.isTransient) {
-        symbol.moveMembersTo(baseSymbol);
-      }
+  effect(
+    () => {
+      for (const symbol of taken) {
+        if (symbol.isTransient) {
+          symbol.moveMembersTo(baseSymbol);
+        }
 
-      for (const refkey of symbol.refkeys) {
-        if (!baseSymbol.refkeys.includes(refkey)) {
-          baseSymbol.refkeys.push(refkey);
+        for (const refkey of symbol.refkeys) {
+          if (!baseSymbol.refkeys.includes(refkey)) {
+            baseSymbol.refkeys.push(refkey);
+          }
         }
       }
-    }
-  });
+    },
+    undefined,
+    {
+      debug: {
+        name: "symbolFlow:moveTakenMembers",
+        type: "symbol",
+      },
+    },
+  );
 }
 
 export function instantiateTakenMembersTo(

package/src/symbols/symbol-slot.test.tsx

@@ -0,0 +1,41 @@
+import { shallowRef } from "@vue/reactivity";
+import { expect, it } from "vitest";
+import { renderTree } from "../render.js";
+import { flushJobs } from "../scheduler.js";
+import { BasicSymbol } from "./basic-symbol.js";
+import { emitSymbol } from "./symbol-flow.js";
+import { createSymbolSlot } from "./symbol-slot.jsx";
+
+it("captures firstSymbol", async () => {
+  const Slot = createSymbolSlot();
+
+  renderTree(
+    <Slot>
+      {() => {
+        emitSymbol(new BasicSymbol("a", undefined));
+      }}
+    </Slot>,
+  );
+  await flushJobs();
+  expect(Slot.firstSymbol.value).toBeDefined();
+  expect(Slot.firstSymbol.value!.name).toBe("a");
+});
+
+it("captures firstSymbol when emitting a ref to a symbol", async () => {
+  const Slot = createSymbolSlot();
+  const symref = shallowRef<BasicSymbol | undefined>();
+
+  renderTree(
+    <Slot>
+      {() => {
+        emitSymbol(symref);
+      }}
+    </Slot>,
+  );
+  await flushJobs();
+  expect(Slot.firstSymbol.value).toBeUndefined();
+  symref.value = new BasicSymbol("a", undefined);
+  await flushJobs();
+  expect(Slot.firstSymbol.value).toBeDefined();
+  expect(Slot.firstSymbol.value!.name).toBe("a");
+});

package/src/symbols/symbol-slot.tsx

@@ -50,36 +50,63 @@ export function createSymbolSlot(): SymbolSlot {
   Object.defineProperty(SymbolSlot, "firstSymbol", {
     get() {
       const ref = shallowRef();
-      effect(() => {
-        ref.value = symbolSlotRef.value?.values().next().value;
-      });
+      effect(
+        () => {
+          ref.value = symbolSlotRef.value?.values().next().value;
+        },
+        undefined,
+        {
+          debug: {
+            name: "symbolSlot:firstSymbol",
+            type: "symbol",
+          },
+        },
+      );
       return ref;
     },
   });
 
   SymbolSlot.copyMembersTo = (baseSymbol: OutputSymbol) => {
-    effect(() => {
-      if (!symbolSlotRef.value) {
-        return;
-      }
+    effect(
+      () => {
+        if (!symbolSlotRef.value) {
+          return;
+        }
 
-      for (const symbol of symbolSlotRef.value) {
-        symbol.copyMembersTo(baseSymbol);
-      }
-    });
+        for (const symbol of symbolSlotRef.value) {
+          symbol.copyMembersTo(baseSymbol);
+        }
+      },
+      undefined,
+      {
+        debug: {
+          name: "symbolSlot:copyMembers",
+          type: "symbol",
+        },
+      },
+    );
   };
 
   SymbolSlot.moveMembersTo = (baseSymbol: OutputSymbol) => {
-    effect(() => {
-      if (!symbolSlotRef.value) {
-        return;
-      }
-      for (const symbol of symbolSlotRef.value) {
-        if (symbol.isTransient) {
-          symbol.moveMembersTo(baseSymbol);
+    effect(
+      () => {
+        if (!symbolSlotRef.value) {
+          return;
         }
-      }
-    });
+        for (const symbol of symbolSlotRef.value) {
+          if (symbol.isTransient) {
+            symbol.moveMembersTo(baseSymbol);
+          }
+        }
+      },
+      undefined,
+      {
+        debug: {
+          name: "symbolSlot:moveMembers",
+          type: "symbol",
+        },
+      },
+    );
   };
 
   return SymbolSlot as any;

package/src/symbols/symbol-table.ts

@@ -1,13 +1,9 @@
 import type { Binder, NameConflictResolver } from "../binder.js";
+import { debug, TracePhase } from "../debug/index.js";
 import { ReactiveUnionSet } from "../reactive-union-set.js";
 import { Refkey } from "../refkey.js";
 import { queueJob } from "../scheduler.js";
-import {
-  formatSymbolName,
-  formatSymbolTableName,
-  trace,
-  TracePhase,
-} from "../tracer.js";
+import { formatSymbolName, formatSymbolTableName } from "../tracer.js";
 import { OutputSpace } from "./output-space.js";
 import type { OutputSymbol } from "./output-symbol.js";
 
@@ -65,7 +61,7 @@ export abstract class SymbolTable extends ReactiveUnionSet<OutputSymbol> {
   ) {
     super({
       onAdd: (symbol) => {
-        trace(
+        debug.trace(
           TracePhase.symbol.addToScope,
           () =>
             `${formatSymbolName(symbol)} added to ${formatSymbolTableName(this)}`,
@@ -78,7 +74,7 @@ export abstract class SymbolTable extends ReactiveUnionSet<OutputSymbol> {
         return symbol;
       },
       onDelete: (symbol) => {
-        trace(
+        debug.trace(
           TracePhase.symbol.removeFromScope,
           () =>
             `${formatSymbolName(symbol)} removed from ${formatSymbolTableName(this)}`,
@@ -97,7 +93,7 @@ export abstract class SymbolTable extends ReactiveUnionSet<OutputSymbol> {
   }
 
   moveTo(target: SymbolTable): void {
-    trace(
+    debug.trace(
       TracePhase.scope.moveSymbols,
       () =>
         `${formatSymbolTableName(this)} -> ${formatSymbolTableName(target)}`,
@@ -117,7 +113,7 @@ export abstract class SymbolTable extends ReactiveUnionSet<OutputSymbol> {
       createRefkeys?(sourceSymbol: OutputSymbol): Refkey[];
     } = {},
   ): void {
-    trace(
+    debug.trace(
       TracePhase.scope.copySymbols,
       () =>
         `${formatSymbolTableName(this)} copied to ${formatSymbolTableName(target)}`,

package/src/trace.ts

@@ -0,0 +1 @@
+// Legacy module removed in favor of ./debug.ts.