vestjs-runtime 1.6.0 → 1.7.0

package/docs/IsolateRegistry.docs.md

@@ -1,146 +0,0 @@
-# Isolate Registry Architecture & API
-
-The Isolate Registry is a high-performance, O(1) indexing system that tracks isolates based on configurable predicates and keys. It eliminates the need for expensive tree traversals when calculating suite results or checking test statuses.
-
-## 🏗️ Architecture
-
-The Registry is divided into two layers:
-
-1.  **Generic Engine (`vestjs-runtime/IsolateRegistry`)**: A predicated indexing engine with **configurable key selectors**. It manages maps of sets on the root isolate and is completely agnostic to both the predicates and key extraction logic.
-2.  **Vest Configuration (`vest/TestRegistry`)**: Defines the categories (failed, pending, etc.) and provides **both predicates and key selectors** (e.g., extracting `fieldName` from test data).
-
-### Key Configuration (`RegistryCategoryConfig`)
-
-Each category is defined by:
-
-```typescript
-type RegistryCategoryConfig = {
-  predicate: (isolate: TIsolate) => boolean; // What isolates match this category?
-  getKey: (isolate: TIsolate) => string; // How to group them (e.g., by fieldName)?
-};
-```
-
-This decoupling allows `vestjs-runtime` to remain **domain-agnostic** while Vest defines how to extract keys from its test data.
-
-## 🏗️ Structure & Location
-
-The registry is stateful and is stored directly on the **Root Isolate** of a suite.
-
-### Storage Location
-
-Each category is stored in the `root.data` object with a `registry_` prefix:
-
-- `root.data.registry_failed`
-- `root.data.registry_pending`
-- ...and so on.
-
-### Shape
-
-Each registry entry is a `RegistryIndex`:
-
-```typescript
-type RegistryIndex = Map<string, Set<TIsolate>>;
-```
-
-- **Key**: Determined by the `getKey` function in the category config (e.g., `fieldName` for tests, or `_generic` for null keys).
-- **Value**: A `Set` containing all isolates currently matching that category.
-
----
-
-## 🔄 Update Lifecycle
-
-The registry is **reactive**. It re-evaluates its state whenever relevant events occur.
-
-### Flowchart
-
-```text
-       [ Isolate Event ]
-              |
-      ( Enter / Status Change )
-              |
-              v
-      useUpdateRegistry
-              |
-    +---------v-------------------+
-    | Iterates all Predicates     |
-    +---------|-------------------+
-              |
-    +---------v-------------------+
-    | For each Category:          |
-    | [Match?] --Yes--> [Add]     |
-    |    |-------No---> [Remove]  |
-    +---------|-------------------+
-              |
-              v
-    Root.data["registry_<category>"]
-```
-
-### When do updates happen?
-
-1.  **Initial Registration (`ISOLATED_ENTER`)**: When a node is first encountered.
-2.  **Status Changes (`setStatus`)**: When a test moves between states (e.g. Pending -> Failed).
-3.  **Cross-Suite Reconciliation**: When a tree is reprocessed or merged.
-4.  **Field Removal**: When `REMOVE_FIELD` is emitted, the registry cleans up all indexed categories for a specific field.
-
----
-
-## 🛠️ APIs
-
-### `IsolateCategory` (Vest specific)
-
-- `failed`: Tests with error severity.
-- `omitted`: Tests that were not run.
-- `passing`: Tests that passed.
-- `pending`: Tests currently in progress.
-- `tested`: Tests that have finished running.
-- `valid`: Tests that are either passing or warnings.
-- `warning`: Tests with warning severity.
-
-### Core Engine (`vestjs-runtime/IsolateRegistry`)
-
-#### `useUpdateRegistry(isolate, predicates)`
-
-```typescript
-useUpdateRegistry(
-  isolate: TIsolate,
-  predicates: Record<string, RegistryCategoryConfig>
-): void
-```
-
-Evaluates all predicates and updates the registry. For each category:
-
-- Calls `config.predicate(isolate)` to check if it matches
-- Calls `config.getKey(isolate)` to determine the index key
-- Adds to or removes from the appropriate registry index
-
-#### `useGetFromRegistry(category, key?)`
-
-```typescript
-useGetFromRegistry(category: string, key?: string): Set<TIsolate>
-```
-
-Retrieves isolates for a category. If `key` is provided (e.g., a fieldName), returns only isolates indexed under that key. Otherwise, returns all isolates in the category.
-
-#### `useHasFromRegistry(category, key?)`
-
-```typescript
-useHasFromRegistry(category: string, key?: string): boolean
-```
-
-Returns `true` if any isolates exist for the given criteria.
-
-#### `useRemoveFieldFromRegistry(key)`
-
-```typescript
-useRemoveFieldFromRegistry(key: string): void
-```
-
-Removes all entries for a specific key (e.g., fieldName) from all registry categories.
-
-#### `useClearRegistry(root)`
-
-```typescript
-useClearRegistry(root: TIsolate): void
-```
-
-Clears all registry indices from the root isolate. Used during tree reprocessing.

