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 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>;
@@ -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: Guard<null | undefined>;
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 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>;
@@ -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: Guard<null | undefined>;
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) => ArrayBuffer.isView(value) && !isDataView(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 allowWhen((value) => value === null, fn);
329
+ return (value) => value === null || fn(value);
328
330
  }
329
331
  function nonNull(fn) {
330
- return requireWhen((value) => value === null, fn);
332
+ return (value) => value !== null && fn(value);
331
333
  }
332
334
  function nullish(fn) {
333
- return allowWhen((value) => value == null, fn);
335
+ return (value) => value === null || value === void 0 || fn(value);
334
336
  }
335
337
  function optional(fn) {
336
- return allowWhen((value) => value === void 0, fn);
338
+ return (value) => value === void 0 || fn(value);
337
339
  }
338
340
  function required(fn) {
339
- return requireWhen((value) => value === void 0, fn);
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 = or(isNull, isUndefined);
395
- var isNotNil = (value) => !isNil(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) => ArrayBuffer.isView(value) && !isDataView(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 allowWhen((value) => value === null, fn);
221
+ return (value) => value === null || fn(value);
220
222
  }
221
223
  function nonNull(fn) {
222
- return requireWhen((value) => value === null, fn);
224
+ return (value) => value !== null && fn(value);
223
225
  }
224
226
  function nullish(fn) {
225
- return allowWhen((value) => value == null, fn);
227
+ return (value) => value === null || value === void 0 || fn(value);
226
228
  }
227
229
  function optional(fn) {
228
- return allowWhen((value) => value === void 0, fn);
230
+ return (value) => value === void 0 || fn(value);
229
231
  }
230
232
  function required(fn) {
231
- return requireWhen((value) => value === void 0, fn);
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 = or(isNull, isUndefined);
287
- var isNotNil = (value) => !isNil(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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "is-kit",
3
- "version": "1.14.0",
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",