is-kit 1.13.0 → 1.14.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
@@ -79,6 +79,14 @@ vlt install is-kit
79
79
  ```
80
80
 
81
81
  ESM and CJS builds are available for npm consumers, and bundled types are included.
82
+ The published declarations support TypeScript 5.7 and newer. CI compiles the
83
+ packed package against every TypeScript minor from 5.7 through the current
84
+ stable release.
85
+
86
+ TypeScript 7 can type-check is-kit declarations, but TypeScript 7.0 does not
87
+ ship the legacy JavaScript Compiler API. Tools that need that API can follow
88
+ the official [TypeScript 7 side-by-side guidance](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/#running-side-by-side-with-typescript-6-0)
89
+ and use `@typescript/typescript6` for programmatic access.
82
90
 
83
91
  vlt requires registry configuration before installing a package by name. Run
84
92
  `vlt setup` once if a registry has not been configured yet.
@@ -227,6 +235,7 @@ If you are new to the library, these are the pieces to remember:
227
235
  - `define<T>(fn)` turns a boolean check into a typed guard.
228
236
  - `lazy(factory)` defers a guard definition so recursive structures can refer to themselves.
229
237
  - `predicateToRefine(fn)` upgrades an existing predicate so it can participate in narrowing chains.
238
+ - `refineKey(key, guard)` carries a child refinement back onto its parent type.
230
239
  - `struct({...})` builds an object-shape guard.
231
240
  - `safeParse(guard, value)` gives you a small tagged result object.
232
241
  - `assert(guard, value)` throws if the value does not match.
@@ -358,7 +367,32 @@ const isTree: Predicate<Tree> = lazy(() =>
358
367
 
359
368
  `lazy` does not detect circular references in the input value.
360
369
 
361
- ### 7. Handle null and undefined explicitly
370
+ ### 7. Refine properties on existing types
371
+
372
+ Use the property helpers when an object is already typed and one child value
373
+ needs additional narrowing.
374
+
375
+ ```ts
376
+ import { isString, refineDefinedKey, refineIndex, refineKey } from 'is-kit';
377
+
378
+ const hasStringValue = refineKey('value', isString);
379
+ const hasDefinedStringLabel = refineDefinedKey('label', isString);
380
+ const hasStringAtZero = refineIndex(0, isString);
381
+ ```
382
+
383
+ - `refineKey` refines one required property using normal property access.
384
+ - `refineDefinedKey` returns `false` for a missing or `undefined` property.
385
+ - `refineIndex` returns `false` for an out-of-bounds, sparse, or `undefined`
386
+ own element.
387
+
388
+ The property helpers accept inherited values and accessors. The index helper
389
+ requires an own element so a sparse hole cannot pass through an inherited
390
+ numeric property.
391
+
392
+ Each key or index must identify one concrete runtime location. This keeps one
393
+ successful lookup from incorrectly narrowing multiple properties.
394
+
395
+ ### 8. Handle null and undefined explicitly
362
396
 
363
397
  Use the nullish helpers to say exactly what is allowed.
364
398
 
@@ -392,7 +426,7 @@ Use `isNil` for a direct nullish check instead of hand-rolling
392
426
  `isNull(x) || isUndefined(x)`. Use `isNotNil` for the inverse check or to
393
427
  remove nullish values while preserving `Array.prototype.filter` narrowing.
394
428
 
395
- ### 8. Parse or assert unknown input
429
+ ### 9. Parse or assert unknown input
396
430
 
397
431
  Use `safeParse` when you want a result object, and `assert` when invalid data should stop execution.
398
432
 
@@ -411,7 +445,7 @@ assert(isString, input, 'Expected a string');
411
445
  input.toUpperCase();
412
446
  ```
413
447
 
414
- ### 9. Decode and validate JSON input
448
+ ### 10. Decode and validate JSON input
415
449
 
416
450
  Use `safeJsonParse` at a JSON text boundary. It decodes the text, treats the
417
451
  result as `unknown`, and only returns the value after the guard accepts it.