package/docs/Isolates.md

@@ -1,97 +0,0 @@
-# Isolates Architecture
-
-## What is an Isolate?
-
-In the `@vestjs-runtime`, an "Isolate" is the fundamental building block of the state and execution tree. Every piece of business logic or structural grouping—whether it's a test, a suite, a group, or a focus context—is represented as an Isolate.
-
-The term "isolate" stems from its purpose: creating an isolated context where functionality runs safely. When traversing the tree of isolates, each context is maintained correctly, preventing sibling states from polluting one another.
-
-Every Isolate contains at minimum:
-
-- `Type`: A string defining the nature of the Isolate (e.g. `'Test'`, `'Suite'`, `'Group'`).
-- `Parent` / `Children`: Linking to construct the overall state tree structure.
-- `Data`: Any metadata the Isolate requires to execute properly.
-- `Status`: Current state of resolution (e.g. `PENDING`, `DONE`).
-
----
-
-## Types of Isolates
-
-Isolates behave differently depending on their internal configurations and traits:
-
-### 1. Stateful Isolates (Default)
-
-Most isolates created with `Isolate.create()` are stateful. This means:
-
-- They persist in the internal history tree.
-- They are subject to reconciliation (comparing current vs previous states between executions).
-- They have a predefined order in the tree matching their execution sequence, which prevents unpredictable side-effects between runs.
-- **Example:** A `VestTest` or a `Group`. The runtime tracks how many tests successfully ran before.
-
-### 2. Transient Isolates
-
-Transient isolates act as "structural" or "control flow" isolates but don't hold state between runs.
-
-Characteristics of transient isolates:
-
-1. They **do not** persist in the history tree.
-2. They **are not** reconciled with previous runs.
-3. They **do not** appear in the serialized suite dump (no `.dump()` presence).
-4. They **do not interfere** with the indexing of siblings. Since they are transient, the runtime reconciler effectively skips them when aligning sibling child indices.
-
-These are primarily used as invisible "modifiers" that dictate logic over their children but hold no inherent measurable business-state of their own.
-
-- **Example:** `IsolateFocused` (used for `.only` and `.skip`).
-
----
-
-## Focus Capabilities (`IsolateFocused`)
-
-`IsolateFocused` is a specialized implementation of a Transient Isolate used to manage the `only` and `skip` execution boundaries.
-
-Because they are transient, testing an `only()` block will not incorrectly disrupt the index sequence of test components evaluated below it. It is strictly used as an execution-context layer.
-
-### How Focus Checking Works
-
-Focus checking uses a **two-tier approach**: explicit matching and implicit exclusion.
-
-#### 1. Explicit Focus Matching (`findClosest` — sibling-aware)
-
-`Walker.findClosest` traverses UP through ancestor levels, and at each level searches the **children** (siblings) for a matching `IsolateFocused` node. Because `only()` and `skip()` create transient isolates that are **siblings** of the tests they affect (not ancestors), the search must start from the test object itself to correctly find focus rules at the same tree level.
-
-**Important:** Starting from `useIsolate()` (the parent context) would be one level too high and would miss sibling focus isolates entirely. This is why the vest-level `useIsExcludedByField` passes the specific `testObject` to `findClosest`, while the runtime-level `useIsFocusedOut` starts from the current isolate context.
-
-If an explicit focus match is found:
-
-- **Skip-focused:** The test is excluded immediately.
-- **Only-focused:** The test is NOT excluded (it matched the only rule).
-
-#### 2. Implicit ONLY Identification (`hasImplicitOnly` — centralized registry)
-
-When no explicit focus match is found for a test, the runtime checks whether any ancestor scope contains an `ONLY` rule — meaning any test _not_ explicitly matched should be excluded.
-
-To keep this check **O(Depth)** performant — instead of O(N) traversing thousands of elements per check — the runtime maintains a centralized `implicitOnlyNodes` Set on the `StateRef` context. When an `IsolateFocused` node with `FocusModes.ONLY` is created, its **parent** is registered in this Set via `useSetNextIsolateChild`.
-
-When checking implicit exclusion, `hasImplicitOnly()` simply walks up the current node's ancestors and queries `implicitOnlyNodes.has(current)` at each level. This approach:
-
-- **Separates concerns:** The Isolate data model remains pure — no focus-specific flags on AST nodes.
-- **Is O(Depth):** Only walks the ancestor chain, not the full tree.
-- **Is centralized:** All implicit-only state lives on the runtime's `StateRef`, not scattered across nodes.
-
-### Interaction with `include()`
-
-At the vest application layer, `useIsExcludedByField` combines both tiers:
-
-1. Explicit focus match via `useClosestMatchingFocus(testObject, fieldName)`.
-2. If no match, falls back to `VestRuntime.hasImplicitOnly()`.
-3. If implicitly excluded, checks the `inclusion` map — `include()` rules can override implicit exclusion but **not** explicit `skip()`.
-
----
-
-## The Reconciler Core
-
-All isolates (except Transient ones) pass through the underlying Reconciler matching system. The reconciler evaluates:
-
-1. Is there an active existing node from the previous history tree in this slot?
-2. If yes: Can it be reused? (Bypassing execution to save processing).
-3. If no: The execution runs anew and is marked as new runtime history.

