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