is-kit 1.14.1 → 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 +3 -6
- package/dist/index.d.ts +3 -6
- 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>;
|
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>;
|
package/package.json
CHANGED