Get unlimited public & private packages + package-based permissions with npm Pro.Get started »

foval

0.0.20 • Public • Published

Foval

Wonderfully easy form validation for Node.js.

Foval saves you an immense amount of time by providing a quick, easy and solid framework for validating your form fields. It is completely asynchronous and supports a wide range of data transformations and validations out of the box. You can even add custom ones if you wish.

Quick Start

If you want to get started quickly, copy and paste the following code into your project:

var form = new Foval({   //pass in the data as a set of key-value pairs.
  'fullName':        'Josh Cole',
  'telephoneNumber': '+44.7912345678',
  'aboutText':       'Lorem ipsum...',
  'hoursNeeded':     30
});
 
form.defineFields({
  fieldName: 'fullName',
  dataType:  'string',
  trim:      true,
  required:  true,
  transforms: {
    before: {
      'str-case': 'capitalise'
    }
  }
}, {
  fieldName: 'telephoneNumber',
  dataType:  'tel',  //automatic validation.
  required:  true
}, {
  fieldName: 'email',
  dataType:  'email',  //automatic validation.
  required:  true
}, {
  fieldName: 'aboutText',
  dataType:  'string',
  transforms: {
    after: {
      'str-line-break-to-br': true
    }
  },
  validations: {
    'str-length': {
      min: 100,
      max: 300
    }
  }
}, {
  fieldName: 'hoursNeeded',
  dataType:  'int',
  validations: {
    'numeric': {
      min: 1,
      max: 50
    }
  }
});
 
form.validate(function (err, isFormValid, validationResults, fieldHash) {
 
  // A fatal error, not a validation error.
  if (err) { return ...  }
 
  // The form failed to validate.
  if (!isFormValid) {
    // Use 'validationResults' to check what went wrong.
    return ...
  }
 
  // Form is valid!
  console.log(fieldHash);  //use 'fieldHash' to access the values.
 
});

Full Guide

This section provides a full guide to form validation with Foval and explain each of the steps in more detail.

Data Types

Foval supports the following internal data types, some of which automatically apply transformations and validations. Raw input from the form is automatically typecast depending on the data type chosen, this is useful for example with numerical fields which are passed through as strings, but really should be integers or floats.

Data Type Becomes Typecast Transform Validation Notes
string string String
str string String
number int Number
int int Number
float float Number
email email String str-trim email
telephone telephone String str-trim telephone
tel telephone String str-trim telephone
url url String str-trim url
boolean boolean Boolean
bool boolean Boolean
checkbox checkbox Boolean
password password String Plain-text.

Defining Fields

In order to validate the form in a structured way you must first define each of the fields, the expected data types, validations you want to run, and any transformations you want to run on the data.

form.defineFields({
  fieldName:    'firstName',
  dataType:     'string',
  defaultValue: 'Bob',
  required:     true,
  trim:         true,
  modify: function (value, finish) {
    ...
    return finish(null, isValid, reason);
  },
  transforms: {
    before: {
      ...
    },
    after: {
      ...
    }
  },
  validations: {
    ...
  }
});

Shortcuts

When defining fields you might want to enable some transforms or validations on a regular basis. To save time you can use the following shortcuts.

Transforms

Shortcut Data Type Default Transform When
trim Boolean False str-trim Before
modify Function Null custom Before

Validations

Shortcut Data Type Default Validation
required Boolean False required

Setting Up Transforms

Transforms allow you to modify the data in the field both 'before' and 'after' it is validated. This is useful for example, if you need to trim whitespace from an email before validating it, and then want to run a custom transform after validation. Transforms will be run in the order they are added. When defining a field you must add transforms inside the 'transforms.before' or 'transforms.after' property. The 'before' transforms will be run before any validation is attempted, and the 'after' transforms will be run after successful validation.

Use The Default Options

If you just pass 'true' the transform will be run with the default options. Please note some transforms have required options.

{
  ...
  transforms: {
    before: {
      'str-case': true
    },
    after: {
      ...
    }
  }
}

Specifying Options

