alabjs 0.1.0

package/src/ssr/router-dev.test.ts

@@ -0,0 +1,230 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  scanDevRoutes,
+  matchDevRoute,
+  findLayoutFiles,
+  findErrorFile,
+  findLoadingFile,
+  scanDevApiRoutes,
+  matchDevApiRoute,
+} from "./router-dev.js";
+
+let appDir: string;
+
+beforeEach(() => {
+  appDir = mkdtempSync(join(tmpdir(), "alab-test-"));
+});
+
+afterEach(() => {
+  rmSync(appDir, { recursive: true, force: true });
+});
+
+function createFile(relPath: string, content = "export default function Page() { return null; }") {
+  const full = join(appDir, relPath);
+  mkdirSync(join(full, ".."), { recursive: true });
+  writeFileSync(full, content, "utf8");
+}
+
+// ─── scanDevRoutes ────────────────────────────────────────────────────────────
+
+describe("scanDevRoutes", () => {
+  it("finds page.tsx at root", () => {
+    createFile("page.tsx");
+    const routes = scanDevRoutes(appDir);
+    expect(routes).toHaveLength(1);
+    expect(routes[0]!.pattern.test("/")).toBe(true);
+  });
+
+  it("finds nested page.tsx", () => {
+    createFile("about/page.tsx");
+    const routes = scanDevRoutes(appDir);
+    expect(routes).toHaveLength(1);
+    expect(routes[0]!.pattern.test("/about")).toBe(true);
+  });
+
+  it("finds dynamic route [id]", () => {
+    createFile("users/[id]/page.tsx");
+    const routes = scanDevRoutes(appDir);
+    expect(routes).toHaveLength(1);
+    expect(routes[0]!.pattern.test("/users/42")).toBe(true);
+    expect(routes[0]!.paramNames).toEqual(["id"]);
+  });
+
+  it("sorts static routes before dynamic ones", () => {
+    createFile("users/new/page.tsx");
+    createFile("users/[id]/page.tsx");
+    const routes = scanDevRoutes(appDir);
+    expect(routes).toHaveLength(2);
+    // Static route (0 params) should come first
+    expect(routes[0]!.paramNames).toHaveLength(0);
+    expect(routes[1]!.paramNames).toHaveLength(1);
+  });
+
+  it("finds page.ts files too", () => {
+    createFile("page.ts");
+    const routes = scanDevRoutes(appDir);
+    expect(routes).toHaveLength(1);
+  });
+
+  it("returns empty for empty directory", () => {
+    const routes = scanDevRoutes(appDir);
+    expect(routes).toHaveLength(0);
+  });
+});
+
+// ─── matchDevRoute ────────────────────────────────────────────────────────────
+
+describe("matchDevRoute", () => {
+  it("matches a static route", () => {
+    createFile("about/page.tsx");
+    const routes = scanDevRoutes(appDir);
+    const match = matchDevRoute(routes, "/about");
+    expect(match).not.toBe(null);
+    expect(match!.params).toEqual({});
+  });
+
+  it("matches root route", () => {
+    createFile("page.tsx");
+    const routes = scanDevRoutes(appDir);
+    const match = matchDevRoute(routes, "/");
+    expect(match).not.toBe(null);
+  });
+
+  it("extracts dynamic params", () => {
+    createFile("users/[id]/page.tsx");
+    const routes = scanDevRoutes(appDir);
+    const match = matchDevRoute(routes, "/users/42");
+    expect(match).not.toBe(null);
+    expect(match!.params).toEqual({ id: "42" });
+  });
+
+  it("returns null for unmatched path", () => {
+    createFile("about/page.tsx");
+    const routes = scanDevRoutes(appDir);
+    const match = matchDevRoute(routes, "/nonexistent");
+    expect(match).toBe(null);
+  });
+
+  it("decodes URI components in params", () => {
+    createFile("posts/[slug]/page.tsx");
+    const routes = scanDevRoutes(appDir);
+    const match = matchDevRoute(routes, "/posts/hello%20world");
+    expect(match).not.toBe(null);
+    expect(match!.params["slug"]).toBe("hello world");
+  });
+
+  it("matches with optional trailing slash", () => {
+    createFile("about/page.tsx");
+    const routes = scanDevRoutes(appDir);
+    const match = matchDevRoute(routes, "/about/");
+    expect(match).not.toBe(null);
+  });
+});
+
+// ─── findLayoutFiles ──────────────────────────────────────────────────────────
+
+describe("findLayoutFiles", () => {
+  it("finds root layout", () => {
+    createFile("layout.tsx");
+    createFile("page.tsx");
+    const layouts = findLayoutFiles(join(appDir, "page.tsx"), appDir);
+    expect(layouts).toHaveLength(1);
+    expect(layouts[0]).toContain("layout.tsx");
+  });
+
+  it("finds nested layouts ordered outermost first", () => {
+    createFile("layout.tsx");
+    createFile("dashboard/layout.tsx");
+    createFile("dashboard/settings/page.tsx");
+    const layouts = findLayoutFiles(join(appDir, "dashboard/settings/page.tsx"), appDir);
+    expect(layouts).toHaveLength(2);
+    // Root layout should come first
+    expect(layouts[0]).toContain(join(appDir, "layout.tsx"));
+    expect(layouts[1]).toContain(join(appDir, "dashboard/layout.tsx"));
+  });
+
+  it("returns empty when no layouts exist", () => {
+    createFile("about/page.tsx");
+    const layouts = findLayoutFiles(join(appDir, "about/page.tsx"), appDir);
+    expect(layouts).toHaveLength(0);
+  });
+});
+
+// ─── findErrorFile ────────────────────────────────────────────────────────────
+
+describe("findErrorFile", () => {
+  it("finds nearest error.tsx", () => {
+    createFile("error.tsx");
+    createFile("dashboard/page.tsx");
+    const errorFile = findErrorFile(join(appDir, "dashboard/page.tsx"), appDir);
+    expect(errorFile).not.toBe(null);
+    expect(errorFile).toContain("error.tsx");
+  });
+
+  it("returns null when no error file exists", () => {
+    createFile("page.tsx");
+    const errorFile = findErrorFile(join(appDir, "page.tsx"), appDir);
+    expect(errorFile).toBe(null);
+  });
+
+  it("prefers the innermost error.tsx", () => {
+    createFile("error.tsx");
+    createFile("dashboard/error.tsx");
+    createFile("dashboard/settings/page.tsx");
+    const errorFile = findErrorFile(join(appDir, "dashboard/settings/page.tsx"), appDir);
+    expect(errorFile).toContain(join("dashboard", "error.tsx"));
+  });
+});
+
+// ─── findLoadingFile ──────────────────────────────────────────────────────────
+
+describe("findLoadingFile", () => {
+  it("finds nearest loading.tsx", () => {
+    createFile("loading.tsx");
+    createFile("page.tsx");
+    const loadingFile = findLoadingFile(join(appDir, "page.tsx"), appDir);
+    expect(loadingFile).not.toBe(null);
+    expect(loadingFile).toContain("loading.tsx");
+  });
+
+  it("returns null when no loading file exists", () => {
+    createFile("page.tsx");
+    const loadingFile = findLoadingFile(join(appDir, "page.tsx"), appDir);
+    expect(loadingFile).toBe(null);
+  });
+});
+
+// ─── API routes ───────────────────────────────────────────────────────────────
+
+describe("scanDevApiRoutes", () => {
+  it("finds route.ts files", () => {
+    createFile("api/health/route.ts");
+    const routes = scanDevApiRoutes(appDir);
+    expect(routes).toHaveLength(1);
+  });
+
+  it("returns empty when no route files", () => {
+    createFile("page.tsx");
+    const routes = scanDevApiRoutes(appDir);
+    expect(routes).toHaveLength(0);
+  });
+});
+
+describe("matchDevApiRoute", () => {
+  it("matches static API route", () => {
+    createFile("api/health/route.ts");
+    const routes = scanDevApiRoutes(appDir);
+    const match = matchDevApiRoute(routes, "/api/health");
+    expect(match).not.toBe(null);
+  });
+
+  it("returns null for unmatched API path", () => {
+    createFile("api/health/route.ts");
+    const routes = scanDevApiRoutes(appDir);
+    const match = matchDevApiRoute(routes, "/api/nonexistent");
+    expect(match).toBe(null);
+  });
+});

