LcFormValidation

Overview

Let's say we want to add validation support for a login form with next constraints:

• login is mandatory and has to be a valid email address.
• password is mandatory.

To implement the form validation you just only need an object literal to declare the proper field validation constraints for the two fields:

// validation constraints definition
const validationConstraints = {
  fields: {
    login: [
      { validator: Validators.required },
      { validator: Validators.email }
    ],
    password: [
      { validator: Validators.required }
    ]
  }
};

Then create an instance of a FormValidation:

// create a form validation instance
const formValidation = createFormValidation(validationConstraints);

Finally apply validation when your data needs to be validate (e.g. a submit event handler):

// e.g. viewModel value: { login: 'johndoe@example.com', password: 'jdoe123' }
function onSave(viewModel) {
  formValidation
    .validateForm(viewModel)
    .then(validationResult => {
      if(validationResult.succeeded) {
        // we can now send it to server to validate credentials
      } else {
        // display validation errors on UI
        displayFormErrors(validationResult);
      }
    })
    .catch(error => {
      // Oops, an error happened...
      handleError(error.message);
    });
}

Validation constraint

Validation constraint is just an object literal passed with two main properties:

fields

An object containing all fields keys that need validations. Each field will have an array of FieldValidationConstraint objects, each one with three properties:

• validator A function that will validate the field and return a FieldValidationResult or a promise wrapping it if the validator is async
• eventsFilter (optional) An object containing one o more event names, that will be used as a filter when the validator needs to be triggered on a specific event, and a boolean value (true to use the filter). The default value is: { onChange: true }.
• customParams (optional) An object with some values needed by the validator (e.g. a date format).

fields: {
  <fieldName>: [
    {
      validator: <validatorFunction>, // function(value, viewModel, customParams)
      eventsFilter: {
        <eventName>: <boolean>,
        ...
      },
      customParams: { ... }
    }
  ]
}

global

The global property will hold an array of validation functions that will validate the entire viewModel:

global: [
  <globalValidatorFunction>, // function(viewModel)
  ...
]

Validating form

In order to validate a single field or the entire form you have to use the methods validateField and validateForm of the instance returned by createFormValidation described in the API section.

Validators.required

The required validator will check the value is not empty. This validator is useful when you need a fulfilled text field or a radio / checkbox button marked. These values are considered empty:

• null
• undefined
• false
• Empty string ""
• Whitespace only string " " (it can be disabled with customParams.trim set to false).

import { createFormValidation, Validators } from 'lc-form-validation';
const validationConstraints = {
  fields: {
    firstName: [
      { validator: Validators.required }
    ]
  }
};

const formValidation = createFormValidation(validationConstraints);

// Example of a successful validation
formValidation
  .validateField(null, 'firstName', 'John')
  .then(validationResult => {
    console.log(validationResult.succeeded); // true
    console.log(validationResult.type); // 'REQUIRED'
    console.log(validationResult.key); // 'firstName'
    console.log(validationResult.errorMessage); // ''
  });

// Example of a unsuccessful validation
formValidation
  .validateField(null, 'firstName', '')
  .then(validationResult => {
    console.log(validationResult.succeeded); // false
    console.log(validationResult.type); // 'REQUIRED'
    console.log(validationResult.key); // 'firstName'
    console.log(validationResult.errorMessage);
    // 'Please fill in this mandatory field.'
  });

Validators.minLength

The minLength validator will check if the length of the string passed as value is equals or greater than the length supplied in customParams.length.

Note: empty values such as "", null or undefined will be marked as valid values. If you need to check for non-empty values you may use this validator along with required validator.

Important! You must always providecustomParams.length and it must be a number. In case it is not provided an error will be thrown in the catch block of the returned promise.

import { createFormValidation, Validators } from 'lc-form-validation';

const validationConstraints = {
  fields: {
    username: [
      {
        validator: Validators.minLength,
        customParams: { length : 4 }
      }
    ]
  }
};

const formValidation = createFormValidation(validationConstraints);

// Example of a successful validation
formValidation
  .validateField(null, 'username', 'jasmine')
  .then(validationResult => {
    console.log(validationResult.succeeded); // true
    console.log(validationResult.type); // 'MIN_LENGTH'
    console.log(validationResult.key); // 'username'
    console.log(validationResult.errorMessage); // ''
  });

