vestjs-runtime 1.7.0 → 2.0.2

package/src/__tests__/Reconciler.transient.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect, vi } from 'vitest';
+import { CB } from 'vest-utils';
+
+import { IReconciler } from '../Reconciler';
+import { Isolate, TIsolate } from '../Isolate/Isolate';
+import * as VestRuntime from '../VestRuntime';
+import { StateRefType } from '../VestRuntime';
+
+/**
+ * A reconciler that returns the history node when types match,
+ * causing Isolate.create to skip the callback (reconciled, not re-run).
+ * When types don't match or history is missing, it returns null
+ * so the node runs as new.
+ */
+function reuseReconciler(
+  currentNode: TIsolate,
+  historyNode: TIsolate,
+): TIsolate | null {
+  // Always re-run Root so its callback executes and creates children.
+  if (currentNode.$type === 'Root') {
+    return null;
+  }
+  if (currentNode.$type === historyNode.$type) {
+    return historyNode;
+  }
+  return null;
+}
+
+describe('Reconciler: Transient Isolates', () => {
+  function withRunTime<T>(stateRef: StateRefType, fn: CB<T>) {
+    return VestRuntime.Run(stateRef, () => fn());
+  }
+
+  /**
+   * Creates a fresh history tree. Uses a pass-through reconciler
+   * (returns null → BaseReconciler → runs as new) so all callbacks execute.
+   */
+  function createHistory(fn: CB): TIsolate {
+    const tempRef = VestRuntime.createRef(
+      (() => null) as unknown as IReconciler,
+      v => v,
+    );
+    let root!: TIsolate;
+    withRunTime(tempRef, () => {
+      root = fn();
+    });
+    return root;
+  }
+
+  /**
+   * Creates a stateRef wired to the `reuseReconciler` and seeds it
+   * with the given history root.
+   */
+  function createReconcilerRef(historyRoot: TIsolate): StateRefType {
+    const ref = VestRuntime.createRef(
+      reuseReconciler as unknown as IReconciler,
+      v => v,
+    );
+    const [, setHistory] = ref.historyRoot();
+    setHistory(historyRoot);
+    return ref;
+  }
+
+  type NodeSpec = { type: string; key?: string; transient?: boolean };
+
+  function buildTree(specs: NodeSpec[]): CB {
+    return () =>
+      Isolate.create('Root', () => {
+        for (const spec of specs) {
+          Isolate.create(
+            spec.type,
+            () => {},
+            spec.transient ? { transient: true } : {},
+            spec.key ?? null,
+          );
+        }
+      });
+  }
+
+  const A: NodeSpec = { type: 'Test', key: 'A' };
+  const B: NodeSpec = { type: 'Test', key: 'B' };
+  const T: NodeSpec = { type: 'Skip', transient: true };
+
+  it.each([
+    {
+      label: 'Adding: History [A, B] → Current [A, T, B]',
+      history: [A, B],
+      current: [A, T, B],
+      callsA: 0,
+      callsB: 0,
+    },
+    {
+      label: 'Removing: History [A, T, B] → Current [A, B]',
+      history: [A, T, B],
+      current: [A, B],
+      callsA: 0,
+      callsB: 0,
+    },
+    {
+      label: 'Moving: History [T, A, B] → Current [A, T, B]',
+      history: [T, A, B],
+      current: [A, T, B],
+      callsA: 0,
+      callsB: 0,
+    },
+    {
+      label: 'Baseline: History [A, B] → Current [A, B]',
+      history: [A, B],
+      current: [A, B],
+      callsA: 0,
+      callsB: 0,
+    },
+    {
+      label: 'New node: History [A] → Current [A, B]',
+      history: [A],
+      current: [A, B],
+      callsA: 0,
+      callsB: 1,
+    },
+  ])(
+    '$label',
+    ({ history, current, callsA: expectedCallsA, callsB: expectedCallsB }) => {
+      const cbA = vi.fn();
+      const cbB = vi.fn();
+
+      const historyRoot = createHistory(buildTree(history));
+
+      const ref = createReconcilerRef(historyRoot);
+      withRunTime(ref, () => {
+        Isolate.create('Root', () => {
+          for (const spec of current) {
+            const cb =
+              spec.key === 'A' ? cbA : spec.key === 'B' ? cbB : () => {};
+            Isolate.create(
+              spec.type,
+              cb,
+              spec.transient ? { transient: true } : {},
+              spec.key ?? null,
+            );
+          }
+        });
+      });
+
+      expect(cbA).toHaveBeenCalledTimes(expectedCallsA);
+      expect(cbB).toHaveBeenCalledTimes(expectedCallsB);
+    },
+  );
+
+  it('Transient callback itself DOES run (it has no history)', () => {
+    const cbTrans = vi.fn();
+
+    const historyRoot = createHistory(buildTree([A, B]));
+
+    const ref = createReconcilerRef(historyRoot);
+    withRunTime(ref, () => {
+      Isolate.create('Root', () => {
+        Isolate.create('Test', () => {}, {}, 'A');
+        Isolate.create('Skip', cbTrans, { transient: true });
+        Isolate.create('Test', () => {}, {}, 'B');
+      });
+    });
+
+    // Transient nodes always run as new
+    expect(cbTrans).toHaveBeenCalledOnce();
+  });
+});

