FormaJS

A lightweight, modular JavaScript library for validating, parsing, and sanitizing form inputs — with built‑in internationalization (i18n), zero external dependencies, and an extensible rule system.

Features

• Common validations out of the box: email, numbers, dates, UUID, IP, credit card, license plate, postal code/ZIP, tax IDs, and more
• Internationalization: localized messages and locale‑aware rules
• Extensible: add your own validators, parsers, and sanitizers
• Zero external dependencies and small, tree‑shakable modules

Documentation

For detailed API documentation, including all available validators, parsers, sanitizers, and formatters with their options and usage examples, see:

• Validators — Email, URL, IP, credit cards, tax IDs, and more
• Parsers — Convert strings to typed values
• Sanitizers — Clean and normalize input data
• Formatters — Apply locale-aware formatting

Installation

npm install @formajs/formajs
# or
pnpm add @formajs/formajs
# or
yarn add @formajs/formajs

Quick start

1) Use the preconfigured instance

// Default export is a preconfigured instance with locale en-US
import forma from '@formajs/formajs';

const res = forma.validateEmail('john@example.com');
if (!res.valid) {
  console.error(res.message); // Localized message (en-US by default)
}

2) Switch locale or use a locale-specific instance (opt-in locales)

import forma from '@formajs/formajs';

// Import the locale module you want to enable (opt-in)
// Available today: en-US (default), pt-BR, en-UK, es-ES, fr-FR, de-DE, zh-CN
import '@formajs/formajs/i18n/pt-BR';

// Change locale at runtime
forma.setLocale('pt-BR');

// Now your validations/messages are in pt-BR
const r = forma.validateTaxId('01234567890');

Or create a new instance with a specific locale:

import { Forma } from '@formajs/formajs';
import '@formajs/formajs/i18n/pt-BR';

const f = new Forma('pt-BR');

// Now your validations/messages are in pt-BR
const r = f.validateTaxId('01234567890');

3) Use the class directly

import { Forma } from '@formajs/formajs';

const f = new Forma('en-US');
const result = f.validateURL('https://example.com', { requireProtocol: true });
// result: { valid: boolean, message: string | null, error?: string, context?: object }

4) Call standalone functions (no message formatting)

All validators/parsers/sanitizers are also exported as standalone functions. These return raw results without localized messages — handy for frameworks or custom flows.

import { validateEmail } from '@formajs/formajs/validators/validateEmail';

const r = validateEmail('bad@@example.com');
// r: { valid: false, error: 'validateEmail', context?: {...} }

Tip: When called via the Forma instance, error codes are mapped to localized messages automatically.

API overview

• Validation result shape (via instance):

  { valid: true, message: null }
  { valid: false, message: string, error: string, context?: object }
  

• Options pattern: each rule accepts an optional final options object. When invoked through Forma, the instance locale is merged with your options.

• Async rules: the engine supports async validators; if a rule returns a Promise, the instance method returns a Promise too.

Locales (i18n)

• Default locale: en-US
• Opt-in additional locales: import the locale module once in your app, e.g. import '@formajs/formajs/i18n/pt-BR'
• Change at runtime: forma.setLocale('pt-BR')
• Per-call override: pass { locale: 'pt-BR' } as the last argument

Available locale modules today:

import '@formajs/formajs/i18n/en-US'; // (English - USA) already preloaded by default
import `@formajs/formajs/i18n/de-DE` // German - Germany
import `@formajs/formajs/i18n/en-AU` // English - Australia
import `@formajs/formajs/i18n/en-CA` // English - Canada
import `@formajs/formajs/i18n/en-IN` // English - India
import `@formajs/formajs/i18n/en-UK` // English - UK
import `@formajs/formajs/i18n/es-AR` // Spanish - Argentina
import `@formajs/formajs/i18n/es-ES` // Spanish - Spain
import `@formajs/formajs/i18n/es-MX` // Spanish - Mexico
import `@formajs/formajs/i18n/fr-CA` // French - Canada
import `@formajs/formajs/i18n/fr-FR` // French - France
import `@formajs/formajs/i18n/it-IT` // Italian - Italy
import `@formajs/formajs/i18n/ja-JP` // Japanese - Japan
import `@formajs/formajs/i18n/pt-BR` // Portuguese - Brazil
import `@formajs/formajs/i18n/pt-PT` // Portuguese - Portugal
import `@formajs/formajs/i18n/ru-RU` // Russian - Russia
import `@formajs/formajs/i18n/tr-TR` // Turkish - Turkey
import `@formajs/formajs/i18n/zh-CN` // Chinese - China

