@bractjs/bractjs 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bractjs/bractjs",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Production-grade SSR framework for Bun + React 19. File-based routing, streaming SSR, server actions, typed routes.",
   "license": "MIT",
   "homepage": "https://github.com/bractjs/bractjs#readme",

package/src/__tests__/action-handler.test.ts

@@ -0,0 +1,47 @@
+import { test, expect, describe } from "bun:test";
+import { handleActionRequest } from "../server/action-handler.ts";
+import { resolveAction } from "../server/action-registry.ts";
+
+// ── handleActionRequest routing guards ────────────────────────────────────
+
+describe("handleActionRequest — routing", () => {
+  test("returns null for non-/_action paths", async () => {
+    const req = new Request("http://localhost/about", { method: "POST" });
+    const result = await handleActionRequest(req);
+    expect(result).toBeNull();
+  });
+
+  test("returns null for / path (no /_action prefix)", async () => {
+    const req = new Request("http://localhost/", { method: "POST" });
+    expect(await handleActionRequest(req)).toBeNull();
+  });
+
+  test("returns 405 for GET to /_action", async () => {
+    const req = new Request("http://localhost/_action?id=abc", { method: "GET" });
+    const res = await handleActionRequest(req);
+    expect(res?.status).toBe(405);
+  });
+
+  test("returns 400 when id query param is missing", async () => {
+    const req = new Request("http://localhost/_action", { method: "POST", headers: { "X-BractJS-Action": "1" } });
+    const res = await handleActionRequest(req);
+    expect(res?.status).toBe(400);
+  });
+
+  test("returns 404 for unknown action id", async () => {
+    const req = new Request("http://localhost/_action?id=does-not-exist-xyz", { method: "POST", headers: { "X-BractJS-Action": "1" } });
+    const res = await handleActionRequest(req);
+    expect(res?.status).toBe(404);
+  });
+
+});
+
+// ── resolveAction ──────────────────────────────────────────────────────────
+
+describe("resolveAction", () => {
+  test("returns null for unknown ids", () => {
+    expect(resolveAction("nonexistent-id-xyz")).toBeNull();
+    expect(resolveAction("")).toBeNull();
+    expect(resolveAction("00000000")).toBeNull();
+  });
+});

package/src/__tests__/action-registry.test.ts

@@ -0,0 +1,73 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { loadServerActions, resolveAction } from "../server/action-registry.ts";
+
+const TMP = resolve(import.meta.dir, ".tmp-action-registry");
+
+async function computeId(filePath: string, name: string): Promise<string> {
+  const raw = new TextEncoder().encode(filePath + "#" + name);
+  const buf = await crypto.subtle.digest("SHA-256", raw);
+  return Array.from(new Uint8Array(buf))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("")
+    .slice(0, 16);
+}
+
+beforeAll(async () => {
+  await rm(TMP, { recursive: true, force: true });
+  await mkdir(join(TMP, "routes"), { recursive: true });
+  await mkdir(join(TMP, "lib"), { recursive: true });
+
+  // Eligible: routes/ file with real "use server" directive
+  await writeFile(
+    join(TMP, "routes", "_index.tsx"),
+    `"use server";\nexport async function realAction() { return 1; }\n`,
+  );
+
+  // Eligible by suffix: .server.ts
+  await writeFile(
+    join(TMP, "lib", "thing.server.ts"),
+    `"use server";\nexport async function suffixAction() { return 2; }\n`,
+  );
+
+  // Ineligible: arbitrary lib file (no .server suffix, not in routes/)
+  await writeFile(
+    join(TMP, "lib", "helpers.ts"),
+    `"use server";\nexport async function shouldNotLoad() { return 3; }\n`,
+  );
+
+  // Ineligible: "use server" inside a template literal (not at start-of-file)
+  await writeFile(
+    join(TMP, "routes", "fake.tsx"),
+    `const s = \`use server\`;\nexport async function notADirective() { return 4; }\n`,
+  );
+
+  await loadServerActions(TMP);
+});
+
+afterAll(async () => {
+  await rm(TMP, { recursive: true, force: true });
+});
+
+describe("loadServerActions — eligibility", () => {
+  test("routes/ file with real directive registers exports", async () => {
+    const id = await computeId(join(TMP, "routes", "_index.tsx"), "realAction");
+    expect(resolveAction(id)).not.toBeNull();
+  });
+
+  test(".server.ts file registers exports", async () => {
+    const id = await computeId(join(TMP, "lib", "thing.server.ts"), "suffixAction");
+    expect(resolveAction(id)).not.toBeNull();
+  });
+
+  test("ineligible path (lib/*.ts) does NOT register", async () => {
+    const id = await computeId(join(TMP, "lib", "helpers.ts"), "shouldNotLoad");
+    expect(resolveAction(id)).toBeNull();
+  });
+
+  test("'use server' inside template literal does NOT register", async () => {
+    const id = await computeId(join(TMP, "routes", "fake.tsx"), "notADirective");
+    expect(resolveAction(id)).toBeNull();
+  });
+});

