Validators

Public validator factories from mates — call them, pass optional messages, compose with withMessage.

import {
  isRequired, isEmail, minLength, maxLength, isPattern,
  isMin, isMax, isOneOf, isEqualTo,
  isArray, isObject, isString, isNumber, isBoolean,
  minItems, maxItems, withMessage,
  type ValidatorFn,
} from "mates";

// Factories — always call: isRequired(), never isRequired
const name = [isRequired(), minLength(2), maxLength(50)];
const email = [isRequired(), isEmail("Need a real email")];
const role = [isOneOf(["admin", "editor", "viewer"])];
const confirm = [isEqualTo(() => password(), "Must match")];

// Custom: (value, signal?) => string | null | Promise<…>
const notAdmin: ValidatorFn<string> = (v) =>
  v.toLowerCase() === "admin" ? "Username is taken" : null;

// withMessage replaces the failing error string
const bio = [withMessage(minLength(8), "Tell us a bit more")];

Overview

A validator is (value, signal?) => string | null | Promise<…>. Built-ins are factories: call them to get the function. Message is always the last optional argument.

On formAtom / useForm, validators must be sync. On schema / validateObject, they may return a Promise and receive an AbortSignal — see Async Validation.

This page lists everything re-exported from lib/index.ts. Additional factories exist under lib/Mutables/form/validators.ts but are not public until exported.

Where validators run

Context	Async?	Signal
`formAtom`	Sync only	Promise throws
`validateObject` / `schema`	Async OK	Second arg AbortSignal

Not public (source only)

Present in lib/Mutables/form/validators.ts but omitted from lib/index.ts: isUrl, isGoodPassword / isStrongPassword / isStrongestPassword, hasCapitalLetter / hasLowercaseLetter / hasNumber / hasSpecialCharacter, isFloat / isInteger / isPositive / isNegative, isGreaterThan / isLessThan / isBetween / isDateBetween, date helpers (isAfter, isBefore, isPast, isFuture, isInTheLast24Hours, …), and all check* boolean utilities. Standalone toFloat / toValidNumber / toFloatString are also source-only — use FormAtom methods.

Public catalog (playground)

isEmail, isPattern, min/max length, numeric bounds, isOneOf, withMessage.

import {

html, formAtom, validateAll, renderApp,

isRequired, isEmail, isPattern, minLength, maxLength,

isMin, isMax, isOneOf, withMessage,

} from "mates";

const App = () => {

const email = formAtom("", [isRequired(), isEmail("Need a real email")]);

const handle = formAtom("", [

isPattern(/^[a-z]+$/, "lowercase letters only"),

minLength(3),

maxLength(12),

]);

const age = formAtom(0, [isMin(18), isMax(120)]);

const role = formAtom("", [isOneOf(["admin", "editor", "viewer"])]);

const bio = formAtom("", [withMessage(minLength(8), "Tell us a bit more")]);

const msg = formAtom("");

const hint = (fa) =>

fa.dirty && fa.errors[0]

? html`<span class="tag tag-danger">${fa.errors.join(" · ")}</span>`

: "";

return () => html`

<label class="m-col m-gap-xs">Email ${hint(email)}

<input .value=${email()} @input=${(e) => email.set(e.target.value)} />

</label>

<label class="m-col m-gap-xs">Handle ${hint(handle)}

<input .value=${handle()} @input=${(e) => handle.set(e.target.value)} />

</label>

<label class="m-col m-gap-xs">Age ${hint(age)}

<input type="number" .value=${age()} @input=${(e) => age.set(+e.target.value)} />

</label>

<label class="m-col m-gap-xs">Role ${hint(role)}

<select .value=${role()} @change=${(e) => role.set(e.target.value)}>

Custom validators

Any (value) => string | null works alongside factories. Return null when valid.

import { html, formAtom, isRequired, minLength, renderApp } from "mates";

const notAdmin = (value) =>

value.toLowerCase() === "admin" ? "Username is taken" : null;

const slugOk = (value) =>

/^[a-z0-9-]+$/.test(value) ? null : "Use lowercase letters, numbers, and dashes";

const App = () => {

const username = formAtom("admin", [isRequired(), minLength(3), notAdmin, slugOk]);

return () => html`

Username

<input .value=${username()} @input=${(e) => username.set(e.target.value)} />

</label>

isValid ${username.isValid}

</span>

${username.dirty && username.errors[0]

? html`<span class="tag tag-danger">${username.errors[0]}</span>`

: ""}

</div>

};

renderApp(App, document.getElementById("app"));

API — Public validators

import { isRequired, isEmail, minLength, maxLength, isPattern, isMin, isMax, isOneOf, isEqualTo, isArray, isObject, isString, isNumber, isBoolean, minItems, maxItems, withMessage, type ValidatorFn } from 'mates'

Prop / Option	Type	Default	Description
`ValidatorFn<T>`	`(value: T, signal?: AbortSignal) => string \| null \| Promise<…>`	—	null = valid; non-empty string = error.
`isRequired(msg?)`	`() => ValidatorFn`	`"Required"`	Fails on empty string/array/object/null/undefined. Numbers and booleans always pass.
`isEmail(msg?)`	`() => ValidatorFn`	`"Invalid email"`	Simple email regex.
`minLength(n, msg?)`	`ValidatorFn`	`"Min {n} characters"`	String length ≥ n.
`maxLength(n, msg?)`	`ValidatorFn`	`"Max {n} characters"`	String length ≤ n.
`isPattern(re, msg?)`	`ValidatorFn`	`"Invalid format"`	regex.test(value).
`isMin(n, msg?) / isMax(n, msg?)`	`ValidatorFn`	`"Min is {n}" / "Max is {n}"`	Numeric ≥ / ≤ bounds.
`isOneOf(values, msg?)`	`ValidatorFn`	`"Must be one of: …"`	Value must be in the list.
`isEqualTo(getter, msg?)`	`ValidatorFn`	`"Must match"`	Compares value === getter(). Pass () => otherField().
`isArray / isObject / isString / isNumber / isBoolean`	`(msg?) => ValidatorFn`	`"Must be a …"`	Runtime type checks.
`minItems(n, msg?) / maxItems(n, msg?)`	`ValidatorFn`	`"Min\|Max {n} items"`	Array length bounds.
`withMessage(fn, msg)`	`ValidatorFn`	—	Wrap a validator; on failure return msg instead of the original string. Supports sync/async.