alabjs 0.3.0-alpha.1 → 0.4.0

package/src/commands/dev.ts

@@ -1,6 +1,6 @@
 import { createServer } from "vite";
-import { resolve, join } from "node:path";
-import { readdirSync, existsSync as fsExistsSync, readFileSync as fsReadFileSync } from "node:fs";
+import { resolve, join, relative } from "node:path";
+import { readdirSync, existsSync as fsExistsSync, readFileSync as fsReadFileSync, writeFileSync, mkdirSync, openSync, readSync, closeSync } from "node:fs";
 import { loadUserConfig, buildImportMap } from "../config.js";
 import { Writable } from "node:stream";
 import type { IncomingMessage } from "node:http";
@@ -19,7 +19,129 @@ import {
 } from "../server/cache.js";
 import { checkRevalidateAuth, applyRevalidate } from "../server/revalidate.js";
 import type { PageMetadata } from "../types/index.js";
-import type { Route } from "../router/manifest.js";
+import type { Route, RouteManifest } from "../router/manifest.js";
+import { subscribeToTag } from "../live/broadcaster.js";
+
+// ─── FNV-1a hash (mirrors the Rust napi hashBuildId) ─────────────────────────
+// Must produce the same output as the Vite plugin so `/_alabjs/live/:id`
+// endpoints match the IDs embedded in the client bundle.
+function fnv1aHex(str: string): string {
+  let hash = 0xcbf29ce484222325n;
+  for (const byte of Buffer.from(str, "utf-8")) {
+    hash ^= BigInt(byte);
+    hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+
+// ─── Live component discovery ─────────────────────────────────────────────────
+// Scans app/ for live component files and builds a hash → abs-path map so the
+// dev SSE endpoint can locate components by the ID the client bundle embeds.
+//
+// Detection order (mirrors the Vite plugin transform hook):
+//   1. *.live.tsx / *.live.ts filename convention  — O(1), no file read needed
+//   2. "use live" directive as first statement      — reads first 200 bytes only
+function buildLiveComponentMap(appDir: string): Map<string, string> {
+  const map = new Map<string, string>();
+
+  function hasUseLiveDirective(filePath: string): boolean {
+    try {
+      // Read only the first 200 bytes to avoid loading large files.
+      const fd = openSync(filePath, "r");
+      const buf = Buffer.alloc(200);
+      const bytesRead = readSync(fd, buf, 0, 200, 0);
+      closeSync(fd);
+      return buf.subarray(0, bytesRead).toString("utf-8").includes('"use live"');
+    } catch {
+      return false;
+    }
+  }
+
+  function scan(dir: string) {
+    try {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) { scan(full); continue; }
+        if (!/\.(tsx|ts)$/.test(entry.name)) continue;
+        // Convention-based detection (no file read).
+        if (/\.live\.(tsx|ts)$/.test(entry.name)) {
+          map.set(fnv1aHex(full), full);
+          continue;
+        }
+        // Directive-based detection (cheap partial read).
+        if (hasUseLiveDirective(full)) {
+          map.set(fnv1aHex(full), full);
+        }
+      }
+    } catch { /* ignore ENOENT */ }
+  }
+
+  scan(appDir);
+  return map;
+}
+
+// ─── Dev-time route type generation ──────────────────────────────────────────
+async function emitDevRouteTypes(cwd: string, appDir: string): Promise<void> {
+  try {
+    type NapiRoutes = { buildRoutes(d: string): string; checkRouteRefs(d: string, m: string): string };
+    const mod = await import("@alabjs/compiler") as unknown as { default?: NapiRoutes } & NapiRoutes;
+    const napi = (mod.default ?? mod) as NapiRoutes;
+    if (typeof napi.buildRoutes !== "function") return;
+
+    const json = napi.buildRoutes(appDir);
+    const manifest = JSON.parse(json) as RouteManifest;
+
+    // Normalise absolute paths → cwd-relative
+    for (const r of manifest.routes) {
+      if (r.file.startsWith(cwd)) r.file = relative(cwd, r.file);
+    }
+
+    const pageRoutes = manifest.routes.filter((r) => r.kind === "page");
+    const routeTypes = pageRoutes.map((r) => {
+      const tsPath = r.path.replace(/\[([^\]]+)\]/g, "${string}");
+      return tsPath.includes("${") ? `\`${tsPath}\`` : JSON.stringify(tsPath);
+    });
+    const unionType = routeTypes.length > 0 ? routeTypes.join(" | ") : "string";
+
+    const content = [
+      "// AUTO-GENERATED by `alab dev` — do not edit manually.",
+      `export type AlabRoutes = ${unionType};`,
+      "declare module \"alabjs/router\" {",
+      "  export function navigate(path: AlabRoutes, opts?: { replace?: boolean }): void;",
+      "}",
+      "declare module \"alabjs/components\" {",
+      "  import type { ComponentProps } from \"react\";",
+      "  interface RouteLinkProps extends Omit<ComponentProps<\"a\">, \"href\"> {",
+      "    to: AlabRoutes;",
+      "    replace?: boolean;",
+      "  }",
+      "  export function RouteLink(props: RouteLinkProps): JSX.Element;",
+      "  export function Link(props: RouteLinkProps): JSX.Element;",
+      "}",
+      "",
+    ].join("\n");
+
+    const distDir = resolve(cwd, ".alabjs");
+    mkdirSync(distDir, { recursive: true });
+    writeFileSync(resolve(distDir, "routes.d.ts"), content, "utf8");
+
+    // Warn about route violations (non-fatal in dev)
+    if (typeof napi.checkRouteRefs === "function") {
+      const violations = JSON.parse(napi.checkRouteRefs(appDir, json)) as Array<{
+        file: string; kind: string; path: string; suggestion?: string;
+      }>;
+      if (violations.length > 0) {
+        console.warn(`\n  alab  ⚠  ${violations.length} route violation(s):`);
+        for (const v of violations) {
+          const rel = relative(cwd, v.file);
+          console.warn(`  ✗ ${rel}  "${v.path}"  (${v.kind.replace("_", " ")})`);
+          if (v.suggestion) console.warn(`    → ${v.suggestion}`);
+        }
+        console.warn("");
+      }
+    }
+  } catch { /* napi binary not available — skip silently */ }
+}
 
 interface DevOptions {
   cwd: string;
@@ -112,6 +234,14 @@ export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions)
 
   const appDir = resolve(cwd, "app");
 
