@assistant-ui/tap 0.3.4 → 0.3.5

package/src/core/execution-context.ts

@@ -0,0 +1,34 @@
+import { ResourceFiber } from "./types";
+
+let currentResourceFiber: ResourceFiber<any, any> | null = null;
+
+export function withResourceFiber<R, P>(
+  fiber: ResourceFiber<R, P>,
+  fn: () => void,
+): void {
+  fiber.currentIndex = 0;
+
+  const previousContext = currentResourceFiber;
+  currentResourceFiber = fiber;
+  try {
+    fn();
+
+    fiber.isFirstRender = false;
+
+    // ensure hook count matches
+    if (fiber.cells.length !== fiber.currentIndex) {
+      throw new Error(
+        `Rendered ${fiber.currentIndex} hooks but expected ${fiber.cells.length}. ` +
+          "Hooks must be called in the exact same order in every render.",
+      );
+    }
+  } finally {
+    currentResourceFiber = previousContext;
+  }
+}
+export function getCurrentResourceFiber(): ResourceFiber<unknown, unknown> {
+  if (!currentResourceFiber) {
+    throw new Error("No resource fiber available");
+  }
+  return currentResourceFiber;
+}

package/src/core/resource.ts

@@ -0,0 +1,16 @@
+import { Resource, ResourceElement } from "./types";
+import { fnSymbol } from "./callResourceFn";
+export function resource<R>(fn: () => R): Resource<R, undefined>;
+export function resource<R, P>(fn: (props: P) => R): Resource<R, P>;
+export function resource<R, P = undefined>(fn: (props: P) => R) {
+  const type = (props?: P) => {
+    return {
+      type,
+      props: props!,
+    } satisfies ResourceElement<R, P>;
+  };
+
+  type[fnSymbol] = fn;
+
+  return type;
+}

package/src/core/scheduler.ts

