@bractjs/bractjs 0.1.27 → 0.1.29

package/src/__tests__/route-lint.test.ts

@@ -0,0 +1,79 @@
+import { test, expect, describe } from "bun:test";
+import { lintRouteModuleSource } from "../build/route-lint.ts";
+
+describe("lintRouteModuleSource — empty routes", () => {
+  test("warns when a route has no meaningful export", () => {
+    const w = lintRouteModuleSource(`export const meta = () => [];\n`, "routes/empty.tsx");
+    expect(w.some((m) => /renders an empty page/.test(m))).toBe(true);
+  });
+
+  test("loader-only is fine (data route)", () => {
+    const w = lintRouteModuleSource(`export function loader() { return {}; }\n`, "routes/data.tsx");
+    expect(w).toEqual([]);
+  });
+
+  test("beforeLoad-only is fine (redirect/guard route)", () => {
+    const w = lintRouteModuleSource(`export function beforeLoad() {}\n`, "routes/guard.tsx");
+    expect(w).toEqual([]);
+  });
+
+  test("named default is fine", () => {
+    const w = lintRouteModuleSource(`export default function Page() { return null; }\n`, "routes/p.tsx");
+    expect(w).toEqual([]);
+  });
+
+  test("anonymous arrow default is recognized as a component", () => {
+    const w = lintRouteModuleSource(`export default () => null;\n`, "routes/anon.tsx");
+    expect(w).toEqual([]);
+  });
+
+  test("anonymous function default is recognized", () => {
+    const w = lintRouteModuleSource(`export default function () { return null; }\n`, "routes/anon2.tsx");
+    expect(w).toEqual([]);
+  });
+});
+
+describe("lintRouteModuleSource — miscased exports", () => {
+  test('"Loader" is flagged as a near-miss of "loader"', () => {
+    const w = lintRouteModuleSource(
+      `export default () => null;\nexport function Loader() { return {}; }\n`,
+      "routes/x.tsx",
+    );
+    expect(w.some((m) => /"Loader" looks like "loader"/.test(m))).toBe(true);
+  });
+
+  test('"fallback" → "Fallback", "beforeload" → "beforeLoad"', () => {
+    const w = lintRouteModuleSource(
+      `export default () => null;\n` +
+        `export const fallback = () => null;\n` +
+        `export function beforeload() {}\n`,
+      "routes/y.tsx",
+    );
+    expect(w.some((m) => /"fallback" looks like "Fallback"/.test(m))).toBe(true);
+    expect(w.some((m) => /"beforeload" looks like "beforeLoad"/.test(m))).toBe(true);
+  });
+
+  test("exact canonical names produce no near-miss warnings", () => {
+    const src =
+      `export default () => null;\n` +
+      `export function loader() { return {}; }\n` +
+      `export function action() { return {}; }\n` +
+      `export const clientLoader = () => ({});\n` +
+      `export const clientAction = () => ({});\n` +
+      `export function headers() { return {}; }\n` +
+      `export const middleware = [];\n` +
+      `export const handle = {};\n` +
+      `export const searchSchema = {};\n` +
+      `export function Fallback() { return null; }\n` +
+      `export const ssr = false;\n`;
+    expect(lintRouteModuleSource(src, "routes/z.tsx")).toEqual([]);
+  });
+
+  test("unrelated exports are not flagged", () => {
+    const w = lintRouteModuleSource(
+      `export default () => null;\nexport const helper = 1;\nexport type Foo = string;\n`,
+      "routes/h.tsx",
+    );
+    expect(w).toEqual([]);
+  });
+});

package/src/__tests__/route-middleware.test.ts