You can also pass an object containing various options to the transform. The 'run' option is 'true' by default, if you set it to 'false' you can prevent the transform from running.

{
  ...
  ...
  transforms: {
    before: {
      'str-case': {
        run:  true,
        case: 'upper'
      }
    },
    after: {
      ...
    }
  }
}

Setting Up Validations

Validations allow you to test the field values against pre-defined rules. When defining a field you must add validations inside the 'validations' property. Validations will be run in the order they are added.

Use The Default Options

If you just pass 'true' the validation will be run with the default options. Please note some validations have required options.

{
  ...
  validations: {
    'password': true
  }
}

Specifying Options

You can also pass an object containing various options to the validation. The 'run' option is 'true' by default, if you set it to 'false' you can prevent the validation from running without invalidating the field.

{
  ...
  validations: {
    'password': {
      run: true,
      requirements: {
        length:    6,
        lowercase: true,
        uppercase: true,
        common:    true
      }
    }
  }
}

Transforms List

The following is a list of all the transforms and what they do. Remember, you can use these 'before' or 'after' the data is validated.

'custom'

Allows you to pass in an asynchronous function to do some transformation of the data.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the transform running.
fn Function Null The custom transform function.

Function Parameters

Parameter Data Type Notes
value Mixed The value of the field.
dataType String The Foval data type of the field.
finish Function The callback to call when your function has finished.

Finish Parameters

Parameter Data Type Notes
err Error An error to pass back or null.
transformedValue Mixed The transformed/unchanged value to pass back.

Example

{
  ...
  transforms: {
    before: {
      'custom': function (value, dataType, finish) {
        var transformedValue = value.replace(/a/gi, 'b');
        return finish(null, transformedValue);
      }
    }
  }
}, {
  ...
  transforms: {
    before: {
      'custom': {
        run: true,
        fn:  function (value, dataType, finish) {
          var transformedValue = value.replace(/a/gi, 'b');
          return finish(null, transformedValue);
        }
      }
    }
  }
}

'md5'

Creates an MD5 hash of the value. Non-string values will be typecast to strings first and this may have unexpected behaviour.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the transform running.
encoding String 'hex' The encoding type. See Node's crypto documentation.
seed Mixed Null Any value to use as a seed, optional.
random Bool False Set true to add a random value to seed the hash with.

Example

{
  ...
  transforms: {
    before: {
      'md5': 'hex'
    }
  }
}, {
  ...
  transforms: {
    before: {
      'md5': {
        run:      true,
        encoding: 'hex'
      }
    }
  }
}

'str-br-to-line-break'

Converts <br> tags to line breaks.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the transform running.

Example

{
  ...
  transforms: {
    before: {
      'str-br-to-line-break': true
    }
  }
}, {
  ...
  transforms: {
    before: {
      'str-br-to-line-break': {
        run: true
      }
    }
  }
}

'str-case'

Change the case of a string.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the transform running.
case String Null The new string case to apply.

Values For 'case'

Case Notes
uppper Makes the whole string uppercase.
lower Makes the whole string lowercase.
capitalise Capitalises the first letter of each word whilst making the rest lowercase.
capitalize Capitalises the first letter of each word whilst making the rest lowercase.

Example

{
  ...
  transforms: {
    before: {
      'str-case': 'upper'
    }
  }
}, {
  ...
  transforms: {
    before: {
      'str-case': {
        run:  true,
        case: 'upper'
      }
    }
  }
}

'str-collapse-whitespace'

Collapse multiple spaces or tabs into single spaces.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the transform running.

Example

{
  ...
  transforms: {
    before: {
      'str-collapse-whitespace': true
    }
  }
}, {
  ...
  transforms: {
    before: {
      'str-collapse-whitespace': {
        run: true
      }
    }
  }
}

'str-line-break-to-br'

Converts line breaks tags to <br> tags.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the transform running.

Example

{
  ...
  transforms: {
    before: {
      'str-line-break-to-br': true
    }
  }
}, {
  ...
  transforms: {
    before: {
      'str-line-break-to-br': {
        run: true
      }
    }
  }
}

