oyvindberg · oyvindberg · Mar 30, 2026 · Mar 29, 2026 · Mar 29, 2026 · Mar 29, 2026
diff --git a/bench/.gitignore b/bench/.gitignore
@@ -0,0 +1,2 @@
+node_modules/
+dist/
diff --git a/bench/index.html b/bench/index.html
@@ -0,0 +1,81 @@
+<!doctype html>
+<html>
+    <head>
+        <meta charset="utf-8" />
+        <title>use-remote-data benchmark</title>
+        <style>
+            * {
+                box-sizing: border-box;
+                margin: 0;
+                padding: 0;
+            }
+            body {
+                font-family: ui-monospace, monospace;
+                padding: 24px;
+                background: #111;
+                color: #eee;
+            }
+            h1 {
+                font-size: 18px;
+                margin-bottom: 16px;
+            }
+            #app {
+                max-width: 900px;
+            }
+            table {
+                border-collapse: collapse;
+                width: 100%;
+                margin: 16px 0;
+            }
+            th,
+            td {
+                padding: 6px 12px;
+                text-align: right;
+                border: 1px solid #333;
+            }
+            th {
+                background: #222;
+                text-align: left;
+            }
+            td:first-child {
+                text-align: left;
+            }
+            .running {
+                color: #ff0;
+            }
+            .done {
+                color: #0f0;
+            }
+            button {
+                font-family: inherit;
+                font-size: 14px;
+                padding: 8px 16px;
+                margin: 8px 4px;
+                cursor: pointer;
+                background: #333;
+                color: #eee;
+                border: 1px solid #555;
+            }
+            button:hover {
+                background: #444;
+            }
+            button:disabled {
+                opacity: 0.4;
+                cursor: not-allowed;
+            }
+            .hidden {
+                display: none;
+            }
+            #stage {
+                position: fixed;
+                top: -9999px;
+                left: -9999px;
+            }
+        </style>
+    </head>
+    <body>
+        <div id="app"></div>
+        <div id="stage"></div>
+        <script type="module" src="/src/main.tsx"></script>
+    </body>
+</html>
diff --git a/bench/package.json b/bench/package.json
@@ -0,0 +1,22 @@
+{
+    "name": "use-remote-data-bench",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build"
+    },
+    "dependencies": {
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0",
+        "@tanstack/react-query": "^5.0.0",
+        "use-remote-data": "file:.."
+    },
+    "devDependencies": {
+        "@types/react": "^19.0.10",
+        "@types/react-dom": "^19.0.4",
+        "@vitejs/plugin-react": "^4.3.0",
+        "typescript": "^5.7.3",
+        "vite": "^6.0.0"
+    }
+}
diff --git a/bench/src/harness.tsx b/bench/src/harness.tsx
@@ -0,0 +1,207 @@
+/**
+ * Benchmark harness. Renders N components offscreen, measures timings,
+ * reports results. Each scenario gets the same treatment.
+ */
+import React, { useState } from 'react';
+import { createRoot } from 'react-dom/client';
+
+/**
+ * Each scenario provides a single component that renders `n` items.
+ * The component receives `n` and `uniqueKeys` and must render
+ * a `<span data-resolved>` for each item once its data arrives.
+ * This lets each library use its natural pattern — per-component hooks,
+ * parent-owned maps, or whatever fits.
+ */
+export interface Scenario {
+    name: string;
+    /** Renders `n` items. Each resolved item must contain a <span data-resolved>. */
+    Scene: React.FC<{ n: number; uniqueKeys: number }>;
+}
+
+export interface BenchResult {
+    name: string;
+    mountMs: number;
+    rerenderMs: number;
+    fullLifecycleMs: number;
+}
+
+function renderOffscreen(element: React.ReactElement): {
+    root: ReturnType<typeof createRoot>;
+    container: HTMLDivElement;
+} {
+    const container = document.createElement('div');
+    document.getElementById('stage')!.appendChild(container);
+    const root = createRoot(container);
+    root.render(element);
+    return { root, container };
+}
+
+function cleanup(root: ReturnType<typeof createRoot>, container: HTMLDivElement) {
+    root.unmount();
+    container.remove();
+}
+
+function waitUntil(predicate: () => boolean, timeout: number, label: string, diagnostic?: () => string): Promise<void> {
+    return new Promise((resolve, reject) => {
+        const deadline = performance.now() + timeout;
+        const check = () => {
+            if (predicate()) {
+                resolve();
+            } else if (performance.now() > deadline) {
+                const extra = diagnostic ? ` — ${diagnostic()}` : '';
+                reject(new Error(`waitUntil timed out: ${label}${extra}`));
+            } else {
+                setTimeout(check, 1);
+            }
+        };
+        setTimeout(check, 0);
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Mount
+// ---------------------------------------------------------------------------
+
+async function measureMount(scenario: Scenario, n: number, uniqueKeys: number, iters: number): Promise<number> {
+    const times: number[] = [];
+
+    for (let i = 0; i < iters; i++) {
+        const start = performance.now();
+        const { root, container } = renderOffscreen(<scenario.Scene n={n} uniqueKeys={uniqueKeys} />);
+        await waitUntil(
+            () => container.querySelectorAll('span').length >= n,
+            30_000,
+            `${scenario.name} mount iter ${i}`,
+            () => `spans: ${container.querySelectorAll('span').length}/${n}`
+        );
+        times.push(performance.now() - start);
+        cleanup(root, container);
+        await new Promise((r) => setTimeout(r, 30));
+    }
+
+    times.sort((a, b) => a - b);
+    return times[Math.floor(times.length / 2)];
+}
+
+// ---------------------------------------------------------------------------
+// Re-render
+// ---------------------------------------------------------------------------
+
+async function measureRerender(scenario: Scenario, n: number, uniqueKeys: number, iters: number): Promise<number> {
+    let triggerRerender: (() => void) | null = null;
+
+    function Parent() {
+        const [tick, setTick] = useState(0);
+        triggerRerender = () => setTick((t) => t + 1);
+        return (
+            <div>
+                <scenario.Scene n={n} uniqueKeys={uniqueKeys} />
+                <span data-tick>{tick}</span>
+            </div>
+        );
+    }
+
+    const { root, container } = renderOffscreen(<Parent />);
+    await waitUntil(
+        () => container.querySelectorAll('[data-resolved]').length >= n,
+        30_000,
+        `${scenario.name} rerender settle`,
+        () => `resolved: ${container.querySelectorAll('[data-resolved]').length}/${n}`
+    );
+    await new Promise((r) => setTimeout(r, 100));
+
+    const times: number[] = [];
+    for (let i = 0; i < iters; i++) {
+        const expectedTick = String(i + 1);
+        triggerRerender!();
+        const start = performance.now();
+        await waitUntil(
+            () => container.querySelector('[data-tick]')?.textContent === expectedTick,
+            30_000,
+            `${scenario.name} rerender iter ${i}`
+        );
+        times.push(performance.now() - start);
+        await new Promise((r) => setTimeout(r, 10));
+    }
+
+    cleanup(root, container);
+    times.sort((a, b) => a - b);
+    return times[Math.floor(times.length / 2)];
+}
+
+// ---------------------------------------------------------------------------
+// Full lifecycle
+// ---------------------------------------------------------------------------
+
+async function measureFullLifecycle(scenario: Scenario, n: number, uniqueKeys: number, iters: number): Promise<number> {
+    const times: number[] = [];
+
+    for (let i = 0; i < iters; i++) {
+        const start = performance.now();
+        const { root, container } = renderOffscreen(<scenario.Scene n={n} uniqueKeys={uniqueKeys} />);
+
+        await waitUntil(
+            () => container.querySelectorAll('[data-resolved]').length >= n,
+            30_000,
+            `${scenario.name} lifecycle iter ${i}`,
+            () =>
+                `resolved: ${container.querySelectorAll('[data-resolved]').length}/${n}, total spans: ${container.querySelectorAll('span').length}`
+        );
+
+        times.push(performance.now() - start);
+        cleanup(root, container);
+        await new Promise((r) => setTimeout(r, 50));
+    }
+
+    times.sort((a, b) => a - b);
+    return times[Math.floor(times.length / 2)];
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export async function runBenchmark(
+    scenarios: Scenario[],
+    n: number,
+    uniqueKeys: number,
+    iters: number,
+    onProgress: (msg: string) => void
+): Promise<BenchResult[]> {
+    const results: BenchResult[] = [];
+
+    for (const s of scenarios) {
+        let mountMs = -1;
+        let rerenderMs = -1;
+        let fullLifecycleMs = -1;
+
+        try {
+            onProgress(`${s.name}: mounting ${n}...`);
+            mountMs = await measureMount(s, n, uniqueKeys, iters);
+        } catch (e) {
+            console.warn(`${s.name} mount failed:`, e);
+            onProgress(`${s.name}: mount timed out`);
+        }
+
+        try {
+            onProgress(`${s.name}: re-rendering ${n}...`);
+            rerenderMs = await measureRerender(s, n, uniqueKeys, iters);
+        } catch (e) {
+            console.warn(`${s.name} rerender failed:`, e);
+            onProgress(`${s.name}: rerender timed out`);
+        }
+
+        try {
+            onProgress(`${s.name}: full lifecycle (${n} fetches)...`);
+            fullLifecycleMs = await measureFullLifecycle(s, n, uniqueKeys, iters);
+        } catch (e) {
+            console.warn(`${s.name} lifecycle failed:`, e);
+            onProgress(`${s.name}: lifecycle timed out`);
+        }
+
+        results.push({ name: s.name, mountMs, rerenderMs, fullLifecycleMs });
+        onProgress(`${s.name}: done`);
+    }
+
+    return results;
+}