alepha 0.22.0 → 0.24.0

package/src/core/__tests__/StateManager.persist.browser.spec.ts

@@ -0,0 +1,87 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { Alepha } from "../Alepha.ts";
+import { $atom } from "../primitives/$atom.ts";
+import { z } from "../providers/TypeProvider.ts";
+
+const schema = z.object({ theme: z.string() });
+
+describe("StateManager web storage persistence", () => {
+  beforeEach(() => {
+    // Always go through `window.*`, matching what the implementation reads
+    // (StateManager.getWebStorage uses `window.localStorage` /
+    // `window.sessionStorage`, not the bare global). On Node >= 22 with Web
+    // Storage enabled (on by default in Node 25), the bare `localStorage` /
+    // `sessionStorage` globals are a DIFFERENT object from jsdom's
+    // `window.localStorage` / `window.sessionStorage` — mixing the two
+    // makes this suite fail for reasons unrelated to the code under test.
+    window.localStorage.clear();
+    window.sessionStorage.clear();
+  });
+
+  it("writes to localStorage when a persisted atom mutates", async () => {
+    const prefs = $atom({
+      name: "test.persist.write",
+      schema,
+      default: { theme: "light" },
+      persist: "localStorage",
+    });
+
+    const alepha = Alepha.create();
+    alepha.store.set(prefs, { theme: "dark" });
+    await new Promise((r) => setTimeout(r, 0)); // state:mutate is async
+
+    expect(window.localStorage.getItem("test.persist.write")).toBe(
+      JSON.stringify({ theme: "dark" }),
+    );
+  });
+
+  it("hydrates from localStorage on registration in a fresh container", () => {
+    window.localStorage.setItem(
+      "test.persist.read",
+      JSON.stringify({ theme: "dark" }),
+    );
+    const prefs = $atom({
+      name: "test.persist.read",
+      schema,
+      default: { theme: "light" },
+      persist: "localStorage",
+    });
+
+    const alepha = Alepha.create();
+    expect(alepha.store.get(prefs)).toEqual({ theme: "dark" });
+  });
+
+  it("drops an invalid persisted value and keeps the default", () => {
+    window.localStorage.setItem(
+      "test.persist.bad",
+      JSON.stringify({ theme: 42 }),
+    );
+    const prefs = $atom({
+      name: "test.persist.bad",
+      schema,
+      default: { theme: "light" },
+      persist: "localStorage",
+    });
+
+    const alepha = Alepha.create();
+    expect(alepha.store.get(prefs)).toEqual({ theme: "light" });
+    expect(window.localStorage.getItem("test.persist.bad")).toBeNull();
+  });
+
+  it("supports sessionStorage", async () => {
+    const prefs = $atom({
+      name: "test.persist.session",
+      schema,
+      default: { theme: "light" },
+      persist: "sessionStorage",
+    });
+
+    const alepha = Alepha.create();
+    alepha.store.set(prefs, { theme: "dark" });
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(window.sessionStorage.getItem("test.persist.session")).toBe(
+      JSON.stringify({ theme: "dark" }),
+    );
+  });
+});

package/src/core/__tests__/StateManager.spec.ts

@@ -1,8 +1,13 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { Alepha } from "../Alepha.ts";
+import { AlephaError } from "../errors/AlephaError.ts";
+import { TypeBoxError } from "../errors/TypeBoxError.ts";
+import { $atom } from "../primitives/$atom.ts";
+import { $computed } from "../primitives/$computed.ts";
 import { AlsProvider } from "../providers/AlsProvider.ts";
 import { StateManager } from "../providers/StateManager.ts";
+import { z } from "../providers/TypeProvider.ts";
 
 // Set up AsyncLocalStorage for tests
 AlsProvider.create = () => new AsyncLocalStorage();
@@ -329,6 +334,237 @@ describe("StateManager", () => {
     });
   });
 
