vestjs-runtime 1.7.0 → 2.0.1

package/src/Isolate/IsolateFocused.ts

@@ -0,0 +1,93 @@
+import {
+  asArray,
+  Maybe,
+  Nullish,
+  OneOrMoreOf,
+  noop,
+  isNotEmpty,
+  isStringValue,
+} from 'vest-utils';
+
+import { IsolateTransient } from './IsolateTransient';
+import { TIsolate } from './Isolate';
+import { IsolateKeys } from './IsolateKeys';
+
+export const VestIsolateTypeFocused = 'Focused';
+
+export enum FocusModes {
+  SKIP = 'skip',
+  ONLY = 'only',
+}
+
+export type FocusMatchExclusion = Maybe<OneOrMoreOf<string>>;
+
+export type TIsolateFocused = TIsolate<IsolateFocusedPayload>;
+
+type IsolateFocusedPayload = {
+  focusMode: FocusModes;
+  match: FocusMatchExclusion;
+  matchAll: boolean;
+};
+
+/**
+ * Creates a focused isolate.
+ * Focused isolates are transient because they only affect the current run
+ * and do not need to be preserved in history or appearing in the suite result.
+ */
+export function IsolateFocused(
+  focusMode: FocusModes,
+  match?: true | FocusMatchExclusion,
+): TIsolateFocused | undefined {
+  const matchedFields = asArray(match).filter(isStringValue).filter(isNotEmpty);
+
+  const matchAll = match === true;
+
+  // If there are no fields to match and matchAll is false,
+  // skip creating the isolate entirely — it would be a no-op.
+  if (!isNotEmpty(matchedFields) && !matchAll) {
+    return undefined;
+  }
+
+  return IsolateTransient<IsolateFocusedPayload>(noop, VestIsolateTypeFocused, {
+    focusMode,
+    match: matchedFields,
+    matchAll,
+  });
+}
+
+export class FocusSelectors {
+  static isSkipFocused(
+    focus: Nullish<TIsolateFocused>,
+    fieldName?: string,
+  ): boolean {
+    if (!focus) return false;
+    const data = focus.data;
+    if (!data || data.focusMode !== FocusModes.SKIP) return false;
+    if (data.matchAll) return true;
+    return hasFocus(focus, fieldName);
+  }
+  static isOnlyFocused(
+    focus: Nullish<TIsolateFocused>,
+    fieldName?: string,
+  ): boolean {
+    if (!focus) return false;
+    const data = focus.data;
+    if (!data || data.focusMode !== FocusModes.ONLY) return false;
+    if (data.matchAll) return true;
+    return hasFocus(focus, fieldName);
+  }
+
+  static isIsolateFocused(isolate: TIsolate): isolate is TIsolateFocused {
+    return isolate[IsolateKeys.Type] === VestIsolateTypeFocused;
+  }
+}
+
+function hasFocus(
+  focus: Nullish<TIsolateFocused>,
+  fieldName?: string,
+): boolean {
+  const match = asArray(focus?.data?.match);
+  if (!match.length) return false;
+
+  return !fieldName || match.includes(fieldName as string);
+}

package/src/Isolate/IsolateIndexer.ts

@@ -0,0 +1,42 @@
+import { isNullish, Nullable } from 'vest-utils';
+
+import { TIsolate } from './IsolateTypes';
+
+export function createHistoryIndex(
+  children: Nullable<TIsolate[]>,
+): Map<string, TIsolate | TIsolate[]> {
+  const index = new Map<string, TIsolate | TIsolate[]>();
+
+  if (!children) {
+    return index;
+  }
+
+  for (const child of children) {
+    addToIndex(index, child);
+  }
+
+  return index;
+}
+
+function addToIndex(
+  index: Map<string, TIsolate | TIsolate[]>,
+  isolate: TIsolate,
+): void {
+  const { key } = isolate;
+
+  if (isNullish(key)) {
+    return;
+  }
+
+  const existing = index.get(key);
+
+  if (existing) {
+    if (Array.isArray(existing)) {
+      existing.push(isolate);
+    } else {
+      index.set(key, [existing, isolate]);
+    }
+  } else {
+    index.set(key, isolate);
+  }
+}

package/src/Isolate/IsolateInspector.ts

