ovr 6.2.4 → 7.0.0-next.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (136) hide show
  1. package/README.md +3 -1
  2. package/dist/app/index.d.ts +51 -7
  3. package/dist/app/index.d.ts.map +1 -1
  4. package/dist/app/index.js +163 -28
  5. package/dist/auth/auth-data.d.ts +26 -0
  6. package/dist/auth/auth-data.d.ts.map +1 -0
  7. package/dist/auth/auth-data.js +42 -0
  8. package/dist/auth/cbor.d.ts +50 -0
  9. package/dist/auth/cbor.d.ts.map +1 -0
  10. package/dist/auth/cbor.js +200 -0
  11. package/dist/auth/client-source.d.ts +3 -0
  12. package/dist/auth/client-source.d.ts.map +1 -0
  13. package/dist/auth/client-source.js +3 -0
  14. package/dist/auth/client.d.ts +3 -0
  15. package/dist/auth/client.d.ts.map +1 -0
  16. package/dist/auth/client.js +186 -0
  17. package/dist/auth/configure.d.ts +28 -0
  18. package/dist/auth/configure.d.ts.map +1 -0
  19. package/dist/auth/configure.js +228 -0
  20. package/dist/auth/der.d.ts +6 -0
  21. package/dist/auth/der.d.ts.map +1 -0
  22. package/dist/auth/der.js +36 -0
  23. package/dist/auth/index.d.ts +242 -0
  24. package/dist/auth/index.d.ts.map +1 -0
  25. package/dist/auth/index.js +152 -0
  26. package/dist/auth/issue.d.ts +36 -0
  27. package/dist/auth/issue.d.ts.map +1 -0
  28. package/dist/auth/issue.js +47 -0
  29. package/dist/auth/metadata.d.ts +22 -0
  30. package/dist/auth/metadata.d.ts.map +1 -0
  31. package/dist/auth/metadata.js +134 -0
  32. package/dist/auth/oauth.d.ts +29 -0
  33. package/dist/auth/oauth.d.ts.map +1 -0
  34. package/dist/auth/oauth.js +724 -0
  35. package/dist/auth/passkey.d.ts +101 -0
  36. package/dist/auth/passkey.d.ts.map +1 -0
  37. package/dist/auth/passkey.js +393 -0
  38. package/dist/auth/state.d.ts +49 -0
  39. package/dist/auth/state.d.ts.map +1 -0
  40. package/dist/auth/state.js +184 -0
  41. package/dist/auth/storage.d.ts +193 -0
  42. package/dist/auth/storage.d.ts.map +1 -0
  43. package/dist/auth/storage.js +410 -0
  44. package/dist/auth/token.d.ts +12 -0
  45. package/dist/auth/token.d.ts.map +1 -0
  46. package/dist/auth/token.js +39 -0
  47. package/dist/context/index.d.ts +86 -16
  48. package/dist/context/index.d.ts.map +1 -1
  49. package/dist/context/index.js +166 -42
  50. package/dist/cookie/index.d.ts +3 -0
  51. package/dist/cookie/index.d.ts.map +1 -1
  52. package/dist/cookie/index.js +1 -0
  53. package/dist/database/index.d.ts +262 -0
  54. package/dist/database/index.d.ts.map +1 -0
  55. package/dist/database/index.js +807 -0
  56. package/dist/form/index.d.ts +699 -0
  57. package/dist/form/index.d.ts.map +1 -0
  58. package/dist/form/index.js +901 -0
  59. package/dist/index.d.ts +10 -3
  60. package/dist/index.d.ts.map +1 -1
  61. package/dist/index.js +9 -3
  62. package/dist/jsx/elements.d.ts +28 -2
  63. package/dist/jsx/elements.d.ts.map +1 -1
  64. package/dist/jsx/index.d.ts +20 -4
  65. package/dist/jsx/index.d.ts.map +1 -1
  66. package/dist/jsx/index.js +6 -65
  67. package/dist/limiter/index.d.ts +65 -0
  68. package/dist/limiter/index.d.ts.map +1 -0
  69. package/dist/limiter/index.js +157 -0
  70. package/dist/markdown/index.d.ts +61 -0
  71. package/dist/markdown/index.d.ts.map +1 -0
  72. package/dist/markdown/index.js +1160 -0
  73. package/dist/markup/index.d.ts +188 -0
  74. package/dist/markup/index.d.ts.map +1 -0
  75. package/dist/markup/index.js +718 -0
  76. package/dist/mcp/index.d.ts +73 -0
  77. package/dist/mcp/index.d.ts.map +1 -0
  78. package/dist/mcp/index.js +988 -0
  79. package/dist/middleware/index.d.ts +3 -4
  80. package/dist/middleware/index.d.ts.map +1 -1
  81. package/dist/multipart/index.d.ts +53 -7
  82. package/dist/multipart/index.d.ts.map +1 -1
  83. package/dist/multipart/index.js +332 -124
  84. package/dist/route/index.d.ts +226 -80
  85. package/dist/route/index.d.ts.map +1 -1
  86. package/dist/route/index.js +239 -99
  87. package/dist/schema/index.d.ts +307 -734
  88. package/dist/schema/index.d.ts.map +1 -1
  89. package/dist/schema/index.js +783 -1050
  90. package/dist/table/index.d.ts +132 -0
  91. package/dist/table/index.d.ts.map +1 -0
  92. package/dist/table/index.js +188 -0
  93. package/dist/trie/index.js +4 -4
  94. package/dist/util/index.d.ts +37 -5
  95. package/dist/util/index.d.ts.map +1 -1
  96. package/dist/util/index.js +156 -41
  97. package/package.json +11 -4
  98. package/src/app/index.ts +230 -42
  99. package/src/auth/auth-data.ts +56 -0
  100. package/src/auth/cbor.ts +231 -0
  101. package/src/auth/client-source.ts +3 -0
  102. package/src/auth/client.ts +205 -0
  103. package/src/auth/configure.ts +279 -0
  104. package/src/auth/der.ts +35 -0
  105. package/src/auth/index.ts +387 -0
  106. package/src/auth/issue.ts +52 -0
  107. package/src/auth/metadata.ts +149 -0
  108. package/src/auth/oauth.ts +882 -0
  109. package/src/auth/passkey.ts +556 -0
  110. package/src/auth/state.ts +213 -0
  111. package/src/auth/storage.ts +572 -0
  112. package/src/auth/token.ts +67 -0
  113. package/src/context/index.ts +240 -65
  114. package/src/cookie/index.ts +3 -0
  115. package/src/database/index.ts +1193 -0
  116. package/src/form/index.ts +1720 -0
  117. package/src/index.ts +10 -3
  118. package/src/jsx/elements.ts +45 -25
  119. package/src/jsx/index.ts +24 -69
  120. package/src/limiter/index.ts +221 -0
  121. package/src/markdown/index.ts +1322 -0
  122. package/src/markup/index.ts +853 -0
  123. package/src/mcp/conformance.2025-11-25.yml +39 -0
  124. package/src/mcp/conformance.2026-07-28.yml +56 -0
  125. package/src/mcp/index.ts +1262 -0
  126. package/src/middleware/index.ts +5 -6
  127. package/src/multipart/index.ts +410 -158
  128. package/src/route/index.ts +559 -278
  129. package/src/schema/index.ts +1542 -2256
  130. package/src/table/index.ts +387 -0
  131. package/src/trie/index.ts +4 -4
  132. package/src/util/index.ts +163 -49
  133. package/dist/render/index.d.ts +0 -79
  134. package/dist/render/index.d.ts.map +0 -1
  135. package/dist/render/index.js +0 -257
  136. package/src/render/index.ts +0 -314
@@ -1,7 +1,86 @@
1
- import { Fragment, type JSX, jsx } from "../jsx/index.js";
2
- import { Multipart } from "../multipart/index.js";
3
- import { Checksum, Codec, Size } from "../util/index.js";
4
- import type { StandardSchemaV1 } from "@standard-schema/spec";
1
+ import type { Field } from "../form/index.js";
2
+ import type {
3
+ StandardJSONSchemaV1,
4
+ StandardSchemaV1,
5
+ } from "@standard-schema/spec";
6
+
7
+ /** Issue details, a `Schema.Issue` is only built for the public result. */
8
+ type Failure = {
9
+ expected: unknown;
10
+ path: Schema.Issue.Path;
11
+ message: string | undefined;
12
+ };
13
+
14
+ /**
15
+ * Keywords a schema adds to its JSON Schema as an object's property, which
16
+ * fields use for their label and an unchecked box's default.
17
+ */
18
+ export const annotate = Symbol("annotate");
19
+
20
+ /**
21
+ * Preprocessors that only normalize input, so a stored value parses unchanged.
22
+ * Tables allow these and reject other preprocessors.
23
+ */
24
+ export const normalizers = new WeakSet<(value: any) => unknown>();
25
+
26
+ /**
27
+ * Set a property, defining `__proto__` as data since assigning it would
28
+ * change the object's prototype.
29
+ *
30
+ * @param data Object to set it on
31
+ * @param name Property name
32
+ * @param value Property value
33
+ */
34
+ export const own = (
35
+ data: Record<string, unknown>,
36
+ name: string,
37
+ value: unknown,
38
+ ) => {
39
+ if (name === "__proto__")
40
+ Object.defineProperty(data, name, {
41
+ value,
42
+ enumerable: true,
43
+ writable: true,
44
+ configurable: true,
45
+ });
46
+ else data[name] = value;
47
+ };
48
+
49
+ /**
50
+ * Add issues to a list, one at a time, since spreading a very long list
51
+ * into `push` overflows the stack.
52
+ *
53
+ * @template I Issue
54
+ * @param issues List to add to
55
+ * @param more Issues to add
56
+ */
57
+ export const append = <I>(issues: I[], more: readonly I[]) => {
58
+ for (const issue of more) issues.push(issue);
59
+ };
60
+
61
+ /**
62
+ * Convert to a number without rounding. Integers beyond 2^53 were or would
63
+ * be rounded, so they are left as text, which fails a number's validation.
64
+ *
65
+ * @param value Value to convert, such as form text or a driver's `numeric`
66
+ * @returns The number, or the text of an integer too large to be one
67
+ */
68
+ export const exact = (value: unknown) => {
69
+ const number = Number(value);
70
+
71
+ return Number.isInteger(number) && !Number.isSafeInteger(number)
72
+ ? String(value)
73
+ : number;
74
+ };
75
+
76
+ /**
77
+ * Compiled parse function. Failures stay plain records until the public
78
+ * `parse` builds the issues, so failed union branches cost no errors.
79
+ */
80
+ type Run = (
81
+ value: unknown,
82
+ path: Schema.Issue.Path,
83
+ ) => { data: any; issues?: never } | { data?: never; issues: Failure[] };
5
84
 
