@thi.ng/validate 0.3.5 → 0.4.0

package/README.md

@@ -8,7 +8,7 @@
 
 > [!NOTE]
 
-> This is one of 215 standalone projects. LLM-free, human-made and
+> This is one of 216 standalone projects. LLM-free, human-made and
 > cared for software, maintained as part of the
 > [@thi.ng/umbrella](https://codeberg.org/thi.ng/umbrella/) ecosystem and
 > anti-framework.
@@ -21,6 +21,7 @@
   - [Built-in validators](#built-in-validators)
   - [Combinators](#combinators)
 - [Status](#status)
+- [Support packages](#support-packages)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
 - [API](#api)
@@ -77,11 +78,15 @@ try {
 - [`isBoolean()`](https://docs.thi.ng/umbrella/validate/functions/isBoolean.html)
 - [`isDate()`](https://docs.thi.ng/umbrella/validate/functions/isDate.html)
 - [`isEnum()`](https://docs.thi.ng/umbrella/validate/functions/isEnum.html)
-- [`isInRange()`](https://docs.thi.ng/umbrella/validate/functions/isInRange.html)
+- [`isEqual()`](https://docs.thi.ng/umbrella/validate/functions/isEqual.html)
+- [`isInClosedInterval()`](https://docs.thi.ng/umbrella/validate/functions/isInClosedInterval.html)
+- [`isInOpenInterval()`](https://docs.thi.ng/umbrella/validate/functions/isInOpenInterval.html)
+- [`isInteger()`](https://docs.thi.ng/umbrella/validate/functions/isInteger.html)
 - [`isLength()`](https://docs.thi.ng/umbrella/validate/functions/isLength.html)
 - [`isMaxLength()`](https://docs.thi.ng/umbrella/validate/functions/isMaxLength.html)
 - [`isMinLength()`](https://docs.thi.ng/umbrella/validate/functions/isMinLength.html)
 - [`isMinMaxLength()`](https://docs.thi.ng/umbrella/validate/functions/isMinMaxLength.html)
+- [`isMultipleOf()`](https://docs.thi.ng/umbrella/validate/functions/isMultipleOf.html)
 - [`isNegative()`](https://docs.thi.ng/umbrella/validate/functions/isNegative.html)
 - [`isNonNegative()`](https://docs.thi.ng/umbrella/validate/functions/isNonNegative.html)
 - [`isNonPositive()`](https://docs.thi.ng/umbrella/validate/functions/isNonPositive.html)
@@ -110,6 +115,10 @@ try {
 
 [Search or submit any issues for this package](https://codeberg.org/thi.ng/umbrella/issues?q=%5Bvalidate%5D)
 
+## Support packages
+
+- [@thi.ng/validate-schema](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/validate-schema) - JSON schema validation layer for [@thi.ng/validate](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/validate)
+
 ## Installation
 
 ```bash
@@ -136,12 +145,13 @@ For Node.js REPL:
 const val = await import("@thi.ng/validate");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.34 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.50 KB
 
 ## Dependencies
 
 - [@thi.ng/api](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/api)
 - [@thi.ng/checks](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/checks)
+- [@thi.ng/equiv](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/equiv)
 - [@thi.ng/errors](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/errors)
 
 Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)

package/api.d.ts

@@ -12,6 +12,7 @@ export interface Validator {
     /**
      * Optional error message (or function to produce such).
      */
-    msg?: string | Fn<any, string>;
+    msg?: ValidatorMsg;
 }
+export type ValidatorMsg = string | Fn<any, string>;
 //# sourceMappingURL=api.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@thi.ng/validate",
-	"version": "0.3.5",
+	"version": "0.4.0",
 	"description": "Functional, composable, fully extensible, predicate-based value validation with customizable error messages",
 	"type": "module",
 	"module": "./index.js",
@@ -40,9 +40,10 @@
 		"tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
 	},
 	"dependencies": {
-		"@thi.ng/api": "^8.12.24",
-		"@thi.ng/checks": "^3.9.4",
-		"@thi.ng/errors": "^2.6.13"
+		"@thi.ng/api": "^8.12.26",
+		"@thi.ng/checks": "^3.10.0",
+		"@thi.ng/equiv": "^2.1.115",
+		"@thi.ng/errors": "^2.6.15"
 	},
 	"devDependencies": {
 		"esbuild": "^0.28.0",
@@ -85,5 +86,5 @@
 		"status": "alpha",
 		"year": 2026
 	},
-	"gitHead": "b302822c51b2ab255f8f27f8dd010433d95f29df"
+	"gitHead": "c47c56420bcae2e0477d252a497be44f08ca185a"
 }

package/validators.d.ts

@@ -1,4 +1,4 @@
-import type { Validator } from "./api.js";
+import type { Validator, ValidatorMsg } from "./api.js";
 /**
  * Error type thrown by validation functions.
  */
@@ -80,7 +80,7 @@ export declare const optional: (first: Validator, ...rest: Validator[]) => Valid
  * @param validator
  * @param msg
  */
-export declare const not: ({ coerce, valid, msg: $msg }: Validator, msg?: Validator["msg"]) => Validator;
+export declare const not: ({ coerce, valid, msg: $msg }: Validator, msg?: ValidatorMsg) => Validator;
 /**
  * Higher order validator. Takes one or more validators and returns a new one
  * which will apply the validators in given order, and return successfully with
@@ -109,27 +109,42 @@ export declare const every: (first: Validator, ...rest: Validator[]) => Validato
  *
  * @param msg
  */
-export declare const isUndefined: (msg?: Validator["msg"]) => Validator;
+export declare const isUndefined: (msg?: ValidatorMsg) => Validator;
 /**
  * Returns validator to check if value is nullish.
  *
  * @param msg
  */
-export declare const isNullish: (msg?: Validator["msg"]) => Validator;
-export declare const isArray: (msg?: Validator["msg"]) => Validator;
-export declare const isArrayOf: (validators: Validator | Validator[], msg?: Validator["msg"]) => Validator;
-export declare const isBoolean: (msg?: Validator["msg"]) => Validator;
-export declare const isNumber: (msg?: Validator["msg"]) => Validator;
-export declare const isString: (msg?: Validator["msg"]) => Validator;
-export declare const isDate: (msg?: Validator["msg"]) => Validator;
-export declare const isFunction: (msg?: Validator["msg"]) => Validator;
-export declare const isRegExp: (msg?: Validator["msg"]) => Validator;
+export declare const isNullish: (msg?: ValidatorMsg) => Validator;
+/**
+ * Returns validator to check if value equals `expected` value (uses
+ * [`equiv()`](https://thi.ng/equiv) for equality checking).
+ *
+ * @param expected
+ * @param msg
+ */
+export declare const isEqual: (expected: any, msg?: ValidatorMsg) => Validator;
+export declare const isArray: (msg?: ValidatorMsg) => Validator;
+export declare const isArrayOf: (validators: Validator | Validator[], msg?: ValidatorMsg) => Validator;
+export declare const isBoolean: (msg?: ValidatorMsg) => Validator;
+export declare const isNumber: (msg?: ValidatorMsg) => Validator;
+/**
+ * Return validator to check if value is an integer (not necessarily in the
+ * 32bit range, but merely if the value has no fractional part).
+ *
+ * @param msg
+ */
+export declare const isInteger: (msg?: ValidatorMsg) => Validator;
+export declare const isString: (msg?: ValidatorMsg) => Validator;
+export declare const isDate: (msg?: ValidatorMsg) => Validator;
+export declare const isFunction: (msg?: ValidatorMsg) => Validator;
+export declare const isRegExp: (msg?: ValidatorMsg) => Validator;
 /**
  * Returns validator which checks that given value is a plain object (not class).
  *
  * @param msg
  */
-export declare const isObject: (msg?: Validator["msg"]) => Validator;
+export declare const isObject: (msg?: ValidatorMsg) => Validator;
 /**
  * Returns validator to check if value is a plain object and the values of all
  * its keys are matching given validators.
@@ -137,14 +152,23 @@ export declare const isObject: (msg?: Validator["msg"]) => Validator;
  * @param validators
  * @param msg
  */
-export declare const isObjectOf: (validators: Validator | Validator[], msg?: Validator["msg"]) => Validator;
-export declare const isTypedArray: (msg?: Validator["msg"]) => Validator;
+export declare const isObjectOf: (validators: Validator | Validator[], msg?: ValidatorMsg) => Validator;
+export declare const isTypedArray: (msg?: ValidatorMsg) => Validator;
 /**
  * Returns validator to check if value is a `Uint8Array`.
  *
  * @param msg
  */
-export declare const isU8Array: (msg?: Validator["msg"]) => Validator;
+export declare const isU8Array: (msg?: ValidatorMsg) => Validator;
+/**
+ * Returns validator to check if value is a number and a multiple of given
+ * `base` (using `eps` tolerance, default: 1e-6).
+ *
+ * @param base
+ * @param eps
+ * @param msg
+ */
+export declare const isMultipleOf: (base: number, eps?: number, msg?: ValidatorMsg) => Validator;
 /**
  * Returns validator to ensure given `keys` are present in an object, optionally
  * also checks their values are `nonNullish` (default: false). If `onlyKeys` is
@@ -156,7 +180,7 @@ export declare const isU8Array: (msg?: Validator["msg"]) => Validator;
  * @param onlyKeys
  * @param msg
  */
-export declare const hasRequiredKeys: (keys: string[], nonNullish?: boolean, onlyKeys?: boolean, msg?: Validator["msg"]) => Validator;
+export declare const hasRequiredKeys: (keys: string[], nonNullish?: boolean, onlyKeys?: boolean, msg?: ValidatorMsg) => Validator;
 /**
  * Takes object of validators to check values of different keys in an object.
  * Returns validator which applies all checks, optionally also ensures no other
@@ -166,7 +190,7 @@ export declare const hasRequiredKeys: (keys: string[], nonNullish?: boolean, onl
  * @param onlyKeys
  */
 export declare const hasKeysOf: (validators: Record<PropertyKey, Validator | Validator[]>, onlyKeys?: boolean) => Validator;
-export declare const hasRequiredPatternKeys: (pattern: RegExp, nonNullish?: boolean, onlyKeys?: boolean, msg?: Validator["msg"]) => Validator;
+export declare const hasRequiredPatternKeys: (pattern: RegExp, nonNullish?: boolean, onlyKeys?: boolean, msg?: ValidatorMsg) => Validator;
 export declare const hasPatternKeysOf: (pattern: RegExp, validators: Validator | Validator[], onlyKeys?: boolean) => Validator;
 /**
  * Returns validator to check if value is one of the given options. Values are
@@ -175,7 +199,7 @@ export declare const hasPatternKeysOf: (pattern: RegExp, validators: Validator |
  * @param opts
  * @param msg
  */
-export declare const isEnum: <T>(opts: T[], msg?: Validator["msg"]) => Validator;
+export declare const isEnum: <T>(opts: T[], msg?: ValidatorMsg) => Validator;
 /**
  * Returns validator to check if value is in given closed [min,max] interval.
  *
@@ -183,20 +207,23 @@ export declare const isEnum: <T>(opts: T[], msg?: Validator["msg"]) => Validator
  * @param max
  * @param msg
  */
-export declare const isInRange: <T extends number | string>(min: T, max: T, msg?: Validator["msg"]) => Validator;
-export declare const isPositive: (msg?: Validator["msg"]) => Validator;
-export declare const isNegative: (msg?: Validator["msg"]) => Validator;
-export declare const isNonPositive: (msg?: Validator["msg"]) => Validator;
-export declare const isNonNegative: (msg?: Validator["msg"]) => Validator;
-export declare const isLength: (n: number, msg?: Validator["msg"]) => Validator;
-export declare const isMinLength: (n: number, msg?: Validator["msg"]) => Validator;
-export declare const isMaxLength: (n: number, msg?: Validator["msg"]) => Validator;
-export declare const isMinMaxLength: (min: number, max: number, msg?: Validator["msg"]) => Validator;
+export declare const isInClosedInterval: (min: number, max: number, msg?: ValidatorMsg) => Validator;
+/** @deprecated renamed to {@link isInClosedInterval} */
+export declare const isInRange: (min: number, max: number, msg?: ValidatorMsg) => Validator;
+export declare const isInOpenInterval: (min: number, max: number, msg?: ValidatorMsg) => Validator;
+export declare const isPositive: (msg?: ValidatorMsg) => Validator;
+export declare const isNegative: (msg?: ValidatorMsg) => Validator;
+export declare const isNonPositive: (msg?: ValidatorMsg) => Validator;
+export declare const isNonNegative: (msg?: ValidatorMsg) => Validator;
+export declare const isLength: (n: number, msg?: ValidatorMsg) => Validator;
+export declare const isMinLength: (n: number, msg?: ValidatorMsg) => Validator;
+export declare const isMaxLength: (n: number, msg?: ValidatorMsg) => Validator;
+export declare const isMinMaxLength: (min: number, max: number, msg?: ValidatorMsg) => Validator;
 /**
  * Returns validator to check if value is a string and matches given regexp.
  *
  * @param re
  * @param msg
  */
-export declare const matchesRegexp: (re: RegExp, msg?: Validator["msg"]) => Validator;
+export declare const matchesRegexp: (re: RegExp, msg?: ValidatorMsg) => Validator;
 //# sourceMappingURL=validators.d.ts.map

package/validators.js

@@ -3,12 +3,14 @@ import { isArrayOf as $isArrayOf } from "@thi.ng/checks/is-array-of";
 import { isBoolean as $isBoolean } from "@thi.ng/checks/is-boolean";
 import { isDate as $isDate } from "@thi.ng/checks/is-date";
 import { isFunction as $isFunction } from "@thi.ng/checks/is-function";
+import { isMultipleOf as $isMultipleOf } from "@thi.ng/checks/is-multiple-of";
 import { isNumber as $isNumber } from "@thi.ng/checks/is-number";
 import { isObjectOf as $isObjectOf } from "@thi.ng/checks/is-object-of";
 import { isPlainObject } from "@thi.ng/checks/is-plain-object";
 import { isRegExp as $isRegExp } from "@thi.ng/checks/is-regexp";
 import { isString as $isString } from "@thi.ng/checks/is-string";
 import { isTypedArray as $isTypedArray } from "@thi.ng/checks/is-typedarray";
+import { equiv } from "@thi.ng/equiv";
 import { defError } from "@thi.ng/errors/deferror";
 const ValidationError = defError(() => `validation error`);
 const validator = (...validators) => (x) => {
@@ -65,66 +67,80 @@ const every = (first, ...rest) => ({
 });
 const isUndefined = (msg) => ({
   valid: (x) => x === void 0,
-  msg: msg ?? `expected undefined value`
+  msg: msg ?? __expectedVal("undefined")
 });
 const isNullish = (msg) => ({
   valid: (x) => x === null,
-  msg: msg ?? `expected nullish value`
+  msg: msg ?? __expectedVal("nullish")
+});
+const isEqual = (expected, msg) => ({
+  valid: (x) => equiv(x, expected),
+  msg: msg ?? __expected(`value to be: ${JSON.stringify(expected) ?? "null"}`)
 });
 const isArray = (msg) => ({
   valid: $isArray,
-  msg: msg ?? `required array value`
+  msg: msg ?? __expectedVal("array")
 });
 const isArrayOf = (validators, msg) => ({
   valid: $isArrayOf(validator(...__asArray(validators))),
-  msg: msg ?? `required array value`
+  msg: msg ?? __expectedVal("array")
 });
 const isBoolean = (msg) => ({
   valid: $isBoolean,
-  msg: msg ?? `required boolean value`
+  msg: msg ?? __expectedVal("boolean")
 });
 const isNumber = (msg) => ({
   valid: $isNumber,
-  msg: msg ?? `required number value`
+  msg: msg ?? __expectedVal("number")
+});
+const isInteger = (msg) => ({
+  valid: (x) => $isNumber(x) && Math.trunc(x) === x,
+  msg: msg ?? __expectedVal("integer")
 });
 const isString = (msg) => ({
   valid: $isString,
-  msg: msg ?? `required string value`
+  msg: msg ?? __expectedVal("string")
 });
 const isDate = (msg) => ({
   valid: $isDate,
-  msg: msg ?? `required date value`
+  msg: msg ?? __expectedVal("date")
 });
 const isFunction = (msg) => ({
   valid: $isFunction,
-  msg: msg ?? `required function value`
+  msg: msg ?? __expectedVal("function")
 });
 const isRegExp = (msg) => ({
   valid: $isRegExp,
-  msg: msg ?? `required regexp value`
+  msg: msg ?? __expectedVal("regexp")
 });
 const isObject = (msg) => ({
   valid: isPlainObject,
-  msg: msg ?? `required plain object value`
+  msg: msg ?? __expectedVal("object")
 });
 const isObjectOf = (validators, msg) => ({
   valid: $isObjectOf(validator(...__asArray(validators))),
-  msg: msg ?? `required object value`
+  msg: msg ?? __expectedVal("object")
 });
 const isTypedArray = (msg) => ({
   valid: $isTypedArray,
-  msg: msg ?? `required typed array value`
+  msg: msg ?? __expectedVal(`typed array`)
 });
 const isU8Array = (msg) => ({
   valid: (x) => x instanceof Uint8Array,
-  msg: msg ?? `required byte array value`
+  msg: msg ?? __expectedVal(`byte array`)
+});
+const isMultipleOf = (base, eps, msg) => ({
+  valid: (x) => $isMultipleOf(base, x, eps),
+  msg: msg ?? __expected(`number value, a multiple of ${base}`)
 });
 const hasRequiredKeys = (keys, nonNullish = false, onlyKeys = false, msg) => ({
   valid: (x) => {
     if (onlyKeys) __onlyKeys(keys, x);
     return keys.every((k) => k in x && (nonNullish ? x[k] != null : true));
   },
-  msg: msg ?? `required keys: ${keys.join(", ")}${nonNullish ? " (values must be non-nullish)" : ""}`
+  msg: msg ?? __expected(
+    `keys: ${keys.join(", ")}${nonNullish ? " (values must be non-nullish)" : ""}`
+  )
 });
 const hasKeysOf = (validators, onlyKeys = false) => ({
   valid: (x) => {
@@ -154,7 +170,9 @@ const hasRequiredPatternKeys = (pattern, nonNullish = false, onlyKeys = false, m
     }
     return found;
   },
-  msg: msg ?? `required pattern keys: ${pattern}${nonNullish ? " (values must be non-nullish)" : ""}`
+  msg: msg ?? __expected(
+    `pattern keys: ${pattern}${nonNullish ? " (values must be non-nullish)" : ""}`
+  )
 });
 const hasPatternKeysOf = (pattern, validators, onlyKeys = false) => {
   const fn = validator(...__asArray(validators));
@@ -187,48 +205,55 @@ const __disallowedKey = (key) => {
 };
 const isEnum = (opts, msg) => ({
   valid: (x) => opts.includes(x),
-  msg: msg ?? `required value to be one of: ${opts.join(", ")}`
+  msg: msg ?? __expected(`value to be one of: ${opts.join(", ")}`)
 });
-const isInRange = (min, max, msg) => ({
+const isInClosedInterval = (min, max, msg) => ({
   valid: (x) => x >= min && x <= max,
-  msg: msg ?? ((x) => `value ${x} not in range [${min},${max}]`)
+  msg: msg ?? (min > -Infinity ? max < Infinity ? __expected(`value in closed interval [${min},${max}]`) : __expected(`value >= ${min}`) : max < Infinity ? __expected(`value <= ${max}`) : "")
+});
+const isInRange = isInClosedInterval;
+const isInOpenInterval = (min, max, msg) => ({
+  valid: (x) => x > min && x < max,
+  msg: msg ?? (min > -Infinity ? max < Infinity ? __expected(`value in open interval (${min},${max})`) : __expected(`value > ${min}`) : max < Infinity ? __expected(`value < ${max}`) : "")
 });
 const isPositive = (msg) => ({
   valid: (x) => x > 0,
-  msg: msg ?? `required positive value`
+  msg: msg ?? __expectedVal("positive")
 });
 const isNegative = (msg) => ({
   valid: (x) => x < 0,
-  msg: msg ?? `required negative number`
+  msg: msg ?? __expectedVal("negative")
 });
 const isNonPositive = (msg) => ({
   valid: (x) => x <= 0,
-  msg: msg ?? `required non-positive value`
+  msg: msg ?? __expectedVal("non-positive")
 });
 const isNonNegative = (msg) => ({
   valid: (x) => x >= 0,
-  msg: msg ?? `required non-negative value`
+  msg: msg ?? __expectedVal("non-negative")
 });
 const isLength = (n, msg) => ({
   valid: (x) => x?.length === n,
-  msg: msg ?? `required length (${n})`
+  msg: msg ?? __expected(`length of ${n}`)
 });
 const isMinLength = (n, msg) => ({
   valid: (x) => x?.length >= n,
-  msg: msg ?? `required min. length (${n})`
+  msg: msg ?? __expected(`min. length ${n}`)
 });
 const isMaxLength = (n, msg) => ({
   valid: (x) => x?.length <= n,
-  msg: msg ?? `required max. length (${n})`
+  msg: msg ?? __expected(`max. length ${n}`)
 });
-const isMinMaxLength = (min, max, msg) => ({
+const isMinMaxLength = (min, max, msg) => min > 0 ? max < Infinity ? min !== max ? {
   valid: (x) => x?.length >= min && x?.length <= max,
-  msg: msg ?? `length not in [${min},${max}] range`
-});
+  msg: msg ?? __expected(`length in [${min},${max}] range`)
+} : isLength(min) : isMinLength(min) : max < Infinity ? isMaxLength(max) : ALWAYS;
 const matchesRegexp = (re, msg) => ({
   valid: (x) => $isString(x) && re.test(x),
-  msg: msg ?? `doesn't match pattern`
+  msg: msg ?? __expected(`pattern: ${re.source}`)
 });
+const __expected = (x) => `expected ${x}`;
+const __expectedVal = (x) => `expected ${x} value`;
 export {
   ALWAYS,
   NEVER,
@@ -243,12 +268,17 @@ export {
   isBoolean,
   isDate,
   isEnum,
+  isEqual,
   isFunction,
+  isInClosedInterval,
+  isInOpenInterval,
   isInRange,
+  isInteger,
   isLength,
   isMaxLength,
   isMinLength,
   isMinMaxLength,
+  isMultipleOf,
   isNegative,
   isNonNegative,
   isNonPositive,