@@ -0,0 +1,93 @@
+import { Nullable, isNotNullish, isNullish } from 'vest-utils';
+
+import { TIsolate } from './Isolate';
+import { IsolateStatus } from './IsolateStatus';
+
+export class IsolateInspector {
+  static at(isolate: Nullable<TIsolate>, at: number): Nullable<TIsolate> {
+    if (isNullish(isolate)) {
+      return null;
+    }
+    return isolate.children?.[at] ?? null;
+  }
+
+  static cursor(isolate: Nullable<TIsolate>): number {
+    if (isNullish(isolate)) {
+      return 0;
+    }
+    return isolate.children?.length ?? 0;
+  }
+
+  static canReorder<I extends TIsolate>(isolate: Nullable<I>): boolean {
+    if (isNullish(isolate)) {
+      return false;
+    }
+
+    return IsolateInspector.allowsReorder(isolate.parent);
+  }
+
+  static allowsReorder<I extends Record<any, any>>(
+    isolate: Nullable<I>,
+  ): boolean {
+    return isolate?.allowReorder === true;
+  }
+
+  static usesKey(isolate: Nullable<TIsolate>): boolean {
+    if (isNullish(isolate)) {
+      return false;
+    }
+    return isNotNullish(isolate.key);
+  }
+
+  static getChildByKey(
+    isolate: Nullable<TIsolate>,
+    key: string,
+  ): Nullable<TIsolate> {
+    if (isNullish(isolate)) {
+      return null;
+    }
+    return isolate.keys?.[key] ?? null;
+  }
+
+  static getStatus(isolate: Nullable<TIsolate>): IsolateStatus {
+    if (isNullish(isolate)) {
+      return IsolateStatus.INITIAL;
+    }
+    return isolate.status ?? IsolateStatus.INITIAL;
+  }
+
+  static statusEquals(
+    isolate: Nullable<TIsolate>,
+    status: IsolateStatus,
+  ): boolean {
+    return IsolateInspector.getStatus(isolate) === status;
+  }
+
+  static isPending(isolate: Nullable<TIsolate>): boolean {
+    return IsolateInspector.statusEquals(isolate, IsolateStatus.PENDING);
+  }
+
+  static isHasPending(isolate: Nullable<TIsolate>): boolean {
+    return IsolateInspector.statusEquals(isolate, IsolateStatus.HAS_PENDING);
+  }
+
+  static hasPending(isolate: Nullable<TIsolate>): boolean {
+    return (
+      IsolateInspector.isPending(isolate) ||
+      IsolateInspector.isHasPending(isolate)
+    );
+  }
+
+  static hasActiveChildren(isolate: Nullable<TIsolate>): boolean {
+    if (isNullish(isolate) || isNullish(isolate.children)) {
+      return false;
+    }
+
+    // Check if ANY immediate child is currently PENDING or HAS_PENDING
+    return isolate.children.some(child => IsolateInspector.hasPending(child));
+  }
+
+  static getParent(isolate: Nullable<TIsolate>): Nullable<TIsolate> {
+    return isolate?.parent ?? null;
+  }
+}

package/src/Isolate/IsolateKeys.ts

@@ -0,0 +1,18 @@
+export enum IsolateKeys {
+  Type = '$type',
+  Keys = 'keys',
+  Key = 'key',
+  Parent = 'parent',
+  Data = 'data',
+  AllowReorder = 'allowReorder',
+  Transient = 'transient',
+  Status = 'status',
+  AbortController = 'abortController',
+  Children = 'children',
+}
+
+export const ExcludedFromDump = new Set([
+  IsolateKeys.AbortController,
+  IsolateKeys.Parent,
+  IsolateKeys.Keys,
+]);

package/src/Isolate/IsolateMutator.ts

