is-kit 1.7.0 → 1.7.1

package/dist/index.d.mts

@@ -50,6 +50,17 @@ type InferSchema<S extends Schema> = Simplify<{
     readonly [K in OptionalSchemaKeys<S>]?: InferSchemaField<S[K]>;
 }>;
 
+/**
+ * Asserts that a value satisfies a guard or refinement, otherwise throws.
+ *
+ * @param guard Guard/refinement to evaluate.
+ * @param value Value to assert.
+ * @param message Optional error message when assertion fails.
+ * @returns Nothing when assertion passes; throws an `Error` on failure.
+ */
+declare function assert<T>(guard: Guard<T>, value: unknown, message?: string): asserts value is T;
+declare function assert<A, B extends A>(refine: Refine<A, B>, value: A, message?: string): asserts value is B;
+
 /**
  * Wraps a user function as a typed predicate.
  *
@@ -63,23 +74,58 @@ declare function define<T>(fn: (value: unknown) => value is T): Predicate<T>;
 declare function define<T>(fn: (value: unknown) => boolean): Predicate<T>;
 
 /**
- * Converts a boolean predicate into a refinement preserving the input type.
+ * Creates a guard that matches values equal to the provided target using `Object.is` semantics.
  *
- * @param fn Boolean-returning function over a value of type A.
- * @returns Refinement equivalent to the provided predicate.
+ * @param target Target value to compare against.
+ * @returns Predicate narrowing to the exact literal type of `target`.
  */
-declare const predicateToRefine: <A>(fn: (value: A) => boolean) => Refine<A, A>;
+declare function equals<const T>(target: T): Predicate<T>;
+/**
+ * Creates a comparator builder based on a guard and selector.
+ * Useful for checking whether a selected key or projection equals a target value.
+ *
+ * @param guard Guard for the base type before selecting a field.
+ * @param selector Optional selector to project the comparable key; if omitted, returns a function to supply it later.
+ * @returns Function that accepts a target and returns a predicate over the original value.
+ */
+declare function equalsBy<F extends Predicate<unknown>>(guard: F): <K>(selector: (value: GuardedOf<F>) => K) => <const T extends K>(target: T) => Predicate<GuardedOf<F>>;
+declare function equalsBy<F extends Predicate<unknown>, K>(guard: F, selector: (value: GuardedOf<F>) => K): <const T extends K>(target: T) => Predicate<GuardedOf<F>>;
+/**
+ * Creates a guard that matches objects having a key equal to the target value.
+ *
+ * @param key Property key to compare.
+ * @param target Value to compare using `Object.is`.
+ * @returns Predicate narrowing to objects where `key` exists and equals `target`.
+ */
+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>;
 
 /**
- * Asserts that a value satisfies a guard or refinement, otherwise throws.
+ * Checks whether a value has the specified own key.
  *
- * @param guard Guard/refinement to evaluate.
- * @param value Value to assert.
- * @param message Optional error message when assertion fails.
- * @returns Nothing when assertion passes; throws an `Error` on failure.
+ * @param key Property key to check.
+ * @returns Predicate narrowing to an object with the key present.
  */
