alabjs 0.1.0

package/src/server/server-fn.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { defineServerFn } from "./index.js";
+import { invalidateCacheKey, getCached, CACHE_MISS } from "./cache.js";
+
+describe("defineServerFn", () => {
+  // ── Basic invocation ──────────────────────────────────────────────────────
+
+  it("returns a callable function", () => {
+    const fn = defineServerFn(async () => "hello");
+    expect(typeof fn).toBe("function");
+  });
+
+  it("invokes the handler with context and input", async () => {
+    const fn = defineServerFn(async (ctx, input: { name: string }) => {
+      return { greeting: `Hello, ${input.name}` };
+    });
+
+    const ctx = {
+      params: {},
+      query: {},
+      headers: {},
+      method: "POST" as const,
+      url: "/test",
+    };
+
+    const result = await fn(ctx, { name: "Ada" });
+    expect(result).toEqual({ greeting: "Hello, Ada" });
+  });
+
+  // ── Zod validation (duck-typed) ───────────────────────────────────────────
+
+  it("validates input with a Zod-like schema", async () => {
+    const mockSchema = {
+      safeParse(input: unknown) {
+        const obj = input as Record<string, unknown>;
+        if (typeof obj?.["name"] === "string" && (obj["name"] as string).length > 0) {
+          return { success: true as const, data: obj };
+        }
+        return { success: false as const, error: { issues: [{ message: "name required" }] } };
+      },
+    };
+
+    const fn = defineServerFn(mockSchema, async (_ctx, input) => {
+      return { validated: (input as { name: string }).name };
+    });
+
+    const ctx = {
+      params: {},
+      query: {},
+      headers: {},
+      method: "POST" as const,
+      url: "/test",
+    };
+
+    const result = await fn(ctx, { name: "Ada" });
+    expect(result).toEqual({ validated: "Ada" });
+  });
+
+  it("throws zodError on validation failure", async () => {
+    const mockSchema = {
+      safeParse(_input: unknown) {
+        return {
+          success: false as const,
+          error: { issues: [{ message: "name required" }] },
+        };
+      },
+    };
+
+    const fn = defineServerFn(mockSchema, async () => {
+      return { ok: true };
+    });
+
+    const ctx = {
+      params: {},
+      query: {},
+      headers: {},
+      method: "POST" as const,
+      url: "/test",
+    };
+
+    try {
+      await fn(ctx, {});
+      expect.fail("Should have thrown");
+    } catch (err) {
+      expect((err as Error).message).toBe("[alabjs] Validation failed");
+      expect((err as Error & { zodError: unknown }).zodError).toBeDefined();
+    }
+  });
+
+  // ── Caching ──────────────────────────────────────────────────────────────
+
+  describe("with cache option", () => {
+    let callCount: number;
+
+    beforeEach(() => {
+      callCount = 0;
+      // Clear any cache from previous test
+      invalidateCacheKey(":undefined");
+    });
+
+    it("caches the result on first call and returns cached on second", async () => {
+      const fn = defineServerFn(
+        async (_ctx, _input) => {
+          callCount++;
+          return { count: callCount };
+        },
+        { cache: { ttl: 60, tags: ["test"] } },
+      );
+
+      const ctx = {
+        params: {},
+        query: {},
+        headers: {},
+        method: "GET" as const,
+        url: "/test",
+      };
+
+      const first = await fn(ctx, undefined);
+      const second = await fn(ctx, undefined);
+
+      // Both calls should return the same result
+      expect(first).toEqual(second);
+      // Handler should only have been called once (second was cached)
+      expect(callCount).toBe(1);
+    });
+  });
+});