@@ -443,7 +477,7 @@ if (result.valid) {
443
477
  coercion and does not depend on a transport or schema format such as HTTP or
444
478
  OpenAPI.
445
479
 
446
- ### 10. Narrow object keys
480
+ ### 11. Narrow object keys
447
481
 
448
482
  Use key helpers when the important part of a value is one property.
449
483
 
@@ -486,6 +520,11 @@ if (isAdmin(value)) {
486
520
  }
487
521
  ```
488
522
 
523
+ Singleton literal keys preserve key-specific narrowing. Union, broad, patterned,
524
+ or branded key domains remain usable as runtime checks, but they narrow only to
525
+ an object—or to the base guard type for `narrowKeyTo`—because one runtime key
526
+ cannot prove that every possible key was checked.
527
+
489
528
  ## 🌍 Real-world use cases
490
529
 
491
530
  Here are the kinds of problems `is-kit` is especially good at solving:
@@ -555,7 +594,7 @@ The library is organized around a few small building blocks:
555
594
 
556
595
  - **Primitives**: `isString`, `isNumber`, `isBoolean`, `isInteger`, ...
557
596
  - **Composition**: `define`, `and`, `andAll`, `or`, `not`, `oneOf`
558
- - **Object shapes**: `struct`, `optionalKey`, `hasKey`, `hasKeys`, `narrowKeyTo`
597
+ - **Object shapes**: `struct`, `optionalKey`, `hasKey`, `hasKeys`, `narrowKeyTo`, `refineKey`, `refineDefinedKey`, `refineIndex`
559
598
  - **Collections**: `arrayOf`, `nonEmptyArrayOf`, `tupleOf`, `setOf`, `mapOf`, `recordOf`
560
599
  - **Literals**: `oneOfValues`, `equals`, `equalsBy`, `equalsKey`
561
600
  - **Nullish handling**: `isNil`, `isNotNil`, `nullable`, `nonNull`, `nullish`, `optional`, `required`
@@ -603,6 +642,7 @@ For detailed API pages and more examples, see:
603
642
 
604
643
  - [Practical guides](https://is-kit.dev/guides)
605
644
  - [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)
606
646
  - [Validate unknown without a schema library](https://is-kit.dev/guides/validate-unknown-without-schema-library)
607
647
  - [API reference](https://is-kit.dev/api-reference)
608
648
  - [Documentation home](https://is-kit.dev/)
package/dist/index.d.mts CHANGED
@@ -140,6 +140,26 @@ declare function assert<A, B extends A>(refine: Refine<A, B>, value: A, message?
140
140
  declare function define<T>(fn: (value: unknown) => value is T): Predicate<T>;
141
141
  declare function define<T>(fn: (value: unknown) => boolean): Predicate<T>;
142
142
 
143
+ /** Detects whether a type represents more than one possible value. */
144
+ type IsUnion<Value, Whole = Value> = Value extends Whole ? [Whole] extends [Value] ? false : true : never;
145
+ /** Keeps only one literal property key so one lookup cannot narrow other keys. */
146
+ type SinglePropertyKey<Key extends PropertyKey> = [Key] extends [never] ? never : true extends IsUnion<Key> ? never : {} extends Record<Key, never> ? never : Key;
147
+ /** Applies the singleton-key constraint to every member of a key tuple. */
148
+ type SinglePropertyKeys<Keys extends readonly PropertyKey[]> = {
149
+ [Index in keyof Keys]: Keys[Index] & SinglePropertyKey<Keys[Index]>;
150
+ };
151
+ /** Narrows one concrete key, or only object-ness for a multi-value key domain. */
152
+ type KeyPresence<Key extends PropertyKey> = [
153
+ SinglePropertyKey<Key>
154
+ ] extends [never] ? object : Record<Key, unknown>;
155
+ /** Narrows concrete key arguments, or only object-ness when any may vary. */
156
+ type KeyPresences<Keys extends readonly PropertyKey[]> = true extends IsUnion<Keys> ? object : [Keys] extends [SinglePropertyKeys<Keys>] ? Record<Keys[number], unknown> : object;
157
+ /** Keeps only one non-negative integer literal that identifies an array index. */
158
+ type ArrayIndex<Index extends number> = SinglePropertyKey<Index> extends never ? never : `${Index}` extends `-${string}` ? never : `${Index}` extends `${bigint}` ? Index : never;
159
+
160
+ type EqualsKeyPredicate<K extends PropertyKey, T> = [
161
+ SinglePropertyKey<K>
162
+ ] extends [never] ? Predicate<object> : <A extends Record<K, unknown>>(input: unknown) => input is A & Record<K, T>;
143
163
  /**
144
164
  * Creates a guard that matches values equal to the provided target using `Object.is` semantics.
145
165
  *
@@ -160,26 +180,32 @@ declare function equalsBy<F extends Predicate<unknown>, K>(guard: F, selector: (
160
180
  /**
161
181
  * Creates a guard that matches objects having a key equal to the target value.
162
182
  *
163
- * @param key Property key to compare.
183
+ * @param key Property key to compare; singleton literals narrow that property.
164
184
  * @param target Value to compare using `Object.is`.
165
- * @returns Predicate narrowing to objects where `key` exists and equals `target`.
185
+ * @returns Predicate with key-specific narrowing for a singleton literal key,
186
+ * or object-only narrowing for a multi-value key domain.
166
187
  */
167
- declare function equalsKey<K extends PropertyKey, const T>(key: K, target: T): <A extends Record<K, unknown>>(input: unknown) => input is A & Record<K, T>;
188
+ declare function equalsKey<const K extends PropertyKey, const T>(key: K, target: T): EqualsKeyPredicate<K, T>;
168
189
 
190
+ type NarrowKeyPredicate<A, K extends PropertyKey, T> = [
191
+ SinglePropertyKey<K>
192
+ ] extends [never] ? Predicate<A> : Predicate<A & Record<K, T>>;
169
193
  /**
170
194
  * Checks whether a value has the specified own key.
171
195
  *
172
196
  * @param key Property key to check.
173
- * @returns Predicate narrowing to an object with the key present.
197
+ * @returns Predicate with key-specific narrowing for a singleton literal key,
198
+ * or object-only narrowing for a multi-value key domain.
174
199
  */
175
- declare const hasKey: <K extends PropertyKey>(key: K) => Predicate<Record<K, unknown>>;
200
+ declare function hasKey<const K extends PropertyKey>(key: K): Predicate<KeyPresence<K>>;
176
201
  /**
177
202
  * Checks whether a value has all specified own keys.
178
203
  *
179
204
  * @param keys Property keys to check.
180
- * @returns Predicate narrowing to an object with all keys present.
205
+ * @returns Predicate with key-specific narrowing when every argument is a
206
+ * singleton literal key, or object-only narrowing otherwise.
181
207
  */
182
- declare const hasKeys: <const KS extends readonly [PropertyKey, ...PropertyKey[]]>(...keys: KS) => Predicate<Record<KS[number], unknown>>;
208
+ declare function hasKeys<const KS extends readonly [PropertyKey, ...PropertyKey[]]>(...keys: KS): Predicate<KeyPresences<KS>>;
183
209
  /**
184
210
  * Builds a guard that narrows a specific key to the provided literal value.
185
211
  *
@@ -188,11 +214,45 @@ declare const hasKeys: <const KS extends readonly [PropertyKey, ...PropertyKey[]
188
214
  * `{ [key]: target }`.
189
215
  *
190
216
  * @param guard Base guard for objects that include `key`.
191
- * @param key Property key to narrow.
217
+ * @param key Property key to compare; singleton literals narrow that property.
192
218
  * @returns Builder that takes a literal `target` and returns a guard that
193
- * narrows `key` to that literal.
219
+ * narrows a singleton `key` to that literal. Multi-value key domains preserve
220
+ * only the base guard's type.
221
+ */
222
+ declare function narrowKeyTo<A, const K extends keyof A & PropertyKey>(guard: Guard<A>, key: K): <const T extends A[K]>(target: T) => NarrowKeyPredicate<A, K, T>;
223
+
224
+ /**
225
+ * Lifts a required-property refinement to its parent object.
226
+ * @param key Single literal key of the required property to refine.
227
+ * @param refinement Refinement applied to the property value.
228
+ * @returns Refinement that preserves the parent type and narrows the property.
229
+ * @example
230
+ * const hasIdentifierExpression = refineKey('expression', ts.isIdentifier);
231
+ */
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
+ /**
234
+ * Lifts a defined optional-property refinement to its parent object.
235
+ * @param key Single literal key of the optional property to refine when defined.
236
+ * @param refinement Refinement applied only to a defined property value.
237
+ * @returns Refinement that requires and narrows the property.
238
+ * @example
239
+ * const hasCallInitializer = refineDefinedKey(
240
+ * 'initializer',
241
+ * ts.isCallExpression
242
+ * );
194
243
  */
195
- declare function narrowKeyTo<A, K extends keyof A>(guard: Guard<A>, key: K): <const T extends A[K]>(target: T) => Predicate<A & Record<K, T>>;
244
+ 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
+ /**
246
+ * Refines one defined own element of a readonly array.
247
+ * @param index Non-negative integer literal identifying the own element.
248
+ * @param refinement Refinement applied only to a defined element.
249
+ * @returns Refinement that narrows the selected index.
250
+ * @example
251
+ * const hasStringFirstArgument = refineIndex(0, ts.isStringLiteral);
252
+ */
253
+ declare function refineIndex<const Index extends number, ElementInput, ElementOutput extends ElementInput>(index: ArrayIndex<Index>, refinement: Refinement<ElementInput, ElementOutput>): Refinement<readonly ElementInput[], readonly ElementInput[] & {
254
+ readonly [K in Index]: Exclude<ElementOutput, undefined>;
255
+ }>;
196
256
 
197
257
  /**
198
258
  * Creates a predicate whose implementation is initialized on first use.
@@ -836,4 +896,4 @@ declare const everyOwnEnumerableEntry: (values: Record<string, unknown>, keyPred
836
896
  */
837
897
  declare const toBooleanPredicates: <A>(predicates: readonly ((value: A) => boolean)[]) => ReadonlyArray<(value: A) => boolean>;
838
898
 
839
- 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 };
899
+ 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, refineDefinedKey, refineIndex, refineKey, required, safeJsonParse, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf, typedStruct };
package/dist/index.d.ts CHANGED
@@ -140,6 +140,26 @@ declare function assert<A, B extends A>(refine: Refine<A, B>, value: A, message?
140
140
  declare function define<T>(fn: (value: unknown) => value is T): Predicate<T>;
141
141
  declare function define<T>(fn: (value: unknown) => boolean): Predicate<T>;
142
142
 
143
+ /** Detects whether a type represents more than one possible value. */
144
+ type IsUnion<Value, Whole = Value> = Value extends Whole ? [Whole] extends [Value] ? false : true : never;
145
+ /** Keeps only one literal property key so one lookup cannot narrow other keys. */
146
+ type SinglePropertyKey<Key extends PropertyKey> = [Key] extends [never] ? never : true extends IsUnion<Key> ? never : {} extends Record<Key, never> ? never : Key;
147
+ /** Applies the singleton-key constraint to every member of a key tuple. */
148
+ type SinglePropertyKeys<Keys extends readonly PropertyKey[]> = {
149
+ [Index in keyof Keys]: Keys[Index] & SinglePropertyKey<Keys[Index]>;
150
+ };
151
+ /** Narrows one concrete key, or only object-ness for a multi-value key domain. */
152
+ type KeyPresence<Key extends PropertyKey> = [
153
+ SinglePropertyKey<Key>
154
+ ] extends [never] ? object : Record<Key, unknown>;
155
+ /** Narrows concrete key arguments, or only object-ness when any may vary. */
156
+ type KeyPresences<Keys extends readonly PropertyKey[]> = true extends IsUnion<Keys> ? object : [Keys] extends [SinglePropertyKeys<Keys>] ? Record<Keys[number], unknown> : object;
157
+ /** Keeps only one non-negative integer literal that identifies an array index. */
158
+ type ArrayIndex<Index extends number> = SinglePropertyKey<Index> extends never ? never : `${Index}` extends `-${string}` ? never : `${Index}` extends `${bigint}` ? Index : never;
159
+
160
+ type EqualsKeyPredicate<K extends PropertyKey, T> = [
161
+ SinglePropertyKey<K>
162
+ ] extends [never] ? Predicate<object> : <A extends Record<K, unknown>>(input: unknown) => input is A & Record<K, T>;
143
163
  /**
144
164
  * Creates a guard that matches values equal to the provided target using `Object.is` semantics.
145
165
  *
@@ -160,26 +180,32 @@ declare function equalsBy<F extends Predicate<unknown>, K>(guard: F, selector: (
160
180
  /**
161
181
  * Creates a guard that matches objects having a key equal to the target value.
162
182
  *
163
- * @param key Property key to compare.
183
+ * @param key Property key to compare; singleton literals narrow that property.
164
184
  * @param target Value to compare using `Object.is`.
165
- * @returns Predicate narrowing to objects where `key` exists and equals `target`.
185
+ * @returns Predicate with key-specific narrowing for a singleton literal key,
186
+ * or object-only narrowing for a multi-value key domain.
166
187
  */
167
- declare function equalsKey<K extends PropertyKey, const T>(key: K, target: T): <A extends Record<K, unknown>>(input: unknown) => input is A & Record<K, T>;
188
+ declare function equalsKey<const K extends PropertyKey, const T>(key: K, target: T): EqualsKeyPredicate<K, T>;
168
189
 
190
+ type NarrowKeyPredicate<A, K extends PropertyKey, T> = [
191
+ SinglePropertyKey<K>
192
+ ] extends [never] ? Predicate<A> : Predicate<A & Record<K, T>>;
169
193
  /**
170
194
  * Checks whether a value has the specified own key.
171
195
  *
172
196
  * @param key Property key to check.
173
- * @returns Predicate narrowing to an object with the key present.
197
+ * @returns Predicate with key-specific narrowing for a singleton literal key,
198
+ * or object-only narrowing for a multi-value key domain.
174
199
  */
175
- declare const hasKey: <K extends PropertyKey>(key: K) => Predicate<Record<K, unknown>>;
200
+ declare function hasKey<const K extends PropertyKey>(key: K): Predicate<KeyPresence<K>>;
176
201
  /**
177
202
  * Checks whether a value has all specified own keys.
178
203
  *
179
204
  * @param keys Property keys to check.
180
- * @returns Predicate narrowing to an object with all keys present.
205
+ * @returns Predicate with key-specific narrowing when every argument is a
206
+ * singleton literal key, or object-only narrowing otherwise.
181
207
  */
182
- declare const hasKeys: <const KS extends readonly [PropertyKey, ...PropertyKey[]]>(...keys: KS) => Predicate<Record<KS[number], unknown>>;
208
+ declare function hasKeys<const KS extends readonly [PropertyKey, ...PropertyKey[]]>(...keys: KS): Predicate<KeyPresences<KS>>;
183
209
  /**
184
210
  * Builds a guard that narrows a specific key to the provided literal value.
185
211
  *
@@ -188,11 +214,45 @@ declare const hasKeys: <const KS extends readonly [PropertyKey, ...PropertyKey[]
188
214
  * `{ [key]: target }`.
189
215
  *
190
216
  * @param guard Base guard for objects that include `key`.
191
- * @param key Property key to narrow.
217
+ * @param key Property key to compare; singleton literals narrow that property.
192
218
  * @returns Builder that takes a literal `target` and returns a guard that
193
- * narrows `key` to that literal.
219
+ * narrows a singleton `key` to that literal. Multi-value key domains preserve
220
+ * only the base guard's type.
221
+ */
222
+ declare function narrowKeyTo<A, const K extends keyof A & PropertyKey>(guard: Guard<A>, key: K): <const T extends A[K]>(target: T) => NarrowKeyPredicate<A, K, T>;
223
+
224
+ /**
225
+ * Lifts a required-property refinement to its parent object.
226
+ * @param key Single literal key of the required property to refine.
227
+ * @param refinement Refinement applied to the property value.
228
+ * @returns Refinement that preserves the parent type and narrows the property.
229
+ * @example
230
+ * const hasIdentifierExpression = refineKey('expression', ts.isIdentifier);
231
+ */
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
+ /**
234
+ * Lifts a defined optional-property refinement to its parent object.
235
+ * @param key Single literal key of the optional property to refine when defined.
236
+ * @param refinement Refinement applied only to a defined property value.
237
+ * @returns Refinement that requires and narrows the property.
238
+ * @example
239
+ * const hasCallInitializer = refineDefinedKey(
240
+ * 'initializer',
241
+ * ts.isCallExpression
242
+ * );
194
243
  */
195
- declare function narrowKeyTo<A, K extends keyof A>(guard: Guard<A>, key: K): <const T extends A[K]>(target: T) => Predicate<A & Record<K, T>>;
244
+ 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
+ /**
246
+ * Refines one defined own element of a readonly array.
247
+ * @param index Non-negative integer literal identifying the own element.
248
+ * @param refinement Refinement applied only to a defined element.
249
+ * @returns Refinement that narrows the selected index.
250
+ * @example
251
+ * const hasStringFirstArgument = refineIndex(0, ts.isStringLiteral);
252
+ */
253
+ declare function refineIndex<const Index extends number, ElementInput, ElementOutput extends ElementInput>(index: ArrayIndex<Index>, refinement: Refinement<ElementInput, ElementOutput>): Refinement<readonly ElementInput[], readonly ElementInput[] & {
254
+ readonly [K in Index]: Exclude<ElementOutput, undefined>;
255
+ }>;
196
256
 
197
257
  /**
198
258
  * Creates a predicate whose implementation is initialized on first use.
@@ -836,4 +896,4 @@ declare const everyOwnEnumerableEntry: (values: Record<string, unknown>, keyPred
836
896
  */
837
897
  declare const toBooleanPredicates: <A>(predicates: readonly ((value: A) => boolean)[]) => ReadonlyArray<(value: A) => boolean>;
838
898
 
839
- 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 };
899
+ 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, refineDefinedKey, refineIndex, refineKey, required, safeJsonParse, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf, typedStruct };
package/dist/index.js CHANGED
@@ -91,6 +91,9 @@ __export(index_exports, {
91
91
  or: () => or,
92
92
  predicateToRefine: () => predicateToRefine,
93
93
  recordOf: () => recordOf,
94
+ refineDefinedKey: () => refineDefinedKey,
95
+ refineIndex: () => refineIndex,
96
+ refineKey: () => refineKey,
94
97
  required: () => required,
95
98
  safeJsonParse: () => safeJsonParse,
96
99
  safeParse: () => safeParse,
@@ -241,22 +244,25 @@ function equalsBy(guard, selector) {
241
244
  return (selectorFn) => createComparator(selectorFn);
242
245
  }
243
246
  function equalsKey(key, target) {
244
- const hasMatchingKey = define((input) => {
247
+ return define((input) => {
245
248
  return isObject(input) && hasOwnPropertyKey(input, key) && Object.is(input[key], target);
246
249
  });
247
- return (input) => hasMatchingKey(input);
248
250
  }
249
251
 
250
- // src/core/key.ts
251
- var hasKey = (key) => define((input) => isObject(input) && hasOwnPropertyKey(input, key));
252
- var hasKeys = (...keys) => {
252
+ // src/core/key-guards.ts
253
+ function hasKey(key) {
254
+ return define(
255
+ (input) => isObject(input) && hasOwnPropertyKey(input, key)
256
+ );
257
+ }
258
+ function hasKeys(...keys) {
253
259
  if (keys.length === 0) {
254
260
  return define(() => false);
255
261
  }
256
262
  return define(
257
263
  (input) => isObject(input) && hasOwnPropertyKeys(input, keys)
258
264
  );
259
- };
265
+ }
260
266
  function narrowKeyTo(guard, key) {
261
267
  return (target) => {
262
268
  const keyEquals = equalsKey(key, target);
@@ -266,6 +272,24 @@ function narrowKeyTo(guard, key) {
266
272
  };
267
273
  }
268
274
 
275
+ // src/core/property-refinement.ts
276
+ function refineKey(key, refinement) {
277
+ return (value) => refinement(value[key]);
278
+ }
279
+ function refineDefinedKey(key, refinement) {
280
+ return (value) => {
281
+ const property = value[key];
282
+ return property !== void 0 && refinement(property);
283
+ };
284
+ }
285
+ function refineIndex(index, refinement) {
286
+ return (value) => {
287
+ if (!hasOwnPropertyKey(value, index)) return false;
288
+ const element = value[index];
289
+ return element !== void 0 && refinement(element);
290
+ };
291
+ }
292
+
269
293
  // src/core/lazy.ts
270
294
  function lazy(factory) {
271
295
  let predicate;
@@ -631,6 +655,9 @@ var toBooleanPredicates = (predicates) => predicates;
631
655
  or,
632
656
  predicateToRefine,
633
657
  recordOf,
658
+ refineDefinedKey,
659
+ refineIndex,
660
+ refineKey,
634
661
  required,
635
662
  safeJsonParse,
636
663
  safeParse,
package/dist/index.mjs CHANGED
@@ -136,22 +136,25 @@ function equalsBy(guard, selector) {
136
136
  return (selectorFn) => createComparator(selectorFn);
137
137
  }
138
138
  function equalsKey(key, target) {
139
- const hasMatchingKey = define((input) => {
139
+ return define((input) => {
140
140
  return isObject(input) && hasOwnPropertyKey(input, key) && Object.is(input[key], target);
141
141
  });
142
- return (input) => hasMatchingKey(input);
143
142
  }
144
143
 
145
- // src/core/key.ts
146
- var hasKey = (key) => define((input) => isObject(input) && hasOwnPropertyKey(input, key));
147
- var hasKeys = (...keys) => {
144
+ // src/core/key-guards.ts
145
+ function hasKey(key) {
146
+ return define(
147
+ (input) => isObject(input) && hasOwnPropertyKey(input, key)
148
+ );
149
+ }
150
+ function hasKeys(...keys) {
148
151
  if (keys.length === 0) {
149
152
  return define(() => false);
150
153
  }
151
154
  return define(
152
155
  (input) => isObject(input) && hasOwnPropertyKeys(input, keys)
153
156
  );
154
- };
157
+ }
155
158
  function narrowKeyTo(guard, key) {
156
159
  return (target) => {
157
160
  const keyEquals = equalsKey(key, target);
@@ -161,6 +164,24 @@ function narrowKeyTo(guard, key) {
161
164
  };
162
165
  }
163
166
 
167
+ // src/core/property-refinement.ts
168
+ function refineKey(key, refinement) {
169
+ return (value) => refinement(value[key]);
170
+ }
171
+ function refineDefinedKey(key, refinement) {
172
+ return (value) => {
173
+ const property = value[key];
174
+ return property !== void 0 && refinement(property);
175
+ };
176
+ }
177
+ function refineIndex(index, refinement) {
178
+ return (value) => {
179
+ if (!hasOwnPropertyKey(value, index)) return false;
180
+ const element = value[index];
181
+ return element !== void 0 && refinement(element);
182
+ };
183
+ }
184
+
164
185
  // src/core/lazy.ts
165
186
  function lazy(factory) {
166
187
  let predicate;
@@ -525,6 +546,9 @@ export {
525
546
  or,
526
547
  predicateToRefine,
527
548
  recordOf,
549
+ refineDefinedKey,
550
+ refineIndex,
551
+ refineKey,
528
552
  required,
529
553
  safeJsonParse,
530
554
  safeParse,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "is-kit",
3
- "version": "1.13.0",
3
+ "version": "1.14.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",
@@ -15,6 +15,18 @@
15
15
  "bin": {
16
16
  "is-kit": "./bin/is-kit.mjs"
17
17
  },
18
+ "scripts": {
19
+ "test": "jest",
20
+ "test:types": "tsd && tsc -p tests-d/tsconfig.property-refinement.json",
21
+ "test:typescript-compat": "node tests/typescript-compatibility.mjs",
22
+ "test:package": "node tests/package-smoke.mjs",
23
+ "test:package:vlt": "node tests/vlt-package-smoke.mjs",
24
+ "lint": "oxlint .",
25
+ "format": "oxfmt .",
26
+ "format:check": "oxfmt --check .",
27
+ "build": "tsup",
28
+ "typedoc": "typedoc --out docs/public/api"
29
+ },
18
30
  "keywords": [
19
31
  "typescript",
20
32
  "type-guard",
@@ -46,6 +58,7 @@
46
58
  "homepage": "https://is-kit.dev/",
47
59
  "author": "nyaomaru",
48
60
  "license": "MIT",
61
+ "packageManager": "pnpm@11.2.2",
49
62
  "devDependencies": {
50
63
  "@types/jest": "^30.0.0",
51
64
  "jest": "^30.4.2",
@@ -64,16 +77,5 @@
64
77
  "baseUrl": ".",
65
78
  "ignoreDeprecations": "6.0"
66
79
  }
67
- },
68
- "scripts": {
69
- "test": "jest",
70
- "test:types": "tsd",
71
- "test:package": "node tests/package-smoke.mjs",
72
- "test:package:vlt": "node tests/vlt-package-smoke.mjs",
73
- "lint": "oxlint .",
74
- "format": "oxfmt .",
75
- "format:check": "oxfmt --check .",
76
- "build": "tsup",
77
- "typedoc": "typedoc --out docs/public/api"
78
80
  }
79
- }
81
+ }