Notes:

• Locales are opt-in to keep bundles small. Only en-US ships preloaded by default.
• If you rely on the i18n utilities directly, you can also use the named exports: registerLocale, getLocaleData, hasLocale from @formajs/formajs/i18n.

Modules and examples

For a complete reference of all available validators, parsers, sanitizers, and formatters with their options and examples, see the detailed documentation in the docs/ folder.

Validators

Examples (see src/validators/ for the full list):

forma.validateEmail('user@example.com');
forma.validateURL('https://example.com', { requireProtocol: true });
forma.validateIP('127.0.0.1');
forma.validateDate('2024-01-31');
forma.validateCreditCard('4111111111111111');

Direct import (tree‑shakable):

import { validateURL } from '@formajs/formajs/validators/validateURL';
validateURL('example.com', { requireProtocol: false });

Sanitizers

Common sanitizers (see src/sanitizers/):

forma.trim('  hello  '); // 'hello'
forma.escapeHTML('<b>x</b>'); // '&lt;b&gt;x&lt;/b&gt;'
forma.normalizeEmail('Foo+bar@GMAIL.com');

Formatters

Apply locale-aware formatting to data (see src/formatters/):

forma.formatPostalCode('09010140', { locale: 'pt-BR' }); // '09010-140'
forma.formatPostalCode('90210', { locale: 'en-US' }); // '90210'

Direct import:

import { formatPostalCode } from '@formajs/formajs/formatters/formatPostalCode';
formatPostalCode('09010140', { locale: 'pt-BR' });

Parsers

Turn strings into typed values (see src/parsers/):

forma.toInt('42'); // 42
forma.toFloat('3.14'); // 3.14
forma.toDate('2024-01-31'); // Date

Import styles, deep imports, and CDN

FormaJS ships multiple formats in dist/ and supports deep imports for optimal bundling:

// ESM
import forma, { Forma } from '@formajs/formajs';
import { validateEmail } from '@formajs/formajs/validators/validateEmail';
// Opt-in a locale
import '@formajs/formajs/i18n/pt-BR';

// CJS
const forma = require('@formajs/formajs').default;
const { validateEmail } = require('@formajs/formajs/validators/validateEmail');
// Opt-in a locale
require('@formajs/formajs/i18n/pt-BR');

<!-- UMD (Browser/CDN) -->
<script src="https://unpkg.com/@formajs/formajs@1/dist/formajs.umd.min.js"></script>
<script>
  // The global remains forma (defined in the UMD build)
  // UMD includes en-US by default. Additional locales are available via ESM/CJS builds.
  forma.validateEmail('john@example.com');
  // To use other locales on the web, prefer a bundler setup (ESM) and import the locale module.
  // In pure script tag usage, you can pass `{ locale: 'pt-BR' }` per call, but messages won't be localized unless the locale data is registered.
  // See ESM/CJS examples above for enabling locales.
</script>

Deep imports are enabled via package.json#exports for validators, sanitizers, and parsers.

Project scripts

See the scripts in package.json. Highlights:

• Run tests: npm run test
• Watch tests: npm run test:watch
• Coverage: npm run test:coverage
• Lint: npm run lint
• Format: npm run format
• Build: npm run build
• Quick check (format + lint): npm run check
• Generate docs tables (experimental): npm run docs

Coverage reports are written to coverage/; open coverage/lcov-report/index.html in your browser.

Contributing

Please read the full guidelines in CONTRIBUTING.md.

Pull requests are welcome—tests, docs, and clear rationale help us review faster.

---

Migration notes (breaking)

Starting in v1.2.0, locales are opt-in and the formaBR named export was removed to reduce bundle size.

What changed:

• Only en-US is preloaded by default.
• To enable another locale, import its module once in your app.
• The formaBR export no longer exists.

How to migrate:

- import { forma, formaBR } from '@formajs/formajs';
+ import forma from '@formajs/formajs';
+ import '@formajs/formajs/i18n/pt-BR';

- const r = formaBR.validateTaxId('01234567890');
+ forma.setLocale('pt-BR');
+ const r = forma.validateTaxId('01234567890');

Or create a dedicated instance:

import { Forma } from '@formajs/formajs';
import '@formajs/formajs/i18n/pt-BR';

const br = new Forma('pt-BR');

License

MIT © FormaJS — see LICENSE.md