@@ -0,0 +1,84 @@
+import { test, expect, describe } from "bun:test";
+import {
+  runRouteMiddleware,
+  collectRouteMiddleware,
+  type RouteMiddleware,
+} from "../server/middleware.ts";
+import type { MiddlewareContext } from "../server/middleware.ts";
+
+function makeCtx(): MiddlewareContext {
+  return { request: new Request("http://localhost/"), params: {}, context: {} };
+}
+
+const ok = async () => new Response("ok", { status: 200 });
+
+describe("collectRouteMiddleware", () => {
+  test("orders root → layouts → route and flattens arrays", () => {
+    const order: string[] = [];
+    const mk = (label: string): RouteMiddleware => async (_c, n) => { order.push(label); return n(); };
+    const chain = {
+      root: { middleware: mk("root") },
+      layouts: [{ middleware: [mk("l0a"), mk("l0b")] }, { middleware: mk("l1") }],
+      route: { middleware: mk("route") },
+    };
+    const fns = collectRouteMiddleware(chain);
+    expect(fns).toHaveLength(5);
+    return runRouteMiddleware(fns, makeCtx(), ok).then(() => {
+      expect(order).toEqual(["root", "l0a", "l0b", "l1", "route"]);
+    });
+  });
+
+  test("ignores modules without middleware and non-function entries", () => {
+    const chain = {
+      root: {},
+      layouts: [{ middleware: undefined }, { middleware: ["nope" as unknown] }],
+      route: { middleware: (async (_c: MiddlewareContext, n: () => Promise<Response>) => n()) },
+    };
+    expect(collectRouteMiddleware(chain)).toHaveLength(1);
+  });
+});
+
+describe("runRouteMiddleware", () => {
+  test("empty list calls handler directly", async () => {
+    const res = await runRouteMiddleware([], makeCtx(), ok);
+    expect(res.status).toBe(200);
+  });
+
+  test("a middleware can short-circuit by not calling next()", async () => {
+    let handlerRan = false;
+    const gate: RouteMiddleware = async () => new Response("denied", { status: 403 });
+    const res = await runRouteMiddleware([gate], makeCtx(), async () => {
+      handlerRan = true;
+      return ok();
+    });
+    expect(res.status).toBe(403);
+    expect(handlerRan).toBe(false);
+  });
+
+  test("shares a mutable context across the chain and into the handler", async () => {
+    const ctx = makeCtx();
+    const setUser: RouteMiddleware = async (c, n) => { c.context.user = "alice"; return n(); };
+    let seenInHandler: unknown;
+    await runRouteMiddleware([setUser], ctx, async () => {
+      seenInHandler = ctx.context.user;
+      return ok();
+    });
+    expect(seenInHandler).toBe("alice");
+  });
+
+  test("rejects if a middleware calls next() twice", async () => {
+    const bad: RouteMiddleware = async (_c, n) => { await n(); return n(); };
+    await expect(runRouteMiddleware([bad], makeCtx(), ok)).rejects.toThrow(/more than once/);
+  });
+
+  test("outer middleware can post-process the inner Response", async () => {
+    const stamp: RouteMiddleware = async (_c, n) => {
+      const res = await n();
+      const out = new Response(res.body, res);
+      out.headers.set("X-Stamped", "1");
+      return out;
+    };
+    const res = await runRouteMiddleware([stamp], makeCtx(), ok);
+    expect(res.headers.get("X-Stamped")).toBe("1");
+  });
+});

package/src/__tests__/route-table.test.ts

@@ -0,0 +1,33 @@
+import { test, expect, describe } from "bun:test";
+import { formatRouteTable } from "../dev/route-table.ts";
+
+describe("formatRouteTable", () => {
+  test("empty → a clear no-routes line", () => {
+    expect(formatRouteTable([])).toBe("[bractjs] no routes found under routes/");
+  });
+
+  test("lists routes sorted by pattern with loader/action markers", () => {
+    const out = formatRouteTable([
+      { pattern: "/blog/:id", file: "routes/blog/[id].tsx", hasLoader: true, hasAction: true },
+      { pattern: "/", file: "routes/_index.tsx", hasLoader: true, hasAction: false },
+    ]);
+    // Header reports the count.
+    expect(out).toContain("[bractjs] 2 routes:");
+    // Sorted: "/" before "/blog/:id".
+    expect(out.indexOf("routes/_index.tsx")).toBeLessThan(out.indexOf("routes/blog/[id].tsx"));
+    // Markers present.
+    expect(out).toContain("loader");
+    expect(out).toContain("action");
+    // The index route shows loader but not action.
+    const indexLine = out.split("\n").find((l) => l.includes("_index"))!;
+    expect(indexLine).toContain("loader");
+    expect(indexLine).not.toContain("action");
+  });
+
+  test("singular wording for one route", () => {
+    const out = formatRouteTable([
+      { pattern: "/", file: "routes/_index.tsx", hasLoader: false, hasAction: false },
+    ]);
+    expect(out).toContain("1 route:");
+  });
+});

