alepha 0.22.0 → 0.24.0

package/src/server/cookies/index.browser.ts

@@ -1,14 +1,17 @@
 import { $module } from "alepha";
 import { AlephaServer } from "alepha/server";
+import { AtomCookiePersistence } from "./providers/AtomCookiePersistence.browser.ts";
+import { CookieParser } from "./services/CookieParser.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
 export * from "./primitives/$cookie.browser.ts";
+export * from "./providers/AtomCookiePersistence.browser.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
 export const AlephaServerCookies = $module({
   name: "alepha.server.cookies",
   primitives: [],
-  services: [AlephaServer],
+  services: [AlephaServer, CookieParser, AtomCookiePersistence],
 });

package/src/server/cookies/index.ts

@@ -1,12 +1,14 @@
 import { $module } from "alepha";
 import { AlephaServer } from "alepha/server";
 import { $cookie, type Cookies } from "./primitives/$cookie.ts";
+import { AtomCookiePersistence } from "./providers/AtomCookiePersistence.ts";
 import { ServerCookiesProvider } from "./providers/ServerCookiesProvider.ts";
 import { CookieParser } from "./services/CookieParser.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
 export * from "./primitives/$cookie.ts";
+export * from "./providers/AtomCookiePersistence.ts";
 export * from "./providers/ServerCookiesProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -28,5 +30,10 @@ declare module "alepha/server" {
 export const AlephaServerCookies = $module({
   name: "alepha.server.cookies",
   primitives: [$cookie],
-  services: [AlephaServer, ServerCookiesProvider, CookieParser],
+  services: [
+    AlephaServer,
+    ServerCookiesProvider,
+    CookieParser,
+    AtomCookiePersistence,
+  ],
 });

package/src/server/cookies/primitives/$cookie.browser.ts

