@alloy-js/core 0.15.0 → 0.17.0

package/src/scheduler.ts

@@ -3,22 +3,47 @@ import { ReactiveEffectRunner } from "@vue/reactivity";
 export interface QueueJob {
   (): any;
 }
+const immediateQueue = new Set<QueueJob>();
 const queue = new Set<QueueJob>();
 
-export function scheduler(jobGetter: () => ReactiveEffectRunner) {
+export function scheduler(
+  jobGetter: () => ReactiveEffectRunner,
+  immediate = false,
+) {
   return () => {
-    queueJob(jobGetter());
+    queueJob(jobGetter(), immediate);
   };
 }
-export function queueJob(job: QueueJob) {
+export function queueJob(job: QueueJob, immediate = false) {
+  // if we have an immediate job, we don't need to queue the normal job.
   // the set is serving an important purpose here in deduping the effects we run
   // (which in effect coalesces multiple update effects together).
-  queue.add(job);
+  if (immediate) {
+    immediateQueue.add(job);
+  } else {
+    queue.add(job);
+  }
 }
 
 export function flushJobs() {
-  for (const job of queue) {
-    queue.delete(job);
+  let job;
+  while ((job = takeJob()) !== null) {
     job();
   }
 }
+
+function takeJob() {
+  if (immediateQueue.size > 0) {
+    // return first item in immediateQueue
+    const job = immediateQueue.values().next().value!;
+    immediateQueue.delete(job);
+    return job;
+  }
+  if (queue.size > 0) {
+    // return first item in queue
+    const job = queue.values().next().value!;
+    queue.delete(job);
+    return job;
+  }
+  return null;
+}

package/src/slot.ts

@@ -1,5 +1,4 @@
 import { ref, Ref } from "@vue/reactivity";
-import { OutputSymbol } from "./binder.js";
 import {
   Children,
   Component,
@@ -7,6 +6,7 @@ import {
   effect,
   memo,
 } from "./jsx-runtime.js";
+import { OutputSymbol } from "./symbols/output-symbol.js";
 
 export interface SlotInstance extends ComponentDefinition {}
 

package/src/stc.ts

@@ -1,9 +1,9 @@
-import {
+import { code, text } from "./code.js";
+import type {
   Children,
   ComponentCreator,
   ComponentDefinition,
-} from "@alloy-js/core/jsx-runtime";
-import { code, text } from "./code.js";
+} from "./jsx-runtime.js";
 
 export type MakeChildrenOptional<T extends object> =
   T extends { children?: any } ?

package/src/sti.ts

@@ -1,10 +1,10 @@
+import { code, text } from "./code.js";
 import {
-  Children,
+  type Children,
   createIntrinsic,
-  IntrinsicElementBase,
-  JSX,
-} from "@alloy-js/core/jsx-runtime";
-import { code, text } from "./code.js";
+  type IntrinsicElementBase,
+  type JSX,
+} from "./jsx-runtime.js";
 
 export type StiSignature<T extends keyof JSX.IntrinsicElements> = (
   ...args: unknown extends T ? []

package/src/symbols/index.ts

@@ -0,0 +1,5 @@
+export * from "./output-scope.js";
+export * from "./output-symbol.js";
+export * from "./symbol-flow.js";
+export * from "./symbol-slot.js";
+export * from "./symbol-table.js";

package/src/symbols/output-scope.ts

@@ -0,0 +1,323 @@
+import {
+  reactive,
+  ReactiveFlags,
+  shallowReactive,
+  track,
+  TrackOpTypes,
+  trigger,
+  TriggerOpTypes,
+  watch,
+} from "@vue/reactivity";
+import type { Binder } from "../binder.js";
+import { useBinder } from "../context/binder.js";
+import { useScope } from "../context/scope.js";
+import type { ReactiveUnionSetOptions } from "../reactive-union-set.js";
+import type { Refkey } from "../refkey.js";
+import {
+  formatScope,
+  formatScopeName,
+  trace,
+  traceEffect,
+  TracePhase,
+} from "../tracer.js";
+import { OutputSymbol } from "./output-symbol.js";
+import { SymbolTable } from "./symbol-table.js";
+
+/**
+ * Flags that describe an output scope.
+ */
+export enum OutputScopeFlags {
+  None = 0,
+
+  /**
+   * This scope is a static member scope.
+   */
+  StaticMemberScope = 1 << 0,
+
+  /**
+   * This scope is an instance member scope.
+   */
+  InstanceMemberScope = 1 << 1,
+
+  /**
+   * This scope is transient, and only exists to be merged with other scopes.
+   */
+  Transient = 1 << 2,
+
+  /**
+   * This scope is a member scope. Scopes with this flag will have an `owner`
+   * property that points to the symbol whose member this scope holds.
+   */
+  MemberScope = StaticMemberScope | InstanceMemberScope,
+}
+
+let scopeCount = 0;
+
+export interface OutputScopeOptions {
+  flags?: OutputScopeFlags;
+  kind?: string;
+  metadata?: Record<string, unknown>;
+  parent?: OutputScope;
+  owner?: OutputSymbol;
+  binder?: Binder;
+}
+
+/**
+ * A container of symbols accessible within some scope in your output code.
+ *
+ * @remarks
+ *
+ * Scopes form a tree. All scopes except the global scope have a parent scope
+ * identified by `parent`. Scopes can have nested scopes which can be accessed
+ * using the `children` property. Whether a child scope can be accessed from
+ * the parent scope is determined by each language's scoping rules.
+ *
+ * This interface is the base implementation of scope. Generally, most languages
+ * will have subtypes of this interface that provide additional metadata about
+ * the scope. For example, TypeScript scopes need to track whether the scope
+ * represents a package, module, class, function, etc.
+ *
+ * Scopes are reactive values, which allows you to observe changes to the scope
+ * within a reactive context.
+ */
+export class OutputScope {
+  // my kingdom for decorators
+  #name: string;
+  /**
+   * The name of the scope.
+   */
+  get name() {
+    track(this, TrackOpTypes.GET, "name");
+    return this.#name;
+  }
+  set name(name: string) {
+    const old = this.#name;
+    this.#name = name;
+    trigger(this, TriggerOpTypes.SET, "name", name, old);
+  }
+
+  #id: number;
+  /**
+   * The unique id of this scope.
+   */
+  get id() {
+    return this.#id;
+  }
+
+  #kind: string;
+
+  /**
+   * The kind of scope. Subtypes will likely provide a set of known scope kinds.
+   * The kind is not used by the binder itself.
+   */
+  get kind() {
+    return this.#kind;
+  }
+
+  #flags: OutputScopeFlags;
+  /**
+   * The flags that describe this scope.
+   */
+  get flags() {
+    track(this, TrackOpTypes.GET, "flags");
+    return this.#flags;
+  }
+  set flags(flags: OutputScopeFlags) {
+    const old = this.#flags;
+    this.#flags = flags;
+    trigger(this, TriggerOpTypes.SET, "flags", flags, old);
+  }
+
+  // read only
+  #metadata: Record<string, unknown>;
+  get metadata() {
+    return this.#metadata;
+  }
+
+  #parent?: OutputScope;
+  /**
+   * The container of this scope. This is only defined for scopes which don't
+   * have the {@link OutputScopeFlags.StaticMemberScope} or
+   * {@link OutputScopeFlags.InstanceMemberScope} flag.
+   */
+  get parent() {
+    return this.#parent;
+  }
+
+  #owner?: OutputSymbol;
+  /**
+   * The symbol that owns this scope. This is only defined for scopes that have
+   * the {@link OutputScopeFlags.StaticMemberScope} or
+   * {@link OutputScopeFlags.InstanceMemberScope} flag.
+   */
+  get owner() {
+    return this.#owner;
+  }
+
+  #symbols: SymbolTable;
+  /**
+   * The symbols defined within this scope.
+   */
+  get symbols() {
+    return this.#symbols;
+  }
+
+  #symbolsByRefkey: ReadonlyMap<Refkey, OutputSymbol>;
+  /**
+   * The symbols defined within this scope, indexed by refkey.
+   */
+  get symbolsByRefkey() {
+    return this.#symbolsByRefkey;
+  }
+
+  #symbolNames: ReadonlySet<string>;
+  get symbolNames() {
+    return this.#symbolNames;
+  }
+
+  #children: Set<OutputScope>;
+  /**
+   * The scopes nested within this scope.
+   */
+  get children() {
+    return this.#children;
+  }
+
+  #binder: Binder | undefined;
+  /**
+   * The binder that created this scope.
+   */
+  get binder() {
+    return this.#binder;
+  }
+
+  [ReactiveFlags.SKIP] = this;
+
+  constructor(name: string, options: OutputScopeOptions = {}) {
+    this.#name = name;
+    this.#id = scopeCount++;
+    this.#flags = options.flags ?? OutputScopeFlags.None;
+    this.#kind = options.kind ?? "scope";
+    this.#metadata = reactive(options.metadata ?? {});
+    this.#binder = options.binder ?? useBinder();
+    this.#owner = options.owner;
+    this.#children = shallowReactive(new Set());
+
+    if (this.#flags & OutputScopeFlags.MemberScope) {
+      if (!this.#owner) {
+        throw new Error("Member scopes must have an owner");
+      }
+    } else {
+      if (!this.#parent) {
+        this.#parent =
+          options.parent ?? useScope() ?? this.#binder?.globalScope;
+      }
+      if (this.#parent) {
+        // not global scope
+        this.#parent.children.add(this);
+      }
+    }
+
+    this.#symbols = new SymbolTable(this, {
+      nameConflictResolver: this.#binder?.nameConflictResolver,
+    });
+    this.#symbolsByRefkey = this.#symbols.createIndex((s) => s.refkeys);
+    this.#symbolNames = this.#symbols.createDerivedSet((s) => {
+      return s.name;
+    });
+
+    if (this.#parent) {
+      this.#parent.children.add(this);
+    }
+
+    this.#binder?.notifyScopeCreated(this);
+
+    trace(TracePhase.scope.create, () => `${formatScope(this)}`);
+    traceEffect(TracePhase.scope.update, () => {
+      return `${formatScope(this)}`;
+    });
+  }
+
+  moveSymbolsFrom(
+    source: OutputScope,
+    options?: ReactiveUnionSetOptions<OutputSymbol>,
+  ) {
+    trace(
+      TracePhase.scope.copySymbols,
+      () =>
+        `Moving symbols from ${formatScopeName(source)} to ${formatScopeName(this)}`,
+    );
+    this.#symbols.addSubset(source.#symbols, {
+      onAdd: (symbol) => {
+        if (options?.onAdd) {
+          return options.onAdd(symbol);
+        }
+        symbol.scope = this;
+        return symbol;
+      },
+      onDelete: (symbol) => {
+        if (options?.onDelete) {
+          options.onDelete(symbol);
+        }
+      },
+    });
+  }
+
+  copySymbolsFrom(
+    source: OutputScope,
+    options?: ReactiveUnionSetOptions<OutputSymbol>,
+  ) {
+    trace(
+      TracePhase.scope.copySymbols,
+      () =>
+        `Copying symbols from ${formatScopeName(source)} to ${formatScopeName(this)}`,
+    );
+    this.#symbols.addSubset(source.#symbols, {
+      onAdd: (symbol) => {
+        if (options?.onAdd) {
+          return options.onAdd(symbol);
+        }
+        return symbol.copyToScope(this);
+      },
+      onDelete: (symbol) => {
+        if (options?.onDelete) {
+          options.onDelete(symbol);
+        }
+      },
+    });
+  }
+
+  clone(options: { parent?: OutputScope; owner?: OutputSymbol } = {}) {
+    if (this.#flags & OutputScopeFlags.MemberScope && !options.owner) {
+      throw new Error("Member scope clones must specify an owner symbol");
+    } else if (this.#flags & ~OutputScopeFlags.MemberScope && !options.parent) {
+      throw new Error("Non-member scope clones must specify a parent scope");
+    }
+    const clone = new OutputScope(this.#name, {
+      binder: this.#binder,
+      flags: this.#flags,
+      kind: this.#kind,
+      metadata: this.#metadata,
+      parent: options.parent,
+      owner: options.owner,
+    });
+
+    watch(
+      () => this.name,
+      (newName) => (clone.name = newName),
+    );
+    watch(
+      () => this.flags,
+      (newFlags) => (clone.flags = newFlags),
+    );
+    // todo: this should be reactive, but cloning non-member scopes
+    // seems like a very rare thing.
+    for (const child of this.#children) {
+      clone.children.add(child.clone());
+    }
+
+    clone.copySymbolsFrom(this);
+
+    return clone;
+  }
+}