package/src/__tests__/VestRuntime.test.ts

@@ -0,0 +1,212 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  Run,
+  createRef,
+  useCurrentCursor,
+  useSetIsolateKey,
+} from '../VestRuntime';
+import { IReconciler } from '../Reconciler';
+import * as VestRuntime from '../VestRuntime';
+import { IsolateInspector } from '../Isolate/IsolateInspector';
+import { IsolateMutator } from '../Isolate/IsolateMutator';
+
+import { ErrorStrings } from '../errors/ErrorStrings';
+import { deferThrow, text } from 'vest-utils';
+import { FocusModes, VestIsolateTypeFocused } from '../Isolate/IsolateFocused';
+
+vi.mock('../Isolate/IsolateInspector', () => ({
+  IsolateInspector: {
+    cursor: vi.fn(),
+    getChildByKey: vi.fn(),
+  },
+}));
+
+vi.mock('../IsolateWalker', () => ({
+  findClosest: vi.fn(),
+}));
+
+vi.mock('../Isolate/IsolateMutator', () => ({
+  IsolateMutator: {
+    addChildKey: vi.fn(),
+    addChild: vi.fn(),
+    setParent: vi.fn(),
+  },
+}));
+
+vi.mock('vest-utils', async importOriginal => {
+  const actual = await importOriginal();
+  return {
+    ...(actual as any),
+    deferThrow: vi.fn(),
+    text: vi.fn(str => str),
+    invariant: vi.fn(),
+  };
+});
+
+vi.mock('context', () => ({
+  createCascade: () => ({
+    run: (stateRef: any, fn: () => void) => {
+      // Create a mutable object
+      const ctx = { stateRef, runtimeNode: null };
+      // Make it accessible to useX via closure?
+      // This closure is per createCascade call.
+      // VestRuntime calls createCascade once at top level.
+      // So this works perfectly.
+      (global as any).__mockCtx = ctx;
+      return fn();
+    },
+    useX: () => (global as any).__mockCtx,
+    use: () => (global as any).__mockCtx,
+  }),
+}));
+
+describe('VestRuntime', () => {
+  let reconciler: IReconciler;
+
+  beforeEach(() => {
+    reconciler = vi.fn();
+    vi.resetAllMocks();
+  });
+
+  const withRun = (fn: () => void, runtimeNode: any = null) => {
+    const ref = createRef(reconciler, {} as any);
+    // Determine how to inject runtimeNode?
+    // ref is internal state.
+    // 'runtimeNode' property in context.
+    // Run(ref, fn) -> PersistedContext.run sets the context.
+
+    // We can't easily inject runtimeNode via `createRef`.
+    // But we can use `PersistedContext.run(ctx, ...)` if we had access.
+    // `createCascade` returns an object with `run`.
+
+    // We can use a trick:
+    // Run(ref, () => {
+    //    // Inside here, useX().runtimeNode = runtimeNode;
+    //    // But `runtimeNode` is on `CTXType` which `useX()` returns.
+    //    // In `VestRuntime.ts`, `useX` returns `CTXType`.
+    //    // We can mutate it!
+    //    if (runtimeNode) {
+    //      const ctx = VestRuntime.useX();
+    //      ctx.runtimeNode = runtimeNode;
+    //    }
+    //    fn();
+    // });
+
+    Run(ref, () => {
+      if (runtimeNode) {
+        // @ts-ignore
+        VestRuntime.useX().runtimeNode = runtimeNode;
+      }
+      fn();
+    });
+  };
+
+  describe('useCurrentCursor', () => {
+    it('Should return 0 when there is no active isolate', () => {
+      withRun(() => {
+        expect(useCurrentCursor()).toBe(0);
+      });
+    });
+
+    it('Should return the cursor of the active isolate', () => {
+      const node = { $type: 'test' };
+      vi.mocked(IsolateInspector.cursor).mockReturnValue(10);
+
+      withRun(() => {
+        expect(useCurrentCursor()).toBe(10);
+        expect(IsolateInspector.cursor).toHaveBeenCalledWith(node);
+      }, node);
+    });
+  });
+
+  describe('useSetIsolateKey', () => {
+    it('Should return early if key is null', () => {
+      withRun(() => {
+        useSetIsolateKey(null, {} as any);
+        expect(true).toBe(true);
+      });
+    });
+
+    it('Should add child key if not exists', () => {
+      const node = { $type: 'child' };
+      const parent = { $type: 'parent' };
+
+      vi.mocked(IsolateInspector.getChildByKey).mockReturnValue(null);
+
+      withRun(() => {
+        useSetIsolateKey('key1', node as any);
+        expect(IsolateMutator.addChildKey).toHaveBeenCalledWith(
+          parent,
+          'key1',
+          node,
+        );
+      }, parent);
+    });
+
+    it('Should deferThrow if key exists', () => {
+      const node = { $type: 'child' };
+      const parent = { $type: 'parent' };
+
+      vi.mocked(IsolateInspector.getChildByKey).mockReturnValue({} as any);
+
+      withRun(() => {
+        useSetIsolateKey('key1', node as any);
+        expect(deferThrow).toHaveBeenCalled();
+        expect(text).toHaveBeenCalledWith(
+          ErrorStrings.ENCOUNTERED_THE_SAME_KEY_TWICE,
+          { key: 'key1' },
+        );
+        expect(IsolateMutator.addChildKey).not.toHaveBeenCalled();
+      }, parent);
+    });
+  });
+
+  describe('useSetNextIsolateChild', () => {
+    it('Should add child to current isolate and set parent', () => {
+      const parent = { $type: 'Parent' };
+      const child = { $type: 'Child' };
+      withRun(() => {
+        VestRuntime.useSetNextIsolateChild(child as any);
+        expect(IsolateMutator.addChild).toHaveBeenCalledWith(parent, child);
+        expect(IsolateMutator.setParent).toHaveBeenCalledWith(child, parent);
+      }, parent);
+    });
+
+    it('Should add parent to implicitOnlyNodes if child is ONLY focused', () => {
+      const parent = { $type: 'Parent' };
+      const child = {
+        $type: VestIsolateTypeFocused,
+        data: { focusMode: FocusModes.ONLY },
+      };
+      withRun(() => {
+        VestRuntime.useSetNextIsolateChild(child as any);
+        const ctx = (global as any).__mockCtx;
+        expect(ctx.stateRef.implicitOnlyNodes.has(parent)).toBe(true);
+      }, parent);
+    });
+  });
+
+  describe('hasImplicitOnly', () => {
+    it('Should return true if an ancestor is in implicitOnlyNodes', () => {
+      const grandparent = { $type: 'Grandparent' };
+      const parent = { $type: 'Parent', parent: grandparent };
+      const child = { $type: 'Child', parent };
+
+      withRun(() => {
+        const ctx = (global as any).__mockCtx;
+        ctx.stateRef.implicitOnlyNodes.add(grandparent);
+        // The current node is `child`
+        expect(VestRuntime.useIsFocusedOut()).toBe(true);
+      }, child);
+    });
+
+    it('Should return false if no ancestor is in implicitOnlyNodes', () => {
+      const parent = { $type: 'Parent' };
+      const child = { $type: 'Child', parent };
+
+      withRun(() => {
+        expect(VestRuntime.useIsFocusedOut()).toBe(false);
+      }, child);
+    });
+  });
+});