+  describe("Atom Validation", () => {
+    const prefs = $atom({
+      name: "test.validation.prefs",
+      schema: z.object({ theme: z.string(), count: z.number() }),
+      default: { theme: "light", count: 0 },
+    });
+
+    it("rejects a write that violates the schema", () => {
+      const alepha = Alepha.create();
+      expect(() =>
+        alepha.store.set(prefs, { theme: "dark", count: "nope" } as any),
+      ).toThrow(TypeBoxError);
+    });
+
+    it("strips unknown keys on write", () => {
+      const alepha = Alepha.create();
+      alepha.store.set(prefs, { theme: "dark", count: 1, extra: true } as any);
+      expect(alepha.store.get(prefs)).toEqual({ theme: "dark", count: 1 });
+    });
+
+    it("validates writes made through the raw string key once registered", () => {
+      const alepha = Alepha.create();
+      alepha.store.get(prefs); // registers the atom
+      expect(() =>
+        alepha.store.set("test.validation.prefs" as any, { theme: 1 } as any),
+      ).toThrow();
+    });
+
+    it("skips validation when skipValidation is set", () => {
+      const alepha = Alepha.create();
+      alepha.store.get(prefs);
+      alepha.store.set("test.validation.prefs" as any, { theme: 1 } as any, {
+        skipValidation: true,
+      });
+      expect((alepha.store.get(prefs) as any).theme).toBe(1);
+    });
+
+    it("falls back to the default when a pre-seeded value is invalid", () => {
+      const alepha = Alepha.create({
+        "test.validation.prefs": { theme: 42 },
+      } as any);
+      expect(alepha.store.get(prefs)).toEqual({ theme: "light", count: 0 });
+    });
+
+    it("warns when a pre-seeded value is invalid and falls back to the default", () => {
+      const warn = vi.fn();
+      const alepha = Alepha.create({
+        "test.validation.prefs": { theme: 42 },
+        "alepha.logger": {
+          trace: vi.fn(),
+          debug: vi.fn(),
+          info: vi.fn(),
+          warn,
+          error: vi.fn(),
+        },
+      } as any);
+
+      expect(alepha.store.get(prefs)).toEqual({ theme: "light", count: 0 });
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(warn.mock.calls[0][0]).toContain("test.validation.prefs");
+    });
+
+    it("decodes a valid pre-seeded value through the schema", () => {
+      const alepha = Alepha.create({
+        "test.validation.prefs": { theme: "dark", count: 2, junk: 1 },
+      } as any);
+      expect(alepha.store.get(prefs)).toEqual({ theme: "dark", count: 2 });
+    });
+
+    it("exposes registered atoms via getAtom", () => {
+      const alepha = Alepha.create();
+      alepha.store.get(prefs);
+      expect(alepha.store.getAtom("test.validation.prefs")).toBeDefined();
+      expect(alepha.store.getAtom("nope")).toBeUndefined();
+    });
+  });
+
+  describe("ALS-aware decode-at-registration", () => {
+    const settings = $atom({
+      name: "test.validation.als.settings",
+      schema: z.object({ theme: z.string(), count: z.number() }),
+      default: { theme: "light", count: 0 },
+    });
+
+    it("decodes a value written into a request-scoped ALS layer before the atom registers, in place", () => {
+      const alepha = Alepha.create();
+
+      const result = alepha.context.run(
+        () => {
+          // Simulate a fork-scoped write landing ahead of the atom's first
+          // access (e.g. $cookie mirroring a cookie value into the store
+          // during server:onRequest, before anything reads the atom).
+          alepha.store.set(
+            settings.key as any,
+            {
+              theme: "dark",
+              count: 1,
+              extra: true,
+            } as any,
+          );
+          return alepha.store.get(settings);
+        },
+        { context: "req-1" },
+      );
+
+      expect(result).toEqual({ theme: "dark", count: 1 });
+      // The fork's value must not have leaked into the app-level store...
+      expect(alepha.store.get(settings, "app")).not.toEqual({
+        theme: "dark",
+        count: 1,
+      });
+      // ...but the app-level store MUST still have received the atom's
+      // declared default. Registration inside a fork is still a
+      // registration: leaving the app store empty here is what made every
+      // later, fork-less (or cookie-less) read resolve `undefined` instead
+      // of the default.
+      expect(alepha.store.get(settings, "app")).toEqual({
+        theme: "light",
+        count: 0,
+      });
+    });
+
+    it("still resolves the default outside the fork after an atom first registered inside one", () => {
+      const alepha = Alepha.create();
+
+      alepha.context.run(
+        () => {
+          alepha.store.set(
+            settings.key as any,
+            {
+              theme: "dark",
+              count: 1,
+            } as any,
+          );
+          // First registration happens here, inside the fork.
+          alepha.store.get(settings);
+        },
+        { context: "req-1" },
+      );
+
+      // A later request (a different fork) carrying no seed of its own, and
+      // the app-level read outside any fork, both see the default.
+      const next = alepha.context.run(() => alepha.store.get(settings), {
+        context: "req-2",
+      });
+
+      expect(next).toEqual({ theme: "light", count: 0 });
+      expect(alepha.store.get(settings)).toEqual({ theme: "light", count: 0 });
+    });
+
+    it("falls back to the default inside the same ALS layer (not the app store) when the seeded value is invalid, and warns", () => {
+      const warn = vi.fn();
+      const alepha = Alepha.create({
+        "alepha.logger": {
+          trace: vi.fn(),
+          debug: vi.fn(),
+          info: vi.fn(),
+          warn,
+          error: vi.fn(),
+        },
+      } as any);
+
+      const result = alepha.context.run(
+        () => {
+          alepha.store.set(settings.key as any, { theme: 42 } as any);
+          return alepha.store.get(settings);
+        },
+        { context: "req-1" },
+      );
+
+      expect(result).toEqual({ theme: "light", count: 0 });
+      expect(warn).toHaveBeenCalledTimes(1);
+      // The invalid seed was replaced inside the ALS layer, and the app
+      // store holds the declared default (never the fork's value).
+      expect(alepha.store.get(settings, "app")).toEqual({
+        theme: "light",
+        count: 0,
+      });
+    });
+
+    it("hands out a fresh copy of the default when a seeded value is invalid — never the shared declaration", () => {
+      const alepha = Alepha.create();
+
+      const result = alepha.context.run(
+        () => {
+          alepha.store.set(settings.key as any, { theme: 42 } as any);
+          return alepha.store.get(settings);
+        },
+        { context: "req-1" },
+      );
+
+      // A careless caller mutates the value it got back from the
+      // fallback-to-default path.
+      (result as { count: number }).count = 424242;
+
+      // `atom.options.default` is a module-level object shared by every
+      // container in the process. If the fallback aliased it instead of
+      // cloning it through the validator, that mutation would have rewritten
+      // the declaration itself — permanently, for every request.
+      expect(settings.options.default).toEqual({ theme: "light", count: 0 });
+
+      const fresh = Alepha.create();
+      expect(fresh.store.get(settings)).toEqual({ theme: "light", count: 0 });
+    });
+
+    it("decodes a value that landed in a parent fork layer before a nested fork registers the atom", () => {
+      const alepha = Alepha.create();
+
+      const result = alepha.context.run(
+        () => {
+          alepha.store.set(
+            settings.key as any,
+            {
+              theme: "dark",
+              count: 5,
+            } as any,
+          );
+
+          // A nested fork (e.g. a batched sub-request) is the one that
+          // first accesses the atom — the raw value lives one layer up.
+          return alepha.context.run(() => alepha.store.get(settings), {
+            context: "req-1-child",
+          });
+        },
+        { context: "req-1" },
+      );
+
+      expect(result).toEqual({ theme: "dark", count: 5 });
+    });
+  });
+
   describe("Mixed ALS and Local Store Scenarios", () => {
     let alepha: Alepha;
     let stateManager: StateManager<TestState>;
@@ -373,4 +609,191 @@ describe("StateManager", () => {
       expect(keys).toEqual(["active"]);
     });
   });
