alabjs 0.1.0

package/src/signals/signals.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect } from "vitest";
+import { signal, computed } from "./index.js";
+
+// Note: useSignal, useSignalValue, useSignalSetter are React hooks that require
+// a React component context. We test the non-hook primitives here (signal, computed)
+// which contain the core reactivity logic (~70% of the module's surface area).
+
+describe("signal", () => {
+  it("initialises with the given value", () => {
+    const s = signal(42);
+    expect(s.get()).toBe(42);
+  });
+
+  it("updates value via set()", () => {
+    const s = signal(0);
+    s.set(10);
+    expect(s.get()).toBe(10);
+  });
+
+  it("supports functional updates", () => {
+    const s = signal(5);
+    s.set((prev) => prev + 3);
+    expect(s.get()).toBe(8);
+  });
+
+  it("getSnapshot returns the current value", () => {
+    const s = signal("hello");
+    expect(s.getSnapshot()).toBe("hello");
+    s.set("world");
+    expect(s.getSnapshot()).toBe("world");
+  });
+
+  it("notifies subscribers on change", () => {
+    const s = signal(0);
+    let notified = false;
+    s.subscribe(() => {
+      notified = true;
+    });
+    s.set(1);
+    expect(notified).toBe(true);
+  });
+
+  it("does NOT notify when value is unchanged (Object.is)", () => {
+    const s = signal(42);
+    let callCount = 0;
+    s.subscribe(() => {
+      callCount++;
+    });
+    s.set(42); // same value
+    expect(callCount).toBe(0);
+  });
+
+  it("does NOT notify when functional update returns same value", () => {
+    const s = signal(42);
+    let callCount = 0;
+    s.subscribe(() => {
+      callCount++;
+    });
+    s.set((v) => v); // identity — same value
+    expect(callCount).toBe(0);
+  });
+
+  it("unsubscribe stops notifications", () => {
+    const s = signal(0);
+    let callCount = 0;
+    const unsub = s.subscribe(() => {
+      callCount++;
+    });
+    s.set(1);
+    expect(callCount).toBe(1);
+    unsub();
+    s.set(2);
+    expect(callCount).toBe(1); // still 1, not notified
+  });
+
+  it("supports multiple subscribers", () => {
+    const s = signal(0);
+    let a = 0;
+    let b = 0;
+    s.subscribe(() => { a++; });
+    s.subscribe(() => { b++; });
+    s.set(1);
+    expect(a).toBe(1);
+    expect(b).toBe(1);
+  });
+
+  it("handles null and undefined values", () => {
+    const s = signal<string | null>(null);
+    expect(s.get()).toBe(null);
+    s.set("hello");
+    expect(s.get()).toBe("hello");
+    s.set(null);
+    expect(s.get()).toBe(null);
+  });
+
+  it("handles object values", () => {
+    const s = signal({ name: "Ada" });
+    expect(s.get()).toEqual({ name: "Ada" });
+    const newObj = { name: "Bob" };
+    s.set(newObj);
+    expect(s.get()).toBe(newObj);
+  });
+});
+
+describe("computed", () => {
+  it("derives value from source signals", () => {
+    const a = signal(2);
+    const b = signal(3);
+    const sum = computed([a, b], ([x, y]) => (x as number) + (y as number));
+    expect(sum.get()).toBe(5);
+  });
+
+  it("recomputes when a source changes", () => {
+    const a = signal(2);
+    const b = signal(3);
+    const sum = computed([a, b], ([x, y]) => (x as number) + (y as number));
+    a.set(10);
+    expect(sum.get()).toBe(13);
+  });
+
+  it("notifies subscribers when derived value changes", () => {
+    const count = signal(0);
+    const doubled = computed([count], ([c]) => (c as number) * 2);
+    let notified = false;
+    doubled.subscribe(() => {
+      notified = true;
+    });
+    count.set(5);
+    expect(notified).toBe(true);
+    expect(doubled.get()).toBe(10);
+  });
+
+  it("does NOT notify when derived value is unchanged", () => {
+    const a = signal(3);
+    const isPositive = computed([a], ([v]) => (v as number) > 0);
+    expect(isPositive.get()).toBe(true);
+    let callCount = 0;
+    isPositive.subscribe(() => {
+      callCount++;
+    });
+    a.set(5); // still positive → derived value stays `true`
+    expect(callCount).toBe(0);
+  });
+
+  it("getSnapshot returns current derived value", () => {
+    const s = signal("hello");
+    const upper = computed([s], ([v]) => (v as string).toUpperCase());
+    expect(upper.getSnapshot()).toBe("HELLO");
+  });
+
+  it("supports single source signal", () => {
+    const name = signal("Ada");
+    const greeting = computed([name], ([n]) => `Hello, ${n as string}!`);
+    expect(greeting.get()).toBe("Hello, Ada!");
+    name.set("Bob");
+    expect(greeting.get()).toBe("Hello, Bob!");
+  });
+
+  it("does not expose set method", () => {
+    const s = signal(1);
+    const c = computed([s], ([v]) => v);
+    expect("set" in c).toBe(false);
+  });
+});