6
85
  export namespace Schema {
7
86
  /**
@@ -28,9 +107,7 @@ export namespace Schema {
28
107
  }
29
108
 
30
109
  /** Invalid result type. */
31
- export interface Invalid extends InstanceType<
32
- typeof Schema.AggregateIssue
33
- > {
110
+ export interface Invalid extends Schema.AggregateIssue {
34
111
  data?: never;
35
112
  }
36
113
 
@@ -43,19 +120,6 @@ export namespace Schema {
43
120
  */
44
121
  export type Result<O, M extends object = {}, V extends object = {}> =
45
122
  (Valid<O> & V) | (Invalid & M);
46
-
47
- /**
48
- * Type of constructor input (path is required).
49
- *
50
- * @template O Parse output
51
- * @param value Unknown value to parse
52
- * @param path Issue path (internal)
53
- * @returns Parse result containing data or issues
54
- */
55
- export type Constructor<O> = (
56
- value: unknown,
57
- path: Issue.Path,
58
- ) => Result<O>;
59
123
  }
60
124
 
61
125
  /**
@@ -75,8 +139,142 @@ export namespace Schema {
75
139
  Infer<S[number]>[]
76
140
  : never;
77
141
 
78
- /** Schema.Issue type */
79
- export type Issue = InstanceType<typeof Schema.Issue>;
142
+ export namespace JsonSchema {
143
+ /** Supported JSON Schema dialects. */
144
+ export type Target = "draft-2020-12" | "draft-07";
145
+
146
+ /** `toJsonSchema` options. */
147
+ export interface Options {
148
+ /**
149
+ * JSON Schema dialect.
150
+ *
151
+ * @default "draft-2020-12"
152
+ */
153
+ readonly target?: Target;
154
+
155
+ /**
156
+ * Describe the accepted input or the parsed output.
157
+ *
158
+ * @default "output"
159
+ */
160
+ readonly io?: "input" | "output";
161
+
162
+ /**
163
+ * `"throw"` for values JSON Schema cannot describe (bigint, instances,
164
+ * transforms), or `"any"` to describe them as `{}`.
165
+ *
166
+ * @default "throw"
167
+ */
168
+ readonly unrepresentable?: "throw" | "any";
169
+ }
170
+
171
+ /** Resolved options used while describing a schema (internal). */
172
+ export type Context = Required<Options>;
173
+
174
+ /** Description of one schema; `optional` keys are omitted from `required` (internal). */
175
+ export interface Node {
176
+ readonly schema: Record<string, unknown>;
177
+ readonly optional?: boolean | undefined;
178
+ }
179
+ }
180
+
181
+ /**
182
+ * Inspectable definition of a schema.
183
+ *
184
+ * Parsing, JSON Schema, and database tables are all derived from it.
185
+ */
186
+ export type Def = (
187
+ | { readonly type: "unknown" }
188
+ | {
189
+ readonly type: "string" | "boolean" | "number" | "bigint" | "date";
190
+ readonly message?: string | undefined;
191
+ }
192
+ | {
193
+ readonly type: "literal";
194
+ readonly value: unknown;
195
+ readonly message?: string | undefined;
196
+ }
197
+ | {
198
+ readonly type: "enum";
199
+ readonly values: readonly unknown[];
200
+ readonly message?: string | undefined;
201
+ }
202
+ | {
203
+ readonly type: "instance";
204
+ readonly class: new (...args: any[]) => unknown;
205
+ readonly message?: string | undefined;
206
+ }
207
+ | {
208
+ readonly type: "array";
209
+ readonly item: Schema<unknown>;
210
+ readonly message?: string | undefined;
211
+ }
212
+ | {
213
+ readonly type: "object";
214
+ readonly shape: Object.Shape;
215
+ readonly mode: Object.Mode;
216
+ }
217
+ | { readonly type: "union"; readonly options: readonly Schema<unknown>[] }
218
+ | {
219
+ readonly type: "optional" | "nullable" | "nullish";
220
+ readonly inner: Schema<unknown>;
221
+ }
222
+ | {
223
+ readonly type: "default";
224
+ readonly inner: Schema<unknown>;
225
+ readonly value: unknown;
226
+ }
227
+ | {
228
+ readonly type: "preprocess" | "transform";
229
+ readonly inner: Schema<unknown>;
230
+ readonly fn: (value: any) => unknown;
231
+ }
232
+ | {
233
+ readonly type: "pipe";
234
+ readonly inner: Schema<unknown>;
235
+ readonly next: Schema<unknown>;
236
+ }
237
+ | {
238
+ readonly type: "json";
239
+ readonly inner: Schema<unknown>;
240
+ readonly schema: Schema<unknown>;
241
+ readonly message?: string | undefined;
242
+ }
243
+ | {
244
+ readonly type: "check";
245
+ readonly inner: Schema<unknown>;
246
+ readonly check: Check;
247
+ }
248
+ ) & {
249
+ /** What the value is, see `describe()` */
250
+ readonly description?: string;
251
+ };
252
+
253
+ /** Validation applied to the output of another schema. */
254
+ export type Check =
255
+ | {
256
+ readonly name: "min" | "max";
257
+ readonly value: number | bigint;
258
+ readonly message: string;
259
+ }
260
+ | {
261
+ readonly name: "int" | "email" | "url" | "uuid";
262
+ readonly message: string;
263
+ }
264
+ | {
265
+ readonly name: "refine";
266
+ readonly fn: (value: any) => boolean;
267
+ readonly message: string;
268
+ };
269
+
270
+ // interfaces, so that declaration files name them `Schema.Issue` and
271
+ // `Schema.AggregateIssue`, which an alias of the class would not be
272
+
273
+ /** Validation issue produced during parsing */
274
+ export interface Issue extends IssueClass {}
275
+
276
+ /** AggregateIssue containing at least one `Schema.Issue` */
277
+ export interface AggregateIssue extends AggregateIssueClass {}
80
278
 
81
279
  export namespace Issue {
82
280
  /** Issue path representation. */
@@ -91,6 +289,7 @@ export namespace Schema {
91
289
  * Object schema with extend capability.
92
290
  *
93
291
  * @template S Object shape type
292
+ * @template M How unknown keys are handled, `strip` by default
94
293
  */
95
294
  export type Object<
96
295
  S extends Object.Shape,
@@ -145,7 +344,7 @@ export namespace Schema {
145
344
  }
146
345
 
147
346
  /** Shared shape types for `Shape` related runtime methods. */
148
- namespace ShapeUtil {
347
+ export namespace ShapeUtil {
149
348
  /**
150
349
  * Shape key name string.
151
350
  *
@@ -169,7 +368,7 @@ namespace ShapeUtil {
169
368
  }
170
369
 
171
370
  /** Shared runtime shape operations used by object and form schema methods. */
172
- class ShapeUtil {
371
+ export class ShapeUtil {
173
372
  /**
174
373
  * Merge two record-like shapes where `extra` keys override `shape`.
175
374
  *
@@ -202,7 +401,7 @@ class ShapeUtil {
202
401
  const out: Record<string, unknown> = {};
203
402
 
204
403
  for (const name of names) {
205
- if (name in shape) out[name] = shape[name];
404
+ if (name in shape) own(out, name, shape[name]);
206
405
  }
207
406
 
208
407
  return out as Pick<S, N>;
@@ -225,112 +424,145 @@ class ShapeUtil {
225
424
  const out: Record<string, unknown> = {};
226
425
 
227
426
  for (const [name, value] of Object.entries(shape)) {
228
- if (!remove.has(name)) out[name] = value;
427
+ if (!remove.has(name)) own(out, name, value);
229
428
  }
230
429
 
231
430
  return out as Omit<S, N>;
232
431
  }
233
432
  }
234
433
 
235
- /**
236
- * Minimal schema validator geared around parsing form data like
237
- * multipart `FormData` and `URLSearchParams`.
238
- *
239
- * Implements Standard Schema v1 via the `~standard` property (sync validate).
240
- *
241
- * @template Output Output type after parsing
242
- */
243
- export class Schema<Output> implements StandardSchemaV1<unknown, Output> {
244
- /** Email regular expression */
245
- static readonly #emailRegex =
246
- /^(?!\.)(?!.*\.\.)([a-z0-9_'+\-\.]*)[a-z0-9_'+\-]@([a-z0-9][a-z0-9\-]*\.)+[a-z]{2,}$/i;
434
+ // named classes, so their published types are written by name and do not
435
+ // spell out what `Error` has in each runtime, such as Node's
247
436
 
248
- /** Validation issue produced during parsing. */
249
- static readonly Issue = class Issue extends Error {
250
- /** Expected type/value. */
251
- readonly expected: string;
437
+ /** Validation issue produced during parsing. */
438
+ class Issue extends Error {
439
+ /** Expected type/value. */
440
+ readonly expected: string;
252
441
 
253
- /** Path to the invalid value. */
254
- readonly path: Schema.Issue.Path;
442
+ /** Path to the invalid value. */
443
+ readonly path: Schema.Issue.Path;
255
444
 
256
- /**
257
- * @param expected Expected value
258
- * @param path Path to the invalid value
259
- * @param message Issue message
260
- */
261
- constructor(expected: unknown, path: Schema.Issue.Path, message?: string) {
262
- const exp = String(expected);
445
+ /**
446
+ * @param expected Expected value
447
+ * @param path Path to the invalid value
448
+ * @param message Issue message
449
+ */
450
+ constructor(expected: unknown, path: Schema.Issue.Path, message?: string) {
451
+ const exp = String(expected);
263
452
 
264
- super(message ?? `Expected ${exp}`);
453
+ super(message ?? `Expected ${exp}`);
265
454
 
266
- this.name = "Schema.Issue";
267
- this.expected = exp;
268
- this.path = path;
269
- }
455
+ this.name = "Schema.Issue";
456
+ this.expected = exp;
457
+ this.path = path;
458
+ }
270
459
 
271
- /**
272
- * @returns `Schema.Issue(path): message`
273
- */
274
- override toString() {
275
- let path = "";
276
-
277
- for (const segment of this.path) {
278
- path +=
279
- typeof segment === "number"
280
- ? `[${segment}]`
281
- : `${path ? "." : path}${segment}`;
282
- }
460
+ /**
461
+ * @returns `Schema.Issue(path): message`
462
+ */
463
+ override toString() {
464
+ let path = "";
283
465
 
284
- return `${this.name}${path ? `(${path})` : ""}: ${this.message}`;
466
+ for (const segment of this.path) {
467
+ path +=
468
+ typeof segment === "number"
469
+ ? `[${segment}]`
470
+ : `${path ? "." : path}${segment}`;
285
471
  }
286
472
 
287
- toJSON() {
288
- return { ...this, message: this.message };
289
- }
290
- };
473
+ return `${this.name}${path ? `(${path})` : ""}: ${this.message}`;
474
+ }
291
475
 
292
- /** AggregateIssue containing at least one Schema.Issue */
293
- static readonly AggregateIssue = class AggregateIssue extends AggregateError {
294
- /** Non-empty tuple of issues */
295
- readonly issues: Schema.Issue.List;
476
+ toJSON() {
477
+ return { ...this, message: this.message };
478
+ }
479
+ }
296
480
 
297
- /** User submitted / sanitized values */
298
- readonly values: Form.Value.Map | undefined;
481
+ /** The classes `Schema`'s issue types are named for */
482
+ type IssueClass = Issue;
483
+ type AggregateIssueClass = AggregateIssue;
299
484
 
300
- /**
301
- * Create a new AggregateIssue.
302
- *
303
- * Coerces issues into a non-empty tuple.
304
- *
305
- * @param issues Issues
306
- * @param values Received values
307
- */
308
- constructor([first, ...rest]: Schema.Issue[], values?: Form.Value.Map) {
309
- if (!first) throw new TypeError("AggregateIssue must have an issue.");
485
+ /** AggregateIssue containing at least one Schema.Issue */
486
+ class AggregateIssue extends AggregateError {
487
+ /** Non-empty tuple of issues */
488
+ readonly issues: Schema.Issue.List;
310
489
 
311
- const issues: Schema.Issue.List = [first, ...rest];
312
- const name = "Schema.AggregateIssue";
313
- const count = issues.length;
490
+ /** User submitted / sanitized values */
491
+ readonly values: Field.Value.Map | undefined;
314
492
 
315
- super(issues, `${name}(${count})\n${issues.join("\n")}`);
493
+ /**
494
+ * Create a new AggregateIssue.
495
+ *
496
+ * Coerces issues into a non-empty tuple.
497
+ *
498
+ * @param issues Issues
499
+ * @param values Received values
500
+ */
501
+ constructor([first, ...rest]: Schema.Issue[], values?: Field.Value.Map) {
502
+ if (!first) throw new TypeError("AggregateIssue must have an issue.");
316
503
 
317
- this.name = name;
318
- this.issues = issues;
319
- this.values = values;
320
- }
504
+ const issues: Schema.Issue.List = [first, ...rest];
505
+ const name = "Schema.AggregateIssue";
506
+ const count = issues.length;
321
507
 
322
- override toString() {
323
- // prevents name being in the default twice since it's
324
- // already in the message
325
- return this.message;
326
- }
508
+ super(issues, `${name}(${count})\n${issues.join("\n")}`);
327
509
 
328
- toJSON() {
329
- return { ...this, message: this.message };
330
- }
510
+ this.name = name;
511
+ this.issues = issues;
512
+ this.values = values;
513
+ }
514
+
515
+ override toString() {
516
+ // prevents name being in the default twice since it's
517
+ // already in the message
518
+ return this.message;
519
+ }
520
+
521
+ toJSON() {
522
+ return { ...this, message: this.message };
523
+ }
524
+ }
525
+
526
+ /**
527
+ * Minimal schema validator geared around parsing form data like
528
+ * multipart `FormData` and `URLSearchParams`.
529
+ *
530
+ * Implements Standard Schema v1 and Standard JSON Schema v1 via the
531
+ * `~standard` property (sync validate).
532
+ *
533
+ * @template Output Output type after parsing
534
+ */
535
+ export class Schema<Output>
536
+ implements
537
+ StandardSchemaV1<unknown, Output>,
538
+ StandardJSONSchemaV1<unknown, Output>
539
+ {
540
+ /** Email regular expression */
541
+ static readonly #emailRegex =
542
+ /^(?!\.)(?!.*\.\.)([a-z0-9_'+\-\.]*)[a-z0-9_'+\-]@([a-z0-9][a-z0-9\-]*\.)+[a-z]{2,}$/i;
543
+
544
+ /** UUID regular expression, any version */
545
+ static readonly #uuidRegex =
546
+ /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i;
547
+
548
+ /** `$schema` URI for each supported target. */
549
+ static readonly #dialects: Record<Schema.JsonSchema.Target, string> = {
550
+ "draft-2020-12": "https://json-schema.org/draft/2020-12/schema",
551
+ "draft-07": "http://json-schema.org/draft-07/schema#",
331
552
  };
332
553
 
333
- readonly "~standard": StandardSchemaV1.Props<unknown, Output> = {
554
+ /** Validation issue produced during parsing. */
555
+ static readonly Issue: new (
556
+ ...args: ConstructorParameters<typeof Issue>
557
+ ) => Schema.Issue = Issue;
558
+
559
+ /** AggregateIssue containing at least one Schema.Issue */
560
+ static readonly AggregateIssue: new (
561
+ ...args: ConstructorParameters<typeof AggregateIssue>
562
+ ) => Schema.AggregateIssue = AggregateIssue;
563
+
564
+ readonly "~standard": StandardSchemaV1.Props<unknown, Output> &
565
+ StandardJSONSchemaV1.Props<unknown, Output> = {
334
566
  version: 1,
335
567
  vendor: "ovr",
336
568
  validate: (value) => {
@@ -338,8 +570,15 @@ export class Schema<Output> implements StandardSchemaV1<unknown, Output> {
338
570
 
339
571
  return result.issues ? result : { value: result.data };
340
572
  },
573
+ jsonSchema: {
574
+ input: (options) => this.#standard(options, "input"),
575
+ output: (options) => this.#standard(options, "output"),
576
+ },
341
577
  };
342
578
 
579
+ /** Inspectable definition this schema was built from. */
580
+ readonly def: Schema.Def;
581
+
343
582
  /**
344
583
  * Parse and validate an unknown value.
345
584
  *
@@ -349,2469 +588,1516 @@ export class Schema<Output> implements StandardSchemaV1<unknown, Output> {
349
588
  */
350
589
  parse: Schema.Parse<Output>;
351
590
 
591
+ /** Compiled parse, nested schemas share one path that is copied only into issues. */
592
+ readonly #run: Run;
593
+
352
594
  /**
353
595
  * Construct a new schema - used internally.
354
596
  *
355
597
  * Use static methods on `Schema` to make a new schema.
356
598
  *
357
- * @param parse Parse function that validates and transforms input
599
+ * @param def Schema definition
358
600
  */
359
- constructor(parse: Schema.Parse.Constructor<Output>) {
360
- this.parse = (value, path = []) => parse(value, path);
601
+ protected constructor(def: Schema.Def) {
602
+ const run = Schema.#compile(def);
603
+
604
+ this.def = def;
605
+ this.#run = run;
606
+ this.parse = (value, path) => {
607
+ const result = run(value, path ? [...path] : []);
608
+
609
+ return result.issues
610
+ ? new Schema.AggregateIssue(
611
+ result.issues.map(
612
+ (issue) =>
613
+ new Schema.Issue(issue.expected, issue.path, issue.message),
614
+ ),
615
+ )
616
+ : result;
617
+ };
361
618
  }
362
619
 
363
620
  /**
364
- * @internal Required for Field to override and return a `Field` instance
621
+ * Required for Field to override and return a `Field` instance
365
622
  * from the chained methods instead of a `Schema`
366
623
  * @template O Output type of the new schema
367
- * @param parse Parse function that validates and transforms input
624
+ * @param def Definition of the new schema
368
625
  * @returns New schema instance based on the current instance
369
626
  */
370
- derive<O>(parse: Schema.Parse.Constructor<O>) {
371
- return new Schema<O>(parse);
627
+ protected derive<O>(def: Schema.Def) {
628
+ return new Schema<O>(def);
372
629
  }
373
630
 
374
631
  /**
375
- * @template T Field tag name
376
- * @template U Field input type attribute
377
- * @template V Field option values
378
- * @returns Optional field
379
- */
380
- optional<
381
- T extends Field.Tag,
382
- U extends Field.Type,
383
- V extends Field.Values | undefined,
384
- >(
385
- this: Field.Instance<Output, T, U, V>,
386
- ): Field.Instance<Output | undefined, T, U, V>;
387
- /**
388
- * @returns Optional schema
632
+ * Say what the value is. Agents read it as the `description` in its JSON
633
+ * Schema, such as of a tool's argument, and a field shows it to people
634
+ * under its control.
635
+ *
636
+ * ```ts
637
+ * Schema.string().uuid().describe("The bookmark's ID");
638
+ * Field.url().describe("An http or https address");
639
+ * ```
640
+ *
641
+ * @param text Description
642
+ * @returns Schema with the description
389
643
  */
390
- optional(this: Schema<Output>): Schema<Output | undefined>;
391
- optional(this: Schema<Output>) {
392
- return this.derive<Output | undefined>((v, path) => {
393
- if (v === undefined) return { data: undefined };
394
-
395
- return this.parse(v, path);
396
- });
644
+ describe(text: string) {
645
+ return this.derive<Output>({ ...this.def, description: text }) as this;
397
646
  }
398
647
 
399
648
  /**
400
- * @template T Field tag name
401
- * @template U Field input type attribute
402
- * @template V Field option values
403
- * @returns Nullable field
404
- */
405
- nullable<
406
- T extends Field.Tag,
407
- U extends Field.Type,
408
- V extends Field.Values | undefined,
409
- >(
410
- this: Field.Instance<Output, T, U, V>,
411
- ): Field.Instance<Output | null, T, U, V>;
412
- /**
413
- * @returns Nullable schema
649
+ * @returns The description given with `describe()`, here or on the
650
+ * schema this one wraps, such as before `optional()`
414
651
  */
415
- nullable(this: Schema<Output>): Schema<Output | null>;
416
- nullable(this: Schema<Output>) {
417
- return this.derive<Output | null>((v, path) => {
418
- if (v === null) return { data: null };
419
-
420
- return this.parse(v, path);
421
- });
652
+ get description(): string | undefined {
653
+ let def: Schema.Def | undefined = this.def;
654
+ while (def) {
655
+ if (def.description !== undefined) return def.description;
656
+ def = "inner" in def ? def.inner.def : undefined;
657
+ }
422
658
  }
423
659
 
424
660
  /**
425
- * @template T Field tag name
426
- * @template U Field input type attribute
427
- * @template V Field option values
428
- * @returns Nullish field
661
+ * @internal Overridden by Field to describe itself as an object's property
662
+ * @param _io Side of the description
663
+ * @returns Keywords added to the property's JSON Schema
429
664
  */
430
- nullish<
431
- T extends Field.Tag,
432
- U extends Field.Type,
433
- V extends Field.Values | undefined,
434
- >(
435
- this: Field.Instance<Output, T, U, V>,
436
- ): Field.Instance<Output | null | undefined, T, U, V>;
665
+ [annotate](_io: "input" | "output"): Record<string, unknown> | void {}
666
+
437
667
  /**
438
- * @returns Nullish schema
668
+ * Convert the schema into a JSON Schema document.
669
+ *
670
+ * Refinements without a JSON Schema equivalent are omitted.
671
+ *
672
+ * @param options Target dialect, input/output side, and unrepresentable handling
673
+ * @returns JSON Schema object
439
674
  */
440
- nullish(this: Schema<Output>): Schema<Output | null | undefined>;
441
- nullish(this: Schema<Output>) {
442
- return this.derive<Output | null | undefined>((v, path) => {
443
- if (v == null) return { data: v };
675
+ toJsonSchema(options: Schema.JsonSchema.Options = {}) {
676
+ const {
677
+ target = "draft-2020-12",
678
+ io = "output",
679
+ unrepresentable = "throw",
680
+ } = options;
444
681
 
445
- return this.parse(v, path);
446
- });
682
+ if (!Object.hasOwn(Schema.#dialects, target)) {
683
+ throw new TypeError(`Unsupported JSON Schema target: ${target}`);
684
+ }
685
+
686
+ return {
687
+ $schema: Schema.#dialects[target],
688
+ ...Schema.#node(this, { target, io, unrepresentable }).schema,
689
+ } as Record<string, unknown>;
447
690
  }
448
691
 
449
692
  /**
450
- * @template T Field tag name
451
- * @template U Field input type attribute
452
- * @template V Field option values
453
- * @param value Default value to use when input is undefined
454
- * @returns Field with default
455
- */
456
- default<
457
- T extends Field.Tag,
458
- U extends Field.Type,
459
- V extends Field.Values | undefined,
460
- >(
461
- this: Field.Instance<Output, T, U, V>,
462
- value: Output,
463
- ): Field.Instance<Output, T, U, V>;
464
- /**
465
- * @param value Default value to use when input is undefined
466
- * @returns Schema with default
693
+ * @param options Standard JSON Schema options
694
+ * @param io Side of the description
695
+ * @returns JSON Schema object
467
696
  */
468
- default(this: Schema<Output>, value: Output): Schema<Output>;
469
- default(this: Schema<Output>, value: Output) {
470
- return this.derive((v, path) => {
471
- if (v === undefined) return { data: value };
472
-
473
- return this.parse(v, path);
697
+ #standard(
698
+ { target, libraryOptions }: StandardJSONSchemaV1.Options,
699
+ io: "input" | "output",
700
+ ) {
701
+ return this.toJsonSchema({
702
+ ...libraryOptions,
703
+ target: target as Schema.JsonSchema.Target,
704
+ io,
474
705
  });
475
706
  }
476
707
 
477
708
  /**
478
- * @template T Field tag name
479
- * @template U Field input type attribute
480
- * @template V Field option values
481
- * @param fn Preprocess function to run before parsing
482
- * @returns Schema that preprocesses input before parsing
483
- */
484
- preprocess<
485
- T extends Field.Tag,
486
- U extends Field.Type,
487
- V extends Field.Values | undefined,
488
- >(
489
- this: Field.Instance<Output, T, U, V>,
490
- fn: (value: unknown) => unknown,
491
- ): Field.Instance<Output, T, U, V>;
492
- /**
493
- * @param fn Preprocess function to run before parsing
494
- * @returns Schema that preprocesses input before parsing
709
+ * @param check Check to apply to the output
710
+ * @returns Checked schema
495
711
  */
496
- preprocess(
497
- this: Schema<Output>,
498
- fn: (value: unknown) => unknown,
499
- ): Schema<Output>;
500
- preprocess(this: Schema<Output>, fn: (value: unknown) => unknown) {
501
- return this.derive((v, path) => this.parse(fn(v), path));
712
+ #check(check: Schema.Check) {
713
+ return this.derive<Output>({ type: "check", inner: this, check });
502
714
  }
503
715
 
504
716
  /**
505
- * @template O Output type after transformation
506
- * @template T Field tag name
507
- * @template U Field input type attribute
508
- * @template V Field option values
509
- * @param fn Transform function to apply to parsed output
510
- * @returns Transformed field
511
- */
512
- transform<
513
- O,
514
- T extends Field.Tag,
515
- U extends Field.Type,
516
- V extends Field.Values | undefined,
517
- >(
518
- this: Field.Instance<Output, T, U, V>,
519
- fn: (value: Output) => O,
520
- ): Field.Instance<O, T, U, V>;
521
- /**
522
- * @template O Output type after transformation
523
- * @param fn Transform function to apply to parsed output
524
- * @returns Transformed schema
717
+ * @param expected Expected value
718
+ * @param path Issue path, copied since parsing continues to change it
719
+ * @param message Issue message
720
+ * @returns Invalid result with one issue
525
721
  */
526
- transform<O>(this: Schema<Output>, fn: (value: Output) => O): Schema<O>;
527
- transform<O>(this: Schema<Output>, fn: (value: Output) => O) {
528
- return this.derive((v, path) => {
529
- const out = this.parse(v, path);
530
-
531
- return out.issues ? out : { data: fn(out.data) };
532
- });
722
+ static #issue(expected: unknown, path: Schema.Issue.Path, message?: string) {
723
+ return { issues: [{ expected, path: [...path], message }] };
533
724
  }
534
725
 
535
726
  /**
536
- * @template O Output type after pipe
537
- * @template T Field tag name
538
- * @template U Field input type attribute
539
- * @template V Field option values
540
- * @param next Schema to validate the result with
541
- * @returns Piped field
727
+ * Compile a definition into its parse function once, at construction.
728
+ *
729
+ * Nested schemas run with the parent's path, adding their key while they
730
+ * parse and removing it after, so valid values allocate no paths.
731
+ *
732
+ * @param def Schema definition
733
+ * @returns Parse function
542
734
  */
543
- pipe<
544
- O,
545
- T extends Field.Tag,
546
- U extends Field.Type,
547
- V extends Field.Values | undefined,
548
- >(
549
- this: Field.Instance<Output, T, U, V>,
550
- next: Schema<O>,
551
- ): Field.Instance<O, T, U, V>;
552
- /**
553
- * @template O Output type after pipe
554
- * @param next Schema to validate the result with
555
- * @returns Piped schema
735
+ static #compile(def: Schema.Def): Run {
736
+ switch (def.type) {
737
+ case "unknown":
738
+ return (v) => ({ data: v });
739
+ case "string":
740
+ case "boolean":
741
+ case "bigint":
742
+ return (v, path) =>
743
+ typeof v === def.type
744
+ ? { data: v }
745
+ : Schema.#issue(def.type, path, def.message);
746
+ case "number":
747
+ return (v, path) =>
748
+ Number.isFinite(v) // isFinite checks type
749
+ ? { data: v }
750
+ : Schema.#issue("number", path, def.message);
751
+ case "date":
752
+ return (v, path) =>
753
+ v instanceof Date && !Number.isNaN(v.getTime())
754
+ ? { data: v }
755
+ : Schema.#issue("Date", path, def.message);
756
+ case "literal":
757
+ return (v, path) =>
758
+ v === def.value
759
+ ? { data: def.value }
760
+ : Schema.#issue(def.value, path, def.message);
761
+ case "enum":
762
+ return (v, path) => {
763
+ for (const value of def.values) {
764
+ if (v === value) return { data: value };
765
+ }
766
+
767
+ return Schema.#issue(
768
+ def.values.map((v) => JSON.stringify(v)).join(" | "),
769
+ path,
770
+ def.message,
771
+ );
772
+ };
773
+ case "instance":
774
+ return (v, path) =>
775
+ v instanceof def.class
776
+ ? { data: v }
777
+ : Schema.#issue(def.class.name, path, def.message);
778
+ case "array":
779
+ return (v, path) => {
780
+ if (!Array.isArray(v))
781
+ return Schema.#issue("Array", path, def.message);
782
+
783
+ const data: unknown[] = [];
784
+ let issues: Failure[] | undefined;
785
+
786
+ for (let i = 0; i < v.length; i++) {
787
+ path.push(i);
788
+ const result = def.item.#run(v[i], path);
789
+ path.pop();
790
+
791
+ if (result.issues) {
792
+ // the first failure's list is new, so it is reused
793
+ if (issues) append(issues, result.issues);
794
+ else issues = result.issues;
795
+ } else {
796
+ data.push(result.data);
797
+ }
798
+ }
799
+
800
+ return issues ? { issues } : { data };
801
+ };
802
+ case "object": {
803
+ const shape = Object.entries(def.shape);
804
+
805
+ return (value, path) => {
806
+ if (
807
+ value == null ||
808
+ typeof value !== "object" ||
809
+ Array.isArray(value)
810
+ ) {
811
+ return Schema.#issue("Object", path);
812
+ }
813
+
814
+ const data: Record<string, unknown> = {};
815
+ let issues: Failure[] | undefined;
816
+
817
+ for (const [name, schema] of shape) {
818
+ path.push(name);
819
+ const result = schema.#run(
820
+ (value as Record<string, unknown>)[name],
821
+ path,
822
+ );
823
+ path.pop();
824
+
825
+ if (result.issues) {
826
+ if (issues) append(issues, result.issues);
827
+ else issues = result.issues;
828
+ } else if (result.data !== undefined) {
829
+ own(data, name, result.data);
830
+ }
831
+ }
832
+
833
+ if (def.mode !== "strip") {
834
+ for (const [name, next] of Object.entries(value)) {
835
+ if (!Object.hasOwn(def.shape, name)) {
836
+ if (def.mode === "strict") {
837
+ (issues ??= []).push({
838
+ expected: "never",
839
+ path: [...path, name],
840
+ message: "Unexpected key",
841
+ });
842
+ } else {
843
+ own(data, name, next);
844
+ }
845
+ }
846
+ }
847
+ }
848
+
849
+ return issues ? { issues } : { data };
850
+ };
851
+ }
852
+ case "union":
853
+ return (v, path) => {
854
+ const issues: Failure[] = [];
855
+
856
+ for (const schema of def.options) {
857
+ const result = schema.#run(v, path);
858
+
859
+ // return as soon as one passes
860
+ if (!result.issues) return result;
861
+
862
+ append(issues, result.issues);
863
+ }
864
+
865
+ return { issues };
866
+ };
867
+ case "optional":
868
+ return (v, path) =>
869
+ v === undefined ? { data: v } : def.inner.#run(v, path);
870
+ case "nullable":
871
+ return (v, path) =>
872
+ v === null ? { data: v } : def.inner.#run(v, path);
873
+ case "nullish":
874
+ return (v, path) => (v == null ? { data: v } : def.inner.#run(v, path));
875
+ case "default":
876
+ return (v, path) =>
877
+ v === undefined ? { data: def.value } : def.inner.#run(v, path);
878
+ case "preprocess":
879
+ return (v, path) => def.inner.#run(def.fn(v), path);
880
+ case "transform":
881
+ return (v, path) => {
882
+ const result = def.inner.#run(v, path);
883
+
884
+ return result.issues ? result : { data: def.fn(result.data) };
885
+ };
886
+ case "pipe":
887
+ return (v, path) => {
888
+ const result = def.inner.#run(v, path);
889
+
890
+ return result.issues ? result : def.next.#run(result.data, path);
891
+ };
892
+ case "json":
893
+ return (v, path) => {
894
+ const result = def.inner.#run(v, path);
895
+ if (result.issues) return result;
896
+
897
+ let data: unknown;
898
+
899
+ try {
900
+ data = JSON.parse(result.data as string);
901
+ } catch {
902
+ return Schema.#issue("JSON", path, def.message);
903
+ }
904
+
905
+ return def.schema.#run(data, path);
906
+ };
907
+ case "check": {
908
+ const test = Schema.#test(def.check);
909
+
910
+ return (v, path) => {
911
+ const result = def.inner.#run(v, path);
912
+
913
+ return result.issues || test(result.data)
914
+ ? result
915
+ : Schema.#issue("refine", path, def.check.message);
916
+ };
917
+ }
918
+ }
919
+ }
920
+
921
+ /**
922
+ * @param check Output check
923
+ * @returns Function that returns `false` when the value fails the check
556
924
  */
557
- pipe<O>(this: Schema<Output>, next: Schema<O>): Schema<O>;
558
- pipe<O>(this: Schema<Output>, next: Schema<O>) {
559
- return this.derive((v, path) => {
560
- const result = this.parse(v, path);
925
+ static #test(check: Schema.Check): (value: any) => boolean {
926
+ switch (check.name) {
927
+ // a string has between length / 2 and length code points, count only between
928
+ case "min": {
929
+ const min = Number(check.value);
561
930
 
562
- return result.issues ? result : next.parse(result.data, path);
563
- });
931
+ return (v) =>
932
+ typeof v === "string"
933
+ ? v.length >= min * 2 ||
934
+ (v.length >= min && Schema.#length(v) >= min)
935
+ : v >= check.value;
936
+ }
937
+ case "max": {
938
+ const max = Number(check.value);
939
+
940
+ return (v) =>
941
+ typeof v === "string"
942
+ ? v.length <= max ||
943
+ (v.length <= max * 2 && Schema.#length(v) <= max)
944
+ : v <= check.value;
945
+ }
946
+ case "int":
947
+ return Number.isSafeInteger;
948
+ case "email":
949
+ return (v) => Schema.#emailRegex.test(v);
950
+ case "url":
951
+ return URL.canParse;
952
+ case "uuid":
953
+ return (v) => Schema.#uuidRegex.test(v);
954
+ case "refine":
955
+ return check.fn;
956
+ }
564
957
  }
565
958
 
566
959
  /**
567
- * Parse a JSON string and validate the parsed value with the provided schema.
568
- *
569
- * @template O Output type
570
- * @template T Field tag name
571
- * @template U Field input type attribute
572
- * @template V Field option values
573
- * @param schema Schema to validate the parsed JSON value with
574
- * @param message Issue message when invalid
575
- * @returns Parsed JSON field
960
+ * @param value String
961
+ * @returns Number of Unicode code points, a surrogate pair counts once
576
962
  */
577
- json<
578
- O,
579
- T extends Field.Tag,
580
- U extends Field.Type,
581
- V extends Field.Values | undefined,
582
- >(
583
- this: Field.Instance<string, T, U, V>,
584
- schema: Schema<O>,
585
- message?: string,
586
- ): Field.Instance<O, T, U, V>;
963
+ static #length(value: string) {
964
+ let length = value.length;
965
+
966
+ for (let i = 0; i < value.length - 1; i++) {
967
+ const code = value.charCodeAt(i);
968
+
969
+ if (code >= 0xd800 && code <= 0xdbff) {
970
+ const next = value.charCodeAt(i + 1);
971
+
972
+ if (next >= 0xdc00 && next <= 0xdfff) {
973
+ length--;
974
+ i++;
975
+ }
976
+ }
977
+ }
978
+
979
+ return length;
980
+ }
981
+
587
982
  /**
588
- * Parse a JSON string and validate the parsed value with the provided schema.
983
+ * Describe a schema as JSON Schema by walking its definition.
589
984
  *
590
- * @template O Output type
591
- * @param schema Schema to validate the parsed JSON value with
592
- * @param message Issue message when invalid
593
- * @returns Parsed JSON schema
985
+ * @param schema Schema to describe
986
+ * @param c Description context
987
+ * @returns Description, optional when its key may be omitted
594
988
  */
595
- json<O>(this: Schema<string>, schema: Schema<O>, message?: string): Schema<O>;
596
- json<O>(this: Schema<string>, schema: Schema<O>, message?: string) {
597
- return this.derive((v, path) => {
598
- const result = this.parse(v, path);
599
- if (result.issues) return result;
600
-
601
- let data: unknown;
602
-
603
- try {
604
- data = JSON.parse(result.data);
605
- } catch {
606
- return new Schema.AggregateIssue([
607
- new Schema.Issue("JSON", path, message),
608
- ]);
989
+ static #node(
990
+ schema: Schema<unknown>,
991
+ c: Schema.JsonSchema.Context,
992
+ ): Schema.JsonSchema.Node {
993
+ const node = Schema.#kind(schema, c);
994
+ const { description } = schema.def;
995
+
996
+ return description === undefined
997
+ ? node
998
+ : { ...node, schema: { ...node.schema, description } };
999
+ }
1000
+
1001
+ /**
1002
+ * @param schema Schema to describe
1003
+ * @param c Context
1004
+ * @returns JSON Schema of the schema's kind
1005
+ */
1006
+ static #kind(
1007
+ schema: Schema<unknown>,
1008
+ c: Schema.JsonSchema.Context,
1009
+ ): Schema.JsonSchema.Node {
1010
+ const { def } = schema;
1011
+
1012
+ switch (def.type) {
1013
+ case "unknown":
1014
+ // accepts undefined, so the key may be absent
1015
+ return { schema: {}, optional: true };
1016
+ case "string":
1017
+ case "boolean":
1018
+ case "number":
1019
+ return { schema: { type: def.type } };
1020
+ case "bigint":
1021
+ case "date":
1022
+ case "instance":
1023
+ return Schema.#unrepresentable(
1024
+ c,
1025
+ def.type === "instance" ? `${def.class.name} instance` : def.type,
1026
+ );
1027
+ case "literal":
1028
+ return Schema.#values(c, [def.value]);
1029
+ case "enum":
1030
+ return Schema.#values(c, def.values);
1031
+ case "array":
1032
+ return {
1033
+ schema: { type: "array", items: Schema.#node(def.item, c).schema },
1034
+ };
1035
+ case "object": {
1036
+ const properties: Record<string, unknown> = {};
1037
+ const required: string[] = [];
1038
+
1039
+ for (const [name, schema] of Object.entries(def.shape)) {
1040
+ const node = Schema.#node(schema, c);
1041
+ const extra = schema[annotate](c.io);
1042
+
1043
+ own(properties, name, { ...node.schema, ...extra });
1044
+ // a key with a default may be left out
1045
+ if (!node.optional && extra?.default === undefined)
1046
+ required.push(name);
1047
+ }
1048
+
1049
+ return {
1050
+ schema: {
1051
+ type: "object",
1052
+ properties,
1053
+ ...(required.length && { required }),
1054
+ // strip accepts unknown input keys but removes them from the output
1055
+ ...((def.mode === "strict" ||
1056
+ (def.mode === "strip" && c.io === "output")) && {
1057
+ additionalProperties: false,
1058
+ }),
1059
+ },
1060
+ };
1061
+ }
1062
+ case "union": {
1063
+ const nodes = def.options.map((schema) => Schema.#node(schema, c));
1064
+
1065
+ return {
1066
+ schema:
1067
+ nodes.length === 1
1068
+ ? nodes[0]!.schema
1069
+ : { anyOf: nodes.map((node) => node.schema) },
1070
+ optional: nodes.some((node) => node.optional),
1071
+ };
1072
+ }
1073
+ case "optional":
1074
+ return { ...Schema.#node(def.inner, c), optional: true };
1075
+ case "nullable":
1076
+ case "nullish": {
1077
+ const node = Schema.#node(def.inner, c);
1078
+
1079
+ return {
1080
+ schema: { anyOf: [node.schema, { type: "null" }] },
1081
+ optional: def.type === "nullish" || node.optional,
1082
+ };
1083
+ }
1084
+ case "default": {
1085
+ const node = Schema.#node(def.inner, c);
1086
+
1087
+ if (c.io === "input")
1088
+ return {
1089
+ schema: Schema.#isJson(def.value)
1090
+ ? { ...node.schema, default: def.value }
1091
+ : node.schema,
1092
+ optional: true,
1093
+ };
1094
+
1095
+ // the default is output without validation by the inner schema
1096
+ if (def.value === undefined)
1097
+ return { schema: node.schema, optional: true };
1098
+ if (!def.inner.parse(def.value).issues) return { schema: node.schema };
1099
+ if (!Schema.#isJson(def.value))
1100
+ return Schema.#unrepresentable(c, "Non-JSON default");
1101
+
1102
+ return { schema: { anyOf: [node.schema, { const: def.value }] } };
1103
+ }
1104
+ case "preprocess":
1105
+ // any input, or none, may be preprocessed into a valid value, unless
1106
+ // the preprocessor only normalizes, where the input is the value
1107
+ return c.io === "input" && !normalizers.has(def.fn)
1108
+ ? { schema: {}, optional: true }
1109
+ : Schema.#node(def.inner, c);
1110
+ case "transform":
1111
+ return c.io === "input"
1112
+ ? Schema.#node(def.inner, c)
1113
+ : Schema.#unrepresentable(c, "Transform output");
1114
+ case "pipe":
1115
+ return Schema.#node(c.io === "input" ? def.inner : def.next, c);
1116
+ case "json": {
1117
+ if (c.io === "output") return Schema.#node(def.schema, c);
1118
+
1119
+ const node = Schema.#node(def.inner, c);
1120
+
1121
+ return {
1122
+ ...node,
1123
+ schema: {
1124
+ ...node.schema,
1125
+ contentMediaType: "application/json",
1126
+ // contentSchema was added after draft-07
1127
+ ...(c.target === "draft-2020-12" && {
1128
+ contentSchema: Schema.#node(def.schema, c).schema,
1129
+ }),
1130
+ },
1131
+ };
1132
+ }
1133
+ case "check": {
1134
+ const node = Schema.#node(def.inner, c);
1135
+
1136
+ // checks constrain the output, so they describe the input only when it is unchanged
1137
+ if (c.io === "input" && !Schema.#unchanged(def.inner.def)) return node;
1138
+
1139
+ return {
1140
+ ...node,
1141
+ schema: {
1142
+ ...node.schema,
1143
+ ...Schema.#keywords(def.check, node.schema),
1144
+ },
1145
+ };
1146
+ }
1147
+ }
1148
+ }
1149
+
1150
+ /**
1151
+ * @param def Schema definition
1152
+ * @returns `true` when parsing never changes a valid value
1153
+ */
1154
+ static #unchanged(def: Schema.Def): boolean {
1155
+ switch (def.type) {
1156
+ case "preprocess":
1157
+ // a normalizer leaves a valid value as it is
1158
+ return normalizers.has(def.fn) && Schema.#unchanged(def.inner.def);
1159
+ case "transform":
1160
+ case "json":
1161
+ return false;
1162
+ case "pipe":
1163
+ return (
1164
+ Schema.#unchanged(def.inner.def) && Schema.#unchanged(def.next.def)
1165
+ );
1166
+ case "union":
1167
+ return def.options.every((schema) => Schema.#unchanged(schema.def));
1168
+ case "optional":
1169
+ case "nullable":
1170
+ case "nullish":
1171
+ case "default":
1172
+ case "check":
1173
+ return Schema.#unchanged(def.inner.def);
1174
+ }
1175
+
1176
+ return true;
1177
+ }
1178
+
1179
+ /**
1180
+ * @param check Output check
1181
+ * @param schema Description being checked
1182
+ * @returns JSON Schema keywords equivalent to the check
1183
+ */
1184
+ static #keywords(check: Schema.Check, schema: Record<string, unknown>) {
1185
+ switch (check.name) {
1186
+ case "email":
1187
+ case "uuid":
1188
+ return { format: check.name };
1189
+ case "url":
1190
+ return { format: "uri" };
1191
+ case "int":
1192
+ return schema.type === "number" && { type: "integer" };
1193
+ case "min":
1194
+ case "max": {
1195
+ if (typeof check.value !== "number") return;
1196
+
1197
+ const min = check.name === "min";
1198
+ const length = schema.type === "string";
1199
+ const key = length
1200
+ ? `${check.name}Length`
1201
+ : (schema.type === "number" || schema.type === "integer") &&
1202
+ (min ? "minimum" : "maximum");
1203
+
1204
+ if (!key) return;
1205
+
1206
+ // lengths are integers, so fractional bounds round inward
1207
+ const value = length
1208
+ ? min
1209
+ ? Math.max(0, Math.ceil(check.value))
1210
+ : Math.floor(check.value)
1211
+ : check.value;
1212
+ const current = schema[key];
1213
+
1214
+ // repeated bounds all apply, so keep the strictest
1215
+ return {
1216
+ [key]:
1217
+ typeof current !== "number"
1218
+ ? value
1219
+ : min
1220
+ ? Math.max(current, value)
1221
+ : Math.min(current, value),
1222
+ };
609
1223
  }
1224
+ }
1225
+ }
610
1226
 
611
- return schema.parse(data, path);
612
- });
1227
+ /**
1228
+ * @param c Description context
1229
+ * @param name Unrepresentable schema name
1230
+ * @returns `{}` when allowed by `c`
1231
+ */
1232
+ static #unrepresentable(
1233
+ c: Schema.JsonSchema.Context,
1234
+ name: string,
1235
+ ): Schema.JsonSchema.Node {
1236
+ if (c.unrepresentable === "any") return { schema: {} };
1237
+
1238
+ throw new TypeError(`${name} cannot be represented in JSON Schema`);
1239
+ }
1240
+
1241
+ /**
1242
+ * @param value Value to check
1243
+ * @returns `true` when the value round-trips through JSON unchanged
1244
+ */
1245
+ static #isJson(value: unknown): boolean {
1246
+ if (
1247
+ value === null ||
1248
+ typeof value === "string" ||
1249
+ typeof value === "boolean"
1250
+ )
1251
+ return true;
1252
+ if (typeof value === "number") return Number.isFinite(value);
1253
+ if (Array.isArray(value)) return value.every(Schema.#isJson);
1254
+ if (
1255
+ typeof value === "object" &&
1256
+ Object.getPrototypeOf(value) === Object.prototype
1257
+ )
1258
+ return Object.values(value).every(Schema.#isJson);
1259
+
1260
+ return false;
1261
+ }
1262
+
1263
+ /**
1264
+ * @param c Description context
1265
+ * @param values Allowed literal values
1266
+ * @returns `const` or `enum` description, optional when `undefined` is allowed
1267
+ */
1268
+ static #values(
1269
+ c: Schema.JsonSchema.Context,
1270
+ values: readonly unknown[],
1271
+ ): Schema.JsonSchema.Node {
1272
+ const defined = values.filter((v) => v !== undefined);
1273
+
1274
+ if (!defined.every(Schema.#isJson)) {
1275
+ return Schema.#unrepresentable(c, "Non-JSON literal");
1276
+ }
1277
+
1278
+ return {
1279
+ // `not: {}` matches nothing, so the key must be absent
1280
+ schema:
1281
+ defined.length === 0
1282
+ ? { not: {} }
1283
+ : defined.length === 1
1284
+ ? { const: defined[0] }
1285
+ : { enum: defined },
1286
+ optional: defined.length < values.length,
1287
+ };
613
1288
  }
614
1289
 
615
1290
  /**
616
- * Validate an input is a valid email string using
617
- * [Reasonable Email Regex by Colin McDonnell](https://colinhacks.com/essays/reasonable-email-regex).
618
- *
619
1291
  * @template T Field tag name
620
1292
  * @template U Field input type attribute
621
1293
  * @template V Field option values
622
- * @param message Issue message when invalid
623
- * @returns Email field
1294
+ * @returns Optional field
624
1295
  */
625
- email<
1296
+ optional<
626
1297
  T extends Field.Tag,
627
1298
  U extends Field.Type,
628
- V extends Field.Values | undefined,
1299
+ V extends Field.Options | undefined,
629
1300
  >(
630
- this: Field.Instance<string, T, U, V>,
631
- message?: string,
632
- ): Field.Instance<string, T, U, V>;
1301
+ this: Field.Instance<Output, T, U, V>,
1302
+ ): Field.Instance<Output | undefined, T, U, V>;
633
1303
  /**
634
- * Validate an input is a valid email string using
635
- * [Reasonable Email Regex by Colin McDonnell](https://colinhacks.com/essays/reasonable-email-regex).
636
- *
637
- * @param message Issue message when invalid
638
- * @returns Email schema
1304
+ * @returns Optional schema
639
1305
  */
640
- email(this: Schema<string>, message?: string): Schema<string>;
641
- email(this: Schema<string>, message = "Expected email") {
642
- return this.refine((s) => Schema.#emailRegex.test(s), message);
1306
+ optional(this: Schema<Output>): Schema<Output | undefined>;
1307
+ optional(this: Schema<Output>) {
1308
+ return this.derive<Output | undefined>({ type: "optional", inner: this });
643
1309
  }
644
1310
 
645
1311
  /**
646
- * Validate an input is a valid URL string.
647
- *
648
1312
  * @template T Field tag name
649
1313
  * @template U Field input type attribute
650
1314
  * @template V Field option values
651
- * @param message Issue message when invalid
652
- * @returns URL field
1315
+ * @returns Nullable field
653
1316
  */
654
- url<
1317
+ nullable<
655
1318
  T extends Field.Tag,
656
1319
  U extends Field.Type,
657
- V extends Field.Values | undefined,
1320
+ V extends Field.Options | undefined,
658
1321
  >(
659
- this: Field.Instance<string, T, U, V>,
660
- message?: string,
661
- ): Field.Instance<string, T, U, V>;
1322
+ this: Field.Instance<Output, T, U, V>,
1323
+ ): Field.Instance<Output | null, T, U, V>;
662
1324
  /**
663
- * Validate an input is a valid URL string.
664
- *
665
- * @param message Issue message when invalid
666
- * @returns URL schema
1325
+ * @returns Nullable schema
667
1326
  */
668
- url(this: Schema<string>, message?: string): Schema<string>;
669
- url(this: Schema<string>, message = "Expected URL") {
670
- return this.refine(URL.canParse, message);
1327
+ nullable(this: Schema<Output>): Schema<Output | null>;
1328
+ nullable(this: Schema<Output>) {
1329
+ return this.derive<Output | null>({ type: "nullable", inner: this });
671
1330
  }
672
1331
 
673
1332
  /**
674
- * Validate an input is a safe integer.
675
- *
676
1333
  * @template T Field tag name
677
1334
  * @template U Field input type attribute
678
1335
  * @template V Field option values
679
- * @param message Issue message when invalid
680
- * @returns Integer field
1336
+ * @returns Nullish field
681
1337
  */
682
- int<
1338
+ nullish<
683
1339
  T extends Field.Tag,
684
1340
  U extends Field.Type,
685
- V extends Field.Values | undefined,
1341
+ V extends Field.Options | undefined,
686
1342
  >(
687
- this: Field.Instance<number, T, U, V>,
688
- message?: string,
689
- ): Field.Instance<number, T, U, V>;
1343
+ this: Field.Instance<Output, T, U, V>,
1344
+ ): Field.Instance<Output | null | undefined, T, U, V>;
690
1345
  /**
691
- * Validate an input is a safe integer.
692
- *
693
- * @param message Issue message when invalid
694
- * @returns Integer schema
1346
+ * @returns Nullish schema
695
1347
  */
696
- int(this: Schema<number>, message?: string): Schema<number>;
697
- int(this: Schema<number>, message = "Expected integer") {
698
- return this.refine(Number.isSafeInteger, message);
1348
+ nullish(this: Schema<Output>): Schema<Output | null | undefined>;
1349
+ nullish(this: Schema<Output>) {
1350
+ return this.derive<Output | null | undefined>({
1351
+ type: "nullish",
1352
+ inner: this,
1353
+ });
699
1354
  }
700
1355
 
701
1356
  /**
702
- * Validate an input is greater than or equal to the minimum.
703
- *
704
- * For strings, this validates minimum length.
705
- *
706
1357
  * @template T Field tag name
707
1358
  * @template U Field input type attribute
708
1359
  * @template V Field option values
709
- * @param value Minimum value or length
710
- * @param message Issue message when invalid
711
- * @returns Refined field
1360
+ * @param value Default value to use when input is undefined
1361
+ * @returns Field with default
712
1362
  */
713
- min<
1363
+ default<
714
1364
  T extends Field.Tag,
715
1365
  U extends Field.Type,
716
- V extends Field.Values | undefined,
1366
+ V extends Field.Options | undefined,
717
1367
  >(
718
- this: Field.Instance<string, T, U, V>,
719
- value: number,
720
- message?: string,
721
- ): Field.Instance<string, T, U, V>;
1368
+ this: Field.Instance<Output, T, U, V>,
1369
+ value: Output,
1370
+ ): Field.Instance<Output, T, U, V>;
1371
+ /**
1372
+ * @param value Default value to use when input is undefined
1373
+ * @returns Schema with default
1374
+ */
1375
+ default(this: Schema<Output>, value: Output): Schema<Output>;
1376
+ default(this: Schema<Output>, value: Output) {
1377
+ return this.derive<Output>({ type: "default", inner: this, value });
1378
+ }
1379
+
722
1380
  /**
723
- * Validate an input is greater than or equal to the minimum.
724
- *
725
1381
  * @template T Field tag name
726
1382
  * @template U Field input type attribute
727
1383
  * @template V Field option values
728
- * @param value Minimum value
729
- * @param message Issue message when invalid
730
- * @returns Refined field
1384
+ * @param fn Preprocess function to run before parsing
1385
+ * @returns Schema that preprocesses input before parsing
731
1386
  */
732
- min<
1387
+ preprocess<
733
1388
  T extends Field.Tag,
734
1389
  U extends Field.Type,
735
- V extends Field.Values | undefined,
1390
+ V extends Field.Options | undefined,
736
1391
  >(
737
- this: Field.Instance<number, T, U, V>,
738
- value: number,
739
- message?: string,
740
- ): Field.Instance<number, T, U, V>;
1392
+ this: Field.Instance<Output, T, U, V>,
1393
+ fn: (value: unknown) => unknown,
1394
+ ): Field.Instance<Output, T, U, V>;
741
1395
  /**
742
- * Validate an input is greater than or equal to the minimum.
743
- *
1396
+ * @param fn Preprocess function to run before parsing
1397
+ * @returns Schema that preprocesses input before parsing
1398
+ */
1399
+ preprocess(
1400
+ this: Schema<Output>,
1401
+ fn: (value: unknown) => unknown,
1402
+ ): Schema<Output>;
1403
+ preprocess(this: Schema<Output>, fn: (value: unknown) => unknown) {
1404
+ return this.derive<Output>({ type: "preprocess", inner: this, fn });
1405
+ }
1406
+
1407
+ /**
1408
+ * @template O Output type after transformation
744
1409
  * @template T Field tag name
745
1410
  * @template U Field input type attribute
746
1411
  * @template V Field option values
747
- * @param value Minimum value
748
- * @param message Issue message when invalid
749
- * @returns Refined field
1412
+ * @param fn Transform function to apply to parsed output
1413
+ * @returns Transformed field
750
1414
  */
751
- min<
1415
+ transform<
1416
+ O,
752
1417
  T extends Field.Tag,
753
1418
  U extends Field.Type,
754
- V extends Field.Values | undefined,
1419
+ V extends Field.Options | undefined,
755
1420
  >(
756
- this: Field.Instance<bigint, T, U, V>,
757
- value: bigint,
1421
+ this: Field.Instance<Output, T, U, V>,
1422
+ fn: (value: Output) => O,
1423
+ ): Field.Instance<O, T, U, V>;
1424
+ /**
1425
+ * @template O Output type after transformation
1426
+ * @param fn Transform function to apply to parsed output
1427
+ * @returns Transformed schema
1428
+ */
1429
+ transform<O>(this: Schema<Output>, fn: (value: Output) => O): Schema<O>;
1430
+ transform<O>(this: Schema<Output>, fn: (value: Output) => O) {
1431
+ return this.derive<O>({ type: "transform", inner: this, fn });
1432
+ }
1433
+
1434
+ /**
1435
+ * @template O Output type after pipe
1436
+ * @template T Field tag name
1437
+ * @template U Field input type attribute
1438
+ * @template V Field option values
1439
+ * @param next Schema to validate the result with
1440
+ * @returns Piped field
1441
+ */
1442
+ pipe<
1443
+ O,
1444
+ T extends Field.Tag,
1445
+ U extends Field.Type,
1446
+ V extends Field.Options | undefined,
1447
+ >(
1448
+ this: Field.Instance<Output, T, U, V>,
1449
+ next: Schema<O>,
1450
+ ): Field.Instance<O, T, U, V>;
1451
+ /**
1452
+ * @template O Output type after pipe
1453
+ * @param next Schema to validate the result with
1454
+ * @returns Piped schema
1455
+ */
1456
+ pipe<O>(this: Schema<Output>, next: Schema<O>): Schema<O>;
1457
+ pipe<O>(this: Schema<Output>, next: Schema<O>) {
1458
+ return this.derive<O>({ type: "pipe", inner: this, next });
1459
+ }
1460
+
1461
+ /**
1462
+ * Parse a JSON string and validate the parsed value with the provided schema.
1463
+ *
1464
+ * @template O Output type
1465
+ * @template T Field tag name
1466
+ * @template U Field input type attribute
1467
+ * @template V Field option values
1468
+ * @param schema Schema to validate the parsed JSON value with
1469
+ * @param message Issue message when invalid
1470
+ * @returns Parsed JSON field
1471
+ */
1472
+ json<
1473
+ O,
1474
+ T extends Field.Tag,
1475
+ U extends Field.Type,
1476
+ V extends Field.Options | undefined,
1477
+ >(
1478
+ this: Field.Instance<string, T, U, V>,
1479
+ schema: Schema<O>,
758
1480
  message?: string,
759
- ): Field.Instance<bigint, T, U, V>;
1481
+ ): Field.Instance<O, T, U, V>;
760
1482
  /**
761
- * Validate an input is greater than or equal to the minimum.
1483
+ * Parse a JSON string and validate the parsed value with the provided schema.
1484
+ *
1485
+ * @template O Output type
1486
+ * @param schema Schema to validate the parsed JSON value with
1487
+ * @param message Issue message when invalid
1488
+ * @returns Parsed JSON schema
1489
+ */
1490
+ json<O>(this: Schema<string>, schema: Schema<O>, message?: string): Schema<O>;
1491
+ json<O>(this: Schema<string>, schema: Schema<O>, message?: string) {
1492
+ return this.derive<O>({ type: "json", inner: this, schema, message });
1493
+ }
1494
+
1495
+ /**
1496
+ * Validate an input is a valid email string using
1497
+ * [Reasonable Email Regex by Colin McDonnell](https://colinhacks.com/essays/reasonable-email-regex).
762
1498
  *
763
- * For strings, this validates minimum length.
1499
+ * @template T Field tag name
1500
+ * @template U Field input type attribute
1501
+ * @template V Field option values
1502
+ * @param message Issue message when invalid
1503
+ * @returns Email field
1504
+ */
1505
+ email<
1506
+ T extends Field.Tag,
1507
+ U extends Field.Type,
1508
+ V extends Field.Options | undefined,
1509
+ >(
1510
+ this: Field.Instance<string, T, U, V>,
1511
+ message?: string,
1512
+ ): Field.Instance<string, T, U, V>;
1513
+ /**
1514
+ * Validate an input is a valid email string using
1515
+ * [Reasonable Email Regex by Colin McDonnell](https://colinhacks.com/essays/reasonable-email-regex).
764
1516
  *
765
- * @param value Minimum value or length
766
1517
  * @param message Issue message when invalid
767
- * @returns Refined schema
1518
+ * @returns Email schema
768
1519
  */
769
- min(this: Schema<string>, value: number, message?: string): Schema<string>;
1520
+ email(this: Schema<string>, message?: string): Schema<string>;
1521
+ email(this: Schema<string>, message = "Expected email") {
1522
+ return this.#check({ name: "email", message });
1523
+ }
1524
+
770
1525
  /**
771
- * Validate an input is greater than or equal to the minimum.
1526
+ * Validate an input is a UUID string of any version.
772
1527
  *
773
- * @param value Minimum value
1528
+ * @template T Field tag name
1529
+ * @template U Field input type attribute
1530
+ * @template V Field option values
774
1531
  * @param message Issue message when invalid
775
- * @returns Refined schema
1532
+ * @returns UUID field
776
1533
  */
777
- min(this: Schema<number>, value: number, message?: string): Schema<number>;
1534
+ uuid<
1535
+ T extends Field.Tag,
1536
+ U extends Field.Type,
1537
+ V extends Field.Options | undefined,
1538
+ >(
1539
+ this: Field.Instance<string, T, U, V>,
1540
+ message?: string,
1541
+ ): Field.Instance<string, T, U, V>;
778
1542
  /**
779
- * Validate an input is greater than or equal to the minimum.
1543
+ * Validate an input is a UUID string of any version.
780
1544
  *
781
- * @param value Minimum value
782
1545
  * @param message Issue message when invalid
783
- * @returns Refined schema
1546
+ * @returns UUID schema
784
1547
  */
785
- min(this: Schema<bigint>, value: bigint, message?: string): Schema<bigint>;
786
- min(
787
- this: Schema<string | number | bigint>,
788
- value: number | bigint,
789
- message = `Expected minimum ${String(value)}`,
790
- ) {
791
- return this.refine((next) => {
792
- return typeof next === "string"
793
- ? next.length >= (value as number)
794
- : next >= (value as number | bigint);
795
- }, message);
1548
+ uuid(this: Schema<string>, message?: string): Schema<string>;
1549
+ uuid(this: Schema<string>, message = "Expected UUID") {
1550
+ return this.#check({ name: "uuid", message });
796
1551
  }
797
1552
 
798
1553
  /**
799
- * Validate an input is less than or equal to the maximum.
1554
+ * Validate an input is a valid URL string.
1555
+ *
1556
+ * @template T Field tag name
1557
+ * @template U Field input type attribute
1558
+ * @template V Field option values
1559
+ * @param message Issue message when invalid
1560
+ * @returns URL field
1561
+ */
1562
+ url<
1563
+ T extends Field.Tag,
1564
+ U extends Field.Type,
1565
+ V extends Field.Options | undefined,
1566
+ >(
1567
+ this: Field.Instance<string, T, U, V>,
1568
+ message?: string,
1569
+ ): Field.Instance<string, T, U, V>;
1570
+ /**
1571
+ * Validate an input is a valid URL string.
800
1572
  *
801
- * For strings, this validates maximum length.
1573
+ * @param message Issue message when invalid
1574
+ * @returns URL schema
1575
+ */
1576
+ url(this: Schema<string>, message?: string): Schema<string>;
1577
+ url(this: Schema<string>, message = "Expected URL") {
1578
+ return this.#check({ name: "url", message });
1579
+ }
1580
+
1581
+ /**
1582
+ * Validate an input is a safe integer.
802
1583
  *
803
1584
  * @template T Field tag name
804
1585
  * @template U Field input type attribute
805
1586
  * @template V Field option values
806
- * @param value Maximum value or length
1587
+ * @param message Issue message when invalid
1588
+ * @returns Integer field
1589
+ */
1590
+ int<
1591
+ T extends Field.Tag,
1592
+ U extends Field.Type,
1593
+ V extends Field.Options | undefined,
1594
+ >(
1595
+ this: Field.Instance<number, T, U, V>,
1596
+ message?: string,
1597
+ ): Field.Instance<number, T, U, V>;
1598
+ /**
1599
+ * Validate an input is a safe integer.
1600
+ *
1601
+ * @param message Issue message when invalid
1602
+ * @returns Integer schema
1603
+ */
1604
+ int(this: Schema<number>, message?: string): Schema<number>;
1605
+ int(this: Schema<number>, message = "Expected integer") {
1606
+ return this.#check({ name: "int", message });
1607
+ }
1608
+
1609
+ /**
1610
+ * Validate an input is greater than or equal to the minimum.
1611
+ *
1612
+ * For strings, this validates minimum length in Unicode characters,
1613
+ * as JSON Schema and Postgres count them.
1614
+ *
1615
+ * @template T Field tag name
1616
+ * @template U Field input type attribute
1617
+ * @template V Field option values
1618
+ * @param value Minimum value or length
807
1619
  * @param message Issue message when invalid
808
1620
  * @returns Refined field
809
1621
  */
810
- max<
1622
+ min<
811
1623
  T extends Field.Tag,
812
1624
  U extends Field.Type,
813
- V extends Field.Values | undefined,
1625
+ V extends Field.Options | undefined,
814
1626
  >(
815
1627
  this: Field.Instance<string, T, U, V>,
816
1628
  value: number,
817
1629
  message?: string,
818
1630
  ): Field.Instance<string, T, U, V>;
819
1631
  /**
820
- * Validate an input is less than or equal to the maximum.
1632
+ * Validate an input is greater than or equal to the minimum.
821
1633
  *
822
1634
  * @template T Field tag name
823
1635
  * @template U Field input type attribute
824
1636
  * @template V Field option values
825
- * @param value Maximum value
1637
+ * @param value Minimum value
826
1638
  * @param message Issue message when invalid
827
1639
  * @returns Refined field
828
1640
  */
829
- max<
1641
+ min<
830
1642
  T extends Field.Tag,
831
1643
  U extends Field.Type,
832
- V extends Field.Values | undefined,
1644
+ V extends Field.Options | undefined,
833
1645
  >(
834
1646
  this: Field.Instance<number, T, U, V>,
835
1647
  value: number,
836
1648
  message?: string,
837
1649
  ): Field.Instance<number, T, U, V>;
838
1650
  /**
839
- * Validate an input is less than or equal to the maximum.
1651
+ * Validate an input is greater than or equal to the minimum.
840
1652
  *
841
1653
  * @template T Field tag name
842
1654
  * @template U Field input type attribute
843
1655
  * @template V Field option values
844
- * @param value Maximum value
1656
+ * @param value Minimum value
845
1657
  * @param message Issue message when invalid
846
1658
  * @returns Refined field
847
1659
  */
848
- max<
1660
+ min<
849
1661
  T extends Field.Tag,
850
1662
  U extends Field.Type,
851
- V extends Field.Values | undefined,
1663
+ V extends Field.Options | undefined,
852
1664
  >(
853
1665
  this: Field.Instance<bigint, T, U, V>,
854
1666
  value: bigint,
855
1667
  message?: string,
856
1668
  ): Field.Instance<bigint, T, U, V>;
857
1669
  /**
858
- * Validate an input is less than or equal to the maximum.
1670
+ * Validate an input is greater than or equal to the minimum.
859
1671
  *
860
- * For strings, this validates maximum length.
1672
+ * For strings, this validates minimum length in Unicode characters,
1673
+ * as JSON Schema and Postgres count them.
861
1674
  *
862
- * @param value Maximum value or length
1675
+ * @param value Minimum value or length
863
1676
  * @param message Issue message when invalid
864
1677
  * @returns Refined schema
865
1678
  */
866
- max(this: Schema<string>, value: number, message?: string): Schema<string>;
1679
+ min(this: Schema<string>, value: number, message?: string): Schema<string>;
867
1680
  /**
868
- * Validate an input is less than or equal to the maximum.
1681
+ * Validate an input is greater than or equal to the minimum.
869
1682
  *
870
- * @param value Maximum value
1683
+ * @param value Minimum value
871
1684
  * @param message Issue message when invalid
872
1685
  * @returns Refined schema
873
1686
  */
874
- max(this: Schema<number>, value: number, message?: string): Schema<number>;
1687
+ min(this: Schema<number>, value: number, message?: string): Schema<number>;
875
1688
  /**
876
- * Validate an input is less than or equal to the maximum.
1689
+ * Validate an input is greater than or equal to the minimum.
877
1690
  *
878
- * @param value Maximum value
1691
+ * @param value Minimum value
879
1692
  * @param message Issue message when invalid
880
1693
  * @returns Refined schema
881
1694
  */
882
- max(this: Schema<bigint>, value: bigint, message?: string): Schema<bigint>;
883
- max(
1695
+ min(this: Schema<bigint>, value: bigint, message?: string): Schema<bigint>;
1696
+ min(
884
1697
  this: Schema<string | number | bigint>,
885
1698
  value: number | bigint,
886
- message = `Expected maximum ${String(value)}`,
1699
+ message = `Expected minimum ${value}`,
887
1700
  ) {
888
- return this.refine((next) => {
889
- return typeof next === "string"
890
- ? next.length <= (value as number)
891
- : next <= (value as number | bigint);
892
- }, message);
1701
+ return this.#check({ name: "min", value, message });
893
1702
  }
894
1703
 
895
1704
  /**
1705
+ * Validate an input is less than or equal to the maximum.
1706
+ *
1707
+ * For strings, this validates maximum length in Unicode characters,
1708
+ * as JSON Schema and Postgres count them.
1709
+ *
896
1710
  * @template T Field tag name
897
1711
  * @template U Field input type attribute
898
1712
  * @template V Field option values
899
- * @param check Validation function that returns `false` to fail
1713
+ * @param value Maximum value or length
900
1714
  * @param message Issue message when invalid
901
1715
  * @returns Refined field
902
1716
  */
903
- refine<
1717
+ max<
904
1718
  T extends Field.Tag,
905
1719
  U extends Field.Type,
906
- V extends Field.Values | undefined,
1720
+ V extends Field.Options | undefined,
907
1721
  >(
908
- this: Field.Instance<Output, T, U, V>,
909
- check: (value: Output) => boolean,
910
- message: string,
911
- ): Field.Instance<Output, T, U, V>;
912
- /**
913
- * @param check Validation function that returns `false` to fail
914
- * @param message Issue message when invalid
915
- * @returns Refined schema
916
- */
917
- refine(
918
- this: Schema<Output>,
919
- check: (value: Output) => boolean,
920
- message: string,
921
- ): Schema<Output>;
922
- refine(
923
- this: Schema<Output>,
924
- check: (value: Output) => boolean,
925
- message: string,
926
- ) {
927
- return this.derive((v, path) => {
928
- const out = this.parse(v, path);
929
-
930
- return out.issues || check(out.data)
931
- ? out
932
- : new Schema.AggregateIssue([
933
- new Schema.Issue("refine", path, message),
934
- ]);
935
- });
936
- }
937
-
938
- /**
939
- * Accepts any value and presents the data as `unknown`.
940
- *
941
- * @returns Unknown schema
942
- */
943
- static unknown() {
944
- return new Schema((v) => ({ data: v }));
945
- }
946
-
947
- /**
948
- * Validate an input is a string.
949
- *
950
- * @param message Issue message when invalid
951
- * @returns String schema
952
- */
953
- static string(message?: string) {
954
- return new Schema((v, path) => {
955
- return typeof v === "string"
956
- ? { data: v }
957
- : new Schema.AggregateIssue([
958
- new Schema.Issue("string", path, message),
959
- ]);
960
- });
961
- }
962
-
963
- /**
964
- * Validate an input is a `true` or `false` boolean.
965
- *
966
- * @param message Issue message when invalid
967
- * @returns Boolean schema
968
- */
969
- static boolean(message?: string) {
970
- return new Schema((v, path) => {
971
- return typeof v === "boolean"
972
- ? { data: v }
973
- : new Schema.AggregateIssue([
974
- new Schema.Issue("boolean", path, message),
975
- ]);
976
- });
977
- }
978
-
979
- /**
980
- * Validate an input is a number.
981
- *
982
- * Rejects non-finite values like `NaN` and `Infinity`.
983
- *
984
- * @param message Issue message when invalid
985
- * @returns Number schema
986
- */
987
- static number(message?: string) {
988
- return new Schema((v, path) => {
989
- return Number.isFinite(v) // isFinite checks type
990
- ? { data: v as number }
991
- : new Schema.AggregateIssue([
992
- new Schema.Issue("number", path, message),
993
- ]);
994
- });
995
- }
996
-
997
- /**
998
- * Validate an input is a big integer.
999
- *
1000
- * @param message Issue message when invalid
1001
- * @returns Big integer schema
1002
- */
1003
- static bigint(message?: string) {
1004
- return new Schema((v, path) => {
1005
- return typeof v === "bigint"
1006
- ? { data: v }
1007
- : new Schema.AggregateIssue([
1008
- new Schema.Issue("bigint", path, message),
1009
- ]);
1010
- });
1011
- }
1012
-
1013
- /**
1014
- * @template L Literal type
1015
- * @param literal Exact value to match
1016
- * @param message Issue message when invalid
1017
- * @returns Literal schema
1018
- */
1019
- static literal<const L>(literal: L, message?: string) {
1020
- return new Schema((v, path) => {
1021
- return v === literal
1022
- ? { data: literal }
1023
- : new Schema.AggregateIssue([new Schema.Issue(literal, path, message)]);
1024
- });
1025
- }
1026
-
1027
- /**
1028
- * Validates that the input is strictly equal (`===`) to one of the allowed
1029
- * values.
1030
- *
1031
- * @template A Allowed type
1032
- * @param allowed Allowed values
1033
- * @param message Issue message when invalid
1034
- * @returns Enum schema
1035
- */
1036
- static enum<const A extends readonly [unknown, ...unknown[]]>(
1037
- allowed: A,
1722
+ this: Field.Instance<string, T, U, V>,
1723
+ value: number,
1038
1724
  message?: string,
1039
- ) {
1040
- return new Schema<A[number]>((v, path) => {
1041
- for (const a of allowed) {
1042
- if (v === a) return { data: a };
1043
- }
1044
-
1045
- return new Schema.AggregateIssue([
1046
- new Schema.Issue(
1047
- allowed.map((v) => JSON.stringify(v)).join(" | "),
1048
- path,
1049
- message,
1050
- ),
1051
- ]);
1052
- });
1053
- }
1054
-
1055
- /**
1056
- * Tries each schema in order and returns the first successfully parsed result.
1057
- *
1058
- * @template S Schemas type
1059
- * @param schemas Schemas to try in order
1060
- * @returns Union schema
1061
- */
1062
- static union<
1063
- const S extends readonly [Schema<unknown>, ...Schema<unknown>[]],
1064
- >(schemas: S) {
1065
- return new Schema((v, path) => {
1066
- const issues: Schema.Issue[] = [];
1067
-
1068
- for (const schema of schemas) {
1069
- const result = schema.parse(v, path);
1070
-
1071
- if (!result.issues) {
1072
- // return as soon as one passes
1073
- return result as Schema.Parse.Result<Schema.Infer<S[number]>>;
1074
- }
1075
-
1076
- issues.push(...result.issues);
1077
- }
1078
-
1079
- return new Schema.AggregateIssue(issues);
1080
- });
1081
- }
1082
-
1083
- /**
1084
- * Validates an input is an instance of the constructor.
1085
- *
1086
- * @template O Output type
1087
- * @param constructor Constructor to validate the input is an instance of
1088
- * @param message Issue message when invalid
1089
- * @returns Validated instance
1090
- */
1091
- static instance<O>(constructor: new (...args: any[]) => O, message?: string) {
1092
- return new Schema((v, path) =>
1093
- v instanceof constructor
1094
- ? { data: v }
1095
- : new Schema.AggregateIssue([
1096
- new Schema.Issue(constructor.name, path, message),
1097
- ]),
1098
- );
1099
- }
1100
-
1101
- /**
1102
- * Validates that the input is an array and parses each item.
1103
- *
1104
- * @template O Output type
1105
- * @param schema Schema for each array item
1106
- * @param message Issue message when invalid
1107
- * @returns Array schema
1108
- */
1109
- static array<O>(schema: Schema<O>, message?: string) {
1110
- return new Schema((v, path) => {
1111
- if (!Array.isArray(v)) {
1112
- return new Schema.AggregateIssue([
1113
- new Schema.Issue("Array", path, message),
1114
- ]);
1115
- }
1116
-
1117
- const data: O[] = [];
1118
- const issues: Schema.Issue[] = [];
1119
-
1120
- for (let i = 0; i < v.length; i++) {
1121
- const result = schema.parse(v[i], [...path, i]);
1122
-
1123
- if (result.issues) {
1124
- issues.push(...result.issues);
1125
- } else {
1126
- data.push(result.data);
1127
- }
1128
- }
1129
-
1130
- if (issues.length) return new Schema.AggregateIssue(issues);
1131
-
1132
- return { data };
1133
- });
1134
- }
1135
-
1136
- /**
1137
- * Validates each key in the shape and returns a new object of parsed outputs.
1138
- *
1139
- * @template S Object shape type
1140
- * @param shape Object shape with schemas for each key
1141
- * @returns Object schema
1142
- */
1143
- static object<S extends Schema.Object.Shape = {}>(
1144
- shape: S = {} as S,
1145
- ): Schema.Object<S> {
1146
- return new ObjectSchema(shape, "strip");
1147
- }
1148
- }
1149
-
1150
- /**
1151
- * Runtime object schema that validates plain objects and supports shape helpers.
1152
- *
1153
- * @template Shape Object shape type
1154
- * @template Mode Object parsing mode
1155
- */
1156
- class ObjectSchema<
1157
- Shape extends Schema.Object.Shape,
1158
- Mode extends Schema.Object.Mode = "strip",
1159
- > extends Schema<Schema.Object.Output<Shape, Mode>> {
1160
- /** Object shape definitions. */
1161
- readonly shape: Shape;
1162
-
1163
- /** Object parsing mode. */
1164
- readonly #mode: Mode;
1165
-
1166
- /**
1167
- * Create a new object schema validator.
1168
- *
1169
- * @param shape Object shape
1170
- * @param mode Object parsing mode
1171
- */
1172
- constructor(shape: Shape, mode: Mode = "strip" as Mode) {
1173
- super((value, path) => {
1174
- if (value == null || typeof value !== "object" || Array.isArray(value)) {
1175
- return new Schema.AggregateIssue([new Schema.Issue("Object", path)]);
1176
- }
1177
-
1178
- const data: Record<string, unknown> = {};
1179
- const issues: Schema.Issue[] = [];
1180
-
1181
- for (const [name, schema] of Object.entries(shape)) {
1182
- const result = schema.parse((value as Record<string, unknown>)[name], [
1183
- ...path,
1184
- name,
1185
- ]);
1186
-
1187
- if (result.issues) {
1188
- issues.push(...result.issues);
1189
- } else if (result.data !== undefined) {
1190
- data[name] = result.data;
1191
- }
1192
- }
1193
-
1194
- if (mode !== "strip") {
1195
- const names = new Set(Object.keys(shape));
1196
-
1197
- for (const [name, next] of Object.entries(
1198
- value as Record<string, unknown>,
1199
- )) {
1200
- if (!names.has(name)) {
1201
- if (mode === "strict") {
1202
- issues.push(
1203
- new Schema.Issue("never", [...path, name], "Unexpected key"),
1204
- );
1205
- } else {
1206
- data[name] = next;
1207
- }
1208
- }
1209
- }
1210
- }
1211
-
1212
- return issues.length
1213
- ? new Schema.AggregateIssue(issues)
1214
- : ({ data } as { data: Schema.Object.Output<Shape, Mode> });
1215
- });
1216
-
1217
- this.shape = shape;
1218
- this.#mode = mode;
1219
- }
1220
-
1221
- /**
1222
- * Merge `extra` into the current shape.
1223
- *
1224
- * @template E Extra shape type
1225
- * @param extra Extra shape or object schema to merge
1226
- * @returns New object schema with the merged shape
1227
- */
1228
- extend<E extends Schema.Object.Shape>(
1229
- extra: E,
1230
- ): Schema.Object<ShapeUtil.Extend<Shape, E>, Mode>;
1231
- extend<E extends Schema.Object.Shape>(
1232
- extra: Schema.Object<E>,
1233
- ): Schema.Object<ShapeUtil.Extend<Shape, E>, Mode>;
1234
- extend(extra: Schema.Object.Shape | Schema.Object<any>) {
1235
- return new ObjectSchema(
1236
- ShapeUtil.extend(
1237
- this.shape,
1238
- extra instanceof ObjectSchema ? extra.shape : extra,
1239
- ),
1240
- this.#mode,
1241
- );
1242
- }
1243
-
1244
- /**
1245
- * Keep only selected field names.
1246
- *
1247
- * @template N Selected key names
1248
- * @param names Non-empty list of key names to keep
1249
- * @returns New object schema with only selected keys
1250
- */
1251
- pick<N extends ShapeUtil.Name<Shape>>(
1252
- names: readonly [N, ...N[]],
1253
- ): Schema.Object<Pick<Shape, N>, Mode> {
1254
- return new ObjectSchema(ShapeUtil.pick(this.shape, names), this.#mode);
1255
- }
1256
-
1257
- /**
1258
- * Remove selected field names.
1259
- *
1260
- * @template N Removed key names
1261
- * @param names Non-empty list of key names to remove
1262
- * @returns New object schema without selected keys
1263
- */
1264
- omit<N extends ShapeUtil.Name<Shape>>(
1265
- names: readonly [N, ...N[]],
1266
- ): Schema.Object<Omit<Shape, N>, Mode> {
1267
- return new ObjectSchema(ShapeUtil.omit(this.shape, names), this.#mode);
1268
- }
1269
-
1270
- /**
1271
- * Reject unknown keys during parsing.
1272
- *
1273
- * @returns New object schema in strict mode
1274
- */
1275
- strict(): Schema.Object<Shape, "strict"> {
1276
- return new ObjectSchema(this.shape, "strict");
1277
- }
1278
-
1279
- /**
1280
- * Preserve unknown keys during parsing.
1281
- *
1282
- * @returns New object schema in loose mode
1283
- */
1284
- loose(): Schema.Object<Shape, "loose"> {
1285
- return new ObjectSchema(this.shape, "loose");
1286
- }
1287
- }
1288
-
1289
- export namespace Form {
1290
- /** Form field shape. */
1291
- export type Shape = Record<string, Field.Any>;
1292
-
1293
- /** Persisted form value */
1294
- export type Value = string | number | boolean | string[];
1295
-
1296
- export namespace Value {
1297
- /**
1298
- * Value map by field name.
1299
- *
1300
- * @template S Shape type
1301
- */
1302
- export type Map<S extends Shape = Shape> = Partial<
1303
- Record<ShapeUtil.Name<S>, Value>
1304
- >;
1305
- }
1306
-
1307
- /**
1308
- * Encoded form state.
1309
- *
1310
- * @template S Shape type to infer value keys from
1311
- */
1312
- export interface State<S extends Shape = Shape> {
1313
- /** Form id generated using the field names */
1314
- readonly id: string;
1315
-
1316
- /** Non-empty list of validation issues */
1317
- readonly issues?: Schema.Issue.List;
1318
-
1319
- /** Map of field names to possible values */
1320
- readonly values?: Value.Map<S>;
1321
- }
1322
-
1323
- export namespace Parse {
1324
- /**
1325
- * Field names that are not marked to stream as multipart parts.
1326
- *
1327
- * @template S Form shape
1328
- */
1329
- type NonStreamNames<S extends Shape> = {
1330
- [K in keyof S]-?: S[K] extends Field.Instance<any, any, any, any, infer P>
1331
- ? P extends true
1332
- ? never
1333
- : K
1334
- : never;
1335
- }[keyof S];
1336
-
1337
- /**
1338
- * Parsed data shape with streamed `stream()` fields removed.
1339
- *
1340
- * @template S Form shape
1341
- */
1342
- type NonStreamShape<S extends Shape> = Pick<S, NonStreamNames<S>>;
1343
-
1344
- /**
1345
- * Parsed form data output.
1346
- *
1347
- * @template S Form shape
1348
- */
1349
- export type Data<S extends Shape> = Schema.Infer<NonStreamShape<S>>;
1350
-
1351
- /**
1352
- * Form parse result.
1353
- *
1354
- * @template S Form shape
1355
- * @template M Extra invalid result metadata
1356
- */
1357
- export type Result<
1358
- S extends Shape,
1359
- M extends object = {},
1360
- > = Schema.Parse.Result<
1361
- Data<S>,
1362
- {
1363
- /** Encoded URL search param field state */
1364
- readonly search: Result.Search;
1365
-
1366
- /** Invalid parses do not expose remaining multipart parts */
1367
- readonly stream?: never;
1368
- } & M,
1369
- {
1370
- /** Rest of the multipart parts to stream */
1371
- readonly stream?: AsyncGenerator<Multipart.Part> | undefined;
1372
- }
1373
- >;
1374
-
1375
- export namespace Result {
1376
- /** Form search params iterable */
1377
- export type Search = [[(typeof Form.params)[1], string]] | undefined;
1378
- }
1379
- }
1380
- }
1381
-
1382
- /**
1383
- * Form schema with JSX rendering capabilities.
1384
- *
1385
- * Parses `FormData` or `URLSearchParams` and generates form field
1386
- * components.
1387
- *
1388
- * @template Shape Form field shape type
1389
- */
1390
- export class Form<Shape extends Form.Shape = Form.Shape> {
1391
- /** Query param keys ordered as `[return, form]`. */
1392
- static readonly params = ["_return", "_form"] as const;
1393
-
1394
- /** Maximum encoded state size in bytes. */
1395
- static readonly #maxStateBytes = 4 * Size.kb;
1396
-
1397
- /** Maximum serialized size for a single persisted value. */
1398
- static readonly #maxValueChars = 512;
1399
-
1400
- /** Schema used to validate persisted form values. */
1401
- static readonly #valueSchema = Schema.union([
1402
- Schema.string(),
1403
- Schema.number(),
1404
- Schema.boolean(),
1405
- Schema.array(Schema.string()),
1406
- ]);
1407
-
1408
- /** Form id. */
1409
- readonly #id: string;
1410
-
1411
- /** Field definitions. */
1412
- readonly shape: Shape;
1413
-
1414
- /** Field names in definition order. */
1415
- readonly names: ShapeUtil.Name<Shape>[];
1416
-
1417
- /** Maximum expected multipart parts derived from field cardinality. */
1418
- readonly parts: number;
1419
-
1420
- /**
1421
- * Create a new form schema validator.
1422
- *
1423
- * @param shape Form fields
1424
- */
1425
- constructor(shape: Shape) {
1426
- this.shape = shape;
1427
- this.names = Object.keys(this.shape) as ShapeUtil.Name<Shape>[];
1428
- this.#id = Checksum.djb2(this.names.join());
1429
- this.parts = Object.values(this.shape).reduce(
1430
- (sum, field) => sum + field.parts,
1431
- 0,
1432
- );
1433
- }
1434
-
1435
- /**
1436
- * Merge `extra` into the current fields.
1437
- *
1438
- * @template E Extra field shape type
1439
- * @param extra Extra fields or form schema to merge
1440
- * @returns New form schema with merged fields
1441
- */
1442
- extend: {
1443
- <E extends Form.Shape>(extra: E): Form<ShapeUtil.Extend<Shape, E>>;
1444
- <E extends Form.Shape>(extra: Form<E>): Form<ShapeUtil.Extend<Shape, E>>;
1445
- (extra: Form<any>): Form<ShapeUtil.Extend<Shape, Form.Shape>>;
1446
- } = (extra: Form.Shape | Form<any>) =>
1447
- Form.from(
1448
- ShapeUtil.extend(this.shape, extra instanceof Form ? extra.shape : extra),
1449
- );
1450
-
1451
- /**
1452
- * Keep only selected field names.
1453
- *
1454
- * @template N Selected field names
1455
- * @param names Non-empty list of field names to keep
1456
- * @returns New form schema with only selected fields
1457
- */
1458
- pick = <N extends ShapeUtil.Name<Shape>>(names: readonly [N, ...N[]]) =>
1459
- Form.from(ShapeUtil.pick(this.shape, names));
1460
-
1461
- /**
1462
- * Remove selected field names.
1463
- *
1464
- * @template N Field names to remove
1465
- * @param names Non-empty list of field names to remove
1466
- * @returns New form schema without selected fields
1467
- */
1468
- omit = <N extends ShapeUtil.Name<Shape>>(names: readonly [N, ...N[]]) =>
1469
- Form.from(ShapeUtil.omit(this.shape, names));
1470
-
1471
- /**
1472
- * @param name Unexpected form field name
1473
- * @param path Parent path
1474
- * @returns Schema issue for unexpected form field names
1475
- */
1476
- #unexpected(name: string, path: Schema.Issue.Path = []) {
1477
- return new Schema.Issue(
1478
- "known form data name",
1479
- [...path, name],
1480
- "Unexpected form data name",
1481
- );
1482
- }
1483
-
1484
- /**
1485
- * Sanitizes render-state values by removing unsupported or oversized entries.
1486
- *
1487
- * @param values Candidate values to keep
1488
- * @param persist When `true`, only allow fields marked with `.persist()`
1489
- * @returns Sanitized values
1490
- */
1491
- #sanitize(values?: Record<string, unknown>, persist = true) {
1492
- const sanitized: Form.Value.Map<Shape> = {};
1493
-
1494
- if (values) {
1495
- for (const [name, value] of Object.entries(values)) {
1496
- const field = this.shape[name];
1497
-
1498
- if (
1499
- field &&
1500
- field.type !== "file" &&
1501
- (!persist || FieldSchema.persisted(field)) &&
1502
- value != null
1503
- ) {
1504
- const result = Form.#valueSchema.parse(value);
1505
-
1506
- if (
1507
- !result.issues &&
1508
- JSON.stringify(result.data).length <= Form.#maxValueChars
1509
- ) {
1510
- sanitized[name as ShapeUtil.Name<Shape>] = result.data;
1511
- }
1512
- }
1513
- }
1514
-
1515
- if (Object.keys(sanitized).length) return sanitized;
1516
- }
1517
- }
1518
-
1519
- /**
1520
- * Decode form state from input.
1521
- *
1522
- * @param stateInput Current page URL
1523
- */
1524
- #decode(stateInput?: URL): Form.State<Shape> | undefined {
1525
- if (stateInput) {
1526
- const values = this.#sanitize(
1527
- this.names.reduce<Record<string, unknown>>((data, name) => {
1528
- if (stateInput.searchParams.has(name)) {
1529
- const value = FieldSchema.read(
1530
- this.shape[name]!,
1531
- stateInput.searchParams,
1532
- name,
1533
- );
1534
-
1535
- if (value != null) data[name] = value;
1536
- }
1537
-
1538
- return data;
1539
- }, {}),
1540
- false,
1541
- );
1542
- const encoded = stateInput.searchParams.get(Form.params[1]);
1543
-
1544
- if (encoded && encoded.length <= Form.#maxStateBytes * 2) {
1545
- try {
1546
- const result = Schema.string()
1547
- .json(
1548
- Schema.object({
1549
- id: Schema.literal(this.#id),
1550
- issues: Schema.array(
1551
- Schema.object({
1552
- expected: Schema.string(),
1553
- path: Schema.array(
1554
- Schema.union([Schema.string(), Schema.number()]),
1555
- ),
1556
- message: Schema.string(),
1557
- }).transform(
1558
- (issue) =>
1559
- new Schema.Issue(
1560
- issue.expected,
1561
- issue.path,
1562
- issue.message,
1563
- ),
1564
- ),
1565
- ).optional(),
1566
- values: Schema.object(
1567
- this.names.reduce<Schema.Object.Shape>((shape, name) => {
1568
- shape[name] = Form.#valueSchema.optional();
1569
-
1570
- return shape;
1571
- }, {}),
1572
- ).optional(),
1573
- }),
1574
- )
1575
- .parse(Codec.decode(Codec.Base64Url.decode(encoded)));
1576
-
1577
- if (result.data?.id === this.#id) {
1578
- const current = this.#sanitize(result.data.values);
1579
-
1580
- return {
1581
- ...result.data,
1582
- values: (values || current) && { ...values, ...current },
1583
- } as unknown as Form.State<Shape>;
1584
- }
1585
- } catch {}
1586
- }
1587
-
1588
- return values && { id: this.#id, values };
1589
- }
1590
- }
1591
-
1592
- /**
1593
- * Parse and validate form data.
1594
- *
1595
- * @param source FormData, URLSearchParams, or Multipart to parse
1596
- * @param path Internal path reference
1597
- * @returns Parsed result
1598
- */
1599
- parse = async (
1600
- source: FormData | URLSearchParams | Multipart,
1601
- path: Schema.Issue.Path = [],
1602
- ): Promise<Form.Parse.Result<Shape>> => {
1603
- const data: Record<string, unknown> = {};
1604
- const issues: Schema.Issue[] = [];
1605
- const values: Record<string, unknown> = {};
1606
- let form: FormData | URLSearchParams;
1607
- let stream: AsyncGenerator<Multipart.Part> | undefined;
1608
-
1609
- if (source instanceof Multipart) {
1610
- form = new FormData();
1611
- const iter = source[Symbol.asyncIterator]();
1612
-
1613
- let current: IteratorResult<Multipart.Part>;
1614
-
1615
- while ((current = await iter.next()) && !current.done) {
1616
- const part = current.value;
1617
-
1618
- if (part.name) {
1619
- const field = this.shape[part.name];
1620
-
1621
- if (!field) {
1622
- issues.push(this.#unexpected(part.name, path));
1623
- } else if (field.streaming) {
1624
- // expose current and rest of the parts to the user
1625
- stream = (async function* () {
1626
- try {
1627
- // have to yield the current part first
1628
- // this is why the multipart can't be passed directly
1629
- yield part;
1630
-
1631
- let next: IteratorResult<Multipart.Part>;
1632
-
1633
- while ((next = await iter.next()) && !next.done) {
1634
- yield next.value;
1635
- }
1636
- } finally {
1637
- try {
1638
- await iter.return?.();
1639
- } catch {}
1640
- }
1641
- })();
1642
-
1643
- break;
1644
- } else {
1645
- form.append(part.name, await part.value());
1646
- }
1647
- }
1648
- }
1649
- } else if (source instanceof FormData) {
1650
- form = source;
1651
-
1652
- for (const name of new Set(source.keys())) {
1653
- if (!this.shape[name]) issues.push(this.#unexpected(name, path));
1654
- }
1655
- } else {
1656
- // allow passthrough for URLSearchParams
1657
- form = source;
1658
- }
1659
-
1660
- for (const [name, field] of Object.entries(this.shape)) {
1661
- if (!field.streaming) {
1662
- const value = FieldSchema.read(field, form, name);
1663
- const result = field.parse(value, [...path, name]);
1664
-
1665
- if (result.issues) {
1666
- issues.push(...result.issues);
1667
- } else if (result.data !== undefined) {
1668
- data[name] = result.data;
1669
- }
1670
-
1671
- if (FieldSchema.persisted(field) && value != null) {
1672
- values[name] = value;
1673
- }
1674
- }
1675
- }
1676
-
1677
- if (issues.length) {
1678
- const result = new Schema.AggregateIssue(issues, this.#sanitize(values));
1679
- let search: Form.Parse.Result.Search;
1680
-
1681
- if (result.values) {
1682
- // trim persisted values until the encoded state fits
1683
- for (let i = this.names.length; i >= 0; i--) {
1684
- // skip on the first time - try to encode everything first
1685
- if (i !== this.names.length) delete result.values[this.names[i]!];
1686
-
1687
- const state = Codec.encode(
1688
- JSON.stringify({
1689
- issues: result.issues,
1690
- id: this.#id,
1691
- ...(Object.keys(result.values).length
1692
- ? { values: result.values }
1693
- : {}),
1694
- } satisfies Form.State),
1695
- );
1696
-
1697
- if (state.byteLength <= Form.#maxStateBytes) {
1698
- search = [[Form.params[1], Codec.Base64Url.encode(state)]];
1699
- break;
1700
- }
1701
- }
1702
- } else {
1703
- // fall back to issues-only state when nothing persisted.
1704
- const state = Codec.encode(
1705
- JSON.stringify({
1706
- issues: result.issues,
1707
- id: this.#id,
1708
- } satisfies Form.State),
1709
- );
1710
-
1711
- if (state.byteLength <= Form.#maxStateBytes) {
1712
- search = [[Form.params[1], Codec.Base64Url.encode(state)]];
1713
- }
1714
- }
1715
-
1716
- if (stream) {
1717
- // invalid result does not expose streamed parts, drain
1718
- try {
1719
- for await (const _ of stream);
1720
- } catch {}
1721
- }
1722
-
1723
- return Object.assign(result, { search });
1724
- }
1725
-
1726
- return { data: data as Form.Parse.Data<Shape>, stream };
1727
- };
1728
-
1729
- /**
1730
- * Render a single form field.
1731
- *
1732
- * @param props Component props
1733
- * @example
1734
- *
1735
- * ```tsx
1736
- * <User.Field name="username" />
1737
- * ```
1738
- */
1739
- Field = (props: Field.Component.Props<Shape>) =>
1740
- this.shape[props.name]!.render({
1741
- ...props,
1742
- state: this.#decode(props.state),
1743
- });
1744
-
1745
- /**
1746
- * Render all form fields.
1747
- *
1748
- * @param props Component props
1749
- * @example
1750
- *
1751
- * ```tsx
1752
- * <User.Fields />
1753
- * ```
1754
- */
1755
- Fields = (
1756
- props: // partial because name is not required
1757
- Partial<Field.Component.Props<Shape>> = {},
1758
- ) => {
1759
- const state = this.#decode(props.state); // pulled out to not call each map iteration
1760
-
1761
- return this.names.map((name) =>
1762
- this.shape[name]!.render({ ...props, name, state }),
1763
- );
1764
- };
1765
-
1766
- /**
1767
- * Access bound sub-components for a field.
1768
- *
1769
- * @template N Type of the form field name
1770
- * @param props Field component props
1771
- * @example
1772
- *
1773
- * ```tsx
1774
- * const Radio = User.component({ name: "radio" });
1775
- *
1776
- * <Radio.Label />
1777
- * <Radio.Control />
1778
- * ```
1779
- */
1780
- component = <N extends ShapeUtil.Name<Shape>>(
1781
- props: { name: N } & Field.Component.Props<Shape>,
1782
- ): Field.Component<Shape[N]> =>
1783
- this.shape[props.name]!.component({
1784
- ...props,
1785
- state: this.#decode(props.state),
1786
- });
1787
-
1788
- /**
1789
- * Create a Form from a shape or use another Form.
1790
- *
1791
- * @template S Form field shape type
1792
- * @param shape Form fields
1793
- */
1794
- static from<S extends Form.Shape>(shape: S | Form<S>): Form<S> {
1795
- return shape instanceof Form ? shape : new Form(shape);
1796
- }
1797
- }
1798
-
1799
- /**
1800
- * Represents a form field with parsing logic and rendering metadata.
1801
- *
1802
- * @template Output Output type of the field
1803
- * @template Tag Tag name
1804
- * @template Type Input type
1805
- * @template Values Persisted field value type
1806
- * @template Stream If the field should be streamed as a part
1807
- */
1808
- class FieldSchema<
1809
- Output = unknown,
1810
- Tag extends Field.Tag = "input",
1811
- Type extends Field.Type = Field.Type,
1812
- Values extends Field.Values | undefined = undefined,
1813
- Stream extends boolean | undefined = undefined,
1814
- > extends Schema<Output> {
1815
- /** Read the value from form data */
1816
- readonly #read: Field.Read;
1817
-
1818
- /** Field type */
1819
- readonly type: Type;
1820
-
1821
- // tag and values are public so emitted .d.ts preserves
1822
- // field discriminants for correct types
1823
- /** Field tag */
1824
- readonly tag: Tag;
1825
-
1826
- /** Field values */
1827
- readonly values: Values;
1828
-
1829
- /** Maximum expected multipart part count for this field name. */
1830
- readonly parts: number;
1831
-
1832
- /** If the field should be streamed as a part */
1833
- readonly streaming: Stream | undefined;
1834
-
1835
- /** If the field should persist invalid-state values. */
1836
- readonly #persist: boolean;
1837
-
1838
- /** Field options */
1839
- readonly #options: Field.Options<Values, Tag>;
1840
-
1841
- /**
1842
- * Create a new field.
1843
- *
1844
- * @param options Field options
1845
- * @param parse How to validate the input
1846
- * @param read How to read the form data
1847
- * @param parts Maximum expected multipart parts for this field
1848
- * @param stream If this field should be streamed as a multipart part
1849
- * @param persist If this field should persist invalid state values
1850
- */
1851
- constructor(
1852
- options: Field.Options<Values, Tag>,
1853
- parse: Schema<Output> | Schema.Parse.Constructor<Output>,
1854
- // default to a single value, treating blank as missing
1855
- read: Field.Read = (data, name) => data.get(name) || undefined,
1856
- parts = 1,
1857
- stream?: Stream,
1858
- persist = false,
1859
- ) {
1860
- super(parse instanceof Schema ? parse.parse : parse);
1861
-
1862
- this.#options = options;
1863
- this.tag = (options.tag ?? "input") as Tag;
1864
- this.values = options.values as Values;
1865
- this.#read = read;
1866
- this.type = options.props?.type as Type;
1867
- this.parts = parts;
1868
- this.streaming = stream;
1869
- this.#persist = persist;
1870
- }
1871
-
1872
- /**
1873
- * @param field Field instance
1874
- * @param data Form data source
1875
- * @param name HTML name attribute
1876
- * @returns Raw field input
1877
- */
1878
- static read(
1879
- field: Field.Any,
1880
- data: FormData | URLSearchParams,
1881
- name: string,
1882
- ) {
1883
- return field.#read(data, name);
1884
- }
1885
-
1886
- /**
1887
- * Stream this field as a multipart request `Part`.
1888
- *
1889
- * @returns Part field
1890
- */
1891
- stream(): Field.Instance<Output, Tag, Type, Values, true> {
1892
- return new FieldSchema<Output, Tag, Type, Values, true>(
1893
- this.#options,
1894
- this.parse,
1895
- this.#read,
1896
- this.parts,
1897
- true,
1898
- this.#persist,
1899
- );
1900
- }
1901
-
1902
- /**
1903
- * Persist this field in the encoded invalid form state.
1904
- *
1905
- * Use this for non-sensitive values that should refill after an invalid
1906
- * redirect.
1907
- *
1908
- * @returns Field that persists submitted values across invalid redirects
1909
- */
1910
- persist<
1911
- U extends (Tag extends "input" ? Exclude<Type, "password" | "file"> : Type),
1912
- >(
1913
- this: Field.Instance<Output, Tag, U, Values, Stream>,
1914
- ): Field.Instance<Output, Tag, U, Values, Stream>;
1915
- persist() {
1916
- return new FieldSchema<Output, Tag, Type, Values, Stream>(
1917
- this.#options,
1918
- this.parse,
1919
- this.#read,
1920
- this.parts,
1921
- this.streaming,
1922
- true,
1923
- );
1924
- }
1925
-
1926
- /**
1927
- * Derive a new Field from the current instance type.
1928
- *
1929
- * @template O Output type of the new Field
1930
- * @param parse Parse function that validates and transforms input
1931
- * @returns New `Field` instance
1932
- */
1933
- override derive<O>(
1934
- parse: Schema.Parse.Constructor<O>,
1935
- ): Field.Instance<O, Tag, Type, Values, Stream> {
1936
- return new FieldSchema<O, Tag, Type, Values, Stream>(
1937
- this.#options,
1938
- parse,
1939
- this.#read,
1940
- this.parts,
1941
- this.streaming,
1942
- this.#persist,
1943
- );
1944
- }
1945
-
1946
- /**
1947
- * @template S Form shape type
1948
- * @param props Field control props
1949
- * @returns Field component with sub-components
1950
- */
1951
- component<S extends Form.Shape>(
1952
- props: Field.Component.Props<S, false>,
1953
- ): Field.Component<this>;
1954
- component<S extends Form.Shape>({
1955
- state,
1956
- ...props
1957
- }: Field.Component.Props<S, false>): unknown {
1958
- const value = state?.values?.[props.name];
1959
- const issue = state?.issues?.find((i) => i.path[0] === props.name);
1960
- const issueId = issue && `${props.name}-issue`;
1961
- const hidden = this.type === "hidden";
1962
- const { label = props.name, ...control } = {
1963
- id: props.name,
1964
- autofocus: issue && state?.issues?.[0] === issue,
1965
- "aria-invalid": issue && "true",
1966
- "aria-describedby": issueId,
1967
- ...this.#options.props,
1968
- ...props,
1969
- };
1970
-
1971
- const Issue = (data: Field.Component.Issue = {}) =>
1972
- issue && // render nothing if no issue
1973
- !hidden &&
1974
- jsx("p", {
1975
- id: issueId,
1976
- children: issue.message,
1977
- "data-issue": issue && state!.issues!.indexOf(issue), // issue index starting from 0
1978
- ...data,
1979
- });
1980
-
1981
- if (this.values && this.tag !== "select") {
1982
- // radio/checkboxes
1983
- // make multiple ids for the group so all don't have the same id
1984
- const groupId = (value: string) =>
1985
- `${control.name}-${value}`.toLowerCase();
1986
-
1987
- const Control = (
1988
- data: Field.Component.Control.Group<"input", Field.Values>,
1989
- ) =>
1990
- jsx(this.tag, {
1991
- ...control,
1992
- id: groupId(data.value),
1993
- // autofocus only the first input in the group
1994
- autofocus: control.autofocus && data.value === this.values?.[0],
1995
- checked: Array.isArray(value)
1996
- ? value.includes(data.value) // checkboxes
1997
- : value === data.value, // radio
1998
- ...data,
1999
- });
2000
-
2001
- const Label = ({
2002
- value,
2003
- ...rest
2004
- }: Field.Component.Label.Group<Field.Values>) =>
2005
- jsx("label", { for: groupId(value), children: value, ...rest });
2006
-
2007
- return {
2008
- Issue,
2009
- Label,
2010
- Control,
2011
- Root: (data: Field.Component.Root = {}) => jsx("fieldset", data),
2012
- Option: ({
2013
- value,
2014
- ...rest
2015
- }: Field.Component.Option.Input<Field.Values>) =>
2016
- jsx("div", {
2017
- children: [Control({ value }), Label({ value })],
2018
- ...rest,
2019
- }),
2020
- Legend: (data: Field.Component.Legend = {}) =>
2021
- jsx("legend", { children: label, ...data }),
2022
- ...this,
2023
- };
2024
- }
2025
-
2026
- return {
2027
- Issue,
2028
- Root: (data: Field.Component.Root = {}) =>
2029
- hidden ? Fragment(data) : jsx("div", data),
2030
- Label: (data: Field.Component.Label = {}) =>
2031
- !hidden && jsx("label", { for: control.id, children: label, ...data }),
2032
- Control: (data?: Field.Component.Control<Tag>) => {
2033
- const attrs = { ...control, ...data };
2034
-
2035
- if (value !== undefined) {
2036
- if (this.tag === "textarea") {
2037
- attrs.children = value;
2038
- } else if (this.tag === "input") {
2039
- if (this.type === "checkbox") {
2040
- attrs.checked = value;
2041
- } else {
2042
- attrs.value = value;
2043
- }
2044
- }
2045
- }
2046
-
2047
- return jsx(this.tag, attrs);
2048
- },
2049
- Option:
2050
- // select
2051
- this.values &&
2052
- ((data: Field.Component.Option<Field.Values>) =>
2053
- jsx("option", {
2054
- children: data.value,
2055
- selected: Array.isArray(value)
2056
- ? value.includes(data.value) // multiselect
2057
- : value === data.value,
2058
- ...data,
2059
- })),
2060
- ...this,
2061
- };
2062
- }
2063
-
2064
- /**
2065
- * @template S Form shape type
2066
- * @param props Field control props
2067
- * @returns Input group component
2068
- */
2069
- #Group<S extends Form.Shape>(
2070
- this: FieldSchema<Output, "input", "radio" | "checkbox", Field.Values>,
2071
- props: Field.Component.Props<S, false>,
2072
- ) {
2073
- const c = this.component(props);
2074
-
2075
- return c.Root({
2076
- children: [
2077
- // @ts-expect-error - `#Group` runs for grouped inputs, includes `Legend` with label
2078
- c.Legend(),
2079
- this.values.map((value: string) => {
2080
- return jsx("div", {
2081
- children: [c.Control({ value }), c.Label({ value })],
2082
- });
2083
- }),
2084
- c.Issue(),
2085
- ],
2086
- });
2087
- }
2088
-
2089
- /**
2090
- * @template S Form shape type
2091
- * @param props Field control props
2092
- * @returns Select component
2093
- */
2094
- #Select<S extends Form.Shape>(
2095
- this: FieldSchema<Output, "select", Type, Field.Values>,
2096
- props: Field.Component.Props<S, false>,
2097
- ) {
2098
- const c = this.component(props);
2099
-
2100
- return c.Root({
2101
- children: [
2102
- c.Label(),
2103
- c.Control({
2104
- children: this.values.map((value: string) => c.Option({ value })),
2105
- }),
2106
- c.Issue(),
2107
- ],
2108
- });
2109
- }
2110
-
2111
- /**
2112
- * @template S Form shape type
2113
- * @param props Field control props
2114
- * @returns Default input component
2115
- */
2116
- #Input<S extends Form.Shape>(props: Field.Component.Props<S, false>) {
2117
- const c = this.component(props);
2118
-
2119
- return c.Root({ children: [c.Label(), c.Control(), c.Issue()] });
2120
- }
2121
-
2122
- /**
2123
- * @template S Form shape type
2124
- * @param props Field control props including `name` of the field to render
2125
- * @returns Component that renders the HTML field with default structure
2126
- */
2127
- render<S extends Form.Shape>(props: Field.Component.Props<S, false>) {
2128
- if (this.values) {
2129
- if (this.tag === "select") return this.#Select(props);
2130
-
2131
- return this.#Group(props);
2132
- }
2133
-
2134
- return this.#Input(props);
2135
- }
2136
-
2137
- /**
2138
- * @param field Field definition
2139
- * @returns `true` when the field persists invalid-state values
2140
- */
2141
- static persisted(field: Field.Any) {
2142
- return field.#persist;
2143
- }
2144
- }
2145
-
2146
- export namespace Field {
2147
- /**
2148
- * Base options to create a Field.
2149
- *
2150
- * @template V Type of the values for group inputs
2151
- * @template T Tag name
2152
- */
2153
- export interface Options<
2154
- V extends Values | undefined = undefined,
2155
- T extends Tag = Tag,
2156
- > {
2157
- /**
2158
- * Tag name.
2159
- *
2160
- * @default "input"
2161
- */
2162
- readonly tag?: T;
2163
-
2164
- /** Values are used for group inputs */
2165
- readonly values?: V;
2166
-
2167
- /** Field props */
2168
- readonly props?: Props | undefined;
2169
- }
2170
-
2171
- /**
2172
- * Raw field value before schema parsing.
2173
- *
2174
- * Single-value fields read one entry, multi-value fields read all entries,
2175
- * and checkboxes read presence.
2176
- */
2177
- export type Input =
2178
- FormDataEntryValue | FormDataEntryValue[] | boolean | undefined;
2179
-
2180
- /**
2181
- * @param data FormData or URLSearchParams
2182
- * @param name HTML name attribute
2183
- * @returns Resolved value read from the form data
2184
- */
2185
- export type Read = (data: FormData | URLSearchParams, name: string) => Input;
2186
-
2187
- /** Form field tag name */
2188
- export type Tag = "input" | "textarea" | "select";
2189
-
2190
- /** `<input type=...>` */
2191
- export type Type = JSX.IntrinsicElements["input"]["type"];
2192
-
2193
- /** Value type for select and radio options */
2194
- export type Values = readonly [string, ...string[]];
2195
-
2196
- /** Field instance type */
2197
- export type Instance<
2198
- Output = unknown,
2199
- Tag extends Field.Tag = "input",
2200
- Type extends Field.Type = Field.Type,
2201
- Values extends Field.Values | undefined = undefined,
2202
- Stream extends boolean | undefined = undefined,
2203
- > = FieldSchema<Output, Tag, Type, Values, Stream>;
2204
-
2205
- /** Any field - `<input type=...>` / `<select>` / `<textarea>` */
2206
- export type Any = Instance<
2207
- any,
2208
- Tag,
2209
- Type,
2210
- Values | undefined,
2211
- boolean | undefined
2212
- >;
2213
-
2214
- /**
2215
- * Obtain the tag name of a field.
2216
- *
2217
- * @template F Field
2218
- */
2219
- export type TagOf<F extends Any> =
2220
- F extends Instance<any, infer T, Field.Type, Field.Values | undefined>
2221
- ? T
2222
- : Tag;
2223
-
2224
- export namespace Component {
2225
- /**
2226
- * Component props available to users to pass into the
2227
- * constructed `<Field />` component.
2228
- *
2229
- * @template S Form shape type
2230
- * @template I `true` the state is a `URL`, `false` is just `State`
2231
- */
2232
- export type Props<S extends Form.Shape, I extends boolean = true> = {
2233
- /** Field name attribute */
2234
- readonly name: ShapeUtil.Name<S>;
2235
-
2236
- /** Form state */
2237
- readonly state?: (I extends true ? URL : Form.State<S>) | undefined;
2238
- } & Field.Props;
2239
-
2240
- /** Root element for the Field component */
2241
- export type Root = JSX.IntrinsicElements["div"];
2242
-
2243
- export namespace Root {
2244
- /** Root for input groups */
2245
- export type Group = JSX.IntrinsicElements["fieldset"];
2246
- }
2247
-
2248
- /** `<Field.Legend />` component props */
2249
- export type Legend = JSX.IntrinsicElements["legend"];
2250
-
2251
- /** `<Field.Issue />` component props */
2252
- export type Issue = JSX.IntrinsicElements["p"];
2253
-
2254
- /**
2255
- * `<Field.Control />` component props
2256
- *
2257
- * @template T Tag name
2258
- */
2259
- export type Control<T extends Tag> = T extends "textarea"
2260
- ? JSX.IntrinsicElements["textarea"]
2261
- : T extends "select"
2262
- ? JSX.IntrinsicElements["select"]
2263
- : JSX.IntrinsicElements["input"];
2264
-
2265
- export namespace Control {
2266
- /**
2267
- * `<Field.Control />` component props for group input element.
2268
- *
2269
- * @template T Tag name
2270
- * @template V Option values
2271
- */
2272
- export type Group<T extends Tag, V extends Values> = Control<T> & {
2273
- readonly value: V[number];
2274
- };
2275
- }
2276
-
2277
- /** `<Field.Label />` component props */
2278
- export type Label = JSX.IntrinsicElements["label"];
2279
-
2280
- export namespace Label {
2281
- /**
2282
- * `<Field.Label />` component props for group input element.
2283
- *
2284
- * @template V Option values
2285
- */
2286
- export type Group<V extends Values> = Label & {
2287
- readonly value: V[number];
2288
- };
2289
- }
2290
-
2291
- /**
2292
- * `<Field.Option />` select component props
2293
- *
2294
- * @template V Values
2295
- */
2296
- export type Option<V extends Values> = JSX.IntrinsicElements["option"] & {
2297
- /** Option value */
2298
- readonly value: V[number];
2299
- };
2300
-
2301
- export namespace Option {
2302
- /**
2303
- * `<Field.Option />` input group component props
2304
- *
2305
- * Wrapper for both the `<Label />` and `<Input />` components.
2306
- *
2307
- * @template V Values
2308
- */
2309
- export type Input<V extends Values> = JSX.IntrinsicElements["div"] & {
2310
- /** Option value */
2311
- readonly value: V[number];
2312
- };
2313
- }
2314
- }
2315
-
2316
- /**
2317
- * Base Field component object that contains sub-components,
2318
- * use for fine grained rendering control.
2319
- *
2320
- * @template F Field
2321
- */
2322
- export type Component<F extends Any> = Readonly<
2323
- {
2324
- /**
2325
- * @param props Issue props
2326
- * @returns Issue container paragraph
2327
- */
2328
- Issue: (props?: Component.Issue) => JSX.Element;
2329
- } & (F extends Instance<any, "select", Field.Type, infer V>
2330
- ? V extends Values
2331
- ? // select
2332
- {
2333
- /** Select option values */
2334
- values: V;
2335
-
2336
- /**
2337
- * @param props Root props
2338
- * @returns Root container div
2339
- */
2340
- Root: (props?: Component.Root) => JSX.Element;
2341
-
2342
- /**
2343
- * @param props Label props
2344
- * @returns Label element
2345
- */
2346
- Label: (props?: Component.Label) => JSX.Element;
2347
-
2348
- /**
2349
- * @param props Control props
2350
- * @returns Control select element
2351
- */
2352
- Control: (props?: Component.Control<"select">) => JSX.Element;
2353
-
2354
- /**
2355
- * @param props Option props
2356
- * @returns Select option element
2357
- */
2358
- Option: (props: Component.Option<V>) => JSX.Element;
2359
- }
2360
- : never
2361
- : F extends Instance<any, "input", Field.Type, infer V>
2362
- ? V extends Values
2363
- ? // radio/checkboxes
2364
- {
2365
- /** Input group values */
2366
- values: V;
2367
-
2368
- /**
2369
- * @param props Root props
2370
- * @returns Root container fieldset
2371
- */
2372
- Root: (props?: Component.Root.Group) => JSX.Element;
2373
-
2374
- /**
2375
- * @param props Legend element props
2376
- * @returns Legend element
2377
- */
2378
- Legend: (props?: Component.Legend) => JSX.Element;
2379
-
2380
- /**
2381
- * @param props Label props including `value`
2382
- * @returns Label element
2383
- */
2384
- Label: (props: Component.Label.Group<V>) => JSX.Element;
2385
-
2386
- /**
2387
- * @param props Control props
2388
- * @returns Control input element
2389
- */
2390
- Control: (
2391
- props?: Component.Control.Group<"input", V>,
2392
- ) => JSX.Element;
2393
-
2394
- /**
2395
- * @param props Option props
2396
- * @returns Both label and input elements together
2397
- */
2398
- Option: (props: Component.Option.Input<V>) => JSX.Element;
2399
- }
2400
- : // regular input
2401
- {
2402
- /**
2403
- * @param props Root props
2404
- * @returns Root container div
2405
- */
2406
- Root: (props?: Component.Root) => JSX.Element;
2407
-
2408
- /**
2409
- * @param props Label props
2410
- * @returns Label element
2411
- */
2412
- Label: (props?: Component.Label) => JSX.Element;
2413
-
2414
- /**
2415
- * @param props Control props
2416
- * @returns Control input element
2417
- */
2418
- Control: (props?: Component.Control<"input">) => JSX.Element;
2419
- }
2420
- : // textarea
2421
- {
2422
- /**
2423
- * @param props Root props
2424
- * @returns Root container div
2425
- */
2426
- Root: (props?: Component.Root) => JSX.Element;
2427
-
2428
- /**
2429
- * @param props Label props
2430
- * @returns Label element
2431
- */
2432
- Label: (props?: Component.Label) => JSX.Element;
2433
-
2434
- /**
2435
- * @param props Control props
2436
- * @returns Control textarea element
2437
- */
2438
- Control: (props?: Component.Control<"textarea">) => JSX.Element;
2439
- })
2440
- >;
2441
-
2442
- /** Any field props */
2443
- export type Props = Props.Input | Props.Select | Props.Textarea;
2444
-
2445
- export namespace Props {
2446
- /** Extra props in addition to HTML attributes */
2447
- interface Meta {
2448
- /** Field label */
2449
- readonly label?: string;
2450
- }
2451
-
2452
- /** Props for `<input>` fields */
2453
- export type Input = Meta & JSX.IntrinsicElements["input"];
2454
-
2455
- /** Props for `<select>` fields */
2456
- export type Select = Meta & JSX.IntrinsicElements["select"];
2457
-
2458
- /** Props for `<textarea>` fields */
2459
- export type Textarea = Meta & JSX.IntrinsicElements["textarea"];
2460
- }
2461
- }
2462
-
2463
- /** Field factory functions */
2464
- export class Field {
2465
- // this is used instead of the defaults for example "Expected string"
2466
- // since "string" doesn't make sense to end users
2467
- /** Default message for required field values. */
2468
- static readonly #required = "Required field";
2469
-
1725
+ ): Field.Instance<string, T, U, V>;
2470
1726
  /**
2471
- * @param value Raw form entry
2472
- * @returns `true` when the file input contains a real file value
1727
+ * Validate an input is less than or equal to the maximum.
1728
+ *
1729
+ * @template T Field tag name
1730
+ * @template U Field input type attribute
1731
+ * @template V Field option values
1732
+ * @param value Maximum value
1733
+ * @param message Issue message when invalid
1734
+ * @returns Refined field
2473
1735
  */
2474
- static #nonEmptyFile(value: FormDataEntryValue | null) {
2475
- return value instanceof File && (value.name !== "" || value.size > 0);
2476
- }
2477
-
1736
+ max<
1737
+ T extends Field.Tag,
1738
+ U extends Field.Type,
1739
+ V extends Field.Options | undefined,
1740
+ >(
1741
+ this: Field.Instance<number, T, U, V>,
1742
+ value: number,
1743
+ message?: string,
1744
+ ): Field.Instance<number, T, U, V>;
2478
1745
  /**
2479
- * @param data Form data
2480
- * @param name HTML name attribute
2481
- * @returns Field values or `undefined` when missing
1746
+ * Validate an input is less than or equal to the maximum.
1747
+ *
1748
+ * @template T Field tag name
1749
+ * @template U Field input type attribute
1750
+ * @template V Field option values
1751
+ * @param value Maximum value
1752
+ * @param message Issue message when invalid
1753
+ * @returns Refined field
2482
1754
  */
2483
- static #readMany(data: FormData | URLSearchParams, name: string) {
2484
- const value = data.getAll(name);
2485
-
2486
- return value.length ? value : undefined;
2487
- }
2488
-
1755
+ max<
1756
+ T extends Field.Tag,
1757
+ U extends Field.Type,
1758
+ V extends Field.Options | undefined,
1759
+ >(
1760
+ this: Field.Instance<bigint, T, U, V>,
1761
+ value: bigint,
1762
+ message?: string,
1763
+ ): Field.Instance<bigint, T, U, V>;
2489
1764
  /**
2490
- * @param props Input props
2491
- * @returns Generic input field
1765
+ * Validate an input is less than or equal to the maximum.
1766
+ *
1767
+ * For strings, this validates maximum length in Unicode characters,
1768
+ * as JSON Schema and Postgres count them.
1769
+ *
1770
+ * @param value Maximum value or length
1771
+ * @param message Issue message when invalid
1772
+ * @returns Refined schema
2492
1773
  */
2493
- static #input<T extends Field.Type>(
2494
- props: Field.Props.Input & { type: T },
2495
- ): Field.Instance<string, "input", T> {
2496
- return new FieldSchema({ props }, Schema.string(Field.#required));
2497
- }
2498
-
1774
+ max(this: Schema<string>, value: number, message?: string): Schema<string>;
2499
1775
  /**
2500
- * @param props Input props
2501
- * @returns Text input field
1776
+ * Validate an input is less than or equal to the maximum.
1777
+ *
1778
+ * @param value Maximum value
1779
+ * @param message Issue message when invalid
1780
+ * @returns Refined schema
2502
1781
  */
2503
- static text(
2504
- props?: Field.Props.Input,
2505
- ): Field.Instance<string, "input", "text"> {
2506
- return Field.#input({ ...props, type: "text" });
2507
- }
2508
-
1782
+ max(this: Schema<number>, value: number, message?: string): Schema<number>;
2509
1783
  /**
2510
- * @param props Input props
2511
- * @returns Password input field
1784
+ * Validate an input is less than or equal to the maximum.
1785
+ *
1786
+ * @param value Maximum value
1787
+ * @param message Issue message when invalid
1788
+ * @returns Refined schema
2512
1789
  */
2513
- static password(
2514
- props?: Field.Props.Input,
2515
- ): Field.Instance<string, "input", "password"> {
2516
- return Field.#input({ ...props, type: "password" });
1790
+ max(this: Schema<bigint>, value: bigint, message?: string): Schema<bigint>;
1791
+ max(
1792
+ this: Schema<string | number | bigint>,
1793
+ value: number | bigint,
1794
+ message = `Expected maximum ${value}`,
1795
+ ) {
1796
+ return this.#check({ name: "max", value, message });
2517
1797
  }
2518
1798
 
2519
1799
  /**
2520
- * @param props Input props
2521
- * @returns Search input field
1800
+ * @template T Field tag name
1801
+ * @template U Field input type attribute
1802
+ * @template V Field option values
1803
+ * @param check Validation function that returns `false` to fail
1804
+ * @param message Issue message when invalid
1805
+ * @returns Refined field
2522
1806
  */
2523
- static search(
2524
- props?: Field.Props.Input,
2525
- ): Field.Instance<string, "input", "search"> {
2526
- return Field.#input({ ...props, type: "search" });
2527
- }
2528
-
1807
+ refine<
1808
+ T extends Field.Tag,
1809
+ U extends Field.Type,
1810
+ V extends Field.Options | undefined,
1811
+ >(
1812
+ this: Field.Instance<Output, T, U, V>,
1813
+ check: (value: Output) => boolean,
1814
+ message: string,
1815
+ ): Field.Instance<Output, T, U, V>;
2529
1816
  /**
2530
- * @param props Input props
2531
- * @returns Telephone input field
1817
+ * @param check Validation function that returns `false` to fail
1818
+ * @param message Issue message when invalid
1819
+ * @returns Refined schema
2532
1820
  */
2533
- static tel(
2534
- props?: Field.Props.Input,
2535
- ): Field.Instance<string, "input", "tel"> {
2536
- return Field.#input({ ...props, type: "tel" });
1821
+ refine(
1822
+ this: Schema<Output>,
1823
+ check: (value: Output) => boolean,
1824
+ message: string,
1825
+ ): Schema<Output>;
1826
+ refine(
1827
+ this: Schema<Output>,
1828
+ check: (value: Output) => boolean,
1829
+ message: string,
1830
+ ) {
1831
+ return this.#check({ name: "refine", fn: check, message });
2537
1832
  }
2538
1833
 
2539
1834
  /**
2540
- * @param props Input props
2541
- * @returns Color input field
1835
+ * Accepts any value and presents the data as `unknown`.
1836
+ *
1837
+ * @returns Unknown schema
2542
1838
  */
2543
- static color(
2544
- props?: Field.Props.Input,
2545
- ): Field.Instance<string, "input", "color"> {
2546
- return Field.#input({ ...props, type: "color" });
1839
+ static unknown() {
1840
+ return new Schema<unknown>({ type: "unknown" });
2547
1841
  }
2548
1842
 
2549
1843
  /**
2550
- * @param props Input props
2551
- * @returns Hidden input field
1844
+ * Validate an input is a string.
1845
+ *
1846
+ * @param message Issue message when invalid
1847
+ * @returns String schema
2552
1848
  */
2553
- static hidden(
2554
- props?: Field.Props.Input,
2555
- ): Field.Instance<string, "input", "hidden"> {
2556
- return Field.#input({ ...props, type: "hidden" });
1849
+ static string(message?: string) {
1850
+ return new Schema<string>({ type: "string", message });
2557
1851
  }
2558
1852
 
2559
1853
  /**
2560
- * @param props Input props
2561
- * @returns Date input field
1854
+ * Validate an input is a `true` or `false` boolean.
1855
+ *
1856
+ * @param message Issue message when invalid
1857
+ * @returns Boolean schema
2562
1858
  */
2563
- static date(
2564
- props?: Field.Props.Input,
2565
- ): Field.Instance<string, "input", "date"> {
2566
- return Field.#input({ ...props, type: "date" });
1859
+ static boolean(message?: string) {
1860
+ return new Schema<boolean>({ type: "boolean", message });
2567
1861
  }
2568
1862
 
2569
1863
  /**
2570
- * @param props Input props
2571
- * @returns Datetime input field
1864
+ * Validate an input is a number.
1865
+ *
1866
+ * Rejects non-finite values like `NaN` and `Infinity`.
1867
+ *
1868
+ * @param message Issue message when invalid
1869
+ * @returns Number schema
2572
1870
  */
2573
- static datetime(
2574
- props?: Field.Props.Input,
2575
- ): Field.Instance<string, "input", "datetime-local"> {
2576
- return Field.#input({ ...props, type: "datetime-local" });
1871
+ static number(message?: string) {
1872
+ return new Schema<number>({ type: "number", message });
2577
1873
  }
2578
1874
 
2579
1875
  /**
2580
- * @param props Input props
2581
- * @returns Month input field
1876
+ * Validate an input is a big integer.
1877
+ *
1878
+ * @param message Issue message when invalid
1879
+ * @returns Big integer schema
2582
1880
  */
2583
- static month(
2584
- props?: Field.Props.Input,
2585
- ): Field.Instance<string, "input", "month"> {
2586
- return Field.#input({ ...props, type: "month" });
1881
+ static bigint(message?: string) {
1882
+ return new Schema<bigint>({ type: "bigint", message });
2587
1883
  }
2588
1884
 
2589
1885
  /**
2590
- * @param props Input props
2591
- * @returns Week input field
1886
+ * Validate an input is a valid `Date`.
1887
+ *
1888
+ * Rejects invalid dates like `new Date("")`.
1889
+ *
1890
+ * @param message Issue message when invalid
1891
+ * @returns Date schema
2592
1892
  */
2593
- static week(
2594
- props?: Field.Props.Input,
2595
- ): Field.Instance<string, "input", "week"> {
2596
- return Field.#input({ ...props, type: "week" });
1893
+ static date(message?: string) {
1894
+ return new Schema<Date>({ type: "date", message });
2597
1895
  }
2598
1896
 
2599
1897
  /**
2600
- * @param props Input props
2601
- * @returns Time input field
1898
+ * @template L Literal type
1899
+ * @param literal Exact value to match
1900
+ * @param message Issue message when invalid
1901
+ * @returns Literal schema
2602
1902
  */
2603
- static time(
2604
- props?: Field.Props.Input,
2605
- ): Field.Instance<string, "input", "time"> {
2606
- return Field.#input({ ...props, type: "time" });
1903
+ static literal<const L>(literal: L, message?: string) {
1904
+ return new Schema<L>({ type: "literal", value: literal, message });
2607
1905
  }
2608
1906
 
2609
1907
  /**
2610
- * Validates email string.
1908
+ * Validates that the input is strictly equal (`===`) to one of the allowed
1909
+ * values.
2611
1910
  *
2612
- * @param props Input props
1911
+ * @template A Allowed type
1912
+ * @param allowed Allowed values
2613
1913
  * @param message Issue message when invalid
2614
- * @returns Email input field
1914
+ * @returns Enum schema
2615
1915
  */
2616
- static email(
2617
- props?: Field.Props.Input,
1916
+ static enum<const A extends readonly [unknown, ...unknown[]]>(
1917
+ allowed: A,
2618
1918
  message?: string,
2619
- ): Field.Instance<string, "input", "email"> {
2620
- return new FieldSchema(
2621
- { props: { ...props, type: "email" } },
2622
- Schema.string(Field.#required).email(message),
2623
- );
1919
+ ) {
1920
+ return new Schema<A[number]>({ type: "enum", values: allowed, message });
2624
1921
  }
2625
1922
 
2626
1923
  /**
2627
- * Validates parsable URL.
1924
+ * Tries each schema in order and returns the first successfully parsed result.
2628
1925
  *
2629
- * @param props Input props
2630
- * @param message Issue message when invalid
2631
- * @returns URL input field
1926
+ * @template S Schemas type
1927
+ * @param schemas Schemas to try in order
1928
+ * @returns Union schema
2632
1929
  */
2633
- static url(
2634
- props?: Field.Props.Input,
2635
- message?: string,
2636
- ): Field.Instance<string, "input", "url"> {
2637
- return new FieldSchema(
2638
- { props: { ...props, type: "url" } },
2639
- Schema.string(Field.#required).url(message),
2640
- );
1930
+ static union<
1931
+ const S extends readonly [Schema<unknown>, ...Schema<unknown>[]],
1932
+ >(schemas: S) {
1933
+ return new Schema<Schema.Infer<S[number]>>({
1934
+ type: "union",
1935
+ options: schemas,
1936
+ });
2641
1937
  }
2642
1938
 
2643
1939
  /**
2644
- * @param props Input props
2645
- * @returns Input field
1940
+ * Validates an input is an instance of the constructor.
1941
+ *
1942
+ * @template O Output type
1943
+ * @param constructor Constructor to validate the input is an instance of
1944
+ * @param message Issue message when invalid
1945
+ * @returns Validated instance
2646
1946
  */
2647
- static #number<T extends "number" | "range">(
2648
- props: Field.Props.Input & { type: T },
2649
- ): Field.Instance<number, "input", T> {
2650
- return new FieldSchema(
2651
- { props },
2652
- Schema.number(Field.#required).preprocess((value) =>
2653
- // form submissions read numeric controls as strings
2654
- value == null || value === "" ? undefined : Number(value),
2655
- ),
2656
- );
1947
+ static instance<O>(constructor: new (...args: any[]) => O, message?: string) {
1948
+ return new Schema<O>({ type: "instance", class: constructor, message });
2657
1949
  }
2658
1950
 
2659
1951
  /**
2660
- * Coerces to number.
1952
+ * Validates that the input is an array and parses each item.
2661
1953
  *
2662
- * @param props Input props
2663
- * @returns Number input field
1954
+ * @template O Output type
1955
+ * @param schema Schema for each array item
1956
+ * @param message Issue message when invalid
1957
+ * @returns Array schema
2664
1958
  */
2665
- static number(
2666
- props?: Field.Props.Input,
2667
- ): Field.Instance<number, "input", "number"> {
2668
- return Field.#number({ ...props, type: "number" });
1959
+ static array<O>(schema: Schema<O>, message?: string) {
1960
+ return new Schema<O[]>({ type: "array", item: schema, message });
2669
1961
  }
2670
1962
 
2671
1963
  /**
2672
- * Coerces to number.
1964
+ * Validates each key in the shape and returns a new object of parsed outputs.
2673
1965
  *
2674
- * @param props Input props
2675
- * @returns Range input field
1966
+ * @template S Object shape type
1967
+ * @param shape Object shape with schemas for each key
1968
+ * @returns Object schema
2676
1969
  */
2677
- static range(
2678
- props?: Field.Props.Input,
2679
- ): Field.Instance<number, "input", "range"> {
2680
- return Field.#number({ ...props, type: "range" });
1970
+ static object<S extends Schema.Object.Shape = {}>(
1971
+ shape: S = {} as S,
1972
+ ): Schema.Object<S> {
1973
+ return new ObjectSchema(shape, "strip");
2681
1974
  }
1975
+ }
1976
+
1977
+ /**
1978
+ * Runtime object schema that validates plain objects and supports shape helpers.
1979
+ *
1980
+ * @template Shape Object shape type
1981
+ * @template Mode Object parsing mode
1982
+ */
1983
+ class ObjectSchema<
1984
+ Shape extends Schema.Object.Shape,
1985
+ Mode extends Schema.Object.Mode = "strip",
1986
+ > extends Schema<Schema.Object.Output<Shape, Mode>> {
1987
+ /** Object shape definitions. */
1988
+ readonly shape: Shape;
1989
+
1990
+ /** Object parsing mode. */
1991
+ readonly #mode: Mode;
2682
1992
 
2683
1993
  /**
2684
- * - unchecked => key missing => `false`
2685
- * - checked => key present => `true`
1994
+ * Create a new object schema validator.
2686
1995
  *
2687
- * @param props Input props
2688
- * @returns Checkbox input field
1996
+ * @param shape Object shape
1997
+ * @param mode Object parsing mode
1998
+ * @param description Description from `describe()`
2689
1999
  */
2690
- static checkbox(
2691
- props?: Field.Props.Input,
2692
- ): Field.Instance<boolean, "input", "checkbox"> {
2693
- return new FieldSchema(
2694
- { props: { ...props, type: "checkbox" } },
2695
- Schema.boolean(),
2696
- (formData, name) => formData.has(name),
2697
- );
2698
- }
2000
+ constructor(
2001
+ shape: Shape,
2002
+ mode: Mode = "strip" as Mode,
2003
+ description?: string,
2004
+ ) {
2005
+ super({
2006
+ type: "object",
2007
+ shape,
2008
+ mode,
2009
+ ...(description !== undefined && { description }),
2010
+ });
2699
2011
 
2700
- /**
2701
- * @param props Input props
2702
- * @returns File input field
2703
- */
2704
- static file(
2705
- props?: Field.Props.Input,
2706
- ): Field.Instance<File, "input", "file"> {
2707
- return new FieldSchema(
2708
- { props: { ...props, type: "file" } },
2709
- Schema.instance(File, Field.#required),
2710
- (data, name) => {
2711
- const value = data.get(name);
2012
+ this.shape = shape;
2013
+ this.#mode = mode;
2014
+ }
2712
2015
 
2713
- return (Field.#nonEmptyFile(value) && value) || undefined;
2714
- },
2715
- );
2016
+ override describe(text: string) {
2017
+ // still an object schema, which `derive` would not make
2018
+ return new ObjectSchema(this.shape, this.#mode, text) as this;
2716
2019
  }
2717
2020
 
2718
2021
  /**
2719
- * @param props Input props
2720
- * @returns Multiple file input field
2022
+ * Merge `extra` into the current shape.
2023
+ *
2024
+ * @template E Extra shape type
2025
+ * @param extra Extra shape or object schema to merge
2026
+ * @returns New object schema with the merged shape
2721
2027
  */
2722
- static files(
2723
- props?: Field.Props.Input,
2724
- ): Field.Instance<File[], "input", "file"> {
2725
- return new FieldSchema(
2726
- { props: { ...props, type: "file", multiple: true } },
2727
- Schema.array(Schema.instance(File, Field.#required), Field.#required),
2728
- (data, name) => {
2729
- const value = data.getAll(name).filter(Field.#nonEmptyFile);
2730
-
2731
- return value.length ? value : undefined;
2732
- },
2733
- Infinity,
2734
- );
2735
- }
2736
-
2028
+ extend<E extends Schema.Object.Shape>(
2029
+ extra: E,
2030
+ ): Schema.Object<ShapeUtil.Extend<Shape, E>, Mode>;
2737
2031
  /**
2738
- * @template V Value type
2739
- * @param values Checkbox values
2740
- * @param props Input props
2741
- * @returns Checkbox group input field
2032
+ * Merge the shape of `extra`, an object schema, into the current shape.
2033
+ *
2034
+ * @template E Extra shape type
2035
+ * @param extra Object schema to merge
2036
+ * @returns New object schema with the merged shape
2742
2037
  */
2743
- static checkboxes<const V extends string>(
2744
- values: readonly [V, ...V[]],
2745
- props?: Field.Props.Input,
2746
- ): Field.Instance<V[], "input", "checkbox", readonly [V, ...V[]]> {
2747
- return new FieldSchema(
2748
- { values, props: { ...props, type: "checkbox" } },
2749
- Schema.array(Schema.enum(values, Field.#required), Field.#required),
2750
- Field.#readMany,
2751
- values.length,
2038
+ extend<E extends Schema.Object.Shape>(
2039
+ extra: Schema.Object<E>,
2040
+ ): Schema.Object<ShapeUtil.Extend<Shape, E>, Mode>;
2041
+ extend(extra: Schema.Object.Shape | Schema.Object<any>) {
2042
+ return new ObjectSchema(
2043
+ ShapeUtil.extend(
2044
+ this.shape,
2045
+ extra instanceof ObjectSchema ? extra.shape : extra,
2046
+ ),
2047
+ this.#mode,
2048
+ this.def.description,
2752
2049
  );
2753
2050
  }
2754
2051
 
2755
2052
  /**
2756
- * @template V Value type
2757
- * @param values Radio button values
2758
- * @param props Input props
2759
- * @returns Radio group input field
2053
+ * Keep only selected field names.
2054
+ *
2055
+ * @template N Selected key names
2056
+ * @param names Non-empty list of key names to keep
2057
+ * @returns New object schema with only selected keys
2760
2058
  */
2761
- static radio<const V extends string>(
2762
- values: readonly [V, ...V[]],
2763
- props?: Field.Props.Input,
2764
- ): Field.Instance<V, "input", "radio", readonly [V, ...V[]]> {
2765
- return new FieldSchema(
2766
- { values, props: { ...props, type: "radio" } },
2767
- Schema.enum(values, Field.#required),
2059
+ pick<N extends ShapeUtil.Name<Shape>>(
2060
+ names: readonly [N, ...N[]],
2061
+ ): Schema.Object<Pick<Shape, N>, Mode> {
2062
+ return new ObjectSchema(
2063
+ ShapeUtil.pick(this.shape, names),
2064
+ this.#mode,
2065
+ this.def.description,
2768
2066
  );
2769
2067
  }
2770
2068
 
2771
2069
  /**
2772
- * @param props Textarea props
2773
- * @returns Textarea field
2070
+ * Remove selected field names.
2071
+ *
2072
+ * @template N Removed key names
2073
+ * @param names Non-empty list of key names to remove
2074
+ * @returns New object schema without selected keys
2774
2075
  */
2775
- static textarea(
2776
- props?: Field.Props.Textarea,
2777
- ): Field.Instance<string, "textarea"> {
2778
- return new FieldSchema(
2779
- { tag: "textarea", props },
2780
- Schema.string(Field.#required),
2076
+ omit<N extends ShapeUtil.Name<Shape>>(
2077
+ names: readonly [N, ...N[]],
2078
+ ): Schema.Object<Omit<Shape, N>, Mode> {
2079
+ return new ObjectSchema(
2080
+ ShapeUtil.omit(this.shape, names),
2081
+ this.#mode,
2082
+ this.def.description,
2781
2083
  );
2782
2084
  }
2783
2085
 
2784
2086
  /**
2785
- * @template V Value type
2786
- * @param values Select options
2787
- * @param props Select props
2788
- * @returns Select field
2087
+ * Reject unknown keys during parsing.
2088
+ *
2089
+ * @returns New object schema in strict mode
2789
2090
  */
2790
- static select<const V extends string>(
2791
- values: readonly [V, ...V[]],
2792
- props?: Field.Props.Select,
2793
- ): Field.Instance<V, "select", Field.Type, readonly [V, ...V[]]> {
2794
- return new FieldSchema(
2795
- { tag: "select", values, props },
2796
- Schema.enum(values, Field.#required),
2797
- );
2091
+ strict(): Schema.Object<Shape, "strict"> {
2092
+ return new ObjectSchema(this.shape, "strict", this.def.description);
2798
2093
  }
2799
2094
 
2800
2095
  /**
2801
- * @template V Value type
2802
- * @param values Select options
2803
- * @param props Select props
2804
- * @returns Multi-select field
2096
+ * Preserve unknown keys during parsing.
2097
+ *
2098
+ * @returns New object schema in loose mode
2805
2099
  */
2806
- static multiselect<const V extends string>(
2807
- values: readonly [V, ...V[]],
2808
- props?: Field.Props.Select,
2809
- ): Field.Instance<V[], "select", Field.Type, readonly [V, ...V[]]> {
2810
- return new FieldSchema(
2811
- { tag: "select", values, props: { ...props, multiple: true } },
2812
- Schema.array(Schema.enum(values, Field.#required), Field.#required),
2813
- Field.#readMany,
2814
- values.length,
2815
- );
2100
+ loose(): Schema.Object<Shape, "loose"> {
2101
+ return new ObjectSchema(this.shape, "loose", this.def.description);
2816
2102
  }
2817
2103
  }