'str-replace'

Replaces something in a string. Can be passed a regular expression or a string. If a string is passed in it will automatically be escape.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the transform running.
find RegExp/String Null The RegExp object or raw string to use.
flags Boolean Null Used if a string is passed to 'find'.
replace String Null The string to replace with.

Example

{
  ...
  transforms: {
    before: {
      'str-replace': {
        run:     true,
        find:    'abc',
        flags:   'gi',
        replace: 'def'
      }
    }
  }
}

'str-trim'

Trims whitespace from the start and end of a string.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the transform running.

Example

{
  ...
  transforms: {
    before: {
      'str-trim': true
    }
  }
}, {
  ...
  transforms: {
    before: {
      'str-trim': {
        run: true
      }
    }
  }
}

'telephone'

Formats a telephone number field as a friendly string.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the transform running.
pattern String Null A Foval telephone pattern to use, overrides the 'format' option.
format String 'basic' The name of the quick format to use.
international Bool Null Set true to use international format or false to use local, otherwise we use the existing format.
countryCode String Null Must be provided if formatting local numbers as international, e.g. '44'.

Instructions for 'pattern'

You can specify a custom pattern (as a string) to meet your requirements, for example:

  • "{ZERO}{REM}"
  • "{ZERO}{4} {REM}"
  • "+{CC} ({ZERO}) {3} {3} {REM}"

Patterns need to be a string, they can have any characters you wish except '{' or '}', and they must use the following flags:

Flag Notes
{CC} The country code in the number, otherwise the 'countryCode' option provided.
{ZERO} Inserts a zero if one if the next digit isn't a zero (use at the start of the number).
{3} The number of digits to use in this position, can be any number >0.
{REM} All the remaining numbers, this should be used last in the pattern.

Values for 'format'

A list of pre-defined patterns to quickly format your number.

Value International Format Local Format
basic +447912345678 07912345678
uk-local +44 (0) 2035 123456 02035 123456
uk-business +44 (0) 845 123 4567 0845 123 4567

Example

{
  ...
  transforms: {
    after: {
      'telephone': 'uk-business'
    }
  }
}, {
  ...
  transforms: {
    after: {
      'telephone': {
        run:         true,
        pattern:     'uk-business',
        countryCode: '44'
      }
    }
  }
}, {
  ...
  transforms: {
    after: {
      'telephone': {
        run:         true,
        pattern:     '+{CC} ({ZERO}) {3} {3} {REM}',
        countryCode: '44'
      }
    }
  }
}

Validations List

'custom'

Allows you to pass in an asynchronous function to do some validation of the data.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the validation running.
fn Function Null The custom validation function.

Function Parameters

Parameter Data Type Notes
value Mixed The value of the field.
dataType String The Foval data type of the field.
isRequired Boolean Whether the field is required, as per the definition.
finish Function The callback to call when your function has finished.

Finish Parameters

Parameter Data Type Notes
err Error An error to pass back or null.
isValid Boolean Set true if the validation passed, otherwise false.
reason String A short string denoting the failure reason, or Null.

Example

{
  ...
  validations: {
    'custom': function (value, dataType, isRequired, finish) {
      ...
      return finish(null, isValid, reason);
    }
  }
}, {
  ...
  validations: {
    'custom': {
      run: true,
      fn:  function (value, dataType, isRequired, finish) {
        ...
        return finish(null, isValid, reason);
      }
    }
  }
}

'email'

Checks to ensure we have a valid email address.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the validation running.

Example

{
  ...
  validations: {
    'email': true
  }
}, {
  ...
  validations: {
    'email': {
      run: true
    }
  }
}

'in-list'

Checks to ensure we the field value is in the provided list (array). Most useful for strings but can be used for other data types.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the validation running.
list Array Null An array of the values to test against.

Example