package/src/__tests__/safe-validate.test.ts

@@ -0,0 +1,96 @@
+import { test, expect, describe } from "bun:test";
+import {
+  safeValidate,
+  isValidationResponse,
+  readValidationError,
+  type Schema,
+} from "../server/validate.ts";
+
+// A Zod/Valibot-style safeParse schema: requires non-empty `title`.
+const TitleSchema: Schema<{ title: string }> = {
+  safeParse(input: unknown) {
+    const raw = (input as { title?: unknown })?.title;
+    const title = typeof raw === "string" ? raw.trim() : "";
+    if (!title) {
+      return { success: false, error: { issues: [{ path: ["title"], message: "Title is required." }] } };
+    }
+    return { success: true, data: { title } };
+  },
+};
+
+// A `.parse()`-only schema that throws.
+const ThrowingSchema: Schema<{ n: number }> = {
+  parse(input: unknown) {
+    const n = Number((input as { n?: unknown })?.n);
+    if (!Number.isFinite(n)) throw new Error("n must be a number");
+    return { n };
+  },
+};
+
+describe("safeValidate", () => {
+  test("ok path returns parsed data", async () => {
+    const r = await safeValidate(TitleSchema, { title: "  hi  " });
+    expect(r).toEqual({ ok: true, data: { title: "hi" } });
+  });
+
+  test("safeParse failure → fieldErrors + firstError", async () => {
+    const r = await safeValidate(TitleSchema, { title: "" });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.fieldErrors).toEqual({ title: ["Title is required."] });
+      expect(r.firstError).toBe("Title is required.");
+    }
+  });
+
+  test("parse-throw failure → _ field + message", async () => {
+    const r = await safeValidate(ThrowingSchema, { n: "abc" });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.fieldErrors._).toEqual(["n must be a number"]);
+      expect(r.firstError).toBe("n must be a number");
+    }
+  });
+
+  test("works with FormData input", async () => {
+    const fd = new FormData();
+    fd.set("title", "from form");
+    const r = await safeValidate(TitleSchema, fd);
+    expect(r).toEqual({ ok: true, data: { title: "from form" } });
+  });
+});
+
+describe("isValidationResponse", () => {
+  test("true for the Response thrown by validation", async () => {
+    // safeValidate swallows it, so trigger the throw via the underlying runSchema path:
+    let thrown: unknown;
+    try {
+      const { validate } = await import("../server/validate.ts");
+      await validate(TitleSchema, { title: "" });
+    } catch (e) {
+      thrown = e;
+    }
+    expect(isValidationResponse(thrown)).toBe(true);
+  });
+
+  test("false for a plain 400 Response without the validation statusText", () => {
+    expect(isValidationResponse(new Response(null, { status: 400 }))).toBe(false);
+    expect(isValidationResponse(new Error("nope"))).toBe(false);
+    expect(isValidationResponse(null)).toBe(false);
+  });
+});
+
+describe("readValidationError", () => {
+  test("parses { errors } body", async () => {
+    const res = Response.json({ errors: { email: ["Invalid"] } }, { status: 400 });
+    const { fieldErrors, firstError } = await readValidationError(res);
+    expect(fieldErrors).toEqual({ email: ["Invalid"] });
+    expect(firstError).toBe("Invalid");
+  });
+
+  test("falls back gracefully on non-JSON body", async () => {
+    const res = new Response("not json", { status: 400 });
+    const { fieldErrors, firstError } = await readValidationError(res);
+    expect(fieldErrors).toEqual({});
+    expect(firstError).toBe("Please check your input.");
+  });
+});

