[68] Add construction cost benchmark (#69)

* add construction cost benchmark

Author: TomStrepsil

benchmarking/README.md

@@ -15,11 +15,11 @@ npm run bench --workspace=benchmarking
 
 Isolates the cost of `PartialMatchRegExp`'s `exec()` override. All three candidates run the same underlying partial pattern against the same input — the only variable is whether a JavaScript wrapper sits in the call chain:
 
-| Candidate | Notes |
-|---|---|
-| Native `RegExp.exec` | Baseline — no partial transform, no override |
+| Candidate                 | Notes                                                          |
+| ------------------------- | -------------------------------------------------------------- |
+| Native `RegExp.exec`      | Baseline — no partial transform, no override                   |
 | `compilePartial()` result | Partial source baked into a plain `RegExp` — no class overhead |
-| `PartialMatchRegExp.exec` | Partial source via the class override |
+| `PartialMatchRegExp.exec` | Partial source via the class override                          |
 
 Two input cases are measured: a full match, and a partial input that returns `null` on the native regex.
 
@@ -38,10 +38,10 @@ Models a user typing character-by-character into a validated input field. Each p
 
 Two patterns are exercised:
 
-| Pattern | Example input | Length |
-|---|---|---|
+| Pattern                  | Example input       | Length   |
+| ------------------------ | ------------------- | -------- |
 | E.164-style phone number | `+1 (555) 123-4567` | 18 chars |
-| ISO 8601 date | `2024-12-31` | 10 chars |
+| ISO 8601 date            | `2024-12-31`        | 10 chars |
 
 Each group compares native `test` (always returns `false` for incomplete input), a plain partial `RegExp`, and `PartialMatchRegExp` on the fast path.
 
@@ -51,13 +51,31 @@ When `exec()` is called on a partial input that contains backreferences, the pat
 
 Two patterns are used to cover different positions within a backreference:
 
-| Pattern | Example |
-|---|---|
-| Repeated word (`/^(\w+) \1$/`) | `"foo foo"` |
+| Pattern                                           | Example              |
+| ------------------------------------------------- | -------------------- |
+| Repeated word (`/^(\w+) \1$/`)                    | `"foo foo"`          |
 | HTML open/close tag (`/^<([a-z]+)>[^<]+<\/\1>$/`) | `"<div>hello</div>"` |
 
 Each pattern is measured at three stages — full match (native fast path), partial input before the backreference atom is reached, and partial input mid-backreference — plus an accumulated keystroke simulation that sums the cost over all prefixes.
 
+### 5. Construction cost (`construction-cost.bench.ts`)
+
+Scenarios 1-4 build every candidate once outside the timed loop, so they never see the cost of `compilePartial()`'s walk()/render() pass — the one-time parsing work done per `new PartialMatchRegExp()`. This scenario isolates that cost so walk additions can be tracked independently of the exec-time scenarios above.
+
+| Candidate                  | Notes                                         |
+| -------------------------- | --------------------------------------------- |
+| Native `new RegExp()`      | Baseline — no parsing beyond V8's own compile |
+| `compilePartial()`         | Walk + render, no class overhead              |
+| `new PartialMatchRegExp()` | `compilePartial()` plus class construction    |
+
+Three patterns span the complexity range the walker branches on:
+
+| Pattern               | Notes                                                            |
+| --------------------- | ---------------------------------------------------------------- |
+| Simple (`/^hello+$/`) | No groups, no character classes, no backreferences               |
+| Phone number          | Several character classes and optional groups, no backreferences |
+| HTML tag              | Capturing group + backreference — exercises the dynamic path     |
+
 ## 🤖 CI integration
 
 The workflow at [`.github/workflows/benchmark.yml`](../.github/workflows/benchmark.yml) runs on every push to `main` and on pull requests targeting `main`.

benchmarking/src/construction-cost.bench.ts

@@ -0,0 +1,47 @@
+/**
+ * Scenario 5: construction cost
+ *
+ * The other scenarios measure exec()/test() on regexes built once outside the
+ * timed loop, so they never see the cost of compilePartial()'s walk()/render()
+ * pass. That pass runs once per `new PartialMatchRegExp()` (or per direct
+ * `compilePartial()` call) and is where per-atom bookkeeping added for new
+ * features (e.g. the feature-flag scan) actually lands. This scenario isolates
+ * that one-time cost so it can be tracked independently of the exec-time
+ * scenarios above.
+ *
+ * Baselines:
+ *   - native `new RegExp()`   — no parsing beyond V8's own compile
+ *   - `compilePartial()`      — walk() + render(), no class wrapper
+ *   - `new PartialMatchRegExp()` — compilePartial() plus class construction
+ *
+ * Three patterns span the complexity range the walker branches on:
+ *   - simple:  no groups, no character classes, no backreferences
+ *   - phone:   several character classes and optional groups, no backreferences
+ *   - HTML tag: capturing group + backreference, exercises the dynamic path
+ */
+
+import { bench, group } from "mitata";
+import { compilePartial } from "../../src/compilePartial.ts";
+import PartialMatchRegExp from "../../src/partialMatchRegExp.ts";
+
+const simplePattern = /^hello+$/;
+const phonePattern = /^\+?1?\s?\(?\d{3}\)?[\s.-]?\d{3}[\s.-]?\d{4}$/;
+const htmlTagPattern = /^<([a-zA-Z][\w-]*)(?:\s[^<>]*)?>[^<]+<\/\1>$/;
+
+group("construction — simple pattern (no groups, no backreferences)", () => {
+  bench("native new RegExp()", () => new RegExp(simplePattern));
+  bench("compilePartial()", () => compilePartial(simplePattern));
+  bench("new PartialMatchRegExp()", () => new PartialMatchRegExp(simplePattern));
+});
+
+group("construction — phone pattern (character classes, optional groups)", () => {
+  bench("native new RegExp()", () => new RegExp(phonePattern));
+  bench("compilePartial()", () => compilePartial(phonePattern));
+  bench("new PartialMatchRegExp()", () => new PartialMatchRegExp(phonePattern));
+});
+
+group("construction — HTML tag pattern (capturing group + backreference)", () => {
+  bench("native new RegExp()", () => new RegExp(htmlTagPattern));
+  bench("compilePartial()", () => compilePartial(htmlTagPattern));
+  bench("new PartialMatchRegExp()", () => new PartialMatchRegExp(htmlTagPattern));
+});

benchmarking/src/run.ts

@@ -18,6 +18,7 @@ import "./dispatch-overhead.bench.ts";
 import "./hot-loop.bench.ts";
 import "./keystroke.bench.ts";
 import "./backref-slow-path.bench.ts";
+import "./construction-cost.bench.ts";
 import { run } from "mitata";
 
 const isJson = process.argv.includes("--json");

docs/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Benchmark for construction cost
+
 ## [1.0.0] - 2026-07-22
 
 ### Fixed