is-kit 1.11.7 → 1.12.0

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
@@ -172,8 +172,23 @@ const isSlug = (value: unknown): value is string =>
172
172
 
173
173
  ### AI agent setup
174
174
 
175
- Add the recommended `is-kit` selection and usage rules to a repository's AI
176
- agent instructions:
175
+ #### Recommended: Codex Marketplace plugin
176
+
177
+ Install the `is-kit` plugin from this repository's Codex Marketplace:
178
+
179
+ ```bash
180
+ codex plugin marketplace add nyaomaru/is-kit
181
+ codex plugin add is-kit@is-kit
182
+ ```
183
+
184
+ This is the primary distribution channel for the `use-is-kit` skill. It gives
185
+ Codex an on-demand workflow for selecting guards, replacing manual runtime
186
+ checks, and validating object boundaries with `is-kit`.
187
+
188
+ #### Compatibility: instruction-only setup
189
+
190
+ For agents that do not support skills or plugins, add the lightweight selection
191
+ and usage rules to the repository's agent instructions:
177
192
 
178
193
  ```bash
179
194
  npx --yes is-kit@latest init-agent
@@ -333,6 +348,8 @@ Use the nullish helpers to say exactly what is allowed.
333
348
 
334
349
  ```ts
335
350
  import {
351
+ isNil,
352
+ isNotNil,
336
353
  isString,
337
354
  nonNull,
338
355
  nullable,
@@ -346,19 +363,19 @@ const isNullishString = nullish(isString);
346
363
  const isOptionalString = optional(isString);
347
364
  const isDefinedString = required(optional(isString));
348
365
  const isNonNullString = nonNull(nullable(isString));
349
- ```
350
-
351
- For a plain "is it `null` or `undefined`?" check, reach for `isNil` instead of
352
- hand-rolling `isNull(x) || isUndefined(x)`:
353
-
354
- ```ts
355
- import { isNil } from 'is-kit';
356
366
 
357
367
  isNil(null); // true
358
368
  isNil(undefined); // true
359
369
  isNil(0); // false
370
+
371
+ const values: Array<string | null | undefined> = ['value', null, undefined];
372
+ const presentValues = values.filter(isNotNil); // string[]
360
373
  ```
361
374
 
375
+ Use `isNil` for a direct nullish check instead of hand-rolling
376
+ `isNull(x) || isUndefined(x)`. Use `isNotNil` for the inverse check or to
377
+ remove nullish values while preserving `Array.prototype.filter` narrowing.
378
+
362
379
  ### 8. Parse or assert unknown input
363
380
 
364
381
  Use `safeParse` when you want a result object, and `assert` when invalid data should stop execution.
@@ -523,11 +540,28 @@ The library is organized around a few small building blocks:
523
540
  - **Object shapes**: `struct`, `optionalKey`, `hasKey`, `hasKeys`, `narrowKeyTo`
524
541
  - **Collections**: `arrayOf`, `nonEmptyArrayOf`, `tupleOf`, `setOf`, `mapOf`, `recordOf`
525
542
  - **Literals**: `oneOfValues`, `equals`, `equalsBy`, `equalsKey`
526
- - **Nullish handling**: `isNil`, `nullable`, `nonNull`, `nullish`, `optional`, `required`
543
+ - **Nullish handling**: `isNil`, `isNotNil`, `nullable`, `nonNull`, `nullish`, `optional`, `required`
527
544
  - **Result helpers**: `safeParse`, `safeParseWith`, `safeJsonParse`, `assert`
528
545
 
529
546
  For the full API list and dedicated pages, use the docs site below.
530
547
 
548
+ ### Public types
549
+
550
+ Start with the primary types for guard authoring, parsing, and schema inference:
551
+
552
+ - `Predicate`, `Guard`, `Refinement`, `Refine`, `ParseResult`, `Primitive`
553
+ - `InferSchema`, `StructOptions`, `TypedStructShape`, `TypedStructFields`
554
+
555
+ Advanced building blocks support reusable wrappers and type-level extensions:
556
+
557
+ - `GuardedOf`, `GuardedWithin`, `OutOfGuards`, `RefineChain`, `ChainResult`
558
+ - `OptionalSchemaField`, `SchemaField`, `Schema`, `NoExtraKeys`
559
+ - `OptionalObjectKeys`, `RequiredObjectKeys`
560
+
561
+ Both groups are supported public API and follow semantic versioning. The
562
+ classification only controls discoverability. `SchemaShape` remains internal
563
+ and is not exported from the package root.
564
+
531
565
  ### v2 migration notice
532
566
 
533
567
  Six low-level utility adapters remain available in v1 for compatibility but are
@@ -559,6 +593,7 @@ Requires Node 22.22.0 and pnpm 11.2.2.
559
593
  - `pnpm build`
560
594
  - `pnpm test`
561
595
  - `pnpm test:types`
596
+ - `pnpm test:package`
562
597
 
563
598
  See `DEVELOPER.md` for setup details and `CONTRIBUTE.md` for contribution workflow.
564
599
 
package/dist/index.d.mts CHANGED
@@ -6,22 +6,33 @@
6
6
  * - Use nullable, optional, or nullish to widen guards for nullish values.
7
7
  * - Use struct or typedStruct for object-shape guards.
8
8
  */
9
+ /** Predicate that accepts an unknown value and narrows it to `T`. */
9
10
  type Predicate<T> = (value: unknown) => value is T;
11
+ /** Refinement that narrows a known input type `A` to its subtype `B`. */
10
12
  type Refinement<A, B extends A> = (value: A) => value is B;
13
+ /** Readability alias for {@link Predicate}. */
11
14
  type Guard<T> = Predicate<T>;
15
+ /** Readability alias for {@link Refinement}. */
12
16
  type Refine<A, B extends A> = Refinement<A, B>;
17
+ /** Validates the ordered refinement types accepted by `andAll`. */
13
18
  type RefineChain<In, T extends readonly unknown[]> = T extends [] ? [] : T extends [Refine<In, infer Next>, ...infer R] ? [Refine<In, Next>, ...RefineChain<Next, Extract<R, readonly unknown[]>>] : never;
19
+ /** Resolves the final narrowed type produced by an ordered refinement chain. */
14
20
  type ChainResult<In, T extends readonly unknown[]> = T extends [] ? In : T extends [Refine<In, infer Next>, ...infer R] ? ChainResult<Next, Extract<R, readonly unknown[]>> : never;
21
+ /** Extracts the union of output types from a readonly guard collection. */
15
22
  type OutOfGuards<T extends readonly Guard<unknown>[]> = T[number] extends Guard<infer U> ? U : never;
23
+ /** Tagged success/failure result containing the value when valid. */
16
24
  type ParseResult<T> = {
17
25
  valid: true;
18
26
  value: T;
19
27
  } | {
20
28
  valid: false;
21
29
  };
30
+ /** Extracts the narrowed output type from a predicate. */
22
31
  type GuardedOf<F> = F extends ((value: unknown) => value is infer G) ? G : never;
32
+ /** Extracts guard outputs that remain assignable to a known input type. */
23
33
  type GuardedWithin<Fs, A> = Extract<Fs extends readonly unknown[] ? GuardedOf<Fs[number]> : never, A>;
24
34
 
35
+ /** Union of JavaScript primitive value types. */
25
36
  type Primitive = string | number | boolean | bigint | symbol | null | undefined;
26
37
 
27
38
  /**
@@ -472,6 +483,20 @@ declare const isNull: Predicate<null>;
472
483
  * @see or
473
484
  */
474
485
  declare const isNil: Guard<null | undefined>;
486
+ /**
487
+ * Checks whether a value is neither `null` nor `undefined`.
488
+ *
489
+ * Narrows the input to `NonNullable<T>`, making it useful for removing nullish
490
+ * values with `Array.prototype.filter`.
491
+ *
492
+ * @param value Value to check.
493
+ * @returns `true` when the value is not nullish.
494
+ * @example
495
+ * const values: Array<string | null | undefined> = ['value', null];
496
+ * const presentValues = values.filter(isNotNil); // string[]
497
+ * @see isNil
498
+ */
499
+ declare const isNotNil: <T>(value: T) => value is NonNullable<T>;
475
500
  /**
476
501
  * Checks whether a value is a JavaScript primitive.
477
502
  *
@@ -782,4 +807,4 @@ declare const everyOwnEnumerableEntry: (values: Record<string, unknown>, keyPred
782
807
  */
783
808
  declare const toBooleanPredicates: <A>(predicates: readonly ((value: A) => boolean)[]) => ReadonlyArray<(value: A) => boolean>;
784
809
 
785
- export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type NoExtraKeys, type OptionalObjectKeys, type OptionalSchemaField, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type RequiredObjectKeys, type Schema, type SchemaField, type StructOptions, type TypedStructFields, type TypedStructShape, and, andAll, arrayOf, assert, define, equals, equalsBy, equalsKey, everyArrayValue, everyMapEntry, everyOwnEnumerableEntry, everySetValue, everyTupleValue, guardIn, hasKey, hasKeys, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFile, isFiniteNumber, isFunction, isInfiniteNumber, isInstanceOf, isInteger, isIterable, isMap, isNaN, isNegative, isNil, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, lazy, mapOf, narrowKeyTo, nonEmptyArrayOf, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeJsonParse, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf, typedStruct };
810
+ export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type NoExtraKeys, type OptionalObjectKeys, type OptionalSchemaField, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type RequiredObjectKeys, type Schema, type SchemaField, type StructOptions, type TypedStructFields, type TypedStructShape, and, andAll, arrayOf, assert, define, equals, equalsBy, equalsKey, everyArrayValue, everyMapEntry, everyOwnEnumerableEntry, everySetValue, everyTupleValue, guardIn, hasKey, hasKeys, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFile, isFiniteNumber, isFunction, isInfiniteNumber, isInstanceOf, isInteger, isIterable, isMap, isNaN, isNegative, isNil, isNotNil, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, lazy, mapOf, narrowKeyTo, nonEmptyArrayOf, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeJsonParse, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf, typedStruct };
package/dist/index.d.ts CHANGED
@@ -6,22 +6,33 @@
6
6
  * - Use nullable, optional, or nullish to widen guards for nullish values.
7
7
  * - Use struct or typedStruct for object-shape guards.
8
8
  */
9
+ /** Predicate that accepts an unknown value and narrows it to `T`. */
9
10
  type Predicate<T> = (value: unknown) => value is T;
11
+ /** Refinement that narrows a known input type `A` to its subtype `B`. */
10
12
  type Refinement<A, B extends A> = (value: A) => value is B;
13
+ /** Readability alias for {@link Predicate}. */
11
14
  type Guard<T> = Predicate<T>;
15
+ /** Readability alias for {@link Refinement}. */
12
16
  type Refine<A, B extends A> = Refinement<A, B>;
17
+ /** Validates the ordered refinement types accepted by `andAll`. */
13
18
  type RefineChain<In, T extends readonly unknown[]> = T extends [] ? [] : T extends [Refine<In, infer Next>, ...infer R] ? [Refine<In, Next>, ...RefineChain<Next, Extract<R, readonly unknown[]>>] : never;
19
+ /** Resolves the final narrowed type produced by an ordered refinement chain. */
14
20
  type ChainResult<In, T extends readonly unknown[]> = T extends [] ? In : T extends [Refine<In, infer Next>, ...infer R] ? ChainResult<Next, Extract<R, readonly unknown[]>> : never;
21
+ /** Extracts the union of output types from a readonly guard collection. */
15
22
  type OutOfGuards<T extends readonly Guard<unknown>[]> = T[number] extends Guard<infer U> ? U : never;
23
+ /** Tagged success/failure result containing the value when valid. */
16
24
  type ParseResult<T> = {
17
25
  valid: true;
18
26
  value: T;
19
27
  } | {
20
28
  valid: false;
21
29
  };
30
+ /** Extracts the narrowed output type from a predicate. */
22
31
  type GuardedOf<F> = F extends ((value: unknown) => value is infer G) ? G : never;
32
+ /** Extracts guard outputs that remain assignable to a known input type. */
23
33
  type GuardedWithin<Fs, A> = Extract<Fs extends readonly unknown[] ? GuardedOf<Fs[number]> : never, A>;
24
34
 
35
+ /** Union of JavaScript primitive value types. */
25
36
  type Primitive = string | number | boolean | bigint | symbol | null | undefined;
26
37
 
27
38
  /**
@@ -472,6 +483,20 @@ declare const isNull: Predicate<null>;
472
483
  * @see or
473
484
  */
474
485
  declare const isNil: Guard<null | undefined>;
486
+ /**
487
+ * Checks whether a value is neither `null` nor `undefined`.
488
+ *
489
+ * Narrows the input to `NonNullable<T>`, making it useful for removing nullish
490
+ * values with `Array.prototype.filter`.
491
+ *
492
+ * @param value Value to check.
493
+ * @returns `true` when the value is not nullish.
494
+ * @example
495
+ * const values: Array<string | null | undefined> = ['value', null];
496
+ * const presentValues = values.filter(isNotNil); // string[]
497
+ * @see isNil
498
+ */
499
+ declare const isNotNil: <T>(value: T) => value is NonNullable<T>;
475
500
  /**
476
501
  * Checks whether a value is a JavaScript primitive.
477
502
  *
@@ -782,4 +807,4 @@ declare const everyOwnEnumerableEntry: (values: Record<string, unknown>, keyPred
782
807
  */
783
808
  declare const toBooleanPredicates: <A>(predicates: readonly ((value: A) => boolean)[]) => ReadonlyArray<(value: A) => boolean>;
784
809
 
785
- export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type NoExtraKeys, type OptionalObjectKeys, type OptionalSchemaField, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type RequiredObjectKeys, type Schema, type SchemaField, type StructOptions, type TypedStructFields, type TypedStructShape, and, andAll, arrayOf, assert, define, equals, equalsBy, equalsKey, everyArrayValue, everyMapEntry, everyOwnEnumerableEntry, everySetValue, everyTupleValue, guardIn, hasKey, hasKeys, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFile, isFiniteNumber, isFunction, isInfiniteNumber, isInstanceOf, isInteger, isIterable, isMap, isNaN, isNegative, isNil, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, lazy, mapOf, narrowKeyTo, nonEmptyArrayOf, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeJsonParse, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf, typedStruct };
810
+ export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type NoExtraKeys, type OptionalObjectKeys, type OptionalSchemaField, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type RequiredObjectKeys, type Schema, type SchemaField, type StructOptions, type TypedStructFields, type TypedStructShape, and, andAll, arrayOf, assert, define, equals, equalsBy, equalsKey, everyArrayValue, everyMapEntry, everyOwnEnumerableEntry, everySetValue, everyTupleValue, guardIn, hasKey, hasKeys, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFile, isFiniteNumber, isFunction, isInfiniteNumber, isInstanceOf, isInteger, isIterable, isMap, isNaN, isNegative, isNil, isNotNil, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, lazy, mapOf, narrowKeyTo, nonEmptyArrayOf, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeJsonParse, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf, typedStruct };
package/dist/index.js CHANGED
@@ -56,6 +56,7 @@ __export(index_exports, {
56
56
  isNaN: () => isNaN,
57
57
  isNegative: () => isNegative,
58
58
  isNil: () => isNil,
59
+ isNotNil: () => isNotNil,
59
60
  isNull: () => isNull,
60
61
  isNumber: () => isNumber,
61
62
  isNumberPrimitive: () => isNumberPrimitive,
@@ -384,6 +385,7 @@ var isSymbol = define((value) => typeof value === "symbol");
384
385
  var isUndefined = define((value) => value === void 0);
385
386
  var isNull = define((value) => value === null);
386
387
  var isNil = or(isNull, isUndefined);
388
+ var isNotNil = (value) => !isNil(value);
387
389
  var isPrimitive = or(
388
390
  isString,
389
391
  isNumberPrimitive,
@@ -608,6 +610,7 @@ function tupleOf(...guards) {
608
610
  isNaN,
609
611
  isNegative,
610
612
  isNil,
613
+ isNotNil,
611
614
  isNull,
612
615
  isNumber,
613
616
  isNumberPrimitive,
package/dist/index.mjs CHANGED
@@ -280,6 +280,7 @@ var isSymbol = define((value) => typeof value === "symbol");
280
280
  var isUndefined = define((value) => value === void 0);
281
281
  var isNull = define((value) => value === null);
282
282
  var isNil = or(isNull, isUndefined);
283
+ var isNotNil = (value) => !isNil(value);
283
284
  var isPrimitive = or(
284
285
  isString,
285
286
  isNumberPrimitive,
@@ -503,6 +504,7 @@ export {
503
504
  isNaN,
504
505
  isNegative,
505
506
  isNil,
507
+ isNotNil,
506
508
  isNull,
507
509
  isNumber,
508
510
  isNumberPrimitive,
@@ -21,6 +21,8 @@ data transformations, or a schema-first workflow.
21
21
  - Use `nullable(guard)`, `optional(guard)`, or `nullish(guard)` when widening an
22
22
  existing guard to accept `null` and/or `undefined`.
23
23
  - Use `isNil(value)` when checking a value directly for `null | undefined`.
24
+ - Use `isNotNil(value)` for the inverse check or to remove nullish array values
25
+ while preserving `Array.prototype.filter` narrowing.
24
26
  - Use `optionalKey(guard)` for optional object keys inside `struct`.
25
27
 
26
28
  ## Preferred Examples
@@ -30,6 +32,7 @@ import {
30
32
  and,
31
33
  define,
32
34
  isNil,
35
+ isNotNil,
33
36
  isNumber,
34
37
  isString,
35
38
  nullish,
@@ -39,6 +42,7 @@ import {
39
42
 
40
43
  const isId = or(isString, isNumber);
41
44
  const isMaybeName = nullish(isString);
45
+ const presentNames = ['Ada', null, undefined].filter(isNotNil);
42
46
  const isSlug = define<string>(
43
47
  (value) => isString(value) && /^[a-z0-9-]+$/.test(value)
44
48
  );
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "is-kit",
3
- "version": "1.11.7",
3
+ "version": "1.12.0",
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",
@@ -68,6 +68,7 @@
68
68
  "scripts": {
69
69
  "test": "jest",
70
70
  "test:types": "tsd",
71
+ "test:package": "node tests/package-smoke.mjs",
71
72
  "lint": "oxlint .",
72
73
  "format": "oxfmt .",
73
74
  "format:check": "oxfmt --check .",