Introduction

risii is a chain-based validation library designed for highly flexible, expressive, and dynamic form validation.

It offers:

• ✨ Declarative, fluent API
• ✨ Dynamic schema generation
• 🔒 Masked fields (****)
• 🔗 Field dependencies (shouldEqualFieldValue)
• 🔁 Pre/post action hooks
• 💾 Persistent validation storage (FORMIK_DATA)
• ⚡ Field-level + form-level validation
• 🎯 Perfect for React, React Native, Vue, and plain JS

Installation

npm install risii

Basic Usage

import { Chain as Validator } from "risii";

const chain = new Validator();

const schema = chain.schema({
  phone: chain.required().number().exactly(10).end(),
});

Chainable validation methods

| Method | Description | | ------------------------------ | -------------------------------- | | required() | Field must not be empty | | string() | Must be a string | | number() | Must contain only digits | | boolean() | Must be true/false | | min(n) | Minimum length | | max(n) | Maximum length | | exactly(n) | Must equal length n | | minPieces(n) | Min number of words | | maxPieces(n) | Max number of words | | startsWith(x) | Value must start with x | | endsWith(x) | Value must end with x | | shouldBeFollowedBy([...]) | Next character must be from list | | isEqualTo(value) | Compare with external value | | shouldEqualFieldValue(key) | Must match another field | | shouldMask() | Masks field (****) | | shouldUpdate() | Force persistence | | isRefferedBy(key) | Reverse dependency | | dependsOn(key) | Depends on another field | | messages(obj) | Override error messages | | actionBefore(fn) | Pre-validation hook | | actionAfter(fn) | Post-validation hook | | isLastField() | Marks last form field | | end() | Ends the chain |

import {Chain as Validator} from 'validatr/index.ts';

const loginMessages = {
  phoneNumber: {
    number: 'Phone number must be a number',
    exactly: 'Phone number must be exactly 9 numbers',
    startsWith: 'Phone number should start with digits 7',
    followedBy: 'Phone number should be followed by digits 8 or 9',
    required: 'Phone number is a required field',
  },
};

export const getLoginSchema = (
  actionAfters = {},
  actionBefores = {},
  setTransporter,
  doAfterAll,
) => {
  let chain = new Validator();
  chain.setErrorTransporter(setTransporter);
  chain.setActionAfterAll(doAfterAll);

  return {
    schema: chain.schema({
      phoneNumber: chain
        .required()
        .number()
        .exactly(9)
        .actionAfter(actionAfters?.phoneNumber)
        .actionBefore(actionBefores?.phoneNumber)
        .messages(loginMessages.phoneNumber)
        .startsWith(7)
        .shouldBeFollowedBy(['8', '9'])
        .isLastField()
        .end(),
    }),
    chain,
  };
};

Field-Level Validation

skema.chain.validate({ phoneNumber: value });

console.log(skema.chain.validated);

Output

{
  "phoneNumber": {
    "validation": { "valid": true },
    "value": "789123456"
  }
}

Form Submission

chain.handleSubmit(validValues => {
  console.log("Submitted:", validValues);
});

This performs:

• Full schema validation
• actionAfterAll
• Returns

React Integration

Field-Level Validation Example

<input
  value={value}
  onChange={async e => {
    const v = e.target.value;
    setValue(v);
    await skema.chain.validate({ phoneNumber: v });
  }}
/>

Full Example

const LoginForm = () => {
  const [values, setValues] = useState({ phoneNumber: "" });
  const [errors, setErrors] = useState({});

  const { schema, chain } = getLoginSchema(
    null,
    { phoneNumber: v => setValues({ phoneNumber: v }) },
    setErrors,
    () => console.log("All valid")
  );

  const handleSubmit = async e => {
    e.preventDefault();
    await chain.validate(values);
    chain.handleSubmit(v => console.log("Submitted:", v));
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={values.phoneNumber}
        onChange={async e => {
          const v = e.target.value;
          setValues({ phoneNumber: v });
          await chain.validate({ phoneNumber: v });
        }}
      />
      {errors.phoneNumber?.message && (
        <p>{errors.phoneNumber.message}</p>
      )}
      <button type="submit">Submit</button>
    </form>
  );
};

Questions & Support

For questions and support please use risiijs's Suppport page on Github repo.

Issues

Please make sure to read the Issue Reporting Checklist before opening an issue. Issues not conforming to the guidelines may be closed immediately.

Changelog

Detailed changes for each release are documented in our Changelog.

Release Notes

A summary of release changes can be found in our Release Notes.

Stay In Touch

Twitter @ntsakosurprise.

Contribution

Please make sure to read the Contributing Guide before making a pull request. If you have an risii plugin, add it with a pull request.

Licence

MIT - see the LICENSE file for details.

copyright (c) 2018-present. Ntsako (Surprise) Mashele