// Example of a unsuccessful validation
formValidation
  .validateField(null, 'username', 'jax')
  .then(validationResult => {
    console.log(validationResult.succeeded); // false
    console.log(validationResult.type); // 'MIN_LENGTH'
    console.log(validationResult.key); // 'username'
    console.log(validationResult.errorMessage);
    // 'The value provided must have at least 4 characters.'
  });

Validators.maxLength

The maxLength validator will check if the length of the string passed as value is lesser or equals than the length supplied in customParams.length.

Note: empty values such as "", null or undefined will be marked as valid values. If you need to check for non-empty values you may use this validator along with required validator.

Important! You must always providecustomParams.length and it must be a number. In case it is not provided an error will be thrown in the catch block of the returned promise.

import { createFormValidation, Validators } from 'lc-form-validation';

const validationConstraints = {
  fields: {
    password: [
      {
        validator: Validators.maxLength,
        customParams: { length : 8 }
      }
    ]
  }
};

const formValidation = createFormValidation(validationConstraints);

// Example of a successful validation
formValidation
  .validateField(null, 'password', 'test1234')
  .then(validationResult => {
    console.log(validationResult.succeeded); // true
    console.log(validationResult.type); // 'MAX_LENGTH'
    console.log(validationResult.key); // 'password'
    console.log(validationResult.errorMessage); // ''
  });

// Example of a unsuccessful validation
formValidation
  .validateField(null, 'password', 'loooooongp@s$w0rd')
  .then(validationResult => {
    console.log(validationResult.succeeded); // false
    console.log(validationResult.type); // 'MAX_LENGTH'
    console.log(validationResult.key); // 'password'
    console.log(validationResult.errorMessage);
    // 'The value provided is too long. Length must not exceed 8 characters.'
  });

Validators.pattern

The pattern validator will check if the value matches a regular expresion given in customParams.pattern option. This regular expression can be either a RegExp instance or a string. It's important to mention that flags in string patterns are not supported.

If you need flags in string patterns you can use the RegExp constructor.

Important! You must always providecustomParams.pattern. In case it is not provided an error will be thrown in the catch block of the returned promise.

import { createFormValidation, Validators } from 'lc-form-validation';

const CODE_PATTERN = /^LC\d{3}$/; // or "^LC\d{3}$"
const validationConstraints = {
  fields: {
    code: [
      {
        validator: Validators.pattern,
        customParams: { pattern: CODE_PATTERN }
      }
    ]
  }
};

const formValidation = createFormValidation(validationConstraints);

// Example of a successful validation
formValidation
  .validateField(null, 'code', 'LC001')
  .then(validationResult => {
    console.log(validationResult.succeeded); // true
    console.log(validationResult.type); // 'PATTERN'
    console.log(validationResult.errorMessage); // ''
  });

// Example of a unsuccessful validation
formValidation
  .validateField(null, 'code', '003a')
  .then(validationResult => {
    console.log(validationResult.succeeded); // false
    console.log(validationResult.type); // 'PATTERN'
    console.log(validationResult.key); // 'code'
    console.log(validationResult.errorMessage);
    // 'Please provide a valid format.'
  });

Validators.email

The email validator will check if the given string value is a valid email address. LcFormValidation's email validator uses a RegExp provided by emailregex.com that follows RFC 5322 Official Standard since email address validation is hard to implement and there is not an unique source of truth. If this email validator doesn't meet your requirements you can write your custom validator.

Note: empty values such as "", null or undefined will be marked as valid values. If you need to check for non-empty values you may use this validator along with required validator.

import { createFormValidation, Validators } from 'lc-form-validation';

const viewModel = null;
const validationConstraints = {
  fields: {
    email: [
      { validator: Validators.email }
    ]
  }
};

const formValidation = createFormValidation(validationConstraints);

// Example of a successful validation
formValidation
  .validateField(viewModel, 'email', 'johndoe@example.com')
  .then(validationResult => {
    console.log(validationResult.succeeded); // true
    console.log(validationResult.type); // 'EMAIL'
    console.log(validationResult.key); // 'email'
    console.log(validationResult.errorMessage); // ''
  });

// Example of a unsuccessful validation
formValidation
  .validateField(null, 'email', 'invalidValue')
  .then(validationResult => {
    console.log(validationResult.succeeded); // false
    console.log(validationResult.type); // 'EMAIL'
    console.log(validationResult.key); // 'email'
    console.log(validationResult.errorMessage);
    // 'Please enter a valid email address.'
  });

FieldValidationResult

FieldValidationResult is a simple class with three main properties:

