@alloy-js/core 0.17.0 → 0.18.0-dev.2

package/src/props-combinators.ts

@@ -0,0 +1,148 @@
+import { computed, isReactive, proxyRefs, toRefs } from "@vue/reactivity";
+import { untrack } from "./reactivity.js";
+
+export function mergeProps<T, U>(source: T, source1: U): T & U;
+export function mergeProps<T, U, V>(
+  source: T,
+  source1: U,
+  source2: V,
+): T & U & V;
+export function mergeProps<T, U, V, W>(
+  source: T,
+  source1: U,
+  source2: V,
+  source3: W,
+): T & U & V & W;
+export function mergeProps(...sources: any): any {
+  const target = {};
+  for (let i = 0; i < sources.length; i++) {
+    let source = sources[i];
+    if (typeof source === "function") source = source();
+    if (source) {
+      const descriptors = Object.getOwnPropertyDescriptors(source);
+      for (const key in descriptors) {
+        if (key in target) continue;
+        Object.defineProperty(target, key, {
+          enumerable: true,
+          get() {
+            for (let i = sources.length - 1; i >= 0; i--) {
+              let s = sources[i];
+              if (typeof s === "function") s = s();
+              const v = (s || {})[key];
+              if (v !== undefined) return v;
+            }
+          },
+        });
+      }
+    }
+  }
+  return target;
+}
+
+export type SplitProps<T, K extends (readonly (keyof T)[])[]> = [
+  ...{
+    [P in keyof K]: P extends `${number}` ?
+      Pick<T, Extract<K[P], readonly (keyof T)[]>[number]>
+    : never;
+  },
+  { [P in keyof T as Exclude<P, K[number][number]>]: T[P] },
+];
+
+export function splitProps<
+  T extends Record<any, any>,
+  K extends [readonly (keyof T)[], ...(readonly (keyof T)[])[]],
+>(props: T, ...keys: K): SplitProps<T, K> {
+  if (isReactive(props)) {
+    const refs = untrack(() => toRefs(props));
+    const remainingKeys = new Set(Object.keys(refs));
+
+    const result: any = keys.map((keySet) => {
+      const resultSet: any = {};
+      for (const key of keySet) {
+        resultSet[key] = refs[key];
+        remainingKeys.delete(key as string);
+      }
+      return proxyRefs(resultSet);
+    });
+
+    const remaining: any = {};
+    for (const key of remainingKeys) {
+      remaining[key] = refs[key];
+    }
+
+    return [...result, proxyRefs(remaining)] as any;
+  }
+
+  const descriptors = Object.getOwnPropertyDescriptors(props);
+  const remainingKeys = new Set(Object.keys(descriptors));
+  const result: any = keys.map((keySet) => {
+    const resultSet: any = {};
+    for (const key of keySet) {
+      if (key in descriptors) {
+        Object.defineProperty(resultSet, key, descriptors[key]);
+        remainingKeys.delete(key as string);
+      }
+    }
+    return resultSet;
+  });
+
+  const remaining: any = {};
+  for (const key of remainingKeys) {
+    Object.defineProperty(remaining, key, descriptors[key]);
+  }
+
+  return [...result, remaining] as any;
+}
+
+/**
+ * Applies default values to a props object. Reactive props are handled properly
+ * by ensuring that their value is not accessed by `defaultProps`, avoiding any
+ * unintended side effects.
+ */
+export function defaultProps<T extends {}>(props: T, defaults: Partial<T>): T {
+  if (isReactive(props)) {
+    const refs = untrack(() => toRefs(props));
+    for (const key in defaults) {
+      const originalRef = refs[key];
+      refs[key] = computed(() =>
+        originalRef.value === undefined ? defaults[key] : originalRef.value,
+      ) as any;
+    }
+
+    return proxyRefs(refs);
+  }
+  const withDefaults = {} as T;
+  const copied = new Set<string>();
+  for (const key in defaults) {
+    copied.add(key);
+    const desc = Object.getOwnPropertyDescriptor(props, key);
+    if (!desc) {
+      withDefaults[key] = defaults[key]!;
+      continue;
+    }
+
+    if (desc.get) {
+      const originalGet = desc.get;
+      desc.get = function () {
+        const value = originalGet.call(this);
+        return value === undefined ? defaults[key as keyof T] : value;
+      };
+      Object.defineProperty(withDefaults, key, desc);
+    } else {
+      desc.value =
+        desc.value === undefined ? defaults[key as keyof T] : desc.value;
+      Object.defineProperty(withDefaults, key, desc);
+    }
+  }
+
+  const descriptors = Object.getOwnPropertyDescriptors(props);
+  for (const key in descriptors) {
+    if (copied.has(key)) {
+      continue;
+    }
+
+    Object.defineProperty(withDefaults, key, descriptors[key]);
+  }
+
+  return withDefaults;
+}

