ovr 6.0.1 → 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.
- package/dist/LICENSE.md +2 -0
- package/dist/app/index.d.ts +1 -1
- package/dist/app/index.d.ts.map +1 -1
- package/dist/app/index.js +17 -11
- package/dist/context/index.d.ts +37 -13
- package/dist/context/index.d.ts.map +1 -1
- package/dist/context/index.js +70 -29
- package/dist/cookie/index.d.ts +1 -1
- package/dist/cookie/index.d.ts.map +1 -1
- package/dist/cookie/index.js +2 -2
- package/dist/index.d.ts +4 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -2
- package/dist/jsx/elements.d.ts +194 -2
- package/dist/jsx/elements.d.ts.map +1 -1
- package/dist/jsx/index.d.ts.map +1 -1
- package/dist/jsx/index.js +18 -8
- package/dist/middleware/index.d.ts +12 -3
- package/dist/middleware/index.d.ts.map +1 -1
- package/dist/multipart/index.d.ts +5 -0
- package/dist/multipart/index.d.ts.map +1 -1
- package/dist/multipart/index.js +22 -24
- package/dist/render/index.d.ts +1 -0
- package/dist/render/index.d.ts.map +1 -1
- package/dist/render/index.js +6 -4
- package/dist/route/index.d.ts +143 -42
- package/dist/route/index.d.ts.map +1 -1
- package/dist/route/index.js +95 -43
- package/dist/schema/index.d.ts +1286 -0
- package/dist/schema/index.d.ts.map +1 -0
- package/dist/schema/index.js +1321 -0
- package/dist/trie/index.d.ts.map +1 -1
- package/dist/trie/index.js +8 -2
- package/dist/util/index.d.ts +138 -9
- package/dist/util/index.d.ts.map +1 -1
- package/dist/util/index.js +152 -19
- package/package.json +4 -1
- package/src/app/index.ts +17 -15
- package/src/context/index.ts +116 -40
- package/src/cookie/index.ts +5 -5
- package/src/index.ts +4 -3
- package/src/jsx/elements.ts +320 -64
- package/src/jsx/index.ts +16 -8
- package/src/middleware/index.ts +19 -8
- package/src/multipart/index.ts +25 -27
- package/src/render/index.ts +7 -4
- package/src/route/index.ts +338 -94
- package/src/schema/index.ts +2794 -0
- package/src/trie/index.ts +12 -2
- package/src/util/index.ts +193 -19
|
@@ -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
|
+
}
|