is-kit 1.15.0 โ 1.15.1
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 +74 -15
- package/dist/index.js +8 -2
- package/dist/index.mjs +8 -2
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -27,42 +27,66 @@
|
|
|
27
27
|
|
|
28
28
|
`is-kit` is a lightweight, zero-dependency toolkit for building reusable TypeScript **type guards**.
|
|
29
29
|
|
|
30
|
-
|
|
30
|
+
`is-kit` is not just a collection of `isX` helpers. Its main focus is composing
|
|
31
|
+
small runtime checks into reusable guards while preserving useful TypeScript
|
|
32
|
+
narrowing.
|
|
33
|
+
|
|
34
|
+
It helps you write small `isFoo` functions, compose them into **richer runtime
|
|
35
|
+
checks**, refine properties on values you already know about, and keep
|
|
36
|
+
**TypeScript narrowing** natural inside regular control flow. Use it at runtime
|
|
37
|
+
boundaries when needed, without requiring a schema-first workflow.
|
|
31
38
|
|
|
32
39
|
**Runtime-safe** ๐ก๏ธ, **composable** ๐งฉ, and **ergonomic** โจ without asking you to adopt a heavy schema workflow.
|
|
33
40
|
|
|
34
41
|
- Build and reuse **typed guards**
|
|
35
42
|
- **Compose guards** with `and`, `or`, `not`, `oneOf`
|
|
36
|
-
- **
|
|
43
|
+
- Use `refineKey` to narrow a **child property** while preserving its parent type
|
|
44
|
+
- **Validate object** shapes and collections when that is useful
|
|
37
45
|
- **Parse or assert** `unknown` values without a large schema framework
|
|
38
46
|
|
|
39
|
-
|
|
40
|
-
|
|
47
|
+
<a href="https://is-kit.dev/">
|
|
48
|
+
<img src="docs/public/document_button.png" alt="Documentation Site" width="240">
|
|
49
|
+
</a>
|
|
41
50
|
|
|
42
51
|
> Best for **app-internal narrowing, filtering, and reusable guards**.
|
|
43
52
|
|
|
44
53
|
## ๐ค Why use `is-kit`?
|
|
45
54
|
|
|
46
|
-
|
|
55
|
+
Many TypeScript projects eventually grow a `utils/is.ts`, `libs/is.ts`, or
|
|
56
|
+
`guards.ts` file. It fills with hand-written guards that solve the same
|
|
57
|
+
problems across projects, are tedious to rewrite, and need manual care to keep
|
|
58
|
+
their TypeScript narrowing correct as they evolve.
|
|
47
59
|
|
|
48
|
-
`is-kit`
|
|
60
|
+
`is-kit` exists to make those guards reusable, composable, and easier to
|
|
61
|
+
maintain. The goal is not to replace every validation library; it is to make
|
|
62
|
+
reusable TypeScript type guards easier to build, compose, and maintain.
|
|
63
|
+
|
|
64
|
+
It is a good fit when you want to:
|
|
49
65
|
|
|
50
66
|
- **write reusable `isX`** functions instead of one-off inline checks
|
|
51
67
|
- keep runtime validation **lightweight and dependency-free**
|
|
52
68
|
- **narrow values directly** in `if`, `filter`, and other TypeScript control flow
|
|
53
|
-
- **compose validation logic** from small guards
|
|
69
|
+
- **compose validation logic** from small guards, including property refinements
|
|
70
|
+
|
|
71
|
+
If you only need a few standalone `isX` checks, a smaller type-check utility
|
|
72
|
+
may be simpler. `is-kit` becomes useful when those checks need to be composed,
|
|
73
|
+
refined, and reused across your application while preserving TypeScript
|
|
74
|
+
narrowing.
|
|
54
75
|
|
|
55
|
-
|
|
76
|
+
Schema validators such as Zod, Valibot, and ArkType often optimize for a
|
|
77
|
+
different workflow. They may be a better fit when you mainly want:
|
|
56
78
|
|
|
57
79
|
- rich, structured validation errors
|
|
58
80
|
- schema-first workflows
|
|
59
81
|
- data transformation pipelines
|
|
60
82
|
|
|
61
|
-
|
|
83
|
+
`is-kit` is aimed at reusable runtime predicates that behave naturally as
|
|
84
|
+
TypeScript type guards. The approaches can also be used together: use a schema
|
|
85
|
+
validator where its parsing model helps, and compose `is-kit` guards wherever
|
|
86
|
+
ordinary narrowing and reusable predicates are the better fit.
|
|
62
87
|
|
|
63
|
-
`is-kit` is meant to take the
|
|
64
|
-
|
|
65
|
-
> Grab a coffee โ and let `is-kit` handle the repetitive part.
|
|
88
|
+
`is-kit` is meant to take the repetitive part out of writing guards while still
|
|
89
|
+
feeling like normal TypeScript.
|
|
66
90
|
|
|
67
91
|
## ๐ฅ Install
|
|
68
92
|
|
|
@@ -107,7 +131,43 @@ import { and, define, or } from 'jsr:@nyaomaru/is-kit';
|
|
|
107
131
|
|
|
108
132
|
## โจ Quick Start
|
|
109
133
|
|
|
110
|
-
Start
|
|
134
|
+
Start by composing small guards.
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
import { and, isNumber, isString, or, predicateToRefine } from 'is-kit';
|
|
138
|
+
|
|
139
|
+
const isId = or(isString, isNumber);
|
|
140
|
+
|
|
141
|
+
const isPositiveNumber = and(
|
|
142
|
+
isNumber,
|
|
143
|
+
predicateToRefine<number>((value) => value > 0)
|
|
144
|
+
);
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
You can also refine one property of an already-typed parent value.
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
import { isString, refineKey } from 'is-kit';
|
|
151
|
+
|
|
152
|
+
type Item = {
|
|
153
|
+
value: string | number;
|
|
154
|
+
id: number;
|
|
155
|
+
};
|
|
156
|
+
|
|
157
|
+
const hasStringValue = refineKey('value', isString);
|
|
158
|
+
|
|
159
|
+
declare const items: Item[];
|
|
160
|
+
|
|
161
|
+
const textItems = items.filter(hasStringValue);
|
|
162
|
+
// Array<Item & { value: string }>
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
The original `Item` type is preserved while its checked `value` property is
|
|
166
|
+
narrowed. This lets a reusable guard carry child narrowing back to the parent
|
|
167
|
+
through `filter`, `find`, and control flow.
|
|
168
|
+
|
|
169
|
+
For an `unknown` value at a runtime boundary, build an object guard and parse
|
|
170
|
+
it.
|
|
111
171
|
|
|
112
172
|
```ts
|
|
113
173
|
import { isNumber, isString, optionalKey, safeParse, struct } from 'is-kit';
|
|
@@ -522,8 +582,7 @@ fields and the union coverage aligned with an existing TypeScript type.
|
|
|
522
582
|
import { discriminatedUnion, isNumber, oneOfValues, typedStruct } from 'is-kit';
|
|
523
583
|
|
|
524
584
|
type Event =
|
|
525
|
-
|
|
526
|
-
| { kind: 'scroll'; delta: number };
|
|
585
|
+
{ kind: 'click'; x: number; y: number } | { kind: 'scroll'; delta: number };
|
|
527
586
|
|
|
528
587
|
const eventUnion = discriminatedUnion<Event>();
|
|
529
588
|
|
package/dist/index.js
CHANGED
|
@@ -529,6 +529,7 @@ const isNotNil = (value) => value !== null && value !== void 0;
|
|
|
529
529
|
const isPrimitive = or(isString, isNumberPrimitive, isBoolean, isBigInt, isSymbol, isUndefined, isNull);
|
|
530
530
|
//#endregion
|
|
531
531
|
//#region src/utils/guard-collections.ts
|
|
532
|
+
const arrayValues = Array.prototype.values;
|
|
532
533
|
const mapEntries = Map.prototype.entries;
|
|
533
534
|
const setValues = Set.prototype.values;
|
|
534
535
|
const everyIterableValue = (values, predicate) => {
|
|
@@ -550,6 +551,11 @@ const everyKeyValueEntry = (entries, predicate) => {
|
|
|
550
551
|
*/
|
|
551
552
|
const everyArrayValue = (values, predicate) => everyIterableValue(values, predicate);
|
|
552
553
|
/**
|
|
554
|
+
* Checks built-in Array data without invoking an instance-provided iterator.
|
|
555
|
+
* WHY: An Array subclass or instance may override its public iterator and throw.
|
|
556
|
+
*/
|
|
557
|
+
const everyBrandedArrayValue = (values, predicate) => everyIterableValue(arrayValues.call(values), predicate);
|
|
558
|
+
/**
|
|
553
559
|
* Checks whether a tuple matches the provided element predicates in order.
|
|
554
560
|
*
|
|
555
561
|
* @deprecated Use `tupleOf` for a narrowing guard or compare the tuple length
|
|
@@ -618,7 +624,7 @@ const everyOwnEnumerableEntry = (values, keyPredicate, valuePredicate) => everyI
|
|
|
618
624
|
* @returns Predicate narrowing to a readonly array of the guarded element type.
|
|
619
625
|
*/
|
|
620
626
|
function arrayOf(elementGuard) {
|
|
621
|
-
return define((input) => Array.isArray(input) &&
|
|
627
|
+
return define((input) => Array.isArray(input) && everyBrandedArrayValue(input, elementGuard));
|
|
622
628
|
}
|
|
623
629
|
/**
|
|
624
630
|
* Validates a non-empty array where every element satisfies the provided guard.
|
|
@@ -627,7 +633,7 @@ function arrayOf(elementGuard) {
|
|
|
627
633
|
* @returns Predicate narrowing to a readonly non-empty array of the guarded element type.
|
|
628
634
|
*/
|
|
629
635
|
function nonEmptyArrayOf(elementGuard) {
|
|
630
|
-
return define((input) => Array.isArray(input) && input.length > 0 &&
|
|
636
|
+
return define((input) => Array.isArray(input) && input.length > 0 && everyBrandedArrayValue(input, elementGuard));
|
|
631
637
|
}
|
|
632
638
|
//#endregion
|
|
633
639
|
//#region src/core/combinators/discriminated-union.ts
|
package/dist/index.mjs
CHANGED
|
@@ -528,6 +528,7 @@ const isNotNil = (value) => value !== null && value !== void 0;
|
|
|
528
528
|
const isPrimitive = or(isString, isNumberPrimitive, isBoolean, isBigInt, isSymbol, isUndefined, isNull);
|
|
529
529
|
//#endregion
|
|
530
530
|
//#region src/utils/guard-collections.ts
|
|
531
|
+
const arrayValues = Array.prototype.values;
|
|
531
532
|
const mapEntries = Map.prototype.entries;
|
|
532
533
|
const setValues = Set.prototype.values;
|
|
533
534
|
const everyIterableValue = (values, predicate) => {
|
|
@@ -549,6 +550,11 @@ const everyKeyValueEntry = (entries, predicate) => {
|
|
|
549
550
|
*/
|
|
550
551
|
const everyArrayValue = (values, predicate) => everyIterableValue(values, predicate);
|
|
551
552
|
/**
|
|
553
|
+
* Checks built-in Array data without invoking an instance-provided iterator.
|
|
554
|
+
* WHY: An Array subclass or instance may override its public iterator and throw.
|
|
555
|
+
*/
|
|
556
|
+
const everyBrandedArrayValue = (values, predicate) => everyIterableValue(arrayValues.call(values), predicate);
|
|
557
|
+
/**
|
|
552
558
|
* Checks whether a tuple matches the provided element predicates in order.
|
|
553
559
|
*
|
|
554
560
|
* @deprecated Use `tupleOf` for a narrowing guard or compare the tuple length
|
|
@@ -617,7 +623,7 @@ const everyOwnEnumerableEntry = (values, keyPredicate, valuePredicate) => everyI
|
|
|
617
623
|
* @returns Predicate narrowing to a readonly array of the guarded element type.
|
|
618
624
|
*/
|
|
619
625
|
function arrayOf(elementGuard) {
|
|
620
|
-
return define((input) => Array.isArray(input) &&
|
|
626
|
+
return define((input) => Array.isArray(input) && everyBrandedArrayValue(input, elementGuard));
|
|
621
627
|
}
|
|
622
628
|
/**
|
|
623
629
|
* Validates a non-empty array where every element satisfies the provided guard.
|
|
@@ -626,7 +632,7 @@ function arrayOf(elementGuard) {
|
|
|
626
632
|
* @returns Predicate narrowing to a readonly non-empty array of the guarded element type.
|
|
627
633
|
*/
|
|
628
634
|
function nonEmptyArrayOf(elementGuard) {
|
|
629
|
-
return define((input) => Array.isArray(input) && input.length > 0 &&
|
|
635
|
+
return define((input) => Array.isArray(input) && input.length > 0 && everyBrandedArrayValue(input, elementGuard));
|
|
630
636
|
}
|
|
631
637
|
//#endregion
|
|
632
638
|
//#region src/core/combinators/discriminated-union.ts
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "is-kit",
|
|
3
|
-
"version": "1.15.
|
|
3
|
+
"version": "1.15.1",
|
|
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",
|
|
@@ -62,14 +62,14 @@
|
|
|
62
62
|
"packageManager": "pnpm@11.2.2",
|
|
63
63
|
"devDependencies": {
|
|
64
64
|
"@types/jest": "^30.0.0",
|
|
65
|
-
"jest": "^30.
|
|
66
|
-
"lefthook": "^2.1.
|
|
67
|
-
"oxfmt": "^0.
|
|
68
|
-
"oxlint": "^1.
|
|
69
|
-
"ts-jest": "^29.4.
|
|
65
|
+
"jest": "^30.5.2",
|
|
66
|
+
"lefthook": "^2.1.14",
|
|
67
|
+
"oxfmt": "^0.71.0",
|
|
68
|
+
"oxlint": "^1.86.0",
|
|
69
|
+
"ts-jest": "^29.4.14",
|
|
70
70
|
"tsd": "^0.33.0",
|
|
71
71
|
"tsdown": "^0.23.0",
|
|
72
|
-
"typedoc": "^0.28.
|
|
72
|
+
"typedoc": "^0.28.20",
|
|
73
73
|
"typescript": "^6.0.3"
|
|
74
74
|
},
|
|
75
75
|
"tsd": {
|