regex

Validates that a value matches (or doesn't match) a regular expression pattern.

Import

import { regexRule } from '@pliant/core';

Signature

function regexRule(options: RegexRuleOptions): RuleDef

Options

Option	Type	Required	Default	Description
pattern	RegExp	Yes	—	Pattern to match
invert	boolean	No	false	Fail if pattern matches

Error Detail

{
  code: 'regex',
  pattern: string,   // Pattern as string
  value: string      // Actual value
}

Examples

Basic Usage

import { createRegistry, addRules, evaluateRules, regexRule } from '@pliant/core';

const registry = createRegistry();
addRules(registry, {
  phone: regexRule({ pattern: /^\d{10}$/ })
});

// Doesn't match
evaluateRules(registry, '123-456-7890', { field: 'phone' }, ['phone']);
// { phone: { code: 'regex', pattern: '^\\d{10}$', value: '123-456-7890' } }

// Matches
evaluateRules(registry, '1234567890', { field: 'phone' }, ['phone']);
// null

Inverted Match

Use invert: true to fail when the pattern matches:

addRules(registry, {
  // Disallow spaces
  noSpaces: regexRule({ pattern: /\s/, invert: true })
});

evaluateRules(registry, 'has space', { field: 'username' }, ['noSpaces']);
// { noSpaces: { code: 'regex', pattern: '\\s', value: 'has space' } }

evaluateRules(registry, 'nospaces', { field: 'username' }, ['noSpaces']);
// null (passes)

Empty Values

Empty values pass validation:

evaluateRules(registry, '', { field: 'phone' }, ['phone']);
// null (passes)

Messages

import { createMessageResolver } from '@pliant/core';

const messages = createMessageResolver({
  regex: 'Invalid format'
});

For better messages, use inherited rules with custom codes:

import { inheritRule, regexRule } from '@pliant/core';

addRules(registry, {
  phone: inheritRule(regexRule({ pattern: /^\d{10}$/ }), {
    code: 'phone'
  }),
  zipCode: inheritRule(regexRule({ pattern: /^\d{5}(-\d{4})?$/ }), {
    code: 'zipCode'
  })
});

const messages = createMessageResolver({
  phone: 'Please enter a 10-digit phone number',
  zipCode: 'Please enter a valid ZIP code'
});

Common Patterns

Phone Number (US)

addRules(registry, {
  phone: regexRule({ pattern: /^\d{10}$/ })
  // Or with formatting:
  // phoneFormatted: regexRule({ pattern: /^\d{3}-\d{3}-\d{4}$/ })
});

ZIP Code (US)

addRules(registry, {
  zipCode: regexRule({ pattern: /^\d{5}(-\d{4})?$/ })
});

Postal Code (Canada)

addRules(registry, {
  postalCode: regexRule({ pattern: /^[A-Z]\d[A-Z] ?\d[A-Z]\d$/i })
});

Social Security Number

addRules(registry, {
  ssn: regexRule({ pattern: /^\d{3}-?\d{2}-?\d{4}$/ })
});

Username (Alphanumeric + Underscore)

addRules(registry, {
  username: regexRule({ pattern: /^[a-zA-Z0-9_]+$/ })
});

Slug (URL-safe)

addRules(registry, {
  slug: regexRule({ pattern: /^[a-z0-9]+(?:-[a-z0-9]+)*$/ })
});

No Special Characters

addRules(registry, {
  name: regexRule({ pattern: /[<>\"'&]/, invert: true })
});

Credit Card (Basic)

addRules(registry, {
  creditCard: regexRule({ pattern: /^\d{13,19}$/ })
});

IP Address (v4)

addRules(registry, {
  ipv4: regexRule({ 
    pattern: /^(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)$/ 
  })
});

URL (Simple)

addRules(registry, {
  url: regexRule({ pattern: /^https?:\/\/.+$/ })
});

Best Practices

Use Anchors

Always use ^ and $ for full-string matching:

// ❌ Matches '123' anywhere in the string
regexRule({ pattern: /\d{3}/ })

// ✅ Matches exactly 3 digits
regexRule({ pattern: /^\d{3}$/ })

Create Semantic Rules

Don't just use generic "regex" messages:

// ❌ Generic
addRules(registry, {
  regex: regexRule({ pattern: /^\d{10}$/ })
});
const messages = { regex: 'Invalid format' };

// ✅ Semantic
addRules(registry, {
  phone: inheritRule(regexRule({ pattern: /^\d{10}$/ }), { code: 'phone' })
});
const messages = { phone: 'Enter a 10-digit phone number' };

Test Edge Cases

const pattern = /^[a-zA-Z]+$/;

// Empty string - decide if allowed
// Unicode - decide if 'café' should pass
// Whitespace - trim before validating?

See Also

• numeric — Digits only
• email — Email format
• Built-in Rules — All rules