{
  ...
  validations: {
    'in-list': ['abc', 'def', 'ghi', 'jkl']
  }
}, {
  ...
  validations: {
    'in-list': {
      run:  true,
      list: ['abc', 'def', 'ghi', 'jkl']
    }
  }
}

'match-field'

Checks to ensure the field matches against another field, by default we only test the value and not the type unless the 'strict' option is set. Most useful for strings but can be used for other data types.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the validation running.
matchField String Null The name of the other field we must match.
strict Boolean False Set true to use the === operator and also check the Foval dataType matches.

Example

{
  ...
  validations: {
    'match-field': 'password'
  }
}, {
  ...
  validations: {
    'match-field': {
      run:        true,
      matchField: 'password',
      strict:     true
    }
  }
}

'numeric'

Runs various numeric validations on a field, depending on the options given.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the validation running.
min Float Null The minimum number allowed.
max Float Null The maximum number allowed.
allowZero Float True Set false to disallow '0' as a valid value.

Example

{
  ...
  validations: {
    'numeric': {
      run:       true,
      min:       -10,
      max:       10,
      allowZero: false
    }
  }
}

'password'

Uses the Countersign module to test the strength of the password.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the validation running.
requirements Object {} Pass in any of the Countersign options.

Default Requirements

See the Countersign documentation for the options you can use.

Property Value
length 6
lowercase True
uppercase True
common True

Example

{
  ...
  validations: {
    'password': true
  }
}, {
  ...
  validations: {
    'password': {
      run: true,
      requirements: {
        length:    6,
        lowercase: true,
        uppercase: true,
        common:    true
      }
    }
  }
}

'regexp'

Allows you to test the value of a field against a regular expression.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the validation running.
test RegExp/String Null A regular expression object or a string.
flags String Null Allows you to set flags if 'test' is a string regular expression.

Example

{
  ...
  validations: {
    'regexp': /[a-z0-9]+/gi
  }
}, {
  ...
  validations: {
    'regexp': {
      run:  true,
      test: /[a-z0-9]+/gi
    }
  }
}, {
  ...
  validations: {
    'regexp': {
      run:   true,
      test:  '[a-z]{0,' + qty + '}[0-9]+',
      flags: 'gi'
    }
  }
}

'required'

Used on fields that are required and tests to see if the field is actually populated. Returns a validation error if there is no value in the field, or the value isn't enough for the field to be considered populated. For example a required checkbox field needs a truthy value to be considered populated, a false value isn't enough and will fail this validation.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the validation running.

Example

{
  ...
  validations: {
    'required': true
  }
}, {
  ...
  validations: {
    'required': {
      run: true
    }
  }
}

'str-length'

Make sure the length of a string falls within a specific range.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the validation running.
min Int Null The minimum number of characters allowed.
max Int Null The maximum number of characters allowed.

Example

{
  ...
  validations: {
    'str-length': {
      run: true,
      min: 100,
      max: 300
    }
  }
}

'telephone'

Checks to ensure we have a valid telephone number. The validation will only pass if the telephone number is a string in one of these formats:

  • International Format: '+44.7912345678'
  • Local Format: '07912345678'

Options

Property Data Type Default Notes
run Boolean True Set false to stop the validation running.
minDigits Int 1 The minimum number of digits in the phone number, not including the country code.
maxDigits Int Null The maximum number of digits in the phone number, not including the country code.

Example

{
  ...
  validations: {
    'telephone': true
  }
}, {
  ...
  validations: {
    'telephone': {
      run:       true,
      minDigits: 5,
      maxDigits: 11
    }
  }
}

'url'

Checks to ensure we have a valid URL.

Options

Property Data Type Default Notes
run Boolean True Set false to stop the validation running.
requireProtocol Boolean True Set false to validate URLs that don't have a HTTP/S protocol.

Example

{
  ...
  validations: {
    'url': true
  }
}, {
  ...
  validations: {
    'url': {
      run:             true,
      requireProtocol: false
    }
  }
}

Install

npm i foval

DownloadsWeekly Downloads

1

Version

0.0.20

License

MIT

Last publish

Collaborators

  • avatar