package/src/ssr/router-dev.ts

@@ -0,0 +1,229 @@
+import { readdirSync, statSync, existsSync } from "node:fs";
+import { join, relative, sep, dirname } from "node:path";
+
+export interface DevRoute {
+  /** Regex that matches the URL pathname for this route. */
+  pattern: RegExp;
+  /** Ordered list of param names, matching regex capture groups. */
+  paramNames: string[];
+  /** Absolute path to the page module on disk. */
+  file: string;
+  /** Whether SSR is enabled (opt-out via `export const ssr = false`). */
+  ssr: boolean;
+}
+
+/**
+ * Scan `appDir` (the project's `app/` directory) for `page.tsx` / `page.ts`
+ * files and build a list of matchable routes for the dev server middleware.
+ *
+ * Only TypeScript files are considered — Alab is TypeScript-only.
+ */
+export function scanDevRoutes(appDir: string): DevRoute[] {
+  const routes: DevRoute[] = [];
+  collectRoutes(appDir, appDir, routes);
+  // Sort so that static segments beat dynamic ones (/users/new before /users/[id]).
+  routes.sort((a, b) => {
+    const aScore = paramScore(a.paramNames.length);
+    const bScore = paramScore(b.paramNames.length);
+    return aScore - bScore;
+  });
+  return routes;
+}
+
+function collectRoutes(appDir: string, dir: string, out: DevRoute[]): void {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+
+    if (stat.isDirectory()) {
+      collectRoutes(appDir, full, out);
+    } else if (entry === "page.tsx" || entry === "page.ts") {
+      const rel = relative(appDir, full);
+      const urlPath = relFileToUrlPath(rel);
+      const { pattern, paramNames } = urlPathToRegex(urlPath);
+      out.push({ pattern, paramNames, file: full, ssr: false });
+    }
+  }
+}
+
+/**
+ * Convert a relative file path (from appDir) to a URL path pattern.
+ *
+ * Examples:
+ *   page.tsx                  → /
+ *   about/page.tsx            → /about
+ *   users/[id]/page.tsx       → /users/[id]
+ *   users/[id]/posts/page.tsx → /users/[id]/posts
+ */
+function relFileToUrlPath(rel: string): string {
+  // Normalise Windows separators
+  const parts = rel.split(sep).join("/").split("/");
+  // Remove the trailing `page.tsx` / `page.ts`
+  parts.pop();
+  if (parts.length === 0) return "/";
+  return "/" + parts.join("/");
+}
+
+/**
+ * Convert an Alab URL path pattern to a regex and extract param names.
+ *
+ * `[id]` → capture group `([^/]+)`, param name `id`
+ */
+function urlPathToRegex(urlPath: string): { pattern: RegExp; paramNames: string[] } {
+  const paramNames: string[] = [];
+  const regexStr = urlPath
+    .split("/")
+    .map((segment) => {
+      const match = /^\[(.+)\]$/.exec(segment);
+      if (match) {
+        paramNames.push(match[1]!);
+        return "([^/]+)";
+      }
+      return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    })
+    .join("/");
+
+  // Match exact path (ignoring trailing slash for non-root paths)
+  const pattern = urlPath === "/" ? /^\/$/ : new RegExp(`^${regexStr}\\/?$`);
+  return { pattern, paramNames };
+}
+
+/** Lower score = higher priority (static routes beat dynamic ones). */
+function paramScore(paramCount: number): number {
+  return paramCount;
+}
+
+/**
+ * Find all layout.tsx files that apply to a given page file, ordered outermost → innermost.
+ *
+ * Given `app/dashboard/users/page.tsx`, returns:
+ *   [ "app/layout.tsx", "app/dashboard/layout.tsx" ]   (only those that exist)
+ */
+export function findLayoutFiles(pageFile: string, appDir: string): string[] {
+  const layouts: string[] = [];
+  let dir = dirname(pageFile);
+
+  // Collect directories from page dir up to (and including) appDir
+  const dirs: string[] = [];
+  while (dir.length >= appDir.length) {
+    dirs.unshift(dir); // prepend so we get outermost first
+    if (dir === appDir) break;
+    dir = dirname(dir);
+  }
+
+  for (const d of dirs) {
+    const candidate = join(d, "layout.tsx");
+    if (existsSync(candidate)) layouts.push(candidate);
+  }
+  return layouts;
+}
+
+/**
+ * Find the nearest error.tsx file for a given page file, searching innermost → outermost.
+ * Returns absolute path or null if none found.
+ */
+export function findErrorFile(pageFile: string, appDir: string): string | null {
+  let dir = dirname(pageFile);
+  while (dir.length >= appDir.length) {
+    const candidate = join(dir, "error.tsx");
+    if (existsSync(candidate)) return candidate;
+    if (dir === appDir) break;
+    dir = dirname(dir);
+  }
+  return null;
+}
+
+/**
+ * Find the nearest loading.tsx file for a given page file, searching innermost → outermost.
+ * Returns absolute path or null if none found.
+ */
+export function findLoadingFile(pageFile: string, appDir: string): string | null {
+  let dir = dirname(pageFile);
+  while (dir.length >= appDir.length) {
+    const candidate = join(dir, "loading.tsx");
+    if (existsSync(candidate)) return candidate;
+    if (dir === appDir) break;
+    dir = dirname(dir);
+  }
+  return null;
+}
+
+export interface DevApiRoute {
+  pattern: RegExp;
+  paramNames: string[];
+  file: string;
+}
+
+/**
+ * Scan `appDir` for `route.ts` / `route.tsx` files and build a list of API routes.
+ * These handle HTTP method exports: GET, POST, PUT, PATCH, DELETE.
+ */
+export function scanDevApiRoutes(appDir: string): DevApiRoute[] {
+  const routes: DevApiRoute[] = [];
+  collectApiRoutes(appDir, appDir, routes);
+  routes.sort((a, b) => a.paramNames.length - b.paramNames.length);
+  return routes;
+}
+
+function collectApiRoutes(appDir: string, dir: string, out: DevApiRoute[]): void {
+  let entries: string[];
+  try { entries = readdirSync(dir); } catch { return; }
+  for (const entry of entries) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      collectApiRoutes(appDir, full, out);
+    } else if (entry === "route.ts" || entry === "route.tsx") {
+      const rel = relative(appDir, full);
+      const urlPath = relFileToUrlPath(rel.replace(/route\.(tsx?)$/, "page.$1"));
+      const { pattern, paramNames } = urlPathToRegex(urlPath);
+      out.push({ pattern, paramNames, file: full });
+    }
+  }
+}
+
+/**
+ * Match a pathname against the API route list.
+ */
+export function matchDevApiRoute(
+  routes: DevApiRoute[],
+  pathname: string,
+): { route: DevApiRoute; params: Record<string, string> } | null {
+  for (const route of routes) {
+    const m = route.pattern.exec(pathname);
+    if (m) {
+      const params: Record<string, string> = {};
+      route.paramNames.forEach((name, i) => { params[name] = decodeURIComponent(m[i + 1] ?? ""); });
+      return { route, params };
+    }
+  }
+  return null;
+}
+
+/**
+ * Match an incoming URL pathname against the dev route list.
+ * Returns the matched route and extracted params, or `null` if no match.
+ */
+export function matchDevRoute(
+  routes: DevRoute[],
+  pathname: string,
+): { route: DevRoute; params: Record<string, string> } | null {
+  for (const route of routes) {
+    const m = route.pattern.exec(pathname);
+    if (m) {
+      const params: Record<string, string> = {};
+      route.paramNames.forEach((name, i) => {
+        params[name] = decodeURIComponent(m[i + 1] ?? "");
+      });
+      return { route, params };
+    }
+  }
+  return null;
+}

