ivl 0.4.5 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@ Main focus is on speed and flexibility of the validation rules.
 
 By default `getValueErrors` and `getSchemaErrors` automatically detects and chooses the most performant checking method for your rule set.
 
-If your rule set and/or schema are very large or complex, you may want to directly use `getValueErrorsSync`/`getSchemaErrorsSync` or `getValueErrorsAsync`/`getSchemaErrorsAsync` for improved performance on synchronous and asynchronous rule sets respectively.
+If you validate against the same rule set or schema repeatedly, compile it once with `compileRules`/`compileSchema` (see [Compiled validators](#compiled-validators)) - that does the sync/async detection up front and is the fastest option.
 
 Use synchronous versions of the functions for better performance if you don't need to support asynchronous checks on your inputs. 
 
@@ -51,6 +51,80 @@ const inDatabase: RULE<string, [ctx: { db: Database }]> = async (value, ctx) =>
 > "may be sync or async", so the return type becomes `string[] | Promise<string[]>`. Prefer
 > `satisfies RULES` / `satisfies SCHEMA`, which validates the shape without losing the inferred types.
 
+# Compiled validators
+`compileRules` and `compileSchema` turn a rule set or schema into a reusable validator. They return
+exactly what `getValueErrors`/`getSchemaErrors` would, with the same sync/async type inference, but the
+work those functions repeat on every call - finding the rule keys and checking for async rules - is
+done once up front:
+
+```typescript
+import { compileSchema } from 'ivl';
+import { EMAIL_RULES, STRONG_PASSWORD_RULES } from 'ivl/patterns';
+
+// Compile once, at module level
+const validateRegistration = compileSchema({
+  email: EMAIL_RULES,
+  password: STRONG_PASSWORD_RULES,
+}, { strict: true });
+
+// ...then call it per request
+const errors = validateRegistration(body); // { email: string[], password: string[] }
+```
+
+The rule sets and options are captured when compiling, so changing them afterwards has no effect on an
+existing validator.
+
+# Options
+`getSchemaErrors`, `getSchemaErrorsSync`, `getSchemaErrorsAsync` and `compileSchema` take an options object;
+`compileRules` takes `break_early`. Both options are off by default.
+
+- **`strict`** - also report keys of the object that the schema doesn't have, each as `['Key not allowed']`.
+- **`break_early`** - report only the first failing rule of each rule set instead of all of them. Rules
+  that aren't `async` run first, in order, and stop at the first failure; `async` rules only run if all of
+  those passed. So a cheap check that fails skips the expensive ones, like a long regex or a database lookup:
+
+```typescript
+const validateEmail = compileRules({
+  ...EMAIL_RULES, // cheap checks first
+  "Email already registered": async (i: unknown) => !(await emailExists(i)),
+}, { break_early: true });
+
+await validateEmail('not an email'); // ['Must be a valid email address'] - the lookup never ran
+```
+
+Every field of a schema is still validated with `break_early`; each just reports at most one error. Leave
+it off when you want to show users every problem at once, e.g. all unmet password requirements.
+
+# Ready-made rule sets
+`ivl/patterns` exports rule sets for common formats, ready to drop into a schema:
+
+```typescript
+import { getSchemaErrors } from 'ivl';
+import { EMAIL_RULES, STRONG_PASSWORD_RULES, IPV4_RULES, IPV6_RULES } from 'ivl/patterns';
+
+const errors = getSchemaErrors(input, {
+  email: EMAIL_RULES,
+  password: STRONG_PASSWORD_RULES,
+  ip: [IPV4_RULES, IPV6_RULES], // passes if either rule set passes
+});
+```
+
+Available: `EMAIL_RULES`, `URL_RULES`, `UUID_RULES`, `UUID_V4_RULES`, `IPV4_RULES`, `IPV6_RULES`,
+`MAC_ADDRESS_RULES`, `HEX_COLOR_RULES`, `SLUG_RULES`, `E164_PHONE_RULES`, `SEMVER_RULES`, `BASE64_RULES`,
+`JWT_RULES`, `ISO_8601_DATE_RULES`, `ISO_8601_DATETIME_RULES`, `ISO_8601_TIME_RULES`, `PASSWORD_RULES`
+and `STRONG_PASSWORD_RULES`.
+
+All of them are synchronous and frozen. To customise one, spread it into a new object:
+
+```typescript
+const COMPANY_EMAIL_RULES = {
+  ...EMAIL_RULES,
+  "Must be a company address": (i: unknown) => typeof i === 'string' && i.endsWith('@example.com'),
+};
+```
+
+The date rule sets also check the calendar, so `2024-02-30` fails even though it matches the pattern.
+
 # Installing
 ```typescript
 bun add ivl // bun.js
@@ -209,4 +283,231 @@ app.put('/register/:invitation_code',
   (c)=> c.text("Success"));
 
 export default app;
-```
+```
+
+<!-- benchmark:start -->
+# Benchmarks
+
+Generated by CI on a GitHub-hosted runner, so absolute numbers vary between runs.
+Compare rows within a table rather than across runs. Read the caveats at the end before
+drawing conclusions: the libraries do different amounts of work in some scenarios.
+
+## Bun (JavaScriptCore)
+
+- **clk**: ~4.30 GHz
+- **cpu**: AMD EPYC 9V45 96-Core Processor
+- **runtime**: bun 1.4.2 (x64-linux)
+
+| • ivl execution paths |              avg |         min |         p75 |         p99 |         max |
+| ------------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| pure regex helper  | ` 13.52 ns/iter` | ` 12.84 ns` | ` 13.64 ns` | ` 16.26 ns` | ` 35.29 ns` |
+| async regex helper | ` 82.30 ns/iter` | ` 73.32 ns` | ` 80.07 ns` | `156.46 ns` | `265.68 ns` |
+| smart regex helper | ` 26.02 ns/iter` | ` 22.43 ns` | ` 24.92 ns` | ` 82.75 ns` | `180.55 ns` |
+| sync regex helper  | ` 24.25 ns/iter` | ` 19.55 ns` | ` 23.57 ns` | ` 75.54 ns` | `210.71 ns` |
+
+| • single regex rule, report all errors (valid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl          | ` 34.12 ns/iter` | ` 28.45 ns` | ` 34.15 ns` | ` 90.83 ns` | `133.14 ns` |
+| ivl compiled | ` 38.29 ns/iter` | ` 34.44 ns` | ` 37.92 ns` | ` 95.95 ns` | `122.56 ns` |
+| zod          | ` 61.64 ns/iter` | ` 50.50 ns` | ` 54.90 ns` | `197.04 ns` | `418.33 ns` |
+| valibot      | ` 36.60 ns/iter` | ` 33.16 ns` | ` 36.12 ns` | ` 69.51 ns` | `129.53 ns` |
+| yup          | `705.02 ns/iter` | `618.97 ns` | `732.24 ns` | `846.00 ns` | `  1.25 µs` |
+
+| • single regex rule, report all errors (invalid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl          | ` 21.34 ns/iter` | ` 18.91 ns` | ` 20.92 ns` | ` 80.84 ns` | `109.01 ns` |
+| ivl compiled | ` 29.84 ns/iter` | ` 26.05 ns` | ` 28.86 ns` | ` 97.03 ns` | `148.36 ns` |
+| zod          | `  1.11 µs/iter` | `  1.03 µs` | `  1.11 µs` | `  1.36 µs` | `  1.45 µs` |
+| valibot      | ` 59.58 ns/iter` | ` 50.78 ns` | ` 57.61 ns` | `127.88 ns` | `184.43 ns` |
+| yup          | `  5.00 µs/iter` | `  4.78 µs` | `  5.05 µs` | `  5.35 µs` | `  5.42 µs` |
+
+| • single regex rule, pass/fail (valid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl compiled | ` 26.07 ns/iter` | ` 23.87 ns` | ` 25.92 ns` | ` 40.28 ns` | `113.68 ns` |
+| zod          | ` 58.58 ns/iter` | ` 50.32 ns` | ` 56.24 ns` | `133.43 ns` | `150.19 ns` |
+| valibot      | ` 31.14 ns/iter` | ` 27.63 ns` | ` 29.65 ns` | ` 90.41 ns` | `151.00 ns` |
+| yup          | `722.17 ns/iter` | `639.21 ns` | `770.56 ns` | `816.36 ns` | `901.42 ns` |
+
+| • single regex rule, pass/fail (invalid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl compiled | ` 16.51 ns/iter` | ` 14.88 ns` | ` 16.05 ns` | ` 28.92 ns` | ` 97.51 ns` |
+| zod          | `  1.05 µs/iter` | `992.50 ns` | `  1.06 µs` | `  1.19 µs` | `  1.21 µs` |
+| valibot      | ` 56.66 ns/iter` | ` 46.98 ns` | ` 53.78 ns` | `136.47 ns` | `341.59 ns` |
+| yup          | `  3.40 µs/iter` | `  3.26 µs` | `  3.46 µs` | `  3.59 µs` | `  3.61 µs` |
+
+| • built-in email validator (regexes differ) (valid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl          | ` 51.80 ns/iter` | ` 47.35 ns` | ` 50.80 ns` | `127.91 ns` | `194.98 ns` |
+| ivl compiled | ` 41.66 ns/iter` | ` 37.96 ns` | ` 41.18 ns` | `103.09 ns` | `136.03 ns` |
+| zod          | ` 70.53 ns/iter` | ` 63.73 ns` | ` 69.40 ns` | `141.86 ns` | `294.39 ns` |
+| valibot      | ` 43.41 ns/iter` | ` 40.13 ns` | ` 43.64 ns` | ` 72.32 ns` | `143.37 ns` |
+| yup          | `832.47 ns/iter` | `751.96 ns` | `880.36 ns` | `961.46 ns` | `981.26 ns` |
+
+| • built-in email validator (regexes differ) (invalid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl          | ` 45.57 ns/iter` | ` 40.58 ns` | ` 44.95 ns` | `124.01 ns` | `155.78 ns` |
+| ivl compiled | ` 36.58 ns/iter` | ` 31.31 ns` | ` 33.96 ns` | `111.54 ns` | `215.61 ns` |
+| zod          | `  1.32 µs/iter` | `  1.18 µs` | `  1.29 µs` | `  2.22 µs` | `  2.77 µs` |
+| valibot      | ` 70.15 ns/iter` | ` 62.03 ns` | ` 68.73 ns` | `137.41 ns` | `170.45 ns` |
+| yup          | `  4.30 µs/iter` | `  4.04 µs` | `  4.41 µs` | `  4.60 µs` | `  4.65 µs` |
+
+| • object schema, report all errors (valid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl          | `327.50 ns/iter` | `299.90 ns` | `320.39 ns` | `492.24 ns` | `668.48 ns` |
+| ivl compiled | `203.15 ns/iter` | `185.28 ns` | `197.36 ns` | `349.93 ns` | `545.51 ns` |
+| zod          | `348.37 ns/iter` | `309.78 ns` | `339.21 ns` | `617.57 ns` | `879.07 ns` |
+| valibot      | `321.00 ns/iter` | `306.99 ns` | `322.20 ns` | `425.95 ns` | `498.46 ns` |
+| yup          | `  5.37 µs/iter` | `  5.17 µs` | `  5.49 µs` | `  5.57 µs` | `  5.62 µs` |
+
+| • object schema, report all errors (invalid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl          | `351.10 ns/iter` | `327.31 ns` | `353.17 ns` | `441.63 ns` | `531.51 ns` |
+| ivl compiled | `198.54 ns/iter` | `184.70 ns` | `195.92 ns` | `283.96 ns` | `316.35 ns` |
+| zod          | `  2.12 µs/iter` | `  1.87 µs` | `  2.28 µs` | `  2.59 µs` | `  2.60 µs` |
+| valibot      | `545.94 ns/iter` | `497.96 ns` | `555.42 ns` | `665.79 ns` | `  1.13 µs` |
+| yup          | ` 17.34 µs/iter` | `  8.43 µs` | ` 16.94 µs` | ` 47.33 µs` | `636.65 µs` |
+
+| • object schema, pass/fail (valid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl compiled | `212.72 ns/iter` | `198.92 ns` | `210.15 ns` | `296.15 ns` | `305.23 ns` |
+| zod          | `379.33 ns/iter` | `330.83 ns` | `355.65 ns` | `790.78 ns` | `972.48 ns` |
+| valibot      | `335.73 ns/iter` | `325.24 ns` | `335.79 ns` | `419.19 ns` | `429.04 ns` |
+| yup          | `  5.53 µs/iter` | `  5.33 µs` | `  5.60 µs` | `  5.83 µs` | `  5.83 µs` |
+
+| • object schema, pass/fail (invalid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl compiled | `165.02 ns/iter` | `146.93 ns` | `154.26 ns` | `372.14 ns` | `539.38 ns` |
+| zod          | `  2.05 µs/iter` | `  1.93 µs` | `  2.09 µs` | `  2.36 µs` | `  2.40 µs` |
+| valibot      | `219.92 ns/iter` | `190.17 ns` | `206.55 ns` | `470.12 ns` | `573.75 ns` |
+| yup          | `  6.74 µs/iter` | `  6.35 µs` | `  6.82 µs` | `  7.05 µs` | `  7.32 µs` |
+
+| • object schema with an async rule, report all errors (valid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl          | `  1.49 µs/iter` | `991.00 ns` | `  1.55 µs` | `  3.67 µs` | `407.89 µs` |
+| ivl compiled | `972.10 ns/iter` | `892.33 ns` | `  1.01 µs` | `  1.22 µs` | `  1.50 µs` |
+| zod          | `  2.04 µs/iter` | `  1.45 µs` | `  2.13 µs` | `  4.55 µs` | `421.99 µs` |
+| valibot      | `  2.06 µs/iter` | `  1.42 µs` | `  2.17 µs` | `  4.55 µs` | `413.39 µs` |
+| yup          | `  6.34 µs/iter` | `  6.05 µs` | `  6.48 µs` | `  6.68 µs` | `  6.72 µs` |
+
+| • object schema with an async rule, report all errors (invalid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl          | `  1.15 µs/iter` | `  1.08 µs` | `  1.20 µs` | `  1.25 µs` | `  1.45 µs` |
+| ivl compiled | `988.52 ns/iter` | `926.70 ns` | `  1.04 µs` | `  1.09 µs` | `  1.09 µs` |
+| zod          | `  3.25 µs/iter` | `  3.03 µs` | `  3.34 µs` | `  3.50 µs` | `  3.51 µs` |
+| valibot      | `  1.76 µs/iter` | `  1.60 µs` | `  1.81 µs` | `  1.96 µs` | `  1.99 µs` |
+| yup          | ` 12.97 µs/iter` | ` 12.54 µs` | ` 13.12 µs` | ` 13.27 µs` | ` 13.37 µs` |
+
+## Node (V8)
+
+- **clk**: ~4.25 GHz
+- **cpu**: AMD EPYC 9V45 96-Core Processor
+- **runtime**: node 24.21.0 (x64-linux)
+
+| • ivl execution paths |              avg |         min |         p75 |         p99 |         max |
+| ------------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| pure regex helper  | ` 24.51 ns/iter` | ` 20.15 ns` | ` 23.01 ns` | ` 59.01 ns` | `141.77 ns` |
+| async regex helper | `115.24 ns/iter` | `103.07 ns` | `116.37 ns` | `244.47 ns` | `565.06 ns` |
+| smart regex helper | ` 57.60 ns/iter` | ` 53.07 ns` | ` 56.42 ns` | `113.03 ns` | `173.16 ns` |
+| sync regex helper  | ` 37.14 ns/iter` | ` 34.47 ns` | ` 37.31 ns` | ` 54.91 ns` | ` 88.52 ns` |
+
+| • single regex rule, report all errors (valid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl          | ` 62.56 ns/iter` | ` 57.85 ns` | ` 61.46 ns` | `121.22 ns` | `259.12 ns` |
+| ivl compiled | ` 33.48 ns/iter` | ` 30.43 ns` | ` 33.13 ns` | ` 53.45 ns` | `104.86 ns` |
+| zod          | ` 83.41 ns/iter` | ` 68.60 ns` | `103.02 ns` | `216.69 ns` | `618.68 ns` |
+| valibot      | ` 43.02 ns/iter` | ` 40.24 ns` | ` 43.45 ns` | ` 60.00 ns` | `136.12 ns` |
+| yup          | `698.06 ns/iter` | `638.67 ns` | `710.79 ns` | `  1.00 µs` | `  1.24 µs` |
+
+| • single regex rule, report all errors (invalid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl          | ` 49.52 ns/iter` | ` 46.45 ns` | ` 49.37 ns` | ` 68.94 ns` | ` 95.38 ns` |
+| ivl compiled | ` 23.19 ns/iter` | ` 21.80 ns` | ` 22.96 ns` | ` 38.54 ns` | `113.55 ns` |
+| zod          | `  1.53 µs/iter` | `  1.28 µs` | `  1.36 µs` | `  3.73 µs` | `  3.76 µs` |
+| valibot      | `184.48 ns/iter` | ` 71.54 ns` | ` 78.01 ns` | `  4.15 µs` | `  4.90 µs` |
+| yup          | ` 23.65 µs/iter` | ` 22.82 µs` | ` 23.81 µs` | ` 23.96 µs` | ` 25.73 µs` |
+
+| • single regex rule, pass/fail (valid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl compiled | ` 32.47 ns/iter` | ` 29.39 ns` | ` 33.25 ns` | ` 38.61 ns` | ` 83.76 ns` |
+| zod          | ` 72.01 ns/iter` | ` 66.45 ns` | ` 70.41 ns` | `122.20 ns` | `604.70 ns` |
+| valibot      | ` 40.36 ns/iter` | ` 38.46 ns` | ` 40.81 ns` | ` 47.20 ns` | `100.89 ns` |
+| yup          | `696.18 ns/iter` | `668.23 ns` | `705.27 ns` | `760.27 ns` | `810.10 ns` |
+
+| • single regex rule, pass/fail (invalid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl compiled | ` 22.68 ns/iter` | ` 21.30 ns` | ` 22.63 ns` | ` 36.02 ns` | `127.04 ns` |
+| zod          | `  1.50 µs/iter` | `  1.30 µs` | `  1.33 µs` | `  3.32 µs` | `  3.41 µs` |
+| valibot      | `188.62 ns/iter` | ` 71.83 ns` | ` 76.80 ns` | `  4.18 µs` | `  5.15 µs` |
+| yup          | ` 13.65 µs/iter` | ` 13.58 µs` | ` 13.70 µs` | ` 13.70 µs` | ` 13.72 µs` |
+
+| • built-in email validator (regexes differ) (valid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl          | `118.83 ns/iter` | `107.39 ns` | `114.09 ns` | `295.92 ns` | `390.04 ns` |
+| ivl compiled | ` 43.08 ns/iter` | ` 40.58 ns` | ` 43.35 ns` | ` 68.22 ns` | `145.20 ns` |
+| zod          | `117.66 ns/iter` | `100.59 ns` | `106.00 ns` | `346.64 ns` | `654.21 ns` |
+| valibot      | ` 46.13 ns/iter` | ` 43.45 ns` | ` 46.57 ns` | ` 67.45 ns` | `142.49 ns` |
+| yup          | `675.60 ns/iter` | `639.19 ns` | `683.40 ns` | `785.82 ns` | `  1.21 µs` |
+
+| • built-in email validator (regexes differ) (invalid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl          | `103.16 ns/iter` | ` 97.03 ns` | `104.03 ns` | `132.85 ns` | `181.27 ns` |
+| ivl compiled | ` 34.96 ns/iter` | ` 31.56 ns` | ` 34.17 ns` | ` 73.88 ns` | `179.74 ns` |
+| zod          | `  1.61 µs/iter` | `  1.37 µs` | `  1.45 µs` | `  3.51 µs` | `  3.71 µs` |
+| valibot      | `170.76 ns/iter` | ` 71.09 ns` | ` 76.18 ns` | `  3.93 µs` | `  5.23 µs` |
+| yup          | ` 22.65 µs/iter` | ` 21.50 µs` | ` 22.21 µs` | ` 24.04 µs` | ` 28.84 µs` |
+
+| • object schema, report all errors (valid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl          | `725.21 ns/iter` | `700.77 ns` | `724.11 ns` | `830.31 ns` | `  1.17 µs` |
+| ivl compiled | `261.26 ns/iter` | `251.23 ns` | `260.07 ns` | `318.92 ns` | `555.87 ns` |
+| zod          | `748.41 ns/iter` | `641.54 ns` | `681.16 ns` | `  1.57 µs` | `  1.62 µs` |
+| valibot      | `423.50 ns/iter` | `404.05 ns` | `417.93 ns` | `734.86 ns` | `893.94 ns` |
+| yup          | `  4.93 µs/iter` | `  4.82 µs` | `  4.93 µs` | `  5.27 µs` | `  5.52 µs` |
+
+| • object schema, report all errors (invalid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl          | `695.66 ns/iter` | `681.21 ns` | `694.45 ns` | `751.23 ns` | `918.42 ns` |
+| ivl compiled | `256.14 ns/iter` | `246.15 ns` | `258.42 ns` | `291.06 ns` | `329.57 ns` |
+| zod          | `  3.57 µs/iter` | `  1.95 µs` | `  3.13 µs` | `  8.54 µs` | `  8.68 ms` |
+| valibot      | `  1.34 µs/iter` | `725.76 ns` | `769.83 ns` | `  6.39 µs` | `  6.67 µs` |
+| yup          | ` 56.17 µs/iter` | ` 26.44 µs` | ` 72.63 µs` | `132.72 µs` | `363.54 µs` |
+
+| • object schema, pass/fail (valid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl compiled | `290.00 ns/iter` | `280.18 ns` | `289.45 ns` | `334.74 ns` | `694.99 ns` |
+| zod          | `743.37 ns/iter` | `654.72 ns` | `701.12 ns` | `  1.25 µs` | `  1.27 µs` |
+| valibot      | `402.39 ns/iter` | `391.71 ns` | `402.53 ns` | `444.24 ns` | `753.31 ns` |
+| yup          | `  4.98 µs/iter` | `  4.90 µs` | `  5.00 µs` | `  5.09 µs` | `  5.24 µs` |
+
+| • object schema, pass/fail (invalid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl compiled | `220.63 ns/iter` | `212.62 ns` | `219.76 ns` | `252.80 ns` | `478.33 ns` |
+| zod          | `  3.33 µs/iter` | `  2.62 µs` | `  4.45 µs` | `  5.82 µs` | `  6.13 µs` |
+| valibot      | `472.12 ns/iter` | `286.54 ns` | `300.30 ns` | `  5.70 µs` | `  5.85 µs` |
+| yup          | ` 15.55 µs/iter` | ` 14.94 µs` | ` 15.32 µs` | ` 15.95 µs` | ` 19.16 µs` |
+
+| • object schema with an async rule, report all errors (valid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl          | `  1.86 µs/iter` | `  1.37 µs` | `  1.96 µs` | `  4.55 µs` | `  4.88 µs` |
+| ivl compiled | `  2.08 µs/iter` | `  1.20 µs` | `  2.54 µs` | `  4.50 µs` | `  4.60 µs` |
+| zod          | `  1.83 µs/iter` | `  1.71 µs` | `  1.92 µs` | `  2.10 µs` | `  2.22 µs` |
+| valibot      | `  2.36 µs/iter` | `  1.83 µs` | `  2.69 µs` | `  2.92 µs` | `  3.12 µs` |
+| yup          | `  5.48 µs/iter` | `  5.35 µs` | `  5.48 µs` | `  5.72 µs` | `  6.15 µs` |
+
+| • object schema with an async rule, report all errors (invalid input) |              avg |         min |         p75 |         p99 |         max |
+| ------------ | ---------------- | ----------- | ----------- | ----------- | ----------- |
+| ivl          | `  1.85 µs/iter` | `  1.37 µs` | `  2.28 µs` | `  3.41 µs` | `  3.68 µs` |
+| ivl compiled | `  1.55 µs/iter` | `  1.14 µs` | `  2.14 µs` | `  2.27 µs` | `  2.53 µs` |
+| zod          | `  4.05 µs/iter` | `  3.42 µs` | `  4.66 µs` | `  4.77 µs` | `  4.80 µs` |
+| valibot      | `  3.10 µs/iter` | `  2.04 µs` | `  3.62 µs` | `  4.11 µs` | `  4.99 µs` |
+| yup          | ` 40.79 µs/iter` | ` 16.19 µs` | ` 62.34 µs` | ` 84.30 µs` | `705.87 µs` |
+
+**Caveats**
+
+
+- Error reports differ in detail: ivl returns the names of the failing rules, zod and valibot build an issue object per failure and copy the parsed value, and yup throws a ValidationError. The "report all errors" results on invalid input largely measure that cost; the "pass/fail" scenarios compare validation alone.
+- After a failed type check, zod and valibot skip the rest of that field, while ivl still runs every rule unless break_early is set.
+- In "pass/fail", valibot (v.is) and yup (isValidSync) stop at the first failure in the whole object; ivl (break_early) still checks every field, stopping within each; zod has no early-exit mode, so it runs safeParse and reads .success.
+- The "built-in email" scenario uses each library's own email regex, so it compares what you get out of the box rather than equal work; ivl's regex is simpler and looser than zod's.
+- Each benchmark cycles through 8 valid or 8 invalid inputs. The async rule resolves immediately, so the async scenario measures promise overhead, not I/O.
+<!-- benchmark:end -->

package/lib/core.d.ts

@@ -1,16 +1,35 @@
-import type { RULES, RULES_SYNC, SCHEMA, SCHEMA_SYNC, SCHEMA_OPTIONS, CHECKABLE_OBJECT, CHECKED_SCHEMA, CHECKED_SCHEMA_SYNC, RULES_KIND, SCHEMA_KIND, MAYBE_ASYNC } from './types';
 /**
- * Detect if a function is async or not
+ * Core validation functions: run rule sets against single values (`getValueErrors*`), run
+ * schemas against objects (`getSchemaErrors*`), and compile either into reusable validators
+ * (`compileRules`, `compileSchema`).
  *
- * @param {unknown} fn the function to inspect
- * @returns {boolean} true if `fn` is declared with the `async` keyword, otherwise false
+ * Shared semantics:
+ * - a rule passes when it returns a truthy value and fails when it returns a falsy value,
+ *   throws, or (on an async path) rejects - a failing rule never throws out of these functions
+ * - errors are the keys of the failing rules, in the rule set's key order
+ * - a rule is async only if it is declared with the `async` keyword; the plain `getValueErrors`
+ *   / `getSchemaErrors` / `compile*` functions use that to pick the sync or async path
+ * - any extra `overload` arguments are passed through to every rule after the value
+ *
+ * @module
+ */
+import type { RULES, RULES_SYNC, SCHEMA, SCHEMA_SYNC, SCHEMA_OPTIONS, RULES_OPTIONS, CHECKABLE_OBJECT, CHECKED_SCHEMA, CHECKED_SCHEMA_SYNC, RULES_KIND, SCHEMA_KIND, MAYBE_ASYNC, ANY_RULES, COMPILED_RULES, COMPILED_SCHEMA } from './types';
+/**
+ * Detect whether a value is a function declared with the `async` keyword.
+ *
+ * Only the declaration is inspected: a plain function that returns a promise is not async
+ * by this definition. Works across realms, since it compares the constructor's name.
+ *
+ * @param {unknown} fn the value to inspect
+ * @returns {boolean} `true` if `fn` is an `async` function, otherwise `false`
  */
 export declare const isAsyncFunction: (fn: unknown) => fn is (...args: never[]) => Promise<unknown>;
 /**
- * Detect if a RULES object has any async rules in it
+ * Detect whether a rule set, or any rule set in an array of alternatives, contains an
+ * `async` rule. This is the check `getValueErrors`/`getSchemaErrors` use to choose a path.
  *
- * @param {RULES|RULES[]} rules a rules object
- * @returns {boolean} true if any of the rules is an async function otherwise false
+ * @param {RULES|RULES[]} rules a rule set, or an array of alternative rule sets
+ * @returns {boolean} `true` if any rule is an `async` function, otherwise `false`
  */
 export declare const hasAsyncFunction: (rules: {
     [key: string]: unknown;
@@ -18,69 +37,136 @@ export declare const hasAsyncFunction: (rules: {
     [key: string]: unknown;
 }[]) => boolean;
 /**
- * Check the input against all provided validation rules asynchronously
+ * Validate a value against a rule set, always asynchronously.
  *
- * @param {V} value the value to check
- * @param {RULES<V>} rules rules object to use for validating the provided value
- * @param {unknown[]} overload array of extra values the validator rules might need to properly validate the value
- * @returns {Promise<string[]>} a list of rule names which failed validation
+ * Sync rules run inline and `async` rules run concurrently; a plain rule returning a promise
+ * is awaited too. A rule that returns a falsy value, throws or rejects fails. The returned
+ * promise never rejects.
+ *
+ * @template V type of the value being validated
+ * @param {V} value the value to validate
+ * @param {RULES<V>} rules the rule set; each key is the error reported when its rule fails
+ * @param {...unknown} overload extra arguments passed to every rule after the value
+ * @returns {Promise<string[]>} the keys of the failing rules, in rule order; empty if all passed
  */
 export declare const getValueErrorsAsync: <V>(value: V, rules: RULES<V>, ...overload: unknown[]) => Promise<string[]>;
 /**
- * Check a schema against all provided validation rules asynchronously
+ * Validate an object against a schema, always asynchronously.
+ *
+ * Each schema key's rule set is run against `object_to_check[key]` (a missing key is
+ * validated as `undefined`). An entry given as an array of alternative rule sets passes if
+ * any alternative passes. Fields whose rules are all sync are filled in immediately; only
+ * fields with pending promises are awaited, concurrently. The returned promise never rejects.
  *
- * @param {CHECKABLE_OBJECT} object_to_check object to be validated
- * @param {S} schema schema to validate against
- * @param {SCHEMA_OPTIONS} options options affecting how the rules are run
- * @param {unknown[]} overload array of extra values the validator rules might need to properly validate the value
- * @returns {CHECKED_SCHEMA<S>} an object containing keys and their respective lists of failed rule names
+ * @template S the schema type, used to infer the result's keys and shapes
+ * @param {CHECKABLE_OBJECT} object_to_check the object to validate
+ * @param {S} schema maps each key to a rule set, or to an array of alternative rule sets
+ * @param {SCHEMA_OPTIONS} [options] `strict: true` also reports keys of the object that the schema doesn't
+ * have; `break_early: true` reports only the first failing rule of each rule set
+ * @param {...unknown} overload extra arguments passed to every rule after the value
+ * @returns {CHECKED_SCHEMA<S>} an object with every schema key, in schema order: `string[]` of
+ * failing rule keys for a rule set, or for alternatives `[]` if any passed and otherwise one
+ * error list per alternative (`string[][]`). In strict mode, each unknown key follows with
+ * `['Key not allowed']`.
  */
 export declare const getSchemaErrorsAsync: <S extends SCHEMA>(object_to_check: CHECKABLE_OBJECT, schema: S, options?: SCHEMA_OPTIONS, ...overload: unknown[]) => CHECKED_SCHEMA<S>;
 /**
- * Check the input against all provided validation rules synchronously
+ * Validate a value against a rule set synchronously.
+ *
+ * A rule that returns a falsy value or throws fails. A rule that returns a promise also
+ * fails, because it can't be awaited here - use `getValueErrorsAsync` for those.
  *
- * @param {V} value the value to check
- * @param {RULES_SYNC<V>} rules rules object to use for validating the provided value
- * @param {unknown[]} overload array of extra values the validator rules might need to properly validate the value
- * @returns {string[]} a list of rule names which failed validation
+ * @template V type of the value being validated
+ * @param {V} value the value to validate
+ * @param {RULES_SYNC<V>} rules the rule set; each key is the error reported when its rule fails
+ * @param {...unknown} overload extra arguments passed to every rule after the value
+ * @returns {string[]} the keys of the failing rules, in rule order; empty if all passed
  */
 export declare const getValueErrorsSync: <V>(value: V, rules: RULES_SYNC<V>, ...overload: unknown[]) => string[];
 /**
- * Check a schema against all provided validation rules synchronously
+ * Validate an object against a schema synchronously.
  *
- * @param {CHECKABLE_OBJECT} object object to be validated
- * @param {S} schema schema to validate against
- * @param {SCHEMA_OPTIONS} options options affecting how the rules are run
- * @param {unknown[]} overload array of extra values the validator rules might need to properly validate the value
- * @returns {CHECKED_SCHEMA_SYNC<S>} an object containing keys and their respective lists of failed rule names
+ * Each schema key's rule set is run against `object[key]` (a missing key is validated as
+ * `undefined`), with the same rule semantics as `getValueErrorsSync`: a rule returning a
+ * promise fails. An entry given as an array of alternative rule sets passes if any
+ * alternative passes.
+ *
+ * @template S the schema type, used to infer the result's keys and shapes
+ * @param {CHECKABLE_OBJECT} object the object to validate
+ * @param {S} schema maps each key to a rule set, or to an array of alternative rule sets
+ * @param {SCHEMA_OPTIONS} [options] `strict: true` also reports keys of the object that the schema doesn't
+ * have; `break_early: true` reports only the first failing rule of each rule set
+ * @param {...unknown} overload extra arguments passed to every rule after the value
+ * @returns {CHECKED_SCHEMA_SYNC<S>} an object with every schema key, in schema order: `string[]`
+ * of failing rule keys for a rule set, or for alternatives `[]` if any passed and otherwise
+ * one error list per alternative (`string[][]`). In strict mode, each unknown key follows
+ * with `['Key not allowed']`.
  */
 export declare const getSchemaErrorsSync: <S extends SCHEMA_SYNC>(object: CHECKABLE_OBJECT, schema: S, options?: SCHEMA_OPTIONS, ...overload: unknown[]) => CHECKED_SCHEMA_SYNC<S>;
 /**
- * Check the input against all provided validation rules, choosing the sync or async
- * implementation based on whether any rule is an `async` function.
+ * Validate a value against a rule set, synchronously if no rule is an `async` function and
+ * asynchronously otherwise (see `getValueErrorsSync` / `getValueErrorsAsync`).
  *
- * The return type is inferred from the rules: all-sync rules yield `string[]`,
- * any `async` rule yields `Promise<string[]>`. Rules whose return type is declared
- * as `boolean | Promise<boolean>` (e.g. annotated as `RULE`) yield the union.
+ * The return type is inferred from the rules: all-sync rules give `string[]`, any `async`
+ * rule gives `Promise<string[]>`, and rules typed as returning `boolean | Promise<boolean>`
+ * (e.g. annotated as `RULE`) give the union. For a rule set used repeatedly,
+ * `compileRules` is faster.
  *
- * @param {V} value the value to check
- * @param {R} rules rules object to use for validating the provided value
- * @param {unknown[]} overload array of extra values the validator rules might need to properly validate the value
- * @returns {Promise<string[]>|string[]} a list of rule names which failed validation
+ * @template V type of the value being validated
+ * @template R the rule set type, used to infer sync or async
+ * @param {V} value the value to validate
+ * @param {R} rules the rule set; each key is the error reported when its rule fails
+ * @param {...unknown} overload extra arguments passed to every rule after the value
+ * @returns {string[]|Promise<string[]>} the keys of the failing rules, in rule order; empty if all passed
  */
 export declare const getValueErrors: <V, R extends RULES<V>>(value: V, rules: R, ...overload: unknown[]) => MAYBE_ASYNC<RULES_KIND<R>, string[]>;
 /**
- * Check a schema against all provided validation rules, choosing the sync or async
- * implementation based on whether any rule is an `async` function.
- *
- * The return type is inferred from the schema: all-sync rules yield the result object
- * directly, any `async` rule yields a `Promise` of it. Rules whose return type is declared
- * as `boolean | Promise<boolean>` (e.g. a schema annotated as `SCHEMA`) yield the union.
- *
- * @param {CHECKABLE_OBJECT} object object to be validated
- * @param {S} schema schema to validate against
- * @param {SCHEMA_OPTIONS} options options affecting how the rules are run
- * @param {unknown[]} overload array of extra values the validator rules might need to properly validate the value
- * @returns {CHECKED_SCHEMA<S>|CHECKED_SCHEMA_SYNC<S>} an object containing keys and their respective lists of failed rule names
+ * Validate an object against a schema, synchronously if no rule in the schema is an
+ * `async` function and asynchronously otherwise (see `getSchemaErrorsSync` /
+ * `getSchemaErrorsAsync` for the details and result shape).
+ *
+ * The return type is inferred from the schema: all-sync rules give the result object
+ * directly, any `async` rule gives a `Promise` of it, and rules typed as returning
+ * `boolean | Promise<boolean>` (e.g. a schema annotated as `SCHEMA`) give the union. For a
+ * schema used repeatedly, `compileSchema` is faster.
+ *
+ * @template S the schema type, used to infer sync or async and the result's keys and shapes
+ * @param {CHECKABLE_OBJECT} object the object to validate
+ * @param {S} schema maps each key to a rule set, or to an array of alternative rule sets
+ * @param {SCHEMA_OPTIONS} [options] `strict: true` also reports keys of the object that the schema doesn't
+ * have; `break_early: true` reports only the first failing rule of each rule set
+ * @param {...unknown} overload extra arguments passed to every rule after the value
+ * @returns {CHECKED_SCHEMA_SYNC<S>|CHECKED_SCHEMA<S>} the errors per key, or a promise of them
  */
 export declare const getSchemaErrors: <S extends SCHEMA>(object: CHECKABLE_OBJECT, schema: S, options?: SCHEMA_OPTIONS, ...overload: unknown[]) => MAYBE_ASYNC<SCHEMA_KIND<S>, CHECKED_SCHEMA_SYNC<S>>;
+/**
+ * Compile a rule set into a reusable validator that gives the same results as
+ * `getValueErrors(value, rules, ...overload)`, but does the key lookup and the sync/async
+ * check once here instead of on every call.
+ *
+ * The rule set is copied, so changes made to `rules` after compiling have no effect on the
+ * returned validator.
+ *
+ * @template R the rule set type; the validator's value parameter and sync/async return type come from it
+ * @param {R} rules the rule set; each key is the error reported when its rule fails
+ * @param {RULES_OPTIONS} [options] `break_early: true` reports only the first failing rule
+ * @returns {COMPILED_RULES<R>} `(value, ...overload) => string[]` if every rule is sync, otherwise
+ * an async function returning `Promise<string[]>`
+ */
+export declare const compileRules: <R extends ANY_RULES>(rules: R, options?: RULES_OPTIONS) => COMPILED_RULES<R>;
+/**
+ * Compile a schema into a reusable validator that gives the same results as
+ * `getSchemaErrors(object, schema, options, ...overload)`, but does the key lookups and the
+ * sync/async check once here instead of on every call.
+ *
+ * The schema, its rule sets and the options are copied, so changes made to them after
+ * compiling have no effect on the returned validator.
+ *
+ * @template S the schema type; the validator's sync/async return type and result shape come from it
+ * @param {S} schema maps each key to a rule set, or to an array of alternative rule sets
+ * @param {SCHEMA_OPTIONS} [options] `strict: true` also reports keys of the object that the schema doesn't
+ * have; `break_early: true` reports only the first failing rule of each rule set
+ * @returns {COMPILED_SCHEMA<S>} `(object, ...overload) => errors` if every rule is sync, otherwise
+ * an async function returning a promise of them; see `getSchemaErrorsSync` for the result shape
+ */
+export declare const compileSchema: <S extends SCHEMA>(schema: S, options?: SCHEMA_OPTIONS) => COMPILED_SCHEMA<S>;

package/lib/helpers/index.js

@@ -1 +1 @@
-var E=(n)=>typeof n==="string"||n!==null&&typeof n==="object"&&("length"in n)&&typeof n.length==="number",a=(n)=>(e)=>typeof e===n,i=(n)=>(e)=>typeof e==="string"&&n.test(e),S=(n=1/0)=>(e)=>typeof e==="number"&&e<=n,l=(n=-1/0)=>(e)=>typeof e==="number"&&e>=n,C=(n=1/0)=>(e)=>E(e)&&e.length<=n,R=(n=0)=>(e)=>E(e)&&e.length>=n,f=(n=1/0,e=0)=>(t)=>typeof t==="string"&&t.length>=e&&t.length<=n,y=(n=1/0,e=-1/0)=>(t)=>typeof t==="number"&&t>=e&&t<=n,w=(n)=>(e)=>e===n||Number.isNaN(n)&&Number.isNaN(e),p=(n=[])=>{let e=new Set(n);return(t)=>e.has(t)},k=()=>(n)=>Number.isInteger(n),_=()=>(n)=>Array.isArray(n),N=(n)=>(e)=>e instanceof n,O=(n)=>(e,...t)=>{try{return!n(e,...t)}catch{return!0}},m=(n)=>async(e,...t)=>{try{return!await n(e,...t)}catch{return!0}},A=(n)=>(e,...t)=>{if(!Array.isArray(e))return!1;for(let o=0;o<e.length;o++)if(!n(e[o],...t))return!1;return!0},U=(n)=>async(e,...t)=>{if(!Array.isArray(e))return!1;for(let o=0;o<e.length;o++)if(!await n(e[o],...t))return!1;return!0},L=(n=[])=>async(e,...t)=>(await Promise.all(n.map((o)=>o(e,...t)))).some((o)=>o),g=(n=[])=>(e,...t)=>n.map((o)=>o(e,...t)).some((o)=>o);var c=(n)=>typeof n==="function"&&n.constructor.name==="AsyncFunction";var u=(n,e)=>Object.fromEntries(Object.entries(n).map(([t,o])=>[t,c(o)?async(s,...r)=>e(o,s,r):(s,...r)=>e(o,s,r)])),d=(n)=>u(n,(e,t,o)=>typeof t>"u"?!0:e(t,...o)),b=(n)=>u(n,(e,t,o)=>t===null?!0:e(t,...o)),H=(n,e)=>u(e,(t,o,s)=>t(n(o),...s));export{L as acceptAnyAsync,g as acceptAnySync,b as allowNull,d as allowUndefined,w as equals,U as everyElementAsync,A as everyElementSync,_ as isArray,N as isInstanceOf,k as isInteger,p as isOneOf,a as isType,i as matchesRegex,S as max,C as maxLength,l as min,R as minLength,m as notAsync,O as notSync,y as numberBetween,H as preprocess,f as stringBetween};
+var u=(n)=>typeof n==="string"||n!==null&&typeof n==="object"&&("length"in n)&&typeof n.length==="number",c=(n)=>(e)=>typeof e===n,l=(n)=>(e)=>typeof e==="string"&&n.test(e),a=(n=1/0)=>(e)=>typeof e==="number"&&e<=n,S=(n=-1/0)=>(e)=>typeof e==="number"&&e>=n,f=(n=1/0)=>(e)=>u(e)&&e.length<=n,C=(n=0)=>(e)=>u(e)&&e.length>=n,y=(n=1/0,e=0)=>(t)=>typeof t==="string"&&t.length>=e&&t.length<=n,k=(n=1/0,e=-1/0)=>(t)=>typeof t==="number"&&t>=e&&t<=n,R=(n)=>(e)=>e===n||Number.isNaN(n)&&Number.isNaN(e),_=(n=[])=>{let e=new Set(n);return(t)=>e.has(t)},w=()=>(n)=>Number.isInteger(n),g=()=>(n)=>Array.isArray(n),L=(n)=>(e)=>e instanceof n,A=(n)=>(e,...t)=>{try{return!n(e,...t)}catch{return!0}},p=(n)=>async(e,...t)=>{try{return!await n(e,...t)}catch{return!0}},O=(n)=>(e,...t)=>{if(!Array.isArray(e))return!1;for(let r=0;r<e.length;r++)if(!n(e[r],...t))return!1;return!0},m=(n)=>async(e,...t)=>{if(!Array.isArray(e))return!1;for(let r=0;r<e.length;r++)if(!await n(e[r],...t))return!1;return!0},U=(n=[])=>async(e,...t)=>(await Promise.all(n.map((r)=>r(e,...t)))).some((r)=>r),N=(n=[])=>(e,...t)=>n.map((r)=>r(e,...t)).some((r)=>r);var E=(n)=>typeof n==="function"&&n.constructor.name==="AsyncFunction";var i=(n,e)=>Object.fromEntries(Object.entries(n).map(([t,r])=>[t,E(r)?async(s,...o)=>e(r,s,o):(s,...o)=>e(r,s,o)])),M=(n)=>i(n,(e,t,r)=>typeof t>"u"?!0:e(t,...r)),P=(n)=>i(n,(e,t,r)=>t===null?!0:e(t,...r)),x=(n,e)=>i(e,(t,r,s)=>t(n(r),...s));export{U as acceptAnyAsync,N as acceptAnySync,P as allowNull,M as allowUndefined,R as equals,m as everyElementAsync,O as everyElementSync,g as isArray,L as isInstanceOf,w as isInteger,_ as isOneOf,c as isType,l as matchesRegex,a as max,f as maxLength,S as min,C as minLength,p as notAsync,A as notSync,k as numberBetween,x as preprocess,y as stringBetween};

package/lib/helpers/rules.d.ts

@@ -1,39 +1,189 @@
+/**
+ * Rule helpers: factories that build common rules, and combinators that modify or combine
+ * existing rules. Every factory returns a new rule, so the result can be used directly as a
+ * value in a rule set, e.g. `{ "Too long": maxLength(100) }`.
+ *
+ * @module
+ */
 import type { RULE, RULE_ASYNC, RULE_SYNC } from '../types';
+/** Every string the `typeof` operator can return. */
 export type TYPEOF_RESULT = "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function";
+/**
+ * Rule: passes if `typeof value === type`. Note that `typeof null` is `'object'`, so
+ * `isType('object')` passes `null`, and `typeof NaN` is `'number'`.
+ *
+ * @param {TYPEOF_RESULT} type the expected `typeof` result
+ * @returns {RULE_SYNC} the rule
+ */
 export declare const isType: (type: TYPEOF_RESULT) => RULE_SYNC;
+/**
+ * Rule: passes if the value is a string that `regex` matches. Non-strings fail.
+ *
+ * The regex is used as given, so one with the `g` or `y` flag is stateful: `test` moves its
+ * `lastIndex`, and repeated calls can alternate between passing and failing. Use regexes
+ * without those flags.
+ *
+ * @param {RegExp} regex the pattern to test strings against
+ * @returns {RULE_SYNC} the rule
+ */
 export declare const matchesRegex: (regex: RegExp) => RULE_SYNC;
+/**
+ * Rule: passes if the value is a number less than or equal to `max_value`. Non-numbers
+ * (including bigints) and `NaN` fail.
+ *
+ * @param {number} [max_value=Infinity] the inclusive upper bound
+ * @returns {RULE_SYNC} the rule
+ */
 export declare const max: (max_value?: number) => RULE_SYNC;
+/**
+ * Rule: passes if the value is a number greater than or equal to `min_value`. Non-numbers
+ * (including bigints) and `NaN` fail.
+ *
+ * @param {number} [min_value=-Infinity] the inclusive lower bound
+ * @returns {RULE_SYNC} the rule
+ */
 export declare const min: (min_value?: number) => RULE_SYNC;
+/**
+ * Rule: passes if the value has a numeric `length` (a string, array, or object with a
+ * numeric `length`) of at most `max_length`. Values without one fail.
+ *
+ * @param {number} [max_length=Infinity] the inclusive maximum length
+ * @returns {RULE_SYNC} the rule
+ */
 export declare const maxLength: (max_length?: number) => RULE_SYNC;
+/**
+ * Rule: passes if the value has a numeric `length` (a string, array, or object with a
+ * numeric `length`) of at least `min_length`. Values without one fail, even with the
+ * default of `0`.
+ *
+ * @param {number} [min_length=0] the inclusive minimum length
+ * @returns {RULE_SYNC} the rule
+ */
 export declare const minLength: (min_length?: number) => RULE_SYNC;
+/**
+ * Rule: passes if the value is a string whose length is between `min` and `max`, inclusive.
+ * Note the argument order: the maximum comes first.
+ *
+ * @param {number} [max=Infinity] the inclusive maximum length
+ * @param {number} [min=0] the inclusive minimum length
+ * @returns {RULE_SYNC} the rule
+ */
 export declare const stringBetween: (max?: number, min?: number) => RULE_SYNC;
+/**
+ * Rule: passes if the value is a number between `min` and `max`, inclusive. Non-numbers
+ * and `NaN` fail. Note the argument order: the maximum comes first.
+ *
+ * @param {number} [max=Infinity] the inclusive upper bound
+ * @param {number} [min=-Infinity] the inclusive lower bound
+ * @returns {RULE_SYNC} the rule
+ */
 export declare const numberBetween: (max?: number, min?: number) => RULE_SYNC;
-/** Equality using SameValueZero semantics (`===`, except `NaN` equals `NaN`) - the same comparison `isOneOf` uses. */
+/**
+ * Rule: passes if the value equals `expected` under SameValueZero semantics (`===`, except
+ * `NaN` equals `NaN`) - the same comparison `isOneOf` uses. Objects compare by reference.
+ *
+ * @param {unknown} expected the value to compare against
+ * @returns {RULE_SYNC} the rule
+ */
 export declare const equals: (expected: unknown) => RULE_SYNC;
-/** Membership in `allowed_values`, using SameValueZero semantics - the same comparison `equals` uses. */
+/**
+ * Rule: passes if the value is one of `allowed_values`, using SameValueZero semantics - the
+ * same comparison `equals` uses. The values are copied into a `Set` when the rule is created,
+ * so later changes to the array have no effect.
+ *
+ * @param {unknown[]} [allowed_values=[]] the accepted values; with none, every value fails
+ * @returns {RULE_SYNC} the rule
+ */
 export declare const isOneOf: (allowed_values?: unknown[]) => RULE_SYNC;
+/**
+ * Rule: passes if the value is a number with no fractional part (`Number.isInteger`).
+ * Bigints, numeric strings, `NaN` and `Infinity` fail.
+ *
+ * @returns {RULE_SYNC} the rule
+ */
 export declare const isInteger: () => RULE_SYNC;
+/**
+ * Rule: passes if the value is an array (`Array.isArray`).
+ *
+ * @returns {RULE_SYNC} the rule
+ */
 export declare const isArray: () => RULE_SYNC;
+/**
+ * Rule: passes if `value instanceof constructor`. Like `instanceof`, this checks the
+ * prototype chain, so it fails for objects from another realm (e.g. an iframe).
+ *
+ * @param {Function} constructor the class or constructor function to check against
+ * @returns {RULE_SYNC} the rule
+ */
 export declare const isInstanceOf: (constructor: abstract new (...args: never[]) => unknown) => RULE_SYNC;
-/** Inverts the given rule; a throwing rule counts as failed, so its negation passes. The rule must be synchronous. */
+/**
+ * Combinator: inverts a synchronous rule. A throwing rule counts as failed, so its negation
+ * passes. The rule must be synchronous: a returned promise is truthy, so the negation fails.
+ *
+ * @template V type of the value being validated
+ * @template O tuple type of the overload arguments, passed through to `rule`
+ * @param {RULE_SYNC<V, O>} rule the rule to invert
+ * @returns {RULE_SYNC<V, O>} the inverted rule
+ */
 export declare const notSync: <V = unknown, O extends unknown[] = unknown[]>(rule: RULE_SYNC<V, O>) => RULE_SYNC<V, O>;
 /**
- * Inverts the given rule; a throwing/rejecting rule counts as failed, so its negation passes.
- * Always async - a single async rule switches the whole rule set onto the async execution
- * path, so prefer `notSync` unless the wrapped rule is genuinely async.
+ * Combinator: inverts a sync or async rule. A throwing or rejecting rule counts as failed, so
+ * its negation passes. Always async - a single async rule switches the whole rule set onto the
+ * async execution path, so prefer `notSync` unless the wrapped rule is genuinely async.
+ *
+ * @template V type of the value being validated
+ * @template O tuple type of the overload arguments, passed through to `rule`
+ * @param {RULE<V, O>} rule the rule to invert
+ * @returns {RULE_ASYNC<V, O>} the inverted rule
  */
 export declare const notAsync: <V = unknown, O extends unknown[] = unknown[]>(rule: RULE<V, O>) => RULE_ASYNC<V, O>;
-/** Passes if the value is an array and every element (holes included) passes the given rule. Stops at the first failure. The rule must be synchronous. */
+/**
+ * Combinator: passes if the value is an array and every element (holes included, as
+ * `undefined`) passes `rule`. Stops at the first failing element; an empty array passes.
+ * A throwing element rule makes the whole rule fail. The rule must be synchronous: a
+ * returned promise is truthy, so that element passes.
+ *
+ * @template E type of the array elements the rule accepts
+ * @template O tuple type of the overload arguments, passed through to `rule`
+ * @param {RULE_SYNC<E, O>} rule the rule every element must pass
+ * @returns {RULE_SYNC<unknown, O>} the array rule
+ */
 export declare const everyElementSync: <E = unknown, O extends unknown[] = unknown[]>(rule: RULE_SYNC<E, O>) => RULE_SYNC<unknown, O>;
 /**
- * Passes if the value is an array and every element (holes included) passes the given rule.
- * Elements are checked sequentially, stopping at the first failure, so an early invalid
- * element in an attacker-sized array doesn't fan out rule calls for the rest of it.
+ * Combinator: passes if the value is an array and every element (holes included, as
+ * `undefined`) passes `rule`, which may be sync or async; an empty array passes. Elements are
+ * checked one at a time, stopping at the first failure, so an early invalid element in an
+ * attacker-sized array doesn't fan out rule calls for the rest of it. A throwing or rejecting
+ * element rule makes the whole rule fail.
  * Always async - a single async rule switches the whole rule set onto the async execution
  * path, so prefer `everyElementSync` unless the element rule is genuinely async.
+ *
+ * @template E type of the array elements the rule accepts
+ * @template O tuple type of the overload arguments, passed through to `rule`
+ * @param {RULE<E, O>} rule the rule every element must pass
+ * @returns {RULE_ASYNC<unknown, O>} the array rule
  */
 export declare const everyElementAsync: <E = unknown, O extends unknown[] = unknown[]>(rule: RULE<E, O>) => RULE_ASYNC<unknown, O>;
-/** Passes if *any* of the given rules passes. Always async. */
+/**
+ * Combinator: passes if *any* of the given rules passes. All rules run concurrently and every
+ * one is awaited, even after one has passed. If any rule throws or rejects, the combined rule
+ * fails, even when another rule passed. With no rules, it fails. Always async.
+ *
+ * @template V type of the value being validated
+ * @template O tuple type of the overload arguments, passed through to every rule
+ * @param {RULE<V, O>[]} [rules=[]] the alternatives, sync or async
+ * @returns {RULE_ASYNC<V, O>} the combined rule
+ */
 export declare const acceptAnyAsync: <V = unknown, O extends unknown[] = unknown[]>(rules?: RULE<V, O>[]) => RULE_ASYNC<V, O>;
-/** Passes if *any* of the given rules passes. All rules must be synchronous. */
+/**
+ * Combinator: passes if *any* of the given rules passes. Every rule runs, even after one has
+ * passed. If any rule throws, the combined rule fails, even when another rule passed. With no
+ * rules, it fails. All rules must be synchronous: a returned promise is truthy, so it counts
+ * as passing.
+ *
+ * @template V type of the value being validated
+ * @template O tuple type of the overload arguments, passed through to every rule
+ * @param {RULE_SYNC<V, O>[]} [rules=[]] the alternatives
+ * @returns {RULE_SYNC<V, O>} the combined rule
+ */
 export declare const acceptAnySync: <V = unknown, O extends unknown[] = unknown[]>(rules?: RULE_SYNC<V, O>[]) => RULE_SYNC<V, O>;

package/lib/helpers/schema.d.ts

@@ -1,29 +1,59 @@
+/**
+ * Rule set helpers: wrap every rule in a rule set at once, typically for use as a schema
+ * entry, e.g. `{ website: allowUndefined(URL_RULES) }`.
+ *
+ * @module
+ */
 import type { RULES } from '../types';
 /**
- * Re-declares each rule so that the parameters of the returned rule are `V` instead of the
- * original rule's parameters, while keeping the original return type (sync stays sync,
- * async stays async).
+ * Re-declares each rule so that the value parameter of the returned rule is `V` instead of
+ * the original rule's, while keeping its overload parameters and its return type (sync stays
+ * sync, async stays async).
+ *
+ * @template R the original rule set
+ * @template V the new value type
  */
 type REWRAPPED<R extends RULES<never>, V> = {
     [K in keyof R]: R[K] extends (value: never, ...overload: infer O) => infer Ret ? (value: V, ...overload: O) => Ret : never;
 };
 /**
- * Wraps every rule so that an `undefined` value always passes.
+ * Wrap every rule in a rule set so that an `undefined` value passes without calling it,
+ * making the field optional. Other values are validated as before.
+ *
  * Sync rules stay sync and async rules stay async, so `getValueErrors`/`getSchemaErrors`
  * still pick the correct execution path.
+ *
+ * @template R the rule set type, preserved in the result
+ * @param {R} rules the rule set to wrap; it is not modified
+ * @returns {R} a new rule set with the same keys
  */
 export declare const allowUndefined: <R extends RULES>(rules: R) => R;
 /**
- * Wraps every rule so that a `null` value always passes.
+ * Wrap every rule in a rule set so that a `null` value passes without calling it. Other
+ * values (including `undefined`) are validated as before.
+ *
  * Sync rules stay sync and async rules stay async, so `getValueErrors`/`getSchemaErrors`
  * still pick the correct execution path.
+ *
+ * @template R the rule set type, preserved in the result
+ * @param {R} rules the rule set to wrap; it is not modified
+ * @returns {R} a new rule set with the same keys
  */
 export declare const allowNull: <R extends RULES>(rules: R) => R;
 /**
- * Wraps every rule so that the value is passed through `fn` before being validated.
- * The rules may be typed against the *output* of `fn`; the returned rules accept `unknown`.
- * Sync rules stay sync and async rules stay async, so `getValueErrors`/`getSchemaErrors`
- * still pick the correct execution path.
+ * Wrap every rule in a rule set so that each rule validates `fn(value)` instead of the value,
+ * e.g. to trim or parse it first. The original value is not changed.
+ *
+ * `fn` is called separately for each rule, so it should be cheap and free of side effects.
+ * If it throws, every rule it was called for fails. The rules may be typed against the
+ * *output* of `fn`; the returned rules accept `unknown`. Sync rules stay sync and async
+ * rules stay async.
+ *
+ * @template V the type `fn` returns
+ * @template R the rule set type
+ * @param {Function} fn transforms the value before each rule sees it
+ * @param {R} rules the rule set to wrap; it is not modified
+ * @returns {REWRAPPED<R, unknown>} a new rule set with the same keys, accepting `unknown`
  */
 export declare const preprocess: <V, R extends RULES<V>>(fn: (value: unknown) => V, rules: R) => REWRAPPED<R, unknown>;
 export {};

package/lib/index.js

@@ -1 +1 @@
-var f={strict:!1};var C=(e)=>typeof e==="function"&&e.constructor.name==="AsyncFunction",A=(e)=>{if(Array.isArray(e))return e.some((r)=>Object.values(r).some(C));return Object.values(e).some(C)},l=async(e,r,...E)=>{let t={},s=[];for(let[n,S]of Object.entries(r)){if(t[n]=!1,C(S)){s.push(S(e,...E).then((o)=>{t[n]=Boolean(o)}).catch(()=>{t[n]=!1}));continue}try{let o=S(e,...E);if(o!==null&&(typeof o==="object"||typeof o==="function")&&typeof o.then==="function")s.push(Promise.resolve(o).then((i)=>{t[n]=Boolean(i)}).catch(()=>{t[n]=!1}));else t[n]=Boolean(o)}catch{t[n]=!1}}if(s.length)await Promise.allSettled(s);let c=[];for(let[n,S]of Object.entries(t))if(!S)c.push(n);return c},y=async(e,r,E=f,...t)=>{let s={},c=[];if(Object.entries(r).forEach(([n,S])=>{let o;if(Array.isArray(S))o=Promise.allSettled(S.map((i)=>l(e[n],i,...t))).then((i)=>{let _=i.map((a)=>{if(a.status==="fulfilled")return a.value;return["Unknown error occurred"]});if(_.some((a)=>!a.length))s[n]=[];else s[n]=_}).catch((i)=>{if(i instanceof Error)s[n]=[i.message];else s[n]=["Unknown error occurred"]});else o=l(e[n],S,...t).then((i)=>{s[n]=i}).catch((i)=>{s[n]=[i instanceof Error?i.message:"Unknown error occurred"]});c.push(o)}),E.strict){let n=Object.keys(e),S=new Set(Object.keys(r));n.filter((i)=>!S.has(i)).forEach((i)=>{s[i]=["Key not allowed"]})}return await Promise.allSettled(c),s},u=(e,r,...E)=>{let t=[];for(let[s,c]of Object.entries(r))try{let n=c(e,...E);if(n!==null&&(typeof n==="object"||typeof n==="function")&&typeof n.then==="function")t.push(s);else if(!n)t.push(s)}catch(n){t.push(s)}return t},N=(e,r,E=f,...t)=>{let s={};for(let[c,n]of Object.entries(r))if(Array.isArray(n)){let S=n.map((o)=>u(e[c],o,...t));s[c]=S.some((o)=>!o.length)?[]:S}else s[c]=u(e[c],n,...t);if(E.strict){let c=Object.keys(e),n=new Set(Object.keys(r));c.filter((o)=>!n.has(o)).forEach((o)=>{s[o]=["Key not allowed"]})}return s},O=(e,r,...E)=>A(r)?l(e,r,...E):u(e,r,...E),H=(e)=>Object.values(e).some(A),m=(e,r,E=f,...t)=>H(r)?y(e,r,E,...t):N(e,r,E,...t);export{m as getSchemaErrors,y as getSchemaErrorsAsync,N as getSchemaErrorsSync,O as getValueErrors,l as getValueErrorsAsync,u as getValueErrorsSync,A as hasAsyncFunction,C as isAsyncFunction};
+var A={strict:!1,break_early:!1},w=(n)=>typeof n==="function"&&n.constructor.name==="AsyncFunction",L=(n)=>{let e=Object.keys(n);for(let t=0;t<e.length;t++)if(w(n[e[t]]))return!0;return!1},R=(n)=>{if(Array.isArray(n)){for(let e=0;e<n.length;e++)if(L(n[e]))return!0;return!1}return L(n)},f=(n)=>n!==null&&(typeof n==="object"||typeof n==="function")&&typeof n.then==="function",k=(n,e,t)=>t.length?n(e,...t):n(e),M=(n,e,t,i=Object.keys(e),E=!1)=>{let s=[];for(let l=0;l<i.length;l++){let r=i[l];try{let o=k(e[r],n,t);if(!o||f(o))s.push(r)}catch{s.push(r)}if(E&&s.length)return s}return s},y=(n,e,t,i=Object.keys(e),E=!1)=>{if(E)return N(n,e,t,i);let s=Array(i.length),l,r=(S,u)=>{s[S]=!1,(l??=[]).push(Promise.resolve(u).then((c)=>{s[S]=Boolean(c)},()=>{s[S]=!1}))};for(let S=0;S<i.length;S++){let u=e[i[S]];try{let c=k(u,n,t);if(f(c))r(S,c);else s[S]=Boolean(c)}catch{s[S]=!1}}let o=()=>{let S=[];for(let u=0;u<i.length;u++)if(!s[u])S.push(i[u]);return S};return l?Promise.all(l).then(o):o()},p=(n)=>{Promise.resolve(n).then(void 0,()=>{})},N=(n,e,t,i)=>{let E,s;for(let r=0;r<i.length;r++){let o=e[i[r]];if(w(o)){(E??=[]).push(r);continue}let S;try{S=k(o,n,t)}catch{S=!1}if(f(S))(s??=[]).push([r,S]);else if(!S){if(s)s.forEach(([,u])=>p(u));return[i[r]]}}if(!E&&!s)return[];let l=s??[];if(E)for(let r of E)l.push([r,k(e[i[r]],n,t)]);return Promise.all(l.map(([r,o])=>Promise.resolve(o).then((S)=>S?-1:r,()=>r))).then((r)=>{let o=-1;for(let S of r)if(S!==-1&&(o===-1||S<o))o=S;return o===-1?[]:[i[o]]})},g=(n)=>{for(let e=0;e<n.length;e++)if(!n[e].length)return[];return n},O=(n,e,t)=>{let i=Object.keys(e);for(let E=0;E<i.length;E++){let s=i[E];if(!Object.hasOwn(t,s))n[s]=["Key not allowed"]}},m=async(n,e,...t)=>y(n,e,t),D=async(n,e,t=A,...i)=>{let E={},s=[],l=Object.keys(e);for(let r=0;r<l.length;r++){let o=l[r],S=e[o],u=n[o];if(Array.isArray(S)){let c=S.map((a)=>y(u,a,i,void 0,t.break_early));if(c.some(f))E[o]=[],s.push(Promise.all(c).then((a)=>{E[o]=g(a)}));else E[o]=g(c)}else{let c=y(u,S,i,void 0,t.break_early);if(f(c))E[o]=[],s.push(c.then((a)=>{E[o]=a}));else E[o]=c}}if(t.strict)O(E,n,e);if(s.length)await Promise.all(s);return E},U=(n,e,...t)=>M(n,e,t),d=(n,e,t,i)=>{let E={},s=Object.keys(e);for(let l=0;l<s.length;l++){let r=s[l],o=e[r];if(Array.isArray(o)){let S=Array(o.length);for(let u=0;u<o.length;u++)S[u]=M(n[r],o[u],i,void 0,t.break_early);E[r]=g(S)}else E[r]=M(n[r],o,i,void 0,t.break_early)}if(t.strict)O(E,n,e);return E},Y=(n,e,t=A,...i)=>d(n,e,t,i),I=(n,e,...t)=>L(e)?m(n,e,...t):M(n,e,t),P=(n)=>{let e=Object.keys(n);for(let t=0;t<e.length;t++)if(R(n[e[t]]))return!0;return!1},T=(n,e,t=A,...i)=>P(e)?D(n,e,t,...i):d(n,e,t,i),h=(n,e,t,i)=>{let E=[],{keys:s,fns:l}=e;for(let r=0;r<l.length;r++){try{let o=k(l[r],n,t);if(!o||f(o))E.push(s[r])}catch{E.push(s[r])}if(i&&E.length)return E}return E},H=(n)=>{let e={...n},t=Object.keys(e);return{keys:t,rules:e,fns:t.map((i)=>e[i])}},B=(n,e=A)=>{let t=H(n),i=Boolean(e.break_early);if(L(t.rules))return async(E,...s)=>y(E,t.rules,s,t.keys,i);return(E,...s)=>h(E,t,s,i)},K=(n,e=A)=>{let t=Object.keys(n).map((s)=>{let l=n[s];return Array.isArray(l)?{key:s,set:void 0,alternatives:l.map(H)}:{key:s,set:H(l),alternatives:void 0}}),i=e.strict?{...n}:void 0,E=Boolean(e.break_early);if(!P(n))return(s,...l)=>{let r={};for(let o=0;o<t.length;o++){let{key:S,set:u,alternatives:c}=t[o];if(u)r[S]=h(s[S],u,l,E);else{let a=Array(c.length);for(let C=0;C<c.length;C++)a[C]=h(s[S],c[C],l,E);r[S]=g(a)}}if(i)O(r,s,i);return r};return async(s,...l)=>{let r={},o=[];for(let S=0;S<t.length;S++){let{key:u,set:c,alternatives:a}=t[S];if(c){let C=y(s[u],c.rules,l,c.keys,E);if(f(C))r[u]=[],o.push(C.then((_)=>{r[u]=_}));else r[u]=C}else{let C=a.map((_)=>y(s[u],_.rules,l,_.keys,E));if(C.some(f))r[u]=[],o.push(Promise.all(C).then((_)=>{r[u]=g(_)}));else r[u]=g(C)}}if(i)O(r,s,i);if(o.length)await Promise.all(o);return r}};export{B as compileRules,K as compileSchema,T as getSchemaErrors,D as getSchemaErrorsAsync,Y as getSchemaErrorsSync,I as getValueErrors,m as getValueErrorsAsync,U as getValueErrorsSync,R as hasAsyncFunction,w as isAsyncFunction};

package/lib/patterns/index.d.ts

@@ -1 +1,2 @@
 export * from './patterns';
+export * from './rule-sets';

package/lib/patterns/index.js

@@ -1 +1 @@
-var E=/^[\w.%+-]+@[\w.-]+\.[a-zA-Z]{1,}$/,t=/^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})$/,_=/^(https?:\/\/)?([^\s$.?#].[^\s]*)\.[a-z]{2,}(\/[^ \t\r\n\v\f]*)?$/i,o=/^(\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d(?:\.\d+)?(?:[+-][0-2]\d:[0-5]\d|Z)?)$/,R=/^(\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d(?::[0-5]\d(?:\.\d+)?)?)$/,a=/^(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(Z|[+-](?:2[0-3]|[01][0-9]):([0-5][0-9]))?$/,d=/^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/,T=(A)=>`[0-9a-f]{8}-[0-9a-f]{4}-${A}[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}`;var f=new RegExp(`^(?:${T("[1-8]")}|0{8}-0{4}-0{4}-0{4}-0{12}|f{8}-f{4}-f{4}-f{4}-f{12})$`,"i"),e=new RegExp(`^${T("4")}$`,"i"),n=new RegExp("^(?:(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)\\.){3}(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)$"),p=new RegExp("^(?:"+["(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4}","(?:[0-9a-f]{1,4}:){1,7}:","(?:[0-9a-f]{1,4}:){1,6}:[0-9a-f]{1,4}","(?:[0-9a-f]{1,4}:){1,5}(?::[0-9a-f]{1,4}){1,2}","(?:[0-9a-f]{1,4}:){1,4}(?::[0-9a-f]{1,4}){1,3}","(?:[0-9a-f]{1,4}:){1,3}(?::[0-9a-f]{1,4}){1,4}","(?:[0-9a-f]{1,4}:){1,2}(?::[0-9a-f]{1,4}){1,5}","[0-9a-f]{1,4}:(?::[0-9a-f]{1,4}){1,6}",":(?:(?::[0-9a-f]{1,4}){1,7}|:)","::(?:ffff(?::0{1,4})?:)?(?:(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)\\.){3}(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)","(?:[0-9a-f]{1,4}:){1,4}:(?:(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)\\.){3}(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)"].join("|")+")$","i"),P=/^[0-9a-f]{2}([:-])(?:[0-9a-f]{2}\1){4}[0-9a-f]{2}$/i,s=/^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i,x=/^[a-z0-9]+(-[a-z0-9]+)*$/,N=/^\+[1-9]\d{1,14}$/,r=/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/,c=/^([A-Za-z0-9+/]{4})*([A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}==)$/,I=/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/,S=/[a-z]/,C=/[A-Z]/,z=/\d/,O=/[^\w\s]/;export{c as BASE64_PATTERN,z as CONTAINS_DIGIT_CHARACTER_PATTERN,S as CONTAINS_LOWERCASE_CHARACTER_PATTERN,O as CONTAINS_SYMBOL_CHARACTER_PATTERN,C as CONTAINS_UPPERCASE_CHARACTER_PATTERN,N as E164_PHONE_PATTERN,E as EMAIL_PATTERN,s as HEX_COLOR_PATTERN,n as IPV4_PATTERN,p as IPV6_PATTERN,R as ISO_8601_DATETIME_PATTERN,o as ISO_8601_DATETIME_PATTERN_STRICT,d as ISO_8601_DATE_PATTERN,a as ISO_8601_TIME_PATTERN,I as JWT_PATTERN,P as MAC_ADDRESS_PATTERN,t as MYSQL_TIMESTAMP_PATTERN,r as SEMVER_PATTERN,x as SLUG_PATTERN,_ as URL_PATTERN,f as UUID_PATTERN,e as UUID_V4_PATTERN};
+var _=/^[\w.%+-]+@[\w.-]+\.[a-zA-Z]{1,}$/,z=/^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})$/,S=/^(https?:\/\/)?([^\s$.?#].[^\s]*)\.[a-z]{2,}(\/[^ \t\r\n\v\f]*)?$/i,T=/^(\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d(?:\.\d+)?(?:[+-][0-2]\d:[0-5]\d|Z)?)$/,v=/^(\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d(?::[0-5]\d(?:\.\d+)?)?)$/,A=/^(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(Z|[+-](?:2[0-3]|[01][0-9]):([0-5][0-9]))?$/,c=/^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/,u=(n)=>`[0-9a-f]{8}-[0-9a-f]{4}-${n}[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}`;var N=new RegExp(`^(?:${u("[1-8]")}|0{8}-0{4}-0{4}-0{4}-0{12}|f{8}-f{4}-f{4}-f{4}-f{12})$`,"i"),d=new RegExp(`^${u("4")}$`,"i"),p=new RegExp("^(?:(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)\\.){3}(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)$"),U=new RegExp("^(?:"+["(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4}","(?:[0-9a-f]{1,4}:){1,7}:","(?:[0-9a-f]{1,4}:){1,6}:[0-9a-f]{1,4}","(?:[0-9a-f]{1,4}:){1,5}(?::[0-9a-f]{1,4}){1,2}","(?:[0-9a-f]{1,4}:){1,4}(?::[0-9a-f]{1,4}){1,3}","(?:[0-9a-f]{1,4}:){1,3}(?::[0-9a-f]{1,4}){1,4}","(?:[0-9a-f]{1,4}:){1,2}(?::[0-9a-f]{1,4}){1,5}","[0-9a-f]{1,4}:(?::[0-9a-f]{1,4}){1,6}",":(?:(?::[0-9a-f]{1,4}){1,7}|:)","::(?:ffff(?::0{1,4})?:)?(?:(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)\\.){3}(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)","(?:[0-9a-f]{1,4}:){1,4}:(?:(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)\\.){3}(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)"].join("|")+")$","i"),i=/^[0-9a-f]{2}([:-])(?:[0-9a-f]{2}\1){4}[0-9a-f]{2}$/i,L=/^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i,C=/^[a-z0-9]+(-[a-z0-9]+)*$/,f=/^\+[1-9]\d{1,14}$/,x=/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/,l=/^([A-Za-z0-9+/]{4})*([A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}==)$/,O=/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/,I=/[a-z]/,P=/[A-Z]/,y=/\d/,m=/[^\w\s]/;var b=(n)=>typeof n==="string"||n!==null&&typeof n==="object"&&("length"in n)&&typeof n.length==="number",s=(n)=>(e)=>typeof e===n,o=(n)=>(e)=>typeof e==="string"&&n.test(e);var R=(n=1/0)=>(e)=>b(e)&&e.length<=n,w=(n=0)=>(e)=>b(e)&&e.length>=n;var a="Must be a string",t=(n,e)=>Object.freeze({[a]:s("string"),[n]:o(e)}),k=(n,e,E)=>{let r=new Date(0);return r.setUTCFullYear(n,e-1,E),r.getUTCFullYear()===n&&r.getUTCMonth()===e-1&&r.getUTCDate()===E},Y=(n)=>{let[e,E,r]=n.slice(0,10).split("-").map(Number);return k(e,E,r)},V=/([+-])(\d\d):\d\d$/,h=(n)=>{let e=V.exec(n.slice(19))?.[2];return Y(n)&&Number(n.slice(11,13))<24&&(e===void 0||Number(e)<24)},g=254,M=128,B=Object.freeze({[a]:s("string"),[`Must be at most ${g} characters`]:R(g),"Must be a valid email address":o(_)}),j=t("Must be a valid URL",S),F=t("Must be a valid UUID",N),X=t("Must be a valid version 4 UUID",d),J=t("Must be a valid IPv4 address",p),q=t("Must be a valid IPv6 address",U),Q=t("Must be a valid MAC address",i),K=t("Must be a valid hex color",L),nn=t("Must be a valid slug",C),en=t("Must be a valid E.164 phone number",f),tn=t("Must be a valid semantic version",x),on=t("Must be valid base64",l),rn=t("Must be a valid JWT",O),sn=t("Must be a valid ISO 8601 time",A),an=Object.freeze({[a]:s("string"),"Must be a valid ISO 8601 date":(n)=>typeof n==="string"&&c.test(n)&&Y(n)}),En=Object.freeze({[a]:s("string"),"Must be a valid ISO 8601 date and time":(n)=>typeof n==="string"&&T.test(n)&&h(n)}),D=Object.freeze({[a]:s("string"),"Must be at least 8 characters":w(8),[`Must be at most ${M} characters`]:R(M),"Must contain at least one lower case character":o(I),"Must contain at least one upper case character":o(P)}),Rn=Object.freeze({...D,"Must contain at least one digit":o(y),"Must contain at least one symbol":o(m)});export{l as BASE64_PATTERN,on as BASE64_RULES,y as CONTAINS_DIGIT_CHARACTER_PATTERN,I as CONTAINS_LOWERCASE_CHARACTER_PATTERN,m as CONTAINS_SYMBOL_CHARACTER_PATTERN,P as CONTAINS_UPPERCASE_CHARACTER_PATTERN,f as E164_PHONE_PATTERN,en as E164_PHONE_RULES,_ as EMAIL_PATTERN,B as EMAIL_RULES,L as HEX_COLOR_PATTERN,K as HEX_COLOR_RULES,p as IPV4_PATTERN,J as IPV4_RULES,U as IPV6_PATTERN,q as IPV6_RULES,v as ISO_8601_DATETIME_PATTERN,T as ISO_8601_DATETIME_PATTERN_STRICT,En as ISO_8601_DATETIME_RULES,c as ISO_8601_DATE_PATTERN,an as ISO_8601_DATE_RULES,A as ISO_8601_TIME_PATTERN,sn as ISO_8601_TIME_RULES,O as JWT_PATTERN,rn as JWT_RULES,i as MAC_ADDRESS_PATTERN,Q as MAC_ADDRESS_RULES,z as MYSQL_TIMESTAMP_PATTERN,D as PASSWORD_RULES,x as SEMVER_PATTERN,tn as SEMVER_RULES,C as SLUG_PATTERN,nn as SLUG_RULES,Rn as STRONG_PASSWORD_RULES,S as URL_PATTERN,j as URL_RULES,N as UUID_PATTERN,F as UUID_RULES,d as UUID_V4_PATTERN,X as UUID_V4_RULES};

package/lib/patterns/rule-sets.d.ts

@@ -0,0 +1,19 @@
+import type { RULES_SYNC } from '../types';
+export declare const EMAIL_RULES: Readonly<RULES_SYNC>;
+export declare const URL_RULES: Readonly<RULES_SYNC>;
+export declare const UUID_RULES: Readonly<RULES_SYNC>;
+export declare const UUID_V4_RULES: Readonly<RULES_SYNC>;
+export declare const IPV4_RULES: Readonly<RULES_SYNC>;
+export declare const IPV6_RULES: Readonly<RULES_SYNC>;
+export declare const MAC_ADDRESS_RULES: Readonly<RULES_SYNC>;
+export declare const HEX_COLOR_RULES: Readonly<RULES_SYNC>;
+export declare const SLUG_RULES: Readonly<RULES_SYNC>;
+export declare const E164_PHONE_RULES: Readonly<RULES_SYNC>;
+export declare const SEMVER_RULES: Readonly<RULES_SYNC>;
+export declare const BASE64_RULES: Readonly<RULES_SYNC>;
+export declare const JWT_RULES: Readonly<RULES_SYNC>;
+export declare const ISO_8601_TIME_RULES: Readonly<RULES_SYNC>;
+export declare const ISO_8601_DATE_RULES: Readonly<RULES_SYNC>;
+export declare const ISO_8601_DATETIME_RULES: Readonly<RULES_SYNC>;
+export declare const PASSWORD_RULES: Readonly<RULES_SYNC>;
+export declare const STRONG_PASSWORD_RULES: Readonly<RULES_SYNC>;

package/lib/types.d.ts

@@ -1,48 +1,93 @@
 /**
- * A synchronous validation rule.
+ * Types for rules, rule sets, schemas and validation results, plus the type-level machinery
+ * that infers whether validation is sync or async from the rules' declared return types.
+ *
+ * @module
+ */
+/**
+ * A synchronous validation rule. It passes by returning `true` (any truthy value counts)
+ * and fails by returning `false` or throwing.
  *
  * @template V type of the value being validated (defaults to `unknown`)
  * @template O tuple type of any extra "overload" arguments passed through by the caller
  */
 export type RULE_SYNC<V = unknown, O extends unknown[] = unknown[]> = (value: V, ...overload: O) => boolean;
 /**
- * An asynchronous validation rule.
+ * An asynchronous validation rule. It passes by resolving to `true` (any truthy value counts)
+ * and fails by resolving to `false` or rejecting.
  *
  * @template V type of the value being validated (defaults to `unknown`)
  * @template O tuple type of any extra "overload" arguments passed through by the caller
  */
 export type RULE_ASYNC<V = unknown, O extends unknown[] = unknown[]> = (value: V, ...overload: O) => Promise<boolean>;
 /**
- * A validation rule which may be either synchronous or asynchronous.
+ * A validation rule which may be either synchronous or asynchronous. Annotating a rule with
+ * this type means its sync/async-ness can't be inferred, so results are typed as a union.
  *
  * @template V type of the value being validated (defaults to `unknown`)
  * @template O tuple type of any extra "overload" arguments passed through by the caller
  */
 export type RULE<V = unknown, O extends unknown[] = unknown[]> = (value: V, ...overload: O) => boolean | Promise<boolean>;
-/** A named set of synchronous rules. Keys are the error messages returned on failure. */
+/**
+ * A set of synchronous rules. Each key is the error reported when its rule fails, and
+ * errors are reported in key order.
+ *
+ * @template V type of the value being validated (defaults to `unknown`)
+ * @template O tuple type of any extra "overload" arguments passed through by the caller
+ */
 export type RULES_SYNC<V = unknown, O extends unknown[] = unknown[]> = {
     [rule_name: string]: RULE_SYNC<V, O>;
 };
-/** A named set of rules, any of which may be asynchronous. Keys are the error messages returned on failure. */
+/**
+ * A set of rules, any of which may be asynchronous. Each key is the error reported when its
+ * rule fails, and errors are reported in key order.
+ *
+ * @template V type of the value being validated (defaults to `unknown`)
+ * @template O tuple type of any extra "overload" arguments passed through by the caller
+ */
 export type RULES<V = unknown, O extends unknown[] = unknown[]> = {
     [rule_name: string]: RULE<V, O>;
 };
 /**
- * Maps object keys to a rule set, or to an array of alternative rule sets
- * (the value passes if it satisfies *any* of the alternatives).
+ * A schema whose rules are all synchronous. Maps each object key to a rule set, or to an
+ * array of alternative rule sets (the value passes if it satisfies *any* of the alternatives).
  */
 export type SCHEMA_SYNC = {
     [key: string]: RULES_SYNC | RULES_SYNC[];
 };
+/**
+ * A schema whose rules may be asynchronous. Maps each object key to a rule set, or to an
+ * array of alternative rule sets (the value passes if it satisfies *any* of the alternatives).
+ */
 export type SCHEMA = {
     [key: string]: RULES | RULES[];
 };
+/** Options for running a rule set. */
+export type RULES_OPTIONS = {
+    /**
+     * Stop at the first failing rule and report only that error, instead of running every rule
+     * and reporting all of them. Defaults to `false`.
+     *
+     * Sync rules run first, in rule order, stopping at the first failure. `async` rules only run
+     * if every sync rule passed; they then run concurrently, and the first failure in rule
+     * order is reported. This skips expensive checks (long regexes, database lookups) on input
+     * that has already failed a cheap one, so put cheap rules first. It doesn't change valid
+     * input, where every rule has to run anyway.
+     */
+    break_early?: boolean;
+};
 /**
- * @arg {boolean} strict --- Don't allow object to have keys not included in the schema
-*/
-export type SCHEMA_OPTIONS = {
+ * Options for validating an object against a schema. `break_early` applies to each field
+ * separately: every field is still validated, each reporting at most one error per rule set.
+ */
+export type SCHEMA_OPTIONS = RULES_OPTIONS & {
+    /**
+     * Report keys of the object that the schema doesn't have, each with the error
+     * `['Key not allowed']`. Defaults to `false`, which ignores them.
+     */
     strict?: boolean;
 };
+/** An object that can be validated against a schema: any string-keyed object. */
 export type CHECKABLE_OBJECT = {
     [key: string]: unknown;
 };
@@ -71,12 +116,41 @@ export type CHECKED_SCHEMA<S extends SCHEMA = SCHEMA> = Promise<CHECKED_SCHEMA_S
  *                so it can't be determined statically
  */
 export type RULE_KIND<R> = R extends (...args: never[]) => infer Ret ? [Ret] extends [boolean] ? 'sync' : [Ret] extends [Promise<boolean>] ? 'async' : 'either' : never;
-/** Union of the kinds of every rule in a rule set (or in an array of rule sets). */
+/** Union of the `RULE_KIND`s of every rule in a rule set (or in an array of rule sets). */
 export type RULES_KIND<R> = R extends readonly (infer E)[] ? RULES_KIND<E> : R extends object ? RULE_KIND<R[keyof R]> : never;
-/** Union of the kinds of every rule in a schema. */
+/** Union of the `RULE_KIND`s of every rule in a schema. */
 export type SCHEMA_KIND<S> = RULES_KIND<S[keyof S]>;
 /**
  * Wraps a result type according to the kinds found in a rule set / schema:
  * any definitely-async rule => `Promise<X>`; all sync => `X`; otherwise `X | Promise<X>`.
+ *
+ * @template K union of rule kinds, from `RULES_KIND` or `SCHEMA_KIND`
+ * @template X the result type to wrap
  */
 export type MAYBE_ASYNC<K, X> = 'async' extends K ? Promise<X> : 'either' extends K ? X | Promise<X> : X;
+/**
+ * Any rule set, whatever value and overload types its rules accept. Used as the constraint
+ * for `compileRules`, so rules with narrowed parameter types can be compiled.
+ */
+export type ANY_RULES = {
+    [rule_name: string]: (value: never, ...overload: never[]) => boolean | Promise<boolean>;
+};
+/**
+ * The value type a rule set accepts: the intersection of what each of its rules accepts,
+ * e.g. `string` for a set mixing `(value: unknown)` and `(value: string)` rules.
+ */
+export type RULES_VALUE<R> = R[keyof R] extends (value: infer V, ...overload: never[]) => unknown ? V : unknown;
+/**
+ * A validator returned by `compileRules`. Returns the keys of the failing rules, as
+ * `string[]` when every rule is sync and `Promise<string[]>` when any is async.
+ *
+ * @template R the compiled rule set's type
+ */
+export type COMPILED_RULES<R> = (value: RULES_VALUE<R>, ...overload: unknown[]) => MAYBE_ASYNC<RULES_KIND<R>, string[]>;
+/**
+ * A validator returned by `compileSchema`. Returns the same result as `getSchemaErrors`,
+ * directly when every rule is sync and as a promise when any is async.
+ *
+ * @template S the compiled schema's type
+ */
+export type COMPILED_SCHEMA<S extends SCHEMA> = (object: CHECKABLE_OBJECT, ...overload: unknown[]) => MAYBE_ASYNC<SCHEMA_KIND<S>, CHECKED_SCHEMA_SYNC<S>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ivl",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "author": {
     "name": "Oskar Voorel",
     "email": "oskar@voorel.com"
@@ -15,6 +15,7 @@
     "@types/bun": "^1.4.0",
     "mitata": "^1.0.34",
     "typescript": "^7.0.2",
+    "valibot": "^1.5.0",
     "yup": "^1.7.1",
     "zod": "^4.5.2"
   },
@@ -51,6 +52,7 @@
     "build": "rm -rf ./lib && bun run build.mjs && tsc -p tsconfig.build.json",
     "prepublishOnly": "bun run build",
     "benchmark": "bun run ./benchmark/index.ts",
+    "benchmark:node": "bun build ./benchmark/index.ts --target=node --packages=external --outfile=./benchmark/.dist/index.mjs 1>&2 && node ./benchmark/.dist/index.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.test.json",
     "test": "bun test && bun run typecheck",
     "release": "bun run ./scripts/release.ts"