vestjs-runtime 1.7.0 → 2.0.1

package/src/IsolateWalker.ts

@@ -0,0 +1,359 @@
+import {
+  Nullable,
+  isNullish,
+  dynamicValue,
+  Result,
+  makeResult,
+  isFailure,
+} from 'vest-utils';
+
+import { IsolateInspector } from './Isolate/IsolateInspector';
+import { type TIsolate } from './Isolate/Isolate';
+import { IsolateMutator } from './Isolate/IsolateMutator';
+
+type VisitOnlyPredicate = (isolate: TIsolate) => boolean;
+
+/**
+ * Walks the isolate tree starting from the given node.
+ * @param startNode - The starting node for the traversal.
+ * @param callback - The callback function to be called for each visited node.
+ * @param visitOnly - Optional predicate to filter which nodes to visit.
+ */
+export function walk(
+  startNode: TIsolate,
+  callback: (isolate: TIsolate) => Result<void>,
+  visitOnly?: VisitOnlyPredicate,
+): Result<void> {
+  if (!startNode) return makeResult.Ok(undefined);
+
+  const stack = [startNode];
+
+  while (stack.length > 0) {
+    const node = stack.pop()!;
+
+    const res = visit(node, visitOnly, callback);
+
+    if (isFailure(res)) {
+      return res;
+    }
+
+    if (node.children) {
+      pushChildren(stack, node.children);
+    }
+  }
+
+  return makeResult.Ok(undefined);
+}
+
+function visit(
+  node: TIsolate,
+  visitOnly: VisitOnlyPredicate | undefined,
+  callback: (isolate: TIsolate) => Result<void>,
+): Result<void> {
+  if (shouldVisit(node, visitOnly)) {
+    return callback(node);
+  }
+  return makeResult.Ok(undefined);
+}
+
+function pushChildren(stack: TIsolate[], children: TIsolate[]): void {
+  for (let i = children.length - 1; i >= 0; i--) {
+    stack.push(children[i]);
+  }
+}
+
+function shouldVisit(node: TIsolate, visitOnly?: VisitOnlyPredicate): boolean {
+  return isNullish(visitOnly) || dynamicValue(visitOnly, node);
+}
+
+/**
+ * Reduces the isolate tree to a single value.
+ * @param startNode - The starting node for the traversal.
+ * @param callback - The reducer function.
+ * @param initialValue - The initial value for the accumulator.
+ * @param visitOnly - Optional predicate to filter which nodes to visit.
+ * @returns The final accumulated value.
+ */
+export function reduce<T>(
+  startNode: TIsolate,
+  callback: (acc: T, isolate: TIsolate) => Result<T>,
+  initialValue: T,
+  visitOnly?: VisitOnlyPredicate,
+): T {
+  let acc = initialValue;
+
+  walk(
+    startNode,
+    node => {
+      const res = callback(acc, node);
+
+      if (isFailure(res)) {
+        return makeResult.Err(res.error);
+      }
+      acc = res.unwrap();
+      return makeResult.Ok(undefined);
+    },
+    visitOnly,
+  );
+
+  return acc;
+}
+
+/**
+ * Checks if any node in the tree satisfies the predicate.
+ * @param startNode - The starting node for the traversal.
+ * @param predicate - The predicate function to test each node.
+ * @param visitOnly - Optional predicate to filter which nodes to visit.
+ * @returns True if any node satisfies the predicate, false otherwise.
+ */
+export function some(
+  startNode: TIsolate,
+  predicate: (node: TIsolate) => boolean,
+  visitOnly?: VisitOnlyPredicate,
+): boolean {
+  let hasMatch = false;
+
+  // Call the walk function with a callback function that sets hasMatch to true if the predicate is satisfied.
+  walk(
+    startNode,
+    node => {
+      if (predicate(node)) {
+        hasMatch = true;
+        return makeResult.Err(undefined);
+      }
+      return makeResult.Ok(undefined);
+    },
+    visitOnly,
+  );
+
+  return hasMatch;
+}
+
+/**
+ * Checks if the tree contains a node that matches the predicate.
+ * @param startNode - The starting node for the traversal.
+ * @param match - The predicate function to match nodes.
+ * @returns True if a matching node is found, false otherwise.
+ */
+export function has(startNode: TIsolate, match: VisitOnlyPredicate): boolean {
+  return some(startNode, () => true, match);
+}
+
+/**
+ * Traverses up the tree to find the closest ancestor that satisfies the predicate,
+ * then returns the first direct descendant of that ancestor that satisfies the predicate.
+ * @param startNode - The starting node.
+ * @param predicate - The predicate to match.
+ * @returns The found node or null.
+ */
+export function findClosest<I extends TIsolate = TIsolate>(
+  startNode: TIsolate,
+  predicate: (node: TIsolate) => boolean,
+): Nullable<I> {
+  let found: Nullable<TIsolate> = null;
+  let current: Nullable<TIsolate> = startNode;
+
+  while (current) {
+    found = current.children?.find(predicate) ?? null;
+
+    if (found) {
+      break;
+    }
+
+    current = current.parent;
+  }
+
+  return found as Nullable<I>;
+}
+
+/**
+ * Finds the first node in the tree that satisfies the predicate.
+ * @param startNode - The starting node.
+ * @param predicate - The predicate to match.
+ * @param visitOnly - Optional predicate to filter which nodes to visit.
+ * @returns The found node or null.
+ */
+export function find(
+  startNode: TIsolate,
+  predicate: (node: TIsolate) => boolean,
+  visitOnly?: VisitOnlyPredicate,
+): Nullable<TIsolate> {
+  let found = null;
+
+  walk(
+    startNode,
+    node => {
+      if (predicate(node)) {
+        found = node;
+        return makeResult.Err(undefined);
+      }
+      return makeResult.Ok(undefined);
+    },
+    visitOnly,
+  );
+
+  return found;
+}
+
+/**
+ * Finds all nodes in the tree that satisfy the predicate.
+ * @param startNode - The starting node.
+ * @param predicate - The predicate to match.
+ * @param visitOnly - Optional predicate to filter which nodes to visit.
+ * @returns An array of found nodes.
+ */
+export function findAll(
+  startNode: TIsolate,
+  predicate: (node: TIsolate) => boolean,
+  visitOnly?: VisitOnlyPredicate,
+): TIsolate[] {
+  const found: TIsolate[] = [];
+
+  walk(
+    startNode,
+    node => {
+      if (predicate(node)) {
+        found.push(node);
+      }
+      return makeResult.Ok(undefined);
+    },
+    visitOnly,
+  );
+
+  return found;
+}
+
+/**
+ * Checks if every node in the tree satisfies the predicate.
+ * @param startNode - The starting node.
+ * @param predicate - The predicate to match.
+ * @param visitOnly - Optional predicate to filter which nodes to visit.
+ * @returns True if all nodes satisfy the predicate, false otherwise.
+ */
+export function every(
+  startNode: TIsolate,
+  predicate: (node: TIsolate) => boolean,
+  visitOnly?: VisitOnlyPredicate,
+): boolean {
+  let hasMatch = true;
+  walk(
+    startNode,
+    node => {
+      if (!predicate(node)) {
+        hasMatch = false;
+        return makeResult.Err(undefined);
+      }
+      return makeResult.Ok(undefined);
+    },
+    visitOnly,
+  );
+
+  return hasMatch;
+}
+
+/**
+ * Removes nodes from the tree that satisfy the predicate.
+ * @param startNode - The starting node.
+ * @param predicate - The predicate to match nodes to remove.
+ * @param visitOnly - Optional predicate to filter which nodes to visit.
+ */
+export function pluck(
+  startNode: TIsolate,
+  predicate: (node: TIsolate) => boolean,
+  visitOnly?: VisitOnlyPredicate,
+): void {
+  walk(
+    startNode,
+    node => {
+      if (predicate(node) && node.parent) {
+        IsolateMutator.removeChild(node.parent, node);
+      }
+      return makeResult.Ok(undefined);
+    },
+    visitOnly,
+  );
+}
+
+/**
+ * Finds the closest ancestor of the startNode that satisfies the predicate.
+ * @param startNode - The starting node.
+ * @param predicate - The predicate to match.
+ * @returns The found ancestor or null.
+ */
+export function closest<I extends TIsolate = TIsolate>(
+  startNode: TIsolate,
+  predicate: (node: TIsolate) => boolean,
+): Nullable<I> {
+  let current: Nullable<TIsolate> = startNode;
+  do {
+    if (predicate(current)) {
+      return current as I;
+    }
+    current = current.parent;
+  } while (current);
+  return null;
+}
+
+/**
+ * Checks if an ancestor satisfying the predicate exists.
+ * @param startNode - The starting node.
+ * @param predicate - The predicate to match.
+ * @returns True if such an ancestor exists, false otherwise.
+ */
+export function closestExists(
+  startNode: TIsolate,
+  predicate: (node: TIsolate) => boolean,
+): boolean {
+  return !!closest(startNode, predicate);
+}
+
+/**
+ * Traverses the tree and returns the first non-nullish value returned by the callback.
+ * It optimizes traversal by only visiting nodes that have pending isolates or are pending themselves.
+ */
+export function mapFirst<T>(
+  startNode: TIsolate,
+  callback: (isolate: TIsolate, breakout: (value: T) => void) => void,
+): T | null {
+  const stack = [startNode];
+  let result: { value: T } | null = null;
+  const breakout = (value: T) => (result = { value });
+
+  while (stack.length > 0) {
+    if (result) {
+      break;
+    }
+
+    const node = stack.pop()!;
+    processNode(node, stack, callback, breakout);
+  }
+
+  return (result as { value: T } | null)?.value ?? null;
+}
+
+function processNode<T>(
+  node: TIsolate,
+  stack: TIsolate[],
+  callback: (isolate: TIsolate, breakout: (value: T) => void) => void,
+  breakout: (value: T) => void,
+): void {
+  if (!IsolateInspector.hasPending(node)) {
+    return;
+  }
+
+  runCallback(node, callback, breakout);
+
+  if (node.children) {
+    pushChildren(stack, node.children);
+  }
+}
+
+function runCallback<T>(
+  node: TIsolate,
+  callback: (isolate: TIsolate, breakout: (value: T) => void) => void,
+  breakout: (value: T) => void,
+): void {
+  if (IsolateInspector.isPending(node)) {
+    callback(node, breakout);
+  }
+}