package/src/ssr/html.test.ts

@@ -0,0 +1,200 @@
+import { describe, it, expect } from "vitest";
+import { htmlShellBefore, htmlShellAfter } from "./html.js";
+
+describe("htmlShellBefore", () => {
+  const baseOpts = {
+    metadata: {},
+    paramsJson: "{}",
+    searchParamsJson: "{}",
+    routeFile: "app/page.tsx",
+    ssr: false,
+  };
+
+  it("produces valid HTML doctype and structure", () => {
+    const html = htmlShellBefore(baseOpts);
+    expect(html).toContain("<!doctype html>");
+    expect(html).toContain('<html lang="en">');
+    expect(html).toContain('<meta charset="UTF-8" />');
+    expect(html).toContain('<div id="alabjs-root">');
+  });
+
+  it("includes alabjs-route meta tag", () => {
+    const html = htmlShellBefore(baseOpts);
+    expect(html).toContain('<meta name="alabjs-route" content="app/page.tsx" />');
+  });
+
+  it("includes alabjs-ssr meta tag set to false", () => {
+    const html = htmlShellBefore(baseOpts);
+    expect(html).toContain('<meta name="alabjs-ssr" content="false" />');
+  });
+
+  it("includes alabjs-ssr meta tag set to true", () => {
+    const html = htmlShellBefore({ ...baseOpts, ssr: true });
+    expect(html).toContain('<meta name="alabjs-ssr" content="true" />');
+  });
+
+  it("embeds params JSON", () => {
+    const html = htmlShellBefore({
+      ...baseOpts,
+      paramsJson: '{"id":"42"}',
+    });
+    expect(html).toContain('<meta name="alabjs-params" content="{&quot;id&quot;:&quot;42&quot;}" />');
+  });
+
+  it("includes title tag when metadata has title", () => {
+    const html = htmlShellBefore({
+      ...baseOpts,
+      metadata: { title: "My Page" },
+    });
+    expect(html).toContain("<title>My Page</title>");
+  });
+
+  it("escapes HTML in title", () => {
+    const html = htmlShellBefore({
+      ...baseOpts,
+      metadata: { title: "<script>alert(1)</script>" },
+    });
+    expect(html).not.toContain("<script>alert(1)</script>");
+    expect(html).toContain("&lt;script&gt;");
+  });
+
+  it("includes description meta tag", () => {
+    const html = htmlShellBefore({
+      ...baseOpts,
+      metadata: { description: "A test page" },
+    });
+    expect(html).toContain('<meta name="description" content="A test page" />');
+  });
+
+  it("includes canonical link", () => {
+    const html = htmlShellBefore({
+      ...baseOpts,
+      metadata: { canonical: "https://example.com/page" },
+    });
+    expect(html).toContain('<link rel="canonical" href="https://example.com/page" />');
+  });
+
+  it("includes robots meta tag", () => {
+    const html = htmlShellBefore({
+      ...baseOpts,
+      metadata: { robots: "noindex, nofollow" },
+    });
+    expect(html).toContain('<meta name="robots" content="noindex, nofollow" />');
+  });
+
+  it("includes theme-color meta tag", () => {
+    const html = htmlShellBefore({
+      ...baseOpts,
+      metadata: { themeColor: "#ff6600" },
+    });
+    expect(html).toContain('<meta name="theme-color" content="#ff6600" />');
+  });
+
+  it("includes Open Graph tags", () => {
+    const html = htmlShellBefore({
+      ...baseOpts,
+      metadata: {
+        og: {
+          title: "OG Title",
+          description: "OG Desc",
+          image: "https://example.com/og.png",
+          url: "https://example.com",
+          type: "website",
+          siteName: "Example",
+        },
+      },
+    });
+    expect(html).toContain('<meta property="og:title" content="OG Title" />');
+    expect(html).toContain('<meta property="og:description" content="OG Desc" />');
+    expect(html).toContain('<meta property="og:image" content="https://example.com/og.png" />');
+    expect(html).toContain('<meta property="og:url" content="https://example.com" />');
+    expect(html).toContain('<meta property="og:type" content="website" />');
+    expect(html).toContain('<meta property="og:site_name" content="Example" />');
+  });
+
+  it("includes Twitter Card tags", () => {
+    const html = htmlShellBefore({
+      ...baseOpts,
+      metadata: {
+        twitter: {
+          card: "summary_large_image",
+          title: "TW Title",
+          description: "TW Desc",
+          image: "https://example.com/tw.png",
+          creator: "@alabjs",
+        },
+      },
+    });
+    expect(html).toContain('<meta name="twitter:card" content="summary_large_image" />');
+    expect(html).toContain('<meta name="twitter:title" content="TW Title" />');
+    expect(html).toContain('<meta name="twitter:creator" content="@alabjs" />');
+  });
+
+  it("includes extra meta tags", () => {
+    const html = htmlShellBefore({
+      ...baseOpts,
+      metadata: {
+        extra: [
+          { name: "author", content: "AlabJS Team" },
+          { property: "article:author", content: "https://example.com" },
+        ],
+      },
+    });
+    expect(html).toContain('name="author"');
+    expect(html).toContain('content="AlabJS Team"');
+    expect(html).toContain('property="article:author"');
+  });
+
+  it("includes layouts meta tag when provided", () => {
+    const html = htmlShellBefore({
+      ...baseOpts,
+      layoutsJson: '["app/layout.tsx"]',
+    });
+    expect(html).toContain('name="alabjs-layouts"');
+  });
+
+  it("includes loading meta tag when provided", () => {
+    const html = htmlShellBefore({
+      ...baseOpts,
+      loadingFile: "app/loading.tsx",
+    });
+    expect(html).toContain('<meta name="alabjs-loading" content="app/loading.tsx" />');
+  });
+
+  it("includes headExtra content", () => {
+    const html = htmlShellBefore({
+      ...baseOpts,
+      headExtra: '<meta name="csrf-token" content="abc123" />',
+    });
+    expect(html).toContain('<meta name="csrf-token" content="abc123" />');
+  });
+
+  it("includes globals.css link", () => {
+    const html = htmlShellBefore(baseOpts);
+    expect(html).toContain('<link rel="stylesheet" href="/app/globals.css" />');
+  });
+});
+
+describe("htmlShellAfter", () => {
+  it("closes the alabjs-root div and body/html", () => {
+    const html = htmlShellAfter({});
+    expect(html).toContain("</div>");
+    expect(html).toContain("</body>");
+    expect(html).toContain("</html>");
+  });
+
+  it("includes the client script tag", () => {
+    const html = htmlShellAfter({});
+    expect(html).toContain('<script type="module" src="/@alabjs/client">');
+  });
+
+  it("includes nonce when provided", () => {
+    const html = htmlShellAfter({ nonce: "abc123" });
+    expect(html).toContain('nonce="abc123"');
+  });
+
+  it("escapes quotes in nonce", () => {
+    const html = htmlShellAfter({ nonce: 'test"nonce' });
+    expect(html).toContain("&quot;");
+  });
+});

