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 CHANGED
@@ -396,7 +396,37 @@ const isConfig = struct({
396
396
  });
397
397
  ```
398
398
 
399
- `optionalKey(guard)` means the property may be missing.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "is-kit",
3
- "version": "1.16.5",
3
+ "version": "1.16.6",
4
4
  "description": "Zero-dependency TypeScript runtime validation toolkit for composable type guards and natural type narrowing.",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",