package/src/Bus.ts

@@ -1,46 +0,0 @@
-import { BusType, isNullish } from 'vest-utils';
-
-import { persist, useX } from './VestRuntime';
-import { RuntimeEvents } from './RuntimeEvents';
-
-export function useBus<
-  E extends Record<string, any> = RuntimeEvents,
->(): BusType<E> {
-  return useX().stateRef.Bus as unknown as BusType<E>;
-}
-
-/*
-  Returns an emitter, but it also has a shortcut for emitting an event immediately
-  by passing an event name.
-*/
-
-export function useEmit<
-  E extends Record<string, any> = RuntimeEvents,
-  T extends keyof E = keyof E,
->(
-  event: T,
-  ...args: E[T] extends void ? [payload?: E[T]] : [payload: E[T]]
-): void;
-export function useEmit<_E extends Record<string, any> = RuntimeEvents>(): (
-  event: string,
-  data?: any,
-) => void;
-export function useEmit(event?: string, data?: any): any {
-  const emit = useBus().emit;
-
-  if (!isNullish(event)) {
-    // @ts-ignore - We're allowing any event name here because the bus might be extended
-    emit(event, data);
-  }
-
-  return persist(emit);
-}
-
-export function usePrepareEmitter<
-  E extends Record<string, any> = RuntimeEvents,
-  T extends keyof E = keyof E,
->(event: T): (arg: E[T]) => void {
-  const emit = useEmit<E>();
-
-  return (arg: E[T]) => emit(event as string, arg);
-}

package/src/Isolate/Isolate.ts