package/src/ssr/html.ts

@@ -0,0 +1,140 @@
+import type { PageMetadata } from "../types/index.js";
+
+export interface HtmlShellOptions {
+  metadata: PageMetadata;
+  /** Serialised params JSON string to embed in the page for client hydration. */
+  paramsJson: string;
+  /** Serialised search-params JSON string. */
+  searchParamsJson: string;
+  /** Relative path to the page module (e.g. `app/users/[id]/page.tsx`). */
+  routeFile: string;
+  /** Whether SSR is enabled for this route. */
+  ssr: boolean;
+  /** JSON array of layout file paths (relative to cwd), outermost first. */
+  layoutsJson?: string | undefined;
+  /** Relative path to the nearest loading.tsx (for client-side Suspense fallback). */
+  loadingFile?: string | undefined;
+  /** Extra content injected into <head> (used by Vite to insert HMR scripts). */
+  headExtra?: string | undefined;
+  /** Nonce for CSP inline scripts (optional). */
+  nonce?: string | undefined;
+}
+
+/** Build the opening HTML fragment — everything up to and including `<div id="alabjs-root">`. */
+export function htmlShellBefore(opts: HtmlShellOptions): string {
+  const {
+    metadata,
+    paramsJson,
+    searchParamsJson,
+    routeFile,
+    ssr,
+    layoutsJson,
+    loadingFile,
+    headExtra = "",
+  } = opts;
+
+  const titleTag = metadata.title
+    ? `<title>${escHtml(metadata.title)}</title>`
+    : "";
+
+  const descTag = metadata.description
+    ? `<meta name="description" content="${escAttr(metadata.description)}" />`
+    : "";
+
+  const canonicalTag = metadata.canonical
+    ? `<link rel="canonical" href="${escAttr(metadata.canonical)}" />`
+    : "";
+
+  const robotsTag = metadata.robots
+    ? `<meta name="robots" content="${escAttr(metadata.robots)}" />`
+    : "";
+
+  const themeColorTag = metadata.themeColor
+    ? `<meta name="theme-color" content="${escAttr(metadata.themeColor)}" />`
+    : "";
+
+  const ogTags = metadata.og ? buildOgTags(metadata.og) : "";
+  const twitterTags = metadata.twitter ? buildTwitterTags(metadata.twitter) : "";
+  const extraTags = metadata.extra ? buildExtraTags(metadata.extra) : "";
+
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    ${titleTag}
+    ${descTag}
+    ${canonicalTag}
+    ${robotsTag}
+    ${themeColorTag}
+    ${ogTags}
+    ${twitterTags}
+    ${extraTags}
+    <meta name="alabjs-route" content="${escAttr(routeFile)}" />
+    <meta name="alabjs-ssr" content="${ssr ? "true" : "false"}" />
+    <meta name="alabjs-params" content="${escAttr(paramsJson)}" />
+    <meta name="alabjs-search-params" content="${escAttr(searchParamsJson)}" />
+    ${layoutsJson ? `<meta name="alabjs-layouts" content="${escAttr(layoutsJson)}" />` : ""}
+    ${loadingFile ? `<meta name="alabjs-loading" content="${escAttr(loadingFile)}" />` : ""}
+    <link rel="stylesheet" href="/app/globals.css" />
+    ${headExtra}
+  </head>
+  <body>
+    <div id="alabjs-root">`;
+}
+
+/** Build the closing HTML fragment — everything after the SSR content. */
+export function htmlShellAfter(opts: { nonce?: string | undefined }): string {
+  const nonceAttr = opts.nonce ? ` nonce="${escAttr(opts.nonce)}"` : "";
+  return `</div>
+    <script type="module" src="/@alabjs/client"${nonceAttr}></script>
+  </body>
+</html>`;
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function escHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function escAttr(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;");
+}
+
+function buildOgTags(og: NonNullable<PageMetadata["og"]>): string {
+  const tags: string[] = [];
+  if (og.title) tags.push(`<meta property="og:title" content="${escAttr(og.title)}" />`);
+  if (og.description) tags.push(`<meta property="og:description" content="${escAttr(og.description)}" />`);
+  if (og.image) tags.push(`<meta property="og:image" content="${escAttr(og.image)}" />`);
+  if (og.url) tags.push(`<meta property="og:url" content="${escAttr(og.url)}" />`);
+  if (og.type) tags.push(`<meta property="og:type" content="${escAttr(og.type)}" />`);
+  if (og.siteName) tags.push(`<meta property="og:site_name" content="${escAttr(og.siteName)}" />`);
+  return tags.join("\n    ");
+}
+
+function buildTwitterTags(tw: NonNullable<PageMetadata["twitter"]>): string {
+  const tags: string[] = [];
+  if (tw.card) tags.push(`<meta name="twitter:card" content="${escAttr(tw.card)}" />`);
+  if (tw.title) tags.push(`<meta name="twitter:title" content="${escAttr(tw.title)}" />`);
+  if (tw.description) tags.push(`<meta name="twitter:description" content="${escAttr(tw.description)}" />`);
+  if (tw.image) tags.push(`<meta name="twitter:image" content="${escAttr(tw.image)}" />`);
+  if (tw.creator) tags.push(`<meta name="twitter:creator" content="${escAttr(tw.creator)}" />`);
+  return tags.join("\n    ");
+}
+
+function buildExtraTags(extra: NonNullable<PageMetadata["extra"]>): string {
+  return extra
+    .map((attrs) => {
+      const attrStr = Object.entries(attrs)
+        .map(([k, v]) => `${k}="${escAttr(v)}"`)
+        .join(" ");
+      return `<meta ${attrStr} />`;
+    })
+    .join("\n    ");
+}

package/src/ssr/render.ts

@@ -0,0 +1,144 @@
+import { createElement, type ComponentType } from "react";
+import { renderToPipeableStream } from "react-dom/server";
+import { Writable } from "node:stream";
+import type { ServerResponse } from "node:http";
+import { htmlShellBefore, htmlShellAfter, type HtmlShellOptions } from "./html.js";
+import type { PageMetadata } from "../types/index.js";
+
+export interface RenderOptions {
+  /** The React page component. */
+  Page: ComponentType<{ params: Record<string, string>; searchParams: Record<string, string> }>;
+  /** Layout components to wrap the page, ordered outermost → innermost. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  layouts?: ComponentType<any>[];
+  /** Parsed route params (e.g. `{ id: "123" }`). */
+  params: Record<string, string>;
+  /** Parsed query params. */
+  searchParams: Record<string, string>;
+  /** Metadata exported by the page module (`export const metadata = ...`). */
+  metadata?: PageMetadata;
+  /** Relative path to the page module, embedded in the HTML for client hydration. */
+  routeFile: string;
+  /** JSON array of layout file paths for client-side hydration. */
+  layoutsJson?: string;
+  /** Relative path to nearest loading.tsx, for client Suspense fallback. */
+  loadingFile?: string | undefined;
+  /** Whether SSR is enabled for this route. */
+  ssr: boolean;
+  /** Extra HTML to inject into <head> (Vite injects its HMR tags here in dev). */
+  headExtra?: string;
+  /** CSP nonce (optional). */
+  nonce?: string;
+}
+
+/**
+ * Render a page component to a streaming HTTP response using React 19's
+ * `renderToPipeableStream`. The HTML shell is split at the `<div id="alab-root">`
+ * boundary: the opening fragment is flushed before React begins streaming, and
+ * the closing fragment is appended when the stream finishes.
+ */
+export function renderToResponse(res: ServerResponse, opts: RenderOptions): void {
+  const {
+    Page,
+    layouts = [],
+    params,
+    searchParams,
+    metadata = {},
+    routeFile,
+    layoutsJson,
+    loadingFile,
+    ssr,
+    headExtra,
+    nonce,
+  } = opts;
+
+  const shellOpts: HtmlShellOptions = {
+    metadata,
+    paramsJson: JSON.stringify(params),
+    searchParamsJson: JSON.stringify(searchParams),
+    routeFile,
+    layoutsJson,
+    loadingFile,
+    ssr,
+    headExtra,
+    nonce,
+  };
+
+  const before = htmlShellBefore(shellOpts);
+  const after = htmlShellAfter({ nonce });
+
+  // Build element tree: Page wrapped by layouts outermost→innermost
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const pageEl = createElement(Page, { params, searchParams }) as any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const rootEl: any = layouts.length
+    ? layouts.reduceRight((child, Layout) => createElement(Layout, {}, child), pageEl)
+    : pageEl;
+
+  let didError = false;
+  let headersSent = false;
+
+  const { pipe, abort } = renderToPipeableStream(
+    rootEl,
+    {
+      onShellReady() {
+        if (headersSent) return;
+        headersSent = true;
+
+        res.statusCode = didError ? 500 : 200;
+        res.setHeader("content-type", "text/html; charset=utf-8");
+        res.write(before);
+
+        // Wrap the Node.js response in a Writable that appends the closing
+        // shell fragment once React finishes streaming.
+        const writable = new Writable({
+          write(chunk: Buffer, _enc, cb) {
+            res.write(chunk, cb);
+          },
+          final(cb) {
+            res.write(after);
+            res.end();
+            cb();
+          },
+        });
+
+        pipe(writable);
+      },
+
+      onShellError(err) {
+        // React couldn't render even the shell boundary — send a plain error page.
+        if (!headersSent) {
+          headersSent = true;
+          res.statusCode = 500;
+          res.setHeader("content-type", "text/plain; charset=utf-8");
+          const msg = err instanceof Error ? err.message : String(err);
+          res.end(`[alabjs] SSR shell error in ${routeFile}: ${msg}`);
+        }
+        console.error(`[alabjs] SSR shell error in ${routeFile}:`, err);
+      },
+
+      onError(err) {
+        didError = true;
+        console.error(`[alabjs] SSR component error in ${routeFile}:`, err);
+      },
+    },
+  );
+
+  // Abort the stream if the client disconnects early.
+  res.on("close", () => {
+    if (!res.writableEnded) abort();
+  });
+}
+
+/**
+ * Render a page component to a full HTML string.
+ * Used in dev mode when streaming is not needed (faster iteration).
+ */
+export async function renderToString(
+  Page: ComponentType<{ params: Record<string, string>; searchParams: Record<string, string> }>,
+  params: Record<string, string>,
+  searchParams: Record<string, string>,
+): Promise<string> {
+  const { renderToString: reactRenderToString } = await import("react-dom/server");
+  return reactRenderToString(createElement(Page, { params, searchParams }));
+}