is-kit 1.14.2 → 1.15.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/README.md CHANGED
@@ -513,7 +513,46 @@ if (result.valid) {
513
513
  coercion and does not depend on a transport or schema format such as HTTP or
514
514
  OpenAPI.
515
515
 
516
- ### 11. Narrow object keys
516
+ ### 11. Validate an exhaustive discriminated union
517
+
518
+ Use `discriminatedUnion<T>()` with `typedStruct` to keep both the branch
519
+ fields and the union coverage aligned with an existing TypeScript type.
520
+
521
+ ```ts
522
+ import { discriminatedUnion, isNumber, oneOfValues, typedStruct } from 'is-kit';
523
+
524
+ type Event =
525
+ | { kind: 'click'; x: number; y: number }
526
+ | { kind: 'scroll'; delta: number };
527
+
528
+ const eventUnion = discriminatedUnion<Event>();
529
+
530
+ export const isEvent = eventUnion('kind', ['click', 'scroll'], {
531
+ click: typedStruct<Extract<Event, { kind: 'click' }>>()({
532
+ kind: oneOfValues('click'),
533
+ x: isNumber,
534
+ y: isNumber
535
+ }),
536
+ scroll: typedStruct<Extract<Event, { kind: 'scroll' }>>()({
537
+ kind: oneOfValues('scroll'),
538
+ delta: isNumber
539
+ })
540
+ });
541
+ ```
542
+
543
+ The value tuple and object keys must each exactly match the union's
544
+ discriminant values, so adding or removing an `Event` member produces a type
545
+ error until both are updated. The tuple makes finite coverage explicit, so
546
+ broad `string`, `number`, and `symbol` discriminants and infinite
547
+ template-literal types are rejected. Boolean branches use the `true` and
548
+ `false` object keys, which is useful for `Result` types with an `ok` field.
549
+ Discriminants that would coerce to the same object key, such as `1` and `'1'`,
550
+ are rejected because they cannot be represented as separate branches.
551
+ For a `__proto__` discriminant, write the branch as `['__proto__']: guard` (or
552
+ use a null-prototype map); the uncomputed object-literal form changes the
553
+ object's prototype instead of creating a branch entry.
554
+
555
+ ### 12. Narrow object keys
517
556
 
518
557
  Use key helpers when the important part of a value is one property.
519
558
 
@@ -630,7 +669,7 @@ The library is organized around a few small building blocks:
630
669
 
631
670
  - **Primitives**: `isString`, `isNumber`, `isBoolean`, `isInteger`, ...
632
671
  - **Composition**: `define`, `and`, `andAll`, `or`, `not`, `oneOf`
633
- - **Object shapes**: `struct`, `optionalKey`, `hasKey`, `hasKeys`, `narrowKeyTo`, `refineKey`, `refineDefinedKey`, `refineIndex`
672
+ - **Object shapes**: `struct`, `typedStruct`, `discriminatedUnion`, `optionalKey`, `hasKey`, `hasKeys`, `narrowKeyTo`, `refineKey`, `refineDefinedKey`, `refineIndex`
634
673
  - **Collections**: `arrayOf`, `nonEmptyArrayOf`, `tupleOf`, `setOf`, `mapOf`, `recordOf`
635
674
  - **Literals**: `oneOfValues`, `equals`, `equalsBy`, `equalsKey`
636
675
  - **Nullish handling**: `isNil`, `isNotNil`, `nullable`, `nonNull`, `nullish`, `optional`, `required`
@@ -700,3 +739,13 @@ Requires Node 22.22.0 and pnpm 11.2.2.
700
739
  See `DEVELOPER.md` for setup details and `CONTRIBUTE.md` for contribution workflow.
701
740
 
702
741
  Pick a guard, compose it, and ship with confidence 🚀
742
+
743
+ ## Star History
744
+
745
+ <a href="https://www.star-history.com/?repos=nyaomaru%2Fis-kit&type=date&legend=top-left">
746
+ <picture>
747
+ <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=nyaomaru/is-kit&type=date&theme=dark&legend=top-left" />
748
+ <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=nyaomaru/is-kit&type=date&legend=top-left" />
749
+ <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=nyaomaru/is-kit&type=date&legend=top-left" />
750
+ </picture>
751
+ </a>