is-kit 1.15.0 โ†’ 1.15.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
@@ -27,42 +27,66 @@
27
27
 
28
28
  `is-kit` is a lightweight, zero-dependency toolkit for building reusable TypeScript **type guards**.
29
29
 
30
- It helps you write small `isFoo` functions, compose them into **richer runtime checks**, and keep **TypeScript narrowing** natural inside regular control flow.
30
+ `is-kit` is not just a collection of `isX` helpers. Its main focus is composing
31
+ small runtime checks into reusable guards while preserving useful TypeScript
32
+ narrowing.
33
+
34
+ It helps you write small `isFoo` functions, compose them into **richer runtime
35
+ checks**, refine properties on values you already know about, and keep
36
+ **TypeScript narrowing** natural inside regular control flow. Use it at runtime
37
+ boundaries when needed, without requiring a schema-first workflow.
31
38
 
32
39
  **Runtime-safe** ๐Ÿ›ก๏ธ, **composable** ๐Ÿงฉ, and **ergonomic** โœจ without asking you to adopt a heavy schema workflow.
33
40
 
34
41
  - Build and reuse **typed guards**
35
42
  - **Compose guards** with `and`, `or`, `not`, `oneOf`
36
- - **Validate object** shapes and collections
43
+ - Use `refineKey` to narrow a **child property** while preserving its parent type
44
+ - **Validate object** shapes and collections when that is useful
37
45
  - **Parse or assert** `unknown` values without a large schema framework
38
46
 
