Numerous Pulls Merged

    v8n
    TypeScript icon, indicating that this package has built-in type declarations

    1.4.0 • Public • Published

    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 validation. 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:

    v8n()
      .string()
      .minLength(5)
      .first("H")
      .last("o")
      .test("Hello"); // true

    Incredibly fluent

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

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

    So fluent that it looks like English:

    v8n()
      .some.not.uppercase() // expects that some character is not uppercase
      .test("Hello"); // true
    
    v8n()
      .not.some.uppercase() // expects that no character is uppercase
      .test("Hello"); // false

    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:

    function foo() {
      return value => value === "bar";
    }
    
    v8n.extend({ foo });

    v8n will treat them like built-in ones:

    v8n()
      .string()
      .foo()
      .test("bar"); // true

    Reusable

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

    specialNumber.js

    import v8n from "v8n";
    
    export default v8n()
      .number()
      .between(50, 100)
      .not.even();

    and use them anywhere you want:

    import specialNumber from "../specialNumber";
    
    specialNumber.test(63); // true

    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!

    // numbers
    v8n()
      .number()
      .between(5, 10)
      .test(7); //true
    
    // strings
    v8n()
      .string()
      .minLength(3)
      .test("foo"); // true
    
    // arrays
    v8n()
      .array()
      .every.even()
      .test([2, 4, 6]); // true
    
    // objects
    const myData = { id: "fe03" };
    
    v8n()
      .schema({
        id: v8n().string()
      })
      .test(myData); // true

    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:

    v8n()
      .string()
      .first("H")
      .test("Hello"); // true

    Exception based validation:

    try {
      v8n()
        .string()
        .first("b")
        .check("foo");
    } catch (ex) {
      console.log(ex.rule.name); // first
    }

    Getting all failures:

    const failed = v8n()
      .string()
      .minLength(3)
      .testAll(10);
    
    failed;
    // [
    //   ValidationError { rule: { name: "string", ... } },
    //   ValidationError { rule: { name: "minLength", ... } }
    // ]

    Async validation:

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

    v8n()
      .somAsyncRule()
      .testAsync("foo") // returns a Promise
      .then(result => {
        /* valid! */
      })
      .catch(ex => {
        /* invalid! */
      });

    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:

    v8n()
      .string()
      .minLength(3)
      .test("Hello"); // true

    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:

    v8n()
      .not.equal(5)
      .test(5); // false

    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 CONTRIBUTING guide.

    License

    MIT License

    Install

    npm i v8n

    DownloadsWeekly Downloads

    25,918

    Version

    1.4.0

    License

    MIT

    Unpacked Size

    191 kB

    Total Files

    30

    Last publish

    Collaborators

    • bruno02221