-declare function assert<T>(guard: Guard<T>, value: unknown, message?: string): asserts value is T;
-declare function assert<A, B extends A>(refine: Refine<A, B>, value: A, message?: string): asserts value is B;
+declare const hasKey: <K extends PropertyKey>(key: K) => Predicate<Record<K, unknown>>;
+/**
+ * Checks whether a value has all specified own keys.
+ *
+ * @param keys Property keys to check.
+ * @returns Predicate narrowing to an object with all keys present.
+ */
+declare const hasKeys: <const KS extends readonly [PropertyKey, ...PropertyKey[]]>(...keys: KS) => Predicate<Record<KS[number], unknown>>;
+/**
+ * Builds a guard that narrows a specific key to the provided literal value.
+ *
+ * Given a base guard and a property key, returns a function that accepts a
+ * target value and produces a guard of the base type intersected with
+ * `{ [key]: target }`.
+ *
+ * @param guard Base guard for objects that include `key`.
+ * @param key Property key to narrow.
+ * @returns Builder that takes a literal `target` and returns a guard that
+ * narrows `key` to that literal.
+ */
+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>>;
 
 /**
  * Combines a precondition guard with an additional refinement to narrow the type.
@@ -162,32 +208,6 @@ declare function optional<A, B extends A>(refine: Refine<A, B>): Refine<A | unde
 declare function required<T>(guard: Guard<T | undefined>): Guard<T>;
 declare function required<A, B extends A>(refine: Refine<A | undefined, B | undefined>): Refine<A, B>;
 
-/**
- * Creates a guard that matches values equal to the provided target using `Object.is` semantics.
- *
- * @param target Target value to compare against.
- * @returns Predicate narrowing to the exact literal type of `target`.
- */
-declare function equals<const T>(target: T): Predicate<T>;
-/**
- * Creates a comparator builder based on a guard and selector.
- * Useful for checking whether a selected key or projection equals a target value.
- *
- * @param guard Guard for the base type before selecting a field.
- * @param selector Optional selector to project the comparable key; if omitted, returns a function to supply it later.
- * @returns Function that accepts a target and returns a predicate over the original value.
- */
-declare function equalsBy<F extends Predicate<unknown>>(guard: F): <K>(selector: (value: GuardedOf<F>) => K) => <const T extends K>(target: T) => Predicate<GuardedOf<F>>;
-declare function equalsBy<F extends Predicate<unknown>, K>(guard: F, selector: (value: GuardedOf<F>) => K): <const T extends K>(target: T) => Predicate<GuardedOf<F>>;
-/**
- * Creates a guard that matches objects having a key equal to the target value.
- *
- * @param key Property key to compare.
- * @param target Value to compare using `Object.is`.
- * @returns Predicate narrowing to objects where `key` exists and equals `target`.
- */
-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>;
-
 /**
  * Executes a guard or refinement and returns a tagged result with the value when valid.
  *
@@ -207,6 +227,14 @@ declare function safeParse(fn: (value: unknown) => boolean, value: unknown): Par
 declare function safeParseWith<T>(guard: Guard<T>): (value: unknown) => ParseResult<T>;
 declare function safeParseWith<A, B extends A>(refine: Refine<A, B>): (value: A) => ParseResult<B>;
 
+/**
+ * Converts a boolean predicate into a refinement preserving the input type.
+ *
+ * @param fn Boolean-returning function over a value of type A.
+ * @returns Refinement equivalent to the provided predicate.
+ */
+declare const predicateToRefine: <A>(fn: (value: A) => boolean) => Refine<A, A>;
+
 /**
  * Checks whether a value is a string.
  *
@@ -317,101 +345,6 @@ declare const isNull: Predicate<null>;
  */
 declare const isPrimitive: Guard<string | number | bigint | boolean | symbol | null | undefined>;
 