package/src/server/sitemap.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest";
+import { generateSitemap } from "./sitemap.js";
+import type { Route } from "../router/manifest.js";
+
+describe("generateSitemap", () => {
+  it("generates valid XML envelope", () => {
+    const xml = generateSitemap([], "https://example.com");
+    expect(xml).toContain('<?xml version="1.0" encoding="UTF-8"?>');
+    expect(xml).toContain("<urlset");
+    expect(xml).toContain("</urlset>");
+  });
+
+  it("includes static page routes", () => {
+    const routes: Route[] = [
+      { path: "/", file: "app/page.tsx", kind: "page", ssr: false, params: [] },
+      { path: "/about", file: "app/about/page.tsx", kind: "page", ssr: false, params: [] },
+    ];
+    const xml = generateSitemap(routes, "https://example.com");
+    expect(xml).toContain("<loc>https://example.com/</loc>");
+    expect(xml).toContain("<loc>https://example.com/about</loc>");
+  });
+
+  it("excludes dynamic routes with [param]", () => {
+    const routes: Route[] = [
+      { path: "/", file: "app/page.tsx", kind: "page", ssr: false, params: [] },
+      { path: "/users/[id]", file: "app/users/[id]/page.tsx", kind: "page", ssr: false, params: ["id"] },
+    ];
+    const xml = generateSitemap(routes, "https://example.com");
+    expect(xml).toContain("<loc>https://example.com/</loc>");
+    expect(xml).not.toContain("/users/[id]");
+  });
+
+  it("excludes API routes", () => {
+    const routes: Route[] = [
+      { path: "/", file: "app/page.tsx", kind: "page", ssr: false, params: [] },
+      { path: "/api/health", file: "app/api/health/route.ts", kind: "api", ssr: false, params: [] },
+    ];
+    const xml = generateSitemap(routes, "https://example.com");
+    expect(xml).not.toContain("/api/health");
+  });
+
+  it("strips trailing slash from base URL", () => {
+    const routes: Route[] = [
+      { path: "/about", file: "app/about/page.tsx", kind: "page", ssr: false, params: [] },
+    ];
+    const xml = generateSitemap(routes, "https://example.com/");
+    expect(xml).toContain("<loc>https://example.com/about</loc>");
+    // Should NOT have double slash
+    expect(xml).not.toContain("https://example.com//about");
+  });
+
+  it("escapes XML special characters", () => {
+    const routes: Route[] = [
+      { path: "/search&filter", file: "app/search/page.tsx", kind: "page", ssr: false, params: [] },
+    ];
+    const xml = generateSitemap(routes, "https://example.com");
+    expect(xml).toContain("&amp;");
+    expect(xml).not.toContain("&filter");
+  });
+
+  it("includes changefreq for each URL", () => {
+    const routes: Route[] = [
+      { path: "/", file: "app/page.tsx", kind: "page", ssr: false, params: [] },
+    ];
+    const xml = generateSitemap(routes, "https://example.com");
+    expect(xml).toContain("<changefreq>weekly</changefreq>");
+  });
+});

package/src/server/sitemap.ts

