@bractjs/bractjs 0.1.0

package/src/server/index.ts

@@ -0,0 +1,8 @@
+export { createServer } from "./serve.ts";
+export type { BractJSConfig } from "./serve.ts";
+
+export { renderRoute } from "./render.ts";
+export type { RenderOptions, ServerManifest } from "./render.ts";
+
+export { redirect, json, error } from "./response.ts";
+export { isDev, requireEnv, safeStringify } from "./env.ts";

package/src/server/layout.ts

@@ -0,0 +1,92 @@
+import { join, resolve } from "node:path";
+import type { RouteFile } from "./scanner.ts";
+import type { RouteModule } from "../shared/route-types.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface LayoutChain {
+  root: RouteModule;
+  layouts: RouteModule[];
+  route: RouteModule;
+}
+
+export interface ResolvedRoute extends RouteFile {
+  layoutFiles: string[];
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+/** Derive the ancestor directory segments from a route's urlPattern. */
+function layoutDirs(urlPattern: string): string[] {
+  if (urlPattern === "") return [];
+  const segments = urlPattern.split("/");
+  // For "blog/[id]" → check "routes/blog/layout.tsx" only (not the leaf)
+  segments.pop();
+  const dirs: string[] = [];
+  for (let i = 1; i <= segments.length; i++) {
+    dirs.push(segments.slice(0, i).join("/"));
+  }
+  return dirs;
+}
+
+// ── resolveLayoutChain ─────────────────────────────────────────────────────
+
+export async function resolveLayoutChain(
+  routeFile: RouteFile,
+  appDir: string
+): Promise<ResolvedRoute> {
+  const layoutFiles: string[] = [];
+
+  // root.tsx is always first — resolve to absolute so dynamic import works
+  // regardless of which package file calls importRouteModule.
+  const rootPath = resolve(join(appDir, "root.tsx"));
+  if (await Bun.file(rootPath).exists()) {
+    layoutFiles.push(rootPath);
+  }
+
+  // Intermediate layout.tsx files, outermost → innermost
+  for (const dir of layoutDirs(routeFile.urlPattern)) {
+    const layoutPath = resolve(join(appDir, "routes", dir, "layout.tsx"));
+    if (await Bun.file(layoutPath).exists()) {
+      layoutFiles.push(layoutPath);
+    }
+  }
+
+  return { ...routeFile, layoutFiles };
+}
+
+// ── importRouteModule ──────────────────────────────────────────────────────
+
+export async function importRouteModule(filePath: string): Promise<RouteModule> {
+  const mod = await import(filePath);
+  return {
+    loader: mod.loader,
+    action: mod.action,
+    meta: mod.meta,
+    handle: mod.handle,
+    ErrorBoundary: mod.ErrorBoundary,
+    default: mod.default,
+  };
+}
+
+// ── resolveRouteChain ──────────────────────────────────────────────────────
+
+export async function resolveRouteChain(
+  routeFile: RouteFile,
+  appDir: string
+): Promise<LayoutChain> {
+  const resolved = await resolveLayoutChain(routeFile, appDir);
+
+  const [rootMod, ...layoutMods] = await Promise.all(
+    resolved.layoutFiles.map(importRouteModule)
+  );
+  const routeMod = await importRouteModule(
+    resolve(join(appDir, routeFile.filePath))
+  );
+
+  return {
+    root: rootMod ?? {},
+    layouts: layoutMods,
+    route: routeMod,
+  };
+}

package/src/server/loader.ts

@@ -0,0 +1,80 @@
+import type { LoaderArgs, ActionArgs, RouteModule } from "../shared/route-types.ts";
+import type { LayoutChain } from "./layout.ts";
+import { isRedirect, isHttpError } from "../shared/errors.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export type LoaderResult = unknown | { __error: unknown } | null;
+
+export interface LoaderResults {
+  root: LoaderResult;
+  layouts: LoaderResult[];
+  route: LoaderResult;
+}
+
+// ── safeRun ────────────────────────────────────────────────────────────────
+
+export async function safeRun<T>(
+  fn: ((args: LoaderArgs) => Promise<T> | T) | undefined,
+  args: LoaderArgs
+): Promise<T | { __error: unknown } | null> {
+  if (!fn) return null;
+
+  try {
+    return await fn(args);
+  } catch (err) {
+    // Re-throw redirects and HTTP errors — caller handles them
+    if (isRedirect(err) || isHttpError(err)) throw err;
+    return { __error: err };
+  }
+}
+
+// ── runLoaders ─────────────────────────────────────────────────────────────
+
+export async function runLoaders(
+  chain: LayoutChain,
+  args: LoaderArgs
+): Promise<LoaderResults> {
+  const layoutLoaders = chain.layouts.map((mod) =>
+    safeRun(mod.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args)
+  );
+
+  const [root, ...layoutResults] = await Promise.all([
+    safeRun(chain.root.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args),
+    ...layoutLoaders,
+  ]);
+
+  const route = await safeRun(
+    chain.route.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined,
+    args
+  );
+
+  return { root, layouts: layoutResults, route };
+}
+
+// ── runAction ──────────────────────────────────────────────────────────────
+
+export async function runAction(
+  routeModule: RouteModule,
+  args: ActionArgs
+): Promise<unknown> {
+  if (!routeModule.action) return null;
+
+  try {
+    return await (routeModule.action as (a: ActionArgs) => Promise<unknown>)(args);
+  } catch (err) {
+    // Re-throw redirects so the server can issue the 3xx response
+    if (isRedirect(err) || isHttpError(err)) throw err;
+    throw err;
+  }
+}
+
+// ── buildLoaderArgs ────────────────────────────────────────────────────────
+
+export function buildLoaderArgs(
+  request: Request,
+  params: Record<string, string>,
+  context: Record<string, unknown>
+): LoaderArgs {
+  return { request, params, context };
+}

package/src/server/matcher.ts

@@ -0,0 +1,99 @@
+import type { RouteFile, Segment } from "./scanner.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface TrieNode {
+  children: Map<string, TrieNode>;
+  paramChild?: { name: string; node: TrieNode };
+  catchAllChild?: { name: string; node: TrieNode };
+  routeFile?: RouteFile;
+}
+
+export type MatchResult = {
+  routeFile: RouteFile;
+  params: Record<string, string>;
+} | null;
+
+// ── Build ──────────────────────────────────────────────────────────────────
+
+function makeNode(): TrieNode {
+  return { children: new Map() };
+}
+
+export function buildTrie(routes: RouteFile[]): TrieNode {
+  const root = makeNode();
+
+  for (const route of routes) {
+    let node = root;
+
+    for (const seg of route.segments) {
+      if (typeof seg === "string") {
+        if (!node.children.has(seg)) node.children.set(seg, makeNode());
+        node = node.children.get(seg)!;
+      } else if ("param" in seg) {
+        if (!node.paramChild) node.paramChild = { name: seg.param, node: makeNode() };
+        node = node.paramChild.node;
+      } else {
+        // catchAll — terminal, store and stop
+        if (!node.catchAllChild) node.catchAllChild = { name: seg.catchAll, node: makeNode() };
+        node = node.catchAllChild.node;
+        break;
+      }
+    }
+
+    node.routeFile = route;
+  }
+
+  return root;
+}
+
+// ── Match ──────────────────────────────────────────────────────────────────
+
+export function matchRoute(pathname: string, trie: TrieNode): MatchResult {
+  const parts = pathname.split("/").filter(Boolean);
+  return walk(trie, parts, 0, {});
+}
+
+function walk(
+  node: TrieNode,
+  parts: string[],
+  idx: number,
+  params: Record<string, string>
+): MatchResult {
+  // All parts consumed — check for route at this node
+  if (idx === parts.length) {
+    return node.routeFile ? { routeFile: node.routeFile, params } : null;
+  }
+
+  const part = parts[idx];
+
+  // 1. Prefer static match
+  const staticChild = node.children.get(part);
+  if (staticChild) {
+    const result = walk(staticChild, parts, idx + 1, params);
+    if (result) return result;
+  }
+
+  // 2. Try param match
+  if (node.paramChild) {
+    const result = walk(node.paramChild.node, parts, idx + 1, {
+      ...params,
+      [node.paramChild.name]: part,
+    });
+    if (result) return result;
+  }
+
+  // 3. Try catch-all — consumes remaining segments
+  if (node.catchAllChild) {
+    const remaining = parts.slice(idx).join("/");
+    const catchNode = node.catchAllChild.node;
+    if (catchNode.routeFile) {
+      return {
+        routeFile: catchNode.routeFile,
+        params: { ...params, [node.catchAllChild.name]: remaining },
+      };
+    }
+  }
+
+  return null;
+}