package/src/__tests__/VestRuntimeStateMachine.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import { VestRuntime } from '../vestjs-runtime';
+import { IsolateMutator } from '../Isolate/IsolateMutator';
+import { Isolate } from '../Isolate/Isolate';
+import { RuntimeState } from '../Orchestrator/RuntimeStates';
+
+describe('Runtime Orchestration', () => {
+  it('Should transition to PENDING if an isolate is pending after mount', () => {
+    VestRuntime.Run(VestRuntime.createRef({} as any, {} as any), () => {
+      // Create a pending isolate
+      const isolate = Isolate.create('test', async () => {
+        await new Promise(() => {});
+      });
+
+      IsolateMutator.setParent(isolate, VestRuntime.useAvailableRoot());
+      IsolateMutator.setPending(isolate);
+
+      expect(VestRuntime.useRuntimeState()).toBe(RuntimeState.PENDING);
+    });
+  });
+
+  it('Should transition to STABLE when pending isolate is done', () => {
+    VestRuntime.Run(VestRuntime.createRef({} as any, {} as any), () => {
+      const isolate = Isolate.create('test', async () => {
+        await new Promise(() => {});
+      });
+      IsolateMutator.setParent(isolate, VestRuntime.useAvailableRoot());
+      IsolateMutator.setPending(isolate);
+
+      // Mark as done
+      IsolateMutator.setDone(isolate);
+
+      expect(VestRuntime.useRuntimeState()).toBe(RuntimeState.STABLE);
+    });
+  });
+});

