@assistant-ui/tap 0.3.4 → 0.3.5

package/src/__tests__/rules/rules.hook-order.test.ts

@@ -0,0 +1,192 @@
+import { describe, it, expect } from "vitest";
+import { tapEffect } from "../../hooks/tap-effect";
+import { tapState } from "../../hooks/tap-state";
+import { createTestResource, renderTest } from "../test-utils";
+import {
+  renderResourceFiber,
+  commitResourceFiber,
+} from "../../core/ResourceFiber";
+
+describe("Rules of Hooks - Hook Order", () => {
+  it("should throw when hooks are called in different order", () => {
+    let condition = true;
+
+    const resource = createTestResource(() => {
+      if (condition) {
+        tapState(1);
+        tapEffect(() => {}, []);
+      } else {
+        tapEffect(() => {}, []);
+        tapState(1);
+      }
+      return null;
+    });
+
+    // First render establishes order
+    renderTest(resource, undefined);
+
+    // Change condition
+    condition = false;
+
+    // Second render with different order should throw
+    expect(() => renderResourceFiber(resource, undefined)).toThrow(
+      "Hook order changed between renders",
+    );
+  });
+
+  it("should throw when hook types change between renders", () => {
+    let useEffect = false;
+
+    const resource = createTestResource(() => {
+      if (useEffect) {
+        tapEffect(() => {});
+      } else {
+        tapState(0);
+      }
+      return null;
+    });
+
+    renderTest(resource, undefined);
+
+    // Change to use different hook type
+    useEffect = true;
+
+    expect(() => renderResourceFiber(resource, undefined)).toThrow(
+      "Hook order changed between renders",
+    );
+  });
+
+  it("should throw with conditional hooks", () => {
+    let condition = true;
+
+    const resource = createTestResource(() => {
+      tapState(1);
+
+      if (condition) {
+        tapState(2); // Conditional hook
+      }
+
+      tapState(3);
+      return null;
+    });
+
+    renderTest(resource, undefined);
+
+    // Change condition
+    condition = false;
+
+    // Should throw because hook count changed
+    expect(() => renderResourceFiber(resource, undefined)).toThrow(
+      "Rendered 2 hooks but expected 3",
+    );
+  });
+
+  it("should allow hooks in loops with consistent count", () => {
+    const items = [1, 2, 3];
+
+    const resource = createTestResource(() => {
+      const states = items.map((item) => {
+        const [value] = tapState(item);
+        return value;
+      });
+
+      return states;
+    });
+
+    const result = renderTest(resource, undefined);
+    expect(result).toEqual([1, 2, 3]);
+
+    // Re-render should work fine
+    expect(() => renderResourceFiber(resource, undefined)).not.toThrow();
+  });
+
+  it("should throw when hooks in loops have inconsistent count", () => {
+    let items = [1, 2, 3];
+
+    const resource = createTestResource(() => {
+      items.forEach((item) => {
+        tapState(item);
+      });
+      return null;
+    });
+
+    renderTest(resource, undefined);
+
+    // Change array length
+    items = [1, 2];
+
+    expect(() => renderResourceFiber(resource, undefined)).toThrow(
+      "Rendered 2 hooks but expected 3",
+    );
+  });
+
+  it("should maintain order with mixed hook types", () => {
+    const resource = createTestResource(() => {
+      const [a] = tapState(1);
+      tapEffect(() => {});
+      const [b] = tapState(2);
+      tapEffect(() => {});
+      const [c] = tapState(3);
+
+      return { a, b, c };
+    });
+
+    const result = renderTest(resource, undefined);
+    expect(result).toEqual({ a: 1, b: 2, c: 3 });
+
+    // Re-render should maintain same order
+    const ctx = renderResourceFiber(resource, undefined);
+    expect(() => commitResourceFiber(resource, ctx)).not.toThrow();
+  });
+
+  it("should detect early return causing different hook counts", () => {
+    let shouldReturn = false;
+
+    const resource = createTestResource(() => {
+      const [a] = tapState(1);
+
+      if (shouldReturn) {
+        return a; // Early return
+      }
+
+      const [b] = tapState(2);
+      return a + b;
+    });
+
+    const result1 = renderTest(resource, undefined);
+    expect(result1).toBe(3);
+
+    // Enable early return
+    shouldReturn = true;
+
+    expect(() => renderResourceFiber(resource, undefined)).toThrow(
+      "Rendered 1 hooks but expected 2",
+    );
+  });
+
+  it("should throw on nested hook calls", () => {
+    const resource = createTestResource(() => {
+      const [count, setCount] = tapState(0);
+
+      // This effect contains a hook call, which is invalid
+      tapEffect(() => {
+        if (count > 0) {
+          expect(() => {
+            const [_nested] = tapState(0); // Invalid: hook inside effect
+          }).toThrow("No resource fiber available");
+        }
+      });
+
+      // Use an effect to trigger the state change
+      tapEffect(() => {
+        if (count === 0) {
+          setCount(1);
+        }
+      }, [count]);
+
+      return count;
+    });
+
+    renderTest(resource, undefined);
+  });
+});