+  // Generate .alabjs/routes.d.ts and warn about route violations (non-fatal in dev).
+  void emitDevRouteTypes(cwd, appDir);
+
+  // Build live component map: hash → absolute file path.
+  // Re-built lazily on each request so new *.live.tsx files are picked up
+  // without restarting the dev server.
+  let liveMap = buildLiveComponentMap(appDir);
+
   const vite = await createServer({
     root: cwd,
     appType: "custom",
@@ -383,6 +513,100 @@ export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions)
         return;
       }
 
+      // ── /_alabjs/live/:id — SSE stream for "use live" components ─────────────
+      if (pathname.startsWith("/_alabjs/live/")) {
+        const liveId = pathname.slice("/_alabjs/live/".length).split("?")[0] ?? "";
+
+        // Rebuild map on each request so new *.live.tsx files appear without restart.
+        liveMap = buildLiveComponentMap(appDir);
+        const liveFile = liveMap.get(liveId);
+        if (!liveFile) {
+          res.statusCode = 404;
+          res.setHeader("content-type", "application/json");
+          res.end(JSON.stringify({ error: `[alabjs] live component not found: ${liveId}` }));
+          return;
+        }
+
+        // Decode props from query param: ?props=<base64-json>
+        const url = new URL(rawUrl, `http://${host}:${port}`);
+        let props: Record<string, unknown> = {};
+        try {
+          const propsParam = url.searchParams.get("props");
+          if (propsParam) props = JSON.parse(Buffer.from(decodeURIComponent(propsParam), "base64").toString("utf-8")) as Record<string, unknown>;
+        } catch { /* malformed — use empty props */ }
+
+        res.statusCode = 200;
+        res.setHeader("content-type", "text/event-stream; charset=utf-8");
+        res.setHeader("cache-control", "no-store");
+        res.setHeader("connection", "keep-alive");
+        res.setHeader("x-accel-buffering", "no");
+
+        let dead = false;
+        let lastHash = "";
+
+        const send = async () => {
+          if (dead || res.destroyed) return;
+          try {
+            const mod = await vite.ssrLoadModule(liveFile) as { default?: unknown };
+            const Component = mod.default;
+            if (typeof Component !== "function") return;
+
+            const { renderToStaticMarkup } = await import("react-dom/server") as {
+              renderToStaticMarkup: (el: unknown) => string;
+            };
+            const { createElement } = await import("react") as {
+              createElement: (type: unknown, props: unknown) => unknown;
+            };
+
+            const html = renderToStaticMarkup(createElement(Component, props));
+
+            // FNV-1a no-op suppression: skip push when content unchanged.
+            const hash = fnv1aHex(html);
+            if (hash === lastHash) return;
+            lastHash = hash;
+
+            res.write(`data: ${html}\n\n`);
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            res.write(`event: error\ndata: ${JSON.stringify(msg)}\n\n`);
+          }
+        };
+
+        // Initial render.
+        await send();
+
+        // Interval-based polling (read liveInterval from module).
+        let intervalMs = 5000;
+        try {
+          const mod = await vite.ssrLoadModule(liveFile) as { liveInterval?: unknown };
+          if (typeof mod.liveInterval === "number" && mod.liveInterval > 0) {
+            intervalMs = mod.liveInterval * 1000;
+          }
+        } catch { /* use default */ }
+
+        const timer = setInterval(() => void send(), intervalMs);
+
+        // Tag-based invalidation.
+        let unsubTags: (() => void) | null = null;
+        try {
+          const mod = await vite.ssrLoadModule(liveFile) as { liveTags?: unknown };
+          if (Array.isArray(mod.liveTags) && mod.liveTags.length > 0) {
+            const unsubs = (mod.liveTags as string[]).map((tag) =>
+              subscribeToTag(tag, () => void send()),
+            );
+            unsubTags = () => unsubs.forEach((u) => u());
+          }
+        } catch { /* no tags */ }
+
+        req.on("close", () => {
+          dead = true;
+          clearInterval(timer);
+          unsubTags?.();
+        });
+
+        return;
+      }
+
       // ── API routes (route.ts) ─────────────────────────────────────────────────
       // Browser navigations (Accept: text/html) skip API routing so a path can
       // serve both a React page AND an API endpoint (e.g. /activity as a page
