1 | import { Validator } from './types';
|
2 | import { Branch, Failure, Path } from './struct-error';
|
3 | import { Struct } from './struct';
|
4 | /**
|
5 | * `SuperstructSettings` are passed in when creating a `Superstruct` factory.
|
6 | */
|
7 | export declare type SuperstructSettings = {
|
8 | types: Record<string, Validator>;
|
9 | error: {
|
10 | new (failures: Failure[]): Error;
|
11 | };
|
12 | };
|
13 | /**
|
14 | * Create a struct singleton with settings that include your own domain-specific
|
15 | * data `types`, and an optional custom `Error` class.
|
16 | */
|
17 | export declare const superstruct: (settings?: Partial<SuperstructSettings>) => Superstruct;
|
18 | /**
|
19 | * `Superstruct` factories create different kinds of [[Struct]] validators, and
|
20 | * encapsulate the user-defined data types.
|
21 | *
|
22 | * The [[struct]] export is a factory that ships with Superstruct by default,
|
23 | * pre-configured with all of the built-in JavaScript data types. It's the
|
24 | * easiest way to quickly define structs:
|
25 | *
|
26 | * ```js
|
27 | * import { struct } from 'superstruct'
|
28 | *
|
29 | * const User = struct({
|
30 | * id: 'number',
|
31 | * name: 'string',
|
32 | * })
|
33 | * ```
|
34 | *
|
35 | * If you need to define custom data types, you can define your own by using
|
36 | * the [[superstruct]] export:
|
37 | *
|
38 | * ```js
|
39 | * import { superstruct } from 'superstruct'
|
40 | * import isEmail from 'is-email'
|
41 | * import isUrl from 'is-url'
|
42 | *
|
43 | * const struct = superstruct({
|
44 | * types: {
|
45 | * email: value => isEmail(value) && value.length < 256,
|
46 | * url: value => isUrl(value) && value.length < 2048,
|
47 | * }
|
48 | * })
|
49 | *
|
50 | * const User = struct({
|
51 | * id: 'number',
|
52 | * name: 'string',
|
53 | * email: 'email',
|
54 | * website: 'url?',
|
55 | * })
|
56 | * ```
|
57 | *
|
58 | * This way you can easily define structs that contain types like `'email'`,
|
59 | * `'url'`, or whatever else your application may need.
|
60 | */
|
61 | export interface Superstruct {
|
62 | /**
|
63 | * Structs are defined by passing a schema definition to the struct factory.
|
64 | * The schema definition can be a string, array, object or function. They can
|
65 | * also be composed by nesting structs inside each other.
|
66 | *
|
67 | * The default struct factory allows you to write structs using a shorthand
|
68 | * syntax for the most common cases—arrays, objects, scalars, tuples, etc.
|
69 | *
|
70 | * ```js
|
71 | * struct('string') // Scalars
|
72 | * struct(['number']) // Arrays
|
73 | * struct({ name: 'string' }) // Objects
|
74 | * struct(['error', 'string']) // Tuples
|
75 | * struct('number?') // Optional
|
76 | * struct('string & email') // Intersection
|
77 | * struct('number | string') // Union
|
78 | * struct(value => true || false) // Function
|
79 | * struct(Struct) // Pass-through
|
80 | * ```
|
81 | *
|
82 | * Each shorthand is equivalent to a method on the [[Superstruct]] factory:
|
83 | *
|
84 | * ```js
|
85 | * // These are equivalent...
|
86 | * struct(['number'])
|
87 | * struct.array(['number'])
|
88 | *
|
89 | * struct('string & email')
|
90 | * struct.union(['string', 'email'])
|
91 | * ```
|
92 | *
|
93 | * And each one can use your custom types, or even other structs:
|
94 | *
|
95 | * ```js
|
96 | * struct('email')
|
97 | * struct(User)
|
98 | * ```
|
99 | *
|
100 | * The second argument to struct factories is always a `defaults` value. It
|
101 | * can either be the default itself or a function that returns the default.
|
102 | *
|
103 | * ```js
|
104 | * struct('id', uuid.v4)
|
105 | *
|
106 | * struct({
|
107 | * id: 'number',
|
108 | * name: 'string',
|
109 | * is_admin: 'boolean?',
|
110 | * }, {
|
111 | * is_admin: false,
|
112 | * })
|
113 | * ```
|
114 | */
|
115 | (schema: any, defaults?: any): Struct;
|
116 | /**
|
117 | * Array structs validate that their input is an array with elements that
|
118 | * match a specific struct. You can also pass the `max` or `min` options to
|
119 | * validate the length of the array.
|
120 | *
|
121 | * ```js
|
122 | * const Struct = struct.array(['number'])
|
123 | *
|
124 | * Struct([1, 2, 3])
|
125 | * ```
|
126 | *
|
127 | * They are similar to the `Array` type in TypeScript.
|
128 | */
|
129 | array(schema: [any], defaults?: any): Struct;
|
130 | /**
|
131 | * Dynamic structs are defined by a function that is passed the value being
|
132 | * validated, and they determine which struct to use at runtime.
|
133 | *
|
134 | * ```js
|
135 | * const Struct = struct.dynamic(value => StructA || StructB)
|
136 | * ```
|
137 | *
|
138 | * They are inhernetly less performant that compile-time structs, but they
|
139 | * unlock a set of possibilities that aren't possible at compile time alone.
|
140 | */
|
141 | dynamic(schema: (value: any, branch: Branch, path: Path) => Struct, defaults?: any): Struct;
|
142 | /**
|
143 | * Enum structs validate that their input is one of a set of values.
|
144 | *
|
145 | * ```js
|
146 | * const Struct = struct.enum(['fruit', 'vegetable', 'meat'])
|
147 | *
|
148 | * Struct('fruit')
|
149 | * ```
|
150 | *
|
151 | * They are similar to the `enum` type in TypeScript.
|
152 | */
|
153 | enum(schema: any[], defaults?: any): Struct;
|
154 | /**
|
155 | * Function structs validate their input against a one-off validator function.
|
156 | *
|
157 | * ```js
|
158 | * const Struct = struct.function(value => typeof value === 'string')
|
159 | *
|
160 | * Struct('a simple string')
|
161 | * ```
|
162 | *
|
163 | * They can't provide as detailed of errors as other struct types, but they do
|
164 | * allow for customization for easy one-off cases.
|
165 | */
|
166 | function(schema: Validator, defaults?: any): Struct;
|
167 | /**
|
168 | * Instance structs validate that their input is an instance of a class.
|
169 | *
|
170 | * ```js
|
171 | * const Struct = struct.instance(MyClass)
|
172 | *
|
173 | * Struct(new MyClass())
|
174 | * ```
|
175 | */
|
176 | instance(schema: any, defaults?: any): Struct;
|
177 | /**
|
178 | * Interface structs validate that their input matches an interface defined as
|
179 | * a set of properties with associated types.
|
180 | *
|
181 | * ```js
|
182 | * const Struct = struct.interface({
|
183 | * length: 'number',
|
184 | * indexOf: 'function',
|
185 | * })
|
186 | *
|
187 | * Struct([1, 2, 3])
|
188 | * Struct('abc')
|
189 | * ```
|
190 | *
|
191 | * They are similar to the structural-typing granted by TypeScript.
|
192 | */
|
193 | interface(schema: any, defaults?: any): Struct;
|
194 | /**
|
195 | * Intersection structs validate that their input matches **all** of a set of
|
196 | * different structs.
|
197 | *
|
198 | * ```js
|
199 | * const Struct = struct.intersection('string & email')
|
200 | *
|
201 | * Struct('jane@example.com')
|
202 | * ```
|
203 | *
|
204 | * Note: The structs will be validated in order, so validators on the right
|
205 | * can rely on the validators before them having passed.
|
206 | *
|
207 | * They are similar to the `&` operator in TypeScript.
|
208 | */
|
209 | intersection(schema: any[], defaults?: any): Struct;
|
210 | /**
|
211 | * Lazy structs allow you to initialize a struct lazily, only initializing it
|
212 | * once on the first time it attempts to be validated.
|
213 | *
|
214 | * ```js
|
215 | * const Struct = struct({
|
216 | * nodes: struct.lazy(() => Struct)
|
217 | * })
|
218 | *
|
219 | * Struct({
|
220 | * nodes: {
|
221 | * nodes: { ... }
|
222 | * }
|
223 | * })
|
224 | * ```
|
225 | *
|
226 | * They are helpful for defining recursive structs.
|
227 | */
|
228 | lazy(schema: () => Struct, defaults?: any): Struct;
|
229 | /**
|
230 | * Literal structs validate their input against a literal value.
|
231 | *
|
232 | * ```js
|
233 | * const Struct = struct.literal(42)
|
234 | *
|
235 | * Struct(42)
|
236 | * ```
|
237 | */
|
238 | literal(schema: any, defaults?: any): Struct;
|
239 | /**
|
240 | * Object structs validate that their input exactly matches an object defined
|
241 | * as a set of properties with associated types.
|
242 | *
|
243 | * ```js
|
244 | * const Struct = struct.object({
|
245 | * id: 'number',
|
246 | * name: 'string',
|
247 | * })
|
248 | *
|
249 | * Struct({
|
250 | * id: 1,
|
251 | * name: 'Jane Smith',
|
252 | * })
|
253 | * ```
|
254 | *
|
255 | * They are similar to the `?` qualifier in TypeScript.
|
256 | */
|
257 | object(schema: {}, defaults?: any): Struct;
|
258 | /**
|
259 | * Optional structs validate that their input passes a specific struct, or
|
260 | * `undefined`.
|
261 | *
|
262 | * ```js
|
263 | * const Struct = struct.optional('string?')
|
264 | *
|
265 | * Struct('a string of text')
|
266 | * Struct(undefined)
|
267 | * ```
|
268 | *
|
269 | * This is a shorthand for using `struct.union` with `undefined`.
|
270 | */
|
271 | optional(schema: any, defaults?: any): Struct;
|
272 | /**
|
273 | * Partial structs validate that their input partially matches an object
|
274 | * defined as a set of properties with associated types. All of the properties
|
275 | * of the object are optional.
|
276 | *
|
277 | * ```js
|
278 | * const Struct = struct.partial({
|
279 | * id: 'number'
|
280 | * name: 'string',
|
281 | * })
|
282 | *
|
283 | * Struct({
|
284 | * name: 'Jane Smith',
|
285 | * })
|
286 | * ```
|
287 | *
|
288 | * They are similar to the `Partial` utility in TypeScript.
|
289 | */
|
290 | partial(schema: {}, defaults?: any): Struct;
|
291 | /**
|
292 | * Pick structs validate that their input exactly matches a subset of an
|
293 | * object defined as a set of properties with associated types. All of the
|
294 | * properties of its schema are required, but the object can have more that it
|
295 | * does not concern itself with.
|
296 | *
|
297 | * ```js
|
298 | * const Struct = struct.pick({
|
299 | * id: 'string',
|
300 | * name: 'string',
|
301 | * })
|
302 | *
|
303 | * Struct({
|
304 | * id: 1,
|
305 | * name: 'James Smith',
|
306 | * email: 'james@example.com',
|
307 | * })
|
308 | * ```
|
309 | *
|
310 | * They are similar to the `Pick` utility in TypeScript.
|
311 | */
|
312 | pick(schema: {}, defaults?: any): Struct;
|
313 | /**
|
314 | * Record structs validate that their input is an object with keys that match
|
315 | * one struct and values that match another. The object can have zero or many
|
316 | * properties set on it.
|
317 | *
|
318 | * ```js
|
319 | * const Struct = struct.record('string', 'number')
|
320 | *
|
321 | * Struct({
|
322 | * a: 1,
|
323 | * b: 2,
|
324 | * })
|
325 | * ```
|
326 | *
|
327 | * They are similar to the `Record` utility in TypeScript.
|
328 | */
|
329 | record(schema: [any, any], defaults?: any): Struct;
|
330 | /**
|
331 | * Scalar structs validate that their input passes the `Validator` function
|
332 | * defined for a specific type by name. By default Superstruct ships with a
|
333 | * set of built-in scalars. But you can configure it with custom scalars that
|
334 | * match your domain.
|
335 | *
|
336 | * ```js
|
337 | * const Struct = struct.scalar('string')
|
338 | *
|
339 | * Struct('a string of text')
|
340 | * ```
|
341 | */
|
342 | scalar(schema: string, defaults?: any): Struct;
|
343 | /**
|
344 | * Size structs validate their input has a certain length, by checking its
|
345 | * `length` property. This works strings or arrays.
|
346 | *
|
347 | * ```js
|
348 | * const Struct = struct.size([0, 7])
|
349 | *
|
350 | * Struct([1, 2, 3])
|
351 | * Struct('abcdefg')
|
352 | * ```
|
353 | *
|
354 | * They are helpful for defining unions with array structs.
|
355 | */
|
356 | size(schema: [number, number], defaults?: any): Struct;
|
357 | /**
|
358 | * Tuple structs validate that their input exactly matches a tuple of values,
|
359 | * in length and in type.
|
360 | *
|
361 | * ```js
|
362 | * const Struct = struct.tuple(['string', 'boolean'])
|
363 | *
|
364 | * Struct(['one', true])
|
365 | * ```
|
366 | */
|
367 | tuple(schema: any[], defaults?: any): Struct;
|
368 | /**
|
369 | * Union structs validate that their input matches **at least one** of a set
|
370 | * of different structs.
|
371 | *
|
372 | * ```js
|
373 | * const Struct = struct.union(['string', 'number'])
|
374 | *
|
375 | * Struct('a string')
|
376 | * Struct(42)
|
377 | * ```
|
378 | *
|
379 | * They are similar to the `|` operator in TypeScript.
|
380 | */
|
381 | union(schema: any[], defaults?: any): Struct;
|
382 | /**
|
383 | * The class for errors thrown by `Structs`, defaults to [[StructError]].
|
384 | */
|
385 | Error: {
|
386 | new (failures: Failure[]): Error;
|
387 | };
|
388 | /**
|
389 | * The set of data types that the factory knows.
|
390 | */
|
391 | Types: Record<string, Validator>;
|
392 | }
|
393 |
|
\ | No newline at end of file |