validx

Validation library for MobX.

Install

# Bring your own MobX
npm install --save mobx validx

Table of Contents

• Why?
• Examples
• API documentation
  • The ValidationContext
    • validate()
    • reset()
    • addErrors()
    • getErrors()
    • getError()
    • clearErrors()
    • errors
    • isValid
  • Validators
  • Built-in validators
    • required
    • pattern
    • func
  • Bound ValidationContext
• Author

Why?

We want to reactively display validation issues in our UI when using MobX. You can use any (non-DOM) validation library, but then you still need to make it reactive.

ValidX is built for MobX and is easy to use, yet powerful enough to add any validation you'd like.

Examples

See the TypeScript example and Babel example for runnable examples (in Node).

API documentation

The ValidationContext

The meat of the library is the validation context. To create one, you can either use

import { ValidationContext } from 'validx'
const validation = new ValidationContext()

Or use the factory function

import { validationContext } from 'validx'
const validation = validationContext()

The properties on the context are reactive (observables/computeds powered by MobX).

validate()

Given an object and a schema, validates the object and returns itself. validate() is a MobX action.

Calling it will populate the errors property with any validation errors found on the object

There are multiple ways to use validate(), see Bound ValidationContext.

import { validationContext, required, pattern } from 'validx'

const validation = validationContext()

// For good measure, reset the internal state.
validation.reset()

// validate takes 2 parameters:
// - the object to validate
// - the schema.
const schema = {
  // The schema maps to the fields we are validating.
  name: [
    // Each field you wish to validate is an array of validation
    // functions.
    // `required` is just a function returning a validator function.
    required({ msg: 'Name is required' })
  ],
  email: [
    required({ msg: 'Email is required' }),
    // The `pattern` validator can be used to validate
    // emails and other regexps.
    pattern({ pattern: 'email', msg: 'Not a valid email' })
  ]
}

validation.validate({
  name: '',
  email: ''
}, schema)

Now that we have validated our object, we can pull the errors from the context.

console.log(validation.isValid)
// false

console.log(validation.errors.name)
// ['Name is required']

console.log(validation.errors.email)
// ['Email is required', 'Not a valid email']

To validate again, we need to reset the context and then call validate.

validation.reset().validate({
  name: 'Jeff',
  email: 'test'
}, schema)

console.log(validation.isValid)
// false

console.log(validation.errors.name)
// []

console.log(validation.errors.email)
// ['Not a valid email']

Let's see what the errors are like when we log them after resetting.

validation.reset()
console.log(validation.isValid)
// true
console.log(validation.errors.name)
// undefined

console.log(validation.errors.email)
// undefined

They are undefined because we don't know what fields will be validated yet.

validation.validate({
  name: 'Jeff',
  email: 'test'
}, schema)

console.log(validation.isValid)
// false

console.log(validation.errors.name)
// []

console.log(validation.errors.email)
// ['Not a valid email']

reset()

Resets the internal state of the context. You usually use this before starting a new validation. reset() is a MobX action.

const validation = validationContext()
validation.validate({ name: '' }, {
  name: [required()]
})
console.log(validation.errors.name)
// ['This field is invalid']
validation.reset()
console.log(validation.errors.name)
// undefined

Use case: sharing a validation context in a class hierarchy.

class Element {
  @observable label = ''

  validation = validationContext(this)

  @action validate () {
    this.validation.validate({
      label: [required({ msg: 'Label required' })]
    })
  }
}

class TextElement extends Element {
  @observable placeholder = ''

  @action validate () {
    // reset before caling super
    this.validation.reset().validate({
      placeholder: [required({ msg: 'Placeholder required' })]
    })
    super.validate()
  }
}

const textElement = new TextElement()
textElement.validate()
console.log(textElement.validation.errors)
// { label: ['Label required'], placeholder: ['Placeholder required'] }

textElement.label = 'First name'
textElement.validate()
console.log(textElement.validation.errors)
// { placeholder: ['Placeholder required'] }

addErrors()

If you at some point want to add errors without calling validate, this is how to do it. addErrors() is a MobX action.

const obj = {}
const validation = validationContext(obj, {
})