@@ -0,0 +1,165 @@
+import {
+  Nullable,
+  invariant,
+  isNullish,
+  makeResult,
+  Result,
+  isFailure,
+} from 'vest-utils';
+
+import { RuntimeApi } from '../VestRuntime';
+
+import { IsolateStateMachine } from './IsolateStateMachine';
+import { IsolateStatus } from './IsolateStatus';
+import { IsolateInspector } from './IsolateInspector';
+
+import { TIsolate } from './Isolate';
+
+function bubbleUpPending(isolate: Nullable<TIsolate>): void {
+  if (isNullish(isolate)) {
+    return;
+  }
+  // If parent is already HAS_PENDING, we can stop the upward traversal.
+  if (IsolateInspector.isHasPending(isolate)) {
+    return;
+  }
+
+  const result = IsolateMutator.setHasPending(isolate);
+
+  if (isFailure(result)) {
+    return;
+  }
+
+  bubbleUpPending(isolate.parent);
+}
+
+function bubbleUpDone(isolate: Nullable<TIsolate>): void {
+  if (isNullish(isolate)) {
+    return;
+  }
+
+  if (!IsolateInspector.isHasPending(isolate)) {
+    return;
+  }
+
+  const result = IsolateMutator.setStatus(isolate, IsolateStatus.DONE, isolate);
+
+  if (isFailure(result)) {
+    return;
+  }
+
+  bubbleUpDone(isolate.parent);
+}
+
+export class IsolateMutator {
+  static setParent(isolate: TIsolate, parent: Nullable<TIsolate>): TIsolate {
+    isolate.parent = parent;
+    return isolate;
+  }
+
+  static saveOutput(isolate: TIsolate, output: any): TIsolate {
+    isolate.output = output;
+    return isolate;
+  }
+
+  static setKey(isolate: TIsolate, key: Nullable<string>): TIsolate {
+    isolate.key = key;
+    return isolate;
+  }
+
+  static addChild(isolate: TIsolate, child: TIsolate): void {
+    invariant(isolate);
+
+    isolate.children = isolate.children ?? [];
+
+    isolate.children.push(child);
+    IsolateMutator.setParent(child, isolate);
+
+    if (IsolateInspector.hasPending(child)) {
+      bubbleUpPending(isolate);
+    }
+  }
+
+  static removeChild(isolate: TIsolate, node: TIsolate): void {
+    isolate.children =
+      isolate.children?.filter(child => child !== node) ?? null;
+  }
+
+  static addChildKey(isolate: TIsolate, key: string, node: TIsolate): void {
+    invariant(isolate);
+
+    isolate.keys = isolate.keys ?? {};
+
+    isolate.keys[key] = node;
+  }
+
+  static slice(isolate: TIsolate, at: number): void {
+    if (isNullish(isolate.children)) {
+      return;
+    }
+    isolate.children.length = at;
+  }
+
+  static setData(isolate: TIsolate, data: any): void {
+    isolate.data = data;
+  }
+
+  static abort(isolate: TIsolate, reason?: string): void {
+    if (isNullish(isolate.abortController)) {
+      return;
+    }
+    isolate.abortController.abort(reason);
+  }
+
+  static setStatus(
+    isolate: TIsolate,
+    status: IsolateStatus,
+    payload?: any,
+  ): Result<IsolateStatus, string> {
+    if (isolate.status === status) {
+      return makeResult.Err(`Isolate status is already ${status}`);
+    }
+
+    isolate.status = IsolateStateMachine.staticTransition(
+      isolate.status ?? IsolateStatus.INITIAL,
+      status,
+      payload,
+    ) as IsolateStatus;
+
+    return makeResult.Ok(isolate.status);
+  }
+
+  static setPending(isolate: TIsolate): void {
+    const result = IsolateMutator.setStatus(isolate, IsolateStatus.PENDING);
+
+    if (isFailure(result)) {
+      return;
+    }
+
+    RuntimeApi.registerPending(isolate);
+
+    // Bubble up the HAS_PENDING status to all ancestors.
+    bubbleUpPending(isolate.parent);
+  }
+
+  static setHasPending(isolate: TIsolate): Result<IsolateStatus, string> {
+    return IsolateMutator.setStatus(isolate, IsolateStatus.HAS_PENDING);
+  }
+
+  static setDone(isolate: TIsolate): void {
+    const result = IsolateMutator.setStatus(
+      isolate,
+      IsolateStatus.DONE,
+      isolate,
+    );
+
+    if (isFailure(result)) {
+      return;
+    }
+
+    // Bubble up the DONE status to ancestors if no other children are pending.
+    bubbleUpDone(isolate.parent);
+
+    RuntimeApi.removePending(isolate);
+  }
+}

package/src/Isolate/IsolateRegistry.ts