-/**
- * Validates an array where every element satisfies the provided guard.
- *
- * @param elementGuard Guard applied to each array element.
- * @returns Predicate narrowing to a readonly array of the guarded element type.
- */
-declare function arrayOf<F extends Predicate<unknown>>(elementGuard: F): Predicate<readonly GuardedOf<F>[]>;
-/**
- * Validates a non-empty array where every element satisfies the provided guard.
- *
- * @param elementGuard Guard applied to each array element.
- * @returns Predicate narrowing to a readonly non-empty array of the guarded element type.
- */
-declare function nonEmptyArrayOf<F extends Predicate<unknown>>(elementGuard: F): Predicate<readonly [GuardedOf<F>, ...GuardedOf<F>[]]>;
-
-/**
- * Validates a set where every value satisfies the provided guard.
- *
- * @param valueGuard Guard applied to each set value.
- * @returns Predicate narrowing to a readonly set of the guarded value type.
- */
-declare function setOf<VF extends Predicate<unknown>>(valueGuard: VF): Predicate<ReadonlySet<GuardedOf<VF>>>;
-
-/**
- * Validates a map where every key and value satisfies the provided guards.
- *
- * @param keyGuard Guard applied to each map key.
- * @param valueGuard Guard applied to each map value.
- * @returns Predicate narrowing to a readonly map with guarded key/value types.
- */
-declare function mapOf<KF extends Predicate<unknown>, VF extends Predicate<unknown>>(keyGuard: KF, valueGuard: VF): Predicate<ReadonlyMap<GuardedOf<KF>, GuardedOf<VF>>>;
-
-/**
- * Validates a fixed-length tuple by applying element-wise guards.
- *
- * @param guards Guards corresponding to each tuple position.
- * @returns Predicate that narrows to a readonly tuple of guarded element types.
- */
-declare function tupleOf<const Fs extends readonly Predicate<unknown>[]>(...guards: Fs): Predicate<{
-    readonly [K in keyof Fs]: GuardedOf<Fs[K]>;
-}>;
-
-/**
- * Combines multiple guards; passes when any one guard matches.
- *
- * @param guards One or more type guards/refinements to try.
- * @returns Predicate that narrows to the union of guarded types.
- */
-declare function oneOf<Fs extends readonly Predicate<unknown>[]>(...guards: Fs): Predicate<GuardedOf<Fs[number]>>;
-declare function oneOf<A, Fs extends readonly Predicate<A>[]>(...guards: Fs): (input: A) => input is GuardedWithin<Fs, A>;
-
-/**
- * Validates a record-like object by guarding both keys and values.
- *
- * @param keyFunction Guard for string keys (e.g., specific literal keys pattern).
- * @param valueFunction Guard applied to each value in the record.
- * @returns Predicate narrowing to a readonly record with guarded key/value types.
- */
-declare function recordOf<KF extends Predicate<string>, VF extends Predicate<unknown>>(keyFunction: KF, valueFunction: VF): Predicate<Readonly<Record<GuardedOf<KF>, GuardedOf<VF>>>>;
-
-/**
- * Marks a struct schema field as optional at the key level.
- *
- * When used inside `struct`, the property may be absent. If the property exists,
- * its value must satisfy the wrapped guard.
- *
- * @param guard Guard used to validate the property value when the key exists.
- * @returns Schema field marker understood by `struct`.
- */
-declare function optionalKey<G extends Predicate<unknown>>(guard: G): OptionalSchemaField<G>;
-/**
- * Validates an object against a field-to-guard schema.
- * Keys in the schema are required unless wrapped with `optionalKey`; optionally
- * rejects extra keys when `exact: true`.
- *
- * @param schema Record of property guards.
- * @param options When `{ exact: true }`, disallows properties not in `schema`.
- * @returns Predicate that narrows to the inferred struct type.
- */
-declare function struct<S extends Schema>(schema: S, options?: {
-    exact?: boolean;
-}): Predicate<InferSchema<S>>;
-
-/**
- * Creates a guard that matches when the input is one of the provided literal values.
- * Uses `Object.is` for exact value semantics. For large sets, keeps O(1) lookups while
- * preserving `+0` vs `-0` by tracking zero variants explicitly in addition to a `Set`.
- *
- * @param values Literal primitives to compare against (varargs or single readonly tuple array).
- * @returns Predicate narrowing to the union of the provided literal values.
- */
-declare function oneOfValues<const T extends ReadonlyArray<Primitive>>(...values: T): Predicate<T[number]>;
-declare function oneOfValues<const T extends ReadonlyArray<Primitive>>(values: T): Predicate<T[number]>;
-declare function oneOfValues<const T extends ReadonlyArray<Primitive>>(...valuesOrArray: T | [T]): Predicate<T[number]>;
-
 /**
  * Checks whether a value is a function.
  *
@@ -535,32 +468,99 @@ declare const isBlob: Predicate<Blob>;
 declare const isInstanceOf: <C extends abstract new (...args: unknown[]) => unknown>(constructor: C) => Guard<InstanceType<C>>;
 
 /**
- * Checks whether a value has the specified own key.
+ * Validates an array where every element satisfies the provided guard.
  *
- * @param key Property key to check.
- * @returns Predicate narrowing to an object with the key present.
+ * @param elementGuard Guard applied to each array element.
+ * @returns Predicate narrowing to a readonly array of the guarded element type.
  */
-declare const hasKey: <K extends PropertyKey>(key: K) => Predicate<Record<K, unknown>>;
+declare function arrayOf<F extends Predicate<unknown>>(elementGuard: F): Predicate<readonly GuardedOf<F>[]>;
 /**
- * Checks whether a value has all specified own keys.
+ * Validates a non-empty array where every element satisfies the provided guard.
  *
- * @param keys Property keys to check.
- * @returns Predicate narrowing to an object with all keys present.
+ * @param elementGuard Guard applied to each array element.
+ * @returns Predicate narrowing to a readonly non-empty array of the guarded element type.
  */
