perf: Benchmarks and optimizations

BENCHMARKING.md

@@ -0,0 +1,63 @@
+# Benchmarking
+
+Valibot has a runtime benchmark suite for catching performance regressions and proving
+optimizations. It runs on [Vitest's built-in `bench`](https://vitest.dev/api/#bench), so there is
+no extra dependency.
+
+## Running
+
+```sh
+cd library
+pnpm bench
+```
+
+This runs every `library/bench/*.bench.ts` file and prints throughput per case (`hz`,
+operations per second, higher is better) along with latency percentiles. To run a single file,
+pass a filter:
+
+```sh
+pnpm bench variant
+```
+
+## What is covered
+
+The suite lives in `library/bench/` and targets the runtime hot paths:
+
+- `variant.bench.ts` / `variant-async.bench.ts` — discriminated-union dispatch (hit first, middle,
+  last option, and miss).
+- `enum.bench.ts` / `picklist.bench.ts` — membership against a large option list (hit and miss).
+- `object.bench.ts` — object validation (all keys present, and a missing required key).
+- `array.bench.ts`, `string-pipe.bench.ts` — regression guards for the array and pipe paths; they
+  should stay flat and signal a regression if they don't.
+
+## Results
+
+Record before/after numbers and the speedups they prove when an optimization changes the numbers,
+capturing both the baseline and the optimized run on the same machine.
+
+## Adding a benchmark
+
+Create `library/bench/<name>.bench.ts`:
+
+```ts
+import { bench, describe } from 'vitest';
+import * as v from '../src/index.ts';
+
+// Build the schema and inputs once, outside bench().
+const schema = v.object({ id: v.number(), name: v.string() });
+const input = { id: 1, name: 'test' };
+
+describe('object', () => {
+  bench('valid', () => {
+    return v.safeParse(schema, input);
+  });
+});
+```
+
+Guidelines:
+
+- Build schemas and inputs once outside `bench()` so you measure validation, not setup.
+- Use `safeParse` / `safeParseAsync` rather than `parse` to avoid throw overhead skewing results.
+- Return the parse result from `bench()` so the engine cannot drop the call as dead code.
+- Absolute `hz` values depend on hardware, so compare the baseline and optimized numbers on the same
+  machine, not across machines.

CONTRIBUTING.md

@@ -44,6 +44,13 @@ As we strive for excellence in our codebase, here are some guidelines to make yo
 - Size matters for PRs: Keep your pull requests concise and focused. Smaller PRs are easier to review and merge, speeding up the development process. This approach helps in isolating changes and simplifying troubleshooting.
 - Crafting a good commit message: Your commit messages are a roadmap of your changes. Make them informative and useful for everyone.
 
+## Benchmarking
+
+If your change is meant to improve performance, back it up with numbers. The repository has a
+runtime benchmark suite (`pnpm bench` in `library`); see [BENCHMARKING.md](BENCHMARKING.md) for how
+to run it, add a case, and record before/after results. Include the relevant baseline vs. optimized
+figures in your pull request.
+
 ## Issues
 
 Submit a [new issue][newissue] if there is a feature to be added, or if a bug was found in the existing code. Before submitting a new issue please review the [existing issues][issues] to avoid creating duplicates. Also, consider resolving current issues or contributing to the discussion on an issue.

library/bench/array.bench.ts

@@ -0,0 +1,16 @@
+import { bench, describe } from 'vitest';
+import * as v from '../src/index.ts';
+
+// Regression guard for array validation throughput.
+const schema = v.array(v.object({ id: v.number(), name: v.string() }));
+
+const input = Array.from({ length: 100 }, (_, i) => ({
+  id: i,
+  name: `item_${i}`,
+}));
+
+describe('array (100 objects)', () => {
+  bench('valid', () => {
+    return v.safeParse(schema, input);
+  });
+});

library/bench/enum.bench.ts

@@ -0,0 +1,27 @@
+import { bench, describe } from 'vitest';
+import * as v from '../src/index.ts';
+
+// Large string enum (~200 members).
+const enumObject: Record<string, string> = {};
+for (let i = 0; i < 200; i++) {
+  enumObject[`KEY_${i}`] = `value_${i}`;
+}
+const schema = v.enum(enumObject);
+
+const hitFirst = 'value_0';
+const hitLast = 'value_199';
+const miss = 'value_missing';
+
+describe('enum (200 members)', () => {
+  bench('hit first', () => {
+    return v.safeParse(schema, hitFirst);
+  });
+
+  bench('hit last', () => {
+    return v.safeParse(schema, hitLast);
+  });
+
+  bench('miss', () => {
+    return v.safeParse(schema, miss);
+  });
+});

library/bench/object.bench.ts

@@ -0,0 +1,41 @@
+import { bench, describe } from 'vitest';
+import * as v from '../src/index.ts';
+
+// Flat schema of primitive entries so the measurement isolates the top-level
+// object entry loop, not array or nested-object validation.
+const schema = v.object({
+  id: v.number(),
+  name: v.string(),
+  active: v.boolean(),
+  count: v.number(),
+  label: v.string(),
+  enabled: v.boolean(),
+});
+
+const fullInput = {
+  id: 1,
+  name: 'test',
+  active: true,
+  count: 2,
+  label: 'x',
+  enabled: false,
+};
+
+const missingKeyInput = {
+  id: 1,
+  name: 'test',
+  active: true,
+  count: 2,
+  label: 'x',
+  // `enabled` missing -> required-key path
+};
+
+describe('object', () => {
+  bench('all keys present (happy path)', () => {
+    return v.safeParse(schema, fullInput);
+  });
+
+  bench('missing required key', () => {
+    return v.safeParse(schema, missingKeyInput);
+  });
+});

library/bench/picklist.bench.ts

@@ -0,0 +1,24 @@
+import { bench, describe } from 'vitest';
+import * as v from '../src/index.ts';
+
+// Large allow-list, e.g. an ISO-style country/option code set.
+const values = Array.from({ length: 200 }, (_, i) => `code_${i}`);
+const schema = v.picklist(values);
+
+const hitFirst = 'code_0';
+const hitLast = 'code_199';
+const miss = 'code_missing';
+
+describe('picklist (200 options)', () => {
+  bench('hit first', () => {
+    return v.safeParse(schema, hitFirst);
+  });
+
+  bench('hit last', () => {
+    return v.safeParse(schema, hitLast);
+  });
+
+  bench('miss', () => {
+    return v.safeParse(schema, miss);
+  });
+});

library/bench/string-pipe.bench.ts

@@ -0,0 +1,18 @@
+import { bench, describe } from 'vitest';
+import * as v from '../src/index.ts';
+
+// Regression guard for pipe execution throughput.
+const schema = v.pipe(
+  v.string(),
+  v.minLength(3),
+  v.maxLength(32),
+  v.trim()
+);
+
+const input = 'hello world';
+
+describe('string pipe', () => {
+  bench('valid', () => {
+    return v.safeParse(schema, input);
+  });
+});

library/bench/variant-async.bench.ts

@@ -0,0 +1,37 @@
+import { bench, describe } from 'vitest';
+import * as v from '../src/index.ts';
+
+// Flat async discriminated union with 10 options, each keyed by a literal
+// `type`. Discriminator entries are sync (literal); the variant run is async.
+const options = Array.from({ length: 10 }, (_, i) =>
+  v.object({
+    type: v.literal(`option_${i}`),
+    value: v.number(),
+    label: v.string(),
+  })
+);
+// @ts-expect-error - runtime array is fine for the benchmark
+const schema = v.variantAsync('type', options);
+
+const firstInput = { type: 'option_0', value: 1, label: 'a' };
+const middleInput = { type: 'option_5', value: 1, label: 'a' };
+const lastInput = { type: 'option_9', value: 1, label: 'a' };
+const missInput = { type: 'option_x', value: 1, label: 'a' };
+
+describe('variantAsync (10 options)', () => {
+  bench('hit first option', async () => {
+    return await v.safeParseAsync(schema, firstInput);
+  });
+
+  bench('hit middle option', async () => {
+    return await v.safeParseAsync(schema, middleInput);
+  });
+
+  bench('hit last option', async () => {
+    return await v.safeParseAsync(schema, lastInput);
+  });
+
+  bench('miss (invalid discriminator)', async () => {
+    return await v.safeParseAsync(schema, missInput);
+  });
+});

library/bench/variant.bench.ts

@@ -0,0 +1,36 @@
+import { bench, describe } from 'vitest';
+import * as v from '../src/index.ts';
+
+// Flat discriminated union with 10 options, each keyed by a literal `type`.
+const options = Array.from({ length: 10 }, (_, i) =>
+  v.object({
+    type: v.literal(`option_${i}`),
+    value: v.number(),
+    label: v.string(),
+  })
+);
+// @ts-expect-error - runtime array is fine for the benchmark
+const schema = v.variant('type', options);
+
+const firstInput = { type: 'option_0', value: 1, label: 'a' };
+const middleInput = { type: 'option_5', value: 1, label: 'a' };
+const lastInput = { type: 'option_9', value: 1, label: 'a' };
+const missInput = { type: 'option_x', value: 1, label: 'a' };
+
+describe('variant (10 options)', () => {
+  bench('hit first option', () => {
+    return v.safeParse(schema, firstInput);
+  });
+
+  bench('hit middle option', () => {
+    return v.safeParse(schema, middleInput);
+  });
+
+  bench('hit last option', () => {
+    return v.safeParse(schema, lastInput);
+  });
+
+  bench('miss (invalid discriminator)', () => {
+    return v.safeParse(schema, missInput);
+  });
+});

library/package.json

@@ -44,6 +44,7 @@
   "scripts": {
     "play": "tsm ./playground.ts",
     "test": "vitest --typecheck",
+    "bench": "vitest bench --run",
     "coverage": "vitest run --coverage --isolate",
     "lint": "eslint \"src/**/*.ts*\" && tsc --noEmit && deno check ./src/index.ts",
     "lint.fix": "eslint \"src/**/*.ts*\" --fix",

library/src/schemas/enum/enum.ts

@@ -144,8 +144,18 @@ export function enum_(
       return _getStandardProps(this);
     },
     '~run'(dataset, config) {
+      // Lazily cache the options as a set for O(1) membership checks. This is
+      // faster than `Array.includes` for large enums and uses SameValueZero
+      // comparison, so behavior is identical. The set is built once and assumes
+      // `options` is not mutated after schema creation, which matches the
+      // existing contract: `expects` is already precomputed from `options`
+      // above, so a post-creation mutation would desync the error message
+      // regardless.
       // @ts-expect-error
-      if (this.options.includes(dataset.value)) {
+      const optionsSet: Set<unknown> = (this._optionsSet ??= new Set(
+        this.options
+      ));
+      if (optionsSet.has(dataset.value)) {
         // @ts-expect-error
         dataset.typed = true;
       } else {

library/src/schemas/looseObject/looseObject.ts

@@ -106,22 +106,22 @@ export function looseObject(
         // Process each object entry of schema
         for (const key in this.entries) {
           const valueSchema = this.entries[key];
+          const isKeyPresent = key in input;
 
           // If key is present or its an optional schema with a default value,
           // parse input of key or default value
           if (
-            key in input ||
+            isKeyPresent ||
             ((valueSchema.type === 'exact_optional' ||
               valueSchema.type === 'optional' ||
               valueSchema.type === 'nullish') &&
               // @ts-expect-error
               valueSchema.default !== undefined)
           ) {
-            const value: unknown =
-              key in input
-                ? // @ts-expect-error
-                  input[key]
-                : getDefault(valueSchema);
+            const value: unknown = isKeyPresent
+              ? // @ts-expect-error
+                input[key]
+              : getDefault(valueSchema);
             const valueDataset = valueSchema['~run']({ value }, config);
 
             // If there are issues, capture them

library/src/schemas/object/object.ts

@@ -109,22 +109,22 @@ export function object(
         // Process each object entry of schema
         for (const key in this.entries) {
           const valueSchema = this.entries[key];
+          const isKeyPresent = key in input;
 
           // If key is present or its an optional schema with a default value,
           // parse input of key or default value
           if (
-            key in input ||
+            isKeyPresent ||
             ((valueSchema.type === 'exact_optional' ||
               valueSchema.type === 'optional' ||
               valueSchema.type === 'nullish') &&
               // @ts-expect-error
               valueSchema.default !== undefined)
           ) {
-            const value: unknown =
-              key in input
-                ? // @ts-expect-error
-                  input[key]
-                : getDefault(valueSchema);
+            const value: unknown = isKeyPresent
+              ? // @ts-expect-error
+                input[key]
+              : getDefault(valueSchema);
             const valueDataset = valueSchema['~run']({ value }, config);
 
             // If there are issues, capture them

library/src/schemas/objectWithRest/objectWithRest.ts

@@ -129,22 +129,22 @@ export function objectWithRest(
         // Process each object entry of schema
         for (const key in this.entries) {
           const valueSchema = this.entries[key];
+          const isKeyPresent = key in input;
 
           // If key is present or its an optional schema with a default value,
           // parse input of key or default value
           if (
-            key in input ||
+            isKeyPresent ||
             ((valueSchema.type === 'exact_optional' ||
               valueSchema.type === 'optional' ||
               valueSchema.type === 'nullish') &&
               // @ts-expect-error
               valueSchema.default !== undefined)
           ) {
-            const value: unknown =
-              key in input
-                ? // @ts-expect-error
-                  input[key]
-                : getDefault(valueSchema);
+            const value: unknown = isKeyPresent
+              ? // @ts-expect-error
+                input[key]
+              : getDefault(valueSchema);
             const valueDataset = valueSchema['~run']({ value }, config);
 
             // If there are issues, capture them