package/src/test/index.ts

@@ -0,0 +1,206 @@
+/**
+ * Alab test utilities — zero setup required.
+ *
+ * @example
+ * ```ts
+ * import { renderPage, mockServerFn } from "alabjs/test";
+ * import { getUser } from "./app/users/[id]/page.server.js";
+ *
+ * mockServerFn(getUser, { id: "1", name: "Alice" });
+ * const { html, status } = await renderPage("/users/1");
+ * expect(html).toContain("Alice");
+ * ```
+ */
+
+import { createElement, type ComponentType } from "react";
+import { renderToString } from "react-dom/server";
+import type { ServerFn } from "../types/index.js";
+
+// ─── mockServerFn ─────────────────────────────────────────────────────────────
+
+/** Registry of mocked server functions — keyed by function name. */
+const _mocks = new Map<string, unknown>();
+
+/**
+ * Mock a `defineServerFn` function for the duration of a test.
+ *
+ * The mock is applied globally for the current test process. Use
+ * `clearMocks()` in `afterEach` if you need isolation between tests,
+ * or rely on Vitest's built-in mock isolation.
+ *
+ * @example
+ * ```ts
+ * import { getUser } from "./page.server.js";
+ * mockServerFn(getUser, { id: "1", name: "Alice", email: "alice@example.com" });
+ * ```
+ */
+export function mockServerFn<T extends ServerFn<any, any, any>>(
+  fn: T,
+  returnValue: T extends ServerFn<any, infer O, any> ? O : never,
+): void {
+  _mocks.set((fn as unknown as { name: string }).name, returnValue);
+}
+
+/**
+ * Mock a server function with a custom handler (for dynamic responses).
+ *
+ * @example
+ * ```ts
+ * mockServerFnWith(getUser, async ({ params }) => {
+ *   if (params.id === "1") return { name: "Alice" };
+ *   throw new Error("Not found");
+ * });
+ * ```
+ */
+export function mockServerFnWith<T extends ServerFn<any, any, any>>(
+  fn: T,
+  handler: T extends ServerFn<infer I, infer O, any>
+    ? (ctx: { params: Record<string, string> }, input: I) => Promise<O>
+    : never,
+): void {
+  _mocks.set((fn as unknown as { name: string }).name, handler);
+}
+
+/** Remove all server function mocks. Call in `afterEach` for test isolation. */
+export function clearMocks(): void {
+  _mocks.clear();
+}
+
+/** @internal Used by Alab's dev server to resolve mocked functions in tests. */
+export function _getMock(fnName: string): unknown | undefined {
+  return _mocks.get(fnName);
+}
+
+// ─── renderPage ───────────────────────────────────────────────────────────────
+
+export interface RenderPageResult {
+  /** Full HTML string including the Alab shell. */
+  html: string;
+  /** HTTP status code (200, 404, 500, etc.). */
+  status: number;
+  /** Whether the render threw an error. */
+  error: Error | null;
+}
+
+export interface RenderPageOptions {
+  /**
+   * Params to inject — useful when the route path has dynamic segments.
+   * @example `{ id: "42" }` for `/users/[id]`
+   */
+  params?: Record<string, string>;
+  /** Search params to inject. */
+  searchParams?: Record<string, string>;
+  /**
+   * Request headers forwarded to middleware and server functions.
+   */
+  headers?: Record<string, string>;
+}
+
+/**
+ * Render a page component to an HTML string for integration testing.
+ *
+ * Automatically applies any `mockServerFn` mocks registered before this call.
+ * Does not start an HTTP server — renders entirely in-process.
+ *
+ * @example
+ * ```ts
+ * const { html, status } = await renderPage("/users/1", { params: { id: "1" } });
+ * expect(status).toBe(200);
+ * expect(html).toContain('<h1>Alice</h1>');
+ * ```
+ */
+export async function renderPage(
+  path: string,
+  options: RenderPageOptions = {},
+): Promise<RenderPageResult> {
+  const { params = {}, searchParams = {} } = options;
+
+  // Dynamically resolve the page module from the file-system.
+  // In test environments, Vitest handles module resolution via the Vite plugin.
+  const appDir = new URL("../../app", import.meta.url).pathname;
+
+  // Convert URL path to a candidate file path.
+  // e.g. "/users/1" → try "app/users/[id]/page.tsx" based on path segments.
+  const segments = path.split("/").filter(Boolean);
+  const candidates = buildCandidatePaths(appDir, segments, params);
+
+  let PageComponent: ComponentType<{ params: Record<string, string>; searchParams: Record<string, string> }> | null = null;
+
+  for (const candidate of candidates) {
+    try {
+      const mod = await import(candidate) as { default?: unknown };
+      if (typeof mod.default === "function") {
+        PageComponent = mod.default as unknown as typeof PageComponent;
+        break;
+      }
+    } catch {
+      // Try next candidate.
+    }
+  }
+
+  if (!PageComponent) {
+    return { html: "", status: 404, error: new Error(`[alabjs/test] No page found for path: ${path}`) };
+  }
+
+  try {
+    const html = renderToString(createElement(PageComponent, { params, searchParams }));
+    return { html, status: 200, error: null };
+  } catch (err) {
+    return {
+      html: "",
+      status: 500,
+      error: err instanceof Error ? err : new Error(String(err)),
+    };
+  }
+}
+
+/**
+ * Render a specific component to HTML (lower-level than `renderPage`).
+ *
+ * @example
+ * ```ts
+ * import UserPage from "./app/users/[id]/page.js";
+ * const { html } = await renderComponent(UserPage, { params: { id: "1" }, searchParams: {} });
+ * ```
+ */
+export async function renderComponent<P extends Record<string, unknown>>(
+  Component: ComponentType<P>,
+  props: P,
+): Promise<RenderPageResult> {
+  try {
+    const html = renderToString(createElement(Component, props));
+    return { html, status: 200, error: null };
+  } catch (err) {
+    return {
+      html: "",
+      status: 500,
+      error: err instanceof Error ? err : new Error(String(err)),
+    };
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function buildCandidatePaths(
+  appDir: string,
+  segments: string[],
+  params: Record<string, string>,
+): string[] {
+  const paramValues = Object.values(params);
+  const candidates: string[] = [];
+
+  // Try resolving dynamic segments in reverse (known params replace segments).
+  const resolvedSegments = segments.map((seg) => {
+    // If this segment matches a known param value, try both [param] and the value.
+    const matchingParam = paramValues.find((v) => v === seg);
+    return matchingParam ? `[${Object.keys(params).find((k) => params[k] === matchingParam) ?? seg}]` : seg;
+  });
+
+  const extensions = [".tsx", ".ts", ".jsx", ".js"];
+  for (const ext of extensions) {
+    candidates.push(`${appDir}/${resolvedSegments.join("/")}/page${ext}`);
+    candidates.push(`${appDir}/${segments.join("/")}/page${ext}`);
+  }
+
+  return candidates;
+}

package/src/types/compiler.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Type declaration for the @alabjs/compiler native binding.
+ * The actual module is a napi-rs .node binary loaded at runtime.
+ * It is an optional dependency — the framework falls back to esbuild if absent.
+ */
+declare module "@alabjs/compiler" {
+  /** Compile a TypeScript/TSX source string to JavaScript. Returns JSON `{ code, map }`. */
+  export function compileSource(source: string, filename: string, minify: boolean): string;
+  /** Check a source file for server-boundary violations. Returns JSON array. */
+  export function checkBoundary(source: string, filename: string): string;
+  /** Scan an app/ directory and build the route manifest. Returns JSON `{ routes }`. */
+  export function buildRoutes(appDir: string): string;
+  /** Optimise an image buffer — decode, resize, and encode to WebP/JPEG/PNG. */
+  export function optimizeImage(
+    input: Buffer,
+    quality?: number | null,
+    width?: number | null,
+    height?: number | null,
+    format?: string | null,
+  ): Promise<Buffer>;
+  /** Scan a `.server.ts` source for `defineServerFn` exports. Returns JSON `Array<{ name, endpoint }>`. */
+  export function extractServerFns(source: string, filename: string): string;
+  /** Return an ES module fetch-stub for a server function (used in client bundles). */
+  export function serverFnStub(name: string, endpoint: string): string;
+}