- Docs
- Validate one value with validateFieldValue()
Validate one value with validateFieldValue()
Pure validator that runs one rule set against a single value without a controller or DOM, useful for server-side and custom checks.
Pure validator. Runs the rule set against a single value. Does not require a controller — useful in tests, custom submission pipelines, or anywhere you need to evaluate validation rules outside of a bound form.
Signature
function validateFieldValue(
field: string,
value: FormFieldValue,
rules: FieldValidationRules,
values: FormValues
): string[]
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
field |
string |
yes | The field name (used for error messages and to seed FieldValidationContext). |
value |
FormFieldValue |
yes | The value to validate. |
rules |
FieldValidationRules |
yes | The rule set to apply. |
values |
FormValues |
yes | All current values, exposed to custom validators via context.values. |
Returns
A string[] of error messages. Empty when the field is valid.
Behaviour
Runs each rule in order:
required— value must be non-empty (non-empty string, non-empty array, non-undefined).minLength— string length (or array length) must be ≥ the threshold.maxLength— string length (or array length) must be ≤ the threshold.pattern— the string form of the value must match the regex (skipped when the value is empty).numeric,min, andmax— non-empty values must be strict decimals and satisfy the inclusive bounds.validate— each field-level custom validator runs in registration order. Returning a string pushes an error; returningfalsepushes"Validation failed."; returningnull,undefined, ortrueis treated as a pass.sameAs— the aggregate value must equal the named value (skipped until both values are non-empty).each— the value-level rules run independently for every collection member, including any member-level custom validators.
Default error messages are produced when the rule was configured without an explicit message. Custom messages come from the { value, message } form of RuleConfig.
Examples
Validate a single value
import { validateFieldValue } from '@samline/forms'
const errors = validateFieldValue(
'email',
'invalid',
{
required: true,
pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
},
{ email: 'invalid' }
)
console.log(errors) // ['Value does not match the required pattern.']
Match two fields
import { validateFieldValue } from '@samline/forms'
const errors = validateFieldValue(
'confirm',
'foo',
{
sameAs: { value: 'password', message: 'Passwords do not match.' },
},
{ password: 'bar', confirm: 'foo' }
)
console.log(errors) // ['Passwords do not match.']
Custom error messages
import { validateFieldValue } from '@samline/forms'
const errors = validateFieldValue(
'password',
'short',
{
minLength: { value: 8, message: 'Use at least 8 characters.' },
},
{ password: 'short' }
)
console.log(errors) // ['Use at least 8 characters.']
Validate strict decimal values and bounds
const errors = validateFieldValue(
'amount',
'100.25',
{ numeric: true, min: 0, max: 500 },
{ amount: '100.25' }
)
console.log(errors) // []
Validate every collection member
const errors = validateFieldValue(
'emails',
['valid@example.com', 'invalid'],
{
each: {
required: true,
pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
},
},
{ emails: ['valid@example.com', 'invalid'] }
)
console.log(errors) // ['Value does not match the required pattern.']
Edge cases
- The pattern rule is skipped for empty values. This is the standard “required + pattern” pattern: required runs first, then pattern runs only when there is a value.
- Numeric rules are skipped for empty values. Use
requiredas well when the field is mandatory. - Numeric parsing is strict. Surrounding whitespace is trimmed, and ordinary signed decimals such as
-2,+3.5,.5, and10.are accepted. Exponents, hexadecimal,Infinity,NaN, and formatted separators are rejected.minandmaxare inclusive and also enforce numeric input whennumericis omitted. - The
sameAsrule is skipped until both values are non-empty. Addrequiredto each mandatory field;sameAsdoes not imply requiredness. - Pure validation does not track dependencies.
dependsOnis controller metadata and has no effect here;validateFieldValueevaluates the supplied values once. validateFieldValuedoes not read from any DOM. Pass everything in as arguments.validateruns after the built-in rules. It receives the full context, including the current value and the other field values.- Multiple custom validators can be passed as an array — they all run, and any error from any of them is collected.
eachkeeps the public return type flat. Member errors are appended to the returnedstring[]in member order. Member custom validators receive a zero-basedindex;elementis unavailable in this DOM-free helper.
Related
validateValues— run a schema against a whole values map.validate— controller-bound equivalent.