Data.Validation provided a way of modelling composable validations. Folktale 2 keeps the same structure and semantics, but there’s some changes in how you extract values out of Validations and test them. You can look at the full documentation for Validation for more detailed information.

Contents

• Constructing
• Pattern matching
• Testing instances
• Validation.ap
• Equality testing
• Validation.get
• Validation.fromEither
• Validation.failureMap

Constructing

Constructing Validation values remains the same, but the import changes.

Previously:

const Validation = require('data.validation');

Validation.Success(1);
Validation.Failure(2);

Now:

const Validation = require('folktale/validation');

Validation.Success(1);
Validation.Failure(2);

Pattern matching

Previously it was possible to pattern match on a Validation value by using the .cata(patterns) method. This method would take the value inside of the data structure and pass it on as positional arguments to the proper function:

const Validation = require('data.validation');

Validation.Success(1).cata({
  Success: (value) => value + 1,
  Failure: (value) => value - 1
});
// ==> 2

Now, the preferred method in Validation is .matchWith(patterns), which works similarly, but passes an object with the fields instead of each value as positional argument:

const Validation = require('folktale/validation');

Validation.Success(1).matchWith({
  Success: (x) => x.value + 1,
  Failure: (x) => x.value - 1
});
// ==> 2

Testing instances

Previously, Validation had isSuccess and isFailure boolean properties, which could be accessed to test whether a particular value was a Success or a Failure:

const Validation = require('data.validation');

const x = Validation.Success(1);
const y = Validation.Failure(1);

x.isSuccess;      // ==> true
x.isFailure;      // ==> false

y.isSuccess;      // ==> false
y.isFailure;      // ==> true

Folktale 2 replaces these with a .hasInstance(value) function on the variant constructors and on the type. Variant testing can now be safely done with this function, including on values that may be null or undefined:

Validation.ap

The new applicativeFn.apply(applicativeValue) method is the recommended way of using applicative functors now, which is standardised across Folktale and independent of Fantasy-Land changes.

.apply and .ap still have the same semantics, but those semantics are different from the new fantasy-land/ap function! In order to write functions that are generic over different Fantasy-Land implementations and versions, the new fantasy-land module should be used instead.

Equality testing

Previously validation had a .isEqual method, which checked if two validation values had the same tag and the same value (compared by reference):

const Validation = require('data.validation');

Validation.Success(1).isEqual(Validation.Success(1));
// ==> true

Validation.Success([1]).isEqual(Validation.Success([1]));
// ==> false

Now, Validation and other Folktale structures have a .equals method that does a similar test, but compares values structurally if they’re Fantasy-Land setoids, arrays, or plain JavaScript objects:

const Validation = require('folktale/validation');

Validation.Success(1).equals(Validation.Success(1));
// ==> true

Validation.Success([1]).equals(Validation.Success([1]));
// ==> true

More details can be found on the Equality derivation documentation.

Validation.get

Previously, Validation had a .get() method that would extract the value of a Success structure, but throw an error if you had a Failure structure:

const Validation = require('data.validation');

Validation.Success(1).get();    // ==> 1
Validation.Failure(1).get();    // ==> [Error: Can't extract the value of a Failure]

This was unsafe, so in order to clearly signal that Folktale 2 has deprecated all .get() m ethods, and introduced a new .unsafeGet() one. You may use the new .unsafeGet() one if you really know what you’re doing, but the method name now signals that you should be careful with it:

const Validation = require('folktale/validation');

Validation.Success(1).unsafeGet();    // ==> 1
Validation.Failure(1).unsafeGet();    // ==> [Error: Can't extract the value of a Failure]

You’re strongly encouraged to use the .getOrElse(default) method instead, which does not suffer from the same partiality problem:

Validation.Success(1).getOrElse(null);    // ==> 1
Validation.Failure(1).getOrElse(null);    // ==> null

Validation.fromEither

Either was replaced by Result in Folktale 2, and so the new method is Validation.fromResult.

Please see the Migrating from Data.Either documentation if you have Either values in your code base.

Validation.failureMap

Previously, Validation had a .failureMap(f) method, which worked like .map(f) for Failure values:

const Validation = require('data.validation');

Validation.Failure(1).failureMap(x => x + 1);
// ==> Validation.Failure(2)

This was a mess, with each structure naming that method in a different way. Folktale 2 standardises these as map{Tag} instead. So Validation gets a .mapFailure(f):

const Validation = require('folktale/validation');

Validation.Failure(1).mapFailure(x => x + 1);
// ==> Validation.Failure(2)