react-bun-ssr 0.1.0

package/framework/runtime/deferred.ts

@@ -0,0 +1,115 @@
+import type { DeferredLoaderResult, DeferredToken } from "./types";
+
+interface ThenableLike {
+  then: (onFulfilled?: (value: unknown) => unknown, onRejected?: (reason: unknown) => unknown) => unknown;
+}
+
+export interface DeferredSettleEntry {
+  id: string;
+  settled: Promise<
+    | { ok: true; value: unknown }
+    | { ok: false; error: string }
+  >;
+}
+
+export interface PreparedDeferredPayload {
+  dataForRender: Record<string, unknown>;
+  dataForPayload: Record<string, unknown>;
+  settleEntries: DeferredSettleEntry[];
+}
+
+const DEFERRED_TYPE = "defer";
+const DEFERRED_TOKEN_KEY = "__rbssrDeferred";
+
+let deferredCounter = 0;
+
+function nextDeferredId(routeId: string, key: string): string {
+  deferredCounter += 1;
+  return `${routeId}:${key}:${deferredCounter}`;
+}
+
+function isThenable(value: unknown): value is ThenableLike {
+  return Boolean(
+    value &&
+      (typeof value === "object" || typeof value === "function") &&
+      typeof (value as ThenableLike).then === "function",
+  );
+}
+
+function toErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+export function defer<T extends Record<string, unknown>>(data: T): DeferredLoaderResult<T> {
+  if (!data || Array.isArray(data) || typeof data !== "object") {
+    throw new Error("defer() expects an object with top-level keys.");
+  }
+
+  return {
+    __rbssrType: DEFERRED_TYPE,
+    data,
+  };
+}
+
+export function isDeferredLoaderResult(value: unknown): value is DeferredLoaderResult<Record<string, unknown>> {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      (value as DeferredLoaderResult<Record<string, unknown>>).__rbssrType === DEFERRED_TYPE &&
+      (value as DeferredLoaderResult<Record<string, unknown>>).data &&
+      !Array.isArray((value as DeferredLoaderResult<Record<string, unknown>>).data) &&
+      typeof (value as DeferredLoaderResult<Record<string, unknown>>).data === "object",
+  );
+}
+
+export function isDeferredToken(value: unknown): value is DeferredToken {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      typeof (value as DeferredToken)[DEFERRED_TOKEN_KEY] === "string",
+  );
+}
+
+export function createDeferredToken(id: string): DeferredToken {
+  return {
+    [DEFERRED_TOKEN_KEY]: id,
+  };
+}
+
+export function prepareDeferredPayload(
+  routeId: string,
+  deferredValue: DeferredLoaderResult<Record<string, unknown>>,
+): PreparedDeferredPayload {
+  const dataForRender: Record<string, unknown> = {};
+  const dataForPayload: Record<string, unknown> = {};
+  const settleEntries: DeferredSettleEntry[] = [];
+
+  for (const [key, value] of Object.entries(deferredValue.data)) {
+    if (!isThenable(value)) {
+      dataForRender[key] = value;
+      dataForPayload[key] = value;
+      continue;
+    }
+
+    const id = nextDeferredId(routeId, key);
+    const promise = Promise.resolve(value);
+    dataForRender[key] = promise;
+    dataForPayload[key] = createDeferredToken(id);
+    settleEntries.push({
+      id,
+      settled: promise.then(
+        resolved => ({ ok: true as const, value: resolved }),
+        error => ({ ok: false as const, error: toErrorMessage(error) }),
+      ),
+    });
+  }
+
+  return {
+    dataForRender,
+    dataForPayload,
+    settleEntries,
+  };
+}

package/framework/runtime/helpers.ts

@@ -0,0 +1,40 @@
+import type { FrameworkConfig, RedirectResult } from "./types";
+import { defer as deferValue } from "./deferred";
+
+export function json(data: unknown, init: ResponseInit = {}): Response {
+  const headers = new Headers(init.headers);
+  if (!headers.has("content-type")) {
+    headers.set("content-type", "application/json; charset=utf-8");
+  }
+
+  return new Response(JSON.stringify(data), {
+    ...init,
+    headers,
+  });
+}
+
+export function redirect(
+  location: string,
+  status: RedirectResult["status"] = 302,
+): RedirectResult {
+  return {
+    type: "redirect",
+    location,
+    status,
+  };
+}
+
+export function defineConfig(config: FrameworkConfig): FrameworkConfig {
+  return config;
+}
+
+export const defer = deferValue;
+
+export function isRedirectResult(value: unknown): value is RedirectResult {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      (value as RedirectResult).type === "redirect" &&
+      typeof (value as RedirectResult).location === "string",
+  );
+}