package/src/__tests__/codegen.test.ts

@@ -0,0 +1,50 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { generateRouteTypes } from "../codegen/route-codegen.ts";
+
+let appDir = "";
+
+beforeAll(async () => {
+  appDir = join(tmpdir(), `bract-codegen-${Date.now()}`);
+  await mkdir(join(appDir, "routes"), { recursive: true });
+});
+
+afterAll(async () => {
+  await rm(appDir, { recursive: true, force: true });
+});
+
+describe("route-codegen — output shape", () => {
+  test("emits JSON-quoted keys for safe patterns", async () => {
+    const routesDir = join(appDir, "routes");
+    await writeFile(join(routesDir, "_index.tsx"), "export default () => null;");
+    await mkdir(join(routesDir, "users"), { recursive: true });
+    await writeFile(join(routesDir, "users", "[id].tsx"), "export default () => null;");
+
+    const out = await generateRouteTypes(appDir);
+    expect(out).toContain("\"/\":");
+    expect(out).toContain("\"/users/:id\":");
+    // The pattern key in the literal union must also be JSON-quoted.
+    expect(out).toMatch(/\| "\/users\/:id"/);
+  });
+
+  test("rejects hostile filenames at codegen time", async () => {
+    const hostileApp = join(tmpdir(), `bract-codegen-hostile-${Date.now()}`);
+    await mkdir(join(hostileApp, "routes"), { recursive: true });
+    // Try to plant a filename with a quote. macOS/Linux accept it; if the FS
+    // doesn't, we skip this assertion (FS already rejected the attack).
+    const hostileFile = join(hostileApp, "routes", `bad"name.tsx`);
+    let planted = false;
+    try {
+      await writeFile(hostileFile, "export default () => null;");
+      planted = await Bun.file(hostileFile).exists();
+    } catch {
+      planted = false;
+    }
+    if (planted) {
+      await expect(generateRouteTypes(hostileApp)).rejects.toThrow(/unsafe route pattern/);
+    }
+    await rm(hostileApp, { recursive: true, force: true });
+  });
+});

package/src/__tests__/deferred.test.ts

