@assistant-ui/tap 0.3.6 → 0.4.0

package/src/__tests__/test-utils.ts

@@ -18,7 +18,9 @@ import { tapState } from "../hooks/tap-state";
  * Sets up a rerender callback that automatically re-renders when state changes.
  */
 export function createTestResource<R, P>(fn: (props: P) => R) {
-  const rerenderCallback = () => {
+  const rerenderCallback = (callback: () => boolean) => {
+    if (!callback()) return;
+
     // Re-render when state changes
     if (activeResources.has(fiber)) {
       const lastProps = propsMap.get(fiber);
@@ -59,7 +61,7 @@ export function renderTest<R, P>(fiber: ResourceFiber<R, P>, props: P): R {
 
   // Return the committed state from the result
   // This accounts for any re-renders that happened during commit
-  return result.state;
+  return result.output;
 }
 
 /**
@@ -84,14 +86,14 @@ export function cleanupAllResources() {
  * 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 {
+export function getCommittedOutput<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;
+  return lastResult.output;
 }
 
 // ============================================================================
@@ -113,7 +115,7 @@ export class TestSubscriber<T> {
     const lastProps = propsMap.get(fiber) ?? undefined;
     const initialResult = renderResourceFiber(fiber, lastProps as any);
     commitResourceFiber(fiber, initialResult);
-    this.lastState = initialResult.state;
+    this.lastState = initialResult.output;
     lastRenderResultMap.set(fiber, initialResult);
     activeResources.add(fiber);
   }
@@ -146,7 +148,7 @@ export class TestResourceManager<R, P> {
     const result = renderResourceFiber(this.fiber, props);
     commitResourceFiber(this.fiber, result);
     lastRenderResultMap.set(this.fiber, result);
-    return result.state;
+    return result.output;
   }
 
   cleanup() {

package/src/core/ResourceFiber.ts

@@ -1,15 +1,18 @@
 import { ResourceFiber, RenderResult, Resource } from "./types";
 import { commitRender, cleanupAllEffects } from "./commit";
-import { withResourceFiber } from "./execution-context";
+import { getDevStrictMode, withResourceFiber } from "./execution-context";
 import { callResourceFn } from "./callResourceFn";
+import { isDevelopment } from "./env";
 
 export function createResourceFiber<R, P>(
-  resource: Resource<R, P>,
-  scheduleRerender: () => void,
+  type: Resource<R, P>,
+  dispatchUpdate: (callback: () => boolean) => void,
+  strictMode: "root" | "child" | null = getDevStrictMode(false),
 ): ResourceFiber<R, P> {
   return {
-    resource,
-    scheduleRerender,
+    type,
+    dispatchUpdate,
+    devStrictMode: strictMode,
     cells: [],
     currentIndex: 0,
     renderContext: undefined,
@@ -20,7 +23,9 @@ export function createResourceFiber<R, P>(
 }
 
 export function unmountResourceFiber<R, P>(fiber: ResourceFiber<R, P>): void {
-  // Clean up all effects
+  if (!fiber.isMounted)
+    throw new Error("Tried to unmount a fiber that is already unmounted");
+
   fiber.isMounted = false;
   cleanupAllEffects(fiber);
 }
@@ -29,16 +34,16 @@ export function renderResourceFiber<R, P>(
   fiber: ResourceFiber<R, P>,
   props: P,
 ): RenderResult {
-  const result: RenderResult = {
+  const result = {
     commitTasks: [],
     props,
-    state: undefined,
+    output: undefined as R | undefined,
   };
 
   withResourceFiber(fiber, () => {
     fiber.renderContext = result;
     try {
-      result.state = callResourceFn(fiber.resource, props);
+      result.output = callResourceFn(fiber.type, props);
     } finally {
       fiber.renderContext = undefined;
     }
@@ -52,7 +57,12 @@ export function commitResourceFiber<R, P>(
   result: RenderResult,
 ): void {
   fiber.isMounted = true;
-  fiber.isNeverMounted = false;
 
-  commitRender(result, fiber);
+  if (isDevelopment && fiber.isNeverMounted && fiber.devStrictMode === "root") {
+    commitRender(result);
+    cleanupAllEffects(fiber);
+  }
+
+  fiber.isNeverMounted = false;
+  commitRender(result);
 }

package/src/core/commit.ts

@@ -1,73 +1,44 @@
 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");
+export function commitRender(renderResult: RenderResult): void {
+  const errors: unknown[] = [];
+
+  for (const task of renderResult.commitTasks) {
+    try {
+      task();
+    } catch (error) {
+      errors.push(error);
     }
+  }
 
-    // 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;
+  if (errors.length > 0) {
+    if (errors.length === 1) {
+      throw errors[0];
+    } else {
+      throw new AggregateError(errors, "Errors during commit");
     }
-  });
+  }
 }
 
 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) {
+  const errors: unknown[] = [];
+  for (const cell of executionContext.cells) {
+    if (cell?.type === "effect" && cell.cleanup) {
       try {
-        cell.cleanup();
+        cell.cleanup?.();
       } catch (e) {
-        if (firstError == null) firstError = e;
+        errors.push(e);
       } finally {
-        cell.mounted = false;
+        cell.cleanup = undefined;
+        cell.deps = null; // Reset deps so effect runs again on next mount
       }
     }
   }
-  if (firstError != null) throw firstError;
+  if (errors.length > 0) {
+    if (errors.length === 1) {
+      throw errors[0];
+    } else {
+      throw new AggregateError(errors, "Errors during cleanup");
+    }
+  }
 }

package/src/core/context.ts

@@ -3,7 +3,7 @@ type Context<T> = {
   [contextValue]: T;
 };
 
-export const createContext = <T>(defaultValue: T): Context<T> => {
+export const createResourceContext = <T>(defaultValue: T): Context<T> => {
   return {
     [contextValue]: defaultValue,
   };
@@ -23,6 +23,6 @@ export const withContextProvider = <T, TResult>(
   }
 };
 
-export const tapContext = <T>(context: Context<T>) => {
+export const tap = <T>(context: Context<T>) => {
   return context[contextValue];
 };

package/src/core/createResource.ts

@@ -5,19 +5,22 @@ import {
   renderResourceFiber,
   commitResourceFiber,
 } from "./ResourceFiber";
-import { flushSync, UpdateScheduler } from "./scheduler";
+import { flushResourcesSync, 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";
+import { tapConst } from "../hooks/tap-const";
+import { getDevStrictMode } from "./execution-context";
+import { isDevelopment } from "./env";
 
 export namespace createResource {
   export type Unsubscribe = () => void;
 
   export interface Handle<R, P> {
-    getState(): R;
+    getValue(): R;
     subscribe(callback: () => void): Unsubscribe;
     render(element: ResourceElement<R, P>): void;
     unmount(): void;
@@ -26,40 +29,44 @@ export namespace createResource {
 
 const HandleWrapperResource = resource(
   <R, P>(state: {
-    element: ResourceElement<R, P>;
+    elementRef: {
+      current: 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);
+    const [, setElement] = tapState(state.elementRef.current);
+    const output = tapResource(state.elementRef.current);
+
+    const subscribers = tapConst(() => new Set<() => void>(), []);
+    const valueRef = tapRef(output);
 
     tapEffect(() => {
-      if (value !== valueRef.current) {
-        valueRef.current = value;
+      if (output !== valueRef.current) {
+        valueRef.current = output;
         subscribers.forEach((callback) => callback());
       }
     });
 
     const handle = tapMemo(
       () => ({
-        getState: () => valueRef.current,
+        getValue: () => 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;
+
+        render: (el: ResourceElement<R, P>) => {
+          const changed = state.elementRef.current !== el;
+          state.elementRef.current = el;
 
           if (state.onRender(changed)) {
-            setElement(element);
+            setElement(el);
           }
         },
         unmount: state.onUnmount,
       }),
-      [],
+      [state],
     );
 
     return handle;
@@ -68,18 +75,26 @@ const HandleWrapperResource = resource(
 
 export const createResource = <R, P>(
   element: ResourceElement<R, P>,
-  { mount = true }: { mount?: boolean } = {},
+  {
+    mount = true,
+    devStrictMode = false,
+  }: { mount?: boolean; devStrictMode?: boolean } = {},
 ): createResource.Handle<R, P> => {
   let isMounted = mount;
   let render: RenderResult;
   const props = {
-    element,
+    elementRef: { current: element },
     onRender: (changed: boolean) => {
       if (isMounted) return changed;
       isMounted = true;
 
-      flushSync(() => {
+      flushResourcesSync(() => {
         if (changed) {
+          // In strict mode, render twice to detect side effects
+          if (isDevelopment && fiber.devStrictMode === "root") {
+            void renderResourceFiber(fiber, props);
+          }
+
           render = renderResourceFiber(fiber, props);
         }
 
@@ -98,19 +113,28 @@ export const createResource = <R, P>(
   };
 
   const scheduler = new UpdateScheduler(() => {
+    // In strict mode, render twice to detect side effects
+    if (isDevelopment && fiber.devStrictMode === "root") {
+      void renderResourceFiber(fiber, props);
+    }
+
     render = renderResourceFiber(fiber, props);
 
     if (scheduler.isDirty || !isMounted) return;
     commitResourceFiber(fiber, render);
   });
 
-  const fiber = createResourceFiber(HandleWrapperResource<R, P>, () =>
-    scheduler.markDirty(),
+  const fiber = createResourceFiber(
+    HandleWrapperResource<R, P>,
+    (callback) => {
+      if (callback()) scheduler.markDirty();
+    },
+    getDevStrictMode(devStrictMode),
   );
 
-  flushSync(() => {
+  flushResourcesSync(() => {
     scheduler.markDirty();
   });
 
-  return render!.state;
+  return render!.output;
 };

package/src/core/env.ts

@@ -0,0 +1,3 @@
+export const isDevelopment =
+  process.env["NODE_ENV"] === "development" ||
+  process.env["NODE_ENV"] === "test";

package/src/core/execution-context.ts

@@ -1,3 +1,4 @@
+import { isDevelopment } from "./env";
 import { ResourceFiber } from "./types";
 
 let currentResourceFiber: ResourceFiber<any, any> | null = null;
@@ -32,3 +33,11 @@ export function getCurrentResourceFiber(): ResourceFiber<unknown, unknown> {
   }
   return currentResourceFiber;
 }
+
+export function getDevStrictMode(enable: boolean) {
+  if (!isDevelopment) return null;
+  if (currentResourceFiber?.devStrictMode)
+    return currentResourceFiber.isFirstRender ? "child" : "root";
+
+  return enable ? "root" : null;
+}

package/src/core/resource.ts

@@ -1,7 +1,10 @@
-import { Resource, ResourceElement } from "./types";
+import { 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>(fn: () => R): () => ResourceElement<R, undefined>;
+export function resource<R, P>(
+  fn: (props: P) => R,
+): (props: P) => ResourceElement<R, P>;
 export function resource<R, P = undefined>(fn: (props: P) => R) {
   const type = (props?: P) => {
     return {

package/src/core/scheduler.ts

@@ -77,7 +77,7 @@ const flushScheduled = () => {
   }
 };
 
-export const flushSync = <T>(callback: () => T): T => {
+export const flushResourcesSync = <T>(callback: () => T): T => {
   const prev = flushState;
   flushState = {
     schedulers: new Set([]),

package/src/core/types.ts

@@ -1,52 +1,51 @@
 import type { tapEffect } from "../hooks/tap-effect";
 import type { tapState } from "../hooks/tap-state";
-import { fnSymbol } from "./callResourceFn";
+import type { fnSymbol } from "./callResourceFn";
 
 export type ResourceElement<R, P = any> = {
-  type: Resource<R, P> & { [fnSymbol]: (props: P) => R };
-  props: P;
+  readonly type: Resource<R, P> & { [fnSymbol]: (props: P) => R };
+  readonly props: P;
+  readonly key?: string | number;
 };
 
-type ResourceArgs<P> = undefined extends P ? [props?: P] : [props: P];
-export type Resource<R, P> = (
-  ...args: ResourceArgs<P>
-) => ResourceElement<R, P>;
+export type Resource<R, P> = (props: P) => ResourceElement<R, P>;
+export type ContravariantResource<R, P> = (props: P) => ResourceElement<R>;
 
-export type ContravariantResource<R, P> = (
-  ...args: ResourceArgs<P>
-) => ResourceElement<R>;
-
-export type ExtractResourceOutput<T> =
-  T extends ResourceElement<infer R, any> ? R : never;
+export type ExtractResourceReturnType<T> =
+  T extends ResourceElement<infer R, any>
+    ? R
+    : T extends Resource<infer R, any>
+      ? R
+      : never;
 
 export type Cell =
   | {
-      type: "state";
+      readonly type: "state";
       value: any;
       set: (updater: tapState.StateUpdater<any>) => void;
     }
   | {
-      type: "effect";
-      mounted: boolean;
-      cleanup?: tapEffect.Destructor | undefined;
-      deps?: readonly unknown[] | undefined;
+      readonly type: "effect";
+      cleanup: tapEffect.Destructor | void;
+      deps: readonly unknown[] | null | undefined;
     };
 
 export interface EffectTask {
-  effect: tapEffect.EffectCallback;
-  deps?: readonly unknown[] | undefined;
-  cellIndex: number;
+  readonly effect: tapEffect.EffectCallback;
+  readonly deps: readonly unknown[] | undefined;
+  readonly cell: Cell & { type: "effect" };
 }
 
 export interface RenderResult {
-  state: any;
-  props: any;
-  commitTasks: EffectTask[];
+  readonly output: any;
+  readonly props: any;
+  readonly commitTasks: (() => void)[];
 }
 
 export interface ResourceFiber<R, P> {
-  readonly scheduleRerender: () => void;
-  readonly resource: Resource<R, P>;
+  readonly dispatchUpdate: (callback: () => boolean) => void;
+  readonly type: Resource<R, P>;
+  readonly devStrictMode: "root" | "child" | null;
 
   cells: Cell[];
   currentIndex: number;

package/src/core/withKey.ts

@@ -0,0 +1,8 @@
+import { ResourceElement } from "./types";
+
+export function withKey<E extends ResourceElement<any, any>>(
+  key: string | number,
+  element: E,
+): E {
+  return { ...element, key };
+}

package/src/hooks/tap-callback.ts

@@ -4,5 +4,6 @@ export const tapCallback = <T extends (...args: any[]) => any>(
   fn: T,
   deps: readonly unknown[],
 ): T => {
+  // biome-ignore lint/correctness/useExhaustiveDependencies: user provided deps instead of callback identity
   return tapMemo(() => fn, deps);
 };

package/src/hooks/tap-const.ts

@@ -0,0 +1,6 @@
+import { tapState } from "./tap-state";
+
+export function tapConst<T>(getValue: () => T, _deps: readonly never[]): T {
+  const [state] = tapState(getValue);
+  return state;
+}

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

@@ -1,5 +1,8 @@
 import { tapRef } from "./tap-ref";
 import { tapEffect } from "./tap-effect";
+import { isDevelopment } from "../core/env";
+import { tapCallback } from "./tap-callback";
+import { getCurrentResourceFiber } from "../core/execution-context";
 
 /**
  * Creates a stable function reference that always calls the most recent version of the callback.
@@ -25,5 +28,17 @@ export function tapEffectEvent<T extends (...args: any[]) => any>(
     callbackRef.current = callback;
   });
 
+  if (isDevelopment) {
+    const fiber = getCurrentResourceFiber();
+    return tapCallback(
+      ((...args: Parameters<T>) => {
+        if (fiber.renderContext)
+          throw new Error("tapEffectEvent cannot be called during render");
+        return callbackRef.current(...args);
+      }) as T,
+      [],
+    );
+  }
+
   return callbackRef.current;
 }

package/src/hooks/tap-effect.ts

@@ -1,35 +1,12 @@
-import { getCurrentResourceFiber } from "../core/execution-context";
 import { Cell } from "../core/types";
+import { depsShallowEqual } from "./utils/depsShallowEqual";
+import { tapHook, registerRenderMountTask } from "./utils/tapHook";
 
-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;
-}
+const newEffect = (): Cell & { type: "effect" } => ({
+  type: "effect",
+  cleanup: undefined,
+  deps: null, // null means the effect has never been run
+});
 
 export namespace tapEffect {
   export type Destructor = () => void;
@@ -45,15 +22,48 @@ export function tapEffect(
   effect: tapEffect.EffectCallback,
   deps?: readonly unknown[],
 ): void {
-  const fiber = getCurrentResourceFiber();
+  const cell = tapHook("effect", newEffect);
+
+  if (deps && cell.deps && depsShallowEqual(cell.deps, deps)) return;
+  if (cell.deps !== null && !!deps !== !!cell.deps)
+    throw new Error(
+      "tapEffect called with and without dependencies across re-renders",
+    );
+
+  registerRenderMountTask(() => {
+    const errors: unknown[] = [];
+
+    try {
+      cell.cleanup?.();
+    } catch (error) {
+      errors.push(error);
+    } finally {
+      cell.cleanup = undefined;
+    }
+
+    try {
+      const cleanup = effect();
+
+      if (cleanup !== undefined && typeof cleanup !== "function") {
+        throw new Error(
+          "An effect function must either return a cleanup function or nothing. " +
+            `Received: ${typeof cleanup}`,
+        );
+      }
+
+      cell.cleanup = cleanup;
+    } catch (error) {
+      errors.push(error);
+    }
 
-  // Reserve a spot for the effect cell and get its index
-  const cellIndex = getEffectCell();
+    cell.deps = deps;
 
-  // Add task to render context for execution in commit phase
-  fiber.renderContext!.commitTasks.push({
-    effect,
-    deps,
-    cellIndex,
+    if (errors.length > 0) {
+      if (errors.length === 1) {
+        throw errors[0];
+      } else {
+        throw new AggregateError(errors, "Errors during commit");
+      }
+    }
   });
 }