@@ -0,0 +1,30 @@
+import type { Route } from "../router/manifest.js";
+
+/**
+ * Generate a `/sitemap.xml` from the route manifest.
+ *
+ * Only static page routes are included — dynamic routes (containing `[param]`)
+ * cannot be enumerated without knowing all possible param values.
+ */
+export function generateSitemap(routes: Route[], baseUrl: string): string {
+  const base = baseUrl.replace(/\/$/, "");
+
+  const urls = routes
+    .filter((r) => r.kind === "page" && !r.path.includes("["))
+    .map((r) => {
+      const loc = r.path === "/" ? base + "/" : base + r.path;
+      return `  <url>\n    <loc>${escXml(loc)}</loc>\n    <changefreq>weekly</changefreq>\n  </url>`;
+    })
+    .join("\n");
+
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>`;
+}
+
+function escXml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}

package/src/server/sse.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from "vitest";
+import { defineSSEHandler, type SSEEvent } from "./sse.js";
+
+describe("defineSSEHandler", () => {
+  it("returns a function", () => {
+    const handler = defineSSEHandler(async function* () {});
+    expect(typeof handler).toBe("function");
+  });
+
+  it("returns a Response with correct SSE headers", () => {
+    const handler = defineSSEHandler(async function* () {});
+    const req = new Request("http://localhost/api/events");
+    const res = handler(req);
+
+    expect(res).toBeInstanceOf(Response);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toBe("text/event-stream; charset=utf-8");
+    expect(res.headers.get("cache-control")).toBe("no-cache, no-transform");
+    expect(res.headers.get("connection")).toBe("keep-alive");
+    expect(res.headers.get("x-accel-buffering")).toBe("no");
+  });
+
+  it("streams SSE events with correct wire format", async () => {
+    const handler = defineSSEHandler(async function* () {
+      yield { event: "price", data: { ticker: "BTC", price: 42000 }, id: "1" } as SSEEvent;
+      yield { data: "plain message" } as SSEEvent;
+    });
+
+    const req = new Request("http://localhost/api/events");
+    const res = handler(req);
+    const text = await res.text();
+
+    // Should start with the connection comment
+    expect(text).toContain(": connected\n\n");
+    // Named event
+    expect(text).toContain("event: price\n");
+    expect(text).toContain("id: 1\n");
+    expect(text).toContain('data: {"ticker":"BTC","price":42000}\n');
+    // Default message event
+    expect(text).toContain('data: "plain message"\n');
+  });
+
+  it("handles events with retry field", async () => {
+    const handler = defineSSEHandler(async function* () {
+      yield { data: "reconnect", retry: 5000 } as SSEEvent;
+    });
+
+    const req = new Request("http://localhost/api/events");
+    const res = handler(req);
+    const text = await res.text();
+
+    expect(text).toContain("retry: 5000\n");
+  });
+
+  it("handles null data (ping frames)", async () => {
+    const handler = defineSSEHandler(async function* () {
+      yield { event: "ping", data: null } as SSEEvent;
+    });
+
+    const req = new Request("http://localhost/api/events");
+    const res = handler(req);
+    const text = await res.text();
+
+    expect(text).toContain("event: ping\n");
+    expect(text).toContain("data: \n");
+  });
+
+  it("closes stream cleanly when generator throws", async () => {
+    const handler = defineSSEHandler(async function* () {
+      yield { data: "before error" } as SSEEvent;
+      throw new Error("stream error");
+    });
+
+    const req = new Request("http://localhost/api/events");
+    const res = handler(req);
+    // Should not throw — error is caught internally
+    const text = await res.text();
+    expect(text).toContain(': connected');
+    expect(text).toContain('data: "before error"');
+  });
+});

package/src/server/sse.ts

@@ -0,0 +1,110 @@
+/**
+ * Alab SSE — Server-Sent Events for API routes.
+ *
+ * `defineSSEHandler` wraps an async generator into a standard `Response` that
+ * streams SSE to the browser. Drop it into any `route.ts` as the `GET` export.
+ *
+ * @example
+ * ```ts
+ * // app/api/prices/route.ts
+ * import { defineSSEHandler } from "alabjs/server";
+ *
+ * export const GET = defineSSEHandler(async function* (req) {
+ *   const url = new URL(req.url);
+ *   const ticker = url.searchParams.get("ticker") ?? "BTC";
+ *
+ *   for (let i = 0; i < 100; i++) {
+ *     yield { event: "price", data: { ticker, price: Math.random() * 1000 }, id: String(i) };
+ *     await new Promise((r) => setTimeout(r, 1000));
+ *   }
+ *
+ *   // Signal the client the stream is done
+ *   yield { event: "done", data: null };
+ * });
+ * ```
+ */
+
+// ─── SSE event shape ──────────────────────────────────────────────────────────
+
+export interface SSEEvent<T = unknown> {
+  /** Named event type. Defaults to `"message"` when omitted. */
+  event?: string;
+  /** Payload — serialised to JSON automatically. Pass `null` for ping frames. */
+  data: T;
+  /** Optional event ID for `lastEventId` reconnect support. */
+  id?: string;
+  /** Retry hint in milliseconds (sent as `retry:` field). */
+  retry?: number;
+}
+
+// ─── Serialise one event to the SSE wire format ───────────────────────────────
+
+function encodeEvent(evt: SSEEvent): string {
+  let frame = "";
+  if (evt.id !== undefined) frame += `id: ${evt.id}\n`;
+  if (evt.event) frame += `event: ${evt.event}\n`;
+  if (evt.retry !== undefined) frame += `retry: ${evt.retry}\n`;
+  frame += `data: ${evt.data === null ? "" : JSON.stringify(evt.data)}\n`;
+  frame += "\n"; // blank line terminates the event
+  return frame;
+}
+
+// ─── defineSSEHandler ─────────────────────────────────────────────────────────
+
+type SSEGenerator<T> = (req: Request) => AsyncGenerator<SSEEvent<T>>;
+
+/**
+ * Wrap an async generator into an SSE-streaming `GET` handler.
+ *
+ * The returned function is a standard `(req: Request) => Response` that is
+ * directly usable as `export const GET` in an `app/.../ route.ts`.
+ *
+ * The generator can `yield` as many events as needed. When it returns (or
+ * throws), the stream is closed. The client can reconnect automatically via
+ * the browser's native `EventSource` retry behaviour.
+ *
+ * @example
+ * ```ts
+ * export const GET = defineSSEHandler(async function* (req) {
+ *   while (true) {
+ *     yield { data: { time: Date.now() } };
+ *     await new Promise((r) => setTimeout(r, 2000));
+ *   }
+ * });
+ * ```
+ */
+export function defineSSEHandler<T = unknown>(
+  generator: SSEGenerator<T>,
+): (req: Request) => Response {
+  return (req: Request): Response => {
+    const encoder = new TextEncoder();
+
+    const body = new ReadableStream({
+      async start(controller) {
+        // Send an initial comment to flush the connection through proxies / nginx
+        controller.enqueue(encoder.encode(": connected\n\n"));
+
+        try {
+          for await (const evt of generator(req)) {
+            controller.enqueue(encoder.encode(encodeEvent(evt as SSEEvent)));
+          }
+        } catch {
+          // Generator threw — close stream cleanly so the client can retry
+        } finally {
+          controller.close();
+        }
+      },
+    });
+
+    return new Response(body, {
+      status: 200,
+      headers: {
+        "content-type": "text/event-stream; charset=utf-8",
+        "cache-control": "no-cache, no-transform",
+        "connection": "keep-alive",
+        // Disable nginx / Cloudflare buffering
+        "x-accel-buffering": "no",
+      },
+    });
+  };
+}

package/src/signals/index.ts

@@ -0,0 +1,177 @@
+/**
+ * Alab Signals — granular reactivity within a React tree.
+ *
+ * Signals are observable values that trigger precise re-renders only in the
+ * components that read them — no context provider needed, no full-tree
+ * reconciliation. Inspired by SolidJS signals, built on React 18's
+ * `useSyncExternalStore` for correctness in concurrent mode.
+ *
+ * @example
+ * ```ts
+ * // signals.ts — define once, use anywhere
+ * import { signal } from "alabjs/signals";
+ *
+ * export const count = signal(0);
+ * export const user = signal<User | null>(null);
+ * ```
+ *
+ * ```tsx
+ * // Counter.tsx — only this component re-renders when count changes
+ * import { useSignal } from "alabjs/signals";
+ * import { count } from "../signals.js";
+ *
+ * export function Counter() {
+ *   const [value, setCount] = useSignal(count);
+ *   return <button onClick={() => setCount(v => v + 1)}>{value}</button>;
+ * }
+ * ```
+ */
+
+import { useSyncExternalStore, useCallback } from "react";
+
+// ─── Signal primitive ─────────────────────────────────────────────────────────
+
+export interface Signal<T> {
+  /** Read the current value (non-reactive — use `useSignalValue` inside components). */
+  get(): T;
+  /** Write a new value and notify all subscribers. */
+  set(value: T | ((prev: T) => T)): void;
+  /** @internal Subscribe to changes — consumed by `useSyncExternalStore`. */
+  subscribe(listener: () => void): () => void;
+  /** @internal Snapshot getter for SSR — returns current value synchronously. */
+  getSnapshot(): T;
+}
+
+/**
+ * Create a new signal with an initial value.
+ *
+ * Signals are plain objects — they don't require a React tree to exist.
+ * Define them at module scope and import them wherever needed.
+ *
+ * @example
+ * ```ts
+ * export const darkMode = signal(false);
+ * export const cart = signal<CartItem[]>([]);
+ * ```
+ */
+export function signal<T>(initial: T): Signal<T> {
+  let _value = initial;
+  const _listeners = new Set<() => void>();
+
+  const notify = () => _listeners.forEach((l) => l());
+
+  return {
+    get() {
+      return _value;
+    },
+    set(next) {
+      const resolved = typeof next === "function"
+        ? (next as (prev: T) => T)(_value)
+        : next;
+      if (Object.is(resolved, _value)) return; // bail if unchanged
+      _value = resolved;
+      notify();
+    },
+    subscribe(listener) {
+      _listeners.add(listener);
+      return () => _listeners.delete(listener);
+    },
+    getSnapshot() {
+      return _value;
+    },
+  };
+}
+
+// ─── React hooks ──────────────────────────────────────────────────────────────
+
+/**
+ * Subscribe to a signal's value — re-renders only when the signal changes.
+ * Returns `[value, setter]`, matching the `useState` API.
+ *
+ * @example
+ * ```tsx
+ * const [isDark, setDark] = useSignal(darkMode);
+ * <button onClick={() => setDark(v => !v)}>{isDark ? "☀️" : "🌙"}</button>
+ * ```
+ */
+export function useSignal<T>(sig: Signal<T>): [T, (value: T | ((prev: T) => T)) => void] {
+  const value = useSyncExternalStore(sig.subscribe, sig.getSnapshot, sig.getSnapshot);
+  // Stable setter — signal.set is already referentially stable
+  const set = useCallback((next: T | ((prev: T) => T)) => sig.set(next), [sig]);
+  return [value, set];
+}
+
+/**
+ * Subscribe to a signal's value (read-only).
+ * Slightly cheaper than `useSignal` when you only need to read.
+ *
+ * @example
+ * ```tsx
+ * const count = useSignalValue(counter);
+ * return <span>{count}</span>;
+ * ```
+ */
+export function useSignalValue<T>(sig: Signal<T>): T {
+  return useSyncExternalStore(sig.subscribe, sig.getSnapshot, sig.getSnapshot);
+}
+
+/**
+ * Returns a stable setter for a signal without subscribing to its value.
+ * Use this in components that only write but never display the signal's value —
+ * they won't re-render when the signal changes.
+ *
+ * @example
+ * ```tsx
+ * const setCount = useSignalSetter(counter);
+ * return <button onClick={() => setCount(v => v + 1)}>Increment</button>;
+ * ```
+ */
+export function useSignalSetter<T>(sig: Signal<T>): (value: T | ((prev: T) => T)) => void {
+  return useCallback((next: T | ((prev: T) => T)) => sig.set(next), [sig]);
+}
+
+/**
+ * Derive a computed value from one or more signals.
+ * The derived signal updates automatically when any source signal changes.
+ *
+ * @example
+ * ```ts
+ * const firstName = signal("Ada");
+ * const lastName = signal("Lovelace");
+ * const fullName = computed([firstName, lastName], ([f, l]) => `${f} ${l}`);
+ * // fullName.get() === "Ada Lovelace"
+ * ```
+ */
+export function computed<Sources extends Signal<any>[], T>(
+  sources: [...Sources],
+  derive: (values: { [K in keyof Sources]: Sources[K] extends Signal<infer V> ? V : never }) => T,
+): Omit<Signal<T>, "set"> {
+  // Read initial value
+  const readValues = () =>
+    sources.map((s) => s.get()) as { [K in keyof Sources]: Sources[K] extends Signal<infer V> ? V : never };
+
+  let _cached = derive(readValues());
+  const _listeners = new Set<() => void>();
+
+  const recompute = () => {
+    const next = derive(readValues());
+    if (!Object.is(next, _cached)) {
+      _cached = next;
+      _listeners.forEach((l) => l());
+    }
+  };
+
+  // Subscribe to all source signals
+  for (const src of sources) {
+    src.subscribe(recompute);
+  }
+
+  return {
+    get() { return _cached; },
+    getSnapshot() { return _cached; },
+    subscribe(listener) {
+      _listeners.add(listener);
+      return () => _listeners.delete(listener);
+    },
+  };
+}