@@ -0,0 +1,96 @@
+import { test, expect, describe } from "bun:test";
+import { Deferred, defer, isDeferred, stripDeferred, promisesOf } from "../shared/deferred.ts";
+
+describe("Deferred", () => {
+  test("holds a promise", () => {
+    const p = Promise.resolve(42);
+    const d = new Deferred(p);
+    expect(d.promise).toBe(p);
+  });
+
+  test("isDeferred returns true for Deferred instances", () => {
+    expect(isDeferred(new Deferred(Promise.resolve()))).toBe(true);
+  });
+
+  test("isDeferred returns false for plain promises", () => {
+    expect(isDeferred(Promise.resolve())).toBe(false);
+  });
+
+  test("isDeferred returns false for non-objects", () => {
+    expect(isDeferred(null)).toBe(false);
+    expect(isDeferred(42)).toBe(false);
+    expect(isDeferred("string")).toBe(false);
+  });
+});
+
+describe("defer", () => {
+  test("wraps Promise values in Deferred", () => {
+    const result = defer({ data: Promise.resolve([1, 2, 3]) });
+    expect(isDeferred(result.data)).toBe(true);
+  });
+
+  test("passes through non-Promise values unchanged", () => {
+    const result = defer({ count: 5, label: "hello" });
+    expect(result.count).toBe(5);
+    expect(result.label).toBe("hello");
+    expect(isDeferred(result.count)).toBe(false);
+  });
+
+  test("mixed: some deferred, some immediate", () => {
+    const p = Promise.resolve("async-val");
+    const result = defer({ sync: "immediate", async: p });
+    expect(result.sync).toBe("immediate");
+    expect(isDeferred(result.async)).toBe(true);
+  });
+
+  test("empty object returns empty object", () => {
+    const result = defer({});
+    expect(Object.keys(result)).toHaveLength(0);
+  });
+});
+
+describe("stripDeferred", () => {
+  test("returns only non-deferred values", () => {
+    const input = defer({ a: 1, b: Promise.resolve(2) });
+    const stripped = stripDeferred(input as Record<string, unknown>);
+    expect(stripped).toHaveProperty("a", 1);
+    expect(stripped).not.toHaveProperty("b");
+  });
+
+  test("returns all values when nothing is deferred", () => {
+    const stripped = stripDeferred({ x: 10, y: "hello" });
+    expect(stripped).toEqual({ x: 10, y: "hello" });
+  });
+
+  test("returns empty object when everything is deferred", () => {
+    const input = defer({ a: Promise.resolve(1), b: Promise.resolve(2) });
+    const stripped = stripDeferred(input as Record<string, unknown>);
+    expect(Object.keys(stripped)).toHaveLength(0);
+  });
+});
+
+describe("promisesOf", () => {
+  test("returns only deferred values as their underlying promises", async () => {
+    const p = Promise.resolve(99);
+    const input = defer({ fast: "sync", slow: p });
+    const promises = promisesOf(input as Record<string, unknown>);
+    expect(Object.keys(promises)).toEqual(["slow"]);
+    const val = await promises.slow;
+    expect(val).toBe(99);
+  });
+
+  test("returns empty object when nothing is deferred", () => {
+    const result = promisesOf({ a: 1, b: "hello" });
+    expect(Object.keys(result)).toHaveLength(0);
+  });
+
+  test("each promise in result resolves to deferred value", async () => {
+    const input = defer({
+      x: Promise.resolve("alpha"),
+      y: Promise.resolve("beta"),
+    });
+    const promises = promisesOf(input as Record<string, unknown>);
+    expect(await promises.x).toBe("alpha");
+    expect(await promises.y).toBe("beta");
+  });
+});

package/src/__tests__/directives.test.ts