@@ -1,163 +0,0 @@
-import { CB, Maybe, Nullable, isNotNullish, isPromise } from 'vest-utils';
-
-import { useEmit } from '../Bus';
-import { Reconciler } from '../Reconciler';
-import * as VestRuntime from '../VestRuntime';
-
-import { IsolateKeys } from './IsolateKeys';
-import { IsolateMutator } from './IsolateMutator';
-import { IsolateStatus } from './IsolateStatus';
-import type { IsolateKey, IsolatePayload, TIsolate } from './IsolateTypes';
-
-export { IsolateKey, TIsolate };
-
-export class Isolate {
-  // eslint-disable-next-line max-statements
-  static create<Payload extends IsolatePayload>(
-    type: string,
-    callback: CB,
-    payload: Maybe<Payload> = undefined,
-    key?: IsolateKey,
-  ): TIsolate<Payload> {
-    const parent = VestRuntime.useIsolate();
-
-    const newCreatedNode = IsolateMutator.setParent(
-      baseIsolate(type, payload, key),
-      parent,
-    );
-
-    const nextIsolateChild = Reconciler.reconcile(newCreatedNode);
-
-    const localHistoryNode = VestRuntime.useHistoryIsolateAtCurrentPosition();
-
-    const shouldRunNew = Object.is(nextIsolateChild, newCreatedNode);
-
-    if (parent) {
-      // We are within an isolate context. This means that
-      // we need to set the new node to be the child of this parent node.
-      VestRuntime.useSetNextIsolateChild(nextIsolateChild);
-    }
-
-    let output;
-
-    if (shouldRunNew) {
-      output = useRunAsNew(localHistoryNode, newCreatedNode, callback);
-    } else {
-      const emit = useEmit();
-      output = nextIsolateChild.output;
-      emit('ISOLATE_RECONCILED', nextIsolateChild);
-    }
-
-    IsolateMutator.saveOutput(nextIsolateChild, output);
-
-    if (!parent) {
-      // We're exiting the node, and there is no parent. This means
-      // that we're at the top level and this node should be set
-      // as the new root of the history tree.
-      VestRuntime.useSetHistoryRoot(nextIsolateChild);
-    }
-
-    return nextIsolateChild as TIsolate<Payload>;
-  }
-
-  static isIsolate(node: any): node is TIsolate {
-    return isNotNullish(node) && node[IsolateKeys.Type];
-  }
-}
-
-/**
- * Creates a new child isolate context where the local history node is the current history node, thus advancing the history cursor.
- * Runs the callback function and returns its output.
- * @param localHistoryNode The local history node.
- * @param current The current isolate.
- * @param callback The callback function to execute.
- * @returns The output of the callback function.
- */
-function useRunAsNew<Callback extends CB = CB>(
-  localHistoryNode: Nullable<TIsolate>,
-  current: TIsolate,
-  callback: CB,
-): ReturnType<Callback> {
-  const runtimeRoot = VestRuntime.useRuntimeRoot();
-
-  // We're creating a new child isolate context where the local history node
-  // is the current history node, thus advancing the history cursor.
-  const output = VestRuntime.Run(
-    {
-      historyNode: localHistoryNode,
-      runtimeNode: current,
-      ...(!runtimeRoot && { runtimeRoot: current }),
-    },
-    () => useRunAsNewCallback(current, callback),
-  );
-
-  current.output = output;
-  return output;
-}
-
-function useRunAsNewCallback(current: TIsolate, callback: CB): any {
-  const emit = useEmit();
-  emit('ISOLATE_ENTER', current);
-  const output = callback(current);
-
-  if (isPromise(output)) {
-    emit('ISOLATE_PENDING', current);
-    IsolateMutator.setPending(current);
-    output.then(
-      VestRuntime.persist(iso => {
-        if (Isolate.isIsolate(iso)) {
-          IsolateMutator.addChild(current, iso);
-        }
-
-        IsolateMutator.setDone(current);
-        emit('ASYNC_ISOLATE_DONE', current);
-      }),
-      VestRuntime.persist(() => {
-        IsolateMutator.setDone(current);
-        emit('ASYNC_ISOLATE_DONE', current);
-      }),
-    );
-  } else {
-    IsolateMutator.setDone(current);
-  }
-
-  return output;
-}
-
-class IsolateInstance implements TIsolate {
-  [IsolateKeys.Type]: string;
-  children: Nullable<TIsolate[]> = null;
-  [IsolateKeys.Keys]: Nullable<Record<string, TIsolate>> = null;
-  [IsolateKeys.Parent]: Nullable<TIsolate> = null;
-  output: any = null;
-  key: IsolateKey = null;
-  [IsolateKeys.AllowReorder]: Maybe<boolean> = undefined;
-  [IsolateKeys.Transient]: Maybe<boolean> = undefined;
-  [IsolateKeys.Status]: IsolateStatus = IsolateStatus.INITIAL;
-  [IsolateKeys.AbortController]: Nullable<AbortController> = null;
-  [IsolateKeys.Data]: Maybe<any>;
-
-  constructor(
-    type: string,
-    payload: Maybe<IsolatePayload> = undefined,
-    key: IsolateKey = null,
-  ) {
-    this[IsolateKeys.Type] = type;
-    this.key = key;
-    const { allowReorder, transient, status, ...data } = payload ?? {};
-    this[IsolateKeys.AllowReorder] = allowReorder;
-    this[IsolateKeys.Transient] = transient;
-    if (status) {
-      this[IsolateKeys.Status] = status;
-    }
-    this[IsolateKeys.Data] = data;
-  }
-}
-
-function baseIsolate(
-  type: string,
-  payload: Maybe<IsolatePayload> = undefined,
-  key: IsolateKey = null,
-): TIsolate {
-  return new IsolateInstance(type, payload, key);
-}

package/src/Isolate/IsolateFocused.ts

@@ -1,93 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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

@@ -1,93 +0,0 @@
-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

@@ -1,18 +0,0 @@
-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,
-]);