@eloquentjs/validator

Full-featured standalone validation for EloquentJS and any Node.js app — sync and async rules, fluent schema API, DB-backed unique/exists checks, custom Rule objects, and Express/Fastify adapters.

npm install @eloquentjs/validator

Three Ways to Validate

1. Fluent Schema API (recommended)

import { v } from '@eloquentjs/validator'

const schema = v.schema({
  name:     v.string().min(2).max(100),
  email:    v.string().email(),
  password: v.string().min(8).confirmed(),
  age:      v.number().integer().min(18).optional(),
  role:     v.string().oneOf(['admin', 'editor', 'viewer']),
  address:  v.object({
    city:    v.string(),
    country: v.string().length(2),
  }),
  tags: v.array().min(1).max(10),
})

// parse() — throws ValidationException on failure
const data = schema.parse(req.body)

// safeParse() — never throws, returns { success, data, errors }
const { success, data, errors } = schema.safeParse(req.body)

// Async (required when using .unique(), .exists(), or async custom rules)
const data = await schema.parseAsync(req.body)
const { success, data, errors } = await schema.safeParseAsync(req.body)

2. Laravel-style rule arrays

import { Validator } from '@eloquentjs/validator'

const validator = Validator.make(req.body, {
  name:  ['required', 'string', 'min:2', 'max:100'],
  email: ['required', 'email'],
  age:   ['required', 'integer', 'min:18'],
  role:  ['required', 'in:admin,editor,viewer'],
})

if (validator.fails()) {
  return res.status(422).json({ errors: validator.errors })
}
const data = validator.validated()  // only the declared fields

// Async (for unique/exists rules)
if (await validator.failsAsync()) {
  return res.status(422).json({ errors: validator.errors })
}

3. Named rule functions

import { required, email, min, max, unique, exists } from '@eloquentjs/validator/rules'

const rules = {
  name:  [required(), string(), min(2), max(100)],
  email: [required(), email(), max(255), unique('users', 'email')],
  role:  [required(), inList('admin', 'editor', 'viewer')],
}

const data = await Validator.make(req.body, rules).validatedAsync()

All Validation Rules

Presence

| Rule | Description | |---|---| | required | Value must be present and non-empty | | nullable | Allows null/undefined (stops further checks if empty) | | sometimes | Only validate when field is present in input | | prohibited | Field must not be present | | required_if:field,value | Required when another field equals a value | | required_with:a,b | Required when any of the listed fields are present | | required_with_all:a,b | Required when all listed fields are present | | required_without:a,b | Required when any of the listed fields are absent | | required_without_all:a,b | Required when all listed fields are absent |

Type

| Rule | Description | |---|---| | string | Must be a string | | integer / int | Must be an integer | | numeric | Must be a number | | boolean / bool | Must be a boolean (true/false/0/1) | | array | Must be an array | | object | Must be a plain object | | date | Must be a parseable date | | json | Must be a valid JSON string |

Size / Length

| Rule | Description | |---|---| | min:n | Min length (string/array) or min value (number) | | max:n | Max length or max value | | size:n | Exact length or value | | between:lo,hi | Value between lo and hi | | digits:n | Exactly n digits | | digits_between:lo,hi | Between lo and hi digits | | gt:field | Greater than another field's value | | gte:field | Greater than or equal to | | lt:field | Less than | | lte:field | Less than or equal to |

String Format

| Rule | Description | |---|---| | email | Valid email address | | url | Valid URL | | uuid | Valid UUID v1-v5 | | ip / ipv4 / ipv6 | Valid IP address | | mac_address | Valid MAC address | | timezone | Valid IANA timezone | | alpha | Letters only | | alpha_num | Letters and numbers only | | alpha_dash | Letters, numbers, dashes, underscores | | starts_with:a,b | Must start with one of the values | | ends_with:a,b | Must end with one of the values | | doesnt_start_with:a | Must not start with value | | doesnt_end_with:a | Must not end with value | | regex:pattern | Must match regex pattern | | in:a,b,c | Must be one of the listed values | | not_in:a,b,c | Must not be one of the listed values | | confirmed | Must match field_confirmation | | same:field | Must match another field | | different:field | Must differ from another field |

Date

| Rule | Description | |---|---| | before:date | Must be before the given date | | after:date | Must be after the given date | | before_or_equal:date | Must be before or equal to date | | after_or_equal:date | Must be after or equal to date |

Database (async)

| Rule | Description | |---|---| | unique:table,column | No matching record in DB | | exists:table,column | Matching record must exist in DB |

DB-Backed Rules

Use Rule.unique() and Rule.exists() for database validation. These require validateAsync() or parseAsync().

import { Rule } from '@eloquentjs/validator'

const rules = {
  // Email must not already exist in users table
  email: ['required', 'email', Rule.unique('users', 'email')],

  // When updating — ignore the current user's own record
  email: ['required', 'email', Rule.unique('users', 'email').ignore(userId)],

  // Extra WHERE conditions
  email: ['required', 'email', Rule.unique('users', 'email')
    .ignore(userId)
    .where('tenant_id', tenantId)],

  // Foreign key must exist
  role_id: ['required', Rule.exists('roles', 'id')],
}