@@ -0,0 +1,52 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { useClientStubPlugin, useServerProxyPlugin } from "../build/directives.ts";
+
+let dir = "";
+
+beforeAll(async () => {
+  dir = join(tmpdir(), `bract-directives-${Date.now()}`);
+  await mkdir(dir, { recursive: true });
+});
+
+afterAll(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+async function runBundle(entry: string, plugin: typeof useClientStubPlugin): Promise<string> {
+  const out = await Bun.build({
+    entrypoints: [entry],
+    target: "browser",
+    minify: false,
+    plugins: [plugin],
+  });
+  if (!out.success) throw new Error(out.logs.join("\n"));
+  return await out.outputs[0].text();
+}
+
+describe("directives — BOM-prefixed 'use server'", () => {
+  test("BOM + 'use server' still detected → exports replaced with fetch proxy", async () => {
+    const file = join(dir, "bom-server.ts");
+    await writeFile(file, "\"use server\";\nexport async function ping(x) { return x; }\n");
+    const code = await runBundle(file, useServerProxyPlugin);
+    // The proxy helper is inlined when directive is detected.
+    expect(code).toContain("__bract");
+    expect(code).toContain("/_action?id=");
+  });
+
+  test("BOM + 'use client' detected → exports replaced with null stubs", async () => {
+    const file = join(dir, "bom-client.tsx");
+    await writeFile(file, "\"use client\";\nexport const Widget = () => null;\n");
+    const code = await runBundle(file, useClientStubPlugin);
+    expect(code).toMatch(/Widget\s*=\s*\(\)\s*=>\s*null/);
+  });
+
+  test("leading whitespace + 'use server' still detected", async () => {
+    const file = join(dir, "ws-server.ts");
+    await writeFile(file, "   \n\t\"use server\";\nexport async function pong() { return 1; }\n");
+    const code = await runBundle(file, useServerProxyPlugin);
+    expect(code).toContain("__bract");
+  });
+});

package/src/__tests__/env.test.ts

@@ -0,0 +1,73 @@
+import { test, expect, describe } from "bun:test";
+import { safeStringify, requireEnv } from "../server/env.ts";
+
+describe("safeStringify", () => {
+  test("serializes plain objects", () => {
+    const out = safeStringify({ a: 1, b: "hello" });
+    expect(JSON.parse(out)).toEqual({ a: 1, b: "hello" });
+  });
+
+  test("serializes arrays", () => {
+    const out = safeStringify([1, 2, 3]);
+    expect(JSON.parse(out)).toEqual([1, 2, 3]);
+  });
+
+  test("serializes null", () => {
+    expect(safeStringify(null)).toBe("null");
+  });
+
+  test("escapes < to \\u003c (XSS safe in <script> tags)", () => {
+    const out = safeStringify({ html: "<script>" });
+    expect(out).not.toContain("<");
+    expect(out).toContain("\\u003c");
+    expect(JSON.parse(out).html).toBe("<script>");
+  });
+
+  test("escapes > to \\u003e", () => {
+    const out = safeStringify({ html: "</script>" });
+    expect(out).not.toContain(">");
+    expect(out).toContain("\\u003e");
+  });
+
+  test("escapes & to \\u0026", () => {
+    const out = safeStringify({ val: "a&&b" });
+    expect(out).not.toContain("&&");
+    expect(out).toContain("\\u0026");
+    expect(JSON.parse(out).val).toBe("a&&b");
+  });
+
+  test("handles circular references with [Circular] sentinel", () => {
+    const obj: Record<string, unknown> = { name: "root" };
+    obj.self = obj;
+    const out = safeStringify(obj);
+    const parsed = JSON.parse(out) as { name: string; self: string };
+    expect(parsed.name).toBe("root");
+    expect(parsed.self).toBe("[Circular]");
+  });
+
+  test("handles nested objects", () => {
+    const out = safeStringify({ a: { b: { c: 42 } } });
+    expect(JSON.parse(out)).toEqual({ a: { b: { c: 42 } } });
+  });
+});
+
+describe("requireEnv", () => {
+  test("returns value when env var is set", () => {
+    Bun.env.TEST_VAR_BRACTJS = "hello";
+    expect(requireEnv("TEST_VAR_BRACTJS")).toBe("hello");
+    delete Bun.env.TEST_VAR_BRACTJS;
+  });
+
+  test("throws when env var is missing", () => {
+    delete Bun.env.DEFINITELY_NOT_SET_BRACTJS;
+    expect(() => requireEnv("DEFINITELY_NOT_SET_BRACTJS")).toThrow(
+      "Missing required environment variable: DEFINITELY_NOT_SET_BRACTJS",
+    );
+  });
+
+  test("throws when env var is empty string", () => {
+    Bun.env.EMPTY_VAR_BRACTJS = "";
+    expect(() => requireEnv("EMPTY_VAR_BRACTJS")).toThrow();
+    delete Bun.env.EMPTY_VAR_BRACTJS;
+  });
+});

package/src/__tests__/errors.test.ts

@@ -0,0 +1,113 @@
+import { test, expect, describe } from "bun:test";
+import {
+  BractJSError,
+  HttpError,
+  isRedirect,
+  isHttpError,
+  isBractJSError,
+} from "../shared/errors.ts";
+
+describe("BractJSError", () => {
+  test("sets name, message, and default status 500", () => {
+    const e = new BractJSError("something went wrong");
+    expect(e.name).toBe("BractJSError");
+    expect(e.message).toBe("something went wrong");
+    expect(e.status).toBe(500);
+    expect(e).toBeInstanceOf(Error);
+  });
+
+  test("accepts custom status", () => {
+    const e = new BractJSError("forbidden", 403);
+    expect(e.status).toBe(403);
+  });
+});
+
+describe("HttpError", () => {
+  test("derives message from known status codes", () => {
+    expect(new HttpError(400).message).toBe("Bad Request");
+    expect(new HttpError(401).message).toBe("Unauthorized");
+    expect(new HttpError(403).message).toBe("Forbidden");
+    expect(new HttpError(404).message).toBe("Not Found");
+    expect(new HttpError(405).message).toBe("Method Not Allowed");
+    expect(new HttpError(422).message).toBe("Unprocessable Entity");
+    expect(new HttpError(429).message).toBe("Too Many Requests");
+    expect(new HttpError(500).message).toBe("Internal Server Error");
+    expect(new HttpError(503).message).toBe("Service Unavailable");
+  });
+
+  test("falls back to generic message for unknown codes", () => {
+    expect(new HttpError(418).message).toBe("HTTP Error 418");
+  });
+
+  test("accepts explicit message override", () => {
+    const e = new HttpError(403, "Custom denied");
+    expect(e.message).toBe("Custom denied");
+    expect(e.status).toBe(403);
+  });
+
+  test("name is HttpError and inherits from BractJSError", () => {
+    const e = new HttpError(500);
+    expect(e.name).toBe("HttpError");
+    expect(e).toBeInstanceOf(BractJSError);
+    expect(e).toBeInstanceOf(Error);
+  });
+});
+
+describe("isRedirect", () => {
+  test("returns true for 3xx Response", () => {
+    expect(isRedirect(new Response(null, { status: 302, headers: { Location: "/" } }))).toBe(true);
+    expect(isRedirect(new Response(null, { status: 301, headers: { Location: "/new" } }))).toBe(true);
+    expect(isRedirect(new Response(null, { status: 307, headers: { Location: "/tmp" } }))).toBe(true);
+  });
+
+  test("returns false for non-3xx Response", () => {
+    expect(isRedirect(new Response(null, { status: 200 }))).toBe(false);
+    expect(isRedirect(new Response(null, { status: 404 }))).toBe(false);
+    expect(isRedirect(new Response(null, { status: 500 }))).toBe(false);
+  });
+
+  test("returns false for non-Response values", () => {
+    expect(isRedirect(null)).toBe(false);
+    expect(isRedirect(undefined)).toBe(false);
+    expect(isRedirect("https://example.com")).toBe(false);
+    expect(isRedirect({ status: 302 })).toBe(false);
+  });
+});
+
+describe("isHttpError", () => {
+  test("returns true for HttpError instances", () => {
+    expect(isHttpError(new HttpError(404))).toBe(true);
+  });
+
+  test("returns false for plain Error", () => {
+    expect(isHttpError(new Error("boom"))).toBe(false);
+  });
+
+  test("returns false for BractJSError (not HttpError)", () => {
+    expect(isHttpError(new BractJSError("oops"))).toBe(false);
+  });
+
+  test("returns false for non-errors", () => {
+    expect(isHttpError(null)).toBe(false);
+    expect(isHttpError(404)).toBe(false);
+  });
+});
+
+describe("isBractJSError", () => {
+  test("returns true for BractJSError", () => {
+    expect(isBractJSError(new BractJSError("x"))).toBe(true);
+  });
+
+  test("returns true for HttpError (subclass)", () => {
+    expect(isBractJSError(new HttpError(500))).toBe(true);
+  });
+
+  test("returns false for plain Error", () => {
+    expect(isBractJSError(new Error("plain"))).toBe(false);
+  });
+
+  test("returns false for non-errors", () => {
+    expect(isBractJSError(null)).toBe(false);
+    expect(isBractJSError("error")).toBe(false);
+  });
+});

package/src/__tests__/hash.test.ts

@@ -0,0 +1,19 @@
+import { test, expect } from "bun:test";
+import { hashString } from "../build/hash.ts";
+
+test("same content → same hash", async () => {
+  const a = await hashString("hello world");
+  const b = await hashString("hello world");
+  expect(a).toBe(b);
+});
+
+test("different content → different hash", async () => {
+  const a = await hashString("foo");
+  const b = await hashString("bar");
+  expect(a).not.toBe(b);
+});
+
+test("hash is 8 hex chars", async () => {
+  const h = await hashString("bractjs");
+  expect(h).toMatch(/^[0-9a-f]{8}$/);
+});

package/src/__tests__/integration.test.ts

@@ -37,7 +37,7 @@ test("GET /_data?path=/ returns JSON with route key", async () => {
 test("POST / runs action and returns 200 HTML", async () => {
   const form = new FormData();
   form.set("name", "bract");
-  const res = await fetch(`${BASE}/`, { method: "POST", body: form });
+  const res = await fetch(`${BASE}/`, { method: "POST", body: form, headers: { Origin: BASE } });
   expect(res.status).toBe(200);
   expect(res.headers.get("content-type")).toContain("text/html");
 });

package/src/__tests__/manifest.test.ts

@@ -0,0 +1,60 @@
+import { test, expect, describe } from "bun:test";
+import { generateManifest } from "../build/manifest.ts";
+
+describe("generateManifest", () => {
+  test("version is always 1", () => {
+    const m = generateManifest({ clientEntry: "/build/client.js", routeChunks: new Map() });
+    expect(m.version).toBe(1);
+  });
+
+  test("sets clientEntry field", () => {
+    const m = generateManifest({ clientEntry: "/build/client.abc123.js", routeChunks: new Map() });
+    expect(m.clientEntry).toBe("/build/client.abc123.js");
+  });
+
+  test("converts routeChunks map to routes object", () => {
+    const chunks = new Map([
+      ["", "/build/route-index.abc.js"],
+      ["about", "/build/route-about.def.js"],
+    ]);
+    const m = generateManifest({ clientEntry: "/build/client.js", routeChunks: chunks });
+    expect(m.routes[""]).toEqual({ chunk: "/build/route-index.abc.js", pattern: "" });
+    expect(m.routes["about"]).toEqual({ chunk: "/build/route-about.def.js", pattern: "about" });
+  });
+
+  test("empty routeChunks produces empty routes object", () => {
+    const m = generateManifest({ clientEntry: "/client.js", routeChunks: new Map() });
+    expect(Object.keys(m.routes)).toHaveLength(0);
+  });
+
+  test("sets optional rootChunk when provided", () => {
+    const m = generateManifest({
+      clientEntry: "/client.js",
+      rootChunk: "/build/root.chunk.js",
+      routeChunks: new Map(),
+    });
+    expect(m.rootChunk).toBe("/build/root.chunk.js");
+  });
+
+  test("rootChunk is undefined when not provided", () => {
+    const m = generateManifest({ clientEntry: "/client.js", routeChunks: new Map() });
+    expect(m.rootChunk).toBeUndefined();
+  });
+
+  test("each route entry has both chunk and pattern fields", () => {
+    const chunks = new Map([["blog/[id]", "/build/blog-id.chunk.js"]]);
+    const m = generateManifest({ clientEntry: "/client.js", routeChunks: chunks });
+    const entry = m.routes["blog/[id]"];
+    expect(entry.chunk).toBe("/build/blog-id.chunk.js");
+    expect(entry.pattern).toBe("blog/[id]");
+  });
+
+  test("handles many routes", () => {
+    const chunks = new Map(
+      Array.from({ length: 20 }, (_, i) => [`route/${i}`, `/build/chunk-${i}.js`])
+    );
+    const m = generateManifest({ clientEntry: "/client.js", routeChunks: chunks });
+    expect(Object.keys(m.routes)).toHaveLength(20);
+    expect(m.routes["route/10"].chunk).toBe("/build/chunk-10.js");
+  });
+});