+
+  describe("Reset, Watch, ServerOnly", () => {
+    const counter = $atom({
+      name: "test.extras.counter",
+      schema: z.object({ value: z.number() }),
+      default: { value: 0 },
+    });
+
+    const secret = $atom({
+      name: "test.extras.secret",
+      schema: z.object({ token: z.string() }),
+      default: { token: "" },
+      serverOnly: true,
+    });
+
+    const doubledCounter = $computed({
+      name: "test.extras.doubled",
+      deps: [counter],
+      get: (c) => c.value * 2,
+    });
+
+    const other = $atom({
+      name: "test.extras.other",
+      schema: z.object({ value: z.number() }),
+      default: { value: 0 },
+    });
+
+    const total = $computed({
+      name: "test.extras.total",
+      deps: [counter, other],
+      get: (c, o) => c.value + o.value,
+    });
+
+    it("reset restores the declared default", () => {
+      const alepha = Alepha.create();
+      alepha.store.set(counter, { value: 99 });
+      alepha.store.reset(counter);
+      expect(alepha.store.get(counter)).toEqual({ value: 0 });
+    });
+
+    it("reset is exposed on the Alepha instance", () => {
+      const alepha = Alepha.create();
+      alepha.store.set(counter, { value: 99 });
+      alepha.reset(counter);
+      expect(alepha.get(counter)).toEqual({ value: 0 });
+    });
+
+    it("watch fires with value and previous value", async () => {
+      const alepha = Alepha.create();
+      const calls: Array<[unknown, unknown]> = [];
+
+      alepha.store.watch(counter, (value, prevValue) => {
+        calls.push([value, prevValue]);
+      });
+
+      alepha.store.set(counter, { value: 1 });
+      await new Promise((r) => setTimeout(r, 0));
+
+      expect(calls).toEqual([[{ value: 1 }, { value: 0 }]]);
+    });
+
+    it("watch returns an unsubscribe function", async () => {
+      const alepha = Alepha.create();
+      const calls: unknown[] = [];
+
+      const off = alepha.store.watch(counter, (value) => {
+        calls.push(value);
+      });
+      off();
+
+      alepha.store.set(counter, { value: 1 });
+      await new Promise((r) => setTimeout(r, 0));
+
+      expect(calls).toEqual([]);
+    });
+
+    it("watch supports computed values", async () => {
+      const alepha = Alepha.create();
+      const calls: Array<[unknown, unknown]> = [];
+
+      alepha.store.watch(doubledCounter, (value, prevValue) => {
+        calls.push([value, prevValue]);
+      });
+
+      alepha.store.set(counter, { value: 5 });
+      await new Promise((r) => setTimeout(r, 0));
+
+      expect(calls).toEqual([[10, 0]]);
+    });
+
+    it("register refuses a Computed, so it can never reach exportAtoms", () => {
+      const alepha = Alepha.create();
+
+      // `reset()`/`register()` are the only atom entry points that took a
+      // Computed without complaint. A registered Computed would land in the
+      // atom registry and from there be serialized into the SSR hydration
+      // payload — breaking the "never stored, never serialized" contract.
+      expect(() => alepha.store.reset(doubledCounter as any)).toThrow(
+        AlephaError,
+      );
+      expect(() => alepha.store.register(doubledCounter as any)).toThrow(
+        /Cannot register computed value/,
+      );
+      expect(alepha.store.getAtom("test.extras.doubled")).toBeUndefined();
+      expect(alepha.store.exportAtoms()["test.extras.doubled"]).toBeUndefined();
+    });
+
+    it("serverOnly atoms are excluded from exportAtoms", () => {
+      const alepha = Alepha.create();
+      alepha.store.set(counter, { value: 1 });
+      alepha.store.set(secret, { token: "s3cret" });
+
+      const exported = alepha.store.exportAtoms();
+      expect(exported["test.extras.counter"]).toEqual({ value: 1 });
+      expect(exported["test.extras.secret"]).toBeUndefined();
+    });
+
+    it("serverOnly atoms are excluded from exportAtoms('current') — the ALS/SSR branch", () => {
+      // This is the branch ReactServerTemplateProvider.buildHydrationData()
+      // actually calls during SSR (exportAtoms("current")), serializing the
+      // result straight into the <script id="__ssr"> hydration payload. The
+      // default-branch test above does not exercise this code path at all.
+      const alepha = Alepha.create();
+
+      const exported = alepha.context.run(
+        () => {
+          alepha.store.set(counter, { value: 7 });
+          alepha.store.set(secret, { token: "s3cret" });
+          return alepha.store.exportAtoms("current");
+        },
+        { context: "test.extras.ssr-fork" },
+      );
+
+      expect(exported["test.extras.counter"]).toEqual({ value: 7 });
+      expect(exported["test.extras.secret"]).toBeUndefined();
+    });
+
+    it("watch on a computed tracks prevValue correctly across two different dependency keys", async () => {
+      const alepha = Alepha.create();
+      const calls: Array<[unknown, unknown]> = [];
+
+      alepha.store.watch(total, (value, prevValue) => {
+        calls.push([value, prevValue]);
+      });
+
+      // Mutate the first dep key.
+      alepha.store.set(counter, { value: 3 });
+      await new Promise((r) => setTimeout(r, 0));
+
+      // Then mutate a *different* dep key. The computed's own `prev` must
+      // have been updated after the first callback, or this second call
+      // would report a stale prevValue.
+      alepha.store.set(other, { value: 4 });
+      await new Promise((r) => setTimeout(r, 0));
+
+      expect(calls).toEqual([
+        [3, 0],
+        [7, 3],
+      ]);
+    });
+
+    it("reset's clone of the default cannot corrupt future resets (zod parse always returns a fresh object)", () => {
+      const alepha = Alepha.create();
+      alepha.store.set(counter, { value: 99 });
+      alepha.store.reset(counter);
+
+      const resetValue = alepha.store.get(counter);
+      expect(resetValue).toEqual({ value: 0 });
+
+      // A careless caller mutates the value handed back by reset/get.
+      (resetValue as { value: number }).value = 424242;
+
+      // The atom's declared default itself must be untouched: `reset()` ->
+      // `set()` -> `SchemaValidator.validate()` runs `schema.safeParse()`,
+      // and zod's object parsing always returns a brand-new object, never
+      // the same reference as `atom.options.default` — even when the input
+      // is already valid. So the mutation above can never reach here.
+      expect(counter.options.default).toEqual({ value: 0 });
+
+      // Prove it end-to-end too: a fresh container resets to the pristine
+      // default, unaffected by the mutation performed above.
+      const freshAlepha = Alepha.create();
+      freshAlepha.store.set(counter, { value: 1 });
+      freshAlepha.store.reset(counter);
+      expect(freshAlepha.store.get(counter)).toEqual({ value: 0 });
+    });
+  });
 });

package/src/core/__tests__/TypeBox-usecases.spec.ts

@@ -1,16 +1,16 @@
-import { Alepha, t } from "alepha";
+import { Alepha, z } from "alepha";
 import { describe, expect, it } from "vitest";
 
 describe("TypeBox Use Cases", () => {
-  it("should remove property when omitted in schema with t.interface()", () => {
-    const entity = t.object({
-      id: t.integer(),
-      name: t.string(),
-      retryCount: t.optional(t.nullable(t.integer())),
+  it("should remove property when omitted in schema with z.interface()", () => {
+    const entity = z.object({
+      id: z.integer(),
+      name: z.string(),
+      retryCount: z.integer().nullable().optional(),
     });
 
-    const testPageSchema = t.object({
-      content: t.array(t.extend(t.omit(entity, ["retryCount"]), {})),
+    const testPageSchema = z.object({
+      content: z.array(entity.omit({ retryCount: true }).extend({})),
     });
 
     const testObject = {