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 +45 -5
- package/dist/index.d.mts +71 -11
- package/dist/index.d.ts +71 -11
- package/dist/index.js +33 -6
- package/dist/index.mjs +30 -6
- package/package.json +15 -13
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.
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
|
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): <
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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): <
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
252
|
-
|
|
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
|
-
|
|
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
|
-
|
|
147
|
-
|
|
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.
|
|
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
|
+
}
|