@@ -31,7 +31,7 @@ import type {
  * class ClientCookies {
  *   preferences = $cookie({
  *     name: "user-prefs",
- *     schema: t.object({ theme: t.text(), language: t.text() }),
+ *     schema: z.object({ theme: z.text(), language: z.text() }),
  *     ttl: [30, "days"]
  *   });
  *

package/src/server/cookies/primitives/$cookie.ts

@@ -90,6 +90,22 @@ export interface CookiePrimitiveOptions<T extends TSchema> {
    * Optional key to link this cookie to an Atom, enabling automatic synchronization between the cookie and the Atom's state.
    */
   key?: string;
+
+  /**
+   * Internal escape hatch: when explicitly set to `false`, the server skips
+   * the `APP_NAME` cookie-name namespace applied by
+   * `ServerCookiesProvider.prefixName()`.
+   *
+   * Used by `AtomCookiePersistence` so the cookie name the server
+   * reads/writes for a `persist: "cookie"` atom matches the bare name its
+   * browser variant uses — `APP_NAME` is not reachable client-side (not
+   * baked into the client bundle, not part of SSR hydration), so the
+   * browser can only ever use the bare atom key.
+   *
+   * Application code declaring `$cookie(...)` directly should leave this
+   * unset — it defaults to `true` (prefixed), matching every other cookie.
+   */
+  prefix?: boolean;
 }
 
 export interface AbstractCookiePrimitive<T extends TSchema> {

package/src/server/cookies/providers/AtomCookiePersistence.browser.ts

@@ -0,0 +1,133 @@
+import { $hook, $inject, Alepha, type Atom, type State } from "alepha";
+import { DateTimeProvider } from "alepha/datetime";
+import type { Cookie } from "../primitives/$cookie.ts";
+import { CookieParser } from "../services/CookieParser.ts";
+
+/**
+ * Browser variant of AtomCookiePersistence: reads `document.cookie` for every
+ * `persist: "cookie"` atom, and writes it back on every mutation.
+ *
+ * Like the server variant, atoms are resolved from the `StateManager`
+ * registry (`alepha.store.listAtoms()`) rather than from a map fed by
+ * `state:register` — that event fires once, is never replayed, and
+ * `$module.register()` registers `atoms[]` before the module's `services[]`
+ * exist, so an event-sourced map would miss every atom declared the
+ * documented way. The `configure` hook sweeps everything registered up to
+ * boot; `state:register` covers atoms that first register later (lazily, on
+ * first read).
+ *
+ * Cookie names are NOT APP_NAME-prefixed here, because `APP_NAME` is not
+ * reachable in the browser: `BuildClientTask` only `define`s
+ * `process.env.NODE_ENV` for the client bundle, and the SSR hydration
+ * payload (`ReactServerTemplateProvider.buildHydrationData`) only carries
+ * registered atom values + router layers — never the raw `env` store key.
+ * The server variant (`AtomCookiePersistence.ts`) matches this by passing
+ * `prefix: false` to `ServerCookiesProvider`, specifically for atom-cookie
+ * traffic — every other server cookie ($cookie primitive) still gets the
+ * APP_NAME namespace. See `ServerCookiesProvider.prefixName`.
+ */
+export class AtomCookiePersistence {
+  protected readonly alepha = $inject(Alepha);
+  protected readonly cookieParser = $inject(CookieParser);
+  protected readonly dateTime = $inject(DateTimeProvider);
+
+  protected readonly onConfigure = $hook({
+    on: "configure",
+    handler: () => {
+      for (const atom of this.cookieAtoms()) {
+        this.read(atom);
+      }
+    },
+  });
+
+  protected readonly onRegister = $hook({
+    on: "state:register",
+    handler: ({ atom }) => {
+      if (atom.options.persist !== "cookie") {
+        return;
+      }
+      this.read(atom);
+    },
+  });
+
+  protected readonly onMutate = $hook({
+    on: "state:mutate",
+    handler: ({ key, value }) => {
+      const atom = this.alepha.store.getAtom(String(key));
+      if (!atom || atom.options.persist !== "cookie") {
+        return;
+      }
+
+      if (value === undefined) {
+        // Without this branch, `store.del(atom)` would write the literal
+        // string "undefined", and the next read's `JSON.parse("undefined")`
+        // would throw into the catch in `read()` on every page load.
+        this.clearCookie(atom.key);
+        return;
+      }
+
+      const cookie: Cookie = {
+        value: encodeURIComponent(JSON.stringify(value)),
+        path: "/",
+        sameSite: "lax",
+        maxAge: this.dateTime.duration([365, "days"]).as("seconds"),
+      };
+      // biome-ignore lint/suspicious/noDocumentCookie: cookie persistence adapter
+      document.cookie = this.cookieParser.cookieToString(atom.key, cookie);
+    },
+  });
+
+  /**
+   * Every registered atom declared with `persist: "cookie"`, read live from
+   * the state manager's registry.
+   */
+  protected cookieAtoms(): Array<Atom<any, any>> {
+    return this.alepha.store
+      .listAtoms()
+      .filter((atom) => atom.options.persist === "cookie");
+  }
+
+  /**
+   * Seed an atom's state from `document.cookie`, if a cookie exists for it.
+   * Idempotent: re-reading an atom that already holds the cookie's value is
+   * a no-op write of the same data.
+   */
+  protected read(atom: Atom<any, any>): void {
+    const raw = this.cookieParser.parseRequestCookies(document.cookie)[
+      atom.key
+    ];
+    if (!raw) {
+      return;
+    }
+
+    try {
+      this.alepha.store.set(
+        atom.key as keyof State,
+        JSON.parse(decodeURIComponent(raw)),
+        { skipEvents: true },
+      );
+    } catch {
+      // Corrupted cookie (invalid JSON/encoding, or a value that no longer
+      // matches the atom's schema — `store.set` validates against it) —
+      // clear it instead of leaving it to keep throwing on every future
+      // read. Mirrors the web-storage adapter's parity
+      // (StateManager.bindWebStorage removes the bad entry too).
+      this.clearCookie(atom.key);
+    }
+  }
+
+  /**
+   * Expire a cookie immediately, mirroring
+   * `ServerCookiesProvider.deleteCookie`'s `Max-Age=0` semantics.
+   */
+  protected clearCookie(name: string): void {
+    const cookie: Cookie = {
+      value: "",
+      path: "/",
+      sameSite: "lax",
+      maxAge: 0,
+    };
+    // biome-ignore lint/suspicious/noDocumentCookie: cookie persistence adapter
+    document.cookie = this.cookieParser.cookieToString(name, cookie);
+  }
+}

package/src/server/cookies/providers/AtomCookiePersistence.ts

@@ -0,0 +1,148 @@
+import { $hook, $inject, Alepha, type Atom, type State } from "alepha";
+import type { DurationLike } from "alepha/datetime";
+import { $logger } from "alepha/logger";
+import type { Cookies } from "../primitives/$cookie.ts";
+import { ServerCookiesProvider } from "./ServerCookiesProvider.ts";
+
+/**
+ * Binds every atom declared with `persist: "cookie"` to an HTTP cookie.
+ *
+ * - `server:onRequest` — seeds the request-scoped state from the cookie, so
+ *   SSR renders with the persisted value.
+ * - `state:mutate` — writes the new value back as a Set-Cookie header.
+ * - `state:register` — an atom registering lazily *during* a request (first
+ *   touched by an SSR render, after `server:onRequest` already ran) reads
+ *   its cookie right away, so that render still sees the persisted value.
+ *
+ * Atoms are resolved from the `StateManager` registry
+ * (`alepha.store.listAtoms()`) on every request and every mutation, never
+ * from a map built up from `state:register` events. That event fires exactly
+ * once per atom and is never replayed, while `$module.register()` registers
+ * `atoms[]` BEFORE it wires `imports[]` and injects `services[]` — so the
+ * documented `$module({ atoms, imports: [AlephaServerCookies], services })`
+ * shape registers every atom before this provider exists. An event-sourced
+ * map would stay empty forever there, making `persist: "cookie"` a silent
+ * no-op in both directions. Reading the registry on demand is
+ * order-independent.
+ *
+ * The cookie is named after the atom key, lives 365 days, SameSite=lax,
+ * path "/". For custom cookie options (encryption, signing, custom TTL),
+ * declare an explicit `$cookie({ key: atom.key, ... })` binding instead.
+ */
+export class AtomCookiePersistence {
+  protected readonly alepha = $inject(Alepha);
+  protected readonly log = $logger();
+  protected readonly serverCookies = $inject(ServerCookiesProvider);
+
+  protected readonly onRequest = $hook({
+    on: "server:onRequest",
+    // Explicit dependency instead of relying on `services` array order in
+    // `AlephaServerCookies`: this hook needs `request.cookies`, which is
+    // only populated by `ServerCookiesProvider.onRequest`. If that ever ran
+    // second, `getCookiesFromContext` would throw, get caught, and log at
+    // debug — cookies silently ignored in production with no visible error.
+    after: [this.serverCookies],
+    handler: ({ request }) => {
+      // `alepha.http.request` is not set in the store yet at this point in
+      // the request lifecycle (`ServerRouterProvider` sets it only after
+      // `server:onRequest` resolves), so the request-scoped cookie jar must
+      // be passed explicitly rather than resolved from context.
+      for (const atom of this.cookieAtoms()) {
+        this.read(atom, request.cookies);
+      }
+    },
+  });
+
+  protected readonly onRegister = $hook({
+    on: "state:register",
+    handler: ({ atom }) => {
+      if (atom.options.persist !== "cookie") {
+        return;
+      }
+
+      // Only the lazy, mid-request case is handled here — every atom already
+      // registered when the request started was swept by `onRequest` above.
+      if (this.alepha.store.get("alepha.http.request")) {
+        this.read(atom);
+      }
+    },
+  });
+
+  protected readonly onMutate = $hook({
+    on: "state:mutate",
+    handler: ({ key, value }) => {
+      const atom = this.alepha.store.getAtom(String(key));
+      if (!atom || atom.options.persist !== "cookie") {
+        return;
+      }
+      try {
+        this.serverCookies.setCookie(atom.key, this.cookieOptions(atom), value);
+      } catch (error) {
+        // Outside a request cycle there is no response to attach the
+        // Set-Cookie header to; browser-side writes are handled by the
+        // browser variant of this provider.
+        this.log.debug(`Cannot persist atom "${atom.key}" to cookie`, {
+          error,
+        });
+      }
+    },
+  });
+
+  /**
+   * Every registered atom declared with `persist: "cookie"`, read live from
+   * the state manager's registry.
+   */
+  protected cookieAtoms(): Array<Atom<any, any>> {
+    return this.alepha.store
+      .listAtoms()
+      .filter((atom) => atom.options.persist === "cookie");
+  }
+
+  protected read(atom: Atom<any, any>, cookies?: Cookies): void {
+    // Safety net, not a live bug today: an ALS provider is always installed
+    // by `core/index.ts` / `core/index.workerd.ts`, so every request already
+    // runs inside its own fork. But `store.set(..., { skipEvents: true })`
+    // below has no `skipContext`, so if no fork were active,
+    // `StateManager.set()` would fall through to writing the APP-LEVEL
+    // store — turning one user's cookie value into what every subsequent
+    // cookieless request reads. Degrade to "cookie ignored" instead.
+    if (!this.alepha.context.exists()) {
+      this.log.debug(
+        `Skipping cookie read for atom "${atom.key}": no active request context.`,
+      );
+      return;
+    }
+
+    try {
+      const value = this.serverCookies.getCookie(
+        atom.key,
+        this.cookieOptions(atom),
+        cookies,
+      );
+      if (value !== undefined) {
+        this.alepha.store.set(atom.key as keyof State, value, {
+          skipEvents: true,
+        });
+      }
+    } catch (error) {
+      this.log.debug(`Cannot read cookie for atom "${atom.key}"`, { error });
+    }
+  }
+
+  protected cookieOptions(atom: Atom<any, any>) {
+    return {
+      schema: atom.schema,
+      path: "/",
+      sameSite: "lax" as const,
+      ttl: [365, "days"] as DurationLike,
+      // The browser variant of this adapter cannot see APP_NAME (not baked
+      // into the client bundle, not part of SSR hydration — see
+      // AtomCookiePersistence.browser.ts), so it always reads/writes the
+      // bare atom key. Skip the APP_NAME prefix here too — specifically for
+      // atom-persisted cookies — so both sides agree on the same cookie
+      // name. Every other server cookie ($cookie primitive) still gets the
+      // namespace; see ServerCookiesProvider.prefixName.
+      prefix: false,
+    };
+  }
+}

package/src/server/cookies/providers/ServerCookiesProvider.ts

@@ -88,13 +88,40 @@ export class ServerCookiesProvider {
     );
   }
 
+  /**
+   * Namespaces a cookie name with the app's `APP_NAME` (lowercased) so that
+   * two Alepha apps sharing a cookie jar do not collide.
+   *
+   * Cookies are scoped by host + path only — never by port — so two apps on
+   * `localhost:3000` and `localhost:4000` would otherwise both read/write a
+   * cookie literally named `tokens` and silently clobber each other (and,
+   * because each encrypts with its own `APP_SECRET`, the foreign cookie fails
+   * to decrypt and gets deleted, logging the user out).
+   *
+   * When `APP_NAME` is unset the name is returned unchanged, so existing
+   * single-app deployments keep their current cookie names. Same convention as
+   * the `APP_NAME` prefix used by R2 storage and server-timing.
+   *
+   * Pass `prefix = false` to skip the namespace entirely — used for
+   * `persist: "cookie"` atoms, whose browser-side counterpart cannot see
+   * `APP_NAME` and therefore always uses the bare name. See
+   * `CookiePrimitiveOptions.prefix`.
+   */
+  protected prefixName(name: string, prefix = true): string {
+    if (!prefix) return name;
+    const app = this.alepha.env.APP_NAME;
+    if (!app) return name;
+    return `${String(app).toLowerCase()}.${name}`;
+  }
+
   public getCookie<T extends TSchema>(
     name: string,
     options: CookiePrimitiveOptions<T>,
     contextCookies?: Cookies,
   ): Static<T> | undefined {
     const cookies = this.getCookiesFromContext(contextCookies);
-    let rawValue = cookies.req[name];
+    const prefixed = options.prefix !== false;
+    let rawValue = cookies.req[this.prefixName(name, prefixed)];
 
     if (!rawValue) return undefined;
 
@@ -132,7 +159,7 @@ export class ServerCookiesProvider {
     } catch (error) {
       this.log.warn(`Failed to parse cookie "${name}"`, error);
       // corrupted or invalid cookie, instruct browser to delete it on next response
-      this.deleteCookie(name, cookies);
+      this.deleteCookie(name, cookies, prefixed);
       return undefined;
     }
   }
@@ -174,15 +201,16 @@ export class ServerCookiesProvider {
       cookie.maxAge = this.dateTimeProvider.duration(options.ttl).as("seconds");
     }
 
-    cookies.res[name] = cookie;
+    cookies.res[this.prefixName(name, options.prefix !== false)] = cookie;
   }
 
   public deleteCookie<T extends TSchema>(
     name: string,
     contextCookies?: Cookies,
+    prefix = true,
   ): void {
     const cookies = this.getCookiesFromContext(contextCookies);
-    cookies.res[name] = null;
+    cookies.res[this.prefixName(name, prefix)] = null;
   }
 
   // --- Crypto & Parsing ---

package/src/server/cookies/services/CookieParser.ts

@@ -58,7 +58,12 @@ export class CookieParser {
     if (cookie.path) {
       parts.push(`Path=${cookie.path}`);
     }
-    if (cookie.maxAge) {
+    // `!= null`, not truthy: `maxAge: 0` is the standard "delete this
+    // cookie now" value (used by AtomCookiePersistence.browser.ts's
+    // clearCookie() and BrowserCookiePrimitive.del()). A truthy check would
+    // silently drop `Max-Age` for exactly that value, turning a deletion
+    // into a plain (non-expiring-until-session-end) write.
+    if (cookie.maxAge != null) {
       parts.push(`Max-Age=${cookie.maxAge}`);
     }
     if (cookie.secure !== false && isHttps) {

package/src/server/core/__tests__/$action.spec.ts

@@ -1,4 +1,4 @@
-import { Alepha, t } from "alepha";
+import { Alepha, z } from "alepha";
 import { FileSystemProvider } from "alepha/system";
 import { describe, test } from "vitest";
 import { $action } from "../index.ts";
@@ -8,14 +8,14 @@ describe("$action", () => {
     class Api {
       hello = $action({
         schema: {
-          params: t.object({
-            name: t.text(),
+          params: z.object({
+            name: z.text(),
           }),
-          query: t.object({
-            transform: t.optional(t.enum(["uppercase"])),
+          query: z.object({
+            transform: z.enum(["uppercase"]).optional(),
           }),
-          response: t.object({
-            message: t.text(),
+          response: z.object({
+            message: z.text(),
           }),
         },
         handler: ({ params, query }) => {
@@ -91,7 +91,7 @@ describe("$action", () => {
     class TestApp {
       test = $action({
         schema: {
-          response: t.void(), // force no response
+          response: z.void(), // force no response
         },
         handler: () => {},
       });
@@ -113,7 +113,7 @@ describe("$action", () => {
     class TestApp {
       test = $action({
         schema: {
-          response: t.json(),
+          response: z.json(),
         },
         handler: () => ({
           ok: true,
@@ -136,7 +136,7 @@ describe("$action", () => {
     class TestApp {
       test = $action({
         schema: {
-          response: t.file(), // expect a file response
+          response: z.file(), // expect a file response
         },
         handler: () =>
           fileSystem.createFile({
@@ -164,10 +164,10 @@ describe("$action", () => {
     class TestApp {
       test = $action({
         schema: {
-          body: t.object({
-            extra: t.text(),
+          body: z.object({
+            extra: z.text(),
           }),
-          response: t.string(),
+          response: z.string(),
         },
         handler: ({ body }) => JSON.stringify(body),
       });

package/src/server/core/__tests__/$middleware.spec.ts

@@ -1,4 +1,4 @@
-import { Alepha, createMiddleware, t } from "alepha";
+import { Alepha, createMiddleware, z } from "alepha";
 import { describe, test } from "vitest";
 import { $action, $middleware, $route, ServerProvider } from "../index.ts";
 
@@ -26,7 +26,7 @@ describe("$middleware", () => {
       });
 
       hello = $action({
-        schema: { response: t.object({ message: t.text() }) },
+        schema: { response: z.object({ message: z.text() }) },
         handler: () => {
           log.push("handler");
           return { message: "hello" };
@@ -55,7 +55,7 @@ describe("$middleware", () => {
       });
 
       hello = $action({
-        schema: { response: t.text() },
+        schema: { response: z.text() },
         handler: () => {
           log.push("handler");
           return "ok";
@@ -83,7 +83,7 @@ describe("$middleware", () => {
       });
 
       hello = $action({
-        schema: { response: t.text() },
+        schema: { response: z.text() },
         handler: () => {
           log.push("handler");
           return "ok";
@@ -110,7 +110,7 @@ describe("$middleware", () => {
       });
 
       getAction = $action({
-        schema: { response: t.text() },
+        schema: { response: z.text() },
         handler: () => {
           log.push("get");
           return "ok";
@@ -120,8 +120,8 @@ describe("$middleware", () => {
       postAction = $action({
         method: "POST",
         schema: {
-          body: t.object({ value: t.text() }),
-          response: t.text(),
+          body: z.object({ value: z.text() }),
+          response: z.text(),
         },
         handler: () => {
           log.push("post");
@@ -154,7 +154,7 @@ describe("$middleware", () => {
 
       health = $action({
         path: "/health",
-        schema: { response: t.text() },
+        schema: { response: z.text() },
         handler: () => {
           log.push("health");
           return "ok";
@@ -162,7 +162,7 @@ describe("$middleware", () => {
       });
 
       hello = $action({
-        schema: { response: t.text() },
+        schema: { response: z.text() },
         handler: () => {
           log.push("hello");
           return "ok";
@@ -193,7 +193,7 @@ describe("$middleware", () => {
 
       hello = $action({
         use: [$track(log, "local")],
-        schema: { response: t.text() },
+        schema: { response: z.text() },
         handler: () => {
           log.push("handler");
           return "ok";

package/src/server/core/__tests__/$route.spec.ts

@@ -1,4 +1,4 @@
-import { Alepha, createMiddleware, t } from "alepha";
+import { Alepha, createMiddleware, z } from "alepha";
 import { describe, test } from "vitest";
 import { $route, ServerProvider } from "../index.ts";
 
@@ -28,14 +28,14 @@ describe("$route", () => {
       $route = $route({
         path: "/hello",
         schema: {
-          query: t.object({
-            a: t.optional(t.text()),
-            b: t.optional(t.array(t.text())),
-            c: t.optional(
-              t.object({
-                d: t.text(),
-              }),
-            ),
+          query: z.object({
+            a: z.text().optional(),
+            b: z.array(z.text()).optional(),
+            c: z
+              .object({
+                d: z.text(),
+              })
+              .optional(),
           }),
         },
         handler: ({ query }) => JSON.stringify({ query }),