asasalad v2.0.3

Asasalad

Asasalad is a Redux form validation utility designed to work with Immutable.js.

##Overview

1. Installation
2. API
3. Influences
4. Explain the Name
5. Future

Installation

npm install --save asasalad 

##API

###Note Every mention of a map (e.g. error map) refers to an Immutable.js Map.

checkFactory

checkFactory(fun, field, ...messages)

####Description Augments a predicate with field and messages properties which are used to build an error map during validation.

####Arguments

1. fun (function) : a predicate that checks for a property that must be true of the form, return false if check fails
2. field (string) : the target field of the check (used to populate the error map)
3. messages (...string) : messages that describes why the check failed

####Returns

1. check (function) : the given predicate (i.e fun) augmented with field and messages properties.

####Example

const passwordCheck = checkFactory(({ password }) =>
                             /^.{3,20}$/.test(password),
                             'password',
                             'password must be 3-20 characters')

###validatorFactory

validatorFactory(...checks)

####Description Takes a collection of checks created with the help of checkFactory and returns a validator.

####Arguments

1. checks (...function) : checks are predicates with field and messages properties as returned from checkFactory

####Returns

1. validator (function) : a validator takes two arguments: errors map and a state map, runs all the checks specified during its creation, and returns an updated error map.

####Example

export const usernameLengthCheck = checkFactory(( { username }) =>
                                   /^.{3,20}$/.test(username),
                                   'username',
                                   "username must be 3 to 20 characters")

export const usernameCharCheck = checkFactory(({ username }) =>
                                 /^[a-z0-9_-]*$/.test(username),
                                 'username',
                                 "username can only include a-z, 0-9 , _ , and -")
                              
const validateUsername = validatorFactory(usernameLengthCheck, usernameCharCheck)

###combineValidators

combineValidators(...validators)

####Description Takes a collection of validators created with validatorFactory and returns a mega validator. combineValidators makes creating a validator for the entire form a snap if you've already defined validators for the various fields in the form.

For example, you can have a seperate validator for each field, which will run after some field specific event (e.g. onBlur). Then you can combine the valdiators for each field into a complete form validator, which you can run (e.g before sending an AJAX request.)

####Arguments

1. validators (...function) : validators are functions with the signature (errors, state) -> errors, and should be created with validatorFactory.

####Returns

1. validator (function) : a mega validator that is functionally equivalent to chaining calls to all the validators passed as arguments to combineValidators.

####Example

const validateUsername = validatorFactory(usernameLengthCheck, usernameCharCheck)

const validateEmail = validatorFactory(emailCheck)

const validatePassword = validatorFactory(passwordCheck, confirmCheck)

const validateConfirm = validatorFactory(confirmCheck)

const validateForm = combineValidators(validateUsername,
                                       validateEmail,
                                       validatePassword,
                                       validateConfirm)

validate

validate(state, validator)

####Description Validate is used inside a Redux reducer. It takes your form state, and an Asasalad validator, and returns a new form state with an updated error map.

####Arguments

1. state (map) : Immutable.js map that contains a form's state
2. validator (function) : a validator built with either validatorFactory or combineValidators

####Returns

1. state (map) : form state with an updated error map

####Example

const signupFormReducer = (state = initialState, action) => {
  switch (action.type) {
    ...
    case 'VALIDATE_SIGNUP_USERNAME':
      return validate(state, validateUsername)
    case 'VALIDATE_SIGNUP_EMAIL':
      return validate(state, validateEmail)
    case 'VALIDATE_SIGNUP_PASSWORD':
      return validate(state, validatePassword)
    ...

Influences

The design of Asasalad was influenced by examples from Functional JavaScript by Michael Fogus.

Explain the Name

If I'm eating an amazing cookie, I might say it's valid as a salad (asasalad).

Future

I am currently working on another library that builds atop of Asasalad called Franklin, which willbuild complete redux forms given little more than a formName and validatorMap.

const validateUsername = validatorFactory(usernameLengthCheck, usernameCharCheck)

const validatePassword = validatorFactory(passwordCheck)

const validatorMap = {
  username : validateUsername,
  password : validatePassword,
}

const { reducer, container } = generateForm('login', validatorMap)