if (usernameIsTaken) {
  validation.addErrors({
    username: ['Username is taken']
  })
}

console.log(validation.errors.username)
// ['Username is taken']

getErrors()

Safer way to get errors for a field rather than using errors.field, as this will return an empty array in case there are no errors.

const validation = validationContext()
validation.addErrors({ name: ['Not cool'] })

validation.getErrors('name')
// ['Not cool']

validation.reset()
validation.getErrors('name')
// []

getError()

Convenience method for getErrors('field')[0]. Returns undefined if the error is not found.

const validation = validationContext()
validation.addErrors({ name: ['Not cool'] })

validation.getError('name')
// 'Not cool'

validation.reset()
validation.getError('name')
// undefined

clearErrors()

Clear errors for a single field, instead of reseting the whole context.

const validation = validationContext()
validation.addErrors({ name: ['Not cool'], language: ['Must be JS'] })

validation.getError('name')
// 'Not cool'

validation.clearErrors('name')

validation.getError('name')
// 'Not cool'

validation.getError('language')
// 'Must be JS'

errors

A MobX computed map of field -> errors. When validate discovers validation errors, it puts them in here.

If a field has not been validated, or the context has just been reset, there will be no keys.

const validation = validationContext(obj, {
  name: [required()]
})
console.log(validation.errors)
// {}

validation.validate()
console.log(validation.errors)
// { name: ['This field is invalid'] }
validation.validate()
// { name: ['This field is invalid', 'This field is invalid] }
// that's why you need to remember to `reset()` first!

isValid

A MobX computed property that determines whether the context has any errors or not.

const validation = validationContext()
console.log(validation.isValid)
// true
validation.validate({ }, { name: [required()] })
console.log(validation.isValid)
// false

Validators

Validators are just plain functions that take an object with the rule configuration as a parameter and returns either true for success, false for failure, or a string for a failure with a specific message.

const validation = validationContext()
const schema = {
  age: [
    required({ msg: 'Age is required' }),
    (opts) => opts.value >= 13 || 'Must be 13 years or older'
  ]
}

validation.validate({
  age: 8
}, schema)

console.log(validation.errors.age)
// ['Must be 13 years or older']

Built-in validators

required

Takes a string (error message) or an object in the form of { required: boolean, msg: string }.

If required === false, the validator will always return true.

{
  // default message
  firstName: [required()],
  // shorthand
  lastName: [required('Last name, please?')],
  // Fully-fledged, only enabled if `this.getSmsNotifications` is `true`
  phoneNumber: [
    required({
      msg: 'Please enter your number so we can send you those notifications',
      required: this.getSmsNotifications,
    })
  ]
}

pattern

Let's you specify a named pattern or your own regex. Supports simple and config signatures.

Named patterns:

• 'email' (uses email-validator)
• 'url' (uses is-url)

Example:

{
  // simple
  email: [pattern('email')],
  // simple with message
  homepage: [pattern('url', 'Not a valid URL, come on!')],
  // simple regex with message
  bio: [pattern(/javascript/i, 'Sorry - no JS, no job.')],
  // config with regex and message
  twitterHandle: [
    pattern({
      pattern: /^@/,
      msg: 'Twitter handles start with an @'
    })
  ]
}

func

If you dislike the boolean || 'message' approach to custom validators, you can use func.

Example:

{
  knownLibraries: [
    // Without func.
    (opts) => opts.value.includes('react') || 'Sorry, only React devs here!',
    // With func.
    func(
      (opts) => opts.value.includes('react'),
      'Sorry, only React devs here!'
    )
  ]
}

Bound ValidationContext

By passing either 1 or 2 parameters to validationContext, you can "pre-bind" it to an object and a schema.

// Not bound to anything.
const obj = { name: '' }
const validation = validationContext()

validation.validate(obj, {
  name: [required()]
})

// Bound to an object
const obj = { name: '' }
const validation = validationContext(obj)

validation.validate({
  name: [required()]
})

// Bound to an object and a schema
const obj = { name: '' }
const validation = validationContext(obj, {
  name: [required()]
})

validation.validate()

Author

Jeff Hansen - @Jeffijoe