package/src/__tests__/test-utils.ts

@@ -0,0 +1,219 @@
+import { resource } from "../core/resource";
+import {
+  createResourceFiber,
+  unmountResourceFiber,
+  renderResourceFiber,
+  commitResourceFiber,
+} from "../core/ResourceFiber";
+import { ResourceFiber } from "../core/types";
+import { tapState } from "../hooks/tap-state";
+
+// ============================================================================
+// Resource Creation
+// ============================================================================
+
+/**
+ * Creates a test resource fiber for unit testing.
+ * This is a low-level utility that creates a ResourceFiber directly.
+ * Sets up a rerender callback that automatically re-renders when state changes.
+ */
+export function createTestResource<R, P>(fn: (props: P) => R) {
+  const rerenderCallback = () => {
+    // Re-render when state changes
+    if (activeResources.has(fiber)) {
+      const lastProps = propsMap.get(fiber);
+      const result = renderResourceFiber(fiber, lastProps);
+      commitResourceFiber(fiber, result);
+      lastRenderResultMap.set(fiber, result);
+    }
+  };
+
+  const fiber = createResourceFiber(resource(fn), rerenderCallback);
+  return fiber;
+}
+
+// ============================================================================
+// Resource Lifecycle Management
+// ============================================================================
+
+// Track resources for cleanup
+const activeResources = new Set<ResourceFiber<any, any>>();
+const propsMap = new WeakMap<ResourceFiber<any, any>, any>();
+const lastRenderResultMap = new WeakMap<ResourceFiber<any, any>, any>();
+
+/**
+ * Renders a test resource fiber with the given props and manages its lifecycle.
+ * - Tracks resources for cleanup
+ * - Returns the current state after render
+ */
+export function renderTest<R, P>(fiber: ResourceFiber<R, P>, props: P): R {
+  propsMap.set(fiber, props);
+
+  // Track resource for cleanup
+  activeResources.add(fiber);
+
+  // Render with new props
+  const result = renderResourceFiber(fiber, props);
+  commitResourceFiber(fiber, result);
+  lastRenderResultMap.set(fiber, result);
+
+  // Return the committed state from the result
+  // This accounts for any re-renders that happened during commit
+  return result.state;
+}
+
+/**
+ * Unmounts a specific resource fiber and removes it from tracking.
+ */
+export function unmountResource<R, P>(fiber: ResourceFiber<R, P>) {
+  if (activeResources.has(fiber)) {
+    unmountResourceFiber(fiber);
+    activeResources.delete(fiber);
+  }
+}
+
+/**
+ * Cleans up all resources. Should be called after each test.
+ */
+export function cleanupAllResources() {
+  activeResources.forEach((fiber) => unmountResourceFiber(fiber));
+  activeResources.clear();
+}
+
+/**
+ * Gets the current committed state of a resource fiber.
+ * Returns the state from the last render/commit cycle.
+ */
+export function getCommittedState<R, P>(fiber: ResourceFiber<R, P>): R {
+  const lastResult = lastRenderResultMap.get(fiber);
+  if (!lastResult) {
+    throw new Error(
+      "No render result found for fiber. Make sure to call renderResource first.",
+    );
+  }
+  return lastResult.state;
+}
+
+// ============================================================================
+// Test Helpers
+// ============================================================================
+
+/**
+ * Helper to subscribe to resource state changes for testing.
+ * Tracks call count and latest state value.
+ */
+export class TestSubscriber<T> {
+  public callCount = 0;
+  public lastState: T;
+  private fiber: ResourceFiber<any, any>;
+
+  constructor(fiber: ResourceFiber<any, any>) {
+    this.fiber = fiber;
+    // Need to render once to get initial state
+    const lastProps = propsMap.get(fiber) ?? undefined;
+    const initialResult = renderResourceFiber(fiber, lastProps as any);
+    commitResourceFiber(fiber, initialResult);
+    this.lastState = initialResult.state;
+    lastRenderResultMap.set(fiber, initialResult);
+    activeResources.add(fiber);
+  }
+
+  cleanup() {
+    if (activeResources.has(this.fiber)) {
+      unmountResourceFiber(this.fiber);
+      activeResources.delete(this.fiber);
+    }
+  }
+}
+
+/**
+ * Helper class to manage resource lifecycle in tests with explicit control.
+ * Useful when you need fine-grained control over mount/unmount timing.
+ */
+export class TestResourceManager<R, P> {
+  private isActive = false;
+
+  constructor(public fiber: ResourceFiber<R, P>) {}
+
+  renderAndMount(props: P): R {
+    if (this.isActive) {
+      throw new Error("Resource already active");
+    }
+
+    this.isActive = true;
+    activeResources.add(this.fiber);
+    propsMap.set(this.fiber, props);
+    const result = renderResourceFiber(this.fiber, props);
+    commitResourceFiber(this.fiber, result);
+    lastRenderResultMap.set(this.fiber, result);
+    return result.state;
+  }
+
+  cleanup() {
+    if (this.isActive && activeResources.has(this.fiber)) {
+      unmountResourceFiber(this.fiber);
+      activeResources.delete(this.fiber);
+      this.isActive = false;
+    }
+  }
+}
+
+// ============================================================================
+// Async Utilities
+// ============================================================================
+
+/**
+ * Waits for the next tick of the event loop.
+ * Useful for testing async state updates.
+ */
+export function waitForNextTick(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+/**
+ * Waits for a condition to be true with timeout.
+ * Useful for testing eventual consistency.
+ */
+export async function waitFor(
+  condition: () => boolean,
+  timeout = 1000,
+  interval = 10,
+): Promise<void> {
+  const start = Date.now();
+  while (!condition()) {
+    if (Date.now() - start > timeout) {
+      throw new Error("Timeout waiting for condition");
+    }
+    await new Promise((resolve) => setTimeout(resolve, interval));
+  }
+}
+
+// ============================================================================
+// Test Data Factories
+// ============================================================================
+
+/**
+ * Creates a simple counter resource for testing.
+ * Commonly used across multiple test files.
+ */
+export function createCounterResource(initialValue = 0) {
+  return (props: { value?: number }) => {
+    const value = props.value ?? initialValue;
+    return { count: value };
+  };
+}
+
+/**
+ * Creates a stateful counter resource for testing.
+ * Includes increment/decrement functions.
+ */
+export function createStatefulCounterResource() {
+  return (props: { initial: number }) => {
+    const [count, setCount] = tapState(props.initial);
+    return {
+      count,
+      increment: () => setCount((c: number) => c + 1),
+      decrement: () => setCount((c: number) => c - 1),
+    };
+  };
+}

package/src/core/ResourceFiber.ts

@@ -0,0 +1,58 @@
+import { ResourceFiber, RenderResult, Resource } from "./types";
+import { commitRender, cleanupAllEffects } from "./commit";
+import { withResourceFiber } from "./execution-context";
+import { callResourceFn } from "./callResourceFn";
+
+export function createResourceFiber<R, P>(
+  resource: Resource<R, P>,
+  scheduleRerender: () => void,
+): ResourceFiber<R, P> {
+  return {
+    resource,
+    scheduleRerender,
+    cells: [],
+    currentIndex: 0,
+    renderContext: undefined,
+    isFirstRender: true,
+    isMounted: false,
+    isNeverMounted: true,
+  };
+}
+
+export function unmountResourceFiber<R, P>(fiber: ResourceFiber<R, P>): void {
+  // Clean up all effects
+  fiber.isMounted = false;
+  cleanupAllEffects(fiber);
+}
+
+export function renderResourceFiber<R, P>(
+  fiber: ResourceFiber<R, P>,
+  props: P,
+): RenderResult {
+  const result: RenderResult = {
+    commitTasks: [],
+    props,
+    state: undefined,
+  };
+
+  withResourceFiber(fiber, () => {
+    fiber.renderContext = result;
+    try {
+      result.state = callResourceFn(fiber.resource, props);
+    } finally {
+      fiber.renderContext = undefined;
+    }
+  });
+
+  return result;
+}
+
+export function commitResourceFiber<R, P>(
+  fiber: ResourceFiber<R, P>,
+  result: RenderResult,
+): void {
+  fiber.isMounted = true;
+  fiber.isNeverMounted = false;
+
+  commitRender(result, fiber);
+}

package/src/core/callResourceFn.ts

@@ -0,0 +1,21 @@
+import { Resource } from "./types";
+
+/**
+ * Renders a resource with the given props.
+ * @internal This is for internal use only.
+ */
+export function callResourceFn<R, P>(resource: Resource<R, P>, props: P): R {
+  const fn = (resource as unknown as { [fnSymbol]?: (props: P) => R })[
+    fnSymbol
+  ];
+  if (!fn) {
+    throw new Error("ResourceElement.type is not a valid Resource");
+  }
+  return fn(props);
+}
+
+/**
+ * Symbol used to store the ResourceFn in the Resource constructor.
+ * @internal This is for internal use only.
+ */
+export const fnSymbol = Symbol("fnSymbol");

package/src/core/commit.ts

@@ -0,0 +1,73 @@
+import { ResourceFiber, RenderResult } from "./types";
+
+export function commitRender<R, P>(
+  renderResult: RenderResult,
+  fiber: ResourceFiber<R, P>,
+): void {
+  // Process all tasks collected during render
+  renderResult.commitTasks.forEach((task) => {
+    const cellIndex = task.cellIndex;
+    const effectCell = fiber.cells[cellIndex]!;
+    if (effectCell.type !== "effect") {
+      throw new Error("Cannot find effect cell");
+    }
+
+    // Check if deps changed
+    let shouldRunEffect = true;
+
+    if (effectCell.deps !== undefined && task.deps !== undefined) {
+      shouldRunEffect =
+        effectCell.deps.length !== task.deps.length ||
+        effectCell.deps.some((dep, j) => !Object.is(dep, task.deps![j]));
+    }
+
+    // Run cleanup if effect will re-run
+    if (shouldRunEffect) {
+      if (effectCell.mounted) {
+        if (typeof effectCell.deps !== typeof task.deps) {
+          throw new Error(
+            "tapEffect called with and without dependencies across re-renders",
+          );
+        }
+
+        try {
+          if (effectCell.mounted && effectCell.cleanup) {
+            effectCell.cleanup();
+          }
+        } finally {
+          effectCell.mounted = false;
+        }
+      }
+      const cleanup = task.effect();
+
+      if (cleanup !== undefined && typeof cleanup !== "function") {
+        throw new Error(
+          "An effect function must either return a cleanup function or nothing. " +
+            `Received: ${typeof cleanup}`,
+        );
+      }
+
+      effectCell.mounted = true;
+      effectCell.cleanup = typeof cleanup === "function" ? cleanup : undefined;
+      effectCell.deps = task.deps;
+    }
+  });
+}
+
+export function cleanupAllEffects<R, P>(executionContext: ResourceFiber<R, P>) {
+  let firstError: unknown | null = null;
+  // Run cleanups in reverse order
+  for (let i = executionContext.cells.length - 1; i >= 0; i--) {
+    const cell = executionContext.cells[i];
+    if (cell?.type === "effect" && cell.mounted && cell.cleanup) {
+      try {
+        cell.cleanup();
+      } catch (e) {
+        if (firstError == null) firstError = e;
+      } finally {
+        cell.mounted = false;
+      }
+    }
+  }
+  if (firstError != null) throw firstError;
+}

package/src/core/context.ts

@@ -0,0 +1,28 @@
+const contextValue: unique symbol = Symbol("tap.Context");
+type Context<T> = {
+  [contextValue]: T;
+};
+
+export const createContext = <T>(defaultValue: T): Context<T> => {
+  return {
+    [contextValue]: defaultValue,
+  };
+};
+
+export const withContextProvider = <T, TResult>(
+  context: Context<T>,
+  value: T,
+  fn: () => TResult,
+) => {
+  const previousValue = context[contextValue];
+  context[contextValue] = value;
+  try {
+    return fn();
+  } finally {
+    context[contextValue] = previousValue;
+  }
+};
+
+export const tapContext = <T>(context: Context<T>) => {
+  return context[contextValue];
+};

package/src/core/createResource.ts

@@ -0,0 +1,116 @@
+import { RenderResult, ResourceElement } from "./types";
+import {
+  createResourceFiber,
+  unmountResourceFiber,
+  renderResourceFiber,
+  commitResourceFiber,
+} from "./ResourceFiber";
+import { flushSync, UpdateScheduler } from "./scheduler";
+import { tapRef } from "../hooks/tap-ref";
+import { tapState } from "../hooks/tap-state";
+import { tapMemo } from "../hooks/tap-memo";
+import { tapEffect } from "../hooks/tap-effect";
+import { resource } from "./resource";
+import { tapResource } from "../hooks/tap-resource";
+
+export namespace createResource {
+  export type Unsubscribe = () => void;
+
+  export interface Handle<R, P> {
+    getState(): R;
+    subscribe(callback: () => void): Unsubscribe;
+    render(element: ResourceElement<R, P>): void;
+    unmount(): void;
+  }
+}
+
+const HandleWrapperResource = resource(
+  <R, P>(state: {
+    element: ResourceElement<R, P>;
+    onRender: (changed: boolean) => boolean;
+    onUnmount: () => void;
+  }): createResource.Handle<R, P> => {
+    const [, setElement] = tapState(state.element);
+    const value = tapResource(state.element);
+    const subscribers = tapRef(new Set<() => void>()).current;
+    const valueRef = tapRef(value);
+
+    tapEffect(() => {
+      if (value !== valueRef.current) {
+        valueRef.current = value;
+        subscribers.forEach((callback) => callback());
+      }
+    });
+
+    const handle = tapMemo(
+      () => ({
+        getState: () => valueRef.current,
+        subscribe: (callback: () => void) => {
+          subscribers.add(callback);
+          return () => subscribers.delete(callback);
+        },
+        render: (element: ResourceElement<R, P>) => {
+          const changed = state.element !== element;
+          state.element = element;
+
+          if (state.onRender(changed)) {
+            setElement(element);
+          }
+        },
+        unmount: state.onUnmount,
+      }),
+      [],
+    );
+
+    return handle;
+  },
+);
+
+export const createResource = <R, P>(
+  element: ResourceElement<R, P>,
+  { mount = true }: { mount?: boolean } = {},
+): createResource.Handle<R, P> => {
+  let isMounted = mount;
+  let render: RenderResult;
+  const props = {
+    element,
+    onRender: (changed: boolean) => {
+      if (isMounted) return changed;
+      isMounted = true;
+
+      flushSync(() => {
+        if (changed) {
+          render = renderResourceFiber(fiber, props);
+        }
+
+        if (scheduler.isDirty) return;
+        commitResourceFiber(fiber, render!);
+      });
+
+      return false;
+    },
+    onUnmount: () => {
+      if (!isMounted) throw new Error("Resource not mounted");
+      isMounted = false;
+
+      unmountResourceFiber(fiber);
+    },
+  };
+
+  const scheduler = new UpdateScheduler(() => {
+    render = renderResourceFiber(fiber, props);
+
+    if (scheduler.isDirty || !isMounted) return;
+    commitResourceFiber(fiber, render);
+  });
+
+  const fiber = createResourceFiber(HandleWrapperResource<R, P>, () =>
+    scheduler.markDirty(),
+  );
+
+  flushSync(() => {
+    scheduler.markDirty();
+  });
+
+  return render!.state;
+};