@tschk/moonshine-framework 0.3.7 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tschk/moonshine-framework",
-  "version": "0.3.7",
+  "version": "0.4.1",
   "license": "ISC",
   "type": "module",
   "main": "./src/index.ts",
@@ -15,7 +15,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@tschk/moonshine": "^0.3.6"
+    "@tschk/moonshine": "^0.4.1"
   },
   "devDependencies": {
     "@types/bun": "1.3.14",

package/src/adapter.ts

@@ -8,6 +8,27 @@ export type DeploymentAdapter = {
   build(manifest: MoonshineManifest, outDir: string): Promise<void>;
 };
 
+/**
+ * A running instance of an adapter, used to exercise it end to end.
+ *
+ * This lives here rather than in the conformance suite because every deploy
+ * package exports a harness as part of its public API (`nodeHarness`,
+ * `bunHarness`, ...). With the type owned by the test suite, each of those
+ * packages had to declare the suite — fixtures and all — as a production
+ * `dependency` purely to name a type, so installing an adapter installed its
+ * own test tooling. The suite still owns the tests; the framework owns the
+ * shape the adapters implement.
+ */
+export type Harness = {
+  start(): Promise<URL>;
+  stop(): Promise<void>;
+};
+
+export type HarnessFactory = (
+  fetch: (request: Request) => Promise<Response>,
+  options: { manifest: MoonshineManifest; staticDir: string },
+) => Harness;
+
 export function defineRoute<T extends RouteDefinition>(route: T): T {
   return route;
 }

package/src/index.ts

@@ -3,3 +3,4 @@ export * from "./config";
 export * from "./manifest";
 export * from "./renderer";
 export * from "./routes";
+export * from "./serialize";

package/src/serialize.ts

@@ -0,0 +1,108 @@
+const ESCAPE_PATTERN = /[<>&\u2028\u2029]/g;
+
+function escapeJsonChar(char: string): string {
+  return `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`;
+}
+
+/**
+ * HTML-safe JSON for anything embedded in a document: server loader data and
+ * island props both land inside `<script>`, so one implementation escapes for
+ * both. Two copies drift, and a copy that misses an escape vector is an XSS.
+ */
+export function serializeData(value: unknown): string {
+  // Ancestor chain, not a visited set: a value repeated in sibling positions
+  // is shared, not cyclic, and must still serialize.
+  const ancestors = new Set<unknown>();
+
+  function visit(v: unknown): string {
+    if (v === undefined || v === null) return "null";
+
+    const type = typeof v;
+
+    if (type === "boolean" || type === "number") {
+      if (Number.isNaN(v as number) || !Number.isFinite(v as number)) {
+        return "null";
+      }
+      return String(v);
+    }
+
+    if (type === "string") {
+      const raw = JSON.stringify(v);
+      if (raw === undefined)
+        throw new TypeError("serializeData: cannot serialize");
+      return raw;
+    }
+
+    if (type === "bigint" || type === "function" || type === "symbol") {
+      throw new TypeError(`serializeData: cannot serialize ${type}`);
+    }
+
+    if (ancestors.has(v))
+      throw new TypeError("serializeData: cyclic reference");
+
+    if (Array.isArray(v)) {
+      ancestors.add(v);
+      try {
+        const parts: string[] = [];
+        for (const item of v) {
+          parts.push(visit(item));
+        }
+        return `[${parts.join(",")}]`;
+      } finally {
+        ancestors.delete(v);
+      }
+    }
+
+    const proto = Object.prototype.toString.call(v);
+
+    if (proto === "[object Date]" || proto === "[object RegExp]") {
+      ancestors.add(v);
+      try {
+        const raw = JSON.stringify(v);
+        if (raw === undefined)
+          throw new TypeError("serializeData: cannot serialize");
+        return raw;
+      } finally {
+        ancestors.delete(v);
+      }
+    }
+
+    // JSON.stringify skips symbol keys silently. A prop the server drops but
+    // the client expects is a hydration mismatch, so refuse the value instead.
+    const symbols = Object.getOwnPropertySymbols(v);
+    if (symbols.length) {
+      throw new TypeError("serializeData: cannot serialize symbol");
+    }
+
+    ancestors.add(v);
+    try {
+      const parts: string[] = [];
+      const keys = Object.keys(v as Record<string, unknown>);
+      for (const key of keys) {
+        let val = undefined;
+        try {
+          val = (v as Record<string, unknown>)[key];
+        } catch {
+          // Throwing getter -> undefined
+          val = undefined;
+        }
+
+        if (typeof val === "function" || typeof val === "symbol") {
+          throw new TypeError(
+            "serializeData: cannot serialize function/symbol",
+          );
+        }
+        // An undefined property is absent, not null: JSON semantics, and what
+        // the client's own JSON.parse round-trip would produce.
+        if (val === undefined) continue;
+        parts.push(`${visit(key)}:${visit(val)}`);
+      }
+      return `{${parts.join(",")}}`;
+    } finally {
+      ancestors.delete(v);
+    }
+  }
+
+  const raw = visit(value);
+  return raw.replace(ESCAPE_PATTERN, escapeJsonChar);
+}

package/test/adapter.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import { defineRoute } from "../src/adapter";
+import type { RouteDefinition } from "../src/routes";
+
+describe("defineRoute", () => {
+  test("returns the exact route definition provided", () => {
+    const route: RouteDefinition = {
+      id: "test-route",
+      path: "/test",
+      file: "test.tsx",
+      mode: "ssr",
+      runtime: "bun",
+    };
+
+    const result = defineRoute(route);
+
+    expect(result).toBe(route);
+    expect(result).toEqual({
+      id: "test-route",
+      path: "/test",
+      file: "test.tsx",
+      mode: "ssr",
+      runtime: "bun",
+    });
+  });
+});

package/test/config.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { defineConfig, type MoonshineConfig } from "../src/config";
+
+describe("defineConfig", () => {
+  test("returns the exact same object reference", () => {
+    const config: MoonshineConfig = {};
+    const result = defineConfig(config);
+    expect(result).toBe(config);
+  });
+
+  test("handles empty configuration", () => {
+    const result = defineConfig({});
+    expect(result).toEqual({});
+  });
+
+  test("handles configuration with mode", () => {
+    const result = defineConfig({ mode: "island" });
+    expect(result).toEqual({ mode: "island" });
+  });
+
+  test("handles configuration with runtime", () => {
+    const result = defineConfig({ runtime: "bun" });
+    expect(result).toEqual({ runtime: "bun" });
+  });
+
+  test("handles full configuration", () => {
+    const config = {
+      mode: "ssr" as const,
+      runtime: "cloudflare" as const,
+    };
+    const result = defineConfig(config);
+    expect(result).toEqual(config);
+  });
+
+  test("preserves additional properties (type safety with generic T)", () => {
+    const config = {
+      mode: "spa" as const,
+      customPlugin: true,
+    };
+    const result = defineConfig(config);
+    expect(result).toEqual(config);
+    // TypeScript check: result.customPlugin should exist
+    expect(result.customPlugin).toBe(true);
+  });
+});

package/test/serialize.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import { serializeData } from "../src/serialize";
+
+// The single HTML-safe JSON serializer: the server data payload and the island
+// props script are the same XSS-prevention primitive, so they share this one
+// implementation rather than drifting apart in two packages.
+describe("serializeData", () => {
+  test("escapes <, >, &, U+2028, and U+2029", () => {
+    const out = serializeData({
+      html: "<script>alert('&

')</script>",
+    });
+    expect(out).not.toContain("<");
+    expect(out).not.toContain(">");
+    expect(out).not.toContain("&");
+    expect(out).not.toContain("
");
+    expect(out).not.toContain("
");
+    expect(out).toContain("\\u003c");
+    expect(out).toContain("\\u003e");
+    expect(out).toContain("\\u0026");
+    expect(out).toContain("\\u2028");
+    expect(out).toContain("\\u2029");
+  });
+
+  test("omits undefined properties instead of nulling them", () => {
+    expect(serializeData({ a: 1, b: undefined })).toBe('{"a":1}');
+    expect(serializeData([1, undefined])).toBe("[1,null]");
+  });
+
+  test("rejects symbol-keyed properties rather than dropping them", () => {
+    expect(() => serializeData({ [Symbol("k")]: 1 })).toThrow(/symbol/);
+  });
+
+  test("serializes NaN and Infinity as null", () => {
+    expect(serializeData({ a: NaN, b: Infinity, c: -Infinity })).toBe(
+      '{"a":null,"b":null,"c":null}',
+    );
+  });
+
+  test("allows shared references and rejects only true cycles", () => {
+    const shared = { id: 1 };
+    expect(serializeData({ a: shared, b: shared })).toBe(
+      '{"a":{"id":1},"b":{"id":1}}',
+    );
+    expect(serializeData([shared, shared])).toBe('[{"id":1},{"id":1}]');
+
+    const cyclic: Record<string, unknown> = {};
+    cyclic.self = cyclic;
+    expect(() => serializeData(cyclic)).toThrow(/cyclic/);
+
+    const arr: unknown[] = [];
+    arr.push(arr);
+    expect(() => serializeData(arr)).toThrow(/cyclic/);
+  });
+
+  test("rejects functions, symbols, and bigints", () => {
+    expect(() => serializeData({ f: () => 1 })).toThrow(/function/);
+    expect(() => serializeData({ s: Symbol("x") })).toThrow(/symbol/);
+    expect(() => serializeData({ n: 1n })).toThrow(/bigint/);
+  });
+
+  test("omits properties with throwing getters", () => {
+    const obj = {
+      get thrower() {
+        throw new Error("Getter threw!");
+      },
+    };
+    expect(serializeData(obj)).toBe("{}");
+  });
+});