package/framework/runtime/index.ts

@@ -0,0 +1,24 @@
+export type {
+  Action,
+  ActionContext,
+  ActionResult,
+  ApiRouteModule,
+  BuildManifest,
+  BuildRouteAsset,
+  DeferredLoaderResult,
+  DeferredToken,
+  FrameworkConfig,
+  Loader,
+  LoaderContext,
+  LoaderResult,
+  Middleware,
+  Params,
+  RedirectResult,
+  ResponseHeaderRule,
+  RequestContext,
+  RouteModule,
+} from "./types";
+
+export { createServer, startHttpServer } from "./server";
+export { defer, json, redirect, defineConfig } from "./helpers";
+export { Outlet, useLoaderData, useParams, useRequestUrl, useRouteError } from "./tree";

package/framework/runtime/io.ts

@@ -0,0 +1,146 @@
+import path from "node:path";
+
+type BunFileStat = Awaited<ReturnType<ReturnType<typeof Bun.file>["stat"]>>;
+export type HashInput = string | ArrayBuffer | Uint8Array;
+export interface FileEntry {
+  name: string;
+  isDirectory: boolean;
+  isFile: boolean;
+}
+
+function isErrno(error: unknown, code: string): boolean {
+  return Boolean(
+    error
+      && typeof error === "object"
+      && "code" in error
+      && (error as { code?: unknown }).code === code,
+  );
+}
+
+export async function statPath(filePath: string): Promise<BunFileStat | null> {
+  try {
+    return await Bun.file(filePath).stat();
+  } catch (error) {
+    if (isErrno(error, "ENOENT")) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+export async function existsPath(filePath: string): Promise<boolean> {
+  return (await statPath(filePath)) !== null;
+}
+
+export async function readText(filePath: string): Promise<string> {
+  return Bun.file(filePath).text();
+}
+
+export async function writeText(filePath: string, content: string): Promise<void> {
+  await ensureDir(path.dirname(filePath));
+  await Bun.write(filePath, content);
+}
+
+export async function writeTextIfChanged(filePath: string, content: string): Promise<boolean> {
+  const stat = await statPath(filePath);
+  if (stat?.isFile()) {
+    const current = await readText(filePath);
+    if (current === content) {
+      return false;
+    }
+  }
+
+  await writeText(filePath, content);
+  return true;
+}
+
+export async function glob(
+  pattern: string,
+  options: {
+    cwd: string;
+    absolute?: boolean;
+    dot?: boolean;
+  },
+): Promise<string[]> {
+  const entries: string[] = [];
+  const scanner = new Bun.Glob(pattern);
+  for await (const entry of scanner.scan({
+    ...options,
+    dot: options.dot ?? true,
+  })) {
+    entries.push(entry);
+  }
+  return entries.sort((a, b) => a.localeCompare(b));
+}
+
+export function sha256Short(input: HashInput): string {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(input);
+  return hasher.digest("hex").slice(0, 8);
+}
+
+export async function ensureDir(dirPath: string): Promise<void> {
+  runPosix(["mkdir", "-p", dirPath], `Failed to create directory: ${dirPath}`);
+}
+
+export async function ensureCleanDir(dirPath: string): Promise<void> {
+  await removePath(dirPath);
+  await ensureDir(dirPath);
+}
+
+export async function removePath(targetPath: string): Promise<void> {
+  runPosix(["rm", "-rf", targetPath], `Failed to remove path: ${targetPath}`);
+}
+
+export async function listEntries(dirPath: string): Promise<FileEntry[]> {
+  const dirStat = await statPath(dirPath);
+  if (!dirStat?.isDirectory()) {
+    return [];
+  }
+
+  const names = await glob("*", {
+    cwd: dirPath,
+    dot: true,
+  });
+
+  const entries: FileEntry[] = [];
+  for (const name of names) {
+    const absolutePath = path.join(dirPath, name);
+    const entryStat = await statPath(absolutePath);
+    if (!entryStat) {
+      continue;
+    }
+
+    entries.push({
+      name,
+      isDirectory: entryStat.isDirectory(),
+      isFile: entryStat.isFile(),
+    });
+  }
+
+  return entries;
+}
+
+export async function makeTempDir(prefix: string): Promise<string> {
+  const dirPath = path.join("/tmp", `${prefix}-${crypto.randomUUID()}`);
+  await ensureDir(dirPath);
+  return dirPath;
+}
+
+function runPosix(cmd: string[], context: string): void {
+  const result = Bun.spawnSync({
+    cmd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  if (result.exitCode === 0) {
+    return;
+  }
+
+  const decoder = new TextDecoder();
+  const stderr = result.stderr.length > 0 ? decoder.decode(result.stderr).trim() : "";
+  const stdout = result.stdout.length > 0 ? decoder.decode(result.stdout).trim() : "";
+  const details = stderr || stdout || `exit code ${result.exitCode}`;
+  throw new Error(`[io] ${context} (${cmd.join(" ")}): ${details}`);
+}

package/framework/runtime/markdown-routes.ts

@@ -0,0 +1,319 @@
+import path from "node:path";
+import { existsPath, readText, writeTextIfChanged } from "./io";
+import { normalizeSlashes, stableHash, trimFileExtension } from "./utils";
+
+const compiledMarkdownCache = new Map<string, { sourceHash: string; outputPath: string }>();
+const REQUIRED_FRONTMATTER_FIELDS = ["title", "description", "section", "order"] as const;
+const MARKDOWN_WRAPPER_VERSION = "2";
+
+interface ParsedFrontmatter {
+  title?: string;
+  description?: string;
+  section?: string;
+  tags: string[];
+}
+
+function decodeHtml(value: string): string {
+  return value
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, "\"")
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/\"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+function highlightWithRegex(
+  source: string,
+  regex: RegExp,
+  classify: (value: string) => string,
+): string {
+  let cursor = 0;
+  let html = "";
+  let match = regex.exec(source);
+
+  while (match) {
+    const value = match[0] ?? "";
+    const index = match.index;
+
+    if (index > cursor) {
+      html += escapeHtml(source.slice(cursor, index));
+    }
+
+    html += `<span class="token ${classify(value)}">${escapeHtml(value)}</span>`;
+    cursor = index + value.length;
+    match = regex.exec(source);
+  }
+
+  if (cursor < source.length) {
+    html += escapeHtml(source.slice(cursor));
+  }
+
+  return html;
+}
+
+function highlightCode(source: string, language: string): string {
+  const normalized = language.toLowerCase();
+
+  if (["ts", "tsx", "js", "jsx", "mjs", "cjs"].includes(normalized)) {
+    const pattern =
+      /(\/\/.*$|\/\*[\s\S]*?\*\/|"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`|\b(?:const|let|var|function|return|if|else|for|while|switch|case|break|continue|import|from|export|default|async|await|try|catch|throw|new|class|extends|interface|type|implements|public|private|protected|readonly|as|in|of|typeof)\b|\b(?:true|false|null|undefined)\b|\b\d+(?:\.\d+)?\b)/gm;
+
+    return highlightWithRegex(source, pattern, value => {
+      if (value.startsWith("//") || value.startsWith("/*")) return "comment";
+      if (
+        value.startsWith("\"") ||
+        value.startsWith("'") ||
+        value.startsWith("`")
+      )
+        return "string";
+      if (/^\d/.test(value)) return "number";
+      if (/^(true|false|null|undefined)$/.test(value)) return "constant";
+      return "keyword";
+    });
+  }
+
+  if (["bash", "sh", "zsh", "shell"].includes(normalized)) {
+    const pattern =
+      /(#.*$|"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\b(?:if|then|fi|for|in|do|done|case|esac|while|function|export)\b|(?:^|\s)(?:bun|npm|node|git|curl|cd|ls|cat|echo)(?=\s|$)|--?[a-zA-Z0-9-]+)/gm;
+
+    return highlightWithRegex(source, pattern, value => {
+      const trimmed = value.trim();
+      if (trimmed.startsWith("#")) return "comment";
+      if (trimmed.startsWith("\"") || trimmed.startsWith("'")) return "string";
+      if (trimmed.startsWith("-")) return "operator";
+      if (/^(if|then|fi|for|in|do|done|case|esac|while|function|export)$/.test(trimmed))
+        return "keyword";
+      return "builtin";
+    });
+  }
+
+  return escapeHtml(source);
+}
+
+function applySyntaxHighlight(html: string): string {
+  return html.replace(
+    /<pre><code class="language-([^"]+)">([\s\S]*?)<\/code><\/pre>/g,
+    (_match, language: string, rawCode: string) => {
+      const code = decodeHtml(rawCode);
+      const highlighted = highlightCode(code, language);
+      return `<pre><code class="language-${escapeHtml(language)}">${highlighted}</code></pre>`;
+    },
+  );
+}
+
+function resolveGeneratedRoot(routesDir: string, generatedMarkdownRootDir?: string): string {
+  if (generatedMarkdownRootDir) {
+    return path.resolve(generatedMarkdownRootDir);
+  }
+
+  const normalizedRoutesDir = normalizeSlashes(path.resolve(routesDir));
+  const appRoutesMatch = normalizedRoutesDir.match(/^(.*)\/app\/routes$/);
+  if (appRoutesMatch) {
+    return path.resolve(appRoutesMatch[1]!, ".rbssr", "generated", "markdown-routes");
+  }
+
+  const snapshotRoutesMatch = normalizedRoutesDir.match(
+    /^(.*)\/\.rbssr\/dev\/server-snapshots\/v\d+\/routes$/,
+  );
+  if (snapshotRoutesMatch) {
+    return path.resolve(snapshotRoutesMatch[1]!, ".rbssr", "generated", "markdown-routes");
+  }
+
+  return path.resolve(routesDir, "..", ".rbssr", "generated", "markdown-routes");
+}
+
+function toRouteGroupKey(routesDir: string): string {
+  const normalized = normalizeSlashes(path.resolve(routesDir));
+  const canonical = normalized.replace(
+    /\/\.rbssr\/dev\/server-snapshots\/v\d+\/routes$/,
+    "/.rbssr/dev/server-snapshots/routes",
+  );
+
+  return stableHash(`${MARKDOWN_WRAPPER_VERSION}\0${canonical}`);
+}
+
+function parseFrontmatter(raw: string): {
+  frontmatter: ParsedFrontmatter;
+  markdown: string;
+} {
+  if (!raw.startsWith("---\n")) {
+    return {
+      frontmatter: { tags: [] },
+      markdown: raw,
+    };
+  }
+
+  const end = raw.indexOf("\n---\n", 4);
+  if (end < 0) {
+    return {
+      frontmatter: { tags: [] },
+      markdown: raw,
+    };
+  }
+
+  const rawFrontmatterLines = raw.slice(4, end).split("\n");
+  const values = new Map<string, string>();
+  for (const line of rawFrontmatterLines) {
+    const separator = line.indexOf(":");
+    if (separator < 0) {
+      continue;
+    }
+    const key = line.slice(0, separator).trim();
+    const value = line.slice(separator + 1).trim();
+    values.set(key, value);
+  }
+
+  for (const key of REQUIRED_FRONTMATTER_FIELDS) {
+    if (!values.has(key)) {
+      return {
+        frontmatter: { tags: [] },
+        markdown: raw,
+      };
+    }
+  }
+
+  const tags = (values.get("tags") ?? "")
+    .split(",")
+    .map(value => value.trim())
+    .filter(Boolean);
+
+  return {
+    frontmatter: {
+      title: values.get("title"),
+      description: values.get("description"),
+      section: values.get("section"),
+      tags,
+    },
+    markdown: raw.slice(end + 5),
+  };
+}
+
+function stripLeadingH1(html: string): string {
+  return html.replace(/^\s*<h1\b[^>]*>[\s\S]*?<\/h1>\s*/i, "");
+}
+
+function toWrapperSource(options: {
+  html: string;
+  frontmatter: ParsedFrontmatter;
+}): string {
+  const { html, frontmatter } = options;
+  const title = frontmatter.title ?? "";
+  const description = frontmatter.description ?? "";
+  const section = frontmatter.section ?? "";
+  const tags = frontmatter.tags ?? [];
+
+  return `const markdownHtml = ${JSON.stringify(html)};
+const markdownTitle = ${JSON.stringify(title)};
+const markdownDescription = ${JSON.stringify(description)};
+const markdownSection = ${JSON.stringify(section)};
+const markdownTags = ${JSON.stringify(tags)};
+
+export default function MarkdownRoute() {
+  return (
+    <>
+      {markdownTitle ? (
+        <header className="docs-hero">
+          {markdownSection ? <p className="kicker">{markdownSection}</p> : null}
+          <h1>{markdownTitle}</h1>
+          {markdownDescription ? <p>{markdownDescription}</p> : null}
+          {markdownTags.length > 0 ? (
+            <div>
+              {markdownTags.map(tag => (
+                <span key={tag}>{tag}</span>
+              ))}
+            </div>
+          ) : null}
+        </header>
+      ) : null}
+      <section className="docs-content-body" dangerouslySetInnerHTML={{ __html: markdownHtml }} />
+    </>
+  );
+}
+
+export function head() {
+  if (!markdownTitle) {
+    return null;
+  }
+  return <title>{markdownTitle}</title>;
+}
+
+export function meta() {
+  const values: Record<string, string> = {};
+
+  if (markdownDescription) {
+    values.description = markdownDescription;
+    values["og:description"] = markdownDescription;
+    values["twitter:description"] = markdownDescription;
+  }
+
+  if (markdownTitle) {
+    values["og:title"] = markdownTitle;
+    values["twitter:title"] = markdownTitle;
+  }
+
+  values["og:type"] = "article";
+  values["twitter:card"] = "summary_large_image";
+
+  if (markdownSection) {
+    values["article:section"] = markdownSection;
+  }
+
+  if (markdownTags.length > 0) {
+    const joinedTags = markdownTags.join(", ");
+    values.keywords = joinedTags;
+    values["article:tag"] = joinedTags;
+  }
+
+  return values;
+}
+`;
+}
+
+async function writeFileIfChanged(filePath: string, content: string): Promise<void> {
+  await writeTextIfChanged(filePath, content);
+}
+
+export async function compileMarkdownRouteModule(options: {
+  routesDir: string;
+  sourceFilePath: string;
+  generatedMarkdownRootDir?: string;
+}): Promise<string> {
+  const routesDir = path.resolve(options.routesDir);
+  const sourceFilePath = path.resolve(options.sourceFilePath);
+  const generatedRoot = resolveGeneratedRoot(routesDir, options.generatedMarkdownRootDir);
+  const routeGroupKey = toRouteGroupKey(routesDir);
+  const relativeRoutePath = normalizeSlashes(path.relative(routesDir, sourceFilePath));
+  const routeModuleRelativePath = `${trimFileExtension(relativeRoutePath)}.tsx`;
+  const outputPath = path.join(generatedRoot, routeGroupKey, routeModuleRelativePath);
+
+  const markdownSource = await readText(sourceFilePath);
+  const sourceHash = stableHash(`${MARKDOWN_WRAPPER_VERSION}\0${markdownSource}`);
+  const cacheKey = `${sourceFilePath}::${outputPath}`;
+  const cached = compiledMarkdownCache.get(cacheKey);
+  if (cached && cached.sourceHash === sourceHash && await existsPath(cached.outputPath)) {
+    return cached.outputPath;
+  }
+
+  const parsed = parseFrontmatter(markdownSource);
+  const highlightedHtml = applySyntaxHighlight(Bun.markdown.html(parsed.markdown));
+  const html = parsed.frontmatter.title ? stripLeadingH1(highlightedHtml) : highlightedHtml;
+  await writeFileIfChanged(
+    outputPath,
+    toWrapperSource({
+      html,
+      frontmatter: parsed.frontmatter,
+    }),
+  );
+  compiledMarkdownCache.set(cacheKey, { sourceHash, outputPath });
+
+  return outputPath;
+}