alabjs 0.1.0

package/src/client/hooks.ts

@@ -0,0 +1,329 @@
+import { use, useReducer, useTransition, useCallback, useState, useEffect, useRef } from "react";
+import type { ServerFn, InferServerOutput, RouteParams, InferServerPath } from "../types/index.js";
+
+// Promise cache keyed by URL.
+// • On the SERVER: cleared before each page render (via _clearALabSSRCache) so
+//   re-renders after Suspense resolution return the same promise object, which
+//   is required for renderToPipeableStream to correctly resolve Suspense.
+// • On the CLIENT: intentionally persists for the session to avoid redundant
+//   network round-trips on subsequent re-renders.
+const _promiseCache = new Map<string, Promise<unknown>>();
+
+/** Clear the server-side promise cache between SSR renders. Called by alab's dev server. */
+export function _clearALabSSRCache(): void {
+  _promiseCache.clear();
+}
+
+/**
+ * Fetch server data with full type inference from a `ServerFn`.
+ *
+ * Use `import type` to reference the server function — type-only imports
+ * are erased at compile time and never cross the server/client boundary.
+ *
+ * @example
+ * ```tsx
+ * // app/posts/[id]/page.tsx
+ * import type { getPost } from "./page.server"; // ← import type, safe
+ * import { useServerData } from "alabjs/client";
+ *
+ * export default function PostPage({ params }: { params: { id: string } }) {
+ *   // Return type is inferred from getPost — no manual type annotation needed
+ *   const post = useServerData<typeof getPost>("getPost", params);
+ *   post.title; // ✅ typed
+ *   post.foo;   // ✅ TS error — doesn't exist on the return type
+ * }
+ * ```
+ */
+export function useServerData<T extends ServerFn<any, any, any>>(
+  fnName: string,
+  params?: RouteParams<InferServerPath<T>>,
+): InferServerOutput<T> {
+  const searchParams = params
+    ? new URLSearchParams(params as Record<string, string>).toString()
+    : "";
+  // When running in Node.js (SSR) fetch requires an absolute URL.
+  // Alab's dev/prod server sets ALAB_ORIGIN before rendering each page.
+  const origin =
+    typeof window !== "undefined"
+      ? ""
+      : (process.env["ALAB_ORIGIN"] ?? "http://localhost:3000");
+
+  const url = `${origin}/_alabjs/data/${fnName}${searchParams ? `?${searchParams}` : ""}`;
+
+  let promise = _promiseCache.get(url) as Promise<InferServerOutput<T>> | undefined;
+  if (!promise) {
+    promise = fetch(url).then((r): Promise<InferServerOutput<T>> => {
+      if (!r.ok) throw new Error(`[alabjs] server data fetch failed: ${r.status} ${r.statusText} — ${url}`);
+      return r.json() as Promise<InferServerOutput<T>>;
+    });
+    _promiseCache.set(url, promise);
+  }
+
+  return use(promise);
+}
+
+// ─── Mutation state machine ────────────────────────────────────────────────────
+
+type MutationState<Output> =
+  | { status: "idle";    data: undefined; error: undefined; zodError: undefined }
+  | { status: "pending"; data: undefined; error: undefined; zodError: undefined }
+  | { status: "success"; data: Output;   error: undefined; zodError: undefined }
+  | { status: "error";   data: undefined; error: Error;    zodError: undefined }
+  | { status: "invalid"; data: undefined; error: undefined; zodError: unknown };
+
+type MutationAction<Output> =
+  | { type: "start" }
+  | { type: "success"; data: Output }
+  | { type: "error"; error: Error }
+  | { type: "invalid"; zodError: unknown }
+  | { type: "reset" };
+
+function mutationReducer<Output>(
+  _state: MutationState<Output>,
+  action: MutationAction<Output>,
+): MutationState<Output> {
+  switch (action.type) {
+    case "start":   return { status: "pending", data: undefined, error: undefined, zodError: undefined };
+    case "success": return { status: "success", data: action.data, error: undefined, zodError: undefined };
+    case "error":   return { status: "error",   data: undefined, error: action.error, zodError: undefined };
+    case "invalid": return { status: "invalid", data: undefined, error: undefined, zodError: action.zodError };
+    case "reset":   return { status: "idle",    data: undefined, error: undefined, zodError: undefined };
+  }
+}
+
+// ─── useMutation options ───────────────────────────────────────────────────────
+
+export interface UseMutationOptions<Output, Input> {
+  /**
+   * Compute an optimistic value from the input immediately — before the server
+   * responds. The component sees this value via `optimisticData` while the
+   * request is in flight.
+   *
+   * On server error, `optimisticData` is cleared and `onError` is called with
+   * a `rollback` callback you can use to undo any local side effects.
+   */
+  optimistic?: (input: Input) => Partial<Output>;
+  /** Called when the mutation succeeds with the server response. */
+  onSuccess?: (data: Output) => void;
+  /**
+   * Called when the mutation fails.
+   * `rollback()` clears the optimistic value and resets state to idle.
+   */
+  onError?: (err: Error, rollback: () => void) => void;
+}
+
+/**
+ * Trigger a server function mutation from the client, with full async state
+ * and optional optimistic updates.
+ *
+ * @example
+ * ```tsx
+ * import type { updateTodo } from "./page.server";
+ * import { useMutation } from "alabjs/client";
+ *
+ * // Basic
+ * const { mutate, data, isPending, error, zodError, reset } =
+ *   useMutation<typeof updateTodo>("updateTodo");
+ *
+ * // With optimistic update
+ * const { mutate, optimisticData } = useMutation<typeof updateTodo>("updateTodo", {
+ *   optimistic: (input) => ({ ...currentTodo, ...input }),
+ *   onError: (err, rollback) => rollback(),
+ * });
+ * ```
+ */
+export function useMutation<T extends ServerFn<any, any, any>>(
+  fnName: string,
+  options?: UseMutationOptions<InferServerOutput<T>, T extends ServerFn<infer I, any, any> ? I : never>,
+) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  type Input = T extends ServerFn<infer I, any, any> ? I : never;
+  type Output = InferServerOutput<T>;
+
+  const [state, dispatch] = useReducer(
+    mutationReducer<Output>,
+    { status: "idle", data: undefined, error: undefined, zodError: undefined } as MutationState<Output>,
+  );
+
+  // Optimistic value lives in separate state so it can be cleared independently.
+  const [optimisticData, setOptimisticData] = useState<Partial<Output> | undefined>(undefined);
+
+  const [isPending, startTransition] = useTransition();
+
+  const rollback = useCallback(() => {
+    setOptimisticData(undefined);
+    dispatch({ type: "reset" });
+  }, []);
+
+  const mutate = useCallback((input: Input): void => {
+    dispatch({ type: "start" });
+
+    if (options?.optimistic) {
+      setOptimisticData(options.optimistic(input));
+    }
+
+    startTransition(() => {
+      void (async () => {
+        try {
+          const r = await fetch(`/_alabjs/fn/${fnName}`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(input),
+          });
+
+          // Zod validation error from server
+          if (r.status === 422) {
+            const body = await r.json() as { zodError: unknown };
+            setOptimisticData(undefined);
+            dispatch({ type: "invalid", zodError: body["zodError"] });
+            return;
+          }
+
+          if (!r.ok) throw new Error(`[alabjs] mutation failed: ${r.status} ${r.statusText}`);
+
+          const data = await r.json() as Output;
+          setOptimisticData(undefined);
+          dispatch({ type: "success", data });
+          options?.onSuccess?.(data);
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          setOptimisticData(undefined);
+          dispatch({ type: "error", error });
+          options?.onError?.(error, rollback);
+        }
+      })();
+    });
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [fnName, rollback]);
+
+  const reset = useCallback(() => {
+    setOptimisticData(undefined);
+    dispatch({ type: "reset" });
+  }, []);
+
+  return {
+    mutate,
+    data: state.data as Output | undefined,
+    /** Present when `optimistic` option is set and the request is in flight. */
+    optimisticData,
+    isPending: isPending || state.status === "pending",
+    error: state.error as Error | undefined,
+    /** Zod validation errors returned by `defineServerFn` schema checks (HTTP 422). */
+    zodError: state.zodError,
+    isSuccess: state.status === "success",
+    isError: state.status === "error",
+    isInvalid: state.status === "invalid",
+    reset,
+  };
+}
+
+// ─── useSSE ───────────────────────────────────────────────────────────────────
+
+/** Possible connection states matching the browser EventSource readyState values. */
+export type SSEReadyState = "connecting" | "open" | "closed";
+
+export interface UseSSEOptions {
+  /** Named event to subscribe to. Defaults to `"message"`. */
+  event?: string;
+  /** Whether to connect immediately. Set `false` to defer. @default true */
+  enabled?: boolean;
+  /** Called once when the EventSource opens. */
+  onOpen?: () => void;
+  /** Called when the EventSource closes or errors. */
+  onError?: (err: Event) => void;
+}
+
+export interface UseSSEResult<T> {
+  /** Most recently received event data (parsed JSON). `undefined` until first event. */
+  data: T | undefined;
+  /** The `lastEventId` string from the most recent event. */
+  lastEventId: string;
+  readyState: SSEReadyState;
+  /** Close the EventSource and stop listening. */
+  close: () => void;
+}
+
+/**
+ * Subscribe to a server-sent event stream from a `defineSSEHandler` route.
+ *
+ * The EventSource is created when the component mounts and closed on unmount.
+ * Data is parsed as JSON automatically.
+ *
+ * @example
+ * ```tsx
+ * import { useSSE } from "alabjs/client";
+ *
+ * export default function PricesPage() {
+ *   const { data, readyState } = useSSE<{ ticker: string; price: number }>(
+ *     "/api/prices?ticker=BTC",
+ *     { event: "price" },
+ *   );
+ *
+ *   return <div>{readyState === "open" ? data?.price ?? "—" : "connecting…"}</div>;
+ * }
+ * ```
+ */
+export function useSSE<T = unknown>(
+  url: string,
+  options: UseSSEOptions = {},
+): UseSSEResult<T> {
+  const { event = "message", enabled = true, onOpen, onError } = options;
+
+  const [data, setData] = useState<T | undefined>(undefined);
+  const [lastEventId, setLastEventId] = useState("");
+  const [readyState, setReadyState] = useState<SSEReadyState>("connecting");
+
+  // Keep callbacks stable across renders without re-subscribing
+  const onOpenRef = useRef(onOpen);
+  const onErrorRef = useRef(onError);
+  onOpenRef.current = onOpen;
+  onErrorRef.current = onError;
+
+  const esRef = useRef<EventSource | null>(null);
+
+  const close = useCallback(() => {
+    esRef.current?.close();
+    esRef.current = null;
+    setReadyState("closed");
+  }, []);
+
+  useEffect(() => {
+    if (!enabled || typeof EventSource === "undefined") return;
+
+    const es = new EventSource(url);
+    esRef.current = es;
+    setReadyState("connecting");
+
+    es.addEventListener("open", () => {
+      setReadyState("open");
+      onOpenRef.current?.();
+    });
+
+    es.addEventListener(event, (e: MessageEvent) => {
+      setLastEventId(e.lastEventId ?? "");
+      try {
+        setData(e.data ? (JSON.parse(e.data) as T) : undefined);
+      } catch {
+        // Server sent data that isn't valid JSON — log and discard rather than
+        // silently casting a raw string to T (which would cause runtime type errors).
+        console.warn("[alabjs] useSSE: received non-JSON data on", url, "— discarding:", e.data);
+      }
+    });
+
+    es.addEventListener("error", (e) => {
+      onErrorRef.current?.(e);
+      if (es.readyState === EventSource.CLOSED) {
+        setReadyState("closed");
+      }
+    });
+
+    return () => {
+      es.close();
+      esRef.current = null;
+    };
+  // Re-subscribe if url or event type changes
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [url, event, enabled]);
+
+  return { data, lastEventId, readyState, close };
+}

package/src/client/index.ts

@@ -0,0 +1,5 @@
+export { useServerData, useMutation, useSSE, _clearALabSSRCache } from "./hooks.js";
+export type { UseSSEOptions, UseSSEResult, SSEReadyState } from "./hooks.js";
+export { useOfflineMutations } from "./offline.js";
+export type { UseOfflineMutationsResult, OfflineMutationResult } from "./offline.js";
+export { AlabProvider } from "./provider.js";

package/src/client/offline-sw.ts

@@ -0,0 +1,191 @@
+/**
+ * Alab offline service worker — queue-and-replay for mutations.
+ *
+ * This module is compiled to a separate SW entry point by `alab build`.
+ * It intercepts failed `/_alabjs/fn/*` POST requests when the network is
+ * unavailable, stores them in IndexedDB, and replays them when connectivity
+ * is restored.
+ *
+ * The SW communicates with the page via `postMessage`:
+ *   page  → SW:   { type: "ALAB_REPLAY" }        — manual replay trigger
+ *   SW    → page: { type: "ALAB_QUEUED",   count: number }
+ *   SW    → page: { type: "ALAB_REPLAYED", fn: string, ok: boolean }
+ *   SW    → page: { type: "ALAB_QUEUE_EMPTY" }
+ */
+
+// ─── Types shared with the client hook ───────────────────────────────────────
+
+export interface QueuedMutation {
+  id: string;
+  fn: string;
+  body: string;
+  timestamp: number;
+}
+
+// ─── IndexedDB helpers ────────────────────────────────────────────────────────
+
+const DB_NAME = "alab-offline";
+const STORE = "mutations";
+const DB_VERSION = 1;
+
+function openDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, DB_VERSION);
+    req.onupgradeneeded = () => {
+      req.result.createObjectStore(STORE, { keyPath: "id" });
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+async function enqueue(item: QueuedMutation): Promise<void> {
+  const db = await openDb();
+  await new Promise<void>((resolve, reject) => {
+    const tx = db.transaction(STORE, "readwrite");
+    tx.objectStore(STORE).put(item);
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+
+async function dequeue(id: string): Promise<void> {
+  const db = await openDb();
+  await new Promise<void>((resolve, reject) => {
+    const tx = db.transaction(STORE, "readwrite");
+    tx.objectStore(STORE).delete(id);
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+
+async function getAllQueued(): Promise<QueuedMutation[]> {
+  const db = await openDb();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE, "readonly");
+    const req = tx.objectStore(STORE).getAll();
+    req.onsuccess = () => resolve(req.result as QueuedMutation[]);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+// ─── Minimal SW global types (avoids lib="WebWorker" conflict with DOM) ──────
+
+interface SwClient { postMessage(msg: unknown): void }
+interface SwClients {
+  matchAll(opts?: { includeUncontrolled?: boolean }): Promise<SwClient[]>;
+  claim(): Promise<void>;
+}
+interface SwExtendableEvent extends Event { waitUntil(p: Promise<unknown>): void }
+interface SwFetchEvent extends SwExtendableEvent {
+  request: Request;
+  respondWith(r: Promise<Response>): void;
+}
+interface SwSyncEvent extends SwExtendableEvent { tag: string }
+interface SwMessageEvent extends SwExtendableEvent { data: unknown }
+interface SwGlobalScope {
+  clients: SwClients;
+  skipWaiting(): void;
+  addEventListener(type: "install", cb: () => void): void;
+  addEventListener(type: "activate", cb: (e: SwExtendableEvent) => void): void;
+  addEventListener(type: "fetch",   cb: (e: SwFetchEvent) => void): void;
+  addEventListener(type: "sync",    cb: (e: SwSyncEvent) => void): void;
+  addEventListener(type: "message", cb: (e: SwMessageEvent) => void): void;
+}
+declare const self: SwGlobalScope;
+
+// ─── Broadcast to all controlled pages ───────────────────────────────────────
+
+function broadcast(msg: Record<string, unknown>) {
+  self.clients.matchAll({ includeUncontrolled: true }).then((clients) => {
+    clients.forEach((c) => c.postMessage(msg));
+  });
+}
+
+// ─── Replay queued mutations ──────────────────────────────────────────────────
+
+async function replay() {
+  const queued = await getAllQueued();
+  if (queued.length === 0) {
+    broadcast({ type: "ALAB_QUEUE_EMPTY" });
+    return;
+  }
+  for (const item of queued) {
+    try {
+      const res = await fetch(`/_alabjs/fn/${item.fn}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: item.body,
+      });
+      if (res.ok || res.status === 422) {
+        // 422 = Zod error — not a network failure; dequeue and notify
+        await dequeue(item.id);
+        broadcast({ type: "ALAB_REPLAYED", fn: item.fn, ok: res.ok });
+      }
+      // 5xx: leave in queue and try again next time
+    } catch {
+      // Still offline — leave in queue
+    }
+  }
+}
+
+// ─── SW event listeners ───────────────────────────────────────────────────────
+
+self.addEventListener("install", () => {
+  self.skipWaiting();
+});
+
+self.addEventListener("activate", (event) => {
+  event.waitUntil(self.clients.claim());
+});
+
+self.addEventListener("fetch", (event: SwFetchEvent) => {
+  const { request } = event;
+
+  // Only intercept mutation POSTs to /_alabjs/fn/*
+  if (
+    request.method !== "POST" ||
+    !new URL(request.url).pathname.startsWith("/_alabjs/fn/")
+  ) {
+    return;
+  }
+
+  event.respondWith(
+    (async () => {
+      try {
+        return await fetch(request.clone());
+      } catch {
+        // Network failure — queue the mutation
+        const fn = new URL(request.url).pathname.replace("/_alabjs/fn/", "");
+        const body = await request.text();
+        const item: QueuedMutation = {
+          id: `${fn}-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+          fn,
+          body,
+          timestamp: Date.now(),
+        };
+        await enqueue(item);
+        const queued = await getAllQueued();
+        broadcast({ type: "ALAB_QUEUED", count: queued.length });
+
+        // Return a synthetic "queued" response so the caller isn't left hanging
+        return new Response(JSON.stringify({ __queued: true, id: item.id }), {
+          status: 202,
+          headers: { "content-type": "application/json" },
+        });
+      }
+    })(),
+  );
+});
+
+self.addEventListener("sync", (event: SwSyncEvent) => {
+  if (event.tag === "alab-mutation-replay") {
+    event.waitUntil(replay());
+  }
+});
+
+self.addEventListener("message", (event: ExtendableMessageEvent) => {
+  if ((event.data as Record<string, unknown>)?.["type"] === "ALAB_REPLAY") {
+    event.waitUntil(replay());
+  }
+});

package/src/client/offline.ts

@@ -0,0 +1,114 @@
+/**
+ * Alab offline support — client-side registration + queue observation.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { useOfflineMutations } from "alabjs/client";
+ *
+ * export default function RootLayout({ children }) {
+ *   const { isOffline, queuedCount, replay } = useOfflineMutations();
+ *
+ *   return (
+ *     <>
+ *       {isOffline && (
+ *         <div className="offline-banner">
+ *           You're offline — {queuedCount} mutation(s) will sync when reconnected.
+ *           <button onClick={replay}>Retry now</button>
+ *         </div>
+ *       )}
+ *       {children}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+
+import { useState, useEffect, useCallback } from "react";
+
+export interface OfflineMutationResult {
+  replayed: { fn: string; ok: boolean }[];
+}
+
+export interface UseOfflineMutationsResult {
+  /** True when `navigator.onLine` is false. */
+  isOffline: boolean;
+  /** Number of mutations currently held in the offline queue. */
+  queuedCount: number;
+  /** Manually trigger a replay of the offline queue. */
+  replay: () => void;
+  /** History of replayed mutations since mount (cleared on replay start). */
+  replayed: OfflineMutationResult["replayed"];
+}
+
+const SW_PATH = "/_alabjs/offline-sw.js";
+
+/**
+ * Register the Alab offline service worker and observe queue state.
+ *
+ * On mount this registers `/_alabjs/offline-sw.js` (emitted by `alab build`).
+ * The hook listens for SW messages and browser online/offline events to keep
+ * state in sync.
+ *
+ * Safe to call in SSR — all browser APIs are guarded behind `typeof window`.
+ */
+export function useOfflineMutations(): UseOfflineMutationsResult {
+  const [isOffline, setIsOffline] = useState(
+    typeof navigator !== "undefined" ? !navigator.onLine : false,
+  );
+  const [queuedCount, setQueuedCount] = useState(0);
+  const [replayed, setReplayed] = useState<OfflineMutationResult["replayed"]>([]);
+
+  // Stable SW controller ref
+  const [swReg, setSwReg] = useState<ServiceWorkerRegistration | null>(null);
+
+  useEffect(() => {
+    if (typeof window === "undefined" || !("serviceWorker" in navigator)) return;
+
+    // Register SW
+    navigator.serviceWorker.register(SW_PATH, { scope: "/" }).then((reg) => {
+      setSwReg(reg);
+    }).catch(() => { /* SW blocked (non-HTTPS, private browsing, etc.) */ });
+
+    // Online / offline events
+    const handleOnline = () => setIsOffline(false);
+    const handleOffline = () => setIsOffline(true);
+    window.addEventListener("online", handleOnline);
+    window.addEventListener("offline", handleOffline);
+
+    // Messages from the SW
+    const handleMessage = (event: MessageEvent) => {
+      const msg = event.data as Record<string, unknown>;
+      if (!msg) return;
+      switch (msg["type"]) {
+        case "ALAB_QUEUED":
+          setQueuedCount(msg["count"] as number);
+          break;
+        case "ALAB_REPLAYED":
+          setReplayed((prev) => [...prev, { fn: msg["fn"] as string, ok: msg["ok"] as boolean }]);
+          break;
+        case "ALAB_QUEUE_EMPTY":
+          setQueuedCount(0);
+          break;
+      }
+    };
+    navigator.serviceWorker.addEventListener("message", handleMessage);
+
+    return () => {
+      window.removeEventListener("online", handleOnline);
+      window.removeEventListener("offline", handleOffline);
+      navigator.serviceWorker.removeEventListener("message", handleMessage);
+    };
+  }, []);
+
+  const replay = useCallback(() => {
+    setReplayed([]);
+    if (swReg?.active) {
+      swReg.active.postMessage({ type: "ALAB_REPLAY" });
+    } else {
+      navigator.serviceWorker.controller?.postMessage({ type: "ALAB_REPLAY" });
+    }
+  }, [swReg]);
+
+  return { isOffline, queuedCount, replay, replayed };
+}

package/src/client/provider.tsx

@@ -0,0 +1,14 @@
+import { Suspense, type ReactNode } from "react";
+
+interface AlabProviderProps {
+  children: ReactNode;
+  fallback?: ReactNode;
+}
+
+/**
+ * Root provider for Alab apps.
+ * Wraps the app in a Suspense boundary for `useServerData` hooks.
+ */
+export function AlabProvider({ children, fallback = null }: AlabProviderProps) {
+  return <Suspense fallback={fallback}>{children}</Suspense>;
+}