Skip to content
Isomorphic validation javascript library ISOMORPHIC-VALIDATION

Validation().constraint() method

Adds Predicates or predicate functions as constraints to a Validation instance.

Syntax

Validation().constraint(predicateFunction)
Validation().constraint(Predicate(predicateFunction))
Validation().constraint(predicateFunction, options)
Validation().constraint(Predicate(predicateFunction), options)

Parameters

  • predicateFunction
    A function which returns either a Boolean value or a Promise of a Boolean value. Instead of a function a Predicate object which wraps the function can be passed in.

  • options optional
    An object that specifies predicate execution features. The available options are:

    • next optional
      Defines execution of the predicates following after the current one. When set to false, the predicates added after this will not be executed and will be invalidated and canceled (if their execution was deferred by the debounce option) until the current predicate is valid.
      Default: true.

    • debounce optional
      Deferres execution of the current predicate by the specified time in milliseconds. This parameter is intended for the client side only and ignored on the server side.
      Default: 0.

    • keepValid optional
      When set to true, assigns (restores) a previous valid value or the initial value (if there was no previous valid value) by the specified path of the validatable object. Runs restored state callbacks.
      Default: false.

    • anyData optional
      Any type of data under any names can be passed. It will be accessible by the specified names through the Validation().constraints property and in ValidationResult.
      Default: undefined.

Return value

The Validation object.

Exceptions

  • If neither a function nor a Predicate is passed as the first parameter throws the corresponding error.

  • If anyData property names clash with Predicate API, throws the corresponding error.

Description

Adds a predicate function to the predicate group associated with the bound validatableObject of the single Validation. When invoked on a grouping Validation, does it for each predicate group of the Validation. A predicate function must return either a Boolean value, if it is synchronous, or a Promise that fulfills with a Boolean value, if it is asynchronous, otherwise the Validation().validate() method will throw an error or return a rejected Promise respectively.

Examples

Parameter “next”

Suppose, an e-mail is needed to be validated and checked for being registered. It doesn’t make sense to perform a relatively costly operation such as making a request to the server and therefore making the server to query an email record from a database if the typed in data does not conform to the basic requirement - to be a valid e-mail. This case illustrates the main purpose of the next parameter - performing further constraints validation only when previous constraints are met. In other words, if predicates added after the parameter next set to false can not return “valid” without the previous one having returned “valid” there is no point to execute them, especially if they are “costly”.

Start typing an email and watch the console. First, only isEmail will be getting invoked, but once you’ve typed a valid e-mail, isEmailRegistered starts getting invoked.

Parameters “next” and “debounce”

This example extends the previous one in a way that now predicate execution following after the constraint added with the parameter next is deferred by the debounce parameter. As it is shown in the previous example, isEmailRegistered gets invoked on every change of the e-mail field once the typed in e-mail becomes a valid e-mail. This may lead to excessive requests to the server. Applying the debounce parameter solves this issue.

Invalidate predicates following after

A constraint added with the parameter next=false when invalid invalidates all the constraints added after it.

Start typing an e-mail address. Watch the console. While isEmail is invalid, isEmailRegistered gets invalidated.

Cancel deferred execution

Once an e-mail address is entered in the proper format isEmailRegistered starts getting deferred on further changes of the e-mail field. If one of these further changes introduces an e-mail address that does not conform to the E-mail format the execution of isEmailRegistered that was deferred earlier should be canceled. Otherwise it will be performed with irrelevant data, asuming it makes a request to the server, it will make an unnecessary request and get an irrelevant response. So deferred execution of predicates following after the one added with the parameter next=false is canceled automatically in case that one is invalid.

Enter an e-mail in the proper format, wait for the hourglass icon ”⏳” which appears after isEmailRegistered execution gets deferred. Make a change to the e-mail incompatible with the proper format. You will see in the console that the actual deferred predicate was not executed. Its execution was canceled.

Parameter “anyData”

This example keeps bulding up on the previous one. Here translated validator messages are accessed by i18n keys supplied with predicate functions as anyData while adding constraints which in turn are accessed through ValidationResult in state callbacks by i18nMsg helper function.

Parameter “keepValid”

This option allows to completely prevent input of certain characters. It can be used to restrict input fields to accept only allowed characters or ignore unwanted characters.

In this example the input field is restricted to accept only letter characters. Additionaly, Predicate().started() and Predicate().restored() state callbacks can be used to perform some side effects like saving and restoring the caret position.