v8n

JavaScript fluent validation library

README

v8n

The ultimate JavaScript validation library you've ever needed.

Dead simple fluent API. Customizable. Reusable.

CircleCI npm version npm bundle size (minified + gzip)

Installation -Documentation -API

Buy Me A Coffee


Introducing v8n


v8n is an acronym for v_alidatio_n. Notice that it has exactly

eight letters between v and n in the _"validation"_ word. This is the

same pattern we are used to seeing with _i18n_, _a11y_, _l10n_ ...


Chainable API


Create validations very easily with its chainable API:

  1. ``` js
  2. v8n()
  3.   .string()
  4.   .minLength(5)
  5.   .first("H")
  6.   .last("o")
  7.   .test("Hello"); // true
  8. ```

Incredibly fluent


Mix rules and modifiers together to create complex validations with
great ease and fluency:

  1. ``` js
  2. v8n()
  3.   .array()
  4.   .every.number()
  5.   .not.some.negative()
  6.   .test([1, 2, -3]); // false - no negative please!
  7. ```

So fluent that it looks like English:

  1. ``` js
  2. v8n()
  3.   .some.not.uppercase() // expects that some character is not uppercase
  4.   .test("Hello"); // true

  5. v8n()
  6.   .not.some.uppercase() // expects that no character is uppercase
  7.   .test("Hello"); // false
  8. ```

Notice how we made very different validation strategies just by changing the
order of the modifiers. It's so intuitive that seems to be impossible, but this
is v8n.

Customizable


Create your own custom validation rules in a very intuitive way:

  1. ``` js
  2. function foo() {
  3.   return value => value === "bar";
  4. }

  5. v8n.extend({ foo });
  6. ```

v8n will treat them like built-in ones:

  1. ``` js
  2. v8n()
  3.   .string()
  4.   .foo()
  5.   .test("bar"); // true
  6. ```

Reusable


Export validations just like you're used to do with your JavaScript modules:

_specialNumber.js_

  1. ``` js
  2. import v8n from "v8n";

  3. export default v8n()
  4.   .number()
  5.   .between(50, 100)
  6.   .not.even();
  7. ```

and use them anywhere you want:

  1. ``` js
  2. import specialNumber from "../specialNumber";

  3. specialNumber.test(63); // true
  4. ```

For any kind of data


Use v8n to validate your data regardless of its type. You can validate
primitives, arrays, objects and whatever you want! You can also use them
together!

  1. ``` js
  2. // numbers
  3. v8n()
  4.   .number()
  5.   .between(5, 10)
  6.   .test(7); //true

  7. // strings
  8. v8n()
  9.   .string()
  10.   .minLength(3)
  11.   .test("foo"); // true

  12. // arrays
  13. v8n()
  14.   .array()
  15.   .every.even()
  16.   .test([2, 4, 6]); // true

  17. // objects
  18. const myData = { id: "fe03" };

  19. v8n()
  20.   .schema({
  21.     id: v8n().string()
  22.   })
  23.   .test(myData); // true
  24. ```

For any kind of validation


Do simple validations with boolean based tests. Get more information about your
validation process with exception based tests. And of course, perform
asynchronous tests as well. All in one library.

Boolean based validation:


  1. ``` js
  2. v8n()
  3.   .string()
  4.   .first("H")
  5.   .test("Hello"); // true
  6. ```

Exception based validation:


  1. ``` js
  2. try {
  3.   v8n()
  4.     .string()
  5.     .first("b")
  6.     .check("foo");
  7. } catch (ex) {
  8.   console.log(ex.rule.name); // first
  9. }
  10. ```

Getting all failures:


  1. ``` js
  2. const failed = v8n()
  3.   .string()
  4.   .minLength(3)
  5.   .testAll(10);

  6. failed;
  7. // [
  8. //   ValidationError { rule: { name: "string", ... } },
  9. //   ValidationError { rule: { name: "minLength", ... } }
  10. // ]
  11. ```

Async validation:


If your validation strategy has some rule that performs time consuming
validation, like a back-end check, you should use asynchronous validation:

  1. ``` js
  2. v8n()
  3.   .somAsyncRule()
  4.   .testAsync("foo") // returns a Promise
  5.   .then(result => {
  6.     /* valid! */
  7.   })
  8.   .catch(ex => {
  9.     /* invalid! */
  10.   });
  11. ```

Shareable


Share your rules with the world, and use theirs as well.

Create useful validation rules and share them with the open source community,
and let people around the world validate without reinventing the wheel.

Ready to use!


There are a lot of built-in rules and modifiers for you to use already
implemented in v8n's core. Take a look at all of them in our
API page. But if you can't find what you
need, go ahead and make it.

Tiny!


All these incredible features for just a few bytes:

npm bundle size (minified + gzip)

Architecture


The v8n core is composed of rules and modifiers. They are used together
to build complex validations in an easy way.

Rules


Rules are the heart of the v8n ecosystem. You use them to build your
validation strategies:

  1. ``` js
  2. v8n()
  3.   .string()
  4.   .minLength(3)
  5.   .test("Hello"); // true
  6. ```

In this code snippet, we're using two rules (string and minLength) to build
our validation strategy. So our validated value ("Hello") is valid because
it's a string and it is at least 3 characters long.

Rules can be more powerful if used along with _modifiers_. Learn about them in

the next section.


Modifiers


Modifiers can be used to change rules meaning. For example, you can use the
not modifier to expect the reversed result from a rule:

  1. ``` js
  2. v8n()
  3.   .not.equal(5)
  4.   .test(5); // false
  5. ```

You can check all available modifiers on our documentation page.


Modifiers are very powerful. They work as decorators for rules. When used
together, they allow you to build very complex validations.

Contribute


Contributions of any kind are welcome! Read our

License