@aventara/core 1.0.0-rc.0 → 1.0.0-rc.1

package/src/runtime/field-check.evaluator.ts

@@ -0,0 +1,720 @@
+import type {
+	AvFieldCheck,
+	AvFieldCheckFormat,
+	AvFieldFormatCheck,
+} from "../contracts/field-check.js";
+import type {
+	AvValidationCode,
+	AvValidationIssue,
+} from "../operations/validation-code.js";
+
+// The field checks of a Contract, evaluated: the rules a field's validators and a
+// Json Shape node's checks state, as zod's check name and parameters. The server
+// runs this module on a field's value after its field pipes, the Json Shape
+// checker runs it on a shape node's value, and a generated client runs a copy of
+// it before it sends a request. It reads only the Contract's check data, so it
+// needs no zod and nothing from a configuration, and it imports nothing but
+// types and reads no platform type a project may not declare: a generator copies
+// it whole, and the copy compiles in any TypeScript project.
+//
+// The semantics are zod's (4.6), check by check: a string's length is counted in
+// Unicode code points, a float's `multipleOf` allows zod's rounding tolerance, a
+// bigint's is exact, and every named format is zod's own pattern or test, copied
+// below and held to zod by Aventara's own tests. A `decimal`'s bounds and
+// multiples are exact: compared digit by digit, never through a float, and never
+// by expanding an exponent a caller wrote.
+//
+// A failed check is one issue on an existing validation code: `V1004` for a
+// range, length or size, `V1003` for a pattern or format. The issue carries zod's
+// check name and the check's parameters as the Contract stores them, so a
+// program can read which rule failed, and a message for a person.
+
+/** What a check judges: the runtime form of the value it is given. */
+export type FieldCheckSubject =
+	| "string"
+	| "number"
+	| "bigint"
+	| "decimal"
+	| "datetime"
+	| "bytes";
+
+// No bigint literal: a project may compile this copy for a target before
+// ES2020, where `0n` is a type error and `BigInt(0)` is not.
+
+/**
+ * What a check judges on a field of each scalar type that takes checks; a field
+ * of any other type (an enum's) holds a string.
+ */
+export const FIELD_CHECK_SUBJECTS: Readonly<Record<string, FieldCheckSubject>> =
+	{
+		string: "string",
+		int: "number",
+		float: "number",
+		bigint: "bigint",
+		decimal: "decimal",
+		datetime: "datetime",
+		bytes: "bytes",
+	};
+
+type Path = readonly (string | number)[];
+
+// ---- named formats, as zod 4.6 checks them -------------------------------
+//
+// Copied from zod (MIT License, Copyright (c) 2025 Colin McDonnell):
+// `v4/core/regexes.js` and the format checks of `v4/core/schemas.js`, with each
+// builder's default options (`z.uuid()` any version, `z.iso.datetime()` UTC
+// only and any precision, `z.iso.time()` with optional seconds).
+
+const DATE_SOURCE =
+	"(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))";
+const HHMM = "(?:[01]\\d|2[0-3]):[0-5]\\d";
+const IPV6_ALPHABET = /^[0-9a-fA-F:.]+$/;
+const CREDIT_CARD = /^\d(?:[ -]?\d){11,18}$/;
+const IBAN = /^[A-Z]{2}(?!00|01|99)\d{2}[A-Z0-9]{11,30}$/;
+
+const FORMAT_PATTERNS: Readonly<Partial<Record<AvFieldCheckFormat, RegExp>>> = {
+	email:
+		/^(?:[A-Za-z0-9_'+-]+\.)*[A-Za-z0-9_'+-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9-]*\.)+[A-Za-z]{2,}$/,
+	// zod writes this one as a string source: its class mixes a combining mark
+	// with the characters it combines with, on purpose.
+	// biome-ignore lint/complexity/useRegexLiterals: a literal trips noMisleadingCharacterClass
+	emoji: new RegExp(
+		"^(?=[\\s\\S]*[\\p{Extended_Pictographic}\\p{Regional_Indicator}\\u20E3])[\\p{Extended_Pictographic}\\p{Emoji_Component}]+$",
+		"u",
+	),
+	uuid: /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/,
+	guid: /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$/,
+	nanoid: /^[a-zA-Z0-9_-]{21}$/,
+	cuid: /^[cC][0-9a-z]{6,}$/,
+	cuid2: /^[0-9a-z]+$/,
+	ulid: /^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$/,
+	xid: /^[0-9a-vA-V]{20}$/,
+	ksuid: /^[A-Za-z0-9]{27}$/,
+	datetime: new RegExp(
+		`^${DATE_SOURCE}T(?:${HHMM}:[0-5]\\d(?:\\.\\d+)?(?:Z))$`,
+	),
+	date: new RegExp(`^${DATE_SOURCE}$`),
+	time: new RegExp(`^${HHMM}(?::[0-5]\\d(?:\\.\\d+)?)?$`),
+	duration:
+		/^P(?:(\d+W)|(?!.*W)(?=\d|T\d)(\d+Y)?(\d+M)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+([.,]\d+)?S)?)?)$/,
+	ipv4: /^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$/,
+	cidrv4:
+		/^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\/([0-9]|[1-2][0-9]|3[0-2])$/,
+	e164: /^\+[1-9]\d{6,14}$/,
+};
+
+// `URL` and `atob` are every JavaScript runtime's, but their types are DOM's or
+// Node's, which a project may not declare: they are read off `globalThis`,
+// typed as far as this module calls them.
+/** The platform's `URL` and `atob`, as this module calls them. */
+const platform = globalThis as unknown as {
+	readonly URL?: {
+		new (input: string): unknown;
+		readonly canParse?: (input: string) => boolean;
+	};
+	readonly atob?: (data: string) => string;
+};
+
+function canParseUrl(input: string): boolean {
+	const Url = platform.URL;
+	if (Url === undefined) {
+		return false;
+	}
+	try {
+		if (typeof Url.canParse === "function") {
+			return Url.canParse(input);
+		}
+		new Url(input);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** `atob`: a base64 string's bytes as a binary string; throws when it is not base64. */
+function decodeBase64(value: string): string {
+	if (platform.atob === undefined) {
+		throw new TypeError("No atob is available here.");
+	}
+	return platform.atob(value);
+}
+
+function isIpv6(value: string): boolean {
+	return IPV6_ALPHABET.test(value) && canParseUrl(`http://[${value}]`);
+}
+
+function isCidrv6(value: string): boolean {
+	const parts = value.split("/");
+	if (parts.length !== 2) {
+		return false;
+	}
+	const [address, prefix] = parts as [string, string];
+	const bits = Number(prefix);
+	return (
+		prefix !== "" &&
+		`${bits}` === prefix &&
+		bits >= 0 &&
+		bits <= 128 &&
+		isIpv6(address)
+	);
+}
+
+function isBase64(value: string): boolean {
+	if (value === "") {
+		return true;
+	}
+	if (/\s/.test(value) || value.length % 4 !== 0) {
+		return false;
+	}
+	try {
+		decodeBase64(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function isBase64Url(value: string): boolean {
+	if (!/^[A-Za-z0-9_-]*$/.test(value)) {
+		return false;
+	}
+	const base64 = value.replace(/[-_]/g, (char) => (char === "-" ? "+" : "/"));
+	return isBase64(base64.padEnd(Math.ceil(base64.length / 4) * 4, "="));
+}
+
+function isLuhn(digits: string): boolean {
+	let length = digits.length;
+	let bit = 1;
+	let sum = 0;
+	while (length) {
+		const value = digits.charCodeAt(--length) - 48;
+		bit ^= 1;
+		sum += bit ? ([0, 2, 4, 6, 8, 1, 3, 5, 7, 9][value] ?? 0) : value;
+	}
+	return sum % 10 === 0;
+}
+
+function isIbanChecksum(iban: string): boolean {
+	let remainder = 0;
+	const step = (code: number): void => {
+		remainder =
+			(code >= 65
+				? remainder * 100 + (code - 55)
+				: remainder * 10 + (code - 48)) % 97;
+	};
+	for (let index = 4; index < iban.length; index += 1) {
+		step(iban.charCodeAt(index));
+	}
+	for (let index = 0; index < 4; index += 1) {
+		step(iban.charCodeAt(index));
+	}
+	return remainder === 1;
+}
+
+function isJwt(token: string): boolean {
+	try {
+		const parts = token.split(".");
+		if (parts.length !== 3 || !parts[0]) {
+			return false;
+		}
+		const header = JSON.parse(decodeBase64(parts[0])) as {
+			readonly typ?: unknown;
+			readonly alg?: unknown;
+		};
+		if ("typ" in header && header.typ !== "JWT") {
+			return false;
+		}
+		return Boolean(header.alg);
+	} catch {
+		return false;
+	}
+}
+
+function isJsonString(value: string): boolean {
+	try {
+		JSON.parse(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Whether `value` is the named format, as zod checks it. */
+function matchesFormat(format: AvFieldCheckFormat, value: string): boolean {
+	switch (format) {
+		case "url":
+			return canParseUrl(value.trim());
+		case "ipv6":
+			return isIpv6(value);
+		case "cidrv6":
+			return isCidrv6(value);
+		case "base64":
+			return isBase64(value);
+		case "base64url":
+			return isBase64Url(value);
+		case "credit_card":
+			return CREDIT_CARD.test(value) && isLuhn(value.replace(/[- ]/g, ""));
+		case "iban":
+			return IBAN.test(value) && isIbanChecksum(value);
+		case "jwt":
+			return isJwt(value);
+		case "json_string":
+			return isJsonString(value);
+		default: {
+			return FORMAT_PATTERNS[format]?.test(value) === true;
+		}
+	}
+}
+
+// ---- exact decimals -------------------------------------------------------
+
+/** A decimal as sign, significant digits and the power of ten of the first one. */
+type DecimalParts = {
+	readonly negative: boolean;
+	/** No leading or trailing zero; `""` for zero. */
+	readonly digits: string;
+	/** The power of ten of `digits`' first digit. */
+	readonly exponent: number;
+};
+
+const DECIMAL = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/;
+
+function decimalParts(text: string): DecimalParts | undefined {
+	const match = DECIMAL.exec(text);
+	if (match === null) {
+		return undefined;
+	}
+	const [, sign, whole = "", fraction = "", power = "0"] = match;
+	const all = `${whole}${fraction}`;
+	const leading = all.length - all.replace(/^0+/, "").length;
+	const digits = all.slice(leading).replace(/0+$/, "");
+	if (digits === "") {
+		return { negative: false, digits: "", exponent: 0 };
+	}
+	return {
+		negative: sign === "-",
+		digits,
+		exponent: whole.length - 1 - leading + Number(power),
+	};
+}
+
+/** `-1`, `0` or `1` as `a` is less than, equal to or greater than `b`. */
+function compareDecimals(a: DecimalParts, b: DecimalParts): number {
+	const signOf = (parts: DecimalParts) =>
+		parts.digits === "" ? 0 : parts.negative ? -1 : 1;
+	if (signOf(a) !== signOf(b)) {
+		return Math.sign(signOf(a) - signOf(b));
+	}
+	if (signOf(a) === 0) {
+		return 0;
+	}
+	let magnitude = 0;
+	if (a.exponent !== b.exponent) {
+		magnitude = a.exponent > b.exponent ? 1 : -1;
+	} else {
+		const width = Math.max(a.digits.length, b.digits.length);
+		const left = a.digits.padEnd(width, "0");
+		const right = b.digits.padEnd(width, "0");
+		magnitude = left === right ? 0 : left > right ? 1 : -1;
+	}
+	return a.negative ? -magnitude : magnitude;
+}
+
+function modPow(base: bigint, power: number, modulus: bigint): bigint {
+	let result = BigInt(1) % modulus;
+	let factor = base % modulus;
+	let remaining = power;
+	while (remaining > 0) {
+		if (remaining % 2 === 1) {
+			result = (result * factor) % modulus;
+		}
+		factor = (factor * factor) % modulus;
+		remaining = Math.floor(remaining / 2);
+	}
+	return result;
+}
+
+/** Whether `a` is an exact multiple of `b`; nothing is a multiple of zero. */
+function isDecimalMultiple(a: DecimalParts, b: DecimalParts): boolean {
+	if (b.digits === "") {
+		return false;
+	}
+	if (a.digits === "") {
+		return true;
+	}
+	// a = A × 10^ea and b = B × 10^eb, with A and B the digit strings as integers.
+	const scaleA = a.exponent - (a.digits.length - 1);
+	const scaleB = b.exponent - (b.digits.length - 1);
+	if (!Number.isSafeInteger(scaleA) || !Number.isSafeInteger(scaleB)) {
+		return false;
+	}
+	const mantissaA = BigInt(a.digits);
+	const mantissaB = BigInt(b.digits);
+	if (scaleA >= scaleB) {
+		return (
+			((mantissaA % mantissaB) *
+				modPow(BigInt(10), scaleA - scaleB, mantissaB)) %
+				mantissaB ===
+			BigInt(0)
+		);
+	}
+	// B × 10^(eb − ea) would have to divide A, whose last digit is not 0: no
+	// power of ten does.
+	return false;
+}
+
+// ---- the checks -----------------------------------------------------------
+
+/** zod's float remainder: a true decimal multiple's rounding is not a remainder. */
+function floatRemainder(value: number, step: number): number {
+	const ratio = value / step;
+	const rounded = Math.round(ratio);
+	const tolerance = 4 * Number.EPSILON * Math.max(Math.abs(ratio), 1);
+	return Math.abs(ratio - rounded) < tolerance ? 0 : ratio - rounded;
+}
+
+/** A string's length in Unicode code points, as zod counts it. */
+function codePoints(value: string): number {
+	let count = value.length;
+	for (let index = 0; index < value.length - 1; index += 1) {
+		if (
+			(value.charCodeAt(index) & 0xfc00) === 0xd800 &&
+			(value.charCodeAt(index + 1) & 0xfc00) === 0xdc00
+		) {
+			count -= 1;
+			index += 1;
+		}
+	}
+	return count;
+}
+
+const patterns = new WeakMap<object, RegExp>();
+
+function patternOf(
+	check: Extract<AvFieldFormatCheck, { readonly format: "regex" }>,
+): RegExp {
+	let pattern = patterns.get(check);
+	if (pattern === undefined) {
+		pattern = new RegExp(check.pattern.source, check.pattern.flags);
+		patterns.set(check, pattern);
+	}
+	// A global or sticky pattern remembers where it stopped; zod resets it too.
+	pattern.lastIndex = 0;
+	return pattern;
+}
+
+function passesFormat(check: AvFieldFormatCheck, value: string): boolean {
+	switch (check.format) {
+		case "regex":
+			return patternOf(check).test(value);
+		case "includes":
+			return value.includes(check.includes);
+		case "starts_with":
+			return value.startsWith(check.prefix);
+		case "ends_with":
+			return value.endsWith(check.suffix);
+		case "lowercase":
+			return /^[^A-Z]*$/.test(value);
+		case "uppercase":
+			return /^[^a-z]*$/.test(value);
+		default:
+			return matchesFormat(check.format, value);
+	}
+}
+
+/**
+ * The order of `value` against a check's bound, or `undefined` when the value is
+ * not of the subject's form (the Framework Validation Layer refused it already).
+ */
+function compareToBound(
+	value: unknown,
+	bound: number | string,
+	subject: FieldCheckSubject,
+): number | undefined {
+	switch (subject) {
+		case "number":
+			return typeof value === "number" && typeof bound === "number"
+				? Math.sign(value - bound)
+				: undefined;
+		case "bigint": {
+			if (typeof value !== "bigint") {
+				return undefined;
+			}
+			const limit = BigInt(bound);
+			return value === limit ? 0 : value > limit ? 1 : -1;
+		}
+		case "decimal": {
+			const left = decimalParts(String(value));
+			const right = decimalParts(String(bound));
+			return left === undefined || right === undefined
+				? undefined
+				: compareDecimals(left, right);
+		}
+		case "datetime":
+			return value instanceof Date
+				? Math.sign(value.getTime() - Date.parse(String(bound)))
+				: undefined;
+		default:
+			return undefined;
+	}
+}
+
+function isMultiple(
+	value: unknown,
+	step: number | string,
+	subject: FieldCheckSubject,
+): boolean | undefined {
+	switch (subject) {
+		case "number":
+			return typeof value === "number" && typeof step === "number"
+				? floatRemainder(value, step) === 0
+				: undefined;
+		case "bigint": {
+			if (typeof value !== "bigint") {
+				return undefined;
+			}
+			const divisor = BigInt(step);
+			return divisor !== BigInt(0) && value % divisor === BigInt(0);
+		}
+		case "decimal": {
+			const left = decimalParts(String(value));
+			const right = decimalParts(String(step));
+			return left === undefined || right === undefined
+				? undefined
+				: isDecimalMultiple(left, right);
+		}
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Whether `value` passes `check`; `true` for a value the check does not judge
+ * (a value of another form, which validation refused before the checks run).
+ */
+export function passesFieldCheck(
+	check: AvFieldCheck,
+	value: unknown,
+	subject: FieldCheckSubject,
+): boolean {
+	switch (check.check) {
+		case "less_than":
+		case "greater_than": {
+			const order = compareToBound(value, check.value, subject);
+			if (order === undefined) {
+				return true;
+			}
+			const signed = check.check === "less_than" ? -order : order;
+			return signed > 0 || (check.inclusive && signed === 0);
+		}
+		case "multiple_of":
+			return isMultiple(value, check.value, subject) ?? true;
+		case "max_length":
+		case "min_length":
+		case "length_equals": {
+			const length = Array.isArray(value)
+				? value.length
+				: typeof value === "string"
+					? codePoints(value)
+					: undefined;
+			if (length === undefined) {
+				return true;
+			}
+			return check.check === "max_length"
+				? length <= check.maximum
+				: check.check === "min_length"
+					? length >= check.minimum
+					: length === check.length;
+		}
+		case "string_format":
+			return typeof value === "string" ? passesFormat(check, value) : true;
+		case "max_size":
+		case "min_size":
+		case "size_equals": {
+			if (!(value instanceof Uint8Array)) {
+				return true;
+			}
+			const size = value.byteLength;
+			return check.check === "max_size"
+				? size <= check.maximum
+				: check.check === "min_size"
+					? size >= check.minimum
+					: size === check.size;
+		}
+	}
+}
+
+// ---- issues ---------------------------------------------------------------
+
+const FORMAT_LABELS: Readonly<Record<AvFieldCheckFormat, string>> = {
+	email: "an email address",
+	url: "a URL",
+	emoji: "emoji",
+	uuid: "a UUID",
+	guid: "a GUID",
+	nanoid: "a Nano ID",
+	cuid: "a CUID",
+	cuid2: "a CUID2",
+	ulid: "a ULID",
+	xid: "an XID",
+	ksuid: "a KSUID",
+	datetime: "an ISO 8601 date-time in UTC",
+	date: "an ISO 8601 date",
+	time: "an ISO 8601 time",
+	duration: "an ISO 8601 duration",
+	ipv4: "an IPv4 address",
+	ipv6: "an IPv6 address",
+	cidrv4: "an IPv4 CIDR block",
+	cidrv6: "an IPv6 CIDR block",
+	base64: "base64",
+	base64url: "base64url",
+	json_string: "a JSON string",
+	e164: "an E.164 phone number",
+	credit_card: "a credit card number",
+	iban: "an IBAN",
+	jwt: "a JWT",
+};
+
+function plural(count: number, one: string, many: string): string {
+	return `${count} ${count === 1 ? one : many}`;
+}
+
+function formatMessage(check: AvFieldFormatCheck): string {
+	switch (check.format) {
+		case "regex":
+			return `Value must match the pattern /${check.pattern.source}/${check.pattern.flags}.`;
+		case "includes":
+			return `Value must include ${JSON.stringify(check.includes)}.`;
+		case "starts_with":
+			return `Value must start with ${JSON.stringify(check.prefix)}.`;
+		case "ends_with":
+			return `Value must end with ${JSON.stringify(check.suffix)}.`;
+		case "lowercase":
+			return "Value must be lowercase.";
+		case "uppercase":
+			return "Value must be uppercase.";
+		default:
+			return `Value must be ${FORMAT_LABELS[check.format]}.`;
+	}
+}
+
+function boundMessage(
+	check: Extract<AvFieldCheck, { readonly inclusive: boolean }>,
+	subject: FieldCheckSubject,
+): string {
+	const bound = String(check.value);
+	if (subject === "datetime") {
+		return check.check === "less_than"
+			? `Value must be ${check.inclusive ? "on or before" : "before"} ${bound}.`
+			: `Value must be ${check.inclusive ? "on or after" : "after"} ${bound}.`;
+	}
+	return check.check === "less_than"
+		? `Value must be ${check.inclusive ? "at most" : "less than"} ${bound}.`
+		: `Value must be ${check.inclusive ? "at least" : "greater than"} ${bound}.`;
+}
+
+/** What a person reads about a failed check. */
+function messageOf(check: AvFieldCheck, subject: FieldCheckSubject): string {
+	switch (check.check) {
+		case "less_than":
+		case "greater_than":
+			return boundMessage(check, subject);
+		case "multiple_of":
+			return `Value must be a multiple of ${check.value}.`;
+		case "max_length":
+			return check.list === true
+				? `List must have at most ${plural(check.maximum, "entry", "entries")}.`
+				: `Value must be at most ${plural(check.maximum, "character", "characters")} long.`;
+		case "min_length":
+			return check.list === true
+				? `List must have at least ${plural(check.minimum, "entry", "entries")}.`
+				: `Value must be at least ${plural(check.minimum, "character", "characters")} long.`;
+		case "length_equals":
+			return `Value must be exactly ${plural(check.length, "character", "characters")} long.`;
+		case "string_format":
+			return formatMessage(check);
+		case "max_size":
+			return `Value must be at most ${plural(check.maximum, "byte", "bytes")}.`;
+		case "min_size":
+			return `Value must be at least ${plural(check.minimum, "byte", "bytes")}.`;
+		case "size_equals":
+			return `Value must be exactly ${plural(check.size, "byte", "bytes")}.`;
+	}
+}
+
+/** The issue of one failed check at `path`: its V-code, zod's check and its parameters. */
+export function fieldCheckIssue(
+	check: AvFieldCheck,
+	subject: FieldCheckSubject,
+	path: Path,
+): AvValidationIssue {
+	const { check: name, ...params } = check;
+	const code: AvValidationCode = name === "string_format" ? "V1003" : "V1004";
+	return {
+		code,
+		path,
+		message: messageOf(check, subject),
+		check: name,
+		params,
+	};
+}
+
+/**
+ * The issues of the checks `value` breaks, one per broken check, in the checks'
+ * order. On a list (`list`), a `list: true` length check judges the list at
+ * `path` and every other check judges each entry, at its index; `null` is no
+ * value and breaks nothing.
+ */
+export function fieldCheckIssues(
+	checks: readonly AvFieldCheck[],
+	value: unknown,
+	subject: FieldCheckSubject,
+	path: Path,
+	list: boolean,
+): readonly AvValidationIssue[] {
+	if (checks.length === 0 || value === null || value === undefined) {
+		return [];
+	}
+	const issues: AvValidationIssue[] = [];
+	if (list && Array.isArray(value)) {
+		for (const check of checks) {
+			if (isListCheck(check) && !passesFieldCheck(check, value, subject)) {
+				issues.push(fieldCheckIssue(check, subject, path));
+			}
+		}
+		for (const [index, entry] of value.entries()) {
+			issues.push(
+				...entryCheckIssues(checks, entry, subject, [...path, index]),
+			);
+		}
+		return issues;
+	}
+	return entryCheckIssues(checks, value, subject, path);
+}
+
+/** The issues of the checks one value — a whole value, or a list's entry — breaks. */
+export function entryCheckIssues(
+	checks: readonly AvFieldCheck[],
+	value: unknown,
+	subject: FieldCheckSubject,
+	path: Path,
+): readonly AvValidationIssue[] {
+	if (value === null || value === undefined) {
+		return [];
+	}
+	const issues: AvValidationIssue[] = [];
+	for (const check of checks) {
+		if (!isListCheck(check) && !passesFieldCheck(check, value, subject)) {
+			issues.push(fieldCheckIssue(check, subject, path));
+		}
+	}
+	return issues;
+}
+
+/** Whether a check judges a list's own length (`AvZ.minItems`/`AvZ.maxItems`). */
+export function isListCheck(check: AvFieldCheck): boolean {
+	return (
+		(check.check === "max_length" || check.check === "min_length") &&
+		check.list === true
+	);
+}