feat: add perf tracer utilities

Author: ClaudiuCeia

docs/guide.md

@@ -176,3 +176,28 @@ if (!result.success) {
   console.error(formatErrorStack(result));
 }
 ```
+
+## Perf tracing (optional)
+
+For larger grammars it can be useful to measure where time goes. `createTracer`
+lets you wrap parsers and collect per-parser call counts, success/failure, input
+consumed, and total/max time.
+
+```ts
+import {
+  createTracer,
+  formatTraceTable,
+  seq,
+  str,
+} from "@claudiu-ceia/combine";
+
+const tr = createTracer();
+
+const word = tr.wrap("word", str("hello"));
+const p = tr.wrap("seq", seq(word, str("!")));
+
+const res = p({ text: "hello!", index: 0 });
+if (res.success) {
+  console.log(formatTraceTable(tr.rows()));
+}
+```

mod.ts

@@ -3,3 +3,4 @@ export * from "./src/combinators.ts";
 export * from "./src/parsers.ts";
 export * from "./src/utility.ts";
 export * from "./src/language.ts";
+export * from "./src/perf.ts";

src/perf.ts

@@ -0,0 +1,136 @@
+import type { Parser, Result } from "./Parser.ts";
+
+export type TraceRow = Readonly<{
+  name: string;
+  calls: number;
+  success: number;
+  failure: number;
+  fatalFailure: number;
+  consumed: number;
+  timeMs: number;
+  maxTimeMs: number;
+}>;
+
+export type Tracer = Readonly<{
+  wrap: <T>(name: string, p: Parser<T>) => Parser<T>;
+  rows: () => TraceRow[];
+  reset: () => void;
+}>;
+
+const nowDefault = (): number => {
+  const perf = (globalThis as { performance?: { now?: () => number } })
+    .performance;
+  return typeof perf?.now === "function" ? perf.now() : Date.now();
+};
+
+type MutableRow = {
+  name: string;
+  calls: number;
+  success: number;
+  failure: number;
+  fatalFailure: number;
+  consumed: number;
+  timeMs: number;
+  maxTimeMs: number;
+};
+
+const getOrCreateRow = (
+  m: Map<string, MutableRow>,
+  name: string,
+): MutableRow => {
+  const existing = m.get(name);
+  if (existing) return existing;
+  const created: MutableRow = {
+    name,
+    calls: 0,
+    success: 0,
+    failure: 0,
+    fatalFailure: 0,
+    consumed: 0,
+    timeMs: 0,
+    maxTimeMs: 0,
+  };
+  m.set(name, created);
+  return created;
+};
+
+export const createTracer = (opts?: { now?: () => number }): Tracer => {
+  const now = opts?.now ?? nowDefault;
+  const m = new Map<string, MutableRow>();
+
+  return {
+    wrap: <T>(name: string, p: Parser<T>): Parser<T> => {
+      return (ctx) => {
+        const row = getOrCreateRow(m, name);
+        row.calls++;
+
+        const t0 = now();
+        const res = p(ctx) as Result<T>;
+        const dt = now() - t0;
+
+        row.timeMs += dt;
+        if (dt > row.maxTimeMs) row.maxTimeMs = dt;
+
+        if (res.success) {
+          row.success++;
+          const consumed = res.ctx.index - ctx.index;
+          if (consumed > 0) row.consumed += consumed;
+        } else {
+          row.failure++;
+          if (res.fatal) row.fatalFailure++;
+        }
+
+        return res;
+      };
+    },
+    rows: (): TraceRow[] => {
+      return [...m.values()]
+        .map((r) => ({ ...r }))
+        .sort((a, b) => b.timeMs - a.timeMs);
+    },
+    reset: (): void => {
+      m.clear();
+    },
+  };
+};
+
+export const formatTraceTable = (rows: TraceRow[]): string => {
+  const headers = [
+    "name",
+    "calls",
+    "ok",
+    "fail",
+    "fatal",
+    "consumed",
+    "timeMs",
+    "maxMs",
+  ] as const;
+
+  const cells: string[][] = [
+    [...headers],
+    ...rows.map((r) => [
+      r.name,
+      String(r.calls),
+      String(r.success),
+      String(r.failure),
+      String(r.fatalFailure),
+      String(r.consumed),
+      r.timeMs.toFixed(3),
+      r.maxTimeMs.toFixed(3),
+    ]),
+  ];
+
+  const widths = headers.map((_, i) =>
+    Math.max(...cells.map((row) => row[i]!.length))
+  );
+
+  const pad = (s: string, w: number) => s.padEnd(w, " ");
+  const lines: string[] = [];
+  lines.push(cells[0]!.map((c, i) => pad(c, widths[i]!)).join("  "));
+  lines.push(widths.map((w) => "-".repeat(w)).join("  "));
+  for (let i = 1; i < cells.length; i++) {
+    lines.push(cells[i]!.map((c, j) => pad(c, widths[j]!)).join("  "));
+  }
+
+  return lines.join("\n");
+};

tests/perf.test.ts

@@ -0,0 +1,54 @@
+import { assertEquals } from "@std/assert";
+import { createTracer, formatTraceTable } from "../src/perf.ts";
+import { failure, type Parser, success } from "../src/Parser.ts";
+
+Deno.test("tracer counts calls and consumed input", () => {
+  let t = 0;
+  const tracer = createTracer({ now: () => ++t }); // deterministic
+
+  const ok1: Parser<string> = (ctx) =>
+    success({ ...ctx, index: ctx.index + 2 }, "ok");
+  const bad: Parser<string> = (ctx) => failure(ctx, "nope");
+
+  const p = tracer.wrap("ok1", ok1);
+  const q = tracer.wrap("bad", bad);
+
+  const r1 = p({ text: "abcd", index: 0 });
+  assertEquals(r1.success, true);
+  const r2 = q({ text: "abcd", index: 2 });
+  assertEquals(r2.success, false);
+
+  const rows = tracer.rows();
+  assertEquals(rows.length, 2);
+
+  const okRow = rows.find((x) => x.name === "ok1")!;
+  assertEquals(okRow.calls, 1);
+  assertEquals(okRow.success, 1);
+  assertEquals(okRow.failure, 0);
+  assertEquals(okRow.consumed, 2);
+
+  const badRow = rows.find((x) => x.name === "bad")!;
+  assertEquals(badRow.calls, 1);
+  assertEquals(badRow.success, 0);
+  assertEquals(badRow.failure, 1);
+});
+
+Deno.test("formatTraceTable prints a header and rows", () => {
+  const table = formatTraceTable([
+    {
+      name: "p",
+      calls: 2,
+      success: 1,
+      failure: 1,
+      fatalFailure: 0,
+      consumed: 3,
+      timeMs: 1.23456,
+      maxTimeMs: 1.0,
+    },
+  ]);
+
+  assertEquals(table.includes("name"), true);
+  assertEquals(table.includes("calls"), true);
+  assertEquals(table.includes("p"), true);
+  assertEquals(table.includes("1.235"), true);
+});