@@ -0,0 +1,95 @@
+type Task = () => void;
+
+type GlobalFlushState = {
+  schedulers: Set<UpdateScheduler>;
+  isScheduled: boolean;
+};
+
+const MAX_FLUSH_LIMIT = 50;
+let flushState: GlobalFlushState = {
+  schedulers: new Set([]),
+  isScheduled: false,
+};
+
+export class UpdateScheduler {
+  private _isDirty = false;
+
+  constructor(private readonly _task: Task) {}
+
+  get isDirty() {
+    return this._isDirty;
+  }
+
+  markDirty() {
+    this._isDirty = true;
+
+    flushState.schedulers.add(this);
+    scheduleFlush();
+  }
+
+  runTask() {
+    this._isDirty = false;
+    this._task();
+  }
+}
+
+const scheduleFlush = () => {
+  if (flushState.isScheduled) return;
+  flushState.isScheduled = true;
+  queueMicrotask(flushScheduled);
+};
+
+const flushScheduled = () => {
+  try {
+    const errors = [];
+    let flushDepth = 0;
+
+    for (const scheduler of flushState.schedulers) {
+      flushState.schedulers.delete(scheduler);
+      if (!scheduler.isDirty) continue;
+
+      flushDepth++;
+
+      if (flushDepth > MAX_FLUSH_LIMIT) {
+        throw new Error(
+          `Maximum update depth exceeded. This can happen when a resource ` +
+            `repeatedly calls setState inside tapEffect.`,
+        );
+      }
+
+      try {
+        scheduler.runTask();
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+
+    if (errors.length > 0) {
+      if (errors.length === 1) {
+        throw errors[0];
+      } else {
+        throw new AggregateError(errors, "Errors occurred during flushSync");
+      }
+    }
+  } finally {
+    flushState.schedulers.clear();
+    flushState.isScheduled = false;
+  }
+};
+
+export const flushSync = <T>(callback: () => T): T => {
+  const prev = flushState;
+  flushState = {
+    schedulers: new Set([]),
+    isScheduled: true,
+  };
+
+  try {
+    const result = callback();
+    flushScheduled();
+
+    return result;
+  } finally {
+    flushState = prev;
+  }
+};

package/src/core/types.ts

@@ -0,0 +1,59 @@
+import type { tapEffect } from "../hooks/tap-effect";
+import type { tapState } from "../hooks/tap-state";
+import { fnSymbol } from "./callResourceFn";
+
+export type ResourceElement<R, P = any> = {
+  type: Resource<R, P> & { [fnSymbol]: (props: P) => R };
+  props: P;
+};
+
+type ResourceArgs<P> = undefined extends P ? [props?: P] : [props: P];
+export type Resource<R, P> = (
+  ...args: ResourceArgs<P>
+) => ResourceElement<R, P>;
+
+export type ContravariantResource<R, P> = (
+  ...args: ResourceArgs<P>
+) => ResourceElement<R>;
+
+export type ExtractResourceOutput<T> =
+  T extends ResourceElement<infer R, any> ? R : never;
+
+export type Cell =
+  | {
+      type: "state";
+      value: any;
+      set: (updater: tapState.StateUpdater<any>) => void;
+    }
+  | {
+      type: "effect";
+      mounted: boolean;
+      cleanup?: tapEffect.Destructor | undefined;
+      deps?: readonly unknown[] | undefined;
+    };
+
+export interface EffectTask {
+  effect: tapEffect.EffectCallback;
+  deps?: readonly unknown[] | undefined;
+  cellIndex: number;
+}
+
+export interface RenderResult {
+  state: any;
+  props: any;
+  commitTasks: EffectTask[];
+}
+
+export interface ResourceFiber<R, P> {
+  readonly scheduleRerender: () => void;
+  readonly resource: Resource<R, P>;
+
+  cells: Cell[];
+  currentIndex: number;
+
+  renderContext: RenderResult | undefined; // set during render
+
+  isMounted: boolean;
+  isFirstRender: boolean;
+  isNeverMounted: boolean;
+}

package/src/hooks/depsShallowEqual.ts

@@ -0,0 +1,10 @@
+export const depsShallowEqual = (
+  a: readonly unknown[],
+  b: readonly unknown[],
+) => {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (!Object.is(a[i], b[i])) return false;
+  }
+  return true;
+};

package/src/hooks/tap-callback.ts

@@ -0,0 +1,8 @@
+import { tapMemo } from "./tap-memo";
+
+export const tapCallback = <T extends (...args: any[]) => any>(
+  fn: T,
+  deps: readonly unknown[],
+): T => {
+  return tapMemo(() => fn, deps);
+};

package/src/hooks/tap-effect-event.ts

@@ -0,0 +1,29 @@
+import { tapRef } from "./tap-ref";
+import { tapEffect } from "./tap-effect";
+
+/**
+ * Creates a stable function reference that always calls the most recent version of the callback.
+ * Similar to React's useEffectEvent hook.
+ *
+ * @param callback - The callback function to wrap
+ * @returns A stable function reference that always calls the latest callback
+ *
+ * @example
+ * ```typescript
+ * const handleClick = tapEffectEvent((value: string) => {
+ *   console.log(value);
+ * });
+ * // handleClick reference is stable, but always calls the latest version
+ * ```
+ */
+export function tapEffectEvent<T extends (...args: any[]) => any>(
+  callback: T,
+): T {
+  const callbackRef = tapRef(callback);
+
+  tapEffect(() => {
+    callbackRef.current = callback;
+  });
+
+  return callbackRef.current;
+}

package/src/hooks/tap-effect.ts

@@ -0,0 +1,59 @@
+import { getCurrentResourceFiber } from "../core/execution-context";
+import { Cell } from "../core/types";
+
+function getEffectCell(): number {
+  const fiber = getCurrentResourceFiber();
+  const index = fiber.currentIndex++;
+
+  // Check if we're trying to use more hooks than in previous renders
+  if (!fiber.isFirstRender && index >= fiber.cells.length) {
+    throw new Error(
+      "Rendered more hooks than during the previous render. " +
+        "Hooks must be called in the exact same order in every render.",
+    );
+  }
+
+  if (!fiber.cells[index]) {
+    // Create the effect cell
+    const cell: Cell & { type: "effect" } = {
+      type: "effect",
+      mounted: false,
+    };
+
+    fiber.cells[index] = cell;
+  }
+
+  const cell = fiber.cells[index];
+  if (cell.type !== "effect") {
+    throw new Error("Hook order changed between renders");
+  }
+
+  return index;
+}
+
+export namespace tapEffect {
+  export type Destructor = () => void;
+  export type EffectCallback = () => void | Destructor;
+}
+
+export function tapEffect(effect: tapEffect.EffectCallback): void;
+export function tapEffect(
+  effect: tapEffect.EffectCallback,
+  deps: readonly unknown[],
+): void;
+export function tapEffect(
+  effect: tapEffect.EffectCallback,
+  deps?: readonly unknown[],
+): void {
+  const fiber = getCurrentResourceFiber();
+
+  // Reserve a spot for the effect cell and get its index
+  const cellIndex = getEffectCell();
+
+  // Add task to render context for execution in commit phase
+  fiber.renderContext!.commitTasks.push({
+    effect,
+    deps,
+    cellIndex,
+  });
+}

package/src/hooks/tap-inline-resource.ts

@@ -0,0 +1,8 @@
+import { ExtractResourceOutput, ResourceElement } from "../core/types";
+import { callResourceFn } from "../core/callResourceFn";
+
+export function tapInlineResource<E extends ResourceElement<any, any>>(
+  element: E,
+): ExtractResourceOutput<E> {
+  return callResourceFn(element.type, element.props);
+}

package/src/hooks/tap-memo.ts

@@ -0,0 +1,16 @@
+import { tapRef } from "./tap-ref";
+import { depsShallowEqual } from "./depsShallowEqual";
+
+export const tapMemo = <T>(fn: () => T, deps: readonly unknown[]) => {
+  const dataRef = tapRef<{ value: T; deps: readonly unknown[] }>();
+  if (!dataRef.current) {
+    dataRef.current = { value: fn(), deps };
+  }
+
+  if (!depsShallowEqual(dataRef.current.deps, deps)) {
+    dataRef.current.value = fn();
+    dataRef.current.deps = deps;
+  }
+
+  return dataRef.current.value;
+};

package/src/hooks/tap-ref.ts

@@ -0,0 +1,16 @@
+import { tapState } from "./tap-state";
+
+export namespace tapRef {
+  export interface RefObject<T> {
+    current: T;
+  }
+}
+
+export function tapRef<T>(initialValue: T): tapRef.RefObject<T>;
+export function tapRef<T = undefined>(): tapRef.RefObject<T | undefined>;
+export function tapRef<T>(initialValue?: T): tapRef.RefObject<T | undefined> {
+  const [state] = tapState(() => ({
+    current: initialValue,
+  }));
+  return state;
+}

package/src/hooks/tap-resource.ts

@@ -0,0 +1,44 @@
+import { ExtractResourceOutput, ResourceElement } from "../core/types";
+import { tapEffect } from "./tap-effect";
+import {
+  createResourceFiber,
+  unmountResourceFiber,
+  renderResourceFiber,
+  commitResourceFiber,
+} from "../core/ResourceFiber";
+import { tapMemo } from "./tap-memo";
+import { tapState } from "./tap-state";
+
+export function tapResource<E extends ResourceElement<any, any>>(
+  element: E,
+): ExtractResourceOutput<E>;
+export function tapResource<E extends ResourceElement<any, any>>(
+  element: E,
+  deps: readonly unknown[],
+): ExtractResourceOutput<E>;
+export function tapResource<E extends ResourceElement<any, any>>(
+  element: E,
+  deps?: readonly unknown[],
+): ExtractResourceOutput<E> {
+  const [stateVersion, rerender] = tapState({});
+  const fiber = tapMemo(
+    () => createResourceFiber(element.type, () => rerender({})),
+    [element.type],
+  );
+
+  const props = deps ? tapMemo(() => element.props, deps) : element.props;
+  const result = tapMemo(
+    () => renderResourceFiber(fiber, props),
+    [fiber, props, stateVersion],
+  );
+
+  tapEffect(() => {
+    return () => unmountResourceFiber(fiber);
+  }, [fiber]);
+
+  tapEffect(() => {
+    commitResourceFiber(fiber, result);
+  }, [fiber, result]);
+
+  return result.state;
+}

package/src/hooks/tap-resources.ts

@@ -0,0 +1,112 @@
+import {
+  ExtractResourceOutput,
+  RenderResult,
+  ResourceElement,
+  ResourceFiber,
+} from "../core/types";
+import { tapEffect } from "./tap-effect";
+import { tapMemo } from "./tap-memo";
+import { tapState } from "./tap-state";
+import { tapCallback } from "./tap-callback";
+import {
+  createResourceFiber,
+  unmountResourceFiber,
+  renderResourceFiber,
+  commitResourceFiber,
+} from "../core/ResourceFiber";
+
+export type TapResourcesRenderResult<R, K extends string | number | symbol> = {
+  add: [K, ResourceFiber<R, any>][];
+  remove: K[];
+  commit: [K, RenderResult][];
+  return: Record<K, R>;
+};
+
+export function tapResources<
+  M extends Record<string | number | symbol, any>,
+  E extends ResourceElement<any, any>,
+>(
+  map: M,
+  getElement: (t: M[keyof M], key: keyof M) => E,
+  getElementDeps: any[],
+): { [K in keyof M]: ExtractResourceOutput<E> } {
+  type R = ExtractResourceOutput<E>;
+  const [version, setVersion] = tapState(0);
+  const rerender = tapCallback(() => setVersion((v) => v + 1), []);
+
+  type K = keyof M;
+  const [fibers] = tapState(() => new Map<K, ResourceFiber<R, any>>());
+
+  const getElementMemo = tapMemo(() => getElement, getElementDeps);
+
+  // Process each element
+
+  const results = tapMemo(() => {
+    const results: TapResourcesRenderResult<R, K> = {
+      remove: [],
+      add: [],
+      commit: [],
+      return: {} as Record<K, R>,
+    };
+
+    // Create/update fibers and render
+    for (const key in map) {
+      const value = map[key as K];
+      const element = getElementMemo(value, key);
+
+      let fiber = fibers.get(key);
+
+      // Create new fiber if needed or type changed
+      if (!fiber || fiber.resource !== element.type) {
+        if (fiber) results.remove.push(key);
+        fiber = createResourceFiber(element.type, rerender);
+        results.add.push([key, fiber]);
+      }
+
+      // Render with current props
+      const renderResult = renderResourceFiber(fiber, element.props);
+      results.commit.push([key, renderResult]);
+
+      results.return[key] = renderResult.state;
+    }
+
+    // Clean up removed fibers (only if there might be stale ones)
+    if (
+      fibers.size >
+      results.commit.length - results.add.length + results.remove.length
+    ) {
+      for (const key of fibers.keys()) {
+        if (!(key in map)) {
+          results.remove.push(key);
+        }
+      }
+    }
+
+    return results;
+  }, [map, getElementMemo, version]);
+
+  // Cleanup on unmount
+  tapEffect(() => {
+    return () => {
+      for (const key of fibers.keys()) {
+        unmountResourceFiber(fibers.get(key)!);
+        fibers.delete(key);
+      }
+    };
+  }, []);
+
+  tapEffect(() => {
+    for (const key of results.remove) {
+      unmountResourceFiber(fibers.get(key)!);
+      fibers.delete(key);
+    }
+    for (const [key, fiber] of results.add) {
+      fibers.set(key, fiber);
+    }
+    for (const [key, result] of results.commit) {
+      commitResourceFiber(fibers.get(key)!, result);
+    }
+  }, [results]);
+
+  return results.return;
+}

package/src/hooks/tap-state.ts

@@ -0,0 +1,83 @@
+import { getCurrentResourceFiber } from "../core/execution-context";
+import { Cell, ResourceFiber } from "../core/types";
+
+export namespace tapState {
+  export type StateUpdater<S> = S | ((prev: S) => S);
+}
+
+const rerender = (fiber: ResourceFiber<any, any>) => {
+  if (fiber.renderContext) {
+    throw new Error("Resource updated during render");
+  }
+
+  if (fiber.isMounted) {
+    // Only schedule rerender if currently mounted
+    fiber.scheduleRerender();
+  } else if (fiber.isNeverMounted) {
+    throw new Error("Resource updated before mount");
+  }
+};
+
+function getStateCell<T>(
+  initialValue: T | (() => T),
+): Cell & { type: "state" } {
+  const fiber = getCurrentResourceFiber();
+  const index = fiber.currentIndex++;
+
+  // Check if we're trying to use more hooks than in previous renders
+  if (!fiber.isFirstRender && index >= fiber.cells.length) {
+    throw new Error(
+      "Rendered more hooks than during the previous render. " +
+        "Hooks must be called in the exact same order in every render.",
+    );
+  }
+
+  if (!fiber.cells[index]) {
+    // Initialize the value immediately
+    const value =
+      typeof initialValue === "function"
+        ? (initialValue as () => T)()
+        : initialValue;
+
+    const cell: Cell & { type: "state" } = {
+      type: "state",
+      value,
+      set: (updater: tapState.StateUpdater<T>) => {
+        const currentValue = cell.value;
+        const nextValue =
+          typeof updater === "function"
+            ? (updater as (prev: T) => T)(currentValue)
+            : updater;
+
+        if (!Object.is(currentValue, nextValue)) {
+          cell.value = nextValue;
+          rerender(fiber);
+        }
+      },
+    };
+
+    fiber.cells[index] = cell;
+  }
+
+  const cell = fiber.cells[index];
+  if (cell.type !== "state") {
+    throw new Error("Hook order changed between renders");
+  }
+
+  return cell as Cell & { type: "state" };
+}
+
+export function tapState<S = undefined>(): [
+  S | undefined,
+  (updater: tapState.StateUpdater<S>) => void,
+];
+export function tapState<S>(
+  initial: S | (() => S),
+): [S, (updater: tapState.StateUpdater<S>) => void];
+export function tapState<S>(
+  initial?: S | (() => S),
+): [S | undefined, (updater: tapState.StateUpdater<S>) => void] {
+  const cell = getStateCell(initial as S | (() => S));
+
+  return [cell.value, cell.set];
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+export { resource } from "./core/resource";
+
+// primitive hooks
+export { tapState } from "./hooks/tap-state";
+export { tapEffect } from "./hooks/tap-effect";
+
+// utility hooks
+export { tapRef } from "./hooks/tap-ref";
+export { tapMemo } from "./hooks/tap-memo";
+export { tapCallback } from "./hooks/tap-callback";
+export { tapEffectEvent } from "./hooks/tap-effect-event";
+
+// resources
+export { tapResource } from "./hooks/tap-resource";
+export { tapInlineResource } from "./hooks/tap-inline-resource";
+export { tapResources } from "./hooks/tap-resources";
+
+// imperative
+export { createResource } from "./core/createResource";
+export { flushSync } from "./core/scheduler";
+
+// context
+export { createContext, tapContext, withContextProvider } from "./core/context";
+
+// types
+export type {
+  Resource,
+  ContravariantResource,
+  ResourceElement,
+  ExtractResourceOutput,
+} from "./core/types";

package/src/react/index.ts

@@ -0,0 +1 @@
+export { useResource } from "./use-resource";

package/src/react/use-resource.ts

@@ -0,0 +1,35 @@
+import { useEffect, useLayoutEffect, useMemo, useState } from "react";
+import { ExtractResourceOutput, ResourceElement } from "../core/types";
+import {
+  createResourceFiber,
+  unmountResourceFiber,
+  renderResourceFiber,
+  commitResourceFiber,
+} from "../core/ResourceFiber";
+
+const shouldAvoidLayoutEffect =
+  (globalThis as any).__ASSISTANT_UI_DISABLE_LAYOUT_EFFECT__ === true;
+
+const useIsomorphicLayoutEffect = shouldAvoidLayoutEffect
+  ? useEffect
+  : useLayoutEffect;
+
+export function useResource<E extends ResourceElement<any, any>>(
+  element: E,
+): ExtractResourceOutput<E> {
+  const [, rerender] = useState({});
+  const fiber = useMemo(
+    () => createResourceFiber(element.type, () => rerender({})),
+    [element.type],
+  );
+
+  const result = renderResourceFiber(fiber, element.props);
+  useIsomorphicLayoutEffect(() => {
+    return () => unmountResourceFiber(fiber);
+  }, [fiber]);
+  useIsomorphicLayoutEffect(() => {
+    commitResourceFiber(fiber, result);
+  });
+
+  return result.state;
+}