is-kit 1.5.0 → 1.6.0

package/README.md

@@ -69,7 +69,9 @@ import {
   and,
   or,
   not,
+  mapOf,
   optionalKey,
+  setOf,
   struct,
   oneOfValues,
   isNumber,
@@ -90,6 +92,8 @@ const isOther = not(isShortOrPositive);
 
 // Define object shapes
 const isRole = oneOfValues(['admin', 'member'] as const);
+const isTags = setOf(isString);
+const isScores = mapOf(isString, isNumber);
 const isUser = struct({
   id: isPositive, // number > 0
   name: isString, // string
@@ -102,6 +106,8 @@ isPositive(3); // true
 isShortOrPositive('foo'); // true
 isShortOrPositive(false); // false
 isOther('x'); // true
+isTags(new Set(['new', 'vip'])); // true
+isScores(new Map([['math', 98]])); // true
 
 const maybeUser: unknown = { id: 7, name: 'Rin', role: 'admin' };
 if (isUser(maybeUser)) {
@@ -118,7 +124,34 @@ Combine them as `optionalKey(optional(guard))` when both are allowed.
 Composed guards stay reusable:
 `isPositive` can be used standalone or as part of a `struct` definition.
 
-When validating complex shapes, reach for `struct` — and friends like `arrayOf`, `recordOf`, or `oneOf`.
+When validating complex shapes, reach for `struct` and collection
+combinators like `arrayOf`, `setOf`, `mapOf`, `recordOf`, or `oneOf`.
+
+### Collection combinators
+
+Use `arrayOf`, `setOf`, `mapOf`, and `recordOf` to validate homogeneous
+collections while preserving precise readonly types.
+
+```ts
+import {
+  arrayOf,
+  mapOf,
+  recordOf,
+  setOf,
+  isNumber,
+  isString
+} from 'is-kit';
+
+const isStringArray = arrayOf(isString);
+const isStringSet = setOf(isString);
+const isScoreMap = mapOf(isString, isNumber);
+const isStringRecord = recordOf(isString, isString);
+
+isStringArray(['a', 'b']); // true
+isStringSet(new Set(['a', 'b'])); // true
+isScoreMap(new Map([['math', 98]])); // true
+isStringRecord({ a: 'x', b: 'y' }); // true
+```
 
 ### Primitive guards
 
@@ -165,6 +198,8 @@ isInfiniteNumber(1); // false
 
 Object/built-in guards cover arrays, dates, maps/sets, and more. Use
 `isInstanceOf` when you want a reusable guard from a class constructor.
+For content-aware map/set validation, pair `isMap` / `isSet` with `mapOf`
+and `setOf`.
 
 ```ts
 import { isArray, isDate, isInstanceOf } from 'is-kit';
@@ -184,7 +219,7 @@ isAnimal({}); // false
 
 - **Define once**: `define<T>(fn)` turns a plain function into a type guard.
 - **Upgrade predicates**: `predicateToRefine(fn)` adds narrowing.
-- **Compose freely**: `and`, `or`, `not`, `oneOf`, `arrayOf`, `struct` …
+- **Compose freely**: `and`, `or`, `not`, `oneOf`, `arrayOf`, `setOf`, `mapOf`, `struct` …
 - **Stay ergonomic**: helpers like `nullable`, `optional`, `equals`, `safeParse`, `assert`, `hasKey`, `hasKeys`, `narrowKeyTo`.
 
 ### Key Helpers

package/dist/index.d.mts

@@ -325,6 +325,23 @@ declare const isPrimitive: Guard<string | number | bigint | boolean | symbol | n
  */
 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.
  *
@@ -546,4 +563,4 @@ declare function narrowKeyTo<A, K extends keyof A>(guard: Guard<A>, key: K): <co
  */
 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, 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, narrowKeyTo, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeParse, safeParseWith, 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, 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 };

package/dist/index.d.ts

@@ -325,6 +325,23 @@ declare const isPrimitive: Guard<string | number | bigint | boolean | symbol | n
  */
 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.
  *
@@ -546,4 +563,4 @@ declare function narrowKeyTo<A, K extends keyof A>(guard: Guard<A>, key: K): <co
  */
 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, 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, narrowKeyTo, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeParse, safeParseWith, 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, 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 };

package/dist/index.js

@@ -68,6 +68,7 @@ __export(index_exports, {
   isWeakMap: () => isWeakMap,
   isWeakSet: () => isWeakSet,
   isZero: () => isZero,
+  mapOf: () => mapOf,
   narrowKeyTo: () => narrowKeyTo,
   nonNull: () => nonNull,
   not: () => not,
@@ -83,6 +84,7 @@ __export(index_exports, {
   required: () => required,
   safeParse: () => safeParse,
   safeParseWith: () => safeParseWith,
+  setOf: () => setOf,
   struct: () => struct,
   toBooleanPredicates: () => toBooleanPredicates,
   tupleOf: () => tupleOf
@@ -303,6 +305,29 @@ function arrayOf(elementGuard) {
   };
 }
 
+// src/core/combinators/set.ts
+function setOf(valueGuard) {
+  return define((input) => {
+    if (!isSet(input)) return false;
+    for (const value of input.values()) {
+      if (!valueGuard(value)) return false;
+    }
+    return true;
+  });
+}
+
+// src/core/combinators/map.ts
+function mapOf(keyGuard, valueGuard) {
+  return define((input) => {
+    if (!isMap(input)) return false;
+    for (const [key, value] of input.entries()) {
+      if (!keyGuard(key)) return false;
+      if (!valueGuard(value)) return false;
+    }
+    return true;
+  });
+}
+
 // src/core/combinators/tuple.ts
 function tupleOf(...guards) {
   return (input) => {
@@ -485,6 +510,7 @@ function narrowKeyTo(guard, key) {
   isWeakMap,
   isWeakSet,
   isZero,
+  mapOf,
   narrowKeyTo,
   nonNull,
   not,
@@ -500,6 +526,7 @@ function narrowKeyTo(guard, key) {
   required,
   safeParse,
   safeParseWith,
+  setOf,
   struct,
   toBooleanPredicates,
   tupleOf

package/dist/index.mjs

@@ -212,6 +212,29 @@ function arrayOf(elementGuard) {
   };
 }
 
+// src/core/combinators/set.ts
+function setOf(valueGuard) {
+  return define((input) => {
+    if (!isSet(input)) return false;
+    for (const value of input.values()) {
+      if (!valueGuard(value)) return false;
+    }
+    return true;
+  });
+}
+
+// src/core/combinators/map.ts
+function mapOf(keyGuard, valueGuard) {
+  return define((input) => {
+    if (!isMap(input)) return false;
+    for (const [key, value] of input.entries()) {
+      if (!keyGuard(key)) return false;
+      if (!valueGuard(value)) return false;
+    }
+    return true;
+  });
+}
+
 // src/core/combinators/tuple.ts
 function tupleOf(...guards) {
   return (input) => {
@@ -393,6 +416,7 @@ export {
   isWeakMap,
   isWeakSet,
   isZero,
+  mapOf,
   narrowKeyTo,
   nonNull,
   not,
@@ -408,6 +432,7 @@ export {
   required,
   safeParse,
   safeParseWith,
+  setOf,
   struct,
   toBooleanPredicates,
   tupleOf

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "is-kit",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Make 'isXXX' easier. Let's make your code type safe and more readable!",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",