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 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
- - [Use is-kit with the TypeScript Compiler API](https://is-kit.dev/guides/typescript-compiler-api)
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 hasIdentifierExpression = refineKey('expression', ts.isIdentifier);
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 hasCallInitializer = refineDefinedKey(
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 hasStringFirstArgument = refineIndex(0, ts.isStringLiteral);
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 hasIdentifierExpression = refineKey('expression', ts.isIdentifier);
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 hasCallInitializer = refineDefinedKey(
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 hasStringFirstArgument = refineIndex(0, ts.isStringLiteral);
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "is-kit",
3
- "version": "1.14.1",
3
+ "version": "1.14.2",
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",