is-kit 1.16.5 → 1.16.6
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/README.md +31 -3
- package/dist/index.d.mts +6 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.js +6 -0
- package/dist/index.mjs +6 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -396,7 +396,37 @@ const isConfig = struct({
|
|
|
396
396
|
});
|
|
397
397
|
```
|
|
398
398
|
|
|
399
|
-
`
|
|
399
|
+
`optional(guard)` and `optionalKey(guard)` answer different questions.
|
|
400
|
+
`optional` is about the value: the key must be there, but it may hold
|
|
401
|
+
`undefined`. `optionalKey` is about the key: it may be missing, but when it is
|
|
402
|
+
there the value must pass the guard. Here is how each one treats `tag` in
|
|
403
|
+
`struct({ id: isNumber, tag: ... })`:
|
|
404
|
+
|
|
405
|
+
| Field schema | `{ id: 1, tag: 'hello' }` | `{ id: 1, tag: undefined }` | `{ id: 1 }` | Inferred `tag` |
|
|
406
|
+
| -------------------------------------- | ------------------------- | --------------------------- | ----------- | --------------------------- |
|
|
407
|
+
| `tag: optional(isString)` | ✅ | ✅ | ❌ | `tag: string \| undefined` |
|
|
408
|
+
| `tag: optionalKey(isString)` | ✅ | ❌ | ✅ | `tag?: string` |
|
|
409
|
+
| `tag: optionalKey(optional(isString))` | ✅ | ✅ | ✅ | `tag?: string \| undefined` |
|
|
410
|
+
|
|
411
|
+
If you come from a schema library where `.optional()` accepts both a missing
|
|
412
|
+
key and `undefined`, the match is `optionalKey(optional(guard))`.
|
|
413
|
+
|
|
414
|
+
The difference shows up with API and JSON payloads. Building an object from a
|
|
415
|
+
maybe-undefined variable keeps the key, and `JSON.stringify` drops it:
|
|
416
|
+
|
|
417
|
+
```ts
|
|
418
|
+
const tag: string | undefined = undefined;
|
|
419
|
+
const payload = { id: 1, tag }; // { id: 1, tag: undefined }, the key is present
|
|
420
|
+
|
|
421
|
+
struct({ id: isNumber, tag: optionalKey(isString) })(payload); // false
|
|
422
|
+
|
|
423
|
+
const received = JSON.parse(JSON.stringify(payload)); // { id: 1 }, the key is gone
|
|
424
|
+
struct({ id: isNumber, tag: optional(isString) })(received); // false
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
So a guard that checks objects you build in code and the same objects after a
|
|
428
|
+
JSON round trip needs `optionalKey(optional(guard))` for fields that may be
|
|
429
|
+
`undefined`.
|
|
400
430
|
|
|
401
431
|
Use `struct(schema, { exact: true })` when extra own enumerable string keys
|
|
402
432
|
should be rejected. Exact mode follows `Object.keys(...)` semantics, so symbol
|
|
@@ -406,8 +436,6 @@ Schemas themselves must use own enumerable string keys. `struct` rejects
|
|
|
406
436
|
symbol-keyed, non-enumerable, and inherited schema fields so its runtime checks
|
|
407
437
|
match the inferred type.
|
|
408
438
|
|
|
409
|
-
If the property must exist but the value may be `undefined`, use `optional(guard)` instead.
|
|
410
|
-
|
|
411
439
|
### 5. Validate arrays, tuples, maps, sets, and records
|
|
412
440
|
|
|
413
441
|
Collection combinators keep your element guards reusable.
|
package/dist/index.d.mts
CHANGED
|
@@ -885,6 +885,12 @@ export declare function typedStruct<T extends object>(): <const S extends TypedS
|
|
|
885
885
|
/**
|
|
886
886
|
* Validates a fixed-length tuple by applying element-wise guards.
|
|
887
887
|
*
|
|
888
|
+
* The input must be a real array (`Array.isArray` check). Array-like objects,
|
|
889
|
+
* strings, null, and undefined are rejected. Length must exactly match the number
|
|
890
|
+
* of guards; on mismatch, no element guards are invoked. Guards run in index order
|
|
891
|
+
* and short-circuit at the first failure. Sparse arrays read holes as `undefined`,
|
|
892
|
+
* so a hole passes only if the guard at that index accepts `undefined`.
|
|
893
|
+
*
|
|
888
894
|
* @param guards Guards corresponding to each tuple position.
|
|
889
895
|
* @returns Predicate that narrows to a readonly tuple of guarded element types.
|
|
890
896
|
*/
|
package/dist/index.d.ts
CHANGED
|
@@ -885,6 +885,12 @@ export declare function typedStruct<T extends object>(): <const S extends TypedS
|
|
|
885
885
|
/**
|
|
886
886
|
* Validates a fixed-length tuple by applying element-wise guards.
|
|
887
887
|
*
|
|
888
|
+
* The input must be a real array (`Array.isArray` check). Array-like objects,
|
|
889
|
+
* strings, null, and undefined are rejected. Length must exactly match the number
|
|
890
|
+
* of guards; on mismatch, no element guards are invoked. Guards run in index order
|
|
891
|
+
* and short-circuit at the first failure. Sparse arrays read holes as `undefined`,
|
|
892
|
+
* so a hole passes only if the guard at that index accepts `undefined`.
|
|
893
|
+
*
|
|
888
894
|
* @param guards Guards corresponding to each tuple position.
|
|
889
895
|
* @returns Predicate that narrows to a readonly tuple of guarded element types.
|
|
890
896
|
*/
|
package/dist/index.js
CHANGED
|
@@ -989,6 +989,12 @@ function typedStruct() {
|
|
|
989
989
|
/**
|
|
990
990
|
* Validates a fixed-length tuple by applying element-wise guards.
|
|
991
991
|
*
|
|
992
|
+
* The input must be a real array (`Array.isArray` check). Array-like objects,
|
|
993
|
+
* strings, null, and undefined are rejected. Length must exactly match the number
|
|
994
|
+
* of guards; on mismatch, no element guards are invoked. Guards run in index order
|
|
995
|
+
* and short-circuit at the first failure. Sparse arrays read holes as `undefined`,
|
|
996
|
+
* so a hole passes only if the guard at that index accepts `undefined`.
|
|
997
|
+
*
|
|
992
998
|
* @param guards Guards corresponding to each tuple position.
|
|
993
999
|
* @returns Predicate that narrows to a readonly tuple of guarded element types.
|
|
994
1000
|
*/
|
package/dist/index.mjs
CHANGED
|
@@ -988,6 +988,12 @@ function typedStruct() {
|
|
|
988
988
|
/**
|
|
989
989
|
* Validates a fixed-length tuple by applying element-wise guards.
|
|
990
990
|
*
|
|
991
|
+
* The input must be a real array (`Array.isArray` check). Array-like objects,
|
|
992
|
+
* strings, null, and undefined are rejected. Length must exactly match the number
|
|
993
|
+
* of guards; on mismatch, no element guards are invoked. Guards run in index order
|
|
994
|
+
* and short-circuit at the first failure. Sparse arrays read holes as `undefined`,
|
|
995
|
+
* so a hole passes only if the guard at that index accepts `undefined`.
|
|
996
|
+
*
|
|
991
997
|
* @param guards Guards corresponding to each tuple position.
|
|
992
998
|
* @returns Predicate that narrows to a readonly tuple of guarded element types.
|
|
993
999
|
*/
|
package/package.json
CHANGED