alepha 0.22.0 → 0.24.0

package/src/react/core/components/ErrorBoundary.tsx

@@ -19,6 +19,20 @@ export interface ErrorBoundaryProps {
    * Use this to log errors to a monitoring service.
    */
   onError?: (error: Error, info: ErrorInfo) => void;
+
+  /**
+   * Clear a caught error whenever any of these values changes (compared with
+   * `Object.is`, positionally).
+   *
+   * A boundary that catches has to be told when the reason to fail is gone —
+   * otherwise the fallback latches and every later render keeps showing the
+   * stale error. The router passes the current path, so navigating away from a
+   * page that threw recovers on its own.
+   *
+   * Unlike remounting via `key`, this clears the error WITHOUT tearing down the
+   * children, so unrelated component state survives an ordinary navigation.
+   */
+  resetKeys?: readonly unknown[];
 }
 
 /**
@@ -61,6 +75,34 @@ export class ErrorBoundary extends React.Component<
     }
   }
 
+  /**
+   * Recover once the caller signals the failing input is gone.
+   */
+  componentDidUpdate(prevProps: PropsWithChildren<ErrorBoundaryProps>): void {
+    if (!this.state.error) {
+      return;
+    }
+
+    if (this.hasResetKeyChanged(prevProps.resetKeys, this.props.resetKeys)) {
+      this.setState({ error: undefined });
+    }
+  }
+
+  protected hasResetKeyChanged(
+    previous: readonly unknown[] | undefined,
+    next: readonly unknown[] | undefined,
+  ): boolean {
+    if (previous === next) {
+      return false;
+    }
+
+    if (!previous || !next || previous.length !== next.length) {
+      return true;
+    }
+
+    return previous.some((value, i) => !Object.is(value, next[i]));
+  }
+
   render(): ReactNode {
     if (this.state.error) {
       const reset = () => {

package/src/react/core/hooks/useAction.ts

@@ -133,6 +133,10 @@ export function useAction<Args extends any[], Result = void>(
   const abortControllerRef = useRef<AbortController | undefined>(undefined);
   const isMountedRef = useRef(true);
   const intervalRef = useRef<Interval | undefined>(undefined);
+  // Monotonic id of the latest run. A superseded run keeps executing until its
+  // abort lands, so every state write is gated on "am I still the latest?" —
+  // otherwise the stale run's `finally` would clear the newer run's `loading`.
+  const runIdRef = useRef(0);
 
   // Track mount state — must set true in body for React StrictMode double-invoke
   useEffect(() => {
@@ -171,13 +175,21 @@ export function useAction<Args extends any[], Result = void>(
   }, []);
 
   const executeAction = useCallback(
-    async (...args: Args): Promise<Result | undefined> => {
-      // Prevent concurrent executions
-      if (isExecutingRef.current) {
+    async (
+      args: Args,
+      { supersede = false }: { supersede?: boolean } = {},
+    ): Promise<Result | undefined> => {
+      if (isExecutingRef.current && !supersede) {
+        // A manual `run()` must not fire twice — this is what stops a
+        // double-clicked mutation from being submitted twice.
         return;
       }
 
-      // Abort previous request if still running
+      // A dep-change or interval run supersedes: the in-flight request was
+      // issued for inputs that are now stale, so its result must never win.
+      // (This is why the guard above is skipped rather than short-circuiting —
+      // otherwise `useQuery([userId])` whose `userId` changes mid-flight would
+      // never refetch, and the old user's data would stay on screen.)
       if (abortControllerRef.current) {
         abortControllerRef.current.abort();
       }
@@ -186,6 +198,9 @@ export function useAction<Args extends any[], Result = void>(
       const abortController = new AbortController();
       abortControllerRef.current = abortController;
 
+      const runId = ++runIdRef.current;
+      const isLatestRun = () => runIdRef.current === runId;
+
       isExecutingRef.current = true;
       setLoading(true);
       setError(undefined);
@@ -200,8 +215,12 @@ export function useAction<Args extends any[], Result = void>(
           signal: abortController.signal,
         } as any);
 
-        // Only update state if still mounted and not aborted
-        if (!isMountedRef.current || abortController.signal.aborted) {
+        // Only update state if still mounted, not aborted, and not superseded
+        if (
+          !isMountedRef.current ||
+          abortController.signal.aborted ||
+          !isLatestRun()
+        ) {
           return;
         }
 
@@ -223,8 +242,8 @@ export function useAction<Args extends any[], Result = void>(
           return;
         }
 
-        // Only update state if still mounted
-        if (!isMountedRef.current) {
+        // Only update state if still mounted and not superseded
+        if (!isMountedRef.current || !isLatestRun()) {
           return;
         }
 
@@ -246,9 +265,13 @@ export function useAction<Args extends any[], Result = void>(
         // fire-and-forget `action.run()` calls from producing unhandled
         // promise rejections.
       } finally {
-        isExecutingRef.current = false;
-        if (isMountedRef.current) {
-          setLoading(false);
+        // A superseded run must not release the guard or drop `loading` — the
+        // run that replaced it is still in flight.
+        if (isLatestRun()) {
+          isExecutingRef.current = false;
+          if (isMountedRef.current) {
+            setLoading(false);
+          }
         }
 
         await alepha.events.emit("react:action:end", {
@@ -265,8 +288,11 @@ export function useAction<Args extends any[], Result = void>(
     [...deps, options.id, options.onError, options.onSuccess],
   );
 
-  const handler = useCallback(
-    async (...args: Args): Promise<Result | undefined> => {
+  const runAction = useCallback(
+    async (
+      args: Args,
+      options_: { supersede?: boolean } = {},
+    ): Promise<Result | undefined> => {
       if (options.debounce) {
         // clear existing timer
         if (debounceTimerRef.current) {
@@ -277,7 +303,7 @@ export function useAction<Args extends any[], Result = void>(
         return new Promise((resolve) => {
           debounceTimerRef.current = dateTimeProvider.createTimeout(
             async () => {
-              const result = await executeAction(...args);
+              const result = await executeAction(args, options_);
               resolve(result);
             },
             options.debounce ?? 0,
@@ -285,11 +311,20 @@ export function useAction<Args extends any[], Result = void>(
         });
       }
 
-      return executeAction(...args);
+      return executeAction(args, options_);
     },
     [executeAction, options.debounce],
   );
 
+  /**
+   * Public `run()` — a user-initiated call. Deduped while one is in flight so a
+   * double-clicked mutation submits once.
+   */
+  const handler = useCallback(
+    (...args: Args): Promise<Result | undefined> => runAction(args),
+    [runAction],
+  );
+
   const cancel = useCallback(() => {
     // clear debounce timer
     if (debounceTimerRef.current) {
@@ -310,10 +345,12 @@ export function useAction<Args extends any[], Result = void>(
     }
   }, []);
 
-  // Run action on mount if runOnInit is true
+  // Run action on mount, and again whenever `deps` change. These runs supersede
+  // an in-flight request: it was issued for the previous deps, so its result is
+  // already stale.
   useEffect(() => {
     if (options.runOnInit) {
-      handler(...([] as any));
+      runAction([] as any, { supersede: true });
     }
   }, deps);
 
@@ -325,7 +362,7 @@ export function useAction<Args extends any[], Result = void>(
 
     // Set up interval
     intervalRef.current = dateTimeProvider.createInterval(
-      () => handler(...([] as any)),
+      () => runAction([] as any, { supersede: true }),
       options.runEvery,
       true,
     );
@@ -337,7 +374,7 @@ export function useAction<Args extends any[], Result = void>(
         intervalRef.current = undefined;
       }
     };
-  }, [handler, options.runEvery]);
+  }, [runAction, options.runEvery]);
 
   return {
     run: handler,

package/src/react/core/hooks/useComputed.ts

@@ -0,0 +1,91 @@
+import type { Computed } from "alepha";
+import { useCallback, useRef, useSyncExternalStore } from "react";
+import { useAlepha } from "./useAlepha.ts";
+
+/**
+ * Subscribes to a `$computed` value.
+ *
+ * `getSnapshot` always reads the dependency atoms **live** off the store —
+ * never through a subscription-set dirty flag. A dirty flag is only ever
+ * flipped by the `state:mutate` listener registered in `subscribe`, which
+ * React wires up in a passive effect (after commit); `EventManager.emit` is
+ * async on top of that. A mutation dispatched between the initial render and
+ * that effect committing would be invisible to the flag, so `getSnapshot`
+ * (including React's own post-subscribe consistency re-check) would keep
+ * returning the stale pre-mutation value. See `useStore.ts` and
+ * `useSelector.ts` for the same rationale.
+ *
+ * Referential stability for `useSyncExternalStore` comes from comparing the
+ * *inputs* (the resolved values of the computed's transitive atom
+ * dependencies) by identity, not from caching on a mount-time ref: when none
+ * of the inputs changed since the last snapshot, the previous output
+ * reference is returned as-is; when any input changed (or `target` itself
+ * was swapped for a different `Computed`), the value is recomputed and a new
+ * reference is cached.
+ *
+ * A `Computed` passed here should be declared at module scope, like an
+ * atom — constructing one inline in a component body creates a new
+ * instance every render, which (because `subscribe`/`getSnapshot` are keyed
+ * on `target.key`, matching `useStore`/`useSelector`) is tolerated for
+ * resubscription purposes, but any closures captured by that instance's
+ * `get()` will be locked to whichever render first created the subscription
+ * until `target.key` itself changes.
+ *
+ * ```tsx
+ * const total = useComputed(cartTotal);
+ * ```
+ */
+function useComputed<R>(target: Computed<R>): R {
+  const alepha = useAlepha();
+  const key = target.key;
+
+  // A ref, not state: the cached snapshot must survive re-renders without
+  // scheduling them. It exists purely to give `useSyncExternalStore` a
+  // stable reference when the resolved dependency values haven't changed —
+  // it is never the source of truth for staleness (see rationale above).
+  const cache = useRef<{
+    target: Computed<R>;
+    inputs: unknown[];
+    value: R;
+  } | null>(null);
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      if (!alepha.isBrowser()) {
+        return () => {};
+      }
+
+      const keys = new Set(target.keys());
+      return alepha.events.on("state:mutate", (ev) => {
+        if (keys.has(ev.key as string)) {
+          onStoreChange();
+        }
+      });
+    },
+    [alepha, key],
+  );
+
+  const getSnapshot = useCallback((): R => {
+    const inputs = target
+      .keys()
+      .map((depKey) => alepha.store.get(depKey as any));
+
+    const prev = cache.current;
+    if (
+      prev &&
+      prev.target === target &&
+      prev.inputs.length === inputs.length &&
+      prev.inputs.every((value, index) => Object.is(value, inputs[index]))
+    ) {
+      return prev.value;
+    }
+
+    const value = alepha.store.get(target);
+    cache.current = { target, inputs, value };
+    return value;
+  }, [alepha, key]);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+export { useComputed };

package/src/react/core/hooks/useSelector.ts

@@ -0,0 +1,67 @@
+import type { Atom, Static, TAtomObject } from "alepha";
+import { useCallback, useRef, useSyncExternalStore } from "react";
+import { useAlepha } from "./useAlepha.ts";
+
+/**
+ * Subscribes to a slice of an atom's state.
+ *
+ * Unlike {@link useStore}, which re-renders on every mutation of the atom,
+ * `useSelector` re-renders only when the selected slice actually changes
+ * according to `equality` (default: `Object.is`). Pass {@link shallowEqual}
+ * when the selector builds a fresh object on each call.
+ *
+ * ```tsx
+ * const theme = useSelector(uiAtom, (s) => s.theme);
+ * ```
+ */
+function useSelector<T extends TAtomObject, R>(
+  target: Atom<T>,
+  select: (state: Static<T>) => R,
+  equality: (a: R, b: R) => boolean = Object.is,
+): R {
+  const alepha = useAlepha();
+  const key = target.key;
+
+  // Refs, not state: the memoized snapshot must survive re-renders without
+  // scheduling them, and `getSnapshot` must return a referentially stable
+  // value for unchanged slices or `useSyncExternalStore` re-renders forever.
+  const cache = useRef<{ input: unknown; selected: R } | null>(null);
+  const selectRef = useRef(select);
+  selectRef.current = select;
+  const equalityRef = useRef(equality);
+  equalityRef.current = equality;
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      if (!alepha.isBrowser()) {
+        return () => {};
+      }
+
+      return alepha.events.on("state:mutate", (ev) => {
+        if (ev.key === key) {
+          onStoreChange();
+        }
+      });
+    },
+    [alepha, key],
+  );
+
+  const getSnapshot = useCallback(() => {
+    const input = alepha.store.get(target);
+    const prev = cache.current;
+    if (prev && Object.is(prev.input, input)) {
+      return prev.selected;
+    }
+    const selected = selectRef.current(input);
+    if (prev && equalityRef.current(prev.selected, selected)) {
+      cache.current = { input, selected: prev.selected };
+      return prev.selected;
+    }
+    cache.current = { input, selected };
+    return selected;
+  }, [alepha, key]);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+export { useSelector };

package/src/react/core/hooks/useStore.ts

@@ -1,10 +1,15 @@
 import type { State, Static, TAtomObject } from "alepha";
 import { Atom } from "alepha";
-import { useEffect, useMemo, useState } from "react";
+import { useCallback, useMemo, useSyncExternalStore } from "react";
 import { useAlepha } from "./useAlepha.ts";
 
 /**
  * Hook to access and mutate the Alepha state.
+ *
+ * Reads through `useSyncExternalStore`, so the store — not a `useState` copy of
+ * it — is the single source of truth. That is what keeps the value correct when
+ * a mutation lands between render and effect-commit, when the component swaps
+ * which `target` it watches, and when React renders concurrently (no tearing).
  */
 function useStore<T extends TAtomObject>(
   target: Atom<T>,
@@ -16,35 +21,49 @@ function useStore<Key extends keyof State>(
 ): UseStoreReturn<State[Key]>;
 function useStore(target: any, defaultValue?: any): any {
   const alepha = useAlepha();
+  const key: string = target instanceof Atom ? target.key : target;
 
+  // Seed during render (not in an effect) on purpose: effects don't run during
+  // SSR, and the default has to be in the store before `exportAtoms` serializes
+  // the hydration payload. Idempotent — only fills an empty slot.
   useMemo(() => {
     if (defaultValue != null && alepha.store.get(target) == null) {
       alepha.store.set(target, defaultValue);
     }
-  }, [defaultValue]);
+  }, [defaultValue, key]);
 
-  const [state, setState] = useState(alepha.store.get(target));
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      if (!alepha.isBrowser()) {
+        return () => {};
+      }
 
-  useEffect(() => {
-    if (!alepha.isBrowser()) {
-      return;
-    }
+      return alepha.events.on("state:mutate", (ev) => {
+        if (ev.key === key) {
+          onStoreChange();
+        }
+      });
+    },
+    [alepha, key],
+  );
 
-    const key = target instanceof Atom ? target.key : target;
+  // Read straight from the store rather than caching the event payload, so the
+  // snapshot stays correct no matter who mutated the key or when.
+  const getSnapshot = useCallback(
+    () => alepha.store.get(target),
+    [alepha, key],
+  );
 
-    return alepha.events.on("state:mutate", (ev) => {
-      if (ev.key === key) {
-        setState(ev.value);
-      }
-    });
-  }, []);
+  const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 
-  return [
-    state,
+  const setState = useCallback(
     (value: any) => {
       alepha.store.set(target, value);
     },
-  ] as const;
+    [alepha, key],
+  );
+
+  return [state, setState] as const;
 }
 
 export type UseStoreReturn<T> = [T, (value: T) => void];

package/src/react/core/index.ts

@@ -11,10 +11,13 @@ export * from "./contexts/AlephaProvider.tsx";
 export * from "./hooks/useAction.ts";
 export * from "./hooks/useAlepha.ts";
 export * from "./hooks/useClient.ts";
+export * from "./hooks/useComputed.ts";
 export * from "./hooks/useEvents.ts";
 export * from "./hooks/useInject.ts";
 export * from "./hooks/useQuery.ts";
+export * from "./hooks/useSelector.ts";
 export * from "./hooks/useStore.ts";
+export * from "./utils/shallowEqual.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 

package/src/react/core/utils/shallowEqual.ts

@@ -0,0 +1,36 @@
+/**
+ * Shallow structural equality over own enumerable keys.
+ *
+ * Intended as the `equality` argument of `useSelector` when the selector
+ * builds a fresh object/array on every call (e.g. `(s) => ({ a: s.a })`).
+ */
+export const shallowEqual = (a: unknown, b: unknown): boolean => {
+  if (Object.is(a, b)) {
+    return true;
+  }
+  if (
+    typeof a !== "object" ||
+    a === null ||
+    typeof b !== "object" ||
+    b === null
+  ) {
+    return false;
+  }
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) {
+    return false;
+  }
+  for (const key of keysA) {
+    if (
+      !Object.hasOwn(b, key) ||
+      !Object.is(
+        (a as Record<string, unknown>)[key],
+        (b as Record<string, unknown>)[key],
+      )
+    ) {
+      return false;
+    }
+  }
+  return true;
+};

package/src/react/form/__tests__/FormModel-submit-loading.spec.ts

@@ -0,0 +1,71 @@
+import { Alepha, z } from "alepha";
+import { AlephaLogger } from "alepha/logger";
+import { describe, it } from "vitest";
+import { FormModel } from "../services/FormModel.ts";
+
+/**
+ * Repro for: a form whose submit fails TypeBox validation (missing field)
+ * leaves the submit button stuck in its loading state forever.
+ *
+ * The button's loading is driven by the `form:submit:begin` / `form:submit:end`
+ * event pair (see useFormState). So the invariant that matters is: every
+ * `form:submit:begin` is followed by a `form:submit:end`, even when validation
+ * throws AND even when a downstream error listener (e.g. the action-error
+ * toaster) itself throws.
+ */
+describe("FormModel.submit loading pairing", () => {
+  const makeForm = (alepha: Alepha) =>
+    alepha.inject(FormModel as any, {
+      lifetime: "transient",
+      args: [
+        "f1",
+        {
+          id: "f1",
+          schema: z.object({ email: z.text(), password: z.text() }),
+          handler: () => {},
+          initialValues: {}, // both required fields missing → decode throws
+        },
+      ],
+    }) as FormModel<any>;
+
+  it("emits form:submit:end on a validation error (intrinsic)", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+    await alepha.start();
+    const form = makeForm(alepha);
+    let begun = false;
+    let ended = false;
+    alepha.events.on("form:submit:begin", () => {
+      begun = true;
+    });
+    alepha.events.on("form:submit:end", () => {
+      ended = true;
+    });
+
+    await form.submit().catch(() => {});
+
+    expect(begun).toBe(true);
+    expect(ended).toBe(true); // pairing must hold
+  });
+
+  it("emits form:submit:end even when a react:action:error listener throws", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+    await alepha.start();
+    const form = makeForm(alepha);
+    let ended = false;
+    alepha.events.on("form:submit:end", () => {
+      ended = true;
+    });
+    // Simulates a globally-mounted listener (e.g. ActionErrorToaster) throwing.
+    alepha.events.on("react:action:error", () => {
+      throw new Error("toaster boom");
+    });
+
+    await form.submit().catch(() => {});
+
+    expect(ended).toBe(true); // currently FAILS: end is skipped → button stuck
+  });
+});

package/src/react/form/__tests__/form-submitting-reactive.browser.spec.tsx

@@ -0,0 +1,96 @@
+import { fireEvent, render, waitFor } from "@testing-library/react";
+import { Alepha, z } from "alepha";
+import { AlephaLogger } from "alepha/logger";
+import { AlephaContext } from "alepha/react";
+import { describe, it } from "vitest";
+import { useForm, useFormState } from "../index.ts";
+
+/**
+ * Submit buttons bind their loading state to `useFormState(form, ["loading"])`
+ * (the reactive form-state API; the non-reactive `form.submitting` getter was
+ * removed). This loading must:
+ *  - turn ON while an async submit is in flight, and
+ *  - turn OFF again afterwards — including after a TypeBox validation error.
+ *
+ * The OFF guarantee relies on `FormModel.submit` always emitting
+ * `form:submit:end` (see FormModel-submit-loading.spec.ts).
+ */
+describe("useFormState loading drives the submit button", () => {
+  const mount = (alepha: Alepha, ui: React.ReactNode) =>
+    render(
+      <AlephaContext.Provider value={alepha}>{ui}</AlephaContext.Provider>,
+    );
+
+  it("turns loading on during an async submit and off after", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+    let release!: () => void;
+
+    const Form = () => {
+      const form = useForm({
+        id: "async",
+        schema: z.object({ name: z.string().min(1) }),
+        initialValues: { name: "ok" },
+        handler: () => new Promise<void>((r) => (release = r)),
+      });
+      const { loading } = useFormState(form, ["loading"]);
+      return (
+        <form {...form.props} data-testid="form">
+          <button
+            type="submit"
+            data-testid="submit"
+            data-loading={loading ? "true" : "false"}
+          >
+            go
+          </button>
+        </form>
+      );
+    };
+
+    const { getByTestId } = mount(alepha, <Form />);
+    fireEvent.submit(getByTestId("form"));
+
+    await waitFor(() =>
+      expect(getByTestId("submit").getAttribute("data-loading")).toBe("true"),
+    );
+    release();
+    await waitFor(() =>
+      expect(getByTestId("submit").getAttribute("data-loading")).toBe("false"),
+    );
+  });
+
+  it("clears loading after a TypeBox validation error", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+
+    const Form = () => {
+      const form = useForm({
+        id: "login",
+        schema: z.object({
+          identifier: z.string().min(1),
+          password: z.string().min(6),
+        }),
+        handler: async () => {},
+      });
+      const { loading } = useFormState(form, ["loading"]);
+      return (
+        <form {...form.props} data-testid="form">
+          <button
+            type="submit"
+            data-testid="submit"
+            data-loading={loading ? "true" : "false"}
+          >
+            Sign in
+          </button>
+        </form>
+      );
+    };
+
+    const { getByTestId } = mount(alepha, <Form />);
+    fireEvent.submit(getByTestId("form")); // empty → validation error
+
+    await waitFor(() =>
+      expect(getByTestId("submit").getAttribute("data-loading")).toBe("false"),
+    );
+  });
+});