formeasy

formeasy is a package that allows validating forms and displaying error messages in an easy way

Summary

• Installation
• Usage example in vue
• Features
  • UseForm composable
  • Validation rules
  • Helpers
  • Types
• Create a validation rule

Installation

npm install formeasy

Usage example in vue

<script lang="ts" setup>

import { UseForm, required } from 'formeasy'

const form = ref({
  firstname: {
    value: '',
    validationRules: [
      required(),
    ]
  },
  lastname: {
    value: '',
    validationRules: [
      required(),
    ]
  }
})

const {
  formIsValid,
  getError,
  reset
} = UseForm(form.value)

const submitForm = () => {

  if (formIsValid()) {
    // do something
    reset()
  }

}

</script>

<template>
  <form
    @submit.prevent="submitForm"
  >

    <div>
      <label for="firstname">Firstname</label>
      <input type="text" id="firstname" v-model="form.firstname.value">
      <p
        v-if="getError('firstname')"
      >{{ getError('firstname') }}</p>
    </div>

    <div>
      <label for="lastname">Lastname</label>
      <input type="text" id="lastname" v-model="form.lastname.value">
      <p
        v-if="getError('lastname')"
      >{{ getError('lastname') }}</p>
    </div>

    <div>
      <button type="submit">Submit</button>
    </div>

  </form>
</template>

Features

UseForm composable

It's the main composable of the package. It allows to validate a form and get error messages.

import { UseForm } from 'formeasy'

const {
  formIsValid,
  getError,
  getErrors,
  reset
} = UseForm()

Name	Params	Description
formIsValid	()	Validate a form and returns true or false whether the form is valid or not
getError	(fieldName: string)	Returns the first error message for the field fieldName if it exists
getErrors	(fieldName?: string)	If fieldName is provided, returns all error messages fo the field fieldName, otherwise all messages for all fields
reset	()	Reset the form to its initial state

Validation rules

Validation rules are functions that return true if the field is valid, otherwise an error message. To date, the following validation rules are available:

import {
  required,
  onlyLetters,
  minLength,
  matches,
  pattern
} from 'formeasy'

Name	Params	Defaults	Description
required	({ message?: string })		Returns an error message if the field is empty
onlyLetters	({ message?: string })		Returns an error message if the field contains other characters than letters
onlyNumbers	({ message?: string })		Returns an error message if the field contains other characters than numbers
isEmail	({ message?: string })		Returns an error message if the field is not a valid email address
minLength	({ min?: number, message?: string })	min: 3	Returns an error message if the field length is less than min
maxLength	({ max?: number, message?: string })	max: 10	Returns an error message if the field length is more than max
matches	({ field: string, message?: string })		Returns an error message if the field value is different from field's value
pattern	({ pattern: RegExp, message?: string })		Returns an error message if the field value doesn't match pattern

You can specify a custom error message by passing the message parameter to the validation rule function.

required({message: 'This is a custom message'})
minLength({min: 5, message: 'You can also replace placeholders: {min}'}) // => You can also replace placeholders: 5

Helpers

import {
  getMessage,
  getFormValues
} from 'formeasy'

Name	Params	Description
getMessage	(params: TValidationRuleWrapperParams)	Returns the message with the placeholders replaced by the values of the params object. params must contain at least a message property. Example: getMessage({ message: 'One {two} three {four}, two: '2', four: '4' }) => 'One 2 three 4'
getFormValues	(form: TFormCollection)	Returns the values of the form as an object. The keys are the field names and the values are the field values.

Types

For information, here are the types used in the package:

interface IForm {
  value: string
  validationRules?: TValidationRulesCollection
}

type TFormValues = Record<string, any>

type TFormCollection = Record<string, IForm>

type TValidationRulesCollection = Array<TValidationRule>

type TValidationRuleWrapper = (params?: TValidationRuleWrapperParams) => TValidationRule
type TValidationRuleWrapperParams = Record<string, any>

interface IValidationRuleParams {
  value: any
  formValues?: any
  required?: boolean
}
type TValidationRule = ({ value, formValues, required }: IValidationRuleParams) => TValidationRuleResult
type TValidationRuleResult = boolean | string

type TErrorsCollection = Record<string, TErrorMessagesCollection>
type TErrorMessagesCollection = Array<TErrorMessage>
type TErrorMessage = string

Create a validation rule

You can create your own validation rules according to the following:

const myCustomRule: TValidationRuleWrapper = (params: TValidationRuleWrapperParams = {}): TValidationRule => {
  // Merge defaults params with the params passed to the function
  params = {
    message: 'This is the default error message',
    someDefaultParam: 'foo',
    ...params
  }
  // Return the final function that tests the value.
  // The function takes an object as a parameter. See below for more details.
  return ({ value }: IValidationRuleParams): TValidationRuleResult => {
    // The logic of the validation rule.
    // Returns true if the field is valid, otherwise an error message.
    // You can use the getMessage(param) helper to replace placeholders in the message
    return /*value is valid ?*/ || getMessage(params)
  }
}

The final function accepts an object as a parameter. This object contains the value to be tested, the values of the other fields of the form and a boolean indicating whether the field is required or not (true if the required validation rule is included in the validationRules array, otherwise false). Example below:

const isDoubleOf: TValidationRuleWrapper = (params: TValidationRuleWrapperParams = {}): TValidationRule => {
  params = {
    message: 'This field must be the double of "{field}" field',
    ...params
  }
  const {
    field
  } = params
  return ({ value, formValues, required }: IValidationRuleParams): TValidationRuleResult => {
    // If the field is required, return the double verification, otherwise return true
    const isEqualToDouble = Number(value) === Number(formValues[field]) * 2
    const shouldDisplayMessage = getMessage(params)

    return required
      ? (isEqualToDouble || shouldDisplayMessage)
      : (Number(value)
        ? (isEqualToDouble || shouldDisplayMessage)
        : true)
  }
}

You can also use other validation rules in your custom validation rule:

const mustBeSolidPassword: TValidationRuleWrapper = (params: TValidationRuleWrapperParams = {}): TValidationRule => {
  params = {
    message: 'This field must be a solid password',
    ...params
  }
  return ({ value }: IValidationRuleParams): TValidationRuleResult => {
    // Use the pattern validation rule with a solid password regex.
    // Note that the return is the call of the result of the pattern validation rule.
    return pattern({
      pattern: /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{8,}$/,
      ...params
    })({ value })
  }
}

Finally, you can use your custom validation rules as seen previously:

const form = ref({
  double: {
    value: '',
    validationRules: [
      isDoubleOf({ field: 'single' }),
    ]
  },
  password: {
    value: '',
    validationRules: [
      // You still can provide a custom params (and message)
      mustBeSolidPassword({ message: `The password you provided is not secure enough` })
    ]
  }
})