• succeeded boolean - The result of a validation constraint.
• type string - An identifier to associate the validation result with a validator, it is useful for checking out what validation did not get passed when multiple validators on a field are applied.
• errorMessage string - A message describing why the field did not get validated. This field can be declared as empty for a successful validation.

A fourth read-only property is added when it is returned by validateForm or validateField named key that will hold the field name to distinguish which field the validation was made.

Note: You can use a plain object as validation result without extending the FieldValidationResult class.

Example of a FieldValidationResult

{
  succeeded: false,
  errorMessage: 'Please, fill in this mandatory field',
  type: 'REQUIRED',
  key: 'lastName'
}

FormValidationResult

FormValidationResult is an global validation result returned by validateForm. It has three main properties:

• succeeded boolean - The result of the entire form validation.
• fieldErrors { [key: string]: FieldValidationResult }; - An object of all field errors given as a result of validate every field. This property contains every field validation result, so it will be filled even if all validation passed.
• formGlobalErrors Array<FieldValidationResult> - A list of all global errors given as a result of executing every global validation function. This property can be empty if there are no errors.

Example of a FormValidationResult

{
  succeeded: true,
  fieldErrors: {
    emailAddress: {
      succeeded: true,
      errorMessage: '',
      type: 'EMAIL',
      key: 'emailAddress'
    }
  },
  formGlobalErrors: []
}

validateForm

formValidation.validateForm(vm: any): Promise<FormValidationResult>;

It validates the entire viewModel passed as argument triggering all field and global validations previously defined in validationConstraints. Field validations are proxied to validateField and global validations are executed.

When all validations are executed they're merged in a FormValidationResult and returned in a promise.

Example:

// Define a validator
function areAllFieldsCheckedValidation(vm) {
  const validationResult = new FieldValidationResult();
  const errorMessage = 'All fields must be checked';
  const isValid = areAllChecked(vm);
  validationResult.succeeded = validationResult;
  validationResult.type = 'ALL_CHECKED';
  validationResult.errorMessage = isValid ? '' : errorMessage;

  return validationResult;
}

function isAllChecked(vm) {
  return Object.keys(vm).every(field => vm[field].checked === true);
}

// Define the form validation constraints
const validationConstraints = {
  global: [areAllFieldsCheckedValidation]
}

// Create an instance of FormValidation
const formValidation = createFormValidation(validationConstraints);
const viewModel = {
  fieldA: { value: 'A', checked: true },
  fieldB: { value: 'B', checked: true },
  fieldC: { value: 'C', checked: true },
};

// Apply validation
formValidation
  .validateForm(viewModel)
  .then(validationResult => {
    console.log(validationResult.succeeded); // true
    console.log(validationResult.fieldErrors); // {}
    console.log(validationResult.formGlobalErrors);
    // [{ errorMessage: '', type: 'ALL_CHECKED', key: '_GLOBAL_FORM_', succeeded: true }]
  })
  .catch(error => {
    // handle error
  });

validateField

validateField(vm: any, key: string, value: any, eventsFilter?: ValidationEventsFilter): Promise<FieldValidationResult>;

It validates a value against all constraints for a field previously defined in validationConstraints. It will trigger every field validation function sequentially and evaluate its FieldValidationResult, if the validation result is not successful it will stop executing the next field validation function, so it will always return the first error.

It accepts four arguments:

• vm any - The entire viewModel. This can be optionally passed as null if your field validation does not needs to do checks againsts your viewModel.
• key string - The name of the field that requires validation. This key has to be the same as defined in your ValidationConstraints.
• value any - The value to validate against the field validation constraints.
• eventsFilter (optional) Object - An object with the signature { <eventName>: boolean } describing the event (or events) to filter what validation functions are triggered. Only the validations matching the filter will be executed. If you need to trigger a validation function multiple times you can add more event filters. The default value is: { onChange: true }. You can also define your custom event names.

Note: Events defined in eventsFilter object are not directly attached to DOM, their purpose is only to filter validation functions.

Important! Since every field validation function is executed sequentially the order you define the field validation functions matters.

Example - single validation:

// Define a validator
function firstUpperCaseValidator(value) {
  const validationResult = new FieldvalidationResult();
  const errorMessage = 'First name's first letter must be uppercase';
  const isValid = value.charAt(0).toUpperCase() === value.charAt(0);
  validationResult.succeeded = isValid;
  validationResult.errorMessage = isValid ? '' : errorMessage;
  validationResult.type = 'FIRSTNAME';

  return validationResult;
}