package/src/__tests__/vestjs-runtime.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from 'vitest';
+import * as VestJSRuntime from '../vestjs-runtime';
+
+describe('vestjs-runtime exports', () => {
+  it('should export public API', () => {
+    expect(VestJSRuntime.Isolate).toBeDefined();
+    expect(VestJSRuntime.IsolateKeys).toBeDefined();
+    expect(VestJSRuntime.Reconciler).toBeDefined();
+    expect(VestJSRuntime.Walker).toBeDefined();
+    expect(VestJSRuntime.VestRuntime).toBeDefined();
+    expect(VestJSRuntime.IsolateInspector).toBeDefined();
+    expect(VestJSRuntime.IsolateMutator).toBeDefined();
+    expect(VestJSRuntime.Bus).toBeDefined();
+    expect(VestJSRuntime.IsolateSelectors).toBeDefined();
+    expect(VestJSRuntime.IsolateSerializer).toBeDefined();
+    expect(VestJSRuntime.IsolateStatus).toBeDefined();
+    expect(VestJSRuntime.IsolateStateMachine).toBeDefined();
+  });
+});

package/src/errors/ErrorStrings.ts

@@ -0,0 +1,6 @@
+export enum ErrorStrings {
+  NO_ACTIVE_ISOLATE = 'Not within an active isolate',
+  UNABLE_TO_PICK_NEXT_ISOLATE = 'Unable to pick next isolate. This is a bug, please report it to the Vest maintainers.',
+  ENCOUNTERED_THE_SAME_KEY_TWICE = `Encountered the same key "{key}" twice. This may lead to inconsistent or overriding of results.`,
+  INVALID_ISOLATE_CANNOT_PARSE = `Invalid isolate was passed to IsolateSerializer. Cannot proceed.`,
+}