package/src/server/meta.ts

@@ -0,0 +1,92 @@
+import type { LayoutChain } from "./layout.ts";
+import type { LoaderResults } from "./loader.ts";
+import type { MetaDescriptor } from "../shared/route-types.ts";
+
+type Params = Record<string, string>;
+
+// ── resolveMeta ────────────────────────────────────────────────────────────
+
+/**
+ * Calls each route module's meta() in layout chain order (root → layouts → route),
+ * passing the appropriate loaderData slice + params to each.
+ */
+export function resolveMeta(
+  chain: LayoutChain,
+  loaderData: LoaderResults,
+  params: Params,
+): MetaDescriptor[] {
+  const all: MetaDescriptor[] = [];
+
+  if (chain.root.meta) {
+    all.push(...chain.root.meta({ loaderData: loaderData.root, params }));
+  }
+
+  chain.layouts.forEach((mod, i) => {
+    if (mod.meta) {
+      all.push(...mod.meta({ loaderData: loaderData.layouts[i] ?? null, params }));
+    }
+  });
+
+  if (chain.route.meta) {
+    all.push(...chain.route.meta({ loaderData: loaderData.route, params }));
+  }
+
+  return all;
+}
+
+// ── mergeMeta ──────────────────────────────────────────────────────────────
+
+/**
+ * Deduplicates descriptors: for same `name` or `property`, last-writer wins.
+ * Title: last `{ title }` descriptor wins.
+ */
+export function mergeMeta(descriptors: MetaDescriptor[]): MetaDescriptor[] {
+  const byName = new Map<string, MetaDescriptor>();
+  const byProperty = new Map<string, MetaDescriptor>();
+  let title: MetaDescriptor | null = null;
+  const rest: MetaDescriptor[] = [];
+
+  for (const d of descriptors) {
+    if ("title" in d) {
+      title = d;
+    } else if ("name" in d) {
+      byName.set((d as { name: string }).name, d);
+    } else if ("property" in d) {
+      byProperty.set((d as { property: string }).property, d);
+    } else {
+      rest.push(d);
+    }
+  }
+
+  return [
+    ...(title ? [title] : []),
+    ...Array.from(byName.values()),
+    ...Array.from(byProperty.values()),
+    ...rest,
+  ];
+}
+
+// ── renderMetaTags ─────────────────────────────────────────────────────────
+
+/** Returns HTML string of <title> and <meta> tags for SSR head injection. */
+export function renderMetaTags(descriptors: MetaDescriptor[]): string {
+  return descriptors
+    .map((d) => {
+      if ("title" in d) return `<title>${escHtml(String((d as { title: string }).title))}</title>`;
+      if ("name" in d) {
+        const { name, content } = d as { name: string; content: string };
+        return `<meta name="${escHtml(name)}" content="${escHtml(content)}">`;
+      }
+      if ("property" in d) {
+        const { property, content } = d as { property: string; content: string };
+        return `<meta property="${escHtml(property)}" content="${escHtml(content)}">`;
+      }
+      return "";
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+function escHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/src/server/middleware.ts

@@ -0,0 +1,47 @@
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface MiddlewareContext {
+  request: Request;
+  params: Record<string, string>;
+  context: Record<string, unknown>;
+}
+
+export type MiddlewareFn = (
+  ctx: MiddlewareContext,
+  next: () => Promise<Response>,
+) => Promise<Response>;
+
+// ── Pipeline ───────────────────────────────────────────────────────────────
+
+export class MiddlewarePipeline {
+  private fns: MiddlewareFn[] = [];
+
+  /** Register a middleware function. Returns `this` for chaining. */
+  use(fn: MiddlewareFn): this {
+    this.fns.push(fn);
+    return this;
+  }
+
+  /**
+   * Compose all registered middleware into a single chain and execute it.
+   * Each fn calls `next()` to invoke the next fn; the last `next()` calls `handler`.
+   */
+  run(
+    ctx: MiddlewareContext,
+    handler: () => Promise<Response>,
+  ): Promise<Response> {
+    let index = 0;
+    const fns = this.fns;
+
+    const dispatch = (): Promise<Response> => {
+      if (index >= fns.length) return handler();
+      const fn = fns[index++];
+      return fn(ctx, dispatch);
+    };
+
+    return dispatch();
+  }
+}
+
+/** Module-level default pipeline — attach middleware here via pipeline.use(). */
+export const pipeline = new MiddlewarePipeline();

package/src/server/render.ts

@@ -0,0 +1,65 @@
+import { renderToReadableStream } from "react-dom/server";
+import type { ReactNode } from "react";
+import type { MetaDescriptor } from "../shared/route-types.ts";
+import { safeStringify, isDev } from "./env.ts";
+import { errorOverlayScript } from "../dev/error-overlay.ts";
+import { mergeMeta, renderMetaTags } from "./meta.ts";
+
+export interface ServerManifest {
+  clientEntry: string;
+  rootChunk?: string;
+  routes: Record<string, { file: string; chunk?: string; imports?: string[] }>;
+}
+
+export interface RenderOptions {
+  shell: ReactNode;
+  loaderData: Record<string, unknown>;
+  actionData: unknown;
+  params: Record<string, string>;
+  pathname: string;
+  manifest: ServerManifest;
+  meta: MetaDescriptor[];
+  status?: number;
+  /** Path of the matched route file (e.g. "routes/_index.tsx"), used by the client to pre-import the module before hydration. */
+  routeFile?: string;
+}
+
+export async function renderRoute(options: RenderOptions): Promise<Response> {
+  const {
+    shell,
+    loaderData,
+    actionData,
+    params,
+    pathname,
+    manifest,
+    status = 200,
+  } = options;
+
+  const devOverlay = isDev() ? errorOverlayScript + "\n" : "";
+  const metaHtml = renderMetaTags(mergeMeta(options.meta ?? []));
+  // Include manifest + routeFile so the client can pre-import the route module
+  // before hydrateRoot(), preventing the SSR/client tree mismatch.
+  const bootstrapScriptContent =
+    devOverlay + `window.__BRACTJS_DATA__=${safeStringify({ loaderData, actionData, params, pathname, manifest, routeFile: options.routeFile, meta: metaHtml })};`;
+
+  let renderError: unknown;
+
+  const stream = await renderToReadableStream(shell, {
+    bootstrapScriptContent,
+    bootstrapModules: [manifest.clientEntry],
+    onError(error) {
+      renderError = error;
+      console.error("[bract] renderToReadableStream error:", error);
+    },
+  });
+
+  const responseStatus = renderError ? 500 : status;
+
+  return new Response(stream, {
+    status: responseStatus,
+    headers: {
+      "Content-Type": "text/html; charset=utf-8",
+      "Transfer-Encoding": "chunked",
+    },
+  });
+}

package/src/server/request-handler.ts

@@ -0,0 +1,142 @@
+import { join } from "node:path";
+import { createElement } from "react";
+import type { TrieNode } from "./matcher.ts";
+import { matchRoute } from "./matcher.ts";
+import { resolveRouteChain } from "./layout.ts";
+import { runLoaders, runAction, buildLoaderArgs } from "./loader.ts";
+import { renderRoute, type ServerManifest } from "./render.ts";
+import { resolveMeta } from "./meta.ts";
+import { json, error } from "./response.ts";
+import { isRedirect } from "../shared/errors.ts";
+import { pipeline, type MiddlewareContext } from "./middleware.ts";
+import { BractJSProvider } from "../shared/context.ts";
+
+export interface HandlerConfig {
+  appDir: string;
+  publicDir: string;
+  manifest: ServerManifest;
+}
+
+const MUTATING_METHODS = new Set(["POST", "PUT", "DELETE", "PATCH"]);
+
+export async function handleRequest(
+  request: Request,
+  trie: TrieNode,
+  config: HandlerConfig
+): Promise<Response> {
+  const ctx: MiddlewareContext = {
+    request,
+    params: {},
+    context: {},
+  };
+
+  return pipeline.run(ctx, () => route(request, trie, config, ctx.context));
+}
+
+async function route(
+  request: Request,
+  trie: TrieNode,
+  config: HandlerConfig,
+  context: Record<string, unknown>,
+): Promise<Response> {
+  const { appDir, publicDir, manifest } = config;
+  const url = new URL(request.url);
+  const { pathname, searchParams } = url;
+
+  // ── Static public assets ──────────────────────────────────────────────
+  if (pathname.startsWith("/public/")) {
+    const file = Bun.file(join(publicDir, pathname.slice("/public/".length)));
+    if (await file.exists()) return new Response(file);
+    return error("Not Found", 404);
+  }
+
+  // ── /_data soft-nav JSON endpoint ─────────────────────────────────────
+  if (pathname.startsWith("/_data")) {
+    const targetPath = searchParams.get("path") ?? "/";
+    const match = matchRoute(targetPath, trie);
+    if (!match) return json({ error: "Not Found" }, { status: 404 });
+
+    try {
+      const chain = await resolveRouteChain(match.routeFile, appDir);
+      const args = buildLoaderArgs(request, match.params, {});
+      const results = await runLoaders(chain, args);
+      return json({ root: results.root, layouts: results.layouts, route: results.route, params: match.params });
+    } catch (err) {
+      console.error("[bractjs] /_data error:", err);
+      return json({ error: "Internal Server Error" }, { status: 500 });
+    }
+  }
+
+  // ── Route matching ────────────────────────────────────────────────────
+  const match = matchRoute(pathname, trie);
+  if (!match) return error("Not Found", 404);
+
+  const chain = await resolveRouteChain(match.routeFile, appDir);
+  const args = buildLoaderArgs(request, match.params, context);
+
+  // ── Action (mutating methods) ─────────────────────────────────────────
+  let actionData: unknown = null;
+  if (MUTATING_METHODS.has(request.method)) {
+    try {
+      const formData = await request.formData();
+      actionData = await runAction(chain.route, { ...args, formData });
+    } catch (err) {
+      if (isRedirect(err)) return err as Response;
+      throw err;
+    }
+
+    // Client-side Form submits with this header — return JSON, not HTML.
+    if (request.headers.get("X-BractJS-Action")) {
+      return json(actionData ?? null);
+    }
+  }
+
+  // ── Loaders ───────────────────────────────────────────────────────────
+  let loaderResults;
+  try {
+    loaderResults = await runLoaders(chain, args);
+  } catch (err) {
+    if (isRedirect(err)) return err as Response;
+    throw err;
+  }
+
+  const loaderData = {
+    root: loaderResults.root,
+    layouts: loaderResults.layouts,
+    route: loaderResults.route,
+  };
+
+  // ── SSR render ────────────────────────────────────────────────────────
+  const RootComponent = chain.root.default ?? (() => null);
+  const RouteComponent = chain.route.default;
+
+  // Wrap root in BractJSProvider so <Outlet> can render the route component
+  // server-side without needing a ClientRouter.
+  const shell = createElement(
+    BractJSProvider,
+    {
+      value: {
+        loaderData: loaderData as Record<string, unknown>,
+        actionData,
+        params: match.params,
+        pathname,
+        manifest: manifest as unknown as import("../shared/context.ts").RouteManifest,
+        RouteComponent,
+      },
+      children: createElement(RootComponent),
+    },
+  );
+
+  const meta = resolveMeta(chain, loaderResults, match.params);
+
+  return renderRoute({
+    shell,
+    loaderData,
+    actionData,
+    params: match.params,
+    pathname,
+    manifest,
+    meta,
+    routeFile: match.routeFile.filePath,
+  });
+}

package/src/server/response.ts

@@ -0,0 +1,17 @@
+export function redirect(url: string, status: number = 302): Response {
+  return new Response(null, {
+    status,
+    headers: { Location: url },
+  });
+}
+
+export function json<T>(data: T, init?: ResponseInit): Response {
+  const body = JSON.stringify(data);
+  const headers = new Headers(init?.headers);
+  headers.set("Content-Type", "application/json; charset=utf-8");
+  return new Response(body, { ...init, headers });
+}
+
+export function error(message: string, status: number = 500): Response {
+  return json({ error: message }, { status });
+}