package/src/reactive-union-set.ts

@@ -1,4 +1,3 @@
-import { effect } from "@alloy-js/core/jsx-runtime";
 import {
   ITERATE_KEY,
   ReactiveFlags,
@@ -9,6 +8,7 @@ import {
   trigger,
   TriggerOpTypes,
 } from "@vue/reactivity";
+import { effect } from "./reactivity.js";
 
 export interface ReactiveUnionSetOptions<T> {
   onAdd?: OnReactiveSetAddCallback<T>;

package/src/reactivity.ts

@@ -0,0 +1,230 @@
+import {
+  pauseTracking,
+  ReactiveEffectRunner,
+  resetTracking,
+  ShallowReactive,
+  shallowRef,
+  stop,
+  effect as vueEffect,
+} from "@vue/reactivity";
+import type { RenderedTextTree } from "./render.js";
+import type { Children, ComponentCreator } from "./runtime/component.js";
+import { scheduler } from "./scheduler.js";
+import type { OutputSymbol } from "./symbols/output-symbol.js";
+import { trace, TracePhase } from "./tracer.js";
+
+// check for multiple versions of alloy here.
+if ((globalThis as any).__ALLOY__) {
+  throw new Error(
+    "Multiple versions of Alloy are loaded for this project. This will likely cause undesirable behavior.",
+  );
+}
+(globalThis as any).__ALLOY__ = true;
+
+export function getElementCache() {
+  return getContext()!.elementCache;
+}
+
+export type ElementCacheKey =
+  | ComponentCreator
+  | (() => unknown)
+  | CustomContext;
+
+export type ElementCache = Map<ElementCacheKey, RenderedTextTree>;
+
+export interface Disposable {
+  (): void;
+}
+
+export interface Context {
+  disposables: Disposable[];
+  owner: Context | null;
+
+  // context providers
+  context?: Record<symbol, unknown>;
+
+  // store random info about the node
+  meta?: Record<string, any>;
+
+  /**
+   * A cache of RenderTextTree nodes created within this context,
+   * indexed by the component or function which created them.
+   */
+  elementCache: ElementCache;
+  /**
+   * When this context was created by a component, this will
+   * be the component that created it.
+   */
+  componentOwner?: ComponentCreator<unknown>;
+
+  /**
+   * Whether this context will take an emitted symbol.
+   */
+  takesSymbols: boolean;
+
+  /**
+   * The symbol that this component has taken.
+   */
+  takenSymbols?: ShallowReactive<Set<OutputSymbol>>;
+}
+
+let globalContext: Context | null = null;
+export function getContext() {
+  return globalContext;
+}
+
+export interface RootOptions {
+  componentOwner?: ComponentCreator<any>;
+}
+
+export function root<T>(fn: (d: Disposable) => T, options?: RootOptions): T {
+  const context: Context = {
+    componentOwner: options?.componentOwner,
+    disposables: [],
+    owner: globalContext,
+    context: {},
+    elementCache: new Map(),
+    takesSymbols: false,
+    takenSymbols: undefined,
+  };
+
+  globalContext = context;
+  let ret;
+  try {
+    ret = untrack(() =>
+      fn(() => {
+        for (const d of context!.disposables) {
+          d();
+        }
+      }),
+    );
+  } finally {
+    globalContext = globalContext!.owner;
+  }
+
+  return ret;
+}
+
+export function untrack<T>(fn: () => T): T {
+  pauseTracking();
+  const v = fn();
+  resetTracking();
+  return v;
+}
+
+export function memo<T>(fn: () => T, equal?: boolean): () => T {
+  const o = shallowRef();
+  effect((prev) => {
+    const res = fn();
+    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+    (!equal || prev !== res) && (o.value = res);
+    return res;
+  }, undefined as T);
+  return () => o.value;
+}
+
+export function effect<T>(fn: (prev?: T) => T, current?: T) {
+  const context: Context = {
+    context: {},
+    disposables: [] as (() => void)[],
+    owner: globalContext,
+    elementCache: new Map(),
+    takesSymbols: false,
+    takenSymbols: undefined,
+  };
+
+  const cleanupFn = (final: boolean) => {
+    const d = context.disposables;
+    context.disposables = [];
+    for (let k = 0, len = d.length; k < len; k++) d[k]();
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+    final && stop(runner);
+  };
+
+  onCleanup(() => cleanupFn(true));
+  const runner: ReactiveEffectRunner<void> = vueEffect(
+    () => {
+      cleanupFn(false);
+
+      const oldContext = globalContext;
+      globalContext = context;
+      try {
+        current = fn(current);
+      } finally {
+        globalContext = oldContext;
+      }
+    },
+    {
+      scheduler: scheduler(() => runner),
+      onTrack(event) {
+        trace(TracePhase.effect.track, () => {
+          return `tracking ${event.target}, ${event.key}`;
+        });
+      },
+      onTrigger(event) {
+        trace(TracePhase.effect.trigger, () => {
+          return `triggering ${event.target}, ${event.key}`;
+        });
+      },
+    },
+  );
+
+  // allow recursive effects (recursive option does nothing, possible bug)
+  (runner as any).effect.flags |= 1 << 5;
+}
+
+/**
+ * Register a cleanup function which is called when the current reactive scope
+ * is recalculated or disposed. This is useful to clean up any side effects
+ * created in the reactive scope.
+ *
+ * @remarks
+ *
+ * When onCleanup is called inside a component definition, the provided function
+ * is called when the component is removed from the tree. This can be useful to
+ * clean up any side effects created as a result of rendering the component. For
+ * example, if rendering a component creates a symbol, `onCleanup` can be used
+ * to remove the symbol when the component is removed from the tree.
+ *
+ * When onCleanup is called inside a memo or effect, the function is called when
+ * the effect is refreshed (e.g. when a memo or computed recalculates) or
+ * disposed (e.g. it is no longer needed because it is attached to a component
+ * which was removed).
+ */
+export function onCleanup(fn: Disposable) {
+  if (globalContext != null) {
+    globalContext.disposables.push(fn);
+  }
+}
+
+/**
+ * Create a custom reactive context for the children returned by
+ * the provided context.
+ */
+export interface CustomContext {
+  [CUSTOM_CONTEXT_SYM]: true;
+  useCustomContext: (useCb: CustomContextChildrenCallback) => void;
+}
+
+export type CustomContextChildrenCallback = (child: Children) => void;
+const CUSTOM_CONTEXT_SYM = Symbol();
+
+export function createCustomContext(
+  useCallback: (useChildren: CustomContextChildrenCallback) => void,
+): CustomContext {
+  return {
+    [CUSTOM_CONTEXT_SYM]: true,
+    useCustomContext(useCb: (children: Children) => void): void {
+      useCallback(useCb);
+    },
+  };
+}
+
+export function isCustomContext(child: Children): child is CustomContext {
+  return (
+    typeof child === "object" &&
+    child !== null &&
+    Object.hasOwn(child, CUSTOM_CONTEXT_SYM)
+  );
+}

package/src/render.ts

@@ -3,26 +3,29 @@ import { Doc, doc } from "prettier";
 import prettier from "prettier/doc.js";
 import { useContext } from "./context.js";
 import { SourceFileContext } from "./context/source-file.js";
+import { shouldDebug } from "./debug.js";
 import {
-  Child,
-  Children,
   Context,
   CustomContext,
   effect,
   getContext,
   getElementCache,
-  IntrinsicElement,
-  isComponentCreator,
   isCustomContext,
-  isIntrinsicElement,
-  popStack,
-  printRenderStack,
-  pushStack,
   root,
   untrack,
-} from "./jsx-runtime.js";
+} from "./reactivity.js";
 import { isRefkey } from "./refkey.js";
+import {
+  Child,
+  Children,
+  Component,
+  isComponentCreator,
+  Props,
+} from "./runtime/component.js";
+import { IntrinsicElement, isIntrinsicElement } from "./runtime/intrinsic.js";
 import { flushJobs } from "./scheduler.js";
+import { trace, TracePhase } from "./tracer.js";
+
 const {
   builders: {
     align,
@@ -172,11 +175,6 @@ export function isPrintHook(type: unknown): type is PrintHook {
 
 export type RenderedTextTree = (string | RenderedTextTree | PrintHook)[];
 
-function traceRender(phase: string, message: () => string) {
-  return false;
-  //console.log(`[\x1b[34m${phase}\x1b[0m]: ${message()}`);
-}
-
 export function render(
   children: Children,
   options?: PrintTreeOptions,
@@ -284,7 +282,12 @@ export function renderTree(children: Children) {
 }
 
 function renderWorker(node: RenderedTextTree, children: Children) {
-  traceRender("render", () => dumpChildren(children));
+  if (!getContext()) {
+    throw new Error(
+      "Cannot render without a context. Make sure you are using the Output component.",
+    );
+  }
+  trace(TracePhase.render.worker, () => dumpChildren(children));
 
   if (Array.isArray(node)) {
     nodesToContext.set(node, getContext()!);
@@ -300,7 +303,7 @@ function renderWorker(node: RenderedTextTree, children: Children) {
 }
 
 function appendChild(node: RenderedTextTree, rawChild: Child) {
-  traceRender("appendChild", () => debugPrintChild(rawChild));
+  trace(TracePhase.render.appendChild, () => debugPrintChild(rawChild));
   const child = normalizeChild(rawChild);
 
   if (typeof child === "string") {
@@ -308,12 +311,18 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
   } else {
     const cache = getElementCache();
     if (cache.has(child as any)) {
-      traceRender("appendChild:cached", () => debugPrintChild(child));
+      trace(
+        TracePhase.render.appendChild,
+        () => "Cached: " + debugPrintChild(child),
+      );
       node.push(cache.get(child as any)!);
       return;
     }
     if (isCustomContext(child)) {
-      traceRender("appendChild:custom-context", () => debugPrintChild(child));
+      trace(
+        TracePhase.render.appendChild,
+        () => "CustomContext: " + debugPrintChild(child),
+      );
       child.useCustomContext((children) => {
         const newNode: RenderedTextTree = [];
         renderWorker(newNode, children);
@@ -321,10 +330,11 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
         cache.set(child, newNode);
       });
     } else if (isIntrinsicElement(child)) {
-      // don't need a new context here because intrinsics are never reactive
-      traceRender("appendChild:intrinsic-element", () =>
-        debugPrintChild(child),
+      trace(
+        TracePhase.render.appendChild,
+        () => "IntrinsicElement: " + debugPrintChild(child),
       );
+      // don't need a new context here because intrinsics are never reactive
       const newNode: RenderedTextTree = [];
 
       function formatHookWithChildren(command: (doc: Doc) => Doc) {
@@ -442,20 +452,26 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
       }
     } else if (isComponentCreator(child)) {
       effect(() => {
-        traceRender("appendChild:component", () => debugPrintChild(child));
+        trace(
+          TracePhase.render.appendChild,
+          () => "Component: " + debugPrintChild(child),
+        );
         const componentRoot: RenderedTextTree = [];
         pushStack(child.component, child.props);
         renderWorker(componentRoot, untrack(child));
         popStack();
         node.push(componentRoot);
         cache.set(child, componentRoot);
-        traceRender("appendChild:component-done", () => debugPrintChild(child));
+        trace(
+          TracePhase.render.appendChild,
+          () => "Component done: " + debugPrintChild(child),
+        );
       });
     } else if (typeof child === "function") {
-      traceRender("appendChild:memo", () => child.toString());
+      trace(TracePhase.render.appendChild, () => "Memo: " + child.toString());
       const index = node.length;
       effect(() => {
-        traceRender("memoEffect:run", () => "");
+        trace(TracePhase.render.renderEffect, () => "");
         let res = child();
         while (typeof res === "function" && !isComponentCreator(res)) {
           res = res();
@@ -466,7 +482,6 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
         cache.set(child, newNodes);
         return newNodes;
       });
-      traceRender("appendChild:memo-done", () => "");
     } else {
       throw new Error("Unexpected child type");
     }
@@ -525,6 +540,8 @@ function debugPrintChild(child: Children): string {
     return "$memo";
   } else if (isRef(child)) {
     return "$ref";
+  } else if (isIntrinsicElement(child)) {
+    return `<${child.name}>`;
   } else {
     return JSON.stringify(child);
   }
@@ -588,3 +605,57 @@ function printTreeWorker(tree: RenderedTextTree): Doc {
 
   return doc;
 }
+// debugging utilities
+const renderStack: {
+  component: Component<any>;
+  props: Props;
+}[] = [];
+
+export function pushStack(component: Component<any>, props: Props) {
+  if (!shouldDebug()) return;
+  renderStack.push({ component, props });
+}
+
+export function popStack() {
+  if (!shouldDebug()) return;
+  renderStack.pop();
+}
+
+export function printRenderStack() {
+  if (!shouldDebug()) return;
+
+  // eslint-disable-next-line no-console
+  console.error("Error rendering:");
+  for (let i = renderStack.length - 1; i >= 0; i--) {
+    const { component, props } = renderStack[i];
+    // eslint-disable-next-line no-console
+    console.error(`    at ${component.name}(${inspectProps(props)})`);
+  }
+}
+
+function inspectProps(props: Props) {
+  return JSON.stringify(
+    Object.fromEntries(
+      Object.entries(props).map(([key, value]) => {
+        let safeValue;
+        switch (typeof value) {
+          case "string":
+          case "number":
+          case "boolean":
+            safeValue = value;
+            break;
+          case "undefined":
+            safeValue = "undefined";
+            break;
+          case "object":
+            safeValue = value ? "{...}" : null;
+            break;
+          case "function":
+            safeValue = "function";
+            break;
+        }
+        return [key, safeValue];
+      }),
+    ),
+  );
+}

package/src/runtime/component.ts

@@ -0,0 +1,67 @@
+import { Ref } from "@vue/reactivity";
+import { CustomContext } from "../reactivity.js";
+import { Refkey } from "../refkey.js";
+import { IntrinsicElement } from "./intrinsic.js";
+
+export type Child =
+  | string
+  | boolean
+  | number
+  | undefined
+  | null
+  | void
+  | (() => Children)
+  | Ref
+  | Refkey
+  | CustomContext
+  | IntrinsicElement;
+
+export type Children = Child | Children[];
+export type Props = Record<string, any>;
+
+export interface ComponentDefinition<TProps = Props> {
+  (props: TProps): Children;
+}
+export interface Component<TProps = Props> {
+  (props: TProps): Children;
+  tag?: symbol;
+}
+
+export interface ComponentCreator<TProps = Props> {
+  component: Component<TProps>;
+  (): Children;
+  props: TProps;
+  tag?: symbol;
+}
+
+export function isComponentCreator<TProps = any>(
+  item: unknown,
+  component?: Component<TProps>,
+): item is ComponentCreator<TProps> {
+  if (!component) {
+    return typeof item === "function" && (item as any).component;
+  }
+  return typeof item === "function" && (item as any).component === component;
+}
+
+export function createComponent<TProps extends Props = Props>(
+  C: Component<TProps>,
+  props: TProps,
+): ComponentCreator<TProps> {
+  const creator: ComponentCreator<TProps> = () => /* */ C(props);
+  creator.props = props;
+  creator.component = C;
+  if (C.tag) {
+    creator.tag = C.tag;
+  }
+
+  return creator;
+}
+
+export function taggedComponent<TProps = Props>(
+  tag: symbol,
+  component: Component<TProps>,
+): Component<TProps> & Required<Pick<Component<TProps>, "tag">> {
+  component.tag = tag;
+  return component as any;
+}