Reference

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

ExportShapeUse it in
regex.<key>{ pattern: RegExp; errorMessage: string }pattern
regex.phone(), date(), numeral(), …Function returning { pattern, errorMessage } from optionspattern or validate
regex.custom(pattern, message?)Your own pattern with the same shapepattern
isValidCurp, isValidRfc, isValidIban, …(value: unknown) => booleanvalidate

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.

ValidatorChecks
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 typeVisible valueCanonical raw value
phone, creditCard, general (with blocks)4111 1111 1111 11114111111111111111
numeral€ 1.234,51234.5
date, time30/04/202630/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/formatter without the peer installed fails; @samline/forms does not catch it.
  • Formatter 2.x or 3.0–3.1. regex exists but has fewer keys, no builders such as regex.date() or regex.postalCode(), and no check-digit validators.
  • Stricter patterns since 3.2.0. Formatter audited the catalog: email, phone, rfc, curp, date and others reject values they used to accept. Keep an old behavior with regex.custom(); the formatter changelog lists each change.
  • The controller never reads regex for you. You opt in per field; nothing turns on regex.email for every email field.
  • Types. The installed peer provides the real types (Regex, RegexKey, PostalCountry). The shim inside @samline/forms only keeps its own build compiling without the peer.