is-kit 1.14.0 → 1.14.2
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 +38 -1
- package/dist/index.d.mts +4 -8
- package/dist/index.d.ts +4 -8
- package/dist/index.js +12 -10
- package/dist/index.mjs +12 -10
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -135,6 +135,23 @@ This is the core idea of `is-kit`:
|
|
|
135
135
|
2. Compose them.
|
|
136
136
|
3. Reuse them anywhere TypeScript narrowing matters.
|
|
137
137
|
|
|
138
|
+
## ESLint integration
|
|
139
|
+
|
|
140
|
+
[`eslint-plugin-is-kit`](https://github.com/nyaomaru/eslint-plugin-is-kit)
|
|
141
|
+
detects ambiguous or redundant array predicates and can suggest reusable
|
|
142
|
+
is-kit guards when they preserve runtime behavior and useful narrowing.
|
|
143
|
+
|
|
144
|
+
```ts
|
|
145
|
+
values.filter(Boolean); // May also remove "", 0, false, and NaN.
|
|
146
|
+
values.filter(isNotNil); // Removes only null and undefined.
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
```sh
|
|
150
|
+
pnpm add -D eslint-plugin-is-kit
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
See the [plugin setup and rule reference](https://github.com/nyaomaru/eslint-plugin-is-kit#readme).
|
|
154
|
+
|
|
138
155
|
## 🧭 Guard Composition Guide
|
|
139
156
|
|
|
140
157
|
When writing reusable guards with `is-kit`, start from the library primitives:
|
|
@@ -375,11 +392,25 @@ needs additional narrowing.
|
|
|
375
392
|
```ts
|
|
376
393
|
import { isString, refineDefinedKey, refineIndex, refineKey } from 'is-kit';
|
|
377
394
|
|
|
395
|
+
type Item = {
|
|
396
|
+
readonly value: string | number;
|
|
397
|
+
readonly label?: string | number;
|
|
398
|
+
};
|
|
399
|
+
|
|
378
400
|
const hasStringValue = refineKey('value', isString);
|
|
379
401
|
const hasDefinedStringLabel = refineDefinedKey('label', isString);
|
|
380
402
|
const hasStringAtZero = refineIndex(0, isString);
|
|
403
|
+
|
|
404
|
+
declare const items: readonly Item[];
|
|
405
|
+
const textItems = items.filter(hasStringValue);
|
|
406
|
+
// Array<Item & Record<'value', string>>
|
|
381
407
|
```
|
|
382
408
|
|
|
409
|
+
The important part is reusable parent narrowing: the predicate retains both
|
|
410
|
+
the original `Item` type and the checked property type through `filter`,
|
|
411
|
+
`find`, and control-flow branches without a handwritten intersection
|
|
412
|
+
annotation.
|
|
413
|
+
|
|
383
414
|
- `refineKey` refines one required property using normal property access.
|
|
384
415
|
- `refineDefinedKey` returns `false` for a missing or `undefined` property.
|
|
385
416
|
- `refineIndex` returns `false` for an out-of-bounds, sparse, or `undefined`
|
|
@@ -392,6 +423,11 @@ numeric property.
|
|
|
392
423
|
Each key or index must identify one concrete runtime location. This keeps one
|
|
393
424
|
successful lookup from incorrectly narrowing multiple properties.
|
|
394
425
|
|
|
426
|
+
See [Refine properties on existing TypeScript
|
|
427
|
+
types](https://is-kit.dev/guides/refine-properties-on-existing-types) for
|
|
428
|
+
required, optional, indexed, nested, and literal examples. The TypeScript
|
|
429
|
+
Compiler API is one advanced application of this generic pattern.
|
|
430
|
+
|
|
395
431
|
### 8. Handle null and undefined explicitly
|
|
396
432
|
|
|
397
433
|
Use the nullish helpers to say exactly what is allowed.
|
|
@@ -642,7 +678,8 @@ For detailed API pages and more examples, see:
|
|
|
642
678
|
|
|
643
679
|
- [Practical guides](https://is-kit.dev/guides)
|
|
644
680
|
- [Keep hand-written type guards in sync with TypeScript types](https://is-kit.dev/guides/keep-type-guards-in-sync)
|
|
645
|
-
- [
|
|
681
|
+
- [Refine properties on existing TypeScript types](https://is-kit.dev/guides/refine-properties-on-existing-types)
|
|
682
|
+
- [Advanced property refinement with the TypeScript Compiler API](https://is-kit.dev/guides/typescript-compiler-api)
|
|
646
683
|
- [Validate unknown without a schema library](https://is-kit.dev/guides/validate-unknown-without-schema-library)
|
|
647
684
|
- [API reference](https://is-kit.dev/api-reference)
|
|
648
685
|
- [Documentation home](https://is-kit.dev/)
|
package/dist/index.d.mts
CHANGED
|
@@ -227,7 +227,7 @@ declare function narrowKeyTo<A, const K extends keyof A & PropertyKey>(guard: Gu
|
|
|
227
227
|
* @param refinement Refinement applied to the property value.
|
|
228
228
|
* @returns Refinement that preserves the parent type and narrows the property.
|
|
229
229
|
* @example
|
|
230
|
-
* const
|
|
230
|
+
* const hasStringValue = refineKey('value', isString);
|
|
231
231
|
*/
|
|
232
232
|
declare function refineKey<const K extends PropertyKey, PropertyInput, PropertyOutput extends PropertyInput>(key: K & SinglePropertyKey<K>, refinement: Refinement<PropertyInput, PropertyOutput>): <ObjectType extends Record<K, PropertyInput>>(value: ObjectType) => value is ObjectType & Record<K, PropertyOutput>;
|
|
233
233
|
/**
|
|
@@ -236,10 +236,7 @@ declare function refineKey<const K extends PropertyKey, PropertyInput, PropertyO
|
|
|
236
236
|
* @param refinement Refinement applied only to a defined property value.
|
|
237
237
|
* @returns Refinement that requires and narrows the property.
|
|
238
238
|
* @example
|
|
239
|
-
* const
|
|
240
|
-
* 'initializer',
|
|
241
|
-
* ts.isCallExpression
|
|
242
|
-
* );
|
|
239
|
+
* const hasDefinedStringLabel = refineDefinedKey('label', isString);
|
|
243
240
|
*/
|
|
244
241
|
declare function refineDefinedKey<const K extends PropertyKey, PropertyInput, PropertyOutput extends PropertyInput>(key: K & SinglePropertyKey<K>, refinement: Refinement<PropertyInput, PropertyOutput>): <ObjectType extends Partial<Record<K, PropertyInput | undefined>>>(value: ObjectType) => value is ObjectType & Record<K, Exclude<PropertyOutput, undefined>>;
|
|
245
242
|
/**
|
|
@@ -248,7 +245,7 @@ declare function refineDefinedKey<const K extends PropertyKey, PropertyInput, Pr
|
|
|
248
245
|
* @param refinement Refinement applied only to a defined element.
|
|
249
246
|
* @returns Refinement that narrows the selected index.
|
|
250
247
|
* @example
|
|
251
|
-
* const
|
|
248
|
+
* const hasStringAtZero = refineIndex(0, isString);
|
|
252
249
|
*/
|
|
253
250
|
declare function refineIndex<const Index extends number, ElementInput, ElementOutput extends ElementInput>(index: ArrayIndex<Index>, refinement: Refinement<ElementInput, ElementOutput>): Refinement<readonly ElementInput[], readonly ElementInput[] & {
|
|
254
251
|
readonly [K in Index]: Exclude<ElementOutput, undefined>;
|
|
@@ -566,9 +563,8 @@ declare const isNull: Predicate<null>;
|
|
|
566
563
|
* isNil(null); // true
|
|
567
564
|
* isNil(undefined); // true
|
|
568
565
|
* isNil(0); // false
|
|
569
|
-
* @see or
|
|
570
566
|
*/
|
|
571
|
-
declare const isNil:
|
|
567
|
+
declare const isNil: (value: unknown) => value is null | undefined;
|
|
572
568
|
/**
|
|
573
569
|
* Checks whether a value is neither `null` nor `undefined`.
|
|
574
570
|
*
|
package/dist/index.d.ts
CHANGED
|
@@ -227,7 +227,7 @@ declare function narrowKeyTo<A, const K extends keyof A & PropertyKey>(guard: Gu
|
|
|
227
227
|
* @param refinement Refinement applied to the property value.
|
|
228
228
|
* @returns Refinement that preserves the parent type and narrows the property.
|
|
229
229
|
* @example
|
|
230
|
-
* const
|
|
230
|
+
* const hasStringValue = refineKey('value', isString);
|
|
231
231
|
*/
|
|
232
232
|
declare function refineKey<const K extends PropertyKey, PropertyInput, PropertyOutput extends PropertyInput>(key: K & SinglePropertyKey<K>, refinement: Refinement<PropertyInput, PropertyOutput>): <ObjectType extends Record<K, PropertyInput>>(value: ObjectType) => value is ObjectType & Record<K, PropertyOutput>;
|
|
233
233
|
/**
|
|
@@ -236,10 +236,7 @@ declare function refineKey<const K extends PropertyKey, PropertyInput, PropertyO
|
|
|
236
236
|
* @param refinement Refinement applied only to a defined property value.
|
|
237
237
|
* @returns Refinement that requires and narrows the property.
|
|
238
238
|
* @example
|
|
239
|
-
* const
|
|
240
|
-
* 'initializer',
|
|
241
|
-
* ts.isCallExpression
|
|
242
|
-
* );
|
|
239
|
+
* const hasDefinedStringLabel = refineDefinedKey('label', isString);
|
|
243
240
|
*/
|
|
244
241
|
declare function refineDefinedKey<const K extends PropertyKey, PropertyInput, PropertyOutput extends PropertyInput>(key: K & SinglePropertyKey<K>, refinement: Refinement<PropertyInput, PropertyOutput>): <ObjectType extends Partial<Record<K, PropertyInput | undefined>>>(value: ObjectType) => value is ObjectType & Record<K, Exclude<PropertyOutput, undefined>>;
|
|
245
242
|
/**
|
|
@@ -248,7 +245,7 @@ declare function refineDefinedKey<const K extends PropertyKey, PropertyInput, Pr
|
|
|
248
245
|
* @param refinement Refinement applied only to a defined element.
|
|
249
246
|
* @returns Refinement that narrows the selected index.
|
|
250
247
|
* @example
|
|
251
|
-
* const
|
|
248
|
+
* const hasStringAtZero = refineIndex(0, isString);
|
|
252
249
|
*/
|
|
253
250
|
declare function refineIndex<const Index extends number, ElementInput, ElementOutput extends ElementInput>(index: ArrayIndex<Index>, refinement: Refinement<ElementInput, ElementOutput>): Refinement<readonly ElementInput[], readonly ElementInput[] & {
|
|
254
251
|
readonly [K in Index]: Exclude<ElementOutput, undefined>;
|
|
@@ -566,9 +563,8 @@ declare const isNull: Predicate<null>;
|
|
|
566
563
|
* isNil(null); // true
|
|
567
564
|
* isNil(undefined); // true
|
|
568
565
|
* isNil(0); // false
|
|
569
|
-
* @see or
|
|
570
566
|
*/
|
|
571
|
-
declare const isNil:
|
|
567
|
+
declare const isNil: (value: unknown) => value is null | undefined;
|
|
572
568
|
/**
|
|
573
569
|
* Checks whether a value is neither `null` nor `undefined`.
|
|
574
570
|
*
|
package/dist/index.js
CHANGED
|
@@ -154,6 +154,10 @@ var arrayBufferByteLength = getIntrinsicGetter(
|
|
|
154
154
|
"byteLength"
|
|
155
155
|
);
|
|
156
156
|
var dataViewBuffer = getIntrinsicGetter(DataView.prototype, "buffer");
|
|
157
|
+
var typedArrayName = Object.getOwnPropertyDescriptor(
|
|
158
|
+
Object.getPrototypeOf(Uint8Array.prototype),
|
|
159
|
+
Symbol.toStringTag
|
|
160
|
+
)?.get;
|
|
157
161
|
var defineOptionalInstanceGuard = (constructor) => constructor === void 0 ? define(() => false) : define(
|
|
158
162
|
(value) => typeof constructor === "function" && value instanceof constructor
|
|
159
163
|
);
|
|
@@ -211,7 +215,7 @@ var isDataView = defineIntrinsicBrandGuard(
|
|
|
211
215
|
(value) => dataViewBuffer.call(value)
|
|
212
216
|
);
|
|
213
217
|
var isTypedArray = define(
|
|
214
|
-
(value) =>
|
|
218
|
+
(value) => typedArrayName?.call(value) !== void 0
|
|
215
219
|
);
|
|
216
220
|
var isError = define(
|
|
217
221
|
(value) => value instanceof Error || getTag(value) === OBJECT_TAG_ERROR
|
|
@@ -321,22 +325,20 @@ function not(fn) {
|
|
|
321
325
|
}
|
|
322
326
|
|
|
323
327
|
// src/core/nullish.ts
|
|
324
|
-
var allowWhen = (acceptedValue, predicate) => (value) => acceptedValue(value) || predicate(value);
|
|
325
|
-
var requireWhen = (rejectedValue, predicate) => (value) => !rejectedValue(value) && predicate(value);
|
|
326
328
|
function nullable(fn) {
|
|
327
|
-
return
|
|
329
|
+
return (value) => value === null || fn(value);
|
|
328
330
|
}
|
|
329
331
|
function nonNull(fn) {
|
|
330
|
-
return
|
|
332
|
+
return (value) => value !== null && fn(value);
|
|
331
333
|
}
|
|
332
334
|
function nullish(fn) {
|
|
333
|
-
return
|
|
335
|
+
return (value) => value === null || value === void 0 || fn(value);
|
|
334
336
|
}
|
|
335
337
|
function optional(fn) {
|
|
336
|
-
return
|
|
338
|
+
return (value) => value === void 0 || fn(value);
|
|
337
339
|
}
|
|
338
340
|
function required(fn) {
|
|
339
|
-
return
|
|
341
|
+
return (value) => value !== void 0 && fn(value);
|
|
340
342
|
}
|
|
341
343
|
|
|
342
344
|
// src/core/parse.ts
|
|
@@ -391,8 +393,8 @@ var isBigInt = define((value) => typeof value === "bigint");
|
|
|
391
393
|
var isSymbol = define((value) => typeof value === "symbol");
|
|
392
394
|
var isUndefined = define((value) => value === void 0);
|
|
393
395
|
var isNull = define((value) => value === null);
|
|
394
|
-
var isNil =
|
|
395
|
-
var isNotNil = (value) =>
|
|
396
|
+
var isNil = (value) => value === null || value === void 0;
|
|
397
|
+
var isNotNil = (value) => value !== null && value !== void 0;
|
|
396
398
|
var isPrimitive = or(
|
|
397
399
|
isString,
|
|
398
400
|
isNumberPrimitive,
|
package/dist/index.mjs
CHANGED
|
@@ -46,6 +46,10 @@ var arrayBufferByteLength = getIntrinsicGetter(
|
|
|
46
46
|
"byteLength"
|
|
47
47
|
);
|
|
48
48
|
var dataViewBuffer = getIntrinsicGetter(DataView.prototype, "buffer");
|
|
49
|
+
var typedArrayName = Object.getOwnPropertyDescriptor(
|
|
50
|
+
Object.getPrototypeOf(Uint8Array.prototype),
|
|
51
|
+
Symbol.toStringTag
|
|
52
|
+
)?.get;
|
|
49
53
|
var defineOptionalInstanceGuard = (constructor) => constructor === void 0 ? define(() => false) : define(
|
|
50
54
|
(value) => typeof constructor === "function" && value instanceof constructor
|
|
51
55
|
);
|
|
@@ -103,7 +107,7 @@ var isDataView = defineIntrinsicBrandGuard(
|
|
|
103
107
|
(value) => dataViewBuffer.call(value)
|
|
104
108
|
);
|
|
105
109
|
var isTypedArray = define(
|
|
106
|
-
(value) =>
|
|
110
|
+
(value) => typedArrayName?.call(value) !== void 0
|
|
107
111
|
);
|
|
108
112
|
var isError = define(
|
|
109
113
|
(value) => value instanceof Error || getTag(value) === OBJECT_TAG_ERROR
|
|
@@ -213,22 +217,20 @@ function not(fn) {
|
|
|
213
217
|
}
|
|
214
218
|
|
|
215
219
|
// src/core/nullish.ts
|
|
216
|
-
var allowWhen = (acceptedValue, predicate) => (value) => acceptedValue(value) || predicate(value);
|
|
217
|
-
var requireWhen = (rejectedValue, predicate) => (value) => !rejectedValue(value) && predicate(value);
|
|
218
220
|
function nullable(fn) {
|
|
219
|
-
return
|
|
221
|
+
return (value) => value === null || fn(value);
|
|
220
222
|
}
|
|
221
223
|
function nonNull(fn) {
|
|
222
|
-
return
|
|
224
|
+
return (value) => value !== null && fn(value);
|
|
223
225
|
}
|
|
224
226
|
function nullish(fn) {
|
|
225
|
-
return
|
|
227
|
+
return (value) => value === null || value === void 0 || fn(value);
|
|
226
228
|
}
|
|
227
229
|
function optional(fn) {
|
|
228
|
-
return
|
|
230
|
+
return (value) => value === void 0 || fn(value);
|
|
229
231
|
}
|
|
230
232
|
function required(fn) {
|
|
231
|
-
return
|
|
233
|
+
return (value) => value !== void 0 && fn(value);
|
|
232
234
|
}
|
|
233
235
|
|
|
234
236
|
// src/core/parse.ts
|
|
@@ -283,8 +285,8 @@ var isBigInt = define((value) => typeof value === "bigint");
|
|
|
283
285
|
var isSymbol = define((value) => typeof value === "symbol");
|
|
284
286
|
var isUndefined = define((value) => value === void 0);
|
|
285
287
|
var isNull = define((value) => value === null);
|
|
286
|
-
var isNil =
|
|
287
|
-
var isNotNil = (value) =>
|
|
288
|
+
var isNil = (value) => value === null || value === void 0;
|
|
289
|
+
var isNotNil = (value) => value !== null && value !== void 0;
|
|
288
290
|
var isPrimitive = or(
|
|
289
291
|
isString,
|
|
290
292
|
isNumberPrimitive,
|
package/package.json
CHANGED