package/src/exports/IsolateSerializer.ts

@@ -0,0 +1,131 @@
+import {
+  Nullable,
+  hasOwnProperty,
+  isNullish,
+  isStringValue,
+  isFailure,
+  text,
+  makeResult,
+  Result,
+  isUnsafeKey,
+} from 'vest-utils';
+import { expandObject, minifyObject } from 'vest-utils/minifyObject';
+
+import { TIsolate } from '../Isolate/Isolate';
+import { ExcludedFromDump, IsolateKeys } from '../Isolate/IsolateKeys';
+import { IsolateMutator } from '../Isolate/IsolateMutator';
+import { ErrorStrings } from '../errors/ErrorStrings';
+
+export class IsolateSerializer {
+  static safeDeserialize(
+    node: Record<string, any> | TIsolate | string,
+  ): Result<TIsolate, Error> {
+    try {
+      const expanded = expandNode(node);
+      if (isFailure(IsolateSerializer.validateIsolate(expanded))) {
+        return makeResult.Err(
+          new Error(ErrorStrings.INVALID_ISOLATE_CANNOT_PARSE),
+        );
+      }
+      return makeResult.Ok(hydrateIsolate(expanded));
+    } catch (error) {
+      return makeResult.Err(
+        error instanceof Error ? error : new Error(String(error)),
+      );
+    }
+  }
+
+  static deserialize(node: Record<string, any> | TIsolate | string): TIsolate {
+    const result = IsolateSerializer.safeDeserialize(node);
+    return result.unwrap();
+  }
+
+  static serialize(
+    isolate: Nullable<TIsolate>,
+    replacer?: (value: any, key: string) => any,
+  ): string {
+    if (isNullish(isolate)) {
+      return '';
+    }
+
+    const minified = minifyObject(isolate, (value: any, key: string) => {
+      if (ExcludedFromDump.has(key as any)) {
+        return undefined;
+      }
+
+      // Drop transient nodes — returning undefined causes
+      // minifyObject to skip the entry entirely.
+      // Transient nodes are not part of the persistent state
+      // and should not be serialized.
+      if (value?.transient) {
+        return undefined;
+      }
+
+      if (replacer) {
+        return replacer(value, key);
+      }
+      return value;
+    });
+
+    return JSON.stringify(minified);
+  }
+
+  static validateIsolate(
+    node: Record<string, any> | TIsolate,
+  ): Result<TIsolate, string> {
+    return hasOwnProperty(node, IsolateKeys.Type)
+      ? makeResult.Ok(node as TIsolate)
+      : makeResult.Err(text(ErrorStrings.INVALID_ISOLATE_CANNOT_PARSE));
+  }
+}
+
+function processChildren(current: TIsolate, queue: TIsolate[]): void {
+  const children = current.children;
+
+  if (!children) {
+    return;
+  }
+
+  current.children = children.map(child => {
+    const nextChild = { ...child };
+
+    IsolateMutator.setParent(nextChild, current);
+    queue.push(nextChild);
+
+    if (nextChild.key) {
+      current.keys = current.keys ?? {};
+      current.keys[nextChild.key] = nextChild;
+    }
+
+    return nextChild;
+  });
+}
+
+function hydrateIsolate(root: TIsolate): TIsolate {
+  const queue = [root];
+
+  while (queue.length) {
+    const current = queue.shift();
+    if (current) {
+      processChildren(current, queue);
+    }
+  }
+
+  return root;
+}
+
+function expandNode(node: Record<string, any> | TIsolate | string): TIsolate {
+  const parsed = isStringValue(node)
+    ? JSON.parse(node, safeReviver)
+    : ({ ...node } as TIsolate);
+  const root = Array.isArray(parsed) ? parsed : [parsed, {}];
+  const expanded = expandObject(root[0], root[1]);
+  return expanded as TIsolate;
+}
+
+function safeReviver(key: string, value: any): any {
+  if (isUnsafeKey(key)) {
+    return;
+  }
+  return value;
+}