is-kit 1.6.4 → 1.7.1

package/README.md

@@ -166,7 +166,7 @@ Use `not(...)` when you want the complement of an existing guard or refinement.
 Use `struct` for plain-object payloads. Keys are required by default.
 
 ```ts
-import { isNumber, isString, optionalKey, struct } from 'is-kit';
+import { isNumber, isString, optional, optionalKey, struct } from 'is-kit';
 
 const isProfile = struct(
   {
@@ -176,14 +176,6 @@ const isProfile = struct(
   },
   { exact: true }
 );
-```
-
-`optionalKey(guard)` means the property may be missing.
-
-If the property must exist but the value may be `undefined`, use `optional(guard)` instead.
-
-```ts
-import { isString, optional, optionalKey, struct } from 'is-kit';
 
 const isConfig = struct({
   label: isString,
@@ -192,6 +184,12 @@ const isConfig = struct({
 });
 ```
 
+`optionalKey(guard)` means the property may be missing.
+
+Use `struct(schema, { exact: true })` when extra keys should be rejected.
+
+If the property must exist but the value may be `undefined`, use `optional(guard)` instead.
+
 ### 5. Validate arrays, tuples, maps, sets, and records
 
 Collection combinators keep your element guards reusable.
@@ -202,12 +200,14 @@ import {
   isNumber,
   isString,
   mapOf,
+  nonEmptyArrayOf,
   recordOf,
   setOf,
   tupleOf
 } from 'is-kit';
 
 const isStringArray = arrayOf(isString);
+const isNonEmptyTagList = nonEmptyArrayOf(isString);
 const isPoint = tupleOf(isNumber, isNumber);
 const isTagSet = setOf(isString);
 const isScoreMap = mapOf(isString, isNumber);
@@ -356,7 +356,7 @@ The library is organized around a few small building blocks:
 - **Primitives**: `isString`, `isNumber`, `isBoolean`, `isInteger`, ...
 - **Composition**: `define`, `and`, `andAll`, `or`, `not`, `oneOf`
 - **Object shapes**: `struct`, `optionalKey`, `hasKey`, `hasKeys`, `narrowKeyTo`
-- **Collections**: `arrayOf`, `tupleOf`, `setOf`, `mapOf`, `recordOf`
+- **Collections**: `arrayOf`, `nonEmptyArrayOf`, `tupleOf`, `setOf`, `mapOf`, `recordOf`
 - **Literals**: `oneOfValues`, `equals`, `equalsBy`, `equalsKey`
 - **Nullish handling**: `nullable`, `nonNull`, `nullish`, `optional`, `required`
 - **Result helpers**: `safeParse`, `safeParseWith`, `assert`

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,94 +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 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.
  *
@@ -528,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.
@@ -606,4 +613,4 @@ declare const everyOwnEnumerableEntry: (values: Record<string, unknown>, keyPred
  */
 declare const toBooleanPredicates: <A>(predicates: readonly ((value: A) => boolean)[]) => ReadonlyArray<(value: A) => boolean>;
 
-export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type OptionalSchemaField, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type Schema, type SchemaField, 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, isFiniteNumber, isFunction, isInfiniteNumber, isInstanceOf, isInteger, isIterable, isMap, isNaN, isNegative, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, mapOf, narrowKeyTo, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf };
+export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type OptionalSchemaField, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type Schema, type SchemaField, 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, isFiniteNumber, isFunction, isInfiniteNumber, isInstanceOf, isInteger, isIterable, isMap, isNaN, isNegative, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, mapOf, narrowKeyTo, nonEmptyArrayOf, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf };