@xylabs/zod 5.0.84 → 5.0.86

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +160 -197
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -15,6 +15,8 @@
15
15
 
16
16
  Base functionality used throughout XY Labs TypeScript/JavaScript libraries
17
17
 
18
+
19
+
18
20
  ## Reference
19
21
 
20
22
  **@xylabs/zod**
@@ -23,21 +25,27 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
23
25
 
24
26
  ## Interfaces
25
27
 
26
- - [ZodFactoryConfigObject](#interfaces/ZodFactoryConfigObject)
28
+ | Interface | Description |
29
+ | ------ | ------ |
30
+ | [ZodFactoryConfigObject](#interfaces/ZodFactoryConfigObject) | Configuration object for zod factory functions, providing a name for error messages. |
27
31
 
28
32
  ## Type Aliases
29
33
 
30
- - [ZodFactoryConfig](#type-aliases/ZodFactoryConfig)
31
- - [AllZodFactories](#type-aliases/AllZodFactories)
34
+ | Type Alias | Description |
35
+ | ------ | ------ |
36
+ | [ZodFactoryConfig](#type-aliases/ZodFactoryConfig) | Configuration for zod factory assertion behavior, either an AssertConfig or a named config object. |
37
+ | [AllZodFactories](#type-aliases/AllZodFactories) | - |
32
38
 
33
39
  ## Functions
34
40
 
35
- - [zodAllFactory](#functions/zodAllFactory)
36
- - [zodAsAsyncFactory](#functions/zodAsAsyncFactory)
37
- - [zodAsFactory](#functions/zodAsFactory)
38
- - [zodIsFactory](#functions/zodIsFactory)
39
- - [zodToAsyncFactory](#functions/zodToAsyncFactory)
40
- - [zodToFactory](#functions/zodToFactory)
41
+ | Function | Description |
42
+ | ------ | ------ |
43
+ | [zodAllFactory](#functions/zodAllFactory) | Creates a bundle of `is`, `as`, and `to` factory functions for a given zod schema. |
44
+ | [zodAsAsyncFactory](#functions/zodAsAsyncFactory) | Creates an async function that validates a value against a zod schema and returns it with a narrowed type. Uses `safeParseAsync` for schemas with async refinements. When called without an assert config, returns undefined on failure. |
45
+ | [zodAsFactory](#functions/zodAsFactory) | Creates a function that validates a value against a zod schema and returns it with a narrowed type. When called without an assert config, returns undefined on failure. When called with an assert config, throws on failure. |
46
+ | [zodIsFactory](#functions/zodIsFactory) | Creates a type guard function that checks if a value matches a zod schema. |
47
+ | [zodToAsyncFactory](#functions/zodToAsyncFactory) | Creates an async function that converts a value to the zod schema type, delegating to `zodAsAsyncFactory` internally. Provides overloads for optional assertion: without assert config resolves to undefined on failure, with assert config throws on failure. |
48
+ | [zodToFactory](#functions/zodToFactory) | Creates a function that converts a value to the zod schema type, delegating to `zodAsFactory` internally. Provides overloads for optional assertion: without assert config returns undefined on failure, with assert config throws on failure. |
41
49
 
42
50
  ### functions
43
51
 
@@ -48,7 +56,12 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
48
56
  ***
49
57
 
50
58
  ```ts
51
- function zodAllFactory<T, TName>(zod, name): object;
59
+ function zodAllFactory<T, TName>(zod: ZodType<T>, name: TName): {
60
+ [key: string]: {
61
+ <T> (value: T): T & T | undefined;
62
+ <T> (value: T, assert: ZodFactoryConfig): T & T;
63
+ };
64
+ };
52
65
  ```
53
66
 
54
67
  **`Alpha`**
@@ -57,31 +70,28 @@ Creates a bundle of `is`, `as`, and `to` factory functions for a given zod schem
57
70
 
58
71
  ## Type Parameters
59
72
 
60
- ### T
61
-
62
- `T`
63
-
64
- ### TName
65
-
66
- `TName` *extends* `string`
73
+ | Type Parameter |
74
+ | ------ |
75
+ | `T` |
76
+ | `TName` *extends* `string` |
67
77
 
68
78
  ## Parameters
69
79
 
70
- ### zod
71
-
72
- `ZodType`\<`T`\>
73
-
74
- The zod schema to validate against
75
-
76
- ### name
77
-
78
- `TName`
79
-
80
- The name used to suffix the generated function names (e.g. 'Address' produces `isAddress`, `asAddress`, `toAddress`)
80
+ | Parameter | Type | Description |
81
+ | ------ | ------ | ------ |
82
+ | `zod` | `ZodType`\<`T`\> | The zod schema to validate against |
83
+ | `name` | `TName` | The name used to suffix the generated function names (e.g. 'Address' produces `isAddress`, `asAddress`, `toAddress`) |
81
84
 
82
85
  ## Returns
83
86
 
84
- `object`
87
+ ```ts
88
+ {
89
+ [key: string]: {
90
+ <T> (value: T): T & T | undefined;
91
+ <T> (value: T, assert: ZodFactoryConfig): T & T;
92
+ };
93
+ }
94
+ ```
85
95
 
86
96
  An object containing `is<Name>`, `as<Name>`, and `to<Name>` functions
87
97
 
@@ -92,9 +102,9 @@ An object containing `is<Name>`, `as<Name>`, and `to<Name>` functions
92
102
  ***
93
103
 
94
104
  ```ts
95
- function zodAsAsyncFactory<TZod>(zod, name): {
96
- <T> (value): Promise<T & TZod | undefined>;
97
- <T> (value, assert): Promise<T & TZod>;
105
+ function zodAsAsyncFactory<TZod>(zod: ZodType<TZod>, name: string): {
106
+ <T> (value: T): Promise<T & TZod | undefined>;
107
+ <T> (value: T, assert: ZodFactoryConfig): Promise<T & TZod>;
98
108
  };
99
109
  ```
100
110
 
@@ -103,67 +113,57 @@ Uses `safeParseAsync` for schemas with async refinements. When called without an
103
113
 
104
114
  ## Type Parameters
105
115
 
106
- ### TZod
107
-
108
- `TZod`
116
+ | Type Parameter |
117
+ | ------ |
118
+ | `TZod` |
109
119
 
110
120
  ## Parameters
111
121
 
112
- ### zod
113
-
114
- `ZodType`\<`TZod`\>
115
-
116
- The zod schema to validate against
117
-
118
- ### name
119
-
120
- `string`
121
-
122
- A name used in error messages for identification
122
+ | Parameter | Type | Description |
123
+ | ------ | ------ | ------ |
124
+ | `zod` | `ZodType`\<`TZod`\> | The zod schema to validate against |
125
+ | `name` | `string` | A name used in error messages for identification |
123
126
 
124
127
  ## Returns
125
128
 
126
129
  An async function that validates and narrows the type of a value
127
130
 
128
131
  ```ts
129
- <T>(value): Promise<T & TZod | undefined>;
132
+ <T>(value: T): Promise<T & TZod | undefined>;
130
133
  ```
131
134
 
132
135
  ### Type Parameters
133
136
 
134
- ### T
135
-
136
- `T`
137
+ | Type Parameter |
138
+ | ------ |
139
+ | `T` |
137
140
 
138
141
  ### Parameters
139
142
 
140
- ### value
141
-
142
- `T`
143
+ | Parameter | Type |
144
+ | ------ | ------ |
145
+ | `value` | `T` |
143
146
 
144
147
  ### Returns
145
148
 
146
149
  `Promise`\<`T` & `TZod` \| `undefined`\>
147
150
 
148
151
  ```ts
149
- <T>(value, assert): Promise<T & TZod>;
152
+ <T>(value: T, assert: ZodFactoryConfig): Promise<T & TZod>;
150
153
  ```
151
154
 
152
155
  ### Type Parameters
153
156
 
154
- ### T
155
-
156
- `T`
157
+ | Type Parameter |
158
+ | ------ |
159
+ | `T` |
157
160
 
158
161
  ### Parameters
159
162
 
160
- ### value
161
-
162
- `T`
163
-
164
- ### assert
165
-
166
- [`ZodFactoryConfig`](#../type-aliases/ZodFactoryConfig)
163
+ | Parameter | Type |
164
+ | ------ | ------ |
165
+ | `value` | `T` |
166
+ | `assert` | [`ZodFactoryConfig`](#../type-aliases/ZodFactoryConfig) |
167
167
 
168
168
  ### Returns
169
169
 
@@ -176,9 +176,9 @@ An async function that validates and narrows the type of a value
176
176
  ***
177
177
 
178
178
  ```ts
179
- function zodAsFactory<TZod>(zod, name): {
180
- <T> (value): T & TZod | undefined;
181
- <T> (value, assert): T & TZod;
179
+ function zodAsFactory<TZod>(zod: ZodType<TZod>, name: string): {
180
+ <T> (value: T): T & TZod | undefined;
181
+ <T> (value: T, assert: ZodFactoryConfig): T & TZod;
182
182
  };
183
183
  ```
184
184
 
@@ -187,67 +187,57 @@ When called without an assert config, returns undefined on failure. When called
187
187
 
188
188
  ## Type Parameters
189
189
 
190
- ### TZod
191
-
192
- `TZod`
190
+ | Type Parameter |
191
+ | ------ |
192
+ | `TZod` |
193
193
 
194
194
  ## Parameters
195
195
 
196
- ### zod
197
-
198
- `ZodType`\<`TZod`\>
199
-
200
- The zod schema to validate against
201
-
202
- ### name
203
-
204
- `string`
205
-
206
- A name used in error messages for identification
196
+ | Parameter | Type | Description |
197
+ | ------ | ------ | ------ |
198
+ | `zod` | `ZodType`\<`TZod`\> | The zod schema to validate against |
199
+ | `name` | `string` | A name used in error messages for identification |
207
200
 
208
201
  ## Returns
209
202
 
210
203
  A function that validates and narrows the type of a value
211
204
 
212
205
  ```ts
213
- <T>(value): T & TZod | undefined;
206
+ <T>(value: T): T & TZod | undefined;
214
207
  ```
215
208
 
216
209
  ### Type Parameters
217
210
 
218
- ### T
219
-
220
- `T`
211
+ | Type Parameter |
212
+ | ------ |
213
+ | `T` |
221
214
 
222
215
  ### Parameters
223
216
 
224
- ### value
225
-
226
- `T`
217
+ | Parameter | Type |
218
+ | ------ | ------ |
219
+ | `value` | `T` |
227
220
 
228
221
  ### Returns
229
222
 
230
223
  `T` & `TZod` \| `undefined`
231
224
 
232
225
  ```ts
233
- <T>(value, assert): T & TZod;
226
+ <T>(value: T, assert: ZodFactoryConfig): T & TZod;
234
227
  ```
235
228
 
236
229
  ### Type Parameters
237
230
 
238
- ### T
239
-
240
- `T`
231
+ | Type Parameter |
232
+ | ------ |
233
+ | `T` |
241
234
 
242
235
  ### Parameters
243
236
 
244
- ### value
245
-
246
- `T`
247
-
248
- ### assert
249
-
250
- [`ZodFactoryConfig`](#../type-aliases/ZodFactoryConfig)
237
+ | Parameter | Type |
238
+ | ------ | ------ |
239
+ | `value` | `T` |
240
+ | `assert` | [`ZodFactoryConfig`](#../type-aliases/ZodFactoryConfig) |
251
241
 
252
242
  ### Returns
253
243
 
@@ -260,44 +250,42 @@ A function that validates and narrows the type of a value
260
250
  ***
261
251
 
262
252
  ```ts
263
- function zodIsFactory<TZod>(zod): <T>(value) => value is T & TZod;
253
+ function zodIsFactory<TZod>(zod: ZodType<TZod>): <T>(value: T) => value is T & TZod;
264
254
  ```
265
255
 
266
256
  Creates a type guard function that checks if a value matches a zod schema.
267
257
 
268
258
  ## Type Parameters
269
259
 
270
- ### TZod
271
-
272
- `TZod`
260
+ | Type Parameter |
261
+ | ------ |
262
+ | `TZod` |
273
263
 
274
264
  ## Parameters
275
265
 
276
- ### zod
277
-
278
- `ZodType`\<`TZod`\>
279
-
280
- The zod schema to validate against
266
+ | Parameter | Type | Description |
267
+ | ------ | ------ | ------ |
268
+ | `zod` | `ZodType`\<`TZod`\> | The zod schema to validate against |
281
269
 
282
270
  ## Returns
283
271
 
284
272
  A type guard function that returns true if the value passes validation
285
273
 
286
274
  ```ts
287
- <T>(value): value is T & TZod;
275
+ <T>(value: T): value is T & TZod;
288
276
  ```
289
277
 
290
278
  ### Type Parameters
291
279
 
292
- ### T
293
-
294
- `T`
280
+ | Type Parameter |
281
+ | ------ |
282
+ | `T` |
295
283
 
296
284
  ### Parameters
297
285
 
298
- ### value
299
-
300
- `T`
286
+ | Parameter | Type |
287
+ | ------ | ------ |
288
+ | `value` | `T` |
301
289
 
302
290
  ### Returns
303
291
 
@@ -310,9 +298,9 @@ A type guard function that returns true if the value passes validation
310
298
  ***
311
299
 
312
300
  ```ts
313
- function zodToAsyncFactory<TZod>(zod, name): {
314
- <T> (value): Promise<T & TZod | undefined>;
315
- <T> (value, assert): Promise<T & TZod>;
301
+ function zodToAsyncFactory<TZod>(zod: ZodType<TZod>, name: string): {
302
+ <T> (value: T): Promise<T & TZod | undefined>;
303
+ <T> (value: T, assert: ZodFactoryConfig): Promise<T & TZod>;
316
304
  };
317
305
  ```
318
306
 
@@ -321,67 +309,57 @@ Provides overloads for optional assertion: without assert config resolves to und
321
309
 
322
310
  ## Type Parameters
323
311
 
324
- ### TZod
325
-
326
- `TZod`
312
+ | Type Parameter |
313
+ | ------ |
314
+ | `TZod` |
327
315
 
328
316
  ## Parameters
329
317
 
330
- ### zod
331
-
332
- `ZodType`\<`TZod`\>
333
-
334
- The zod schema to validate against
335
-
336
- ### name
337
-
338
- `string`
339
-
340
- A name used in error messages for identification
318
+ | Parameter | Type | Description |
319
+ | ------ | ------ | ------ |
320
+ | `zod` | `ZodType`\<`TZod`\> | The zod schema to validate against |
321
+ | `name` | `string` | A name used in error messages for identification |
341
322
 
342
323
  ## Returns
343
324
 
344
325
  An async function that validates and converts a value to the schema type
345
326
 
346
327
  ```ts
347
- <T>(value): Promise<T & TZod | undefined>;
328
+ <T>(value: T): Promise<T & TZod | undefined>;
348
329
  ```
349
330
 
350
331
  ### Type Parameters
351
332
 
352
- ### T
353
-
354
- `T`
333
+ | Type Parameter |
334
+ | ------ |
335
+ | `T` |
355
336
 
356
337
  ### Parameters
357
338
 
358
- ### value
359
-
360
- `T`
339
+ | Parameter | Type |
340
+ | ------ | ------ |
341
+ | `value` | `T` |
361
342
 
362
343
  ### Returns
363
344
 
364
345
  `Promise`\<`T` & `TZod` \| `undefined`\>
365
346
 
366
347
  ```ts
367
- <T>(value, assert): Promise<T & TZod>;
348
+ <T>(value: T, assert: ZodFactoryConfig): Promise<T & TZod>;
368
349
  ```
369
350
 
370
351
  ### Type Parameters
371
352
 
372
- ### T
373
-
374
- `T`
353
+ | Type Parameter |
354
+ | ------ |
355
+ | `T` |
375
356
 
376
357
  ### Parameters
377
358
 
378
- ### value
379
-
380
- `T`
381
-
382
- ### assert
383
-
384
- [`ZodFactoryConfig`](#../type-aliases/ZodFactoryConfig)
359
+ | Parameter | Type |
360
+ | ------ | ------ |
361
+ | `value` | `T` |
362
+ | `assert` | [`ZodFactoryConfig`](#../type-aliases/ZodFactoryConfig) |
385
363
 
386
364
  ### Returns
387
365
 
@@ -394,9 +372,9 @@ An async function that validates and converts a value to the schema type
394
372
  ***
395
373
 
396
374
  ```ts
397
- function zodToFactory<TZod>(zod, name): {
398
- <T> (value): T & TZod | undefined;
399
- <T> (value, assert): T & TZod;
375
+ function zodToFactory<TZod>(zod: ZodType<TZod>, name: string): {
376
+ <T> (value: T): T & TZod | undefined;
377
+ <T> (value: T, assert: ZodFactoryConfig): T & TZod;
400
378
  };
401
379
  ```
402
380
 
@@ -405,67 +383,57 @@ Provides overloads for optional assertion: without assert config returns undefin
405
383
 
406
384
  ## Type Parameters
407
385
 
408
- ### TZod
409
-
410
- `TZod`
386
+ | Type Parameter |
387
+ | ------ |
388
+ | `TZod` |
411
389
 
412
390
  ## Parameters
413
391
 
414
- ### zod
415
-
416
- `ZodType`\<`TZod`\>
417
-
418
- The zod schema to validate against
419
-
420
- ### name
421
-
422
- `string`
423
-
424
- A name used in error messages for identification
392
+ | Parameter | Type | Description |
393
+ | ------ | ------ | ------ |
394
+ | `zod` | `ZodType`\<`TZod`\> | The zod schema to validate against |
395
+ | `name` | `string` | A name used in error messages for identification |
425
396
 
426
397
  ## Returns
427
398
 
428
399
  A function that validates and converts a value to the schema type
429
400
 
430
401
  ```ts
431
- <T>(value): T & TZod | undefined;
402
+ <T>(value: T): T & TZod | undefined;
432
403
  ```
433
404
 
434
405
  ### Type Parameters
435
406
 
436
- ### T
437
-
438
- `T`
407
+ | Type Parameter |
408
+ | ------ |
409
+ | `T` |
439
410
 
440
411
  ### Parameters
441
412
 
442
- ### value
443
-
444
- `T`
413
+ | Parameter | Type |
414
+ | ------ | ------ |
415
+ | `value` | `T` |
445
416
 
446
417
  ### Returns
447
418
 
448
419
  `T` & `TZod` \| `undefined`
449
420
 
450
421
  ```ts
451
- <T>(value, assert): T & TZod;
422
+ <T>(value: T, assert: ZodFactoryConfig): T & TZod;
452
423
  ```
453
424
 
454
425
  ### Type Parameters
455
426
 
456
- ### T
457
-
458
- `T`
427
+ | Type Parameter |
428
+ | ------ |
429
+ | `T` |
459
430
 
460
431
  ### Parameters
461
432
 
462
- ### value
463
-
464
- `T`
465
-
466
- ### assert
467
-
468
- [`ZodFactoryConfig`](#../type-aliases/ZodFactoryConfig)
433
+ | Parameter | Type |
434
+ | ------ | ------ |
435
+ | `value` | `T` |
436
+ | `assert` | [`ZodFactoryConfig`](#../type-aliases/ZodFactoryConfig) |
469
437
 
470
438
  ### Returns
471
439
 
@@ -483,11 +451,9 @@ Configuration object for zod factory functions, providing a name for error messa
483
451
 
484
452
  ## Properties
485
453
 
486
- ### name
487
-
488
- ```ts
489
- name: string;
490
- ```
454
+ | Property | Type |
455
+ | ------ | ------ |
456
+ | <a id="name"></a> `name` | `string` |
491
457
 
492
458
  ### type-aliases
493
459
 
@@ -505,13 +471,10 @@ type AllZodFactories<TType, TName> = { [K in `is${TName}`]: ReturnType<typeof zo
505
471
 
506
472
  ## Type Parameters
507
473
 
508
- ### TType
509
-
510
- `TType`
511
-
512
- ### TName
513
-
514
- `TName` *extends* `string`
474
+ | Type Parameter |
475
+ | ------ |
476
+ | `TType` |
477
+ | `TName` *extends* `string` |
515
478
 
516
479
  ### <a id="ZodFactoryConfig"></a>ZodFactoryConfig
517
480
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xylabs/zod",
3
- "version": "5.0.84",
3
+ "version": "5.0.86",
4
4
  "description": "Base functionality used throughout XY Labs TypeScript/JavaScript libraries",
5
5
  "homepage": "https://xyo.network",
6
6
  "bugs": {
@@ -35,12 +35,12 @@
35
35
  "!**/*.test.*"
36
36
  ],
37
37
  "dependencies": {
38
- "@xylabs/error": "~5.0.84",
39
- "@xylabs/typeof": "~5.0.84"
38
+ "@xylabs/error": "~5.0.86",
39
+ "@xylabs/typeof": "~5.0.86"
40
40
  },
41
41
  "devDependencies": {
42
- "@xylabs/ts-scripts-yarn3": "~7.4.13",
43
- "@xylabs/tsconfig": "~7.4.13",
42
+ "@xylabs/ts-scripts-yarn3": "~7.4.16",
43
+ "@xylabs/tsconfig": "~7.4.16",
44
44
  "typescript": "~5.9.3",
45
45
  "vitest": "^4.0.18",
46
46
  "zod": "^4.3.6"