package/src/__tests__/scanner.test.ts

@@ -1,5 +1,10 @@
 import { test, expect, describe } from "bun:test";
-import { filePathToPattern, pathToSegments } from "../server/scanner.ts";
+import {
+  filePathToPattern,
+  pathToSegments,
+  layoutDirsFromFilePath,
+  isRouteGroupSegment,
+} from "../server/scanner.ts";
 
 describe("filePathToPattern", () => {
   test("_index maps to empty pattern (root index)", () => {
@@ -25,6 +30,42 @@ describe("filePathToPattern", () => {
   test("strips .ts extension too", () => {
     expect(filePathToPattern("routes/api/data.ts")).toBe("api/data");
   });
+
+  test("route group folder adds no URL segment", () => {
+    expect(filePathToPattern("routes/(marketing)/about.tsx")).toBe("about");
+  });
+
+  test("nested route group strips only the group segment", () => {
+    expect(filePathToPattern("routes/(marketing)/blog/[id].tsx")).toBe("blog/[id]");
+  });
+
+  test("group wrapping the index → root pattern", () => {
+    expect(filePathToPattern("routes/(marketing)/_index.tsx")).toBe("");
+  });
+
+  test("[[id]] optional kept in pattern string", () => {
+    expect(filePathToPattern("routes/users/[[id]].tsx")).toBe("users/[[id]]");
+  });
+});
+
+describe("route groups", () => {
+  test("isRouteGroupSegment detects (group) but not () or plain", () => {
+    expect(isRouteGroupSegment("(marketing)")).toBe(true);
+    expect(isRouteGroupSegment("()")).toBe(false);
+    expect(isRouteGroupSegment("about")).toBe(false);
+    expect(isRouteGroupSegment("[id]")).toBe(false);
+  });
+
+  test("layoutDirsFromFilePath includes group folders", () => {
+    expect(layoutDirsFromFilePath("routes/(marketing)/blog/[id].tsx")).toEqual([
+      "(marketing)",
+      "(marketing)/blog",
+    ]);
+  });
+
+  test("layoutDirsFromFilePath for a top-level route → empty", () => {
+    expect(layoutDirsFromFilePath("routes/about.tsx")).toEqual([]);
+  });
 });
 
 describe("pathToSegments", () => {
@@ -44,6 +85,10 @@ describe("pathToSegments", () => {
     expect(pathToSegments("docs/[...slug]")).toEqual(["docs", { catchAll: "slug" }]);
   });
 
+  test("[[id]] → optional segment", () => {
+    expect(pathToSegments("users/[[id]]")).toEqual(["users", { optional: "id" }]);
+  });
+
   test("nested static path", () => {
     expect(pathToSegments("a/b/c")).toEqual(["a", "b", "c"]);
   });

package/src/__tests__/scroll-restoration.test.ts

@@ -0,0 +1,66 @@
+import { test, expect, describe } from "bun:test";
+import {
+  savePosition,
+  serializePositions,
+  deserializePositions,
+  MAX_SCROLL_ENTRIES,
+} from "../client/scroll-restoration.ts";
+
+describe("savePosition", () => {
+  test("stores and overwrites a key", () => {
+    const map = new Map<string, number>();
+    savePosition(map, "a", 100);
+    savePosition(map, "a", 250);
+    expect(map.get("a")).toBe(250);
+    expect(map.size).toBe(1);
+  });
+
+  test("evicts the oldest entries past the cap", () => {
+    const map = new Map<string, number>();
+    for (let i = 0; i < 5; i++) savePosition(map, `k${i}`, i, 3);
+    expect(map.size).toBe(3);
+    expect(map.has("k0")).toBe(false);
+    expect(map.has("k1")).toBe(false);
+    expect(map.get("k4")).toBe(4);
+  });
+
+  test("re-saving refreshes LRU order", () => {
+    const map = new Map<string, number>();
+    savePosition(map, "a", 1, 2);
+    savePosition(map, "b", 2, 2);
+    savePosition(map, "a", 10, 2); // refresh "a" → "b" is now oldest
+    savePosition(map, "c", 3, 2);
+    expect(map.has("b")).toBe(false);
+    expect(map.get("a")).toBe(10);
+    expect(map.get("c")).toBe(3);
+  });
+
+  test("default cap is applied", () => {
+    const map = new Map<string, number>();
+    for (let i = 0; i < MAX_SCROLL_ENTRIES + 10; i++) savePosition(map, `k${i}`, i);
+    expect(map.size).toBe(MAX_SCROLL_ENTRIES);
+  });
+});
+
+describe("serialize/deserialize", () => {
+  test("roundtrips entries", () => {
+    const map = new Map<string, number>([["a", 0], ["b", 1234.5]]);
+    const restored = deserializePositions(serializePositions(map));
+    expect(restored.get("a")).toBe(0);
+    expect(restored.get("b")).toBe(1234.5);
+    expect(restored.size).toBe(2);
+  });
+
+  test("null/malformed/foreign payloads yield an empty map", () => {
+    expect(deserializePositions(null).size).toBe(0);
+    expect(deserializePositions("not json{").size).toBe(0);
+    expect(deserializePositions('"a string"').size).toBe(0);
+    expect(deserializePositions("[1,2,3]").size).toBe(0);
+  });
+
+  test("non-numeric values are dropped", () => {
+    const restored = deserializePositions('{"a": 10, "b": "nope", "c": null, "d": 1e999}');
+    expect(restored.get("a")).toBe(10);
+    expect(restored.size).toBe(1); // "d" is Infinity after JSON.parse → dropped
+  });
+});

package/src/__tests__/search-serializer.test.ts

@@ -0,0 +1,42 @@
+import { test, expect, describe } from "bun:test";
+import { serializeSearch, withSearch } from "../client/search-serializer.ts";
+
+describe("serializeSearch", () => {
+  test("primitives stringify", () => {
+    expect(serializeSearch({ page: 2, q: "hi", on: true })).toBe("?page=2&q=hi&on=true");
+  });
+
+  test("undefined/null drop the key", () => {
+    expect(serializeSearch({ a: 1, b: undefined, c: null })).toBe("?a=1");
+  });
+
+  test("arrays become repeated keys (inverse of searchParamsToObject)", () => {
+    expect(serializeSearch({ tag: ["a", "b"] })).toBe("?tag=a&tag=b");
+  });
+
+  test("nested objects JSON-stringify", () => {
+    expect(serializeSearch({ f: { x: 1 } })).toBe("?f=" + encodeURIComponent('{"x":1}'));
+  });
+
+  test("empty object → empty string", () => {
+    expect(serializeSearch({})).toBe("");
+  });
+
+  test("values are URL-encoded", () => {
+    expect(serializeSearch({ q: "a b&c" })).toBe("?q=a+b%26c");
+  });
+});
+
+describe("withSearch", () => {
+  test("appends search to a bare path", () => {
+    expect(withSearch("/posts", { page: 2 })).toBe("/posts?page=2");
+  });
+
+  test("replaces an existing query, preserves the hash", () => {
+    expect(withSearch("/posts?old=1#top", { page: 2 })).toBe("/posts?page=2#top");
+  });
+
+  test("no search → path untouched", () => {
+    expect(withSearch("/posts?old=1")).toBe("/posts?old=1");
+  });
+});

package/src/__tests__/search-validation.test.ts

@@ -0,0 +1,125 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { resolve } from "node:path";
+import { searchParamsToObject, validateSearch } from "../server/search.ts";
+import { createServer } from "../server/serve.ts";
+
+// ── Unit: searchParamsToObject ──────────────────────────────────────────────
+
+describe("searchParamsToObject", () => {
+  test("single values stay strings", () => {
+    expect(searchParamsToObject(new URLSearchParams("a=1&b=x"))).toEqual({ a: "1", b: "x" });
+  });
+
+  test("repeated keys collapse into arrays", () => {
+    expect(searchParamsToObject(new URLSearchParams("tag=a&tag=b&tag=c"))).toEqual({
+      tag: ["a", "b", "c"],
+    });
+  });
+
+  test("empty params → empty object", () => {
+    expect(searchParamsToObject(new URLSearchParams(""))).toEqual({});
+  });
+});
+
+// ── Unit: validateSearch ────────────────────────────────────────────────────
+
+const coercingSchema = {
+  safeParse(input: unknown) {
+    const obj = input as Record<string, unknown>;
+    const n = Number(obj.page ?? 1);
+    if (!Number.isInteger(n)) {
+      return { success: false, error: { issues: [{ path: ["page"], message: "not an int" }] } };
+    }
+    return { success: true, data: { page: n } };
+  },
+};
+
+describe("validateSearch", () => {
+  test("no schema → raw string record (back-compat)", async () => {
+    const url = new URL("http://x.test/posts?page=2&tag=a&tag=b");
+    expect(await validateSearch(undefined, url)).toEqual({ page: "2", tag: ["a", "b"] });
+  });
+
+  test("schema output replaces raw strings (coercion)", async () => {
+    const url = new URL("http://x.test/posts?page=7");
+    expect(await validateSearch(coercingSchema, url)).toEqual({ page: 7 });
+  });
+
+  test("schema failure throws a 400 Response with field errors", async () => {
+    const url = new URL("http://x.test/posts?page=abc");
+    try {
+      await validateSearch(coercingSchema, url);
+      expect.unreachable("validateSearch should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(Response);
+      const res = err as Response;
+      expect(res.status).toBe(400);
+      const body = (await res.json()) as { errors: Record<string, string[]> };
+      expect(body.errors.page).toEqual(["not an int"]);
+    }
+  });
+});
+
+// ── Integration: live server with a searchSchema route ─────────────────────
+
+const PORT = 3996;
+const BASE = `http://localhost:${PORT}`;
+const FIXTURE_APP = resolve(import.meta.dir, "fixtures/app");
+
+let handle: ReturnType<typeof createServer>;
+
+beforeAll(() => {
+  handle = createServer({
+    port: PORT,
+    appDir: FIXTURE_APP,
+    manifest: { clientEntry: "/build/client/client.js", routes: {} },
+  });
+});
+
+afterAll(() => {
+  handle.stop();
+});
+
+describe("searchSchema end-to-end", () => {
+  test("/_data returns the validated+coerced search object and loaders receive it", async () => {
+    const res = await fetch(`${BASE}/_data?path=${encodeURIComponent("/search-demo?page=3&tag=x")}`);
+    expect(res.status).toBe(200);
+    const data = (await res.json()) as {
+      search: Record<string, unknown>;
+      route: { receivedSearch: Record<string, unknown> };
+    };
+    expect(data.search).toEqual({ page: 3, tag: ["x"] });
+    expect(data.route.receivedSearch).toEqual({ page: 3, tag: ["x"] });
+  });
+
+  test("/_data applies schema defaults when params are absent", async () => {
+    const res = await fetch(`${BASE}/_data?path=${encodeURIComponent("/search-demo")}`);
+    const data = (await res.json()) as { search: Record<string, unknown> };
+    expect(data.search).toEqual({ page: 1 });
+  });
+
+  test("/_data with invalid search → 400 with field errors, loader never runs", async () => {
+    const res = await fetch(`${BASE}/_data?path=${encodeURIComponent("/search-demo?page=abc")}`);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { errors: Record<string, string[]> };
+    expect(body.errors.page).toBeDefined();
+  });
+
+  test("document GET with invalid search → 400", async () => {
+    const res = await fetch(`${BASE}/search-demo?page=abc`);
+    expect(res.status).toBe(400);
+  });
+
+  test("document GET hydrates the validated search into __BRACTJS_DATA__", async () => {
+    const res = await fetch(`${BASE}/search-demo?page=5`);
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain('"search":{"page":5}');
+  });
+
+  test("routes without a schema still get the raw string record", async () => {
+    const res = await fetch(`${BASE}/_data?path=${encodeURIComponent("/?q=hello")}`);
+    const data = (await res.json()) as { search: Record<string, unknown> };
+    expect(data.search).toEqual({ q: "hello" });
+  });
+});