// Define the field validation constraints
const validationConstraints = {
  fields: {
    firstName: [
      { validator: Validators.required },
      { validator: firstUpperCaseValidator }
    ]
  }
};

// Create an instance of FormValidation
const formValidation = createFormValidation(validationConstraints);

// Apply validation
formValidation
  .validateField(null, 'firstName', 'John')
  .then(validationResult => {
    console.log(validationResult.succeeded); // true
    console.log(validationResult.errorMessage); // ''
    console.log(validationResult.type); // 'FIRSTNAME'
    console.log(validationResult.key); // 'firstName'
  })
  .catch(error => {
    // handle error
  });

isValidationInProgress

formValidation.isValidationInProgress(): boolean;

It checks if a form or a field validation is currently in progress by returning true or false.

Example:

const validationConstraints = {
  fields: {
    firstName: [
      { validator: Validators.required }
    ],
    lastName: [
      { validator: Validators.required }
    ],
  }
};

const formValidation = createFormValidation(validationConstraints);
const viewModel = {
  firstName: 'John',
  lastName: 'Doe',
};

formValidation
  .validateform(viewModel)
  .then(validationResult => {
    console.log(formValidation.isValidationInProgress()); // false (validation finished)
  });

console.log(formValidation.isValidationInProgress()); // true (validation started)

Using eventsFilter to filter validations

By default { onChange: true } is applied when the eventsFilter object is not passed. You can pass the name of a event or a identifier to track when certain validations are triggered..

Important! If you filter a validation using a non registered event name the FieldValidationResult will be undefined.

Let's take a look at the next example. Suppose we need to apply a validation to signup a new user and the username with the next constraints:

• The username is mandatory.
• The username can only contains lowercase letters and numbers.
• The username must not exist in the database.

We can apply the required and format validation when the user types and apply the database verification when the input foucs out. The resulting validation constraints would look like this:

const validationConstraints = {
  fields: {
    username: [
      { validator: Validators.required },
      {
        validator: Validators.pattern,
        customParams: { pattern: /^[a-z\d]+$/ },
        eventsFilter: { onChange: true, onBlur: true },
      },
      {
        // your custom validator that queries the database
        validator: usernameDoesNotExistsValidator,
        eventsFilter: { onBlur: true }
      }
    ]
  }
};

const formValidation = createFormValidation(validationConstraints);

Then attach the proper events to your form input and validate the field. For a jQuery implementation it would look like this:

$('#txtUsername').on({
  keyup: function() {
    formValidation
      .validateField(null, 'username', $(this).val())
      .then(function(validationResult) {
        if (validationResult.succeeded) {
          $('#usernameErrorMessage').hide().val('');
        } else {
          $('#usenameErrorMessage').val(validationResult.errorMessage).show();
        }
      });
  },
  blur: function() {
    formValidation
      .validateField(null, 'username', $(this).val(), { onBlur: true }) // apply event filter
      .then(function(validationResult) {
        if (validationResult.succeeded) {
          $('#usernameErrorMessage').hide().val('');
        } else {
          $('#usenameErrorMessage').val(validationResult.errorMessage).show();
        }
      });
  }
});

Note: This is a basic example, you could move this to a more mantenible helper instead of a huge object.

isFormPristine

formValidation.isFormPristine(): boolean;

It checks if the form was validated at least once using validateForm or validateField. It returns true or false.

Example:

const validationConstraints = {
  fields: {
    firstName: [
      { validator: Validators.required }
    ],
    lastName: [
      { validator: Validators.required }
    ],
  }
};

const formValidation = createFormValidation(validationConstraints);
const viewModel = {
  firstName: 'John',
  lastName: 'Doe',
};

console.log(formValidation.isFormPristine()); // true
formValidation
  .validateform(viewModel)
  .then(validationResult => {
    console.log(formValidation.isFormPristine()); // false
  });

isFormDirty

formValidation.isFormDirty(): boolean;

This method is the counterpart of isFormPristine. It will return false when then form was never validated, and true if it was.

const validationConstraints = {
  fields: {
    firstName: [
      { validator: Validators.required }
    ],
    lastName: [
      { validator: Validators.required }
    ],
  }
};

const formValidation = createFormValidation(validationConstraints);
console.log(formValidation.isFormDirty()); // false
formValidation
  .validateField(null, 'firstName', 'John')
  .then(validationResult => {
    console.log(formValidation.isFormDirty()); // true
  });