39
- [๐Ÿ“š Documentation Site](https://is-kit.dev/) ยท
40
- [๐Ÿงญ Practical Guides](https://is-kit.dev/guides)
47
+ <a href="https://is-kit.dev/">
48
+ <img src="docs/public/document_button.png" alt="Documentation Site" width="240">
49
+ </a>
41
50
 
42
51
  > Best for **app-internal narrowing, filtering, and reusable guards**.
43
52
 
44
53
  ## ๐Ÿค” Why use `is-kit`?
45
54
 
46
- Tired of rewriting the same `isFoo` checks again and again?
55
+ Many TypeScript projects eventually grow a `utils/is.ts`, `libs/is.ts`, or
56
+ `guards.ts` file. It fills with hand-written guards that solve the same
57
+ problems across projects, are tedious to rewrite, and need manual care to keep
58
+ their TypeScript narrowing correct as they evolve.
47
59
 
48
- `is-kit` is a good fit when you want to:
60
+ `is-kit` exists to make those guards reusable, composable, and easier to
61
+ maintain. The goal is not to replace every validation library; it is to make
62
+ reusable TypeScript type guards easier to build, compose, and maintain.
63
+
64
+ It is a good fit when you want to:
49
65
 
50
66
  - **write reusable `isX`** functions instead of one-off inline checks
51
67
  - keep runtime validation **lightweight and dependency-free**
52
68
  - **narrow values directly** in `if`, `filter`, and other TypeScript control flow
53
- - **compose validation logic** from small guards instead of large schema objects
69
+ - **compose validation logic** from small guards, including property refinements
70
+
71
+ If you only need a few standalone `isX` checks, a smaller type-check utility
72
+ may be simpler. `is-kit` becomes useful when those checks need to be composed,
73
+ refined, and reused across your application while preserving TypeScript
74
+ narrowing.
54
75
 
55
- `is-kit` is probably not the best first choice if you mainly want:
76
+ Schema validators such as Zod, Valibot, and ArkType often optimize for a
77
+ different workflow. They may be a better fit when you mainly want:
56
78
 
57
79
  - rich, structured validation errors
58
80
  - schema-first workflows
59
81
  - data transformation pipelines
60
82
 
61
- In those cases, a schema validator such as `Zod` may be a better fit. (Of course, you can combine them ๐Ÿฒ)
83
+ `is-kit` is aimed at reusable runtime predicates that behave naturally as
84
+ TypeScript type guards. The approaches can also be used together: use a schema
85
+ validator where its parsing model helps, and compose `is-kit` guards wherever
86
+ ordinary narrowing and reusable predicates are the better fit.
62
87
 
63
- `is-kit` is meant to take the boring part out of writing guards, while still feeling like normal TypeScript.
64
-
65
- > Grab a coffee โ˜• and let `is-kit` handle the repetitive part.
88
+ `is-kit` is meant to take the repetitive part out of writing guards while still
89
+ feeling like normal TypeScript.
66
90
 
67
91
  ## ๐Ÿ“ฅ Install
68
92
 
@@ -107,7 +131,43 @@ import { and, define, or } from 'jsr:@nyaomaru/is-kit';
107
131
 
108
132
  ## โœจ Quick Start
109
133
 
110
- Start with a plain object guard and parse an `unknown` value.
134
+ Start by composing small guards.
135
+
136
+ ```ts
137
+ import { and, isNumber, isString, or, predicateToRefine } from 'is-kit';
138
+
139
+ const isId = or(isString, isNumber);
140
+
141
+ const isPositiveNumber = and(
142
+ isNumber,
143
+ predicateToRefine<number>((value) => value > 0)
144
+ );
145
+ ```
146
+
147
+ You can also refine one property of an already-typed parent value.
148
+
149
+ ```ts
150
+ import { isString, refineKey } from 'is-kit';
151
+
152
+ type Item = {
153
+ value: string | number;
154
+ id: number;
155
+ };
156
+
157
+ const hasStringValue = refineKey('value', isString);
158
+
159
+ declare const items: Item[];
160
+
161
+ const textItems = items.filter(hasStringValue);
162
+ // Array<Item & { value: string }>
163
+ ```
164
+
165
+ The original `Item` type is preserved while its checked `value` property is
166
+ narrowed. This lets a reusable guard carry child narrowing back to the parent
167
+ through `filter`, `find`, and control flow.
168
+
169
+ For an `unknown` value at a runtime boundary, build an object guard and parse
170
+ it.
111
171
 
112
172
  ```ts
113
173
  import { isNumber, isString, optionalKey, safeParse, struct } from 'is-kit';
@@ -522,8 +582,7 @@ fields and the union coverage aligned with an existing TypeScript type.
522
582
  import { discriminatedUnion, isNumber, oneOfValues, typedStruct } from 'is-kit';
523
583
 
524
584
  type Event =
525
- | { kind: 'click'; x: number; y: number }
526
- | { kind: 'scroll'; delta: number };
585
+ { kind: 'click'; x: number; y: number } | { kind: 'scroll'; delta: number };
527
586
 
528
587
  const eventUnion = discriminatedUnion<Event>();
529
588
 
package/dist/index.d.mts CHANGED
@@ -64,6 +64,14 @@ type StructOptions = Readonly<{
64
64
  * Object schema shape preserving concrete keys.
65
65
  */
66
66
  type SchemaShape<S extends object> = Readonly<{ [K in keyof S]: SchemaField; }>;
67
+ /**
68
+ * Schema shape accepted by `struct`, limited to JavaScript string and numeric keys.
69
+ *
70
+ * Numeric keys are included because JavaScript normalizes them to string property
71
+ * keys during enumeration. Symbol keys are excluded because `struct` does not
72
+ * enumerate them at runtime.
73
+ */
74
+ type StructSchemaShape<S extends SchemaShape<S>> = Extract<keyof S, symbol> extends never ? S : never;
67
75
  type Simplify<T> = { [K in keyof T]: T[K]; };
68
76
  type InferSchemaField<F> = F extends Predicate<unknown> ? GuardedOf<F> : F extends OptionalSchemaField<infer G> ? GuardedOf<G> : never;
69
77
  type RequiredSchemaKeys<S extends SchemaShape<S>> = { [K in keyof S]-?: S[K] extends OptionalSchemaField<Predicate<unknown>> ? never : K; }[keyof S];
@@ -809,16 +817,18 @@ export declare function setOf<VF extends Predicate<unknown>>(valueGuard: VF): Pr
809
817
  */
810
818
  export declare function optionalKey<G extends Predicate<unknown>>(guard: G): OptionalSchemaField<G>;
811
819
  /**
812
- * Validates an object against a field-to-guard schema.
813
- * Keys in the schema are required unless wrapped with `optionalKey`; optionally
820
+ * Validates an object against a field-to-guard schema with string runtime keys.
821
+ * Numeric schema keys are normalized to strings by JavaScript; symbol-keyed fields
822
+ * are not supported. Keys are required unless wrapped with `optionalKey`; optionally
814
823
  * rejects extra keys when `exact: true`.
815
824
  *
816
- * @param schema Record of property guards.
825
+ * @param schema Record of string- or numeric-keyed property guards.
817
826
  * @param options When `{ exact: true }`, disallows own enumerable string-key
818
827
  * properties not in `schema`.
819
828
  * @returns Predicate that narrows to the inferred struct type.
829
+ * @throws {TypeError} If `schema` has own symbol-keyed fields.
820
830
  */
821
- export declare function struct<const S extends SchemaShape<S>>(schema: S, options?: StructOptions): Predicate<InferSchema<S>>;
831
+ export declare function struct<const S extends SchemaShape<S>>(schema: StructSchemaShape<S>, options?: StructOptions): Predicate<InferSchema<S>>;
822
832
  //#endregion
823
833
  //#region src/core/combinators/typed-struct.d.ts
824
834
  /**
package/dist/index.d.ts CHANGED
@@ -64,6 +64,14 @@ type StructOptions = Readonly<{
64
64
  * Object schema shape preserving concrete keys.
65
65
  */
66
66
  type SchemaShape<S extends object> = Readonly<{ [K in keyof S]: SchemaField; }>;
67
+ /**
68
+ * Schema shape accepted by `struct`, limited to JavaScript string and numeric keys.
69
+ *
70
+ * Numeric keys are included because JavaScript normalizes them to string property
71
+ * keys during enumeration. Symbol keys are excluded because `struct` does not
72
+ * enumerate them at runtime.
73
+ */
74
+ type StructSchemaShape<S extends SchemaShape<S>> = Extract<keyof S, symbol> extends never ? S : never;
67
75
  type Simplify<T> = { [K in keyof T]: T[K]; };
68
76
  type InferSchemaField<F> = F extends Predicate<unknown> ? GuardedOf<F> : F extends OptionalSchemaField<infer G> ? GuardedOf<G> : never;
69
77
  type RequiredSchemaKeys<S extends SchemaShape<S>> = { [K in keyof S]-?: S[K] extends OptionalSchemaField<Predicate<unknown>> ? never : K; }[keyof S];
@@ -809,16 +817,18 @@ export declare function setOf<VF extends Predicate<unknown>>(valueGuard: VF): Pr
809
817
  */
810
818
  export declare function optionalKey<G extends Predicate<unknown>>(guard: G): OptionalSchemaField<G>;
811
819
  /**
812
- * Validates an object against a field-to-guard schema.
813
- * Keys in the schema are required unless wrapped with `optionalKey`; optionally
820
+ * Validates an object against a field-to-guard schema with string runtime keys.
821
+ * Numeric schema keys are normalized to strings by JavaScript; symbol-keyed fields
822
+ * are not supported. Keys are required unless wrapped with `optionalKey`; optionally
814
823
  * rejects extra keys when `exact: true`.
815
824
  *
816
- * @param schema Record of property guards.
825
+ * @param schema Record of string- or numeric-keyed property guards.
817
826
  * @param options When `{ exact: true }`, disallows own enumerable string-key
818
827
  * properties not in `schema`.
819
828
  * @returns Predicate that narrows to the inferred struct type.
829
+ * @throws {TypeError} If `schema` has own symbol-keyed fields.
820
830
  */
821
- export declare function struct<const S extends SchemaShape<S>>(schema: S, options?: StructOptions): Predicate<InferSchema<S>>;
831
+ export declare function struct<const S extends SchemaShape<S>>(schema: StructSchemaShape<S>, options?: StructOptions): Predicate<InferSchema<S>>;
822
832
  //#endregion
823
833
  //#region src/core/combinators/typed-struct.d.ts
824
834
  /**
package/dist/index.js CHANGED
@@ -529,6 +529,7 @@ const isNotNil = (value) => value !== null && value !== void 0;
529
529
  const isPrimitive = or(isString, isNumberPrimitive, isBoolean, isBigInt, isSymbol, isUndefined, isNull);
530
530
  //#endregion
531
531
  //#region src/utils/guard-collections.ts
532
+ const arrayValues = Array.prototype.values;
532
533
  const mapEntries = Map.prototype.entries;
533
534
  const setValues = Set.prototype.values;
534
535
  const everyIterableValue = (values, predicate) => {
@@ -550,6 +551,11 @@ const everyKeyValueEntry = (entries, predicate) => {
550
551
  */
551
552
  const everyArrayValue = (values, predicate) => everyIterableValue(values, predicate);
552
553
  /**
554
+ * Checks built-in Array data without invoking an instance-provided iterator.
555
+ * WHY: An Array subclass or instance may override its public iterator and throw.
556
+ */
557
+ const everyBrandedArrayValue = (values, predicate) => everyIterableValue(arrayValues.call(values), predicate);
558
+ /**
553
559
  * Checks whether a tuple matches the provided element predicates in order.
554
560
  *
555
561
  * @deprecated Use `tupleOf` for a narrowing guard or compare the tuple length
@@ -618,7 +624,7 @@ const everyOwnEnumerableEntry = (values, keyPredicate, valuePredicate) => everyI
618
624
  * @returns Predicate narrowing to a readonly array of the guarded element type.
619
625
  */
620
626
  function arrayOf(elementGuard) {
621
- return define((input) => Array.isArray(input) && everyArrayValue(input, elementGuard));
627
+ return define((input) => Array.isArray(input) && everyBrandedArrayValue(input, elementGuard));
622
628
  }
623
629
  /**
624
630
  * Validates a non-empty array where every element satisfies the provided guard.
@@ -627,7 +633,7 @@ function arrayOf(elementGuard) {
627
633
  * @returns Predicate narrowing to a readonly non-empty array of the guarded element type.
628
634
  */
629
635
  function nonEmptyArrayOf(elementGuard) {
630
- return define((input) => Array.isArray(input) && input.length > 0 && everyArrayValue(input, elementGuard));
636
+ return define((input) => Array.isArray(input) && input.length > 0 && everyBrandedArrayValue(input, elementGuard));
631
637
  }
632
638
  //#endregion
633
639
  //#region src/core/combinators/discriminated-union.ts
@@ -764,16 +770,23 @@ function optionalKey(guard) {
764
770
  };
765
771
  }
766
772
  /**
767
- * Validates an object against a field-to-guard schema.
768
- * Keys in the schema are required unless wrapped with `optionalKey`; optionally
773
+ * Validates an object against a field-to-guard schema with string runtime keys.
774
+ * Numeric schema keys are normalized to strings by JavaScript; symbol-keyed fields
775
+ * are not supported. Keys are required unless wrapped with `optionalKey`; optionally
769
776
  * rejects extra keys when `exact: true`.
770
777
  *
771
- * @param schema Record of property guards.
778
+ * @param schema Record of string- or numeric-keyed property guards.
772
779
  * @param options When `{ exact: true }`, disallows own enumerable string-key
773
780
  * properties not in `schema`.
774
781
  * @returns Predicate that narrows to the inferred struct type.
782
+ * @throws {TypeError} If `schema` has own symbol-keyed fields.
775
783
  */
776
784
  function struct(schema, options) {
785
+ return createStruct(schema, options);
786
+ }
787
+ /** @internal Shared implementation for string-keyed schema builders. */
788
+ function createStruct(schema, options) {
789
+ if (Object.getOwnPropertySymbols(schema).length > 0) throw new TypeError("struct schema fields cannot use symbol keys");
777
790
  const requiredEntries = [];
778
791
  const optionalEntries = [];
779
792
  const schemaKeys = [];
@@ -812,7 +825,7 @@ function struct(schema, options) {
812
825
  * @returns Builder that rejects missing, extra, or incompatible struct fields.
813
826
  */
814
827
  function typedStruct() {
815
- return (fields, options) => struct(fields, options);
828
+ return (fields, options) => createStruct(fields, options);
816
829
  }
817
830
  //#endregion
818
831
  //#region src/core/combinators/tuple.ts
package/dist/index.mjs CHANGED
@@ -528,6 +528,7 @@ const isNotNil = (value) => value !== null && value !== void 0;
528
528
  const isPrimitive = or(isString, isNumberPrimitive, isBoolean, isBigInt, isSymbol, isUndefined, isNull);
529
529
  //#endregion
530
530
  //#region src/utils/guard-collections.ts
531
+ const arrayValues = Array.prototype.values;
531
532
  const mapEntries = Map.prototype.entries;
532
533
  const setValues = Set.prototype.values;
533
534
  const everyIterableValue = (values, predicate) => {
@@ -549,6 +550,11 @@ const everyKeyValueEntry = (entries, predicate) => {
549
550
  */
550
551
  const everyArrayValue = (values, predicate) => everyIterableValue(values, predicate);
551
552
  /**
553
+ * Checks built-in Array data without invoking an instance-provided iterator.
554
+ * WHY: An Array subclass or instance may override its public iterator and throw.
555
+ */
556
+ const everyBrandedArrayValue = (values, predicate) => everyIterableValue(arrayValues.call(values), predicate);
557
+ /**
552
558
  * Checks whether a tuple matches the provided element predicates in order.
553
559
  *
554
560
  * @deprecated Use `tupleOf` for a narrowing guard or compare the tuple length
@@ -617,7 +623,7 @@ const everyOwnEnumerableEntry = (values, keyPredicate, valuePredicate) => everyI
617
623
  * @returns Predicate narrowing to a readonly array of the guarded element type.
618
624
  */
619
625
  function arrayOf(elementGuard) {
620
- return define((input) => Array.isArray(input) && everyArrayValue(input, elementGuard));
626
+ return define((input) => Array.isArray(input) && everyBrandedArrayValue(input, elementGuard));
621
627
  }
622
628
  /**
623
629
  * Validates a non-empty array where every element satisfies the provided guard.
@@ -626,7 +632,7 @@ function arrayOf(elementGuard) {
626
632
  * @returns Predicate narrowing to a readonly non-empty array of the guarded element type.
627
633
  */
628
634
  function nonEmptyArrayOf(elementGuard) {
629
- return define((input) => Array.isArray(input) && input.length > 0 && everyArrayValue(input, elementGuard));
635
+ return define((input) => Array.isArray(input) && input.length > 0 && everyBrandedArrayValue(input, elementGuard));
630
636
  }
631
637
  //#endregion
632
638
  //#region src/core/combinators/discriminated-union.ts
@@ -763,16 +769,23 @@ function optionalKey(guard) {
763
769
  };
764
770
  }
765
771
  /**
766
- * Validates an object against a field-to-guard schema.
767
- * Keys in the schema are required unless wrapped with `optionalKey`; optionally
772
+ * Validates an object against a field-to-guard schema with string runtime keys.
773
+ * Numeric schema keys are normalized to strings by JavaScript; symbol-keyed fields
774
+ * are not supported. Keys are required unless wrapped with `optionalKey`; optionally
768
775
  * rejects extra keys when `exact: true`.
769
776
  *
770
- * @param schema Record of property guards.
777
+ * @param schema Record of string- or numeric-keyed property guards.
771
778
  * @param options When `{ exact: true }`, disallows own enumerable string-key
772
779
  * properties not in `schema`.
773
780
  * @returns Predicate that narrows to the inferred struct type.
781
+ * @throws {TypeError} If `schema` has own symbol-keyed fields.
774
782
  */
775
783
  function struct(schema, options) {
784
+ return createStruct(schema, options);
785
+ }
786
+ /** @internal Shared implementation for string-keyed schema builders. */
787
+ function createStruct(schema, options) {
788
+ if (Object.getOwnPropertySymbols(schema).length > 0) throw new TypeError("struct schema fields cannot use symbol keys");
776
789
  const requiredEntries = [];
777
790
  const optionalEntries = [];
778
791
  const schemaKeys = [];
@@ -811,7 +824,7 @@ function struct(schema, options) {
811
824
  * @returns Builder that rejects missing, extra, or incompatible struct fields.
812
825
  */
813
826
  function typedStruct() {
814
- return (fields, options) => struct(fields, options);
827
+ return (fields, options) => createStruct(fields, options);
815
828
  }
816
829
  //#endregion
817
830
  //#region src/core/combinators/tuple.ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "is-kit",
3
- "version": "1.15.0",
3
+ "version": "1.15.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",
@@ -62,14 +62,14 @@
62
62
  "packageManager": "pnpm@11.2.2",
63
63
  "devDependencies": {
64
64
  "@types/jest": "^30.0.0",
65
- "jest": "^30.4.2",
66
- "lefthook": "^2.1.9",
67
- "oxfmt": "^0.55.0",
68
- "oxlint": "^1.70.0",
69
- "ts-jest": "^29.4.11",
65
+ "jest": "^30.5.2",
66
+ "lefthook": "^2.1.14",
67
+ "oxfmt": "^0.71.0",
68
+ "oxlint": "^1.86.0",
69
+ "ts-jest": "^29.4.14",
70
70
  "tsd": "^0.33.0",
71
71
  "tsdown": "^0.23.0",
72
- "typedoc": "^0.28.19",
72
+ "typedoc": "^0.28.20",
73
73
  "typescript": "^6.0.3"
74
74
  },
75
75
  "tsd": {