Add Deno benchmark runner and update perf docs

Author: seefeldb

packages/api/perf/README.md

@@ -5,19 +5,13 @@ expensive particular exported types from `packages/api/index.ts` are to check.
 Each scenario lives in its own `.ts` file with a matching `tsconfig.*.json` so
 that we can profile the types independently.
 
-## Prerequisites
-
-The commands below assume you are inside the repo root and that the vendored
-TypeScript binary at `tsc` is available. Use `bash` to run the snippets
-exactlyas shown.
-
 ## Quick Metrics
 
 Run the compiler with `--extendedDiagnostics` to get counts of type
 instantiations, memory usage, etc.
 
 ```bash
-tsc \
+deno run -A npm:typescript@5.8.3/bin/tsc \
   --project packages/api/perf/tsconfig.key.json \
   --extendedDiagnostics --pretty false
 ```
@@ -43,7 +37,7 @@ profile…”.
 
 ```bash
 NODE_OPTIONS=--max-old-space-size=4096 \
-tsc \
+deno run -A npm:typescript@5.8.3/bin/tsc \
   --project packages/api/perf/tsconfig.ikeyable-cell.json \
   --generateCpuProfile packages/api/perf/traces/ikeyable-cell.cpuprofile
 ```
@@ -63,7 +57,7 @@ exceed V8’s heap limit on the heavy scenarios.
 ```bash
 mkdir -p packages/api/perf/traces/ikeyable-cell \
   && NODE_OPTIONS=--max-old-space-size=4096 \
-     tsc \
+     deno run -A npm:typescript@5.8.3/bin/tsc \
        --project packages/api/perf/tsconfig.ikeyable-cell.json \
        --generateTrace packages/api/perf/traces/ikeyable-cell
 ```
@@ -79,14 +73,19 @@ trace generation; it keeps the scenario minimal enough to succeed.
 
 ## Scripts / Analysis
 
-There are no bespoke scripts yet; ad-hoc analysis can be performed with Node.js
-like so:
+To run every scenario in one go (and print a short summary for each), run:
+
+```bash
+deno run -A packages/api/perf/run-benchmarks.ts
+```
+
+For ad-hoc inspection of trace files you can also use Deno directly:
 
 ```bash
-deno -e 'const trace=require("./packages/api/perf/traces/ikeyable-cell/trace.json");\
-const totals=new Map();\
-for (const e of trace) if (e.ph==="X") totals.set(e.name,(totals.get(e.name)||0)+e.dur);\
-console.log([...totals.entries()].sort((a,b)=>b[1]-a[1]).slice(0,10));'
+deno eval 'import trace from "./packages/api/perf/traces/ikeyable-cell/trace.json" assert { type: "json" };\
+const totals = new Map();\
+for (const e of trace) if (e.ph === "X") totals.set(e.name, (totals.get(e.name) ?? 0) + e.dur);\
+console.log([...totals.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10));'
 ```
 
 Feel free to add your own utilities here if repeated analyses become necessary.

packages/api/perf/run-benchmarks.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env -S deno run -A
+
+const CONFIGS = [
+  "tsconfig.baseline.json",
+  "tsconfig.key.json",
+  "tsconfig.anycell.json",
+  "tsconfig.schema.json",
+  "tsconfig.ikeyable-cell.json",
+  "tsconfig.ikeyable-schema.json",
+  "tsconfig.ikeyable-realistic.json",
+] as const;
+
+const scriptDir = new URL(".", import.meta.url);
+const cwd = scriptDir.pathname;
+
+function fromFileUrl(url: URL): string {
+  if (url.protocol !== "file:") throw new TypeError("URL must be a file URL");
+  const path = decodeURIComponent(url.pathname);
+  if (Deno.build.os === "windows") {
+    return path.slice(1).replaceAll("/", "\\");
+  }
+  return path;
+}
+
+const tscPath = fromFileUrl(
+  new URL(
+    "../../../node_modules/.deno/typescript@5.8.3/node_modules/typescript/bin/tsc",
+    import.meta.url,
+  ),
+);
+
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+
+async function runScenario(config: string) {
+  console.log(`# ${config}`);
+
+  const command = new Deno.Command(tscPath, {
+    args: ["--project", config, "--extendedDiagnostics", "--pretty", "false"],
+    cwd,
+  });
+
+  const { code, stdout, stderr } = await command.output();
+  if (code !== 0) {
+    const err = decoder.decode(stderr);
+    console.error(err);
+    throw new Error(`Benchmark failed for ${config}`);
+  }
+
+  const output = decoder.decode(stdout);
+  console.log(output);
+
+  const summary: string[] = [];
+  for (const line of output.split("\n")) {
+    if (line.startsWith("Instantiations:")) {
+      summary.push(line.trim());
+    } else if (line.startsWith("Check time:")) {
+      summary.push(line.trim());
+    }
+  }
+
+  if (summary.length > 0) {
+    await Deno.stdout.write(
+      encoder.encode(
+        `${summary.join(" | ")}\n----------------------------------------\n\n`,
+      ),
+    );
+  } else {
+    console.log("----------------------------------------\n");
+  }
+}
+
+for (const config of CONFIGS) {
+  await runScenario(config);
+}