-declare const hasKeys: <const KS extends readonly [PropertyKey, ...PropertyKey[]]>(...keys: KS) => Predicate<Record<KS[number], unknown>>;
+declare function nonEmptyArrayOf<F extends Predicate<unknown>>(elementGuard: F): Predicate<readonly [GuardedOf<F>, ...GuardedOf<F>[]]>;
+
 /**
- * Builds a guard that narrows a specific key to the provided literal value.
+ * Validates a map where every key and value satisfies the provided guards.
  *
- * Given a base guard and a property key, returns a function that accepts a
- * target value and produces a guard of the base type intersected with
- * `{ [key]: target }`.
+ * @param keyGuard Guard applied to each map key.
+ * @param valueGuard Guard applied to each map value.
+ * @returns Predicate narrowing to a readonly map with guarded key/value types.
+ */
+declare function mapOf<KF extends Predicate<unknown>, VF extends Predicate<unknown>>(keyGuard: KF, valueGuard: VF): Predicate<ReadonlyMap<GuardedOf<KF>, GuardedOf<VF>>>;
+
+/**
+ * Combines multiple guards; passes when any one guard matches.
  *
- * @param guard Base guard for objects that include `key`.
- * @param key Property key to narrow.
- * @returns Builder that takes a literal `target` and returns a guard that
- * narrows `key` to that literal.
+ * @param guards One or more type guards/refinements to try.
+ * @returns Predicate that narrows to the union of guarded types.
  */
-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>>;
+declare function oneOf<Fs extends readonly Predicate<unknown>[]>(...guards: Fs): Predicate<GuardedOf<Fs[number]>>;
+declare function oneOf<A, Fs extends readonly Predicate<A>[]>(...guards: Fs): (input: A) => input is GuardedWithin<Fs, A>;
+
+/**
+ * Creates a guard that matches when the input is one of the provided literal values.
+ * Uses `Object.is` for exact value semantics. For large sets, keeps O(1) lookups while
+ * preserving `+0` vs `-0` by tracking zero variants explicitly in addition to a `Set`.
+ *
+ * @param values Literal primitives to compare against (varargs or single readonly tuple array).
+ * @returns Predicate narrowing to the union of the provided literal values.
+ */
+declare function oneOfValues<const T extends ReadonlyArray<Primitive>>(...values: T): Predicate<T[number]>;
+declare function oneOfValues<const T extends ReadonlyArray<Primitive>>(values: T): Predicate<T[number]>;
+declare function oneOfValues<const T extends ReadonlyArray<Primitive>>(...valuesOrArray: T | [T]): Predicate<T[number]>;
+
+/**
+ * Validates a record-like object by guarding both keys and values.
+ *
+ * @param keyFunction Guard for string keys (e.g., specific literal keys pattern).
+ * @param valueFunction Guard applied to each value in the record.
+ * @returns Predicate narrowing to a readonly record with guarded key/value types.
+ */
+declare function recordOf<KF extends Predicate<string>, VF extends Predicate<unknown>>(keyFunction: KF, valueFunction: VF): Predicate<Readonly<Record<GuardedOf<KF>, GuardedOf<VF>>>>;
+
+/**
+ * Validates a set where every value satisfies the provided guard.
+ *
+ * @param valueGuard Guard applied to each set value.
+ * @returns Predicate narrowing to a readonly set of the guarded value type.
+ */
+declare function setOf<VF extends Predicate<unknown>>(valueGuard: VF): Predicate<ReadonlySet<GuardedOf<VF>>>;
+
+/**
+ * Marks a struct schema field as optional at the key level.
+ *
+ * When used inside `struct`, the property may be absent. If the property exists,
+ * its value must satisfy the wrapped guard.
+ *
+ * @param guard Guard used to validate the property value when the key exists.
+ * @returns Schema field marker understood by `struct`.
+ */
+declare function optionalKey<G extends Predicate<unknown>>(guard: G): OptionalSchemaField<G>;
+/**
+ * Validates an object against a field-to-guard schema.
+ * Keys in the schema are required unless wrapped with `optionalKey`; optionally
+ * rejects extra keys when `exact: true`.
+ *
+ * @param schema Record of property guards.
+ * @param options When `{ exact: true }`, disallows properties not in `schema`.
+ * @returns Predicate that narrows to the inferred struct type.
+ */
+declare function struct<S extends Schema>(schema: S, options?: {
+    exact?: boolean;
+}): Predicate<InferSchema<S>>;
+
+/**
+ * Validates a fixed-length tuple by applying element-wise guards.
+ *
+ * @param guards Guards corresponding to each tuple position.
+ * @returns Predicate that narrows to a readonly tuple of guarded element types.
+ */
+declare function tupleOf<const Fs extends readonly Predicate<unknown>[]>(...guards: Fs): Predicate<{
+    readonly [K in keyof Fs]: GuardedOf<Fs[K]>;
+}>;
 
 /**
  * Checks whether every array element satisfies the provided predicate.