- Docs
- Formatter regex presets
Formatter regex presets
Validation patterns and check-digit validators from the optional @samline/formatter peer, wired into forms validators.
@samline/formatter ships a catalog of validation patterns, each paired with an error message, and functions that verify check digits. Feed them to the pattern and validate rules instead of writing a RegExp and a message for every form. This page covers how they fit forms; the formatter regex reference is the canonical list of keys, builders and validators.
Import
import { isValidCurp, regex } from '@samline/formatter'
npm install @samline/formatter
pnpm add @samline/formatter
bun add @samline/formatter
Forms accepts the peer as ^2.1.0 || ^3.0.0. This page describes formatter 3.2.0 and newer: the country entries, the callable builders and the check-digit validators do not exist in older versions.
What the peer provides
| Export | Shape | Use it in |
|---|---|---|
regex.<key> | { pattern: RegExp; errorMessage: string } | pattern |
regex.phone(), date(), numeral(), … | Function returning { pattern, errorMessage } from options | pattern or validate |
regex.custom(pattern, message?) | Your own pattern with the same shape | pattern |
isValidCurp, isValidRfc, isValidIban, … | (value: unknown) => boolean | validate |
Static entries cover Mexican identity (curp, rfc, ine, nss, clabe, cp), the United States (ssn, itin, ein, passportUs, routingNumber), Europe (iban, bic, vatEu, dniEs), web values (email, url, domain, ipv4, uuid, slug…) and dates, times and numbers. phone, creditCard, url, uuid, date, numeral and postalCode are also callable and keep their static .pattern; digits, time, password and custom are only callable. regex.postalCode({ country }) knows 24 countries and throws a RangeError for any other; use regex.custom() for those.
Pattern rule
Pass the entry’s pattern and errorMessage to the pattern rule. The rule skips empty values, so pair it with required when the field is mandatory:
import { form } from '@samline/forms'
import { regex } from '@samline/formatter'
const signup = form('signup-form', {
validators: {
email: {
required: true,
pattern: { value: regex.email.pattern, message: regex.email.errorMessage },
},
},
})
When the value does not match, the controller pushes regex.email.errorMessage into state.errors.email and applies css-error to the field — see Configuration and CSS styling. Without a message, the rule pushes the forms default, Value does not match the required pattern.
Some entries use the u flag (email, url, domain, personName, onlyLetters…); the pattern rule runs them as they are. regex.email accepts accents in the domain (ana@correo.méx) but not before the @.
Check digits with validate
A pattern checks the shape of a value. A check digit also catches most typos: one wrong digit or two swapped. Keep the pattern for the message and add the validator in validate, which treats a string as the error and false as Validation failed.:
import { form } from '@samline/forms'
import { isValidCurp, isValidIban, regex } from '@samline/formatter'
const profile = form('profile-form', {
validators: {
curp: {
required: true,
pattern: { value: regex.curp.pattern, message: regex.curp.errorMessage },
validate: ({ value }) => isValidCurp(value) || 'The CURP check digit does not match.',
},
iban: {
validate: ({ value }) => !value || isValidIban(value) || 'Check the IBAN.',
},
},
})
GODE561231HDFRRN00 passes both rules; GODE561231HDFRRN01 has the right shape, so only validate reports it. validate also runs on empty values, which is why the optional iban returns early.
| Validator | Checks |
|---|---|
isValidCard(value) | 12–19 digits and the Luhn checksum |
isLuhn(value) | Luhn checksum of any 2+ digits (IMEI, custom IDs) |
isValidClabe(value) | Mexican CLABE: 18 digits and the Banco de México check digit |
isValidNss(value) | Mexican NSS (IMSS): 11 digits and its Luhn check digit |
isValidCurp(value) | Mexican CURP and its RENAPO check digit |
isValidRfc(value) | Mexican RFC and its SAT check digit |
isValidIban(value) | IBAN length for its country and the mod-97 checksum |
isValidRoutingNumber(value) | US ABA routing number and its checksum |
isValidDniEs(value) | Spanish DNI or NIE and its control letter |
Every validator ignores spaces and hyphens, upper-cases letters and returns false for non-strings, so it works on the raw or the displayed value. A valid check digit proves the value is well formed, not that it exists: confirm it with the issuer when that matters, and validate again on the server.
Formatted fields
A validator keyed by the canonical name reads the hidden raw mirror that format() keeps. What that raw value contains depends on the format type:
| Format type | Visible value | Canonical raw value |
|---|---|---|
phone, creditCard, general (with blocks) | 4111 1111 1111 1111 | 4111111111111111 |
numeral | € 1.234,5 | 1234.5 |
date, time | 30/04/2026 | 30/04/2026 |
Digit-only rules (regex.creditCard, regex.clabe, regex.digits()) and every check-digit validator fit the raw value of phone, creditCard and general fields.
regex.date() and regex.time() take the same options as format() and match the visible value, which a date or time raw value keeps. Use them in pattern directly:
import { form } from '@samline/forms'
import { regex } from '@samline/formatter'
const dateOptions = { datePattern: ['d', 'm', 'Y'], delimiter: '/' }
const birthday = regex.date(dateOptions)
const booking = form('booking-form', {
formats: { birthday: { type: 'date', field: 'birthday', options: dateOptions } },
validators: {
birthday: { pattern: { value: birthday.pattern, message: birthday.errorMessage } },
},
})
The date mask lets a half-typed value through (30/04/202); the rule reports it until the date is complete and real.
A numeral raw value drops the prefix and delimiters, so regex.numeral(options) only matches the visible value. Read it from values in validate:
import { form } from '@samline/forms'
import { regex } from '@samline/formatter'
const priceOptions = { delimiter: '.', numeralDecimalMark: ',', prefix: '€ ' }
const price = regex.numeral(priceOptions)
const order = form('order-form', {
formats: { price: { type: 'numeral', field: 'price', options: priceOptions } },
validators: {
price: {
validate: ({ values }) =>
price.pattern.test(String(values.price_displayed ?? '')) || price.errorMessage,
},
},
})
Without a controller
The patterns and validators are plain values, so they work with the pure helper too:
import { regex } from '@samline/formatter'
import { validateFieldValue } from '@samline/forms'
validateFieldValue('email', 'ana..lopez@correo.mx', { pattern: regex.email.pattern }, {})
// ['Value does not match the required pattern.']
See validateFieldValue for the signature.
Browser globals
In a bundled app, spread regex and the validators you need next to the browser registry:
import { browser } from '@samline/forms'
import { isValidCurp, regex } from '@samline/formatter'
window.Form = { ...browser, regex, isValidCurp }
window.Form.newForm({
id: 'contact-form',
options: {
validators: {
email: {
required: true,
pattern: { value: regex.email.pattern, message: regex.email.errorMessage },
},
},
},
})
The /browser module installs the same registry on globalThis.Forms. The standalone forms IIFE bundles what format() needs, but not regex or the validators. On a page without a bundler, also load the formatter global, which exposes window.Formatter.regex and window.Formatter.checks:
<script src="https://cdn.jsdelivr.net/npm/@samline/formatter@3/dist/browser/formatter.global.js"></script>
<script>
const { regex, checks } = window.Formatter
// regex.curp.pattern, checks.isValidCurp(value)
</script>
The formatter global repeats formatting code the forms IIFE already contains (about 13 KB gzip), so add it only when the page needs the patterns.
Edge cases
- Missing peer. Importing from
@samline/formatterwithout the peer installed fails;@samline/formsdoes not catch it. - Formatter 2.x or 3.0–3.1.
regexexists but has fewer keys, no builders such asregex.date()orregex.postalCode(), and no check-digit validators. - Stricter patterns since 3.2.0. Formatter audited the catalog:
email,phone,rfc,curp,dateand others reject values they used to accept. Keep an old behavior withregex.custom(); the formatter changelog lists each change. - The controller never reads
regexfor you. You opt in per field; nothing turns onregex.emailfor everyemailfield. - Types. The installed peer provides the real types (
Regex,RegexKey,PostalCountry). The shim inside@samline/formsonly keeps its own build compiling without the peer.
Related
validators— the option that receives the rules.- Validation guide —
pattern,validate,dependsOnandeach. - Formatting guide — the raw mirror that canonical-name rules read.
validateFieldValue— the pure helper.- Formatter regex reference — every key, builder and validator.