package/src/Orchestrator/RuntimeStates.ts

@@ -0,0 +1,4 @@
+export enum RuntimeState {
+  PENDING = 'PENDING',
+  STABLE = 'STABLE',
+}

package/src/Reconciler.ts

@@ -0,0 +1,178 @@
+import {
+  Maybe,
+  Nullable,
+  invariant,
+  isNullish,
+  dynamicValue,
+} from 'vest-utils';
+
+import { type TIsolate } from './Isolate/Isolate';
+import { createHistoryIndex } from './Isolate/IsolateIndexer';
+import { IsolateInspector } from './Isolate/IsolateInspector';
+import { IsolateMutator } from './Isolate/IsolateMutator';
+import { isSameIsolateType } from './Isolate/IsolateSelectors';
+import * as VestRuntime from './VestRuntime';
+import { ErrorStrings } from './errors/ErrorStrings';
+// import { isSameIsolateType } from 'IsolateSelectors';
+
+// I would rather not use `any` here, but instead use `Isolate`.
+// The problem is that it breaks the actual implementation of `Isolate` in `IsolateTest`
+// As it is not properly extending `Isolate`.
+export interface IReconciler<I = any> {
+  (currentNode: I, historyNode: I): Nullable<I>;
+}
+
+function BaseReconciler(
+  currentNode: TIsolate,
+  historyNode: TIsolate,
+): TIsolate {
+  if (isNullish(historyNode)) {
+    return currentNode;
+  }
+  return currentNode;
+}
+
+export class Reconciler {
+  /**
+   * Reconciles the current isolate with the history isolate.
+   * If the current isolate is of a different type than the history isolate,
+   * the current isolate is returned.
+   * Otherwise, the reconciler function is called to determine the next isolate.
+   * If the reconciler function returns null or undefined, the base reconciler is used.
+   * If no history isolate exists, the current isolate is returned.
+   * @param node The current isolate to reconcile.
+   * @returns The next isolate after reconciliation.
+   */
+  static reconcile(node: TIsolate): TIsolate {
+    // If the node is transient, it should not be reconciled with history
+    // and should not consume the history cursor.
+    // This allows us to insert/remove transient nodes without affecting
+    // the stable identity of their siblings.
+    if (node.transient) {
+      return node;
+    }
+
+    const localHistoryNode = VestRuntime.useHistoryIsolateAtCurrentPosition();
+
+    const nextNodeResult = pickNextNode(node, localHistoryNode);
+
+    invariant(nextNodeResult, ErrorStrings.UNABLE_TO_PICK_NEXT_ISOLATE);
+
+    return nextNodeResult;
+  }
+
+  static dropNextNodesOnReorder<I extends TIsolate>(
+    reorderLogic: (newNode: I, prevNode: Maybe<TIsolate>) => boolean,
+    newNode: I,
+    prevNode: Maybe<TIsolate>,
+  ): boolean {
+    const didReorder = reorderLogic(newNode, prevNode);
+
+    if (didReorder) {
+      removeAllNextNodesInIsolate();
+    }
+
+    return didReorder;
+  }
+
+  static handleIsolateNodeWithKey<I extends TIsolate>(
+    node: TIsolate,
+
+    // The revoke function allows the caller to revoke the previous node
+    revoke: ((node: I) => boolean) | false,
+  ): TIsolate {
+    invariant(IsolateInspector.usesKey(node));
+
+    const prevNodeByKey = getNodeByKey(node.key);
+    let nextNode = node;
+
+    if (!isNullish(prevNodeByKey) && !dynamicValue(revoke, prevNodeByKey)) {
+      nextNode = prevNodeByKey;
+    }
+
+    VestRuntime.useSetIsolateKey(node.key, nextNode);
+
+    return nextNode;
+  }
+}
+
+function pickNextNode(
+  currentNode: TIsolate,
+  historyNode: Nullable<TIsolate>,
+): TIsolate {
+  if (isNullish(historyNode)) {
+    return handleNoHistoryNode(currentNode);
+  }
+
+  if (!isSameIsolateType(currentNode, historyNode)) {
+    return currentNode;
+  }
+
+  const reconciler = VestRuntime.useReconciler();
+
+  return (
+    reconciler(currentNode, historyNode) ??
+    BaseReconciler(currentNode, historyNode)
+  );
+}
+
+function handleNoHistoryNode<I extends TIsolate>(newNode: I): I {
+  if (IsolateInspector.usesKey(newNode)) {
+    return Reconciler.handleIsolateNodeWithKey(newNode, false) as I;
+  }
+
+  return newNode;
+}
+
+function removeAllNextNodesInIsolate() {
+  const currentNode = VestRuntime.useIsolate();
+  const historyNode = VestRuntime.useHistoryIsolate();
+
+  if (!historyNode || !currentNode) {
+    // This is probably unreachable, but TS is not convinced.
+    // Let's play it safe.
+    /* istanbul ignore next */
+    return;
+  }
+
+  IsolateMutator.slice(historyNode, IsolateInspector.cursor(currentNode));
+}
+
+const historyIndexCache = new WeakMap<
+  TIsolate,
+  Map<string, TIsolate | TIsolate[]>
+>();
+
+function getNodeByKey(key: Nullable<string>): Nullable<TIsolate> {
+  const historyParent = VestRuntime.useHistoryIsolate();
+
+  if (isNullish(key) || !historyParent) {
+    return null;
+  }
+
+  const index = getHistoryIndex(historyParent);
+  const match = index.get(key);
+
+  if (!match) {
+    return null;
+  }
+
+  if (Array.isArray(match)) {
+    return match[0];
+  }
+
+  return match;
+}
+
+function getHistoryIndex(
+  historyParent: TIsolate,
+): Map<string, TIsolate | TIsolate[]> {
+  let index = historyIndexCache.get(historyParent);
+
+  if (!index) {
+    index = createHistoryIndex(historyParent.children);
+    historyIndexCache.set(historyParent, index);
+  }
+
+  return index;
+}

package/src/RuntimeEvents.ts

@@ -0,0 +1,9 @@
+import { TIsolate } from './Isolate/IsolateTypes';
+
+export type RuntimeEvents = {
+  ASYNC_ISOLATE_DONE: TIsolate;
+  ISOLATE_DONE: TIsolate;
+  ISOLATE_ENTER: TIsolate;
+  ISOLATE_PENDING: TIsolate;
+  ISOLATE_RECONCILED: TIsolate;
+};