@@ -671,4 +895,23 @@ export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions)
 
   await vite.listen();
   vite.printUrls();
+
+  // ── Watch app/ for route file additions/deletions ──────────────────────────
+  // Re-emit .alabjs/routes.d.ts so TypeScript picks up new routes immediately
+  // without needing a dev server restart. Also rebuilds the live component map.
+  const ROUTE_FILE_RE = /\.(page|server|live|layout)\.(tsx|ts)$|^(page|layout|error|loading|route)\.(tsx|ts)$/;
+
+  vite.watcher.on("add", (filePath) => {
+    if (!filePath.startsWith(appDir)) return;
+    if (!ROUTE_FILE_RE.test(filePath)) return;
+    void emitDevRouteTypes(cwd, appDir);
+    liveMap = buildLiveComponentMap(appDir);
+  });
+
+  vite.watcher.on("unlink", (filePath) => {
+    if (!filePath.startsWith(appDir)) return;
+    if (!ROUTE_FILE_RE.test(filePath)) return;
+    void emitDevRouteTypes(cwd, appDir);
+    liveMap = buildLiveComponentMap(appDir);
+  });
 }

package/src/components/Link.tsx

@@ -6,6 +6,15 @@ export interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
   prefetch?: boolean;
 }
 
+export interface RouteLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+  /** The destination path. Narrows to AlabRoutes when routes.d.ts is included. */
+  to: string;
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean;
+  /** Prefetch the target page on hover (default: true). */
+  prefetch?: boolean;
+}
+
 declare global {
   interface Window {
     __alabjs_navigate?: (href: string) => Promise<void>;
@@ -62,3 +71,14 @@ export function Link({ href, children, prefetch = true, onClick, ...rest }: Link
     </a>
   );
 }
+
+/**
+ * Type-safe navigation link.
+ *
+ * Identical to `<Link>` but uses a `to` prop instead of `href`.
+ * When `.alabjs/routes.d.ts` is included in your tsconfig, the `to` prop
+ * is narrowed to the `AlabRoutes` union so typos become build errors.
+ */
+export function RouteLink({ to, replace: _replace, ...rest }: RouteLinkProps) {
+  return <Link href={to} {...rest} />;
+}

package/src/components/index.ts

@@ -1,7 +1,7 @@
 export { Image } from "./Image.js";
 export type { ImageProps } from "./Image.js";
-export { Link } from "./Link.js";
-export type { LinkProps } from "./Link.js";
+export { Link, RouteLink } from "./Link.js";
+export type { LinkProps, RouteLinkProps } from "./Link.js";
 export { ErrorBoundary } from "./ErrorBoundary.js";
 export { Script } from "./Script.js";
 export type { ScriptProps } from "./Script.js";

package/src/live/broadcaster.ts

@@ -0,0 +1,83 @@
+/**
+ * In-process tag-based pub/sub broadcaster for live components.
+ *
+ * Each SSE connection subscribes to the tags returned by its component's
+ * `liveTags(props)` export. When `invalidateLive({ tags })` is called from
+ * anywhere on the server (route handler, webhook, cron job), every matching
+ * subscriber is notified and re-renders its HTML fragment over SSE.
+ *
+ * Current implementation: plain Node.js `EventEmitter` — zero dependencies,
+ * zero config, works for any single-process deployment (Railway, Fly.io,
+ * Render, Heroku — single dyno/instance covers the vast majority of use cases).
+ *
+ * ─── Redis adapter (ON HOLD) ──────────────────────────────────────────────────
+ * Multi-instance deployments (PM2 cluster, multiple replicas behind a load
+ * balancer) need cross-process pub/sub: `invalidateLive` called on instance A
+ * must wake SSE connections on instances B and C.
+ *
+ * A Redis adapter is planned but intentionally deferred:
+ *  - Most alab apps run single-instance and would pay Redis cost for no benefit
+ *  - Vertical scaling (bigger machine) handles serious load before needing replicas
+ *  - The interface here (`subscribeToTag` / `broadcastTag`) is already the right
+ *    abstraction; swapping the backend is a ~20-line change when needed
+ *
+ * When it ships it will be an optional package:
+ *
+ * ```ts
+ * // alabjs.config.ts
+ * import { redisBroadcaster } from "@alabjs/broadcaster-redis";
+ *
+ * export default defineConfig({
+ *   live: { broadcaster: redisBroadcaster({ url: process.env.REDIS_URL }) },
+ * });
+ * ```
+ *
+ * Tracking issue: https://github.com/alab-framework/alab/issues — search
+ * "broadcaster-redis" to follow progress or upvote.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+
+import { EventEmitter } from "node:events";
+
+// One emitter per process — all SSE handlers share it.
+const _emitter = new EventEmitter();
+// Prevent Node.js MaxListenersExceededWarning on pages with many live components.
+_emitter.setMaxListeners(0);
+
+const TAG_EVENT_PREFIX = "live:tag:";
+
+/**
+ * Subscribe a callback to a specific tag.
+ *
+ * @returns An unsubscribe function — call it on SSE client disconnect.
+ */
+export function subscribeToTag(tag: string, callback: () => void): () => void {
+  const event = TAG_EVENT_PREFIX + tag;
+  _emitter.on(event, callback);
+  return () => _emitter.off(event, callback);
+}
+
+/**
+ * Broadcast a tag change to all live SSE connections subscribed to it.
+ */
+export function broadcastTag(tag: string): void {
+  _emitter.emit(TAG_EVENT_PREFIX + tag);
+}
+
+/**
+ * Invalidate live components by tag.
+ *
+ * Triggers an immediate re-render push for every SSE connection subscribed
+ * to any of the given tags. Called from route handlers, webhooks, cron jobs,
+ * or the existing `/_alabjs/revalidate` endpoint.
+ *
+ * ```ts
+ * import { invalidateLive } from "alabjs/server";
+ * await invalidateLive({ tags: ["stock:AAPL", "stock:GOOG"] });
+ * ```
+ */
+export async function invalidateLive(opts: { tags: string[] }): Promise<void> {
+  for (const tag of opts.tags) {
+    broadcastTag(tag);
+  }
+}

package/src/live/registry.ts

@@ -0,0 +1,56 @@
+/**
+ * Live component registry.
+ *
+ * At server startup, `createApp` scans `dist/server/**\/*.live.js`, imports
+ * each module, reads the `liveInterval` and `liveTags` exports, and calls
+ * `registerLiveComponent()`. The SSE endpoint then looks up entries here.
+ */
+
+export interface LiveComponentEntry {
+  /** Stable FNV-1a hash of the original source module path (16 hex chars). */
+  id: string;
+  /** Absolute path to the compiled `.live.js` file in dist/server. */
+  modulePath: string;
+  /**
+   * Re-render interval in milliseconds.
+   * Set via `export const liveInterval = 5000` in the live component file.
+   * When undefined, the component only updates on tag invalidation.
+   */
+  liveInterval?: number;
+  /**
+   * Function that returns cache tags for a given props object.
+   * Set via `export const liveTags = (props) => [\`stock:\${props.ticker}\`]`.
+   * When undefined, the component is not subscribed to tag broadcasts.
+   */
+  liveTags?: (props: unknown) => string[];
+}
+
+const _registry = new Map<string, LiveComponentEntry>();
+
+export function registerLiveComponent(entry: LiveComponentEntry): void {
+  _registry.set(entry.id, entry);
+}
+
+export function getLiveComponent(id: string): LiveComponentEntry | undefined {
+  return _registry.get(id);
+}
+
+/** Return all entries whose `liveTags(props)` includes the given tag. */
+export function getLiveComponentsByTag(tag: string): Array<{ entry: LiveComponentEntry; props: unknown }> {
+  // This is called by the broadcaster when a tag is invalidated.
+  // Each SSE connection registers itself with the tag broadcaster directly,
+  // so this function is used only for discovery — not for fan-out.
+  const results: Array<{ entry: LiveComponentEntry; props: unknown }> = [];
+  for (const entry of _registry.values()) {
+    if (entry.liveTags) {
+      // We don't know props here — tag matching is handled per-connection
+      // in the SSE handler via subscribeToTag.
+      results.push({ entry, props: undefined });
+    }
+  }
+  return results;
+}
+
+export function registrySize(): number {
+  return _registry.size;
+}

package/src/live/renderer.ts

@@ -0,0 +1,54 @@
+/**
+ * Server-side HTML fragment renderer for live components.
+ *
+ * Uses `renderToStaticMarkup` (not `renderToPipeableStream`) because:
+ *   - The SSE update path does a raw DOM swap — no React hydration needed.
+ *   - Synchronous output fits the push model.
+ *   - No `data-reactroot` attributes in the fragment (smaller payload).
+ */
+
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+
+/**
+ * Render a live component to an HTML fragment string.
+ *
+ * @param modulePath - Absolute path to the compiled `.live.js` module.
+ * @param props      - Props to pass to the component (from the SSE query string).
+ * @returns          - Raw HTML string (no wrapping element).
+ */
+export async function renderLiveFragment(
+  modulePath: string,
+  props: unknown,
+): Promise<string> {
+  // Dynamic import — Node's module cache means repeated calls for the same
+  // module path are effectively free after the first load.
+  const mod = await import(modulePath) as { default?: unknown };
+  const Component = mod.default;
+
+  if (typeof Component !== "function") {
+    throw new Error(
+      `[alabjs] live component at ${modulePath} has no default export`,
+    );
+  }
+
+  // renderToStaticMarkup handles async components (React 19+).
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const html = renderToStaticMarkup(createElement(Component as any, props as any));
+  return html;
+}
+
+/**
+ * FNV-1a 64-bit content hash of an HTML string.
+ * Used to suppress no-op SSE pushes when the rendered output hasn't changed.
+ */
+export function hashFragment(html: string): string {
+  const FNV_OFFSET = 14_695_981_039_346_656_037n;
+  const FNV_PRIME = 1_099_511_628_211n;
+  let hash = FNV_OFFSET;
+  for (let i = 0; i < html.length; i++) {
+    hash ^= BigInt(html.charCodeAt(i));
+    hash = BigInt.asUintN(64, hash * FNV_PRIME);
+  }
+  return hash.toString(16).padStart(16, "0");
+}

package/src/router/manifest.ts

@@ -1,4 +1,4 @@
-export type RouteKind = "page" | "server" | "layout" | "error" | "loading" | "api";
+export type RouteKind = "page" | "server" | "layout" | "error" | "loading" | "api" | "live";
 
 export interface Route {
   path: string;