is-kit 1.11.7 โ†’ 1.12.1

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
@@ -23,6 +23,8 @@
23
23
  </a>
24
24
  </p>
25
25
 
26
+ <h2 align="center">Build small guards. Compose them.</h2>
27
+
26
28
  `is-kit` is a lightweight, zero-dependency toolkit for building reusable TypeScript **type guards**.
27
29
 
28
30
  It helps you write small `isFoo` functions, compose them into **richer runtime checks**, and keep **TypeScript narrowing** natural inside regular control flow.
@@ -34,7 +36,8 @@ It helps you write small `isFoo` functions, compose them into **richer runtime c
34
36
  - **Validate object** shapes and collections
35
37
  - **Parse or assert** `unknown` values without a large schema framework
36
38
 
37
- [๐Ÿ“š Documentation Site](https://is-kit-docs.vercel.app/)
39
+ [๐Ÿ“š Documentation Site](https://is-kit-docs.vercel.app/) ยท
40
+ [๐Ÿงญ Practical Guides](https://is-kit-docs.vercel.app/guides)
38
41
 
39
42
  > Best for **app-internal narrowing, filtering, and reusable guards**.
40
43
 
@@ -71,12 +74,25 @@ bun add is-kit
71
74
  npm install is-kit
72
75
  # or
73
76
  yarn add is-kit
77
+ # or
78
+ vlt install is-kit
74
79
  ```
75
80
 
76
81
  ESM and CJS builds are available for npm consumers, and bundled types are included.
77
82
 
83
+ vlt requires registry configuration before installing a package by name. Run
84
+ `vlt setup` once if a registry has not been configured yet.
85
+
78
86
  ### JSR
79
87
 
88
+ Install the JSR package with vlt:
89
+
90
+ ```bash
91
+ vlt install jsr:@nyaomaru/is-kit
92
+ ```
93
+
94
+ Or import it directly in runtimes that support `jsr:` specifiers:
95
+
80
96
  ```ts
81
97
  import { and, define, or } from 'jsr:@nyaomaru/is-kit';
82
98
  ```
@@ -172,8 +188,23 @@ const isSlug = (value: unknown): value is string =>
172
188
 
173
189
  ### AI agent setup
174
190
 
175
- Add the recommended `is-kit` selection and usage rules to a repository's AI
176
- agent instructions:
191
+ #### Recommended: Codex Marketplace plugin
192
+
193
+ Install the `is-kit` plugin from this repository's Codex Marketplace:
194
+
195
+ ```bash
196
+ codex plugin marketplace add nyaomaru/is-kit
197
+ codex plugin add is-kit@is-kit
198
+ ```
199
+
200
+ This is the primary distribution channel for the `use-is-kit` skill. It gives
201
+ Codex an on-demand workflow for selecting guards, replacing manual runtime
202
+ checks, and validating object boundaries with `is-kit`.
203
+
204
+ #### Compatibility: instruction-only setup
205
+
206
+ For agents that do not support skills or plugins, add the lightweight selection
207
+ and usage rules to the repository's agent instructions:
177
208
 
178
209
  ```bash
179
210
  npx --yes is-kit@latest init-agent
@@ -333,6 +364,8 @@ Use the nullish helpers to say exactly what is allowed.
333
364
 
334
365
  ```ts
335
366
  import {
367
+ isNil,
368
+ isNotNil,
336
369
  isString,
337
370
  nonNull,
338
371
  nullable,
@@ -346,19 +379,19 @@ const isNullishString = nullish(isString);
346
379
  const isOptionalString = optional(isString);
347
380
  const isDefinedString = required(optional(isString));
348
381
  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
382
 
357
383
  isNil(null); // true
358
384
  isNil(undefined); // true
359
385
  isNil(0); // false
386
+
387
+ const values: Array<string | null | undefined> = ['value', null, undefined];
388
+ const presentValues = values.filter(isNotNil); // string[]
360
389
  ```
361
390
 
391
+ Use `isNil` for a direct nullish check instead of hand-rolling
392
+ `isNull(x) || isUndefined(x)`. Use `isNotNil` for the inverse check or to
393
+ remove nullish values while preserving `Array.prototype.filter` narrowing.
394
+
362
395
  ### 8. Parse or assert unknown input
363
396
 
364
397
  Use `safeParse` when you want a result object, and `assert` when invalid data should stop execution.
@@ -523,11 +556,28 @@ The library is organized around a few small building blocks:
523
556
  - **Object shapes**: `struct`, `optionalKey`, `hasKey`, `hasKeys`, `narrowKeyTo`
524
557
  - **Collections**: `arrayOf`, `nonEmptyArrayOf`, `tupleOf`, `setOf`, `mapOf`, `recordOf`
525
558
  - **Literals**: `oneOfValues`, `equals`, `equalsBy`, `equalsKey`
526
- - **Nullish handling**: `isNil`, `nullable`, `nonNull`, `nullish`, `optional`, `required`
559
+ - **Nullish handling**: `isNil`, `isNotNil`, `nullable`, `nonNull`, `nullish`, `optional`, `required`
527
560
  - **Result helpers**: `safeParse`, `safeParseWith`, `safeJsonParse`, `assert`
528
561
 
529
562
  For the full API list and dedicated pages, use the docs site below.
530
563
 
564
+ ### Public types
565
+
566
+ Start with the primary types for guard authoring, parsing, and schema inference:
567
+
568
+ - `Predicate`, `Guard`, `Refinement`, `Refine`, `ParseResult`, `Primitive`
569
+ - `InferSchema`, `StructOptions`, `TypedStructShape`, `TypedStructFields`
570
+
571
+ Advanced building blocks support reusable wrappers and type-level extensions:
572
+
573
+ - `GuardedOf`, `GuardedWithin`, `OutOfGuards`, `RefineChain`, `ChainResult`
574
+ - `OptionalSchemaField`, `SchemaField`, `Schema`, `NoExtraKeys`
575
+ - `OptionalObjectKeys`, `RequiredObjectKeys`
576
+
577
+ Both groups are supported public API and follow semantic versioning. The
578
+ classification only controls discoverability. `SchemaShape` remains internal
579
+ and is not exported from the package root.
580
+
531
581
  ### v2 migration notice
532
582
 
533
583
  Six low-level utility adapters remain available in v1 for compatibility but are
@@ -549,7 +599,12 @@ public root exports are planned for removal.
549
599
 
550
600
  For detailed API pages and more examples, see:
551
601
 
552
- https://is-kit-docs.vercel.app/
602
+ - [Practical guides](https://is-kit-docs.vercel.app/guides)
603
+ - [API reference](https://is-kit-docs.vercel.app/api-reference)
604
+ - [Documentation home](https://is-kit-docs.vercel.app/)
605
+
606
+ Start with [How to safely filter null and undefined from arrays in
607
+ TypeScript](https://is-kit-docs.vercel.app/guides/filter-null-and-undefined).
553
608
 
554
609
  ## ๐Ÿ‘จโ€๐Ÿ’ป Development
555
610
 
@@ -559,6 +614,7 @@ Requires Node 22.22.0 and pnpm 11.2.2.
559
614
  - `pnpm build`
560
615
  - `pnpm test`
561
616
  - `pnpm test:types`
617
+ - `pnpm test:package`
562
618
 
563
619
  See `DEVELOPER.md` for setup details and `CONTRIBUTE.md` for contribution workflow.
564
620
 
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.1",
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,8 @@
68
68
  "scripts": {
69
69
  "test": "jest",
70
70
  "test:types": "tsd",
71
+ "test:package": "node tests/package-smoke.mjs",
72
+ "test:package:vlt": "node tests/vlt-package-smoke.mjs",
71
73
  "lint": "oxlint .",
72
74
  "format": "oxfmt .",
73
75
  "format:check": "oxfmt --check .",