alepha 0.23.0 → 0.24.0

package/src/queue/core/providers/WorkerProvider.ts

@@ -6,7 +6,7 @@ import {
   Alepha,
   type Static,
   type TSchema,
-  t,
+  z,
 } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
@@ -25,22 +25,25 @@ import { QueueProvider } from "./QueueProvider.ts";
  */
 export const queueWorkerOptions = $atom({
   name: "alepha.queue.worker.options",
-  schema: t.object({
-    interval: t.integer({
-      default: 1000,
-      description:
+  schema: z.object({
+    interval: z
+      .integer()
+      .describe(
         "Interval in milliseconds to wait before checking for new messages.",
-    }),
-    maxInterval: t.integer({
-      default: 32000,
-      description:
+      )
+      .default(1000),
+    maxInterval: z
+      .integer()
+      .describe(
         "Maximum interval in milliseconds to wait before checking for new messages.",
-    }),
-    concurrency: t.integer({
-      default: 1,
-      description:
+      )
+      .default(32000),
+    concurrency: z
+      .integer()
+      .describe(
         "Number of workers to run concurrently. Useful only if you are doing a lot of I/O.",
-    }),
+      )
+      .default(1),
   }),
   default: {
     interval: 1000,

package/src/queue/redis/providers/RedisQueueProvider.ts

@@ -1,4 +1,4 @@
-import { $atom, $inject, $state, type Static, t } from "alepha";
+import { $atom, $inject, $state, type Static, z } from "alepha";
 import type { QueueProvider } from "alepha/queue";
 import { RedisProvider } from "alepha/redis";
 
@@ -9,8 +9,8 @@ import { RedisProvider } from "alepha/redis";
  */
 export const redisQueueOptions = $atom({
   name: "alepha.queue.redis.options",
-  schema: t.object({
-    prefix: t.text({
+  schema: z.object({
+    prefix: z.text({
       default: "queue",
       description: "Prefix for all queue keys in Redis.",
     }),

package/src/react/core/__tests__/ErrorBoundary.browser.spec.tsx

@@ -0,0 +1,92 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { ErrorBoundary } from "../components/ErrorBoundary.tsx";
+
+const Boom = () => {
+  throw new Error("boom");
+};
+
+const Fine = () => <div>fine</div>;
+
+describe("ErrorBoundary", () => {
+  const fallback = (error: Error) => <div>caught: {error.message}</div>;
+
+  it("renders the fallback when a child throws", () => {
+    render(
+      <ErrorBoundary fallback={fallback}>
+        <Boom />
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByText("caught: boom")).toBeDefined();
+  });
+
+  /**
+   * Without this, a route that throws latches the fallback forever: navigating
+   * to a healthy page still shows the old error until a full page reload.
+   */
+  it("clears a caught error when a reset key changes", () => {
+    const { rerender } = render(
+      <ErrorBoundary fallback={fallback} resetKeys={["/broken"]}>
+        <Boom />
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByText("caught: boom")).toBeDefined();
+
+    rerender(
+      <ErrorBoundary fallback={fallback} resetKeys={["/healthy"]}>
+        <Fine />
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByText("fine")).toBeDefined();
+    expect(screen.queryByText("caught: boom")).toBeNull();
+  });
+
+  it("keeps showing the fallback while the reset keys are unchanged", () => {
+    const { rerender } = render(
+      <ErrorBoundary fallback={fallback} resetKeys={["/broken"]}>
+        <Boom />
+      </ErrorBoundary>,
+    );
+
+    rerender(
+      <ErrorBoundary fallback={fallback} resetKeys={["/broken"]}>
+        <Fine />
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByText("caught: boom")).toBeDefined();
+  });
+
+  it("still exposes a manual reset to the fallback", () => {
+    let reset: (() => void) | undefined;
+    const { rerender } = render(
+      <ErrorBoundary
+        fallback={(error, doReset) => {
+          reset = doReset;
+          return <div>caught: {error.message}</div>;
+        }}
+      >
+        <Boom />
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByText("caught: boom")).toBeDefined();
+
+    reset?.();
+    rerender(
+      <ErrorBoundary
+        fallback={(error, doReset) => {
+          reset = doReset;
+          return <div>caught: {error.message}</div>;
+        }}
+      >
+        <Fine />
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByText("fine")).toBeDefined();
+  });
+});

package/src/react/core/__tests__/Router.spec.tsx

@@ -1,4 +1,4 @@
-import { Alepha, t } from "alepha";
+import { Alepha, z } from "alepha";
 import { renderToString } from "react-dom/server";
 import { test } from "vitest";
 import { NestedView } from "../../router/index.ts";
@@ -70,8 +70,8 @@ test("Router - NestedView", async ({ expect }) => {
         name: "Hello",
         path: "/hello/:name",
         schema: {
-          params: t.object({
-            name: t.text(),
+          params: z.object({
+            name: z.text(),
           }),
         },
         loader: ({ params }) => params,
@@ -124,7 +124,7 @@ test("Router - All routes", async ({ expect }) => {
           },
           {
             path: ":id",
-            schema: { params: t.object({ id: t.text() }) },
+            schema: { params: z.object({ id: z.text() }) },
             loader: ({ params }) => {
               if (params.id === "boom") throw new Error("boom");
               return params;

package/src/react/core/__tests__/useComputed.browser.spec.tsx

@@ -0,0 +1,192 @@
+import { act, renderHook } from "@testing-library/react";
+import { $atom, $computed, Alepha, type Computed, z } from "alepha";
+import type { ReactNode } from "react";
+import { useRef } from "react";
+import { describe, expect, it } from "vitest";
+import { AlephaContext } from "../contexts/AlephaContext.ts";
+import { useComputed } from "../hooks/useComputed.ts";
+
+const countAtom = $atom({
+  name: "test.useComputed.count",
+  schema: z.object({ value: z.number() }),
+  default: { value: 1 },
+});
+
+const squared = $computed({
+  name: "test.useComputed.squared",
+  deps: [countAtom],
+  get: (c) => c.value * c.value,
+});
+
+const otherAtom = $atom({
+  name: "test.useComputed.other",
+  schema: z.object({ value: z.number() }),
+  default: { value: 5 },
+});
+
+const otherSquared = $computed({
+  name: "test.useComputed.otherSquared",
+  deps: [otherAtom],
+  get: (o) => o.value + 100,
+});
+
+const cartAtom = $atom({
+  name: "test.useComputed.cart",
+  schema: z.object({
+    items: z.array(z.object({ price: z.number() })),
+  }),
+  default: { items: [] },
+});
+
+const cartSummary = $computed({
+  name: "test.useComputed.cartSummary",
+  deps: [cartAtom],
+  get: (c) => ({ count: c.items.length, items: c.items }),
+});
+
+describe("useComputed", () => {
+  const setup = async () => {
+    const alepha = Alepha.create();
+    await alepha.start();
+
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <AlephaContext.Provider value={alepha}>{children}</AlephaContext.Provider>
+    );
+
+    return { alepha, wrapper };
+  };
+
+  it("renders the derived value", async () => {
+    const { wrapper } = await setup();
+    const { result } = renderHook(() => useComputed(squared), { wrapper });
+    expect(result.current).toBe(1);
+  });
+
+  it("updates when a dependency mutates", async () => {
+    const { alepha, wrapper } = await setup();
+    const { result } = renderHook(() => useComputed(squared), { wrapper });
+
+    await act(async () => {
+      alepha.store.set(countAtom, { value: 3 });
+    });
+
+    expect(result.current).toBe(9);
+  });
+
+  it("ignores mutations of unrelated keys", async () => {
+    const { alepha, wrapper } = await setup();
+    let renders = 0;
+
+    renderHook(
+      () => {
+        renders++;
+        return useComputed(squared);
+      },
+      { wrapper },
+    );
+
+    const before = renders;
+    await act(async () => {
+      alepha.store.set("test.useComputed.unrelated" as any, 42 as any);
+    });
+
+    expect(renders).toBe(before);
+  });
+
+  // The cache's entire reason to exist is referential stability for
+  // object/array-returning computed values (the infinite-loop guard for
+  // `useSyncExternalStore`). A number-returning computed can't tell a real
+  // cache apart from no caching at all, because numbers are stable under
+  // `Object.is` by value — these tests use an object-returning computed so
+  // a naive `getSnapshot = () => alepha.store.get(target)` (no caching
+  // mechanism whatsoever) would actually fail them.
+  describe("referential stability of object/array-returning values", () => {
+    it("returns the same reference across re-renders when no dependency changed", async () => {
+      const { wrapper } = await setup();
+      const { result, rerender } = renderHook(() => useComputed(cartSummary), {
+        wrapper,
+      });
+
+      const first = result.current;
+      rerender();
+
+      expect(result.current).toBe(first);
+    });
+
+    it("returns a new reference once a dependency actually changes", async () => {
+      const { alepha, wrapper } = await setup();
+      const { result } = renderHook(() => useComputed(cartSummary), {
+        wrapper,
+      });
+
+      const first = result.current;
+
+      await act(async () => {
+        alepha.store.set(cartAtom, { items: [{ price: 9 }] });
+      });
+
+      expect(result.current).not.toBe(first);
+      expect(result.current.count).toBe(1);
+    });
+  });
+
+  // Fix 1 regression: a mutation that lands in the window between the
+  // initial render and the passive effect that subscribes to
+  // `state:mutate` must still be reflected. A dirty-flag cache — set only
+  // by that subscription's listener — can never learn about a mutation
+  // that happened before the listener existed, so it would serve the
+  // stale pre-mutation value forever (until some later, unrelated mutation
+  // on the same key happened to fire). `MutateDuringRender` reproduces the
+  // window deterministically: it is a sibling rendered (in the same
+  // synchronous render pass) right after the `useComputed` consumer, so its
+  // mutation always lands after `useComputed`'s first `getSnapshot()` call
+  // but strictly before React commits and runs any effect — the exact race
+  // described in the review.
+  describe("mutation landing before the store subscribes", () => {
+    const MutateDuringRender = (props: { alepha: Alepha }) => {
+      const done = useRef(false);
+      if (!done.current) {
+        done.current = true;
+        props.alepha.store.set(countAtom, { value: 3 });
+      }
+      return null;
+    };
+
+    it("reflects a mutation dispatched before the mutate listener attaches", async () => {
+      const alepha = Alepha.create();
+      await alepha.start();
+
+      const wrapper = ({ children }: { children: ReactNode }) => (
+        <AlephaContext.Provider value={alepha}>
+          {children}
+          <MutateDuringRender alepha={alepha} />
+        </AlephaContext.Provider>
+      );
+
+      const { result } = renderHook(() => useComputed(squared), { wrapper });
+
+      expect(result.current).toBe(9);
+    });
+  });
+
+  // Fix 2 regression: swapping `target` for a different `Computed` across
+  // renders must render the new target's value immediately — not the old
+  // target's cached value, and not only once a mutation happens to touch
+  // the new target's keys.
+  describe("swapping targets", () => {
+    it("renders the new target's value right after the swap", async () => {
+      const { wrapper } = await setup();
+      const initialProps: { target: Computed<number> } = { target: squared };
+      const { result, rerender } = renderHook(
+        (props: { target: Computed<number> }) => useComputed(props.target),
+        { wrapper, initialProps },
+      );
+
+      expect(result.current).toBe(1);
+
+      rerender({ target: otherSquared });
+
+      expect(result.current).toBe(105);
+    });
+  });
+});

package/src/react/core/__tests__/useQuery.browser.spec.tsx

@@ -108,4 +108,52 @@ describe("useQuery", () => {
       expect(result.current.data).toBe("fetched");
     });
   });
+
+  /**
+   * The concurrency guard used to bail out BEFORE the abort-previous block, so
+   * a dep that changed while a request was in flight never triggered a refetch:
+   * the stale user's data committed and stayed forever.
+   */
+  test("refetches when a dep changes mid-flight and commits the newest result", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create().with(AlephaDateTime);
+    await alepha.start();
+
+    const release: Record<string, () => void> = {};
+    const handler = vi.fn(
+      (userId: string) =>
+        new Promise<string>((resolve) => {
+          release[userId] = () => resolve(`data-for-${userId}`);
+        }),
+    );
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <AlephaContext.Provider value={alepha}>{children}</AlephaContext.Provider>
+    );
+
+    const { result, rerender } = renderHook(
+      ({ userId }) => useQuery({ handler: () => handler(userId) }, [userId]),
+      { wrapper, initialProps: { userId: "alice" } },
+    );
+
+    // alice's request is in flight (never resolved yet).
+    await waitFor(() => expect(handler).toHaveBeenCalledTimes(1));
+    expect(result.current.data).toBe(undefined);
+
+    // The dep changes while alice is still in flight.
+    rerender({ userId: "bob" });
+
+    await waitFor(() => expect(handler).toHaveBeenCalledTimes(2));
+
+    // Now let both finish — alice (superseded) first, then bob.
+    await act(async () => {
+      release.alice?.();
+      release.bob?.();
+    });
+
+    await waitFor(() => {
+      expect(result.current.data).toBe("data-for-bob");
+    });
+  });
 });

package/src/react/core/__tests__/useSelector.browser.spec.tsx

@@ -0,0 +1,105 @@
+import { act, renderHook } from "@testing-library/react";
+import { $atom, Alepha, z } from "alepha";
+import type { ReactNode } from "react";
+import { describe, expect, it } from "vitest";
+import { AlephaContext } from "../contexts/AlephaContext.ts";
+import { useSelector } from "../hooks/useSelector.ts";
+import { shallowEqual } from "../utils/shallowEqual.ts";
+
+const prefsAtom = $atom({
+  name: "test.useSelector.prefs",
+  schema: z.object({
+    theme: z.string(),
+    sidebar: z.object({ collapsed: z.boolean() }),
+  }),
+  default: { theme: "light", sidebar: { collapsed: false } },
+});
+
+describe("useSelector", () => {
+  const setup = async () => {
+    const alepha = Alepha.create();
+    await alepha.start();
+
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <AlephaContext.Provider value={alepha}>{children}</AlephaContext.Provider>
+    );
+
+    return { alepha, wrapper };
+  };
+
+  it("returns the selected slice", async () => {
+    const { wrapper } = await setup();
+
+    const { result } = renderHook(
+      () => useSelector(prefsAtom, (s) => s.theme),
+      { wrapper },
+    );
+
+    expect(result.current).toBe("light");
+  });
+
+  it("re-renders when the selected slice changes", async () => {
+    const { alepha, wrapper } = await setup();
+
+    const { result } = renderHook(
+      () => useSelector(prefsAtom, (s) => s.theme),
+      { wrapper },
+    );
+
+    await act(async () => {
+      alepha.store.mut(prefsAtom, (s) => ({ ...s, theme: "dark" }));
+    });
+
+    expect(result.current).toBe("dark");
+  });
+
+  it("does not re-render when an unselected field changes", async () => {
+    const { alepha, wrapper } = await setup();
+    let renders = 0;
+
+    renderHook(
+      () => {
+        renders++;
+        return useSelector(prefsAtom, (s) => s.theme);
+      },
+      { wrapper },
+    );
+
+    const before = renders;
+    await act(async () => {
+      alepha.store.mut(prefsAtom, (s) => ({
+        ...s,
+        sidebar: { collapsed: true },
+      }));
+    });
+
+    expect(renders).toBe(before);
+  });
+
+  it("suppresses re-renders for structurally equal object slices via shallowEqual", async () => {
+    const { alepha, wrapper } = await setup();
+    let renders = 0;
+
+    const { result } = renderHook(
+      () => {
+        renders++;
+        return useSelector(
+          prefsAtom,
+          (s) => ({ collapsed: s.sidebar.collapsed }),
+          shallowEqual,
+        );
+      },
+      { wrapper },
+    );
+
+    const first = result.current;
+    const before = renders;
+
+    await act(async () => {
+      alepha.store.mut(prefsAtom, (s) => ({ ...s, theme: "dark" }));
+    });
+
+    expect(renders).toBe(before);
+    expect(result.current).toBe(first);
+  });
+});

package/src/react/core/__tests__/useStore.browser.spec.tsx

@@ -0,0 +1,113 @@
+import { act, renderHook } from "@testing-library/react";
+import { Alepha } from "alepha";
+import type { ReactNode } from "react";
+import { describe, expect, it } from "vitest";
+import { AlephaContext } from "../contexts/AlephaContext.ts";
+import { useStore } from "../hooks/useStore.ts";
+
+describe("useStore", () => {
+  const setup = async () => {
+    const alepha = Alepha.create();
+    await alepha.start();
+
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <AlephaContext.Provider value={alepha}>{children}</AlephaContext.Provider>
+    );
+
+    return { alepha, wrapper };
+  };
+
+  it("reflects a mutation to the subscribed key", async () => {
+    const { alepha, wrapper } = await setup();
+    alepha.store.set("count" as any, 1 as any);
+
+    const { result } = renderHook(() => useStore("count" as any), { wrapper });
+
+    expect(result.current[0]).toBe(1);
+
+    await act(async () => {
+      alepha.store.set("count" as any, 2 as any);
+    });
+
+    expect(result.current[0]).toBe(2);
+  });
+
+  it("ignores mutations to other keys", async () => {
+    const { alepha, wrapper } = await setup();
+    alepha.store.set("count" as any, 1 as any);
+
+    const { result } = renderHook(() => useStore("count" as any), { wrapper });
+
+    await act(async () => {
+      alepha.store.set("unrelated" as any, 99 as any);
+    });
+
+    expect(result.current[0]).toBe(1);
+  });
+
+  /**
+   * The subscription used to be registered in a `[]`-deps effect and the value
+   * seeded via `useState`, so a component that switches which key it watches
+   * kept reading — and listening to — the ORIGINAL key forever.
+   */
+  it("re-reads the store when the target key changes", async () => {
+    const { alepha, wrapper } = await setup();
+    alepha.store.set("a" as any, "value-a" as any);
+    alepha.store.set("b" as any, "value-b" as any);
+
+    const { result, rerender } = renderHook(
+      ({ target }) => useStore(target as any),
+      { wrapper, initialProps: { target: "a" } },
+    );
+
+    expect(result.current[0]).toBe("value-a");
+
+    rerender({ target: "b" });
+
+    expect(result.current[0]).toBe("value-b");
+  });
+
+  it("re-subscribes when the target key changes", async () => {
+    const { alepha, wrapper } = await setup();
+    alepha.store.set("a" as any, "value-a" as any);
+    alepha.store.set("b" as any, "value-b" as any);
+
+    const { result, rerender } = renderHook(
+      ({ target }) => useStore(target as any),
+      { wrapper, initialProps: { target: "a" } },
+    );
+
+    rerender({ target: "b" });
+
+    await act(async () => {
+      alepha.store.set("b" as any, "value-b2" as any);
+    });
+
+    expect(result.current[0]).toBe("value-b2");
+  });
+
+  it("seeds the default value into the store", async () => {
+    const { alepha, wrapper } = await setup();
+
+    const { result } = renderHook(() => useStore("seeded" as any, "hello"), {
+      wrapper,
+    });
+
+    expect(result.current[0]).toBe("hello");
+    expect(alepha.store.get("seeded" as any)).toBe("hello");
+  });
+
+  it("writes through the setter", async () => {
+    const { alepha, wrapper } = await setup();
+    alepha.store.set("count" as any, 1 as any);
+
+    const { result } = renderHook(() => useStore("count" as any), { wrapper });
+
+    await act(async () => {
+      result.current[1](5 as any);
+    });
+
+    expect(alepha.store.get("count" as any)).toBe(5);
+    expect(result.current[0]).toBe(5);
+  });
+});