// Must use async path for DB rules
const data = await Validator.make(req.body, rules).validatedAsync()

Custom Rule Objects

Extend Rule to create reusable, testable rule classes:

import { Rule } from '@eloquentjs/validator'

// Sync rule
class SlugFormat extends Rule {
  message() { return 'The :field must be a valid slug (lowercase letters, numbers, hyphens).' }
  passes(field, value) {
    return /^[a-z0-9-]+$/.test(value)
  }
}

// Async rule (DB lookup, API call, etc.)
class UniqueSlug extends Rule {
  constructor(postId = null) { super(); this.postId = postId }
  message() { return 'This slug is already in use.' }
  async passesAsync(field, value, data) {
    let qb = Post.where('slug', value)
    if (this.postId) qb = qb.where('id', '!=', this.postId)
    return !(await qb.exists())
  }
}

// Implicit rule (runs even when value is empty)
class RequiredForPremium extends Rule {
  static implicit = true
  message() { return ':field is required for premium accounts.' }
  passes(field, value, data) {
    if (data.plan !== 'premium') return true
    return value != null && value !== ''
  }
}

// Use in rules
const validator = Validator.make(data, {
  slug: ['required', new SlugFormat(), new UniqueSlug(existingPostId)],
})
await validator.validatedAsync()

Nested Fields & Objects

// Dot-notation for nested objects
const validator = Validator.make(data, {
  'address.city':    ['required', 'string'],
  'address.zip':     ['required', 'digits:5'],
  'address.country': ['required', 'size:2'],
})

// Schema API handles nesting automatically
const schema = v.schema({
  address: v.object({
    city:    v.string(),
    zip:     v.string().digits(5),
    country: v.string().length(2),
  }),
})

Bail and Sometimes

// bail() — stop validating all fields after first failure
const validator = Validator.make(data, rules).bail()

// sometimes() — only validate when field is present in input
const validator = Validator.make(data, {
  phone: ['string', 'min:10'],
}).sometimes('phone')

Custom Attribute Names

// Replace field names in error messages
const validator = Validator.make(
  data,
  { usr_email: ['required', 'email'] },
  {},                                        // custom messages (empty)
  { usr_email: 'email address' }             // custom attribute names
)
// Error: "The email address field is required." (not "The usr_email field is required.")

Custom Error Messages

const validator = Validator.make(data, rules, {
  'email.required': 'We need your email address.',
  'email.email':    'That doesn\'t look like a valid email.',
  'name.min':       'Your name must be at least :min characters.',
  'required':       'The :field field cannot be blank.',  // applies to all required rules
})

Framework Adapters

Express

import { expressValidate, validationErrorHandler } from '@eloquentjs/validator/adapters'

// Route middleware
router.post('/users',
  expressValidate({
    name:  ['required', 'string', 'min:2'],
    email: ['required', 'email'],
  }),
  async (req, res) => {
    // req.validated — only the schema-defined fields
    const user = await User.create(req.validated)
    res.status(201).json(user)
  }
)

// With schema API
router.post('/users', expressValidate(userSchema, { async: true }), handler)

// Validate query params
router.get('/users', expressValidate(filterSchema, { source: 'query' }), handler)

// Global error handler — mount after routes
app.use(validationErrorHandler)
// Returns: 422 { message: 'The given data was invalid.', errors: { field: [...] } }

Fastify

import { fastifyValidate, fastifyValidationPlugin } from '@eloquentjs/validator/adapters'

// Route-level hook
fastify.post('/users', {
  preHandler: fastifyValidate(userSchema, { async: true }),
}, async (req, reply) => {
  const user = await User.create(req.validated)
  reply.send(user)
})

// Global error handler plugin
await fastify.register(fastifyValidationPlugin)

Convenience Shorthands

import { validate, validateAsync } from '@eloquentjs/validator'

// Throws ValidationException immediately
const data = validate(input, { name: ['required', 'string'] })

// Async version
const data = await validateAsync(input, {
  email: ['required', 'email', Rule.unique('users', 'email')],
})

Named Rule Convenience Groups

import { emailRules, passwordRules, slugRules } from '@eloquentjs/validator/rules'

const rules = {
  email:    emailRules(),    // [required, string, email, max(255)]
  password: passwordRules(), // [required, string, min(8)]
  slug:     slugRules(),     // [required, string, regex(/^[a-z0-9-]+$/), max(255)]
}

Error Structure

ValidationException has an errors property — an object mapping field names to arrays of error strings:

{
  name:    ['The name field is required.'],
  email:   ['The email must be a valid email address.', 'The email has already been taken.'],
  address: {
    zip: ['The address.zip must be 5 digits.']
  }
}

Extending the Core Validator

@eloquentjs/validator's Validator extends @eloquentjs/core's built-in sync Validator. All 25+ core rules still work. This package adds:

• Async validation (validateAsync, validatedAsync, failsAsync)
• 20+ new rules (digits, uuid, ip, json, timezone, alpha, starts_with, before, gt, required_with, etc.)
• Rule object support (custom class-based rules)
• Nested dot-notation fields
• Bail mode and sometimes mode
• Custom attribute display names
• Framework adapters (Express, Fastify)
• DB-backed unique / exists (via @eloquentjs/core connection)

License

MIT