@@ -0,0 +1,176 @@
+import { Nullable, isEmptySet, isNotEmptySet } from 'vest-utils';
+
+import { useAvailableRoot } from '../VestRuntime';
+import { TIsolate } from './Isolate';
+
+/**
+ * A registry index, mapping group keys (like field names) to sets of isolates.
+ */
+export type RegistryIndex = Map<string, Set<TIsolate>>;
+
+/**
+ * Configuration for a registry category.
+ */
+export type RegistryCategoryConfig = {
+  predicate: (isolate: TIsolate) => boolean;
+  getKey: (isolate: TIsolate) => string;
+};
+
+/**
+ * Updates the registration of an isolate in all relevant indices based on provided predicates.
+ *
+ * @param isolate - The isolate node to update.
+ * @param predicates - A record of category keys and their corresponding predicate configurations.
+ */
+export function useUpdateRegistry(
+  isolate: TIsolate,
+  predicates: Record<string, RegistryCategoryConfig>,
+) {
+  const root = useGetAvailableRoot();
+
+  if (!root) return;
+
+  for (const key in predicates) {
+    useUpdateCategoryInRegistry(root, key, predicates[key], isolate);
+  }
+}
+
+/**
+ * Retrieves isolates from the registry based on a category and an optional key.
+ */
+export function useGetFromRegistry(
+  category: string,
+  key?: string,
+): Set<TIsolate> {
+  const root = useGetAvailableRoot();
+  if (!root) return new Set();
+
+  const index = useEnsureRegistryIndex(root, category);
+
+  if (key) {
+    return index.get(key) ?? new Set();
+  }
+
+  const allNodes = new Set<TIsolate>();
+  index.forEach(set => set.forEach(node => allNodes.add(node)));
+  return allNodes;
+}
+
+/**
+ * Checks if the registry contains any isolates for a given category and optional key.
+ */
+export function useHasFromRegistry(category: string, key?: string): boolean {
+  return isNotEmptySet(useGetFromRegistry(category, key));
+}
+
+/**
+ * Removes all entries for a specific key from the registry.
+ */
+export function useRemoveFieldFromRegistry(key: string): void {
+  const root = useGetAvailableRoot();
+
+  if (!root) return;
+
+  useForEachRegistryIndex(root, index => index.delete(key));
+}
+
+/**
+ * Clears all registry entries from the root isolate.
+ */
+export function useClearRegistry(root: TIsolate) {
+  useForEachRegistryIndex(root, index => index.clear());
+}
+
+// Internal Helpers
+
+const GENERIC_REGISTRY_KEY = '_generic';
+
+function useGetAvailableRoot(): TIsolate | undefined {
+  try {
+    return useAvailableRoot();
+  } catch {
+    return undefined;
+  }
+}
+
+function useUpdateCategoryInRegistry(
+  root: TIsolate,
+  category: string,
+  config: RegistryCategoryConfig,
+  isolate: TIsolate,
+) {
+  const isMatching = config.predicate(isolate);
+  const index = useEnsureRegistryIndex(root, category);
+  const key = config.getKey(isolate);
+
+  if (isMatching) {
+    useAddNodeToRegistryIndex(index, key, isolate);
+  } else {
+    useRemoveNodeFromRegistryIndex(index, key, isolate);
+  }
+}
+
+function useEnsureRegistryIndex(
+  root: TIsolate,
+  category: string,
+): RegistryIndex {
+  const registryKey = `registry_${category}`;
+
+  if (!root.data[registryKey]) {
+    useDefineEnumerable(root.data, registryKey, new Map());
+  }
+
+  return root.data[registryKey];
+}
+
+function useForEachRegistryIndex(
+  root: TIsolate,
+  callback: (index: RegistryIndex) => void,
+) {
+  for (const key in root.data) {
+    if (key.startsWith('registry_')) {
+      callback(root.data[key]);
+    }
+  }
+}
+
+function useAddNodeToRegistryIndex(
+  index: RegistryIndex,
+  key: Nullable<string>,
+  isolate: TIsolate,
+) {
+  const indexKey = key ?? GENERIC_REGISTRY_KEY;
+  let entry = index.get(indexKey);
+
+  if (!entry) {
+    entry = new Set();
+    index.set(indexKey, entry);
+  }
+
+  entry.add(isolate);
+}
+
+function useRemoveNodeFromRegistryIndex(
+  index: RegistryIndex,
+  key: Nullable<string>,
+  isolate: TIsolate,
+) {
+  const indexKey = key ?? GENERIC_REGISTRY_KEY;
+  const entry = index.get(indexKey);
+
+  if (entry) {
+    entry.delete(isolate);
+    if (isEmptySet(entry)) {
+      index.delete(indexKey);
+    }
+  }
+}
+
+function useDefineEnumerable(obj: any, key: string, value: any) {
+  Object.defineProperty(obj, key, {
+    configurable: true,
+    enumerable: true,
+    value,
+    writable: true,
+  });
+}

package/src/Isolate/IsolateReorderable.ts

@@ -0,0 +1,11 @@
+import { CB } from 'vest-utils';
+
+import { Isolate } from './Isolate';
+
+export function IsolateReorderable(
+  callback: CB,
+  type = 'Reorderable',
+  payload: Record<string, any> = {},
+) {
+  return Isolate.create(type, callback, { ...payload, allowReorder: true });
+}

package/src/Isolate/IsolateSelectors.ts

@@ -0,0 +1,25 @@
+import { Maybe } from 'vest-utils';
+
+import { TIsolate } from './Isolate';
+import { IsolateKeys } from './IsolateKeys';
+
+export function isIsolateType<I extends TIsolate>(
+  node: Maybe<TIsolate>,
+  type: string,
+): node is I {
+  return node?.[IsolateKeys.Type] === type;
+}
+
+export function isSameIsolateType<A extends TIsolate, B extends TIsolate>(
+  a: A,
+  b: B,
+): boolean {
+  return isIsolateType(a, b[IsolateKeys.Type]);
+}
+
+export function isSameIsolateIdentity<A extends TIsolate, B extends TIsolate>(
+  a: A,
+  b: B,
+): boolean {
+  return Object.is(a, b) || (isSameIsolateType(a, b) && a.key === b.key);
+}

package/src/Isolate/IsolateStateMachine.ts

@@ -0,0 +1,30 @@
+import { StateMachine, TStateMachine } from 'vest-utils';
+
+import { TIsolate } from './Isolate';
+import { IsolateInspector } from './IsolateInspector';
+
+import { IsolateStatus } from './IsolateStatus';
+
+const machine: TStateMachine<IsolateStatus> = {
+  initial: IsolateStatus.INITIAL,
+  states: {
+    [IsolateStatus.DONE]: {},
+    [IsolateStatus.INITIAL]: {
+      [IsolateStatus.PENDING]: IsolateStatus.PENDING,
+      [IsolateStatus.HAS_PENDING]: IsolateStatus.HAS_PENDING,
+      [IsolateStatus.DONE]: IsolateStatus.DONE,
+    },
+    [IsolateStatus.PENDING]: {
+      [IsolateStatus.DONE]: IsolateStatus.DONE,
+    },
+    [IsolateStatus.HAS_PENDING]: {
+      [IsolateStatus.DONE]: [
+        IsolateStatus.DONE,
+        (isolate: TIsolate) => !IsolateInspector.hasActiveChildren(isolate),
+      ],
+      [IsolateStatus.PENDING]: IsolateStatus.PENDING,
+    },
+  },
+};
+
+export const IsolateStateMachine = StateMachine(machine);

package/src/Isolate/IsolateStatus.ts

@@ -0,0 +1,8 @@
+export const IsolateStatus = {
+  DONE: 'DONE',
+  HAS_PENDING: 'HAS_PENDING',
+  INITIAL: 'INITIAL',
+  PENDING: 'PENDING',
+} as const;
+
+export type IsolateStatus = (typeof IsolateStatus)[keyof typeof IsolateStatus];

package/src/Isolate/IsolateTransient.ts

@@ -0,0 +1,27 @@
+import { CB } from 'vest-utils';
+
+import { Isolate } from './Isolate';
+import type { IsolatePayload, TIsolate } from './IsolateTypes';
+
+/**
+ * Creates a transient isolate.
+ *
+ * Transient isolates are isolates that:
+ * 1. Do not persist in the history tree.
+ * 2. Are not reconciled with previous runs.
+ * 3. Do not appear in the serialized suite dump.
+ * 4. Do not interfere with the index of their siblings (they are skipped by the reconciler).
+ *
+ * This is useful for "structural" isolates that are used for control flow or grouping
+ * but do not hold state that needs to be preserved between runs, such as `focused` (skip/only) isolates.
+ */
+export function IsolateTransient<Payload extends IsolatePayload>(
+  callback: CB,
+  type = 'Transient',
+  payload: Payload = {} as Payload,
+): TIsolate<Payload> {
+  return Isolate.create<Payload>(type, callback, {
+    ...payload,
+    transient: true,
+  });
+}