npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

jb-validation

v0.2.0

Published

validation module

Downloads

1,048

Readme

JBValidation

GitHub license NPM Downloads

standard validation module that enables you to implement high interactive validation web-components and framework components with zero effort.

  • modular so it can be used anywhere.
  • support regex & custom validation function.
  • reactive and customizable.
  • support async validations.
  • fast & reliable
  • integrate with jb-form to make zero config form with highly customizable validation methods

installation

npm install jb-validation

Architecture

jb-validation is a universal validation module that let you simplify validations process.
to achieve our goal we make jb-validation Async first mean checkValidation return Promise by default, despite all your validations were sync or not.
in 90% of front-end use cases we just need sync Validation in our component or in our apps so we recommend you to use sync methods for your default useCases in front-end components and add some async methods beside them for more complex use cases. but in other scenario like web-services and etc please use Async first approach.

here we have ValidationHelper class that is a base class of our validation system. in every component or module that want to implement jb-validation first we have to create a instance of ValidationHelper class and then infract with it. this document have 2 sections:

  1. how to interact with already implemented module inside any component.
  2. how to implement jb-validation in a new component.

before we start to see how to use validations methods we must get familiar with some types in jb-validation:

validator:

a regex or function that test value and return true/false or string or Promise<boolean | >.

ValidationItem:

single validation item with validator AND A default error message in case of invalidity and other meta data like validation type & defer.

ValidationList:

list of validation Item to validate your value with. if value pass all the list validators it's considered as a valid value.

ValidationValue

validation value is the value you need for your validator functions parameter. it's may be the same with component value or it may be different with it. for example in jb-date-input value is date ISO string like 2024-05-11 but in our validator we need more data to validate the date like Date object so we define it in our ValidationValue type.

getting started

in every web-component that support jb-validation as a validation method you must follow 3 step 1- provide a validation list(contain validator and message)
2- call check validation method
3- check the result its easy and straight forward like the example:

component.validation.list = [
  {
    validator: /.{3}/g,
    message: "your value must have at least 3 char",
  },
];
//check validity and get the result
//sync result will ignore async validator or async value
const result = component.validation.checkValiditySync({showError:true});
//async validator that also support async validation getter and async validator function. will return promise
const asyncResult = component.validation.checkValidity({showError:true});
//do whatever you want with the result
console.log("isInputValid:", result.isAllValid);
asyncResult.then((asyncResultData)=>{console.log("isInputValid:", asyncResultData.isAllValid);})

providing validation

there is 2 way to provide a validation to the module 1- provide a validation list directly by an array of validator

component.validation.list = [
  {
    validator: /.{3}/g,
    message: "your value must have at least 3 char",
  },
];

2- register a function that return validation list:

const getValidations = () => {
  return [
    {
      validator: /.{3}/g,
      message: "your value must have at least 3 char",
    },
  ];
};
component.validation.addValidationListGetter(getValidations);

in the second method getValidations will be called on each validation check so if you have a complex validation logic that may change base on your app states or component states it's better to use second way to make sure everything is controlled.
remember both way can be used together and you can even add multiple ValidationListGetter in more complex situations.

validators

validations in jb-validation follow this typescript type:

//ValidationValue will be different base on the implementor component
export type ValidatorFunction<ValidationValue> = (
  value: ValidationValue,
) => boolean | string | Promise<boolean | string>;
export type ValidationItem<ValidationValue> = {
  /**
   * @property validation function or regex to match value with
   */
  validator: RegExp | ValidatorFunction<ValidationValue>;
  /**
   * @property error message that will be shown if validator return false or regex failed
   */
  message: string;
  /**
   *  @property type of error (category) its optional
   */
  stateType?: keyof ValidityStateFlags;
  /**
   * @property defer validator execution until all non-deferred validation executed.(good for async validator)
   */
  defer?: boolean;
};

it means you can pass a regex or function as a validator and there is a optional stateType that indicate which standard has been violated.

function validator

function validator have many benefits one of them is that they may be defined in a scope that contain your app states and variables (like in react components or hooks or angular class). it means that you can access your own app variables and write a logic in your function base on your need. for example:

function setValidations(validStudentList = []) {}
component.validation.list = [{
  validator: (student) => validStudentList.includes(student),
  message: "this student is not in our valid student list",
}];

the other benefits is that you can have very complex logic for your input because its just a plain function and if you return string instead of boolean we assume it as an Error message and show it to the user.

function setValidations(blackList = []) {}
component.validation.list = [{
  validator: (studentName) => {
    if (blackList.includes(studentName)) {
      return `${studentName} is in the black list try someone else`;
    }
    return true;
  },
  message: "this message will shown if you return false",
}];

async validator

you can also set async validator function to check validation with your server or doing heavy search. to achieve this you just have to return promise in your validator function.

function setValidations(validStudentList = []) {}
component.validation.list = [{
  validator: ({ displayValue, value }) => {
    return new Promise((resolve) => {
      isEmailTaken(value).then(({ isTaken, suggestionMail }) => {
        if (isTaken) {
          if (suggestionMail) {
            //invalid value with custom message
            resolve(`${value} is taken. but you can pick ${suggestionMail}`);
          } else {
            //invalid value with default message
            resolve(false);
            //we dont support promise reject so please always resolve your promise. 
          }
        } else {
            // valid value
          resolve(true);
        }
      });
    });
  },
  message: "email is already taken",
  // will wait for all non async validation to be valid then execute. if not set it may cause delay in validation display even for sync validation
  defer:true,
}];

remember all async validator will be executed after sync one and deferred validation will only execute when all non-deferred one were valid. so if you want your async validator does not execute until all other validator passes, set defer:true so it will execute when all other validation is passed.

implement in new a web-component

if you have a web-component and you want to ad jb-validation support to it you just have to create a instance of ValidationHelper in your component.
after that just pas some callbacks function that jb-validation need to interact with your component and then you will have the validation support into your web-component.

Other Related Docs: