Rule-based, extensible and async-friendly data validation engine for complex forms and business rules.
npm install check-rule-matecheck-rule-mate is a lightweight rule-driven validation engine for JavaScript.
Instead of coupling validation logic directly to schemas or fields, check-rule-mate separates concerns into rules, schemas, validators, and error messages, allowing you to build highly reusable, composable, and context-aware validations.
It is designed for scenarios where traditional schema-based validators start to feel limiting, especially when you need:
- Cross-field validation
- Contextual rules
- Async checks
- Reusable validation logic across multiple forms
- Full control over execution flow and error handling
- Lifecycle Hooks
Github repository: check-rule-mate repository
Examples of how implement check-rule-mate: check-rule-mate examples
Test the core functionalities here: check-rule-mate demo
(Note: Creating or modifying custom validators is not supported in the demo, as it requires JavaScript implementation.)
Use check-rule-mate if you:
- Need reusable validation logic across different forms and contexts
- Have complex or conditional validation rules
- Want full control over how validation runs
- Need async validations (API calls, database checks, etc.)
- Prefer rule-driven validation instead of tightly coupled schemas
- Want clean separation between rules, data, and messages
- You want to have auto documentation of your forms
check-rule-mate is built around four main concepts:
1. Rules: How data is validated
2. Schema: What should be validated
3. Validation Helpers: How rules are executed
4. Error Messages: How errors are communicated
This separation makes the system flexible, scalable, and easy to maintain.
- Rule-based validation engine
- Reusable validation rules
- Modifiers for contextual rule extensions
- Cross-field validation using dynamic parameters
- Async validation support
- Abort early or collect all errors
- Strict or loose schema matching
- i18n-ready error messages
- Framework-agnostic (frontend or backend)
- Auto documentation (automatic generated by a CLI command)
- Template checker (automatic checked by a CLI command)
- Getting Started
- NPM - Installation
- Repository - Installation
- Running Tests
- How It Works
- Basic Usage
- Lifecycle Hooks
- Auto documentation
- [[Experimental] - Documentation Playground](#experimental-documentation-playground)
- Auto Checker for Templates
- Defining Validation
- 1. Schema
- 2. Rules
- 3. Validation Helpers
- 4. Error Messages
- 5. Example Usage
- Vanilla
- Express
- Frontend
- When NOT to use check-rule-mate
- Full Documentation (in progress)
- License;
bash
npm install check-rule-mate
`$3
If you downloaded the repository you can install using:
bash
npm install
npm start
`$3
Execute the test suite with:
bash
npm test
`How It Works
$3
javascript
import MY_RULES from './rules/myValidatorRules.json' with { type: 'json' };
import CONTACT_US from './schemas/contactUs.json' with { type: 'json' };
import ERROR_MESSAGES from './i18n/en_US/errors.json' with { type: 'json' };import { createValidator } from 'check-rule-mate';
import { myValidator } from './validators/myValidator.js';
const fields = {
name: 'John',
lastName: 'Doe',
email: 'email@email.com',
emailConfirm: 'email@email.com',
phone: '',
subject: 'I need a coffee',
message: 'Give me coffee'
};
async function runFormValidate() {
const validator = createValidator(fields, {
validationHelpers: myValidator,
rules: MY_RULES,
schema: CONTACT_US,
errorMessages: ERROR_MESSAGES,
options: {
cache: true,
abortEarly: false,
propertiesMustMatch: true,
}
});
const result = await validator.validate();
// This should return { ok: true }
console.log(result);
}
runFormValidate();
`$3
A validation result follows this structure:When is valid:
javascript
{ ok: true }
`When is invalid and has errors:
typescript
{
error: true,
errors: {
[field: string]: {
name: string,
type: string,
message: string,
code: string,
}[];
};
}
`$3
The check-rule-mate lifecycle hooks allow you to observe, extend and react to the validation process without coupling logic to rules or helpers.Hooks are especially useful for:
- Logging and debugging
- Analytics and metrics
- Custom side-effects
- Integrating validation with UI or external systems
- Advanced error handling and reporting
- They provide fine-grained control over the validation lifecycle.
typescript
hooks?: {
onValidateStart?: (payload) => void;
onValidateFieldStart?: (payload) => void;
onValidateFieldError?: (payload) => void;
onValidateFieldSuccess?: (payload) => void;
onValidateEnd?: (payload) => void;
}
`#### Hook Payloads
#####
Triggered once before validation begins.
typescript
onValidateStart: ({ data }) => void
`Payload:
-
: Full form data object being validated#####
onValidateFieldStart
Triggered before validating each field.
typescript
onValidateFieldStart: ({ field, value, schemaField }) => void
`Payload:
-
: Field name
- value: Field value
- schemaField: Schema configuration for the field (or null if missing)#####
onValidateFieldError
Triggered when a field fails validation.
typescript
onValidateFieldError: ({ field, value, schemaField, error }) => void
`Payload:
-
: Field name
- value: Field value
- schemaField: Schema configuration for the field (or null if missing)
- error: Validation error object#####
onValidateFieldSuccess
Triggered when a field is successfully validated.
typescript
onValidateFieldSuccess: ({ field, value, schemaField }) => void
`Payload:
-
: Field name
- value: Field value
- schemaField: Schema configuration for the field (or null if missing)#####
onValidateEnd
Triggered once after validation finishes.
typescript
onValidateEnd: ({ data, errors }) => void
`Payload:
-
: Full form data object being validated
- errors: Validation errors (if any)
If no errors occurred, errors may be undefined.#### Hooks - Example Usage
`javascript
const validator = createValidator(fields, {
validationHelpers: myValidator,
rules: MY_RULES,
schema: CONTACT_US,
errorMessages: ERROR_MESSAGES,
hooks: {
onValidateStart: ({ data }) => {
console.log('Validation started', data);
}, onValidateFieldStart: ({ field, value }) => {
console.log(
Validating ${field}, value);
}, onValidateFieldError: ({ field, error }) => {
console.error(
Error on ${field}, error);
}, onValidateFieldSuccess: ({ field }) => {
console.log(
${field} validated successfully);
}, onValidateEnd: ({ data, errors }) => {
if (errors) {
console.log('Validation finished with errors', errors);
} else {
console.log('Validation finished successfully');
}
}
}
});
await validator.validate();
`$3
check-rule-mate contains a script to generate automatic documentation based in your rules, schemas and error messages.
To use that it is simple, you only need to run this command:
bash
npx check-rule-mate docs --rules {rules path} --schemas {schemas path} --errors {errors path} --out {file.html}
`This will generate a HTML file containing the rules, schemas and errors.
$3
> ⚠️ The playground executes bundled client-side JavaScript.
> Do not use untrusted validation code.
The Documentation Playground allows you to generate an interactive HTML page where you can test your schemas, rules, and validators directly in the browser.
This feature is experimental and intended mainly for development and exploration purposes. It bundles your validation logic into a client-side format, enabling real-time validation without any backend setup.
> ⚠️ Since this feature is experimental, APIs and behavior may change.
---
#### Requirements
The playground generator depends on optional dependencies that are not installed by default.
Before using it, make sure you have the required optional dependencies installed:
bash
npm install esbuild
`#### Usage
Run the playground generator using the CLI:
bash
npx check-rule-mate docs:playground \
--rules {rules-path} \
--schemas {schemas-path} \
--errors {errors-path} \
--options {options-path} \
--out {output-file.html}
`This command will generate a self-contained HTML file with:
- Documentation for your rules and schemas
- A playground to test validation behavior in real time
#### Options File
The playground requires an options file to map validator names to their source files.
Example:
json
{
"validators": {
"myValidator": "./examples/vanilla/src/check-rule-mate-rules/validators/validators.js",
"nameValidator": "./examples/vanilla/src/check-rule-mate-rules/validators/validators.js",
"myValidator2": "./examples/vanilla/src/check-rule-mate-rules/validators/validator2.js"
}
}
`
How it works:
- Keys represent the exported object/function/class name of your validator
- Values are paths to the files where those validators are defined
- These validators are bundled and made available inside the playgroundThis explicit mapping ensures predictable builds and avoids magic imports.
$3
You can auto check if your template it is working properly with all necessary properties or have something missing.It is works with:
, Rules and Errorsbash
npx check-rule-mate verify --rules {rules path} --schemas {schemas path} --errors {errors path}
`If everything it is working properly this should be your message:
bash
✔ Schemas loaded: 4
✔ Rules loaded: 6
✔ Errors loaded: 6✔ No issues found
`Else if some error was found could be something like that:
bash
✔ Schemas loaded: 4
✔ Rules loaded: 6
✔ Errors loaded: 6❌ Validation failed
❌ Schema "contactUs.json" → field "phone" references rule "cellphone" which does not exist
`
Defining Validation
$3
Schemas map data fields to rules.
json
{
"name": {
"rule": "name",
"required": true
},
"email": {
"rule": "email",
"required": true,
"cache": false,
},
"emailConfirm": {
"rule": "email--confirm",
"required": true,
"cache": false,
},
"phone": {
"rule": "phone",
"required": false
}
}
`#### Schema Properties
- rule: Rule name (supports modifiers via
)
- required: Whether the field must exist and not be empty
- cache: if this field will have cache or not$3
Rules define validation logic, independent of any specific form.
`json
{
"name": {
"validate": ["hasText"],
"error": { "hasText": "common.hasText" }
},
"email": {
"regex": "/^[a-z0-9.]+@[a-z0-9]+\\.[a-z]+(\\.[a-z]+)?$/i",
"validate": ["regex"],
"error": { "regex": "email.regex" },
"modifier": {
"confirm": {
"validate": ["regex", "equals"],
"params": { "equals": ["$email"] },
"error": { "equals": "email.equals" }
}
}
},
"date": {
"regex": "/^\\d{4}\/\\-\/\\-$/",
"validate": ["regex", "validDate"],
"error": {
"regex": "common.dateFormat",
"validDate": "date.validDate"
},
"modifier": {
"age": {
"validate": ["regex", "validateAge"],
"params": {
"validateAge": [18, 130]
},
"error": {
"regex": "common.dateFormat",
"validateAge": "date.modifier.age.validateAge"
}
}
}
}
}
`#### Rule Properties
- validate: Ordered list of validation functions
- regex: Optional regex used by the regex helper
- error: Error keys mapped to validation functions
- modifier: Contextual rule extensions
- params: Parameters passed to validation helpers
#### Modifiers (Contextual Rules)
Modifiers allow extending a rule without duplicating logic.
Example:
json
"email--confirm"
`Internally:
- Base rule: email
- Modifier: confirm
Modifiers can override:
- validate
- params
- regex
- error
This makes rules highly reusable and expressive.
#### Dynamic Parameters ($field)
Rules can reference other fields dynamically:
json
"params": {
"equals": ["$email"]
}
`At runtime:
-
resolves to data.email
- Enables cross-field validation
$3
Validation helpers are the runtime implementation of rules.javascript
const myValidator = function (value, rule, modifier = null, data = null) {
function regex() {
const regexTemplate = rule.modifier?.[modifier]?.regex || rule.regex;
const regex = new RegExp(regexTemplate);
return regex.test(value);
} function hasText() {
return value.trim().length > 0;
}
function equals(key) {
return value === data[key];
}
async function isDataFetched() {
try {
let result = await new Promise((resolve, reject) => {
setTimeout(() => {
const success = !!value;
if (success) {
resolve('Data fetched successfully!');
} else {
reject('Error fetching data');
}
}, 2000);
});
return !!result;
} catch (error) {
return false;
}
}
return { regex, hasText, equals, isDataFetched };
};
`#### Helper Signature
typescript
(value, rule, modifier?, data?) => Record
`Helpers:
- Can be sync or async
- Are stateless
- Do not know about schemas or error messages
$3
Errors are resolved via keys, not hardcoded strings.
json
{
"common": {
"hasText": "Please fill the field"
},
"email": {
"regex": "Please enter a valid email",
"equals": "Emails do not match"
}
}
`
This makes localization and message customization straightforward.$3
typescript
options: {
cache?: boolean, // If cache is enabled or not
abortEarly?: boolean, // Stop on first error
propertiesMustMatch?: boolean, // Schema vs data strictness
}
`Example Usage
Explore examples in the examples folder folder. Before execute any test change the type in package.json for module instead commonjs
Examples folder: Github repo examples folder.
$3
Here you are free to test anything you want about form validation, also We have a lot of tests scenarios in __tests__ which could be a great start.Command to run Vanilla example:
bash
npm run example:vanilla
`Vanilla example: Github repo vanilla file.
#### __tests__
Command to run tests:
bash
npm run test
`Unit tests examples: Github repo unit tests file.
$3
See how the check-rule-mate works in back-end using a middleware.Command to run Express example:
bash
npm run example:express
``Express example: Github repo express file.
Frontend example: check-rule-mate demo.