check-rule-mate 0.0.1

package/README.md

@@ -0,0 +1,210 @@
+# check-rule-mate
+
+## Overview
+
+A lightweight and reusable JavaScript "library" for data validation. This library was  esigned to simplify the process of validating form inputs using flexible rules and error handling. Validating your data by allowing you to define flexible rules, custom error messages, and reusable helper functions—all in a structured format.
+
+The core goal is to provide a **reusable and easy-to-extend** for handling various form inputs, including fields like name, email, birthdate, phone number, and more.
+
+Test the core functionalities here: [check-rule-mate Demo](https://johnrock16.github.io/check-rule-mate/)
+(Note: Creating or modifying custom validators is not supported in the demo, as it requires JavaScript implementation.)
+
+
+## Features
+
+- **Custom Validation Rules**: Easily define custom rules for form fields.
+- **Modular Design**: Separation of rule definitions and error messages for easy management.
+- **Easy Integration**: Can be used in any JavaScript environment.
+- **Clear Error Handling**: Handles errors and displays messages.
+- **Extendable**: Create your custom validators and rules and extend as you want.
+
+## Advanced Features
+
+- **Modifiers:** Extend rules for specific use cases (e.g., age validation in a date rule).
+- **Dynamic Parameters:** Use $variable to access field data within rules.
+- **Modular Rules and Validators:** Create multiple files for rules and helpers, organizing them by context or form.
+
+## Table of Contents
+
+- [Getting Started](#Getting-Started)
+  - [Installation](#Installation)
+  - [Running Tests](#Running-Tests)
+- [How It Works](#How-It-Works)
+  - [Basic Example](#Basic-Example)
+- [Defining Validation Components](#Defining-Validation-Components)
+  - [1. Data Rules](#Data-Rules)
+  - [2. General Rules](#General-Rules)
+  - [3. Validation Helpers](#Validation-Helpers)
+  - [4. Error Messages](#Error-Messages)
+  - [5. Example Usage](#Example-Usage)
+    - [Vanilla](#vanilla)
+    - [Express](#express)
+    - [Frontend](#frontend)
+
+## Getting Started
+### Installation
+
+To install and start the library, run:
+```bash
+npm install
+npm start
+```
+
+### Running Tests
+
+Execute the test suite with:
+```bash
+npm test
+```
+
+## How It Works
+### Basic Example
+
+Here’s an example of validating a set of fields:
+```javascript
+  const { myValidator } = require('./dataValidator/validators');
+  const { dataValidate } = require('./dataValidator/dataValidate');
+  const MY_RULES = require('./dataValidator/rules/validators/myValidatorRules.json');
+  const CONTACT_US = require('./dataValidator/rules/data/contactUs.json');
+  const MY_VALIDATION_ERROR_MESSAGES = require('./i18n/en_US/errors/myValidatorRules.json');
+
+  const fields = {
+    name: "John",
+    lastName: "Doe",
+    email: "email@email.com",
+    emailConfirm: "email@email.com",
+    phone: "",
+    subject: "I need a coffee",
+    message: "Give me coffee"
+  };
+
+  // This should return { ok: true }
+  const result = dataValidate(fields, {
+    validationHelpers: myValidator,
+    rules: MY_RULES,
+    dataRule: CONTACT_US,
+    dataErrorMessages: MY_VALIDATION_ERROR_MESSAGES,
+  });
+```
+
+#### Parameters for dataValidate:
+
+- **fields**: The object containing data to be validated.
+- **validationHelpers**: Functions to validate field data (see /dataValidator/validators).
+- **rules**: General validation rules for your application.
+- **dataRule**: Specific rules linking fields to validation logic.
+- **dataErrorMessages**: Custom error messages returned upon validation failure.
+
+## Defining Validation Components
+
+### Data Rules
+
+Define rules for specific datasets, such as forms. Example for a "Contact Us" form:
+```json
+{
+  "name": { "rule": "name", "required": true },
+  "lastName": { "rule": "name", "required": true },
+  "email": { "rule": "email", "required": true },
+  "emailConfirm": { "rule": "email--confirm", "required": true },
+  "phone": { "rule": "phone", "required": false },
+  "subject": { "rule": "hasText", "required": true },
+  "message": { "rule": "hasText", "required": true }
+}
+```
+
+### General Rules
+
+Define reusable validation logic. Example:
+
+```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}[\/\\-](0?[1-9]|1[012])[\/\\-](0?[1-9]|[12][0-9]|3[01])$/",
+    "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"
+        }
+      }
+    }
+  }
+}
+```
+#### Key Components:
+
+- **validate**: Array of functions to execute for validation.
+- **error**: Error messages for validation failures.
+- **regex**: Regular expression for validation.
+- **modifier**: Overrides specific rules with additional validations.
+- **params**: Parameters for validation functions (e.g., $email accesses email field data).
+
+
+### Validation Helpers
+Helper functions perform actual validation. Example:
+
+```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];
+  }
+
+  return { regex, hasText, equals };
+};
+```
+
+### Error Messages
+
+Define custom error messages in a structured format:
+``` json
+{
+  "common": { "hasText": "Please fill out this field." },
+  "email": { "regex": "Enter a valid email address." }
+}
+```
+
+### Example Usage
+
+Explore examples in the examples folder folder.
+
+#### Vanilla
+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.
+#### Express:
+See how the check-rule-mate works in back-end using a middleware.
+#### Frontend:
+Here you can found the DEMO page and it's a type of "playground" to test how RULES works and validations works. (Here you can't create customized javascript so custom validatorHelpers are disabled by default)

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "check-rule-mate",
+  "version": "0.0.1",
+  "description": "",
+  "main": "./dist/main.cjs.js",
+  "type": "commonjs",
+  "scripts": {
+    "start": "node ./examples/vanilla/src/index.js",
+    "build": "node build",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "example:vanilla": "node ./examples/vanilla/src/index.js",
+    "example:express": "node ./examples/express/src/main.js"
+  },
+  "author": "João Rocha",
+  "license": "ISC",
+  "devDependencies": {
+    "esbuild": "^0.24.0",
+    "express": "^4.21.2",
+    "jest": "^29.7.0"
+  }
+}

package/src/js/dataValidate.js

@@ -0,0 +1,119 @@
+/**
+ * Validate your data fields using your rules, data rules and validators.
+ * @param {[DataField]} data - All the data fields to be validate
+ * @param {DataValidatorConfigs} config - The configs which will be followed during validation
+ * @returns {DataValidatorSuccessResponse | DataValidatorErrorResponse} - The response of your validation
+ */
+export function dataValidate(data, {validationHelpers = {}, rules, dataRule, dataErrorMessages = {}}) {
+    const dataErrors = {};
+
+    function getObjectValueByPath(obj, path) {
+        if (!obj || typeof path !== 'string') return undefined;
+
+        const keys = path.split('.');
+        let current = obj;
+
+        for (const key of keys) {
+            if (current[key] === undefined) return undefined;
+            current = current[key];
+        }
+
+        return current;
+    }
+
+    function inputValidation(dataAttribute, data = null) {
+        const { rule, required } = dataRule[dataAttribute.key];
+
+        if ((rule && required) || (!required && dataAttribute.value != '')) {
+            if (rule) {
+                const INPUT_RULE = rule.split('--')[0];
+                const RULE_MODIFIER = rule.split('--').length > 1 ? rule.split('--')[1] : '';
+                const dataAttributeValidation = dataAttributeValidator(dataAttribute.value, rules[INPUT_RULE], RULE_MODIFIER, validationHelpers, data);
+                const { isValid, errorMessage, errorType } = dataAttributeValidation.validate();
+                if (!isValid) {
+                    dataErrors[dataAttribute.key] = {
+                        name: dataAttribute.key,
+                        error: true,
+                        errorMessage: getObjectValueByPath(dataErrorMessages, errorMessage) || errorMessage,
+                        errorType: errorType
+                    }
+                }
+                return isValid;
+            }
+        }
+        return true;
+    }
+
+    function validate() {
+        let dataArr = Object.keys(data).map((key) => ({ key, value: data[key] }));
+        if (dataArr && dataArr.length > 0) {
+            if(!Object.keys(dataRule).every((key) => data.hasOwnProperty(key))) {
+                return { error: true, errorMessage: "Missing properties"}
+            }
+            const dataValidators = [...dataArr].map((input) => inputValidation(input, data));
+
+            if (dataValidators.some((element) => !element)) {
+                return { error: true, dataErrors: dataErrors };
+            }
+
+            const dataRuleArr = Object.keys(dataRule).map((key) => ({ key, required: dataRule[key].required}));
+            const dataAttributesKey = dataArr.map((attribute) => attribute.key);
+            const dataAttributesRequired = dataRuleArr.filter((rule) => rule.required).map((rule) => rule.key);
+
+            if (!dataAttributesRequired.every((fieldRequired) => dataAttributesKey.includes(fieldRequired))) {
+                return { error: true };
+            }
+        } else if (!dataArr || dataArr.length === 0) {
+            return { error: true, errorMessage: "Missing fields for dataRules"}
+        }
+        return { ok: true };
+    }
+
+    return validate();
+}
+
+/**
+ * A function to validate each attribute from a object [dataField]
+ * @param {string} value - The value to be validated
+ * @param {string} rule - The rule to be used during validation
+ * @param {string} modifier - The modifier of the rule if have
+ * @param {Function} customValidation - The function which will validate the value
+ * @param {[DataField]} data - The entire data fields
+ * @returns {{validate: Function}} the built function to validate all this parameters
+ */
+function dataAttributeValidator (value, rule, modifier = null, customValidation = null, data = null) {
+    function validateRules(rule) {
+        let errorMessage;
+        let errorType;
+        const isValid = !rule.validate.some((validation) => {
+            let isInvalid = true;
+            if ((rule.params && rule.params[validation] && rule.params[validation].length > 0)) {
+                const params = rule.params[validation].map((param) => (typeof param === 'string' && param[0] === '$') ? param.substring(1, param.length) : param);
+                isInvalid = !this[validation](...params)
+            } else {
+                isInvalid = !this[validation]()
+            }
+            if (isInvalid && !errorMessage && rule?.error[validation]) {
+                errorMessage = rule.error[validation];
+                errorType = validation;
+            }
+            return isInvalid;
+        });
+        return {isValid, errorMessage, errorType}
+    }
+
+    function validate() {
+        if (customValidation && typeof customValidation === 'function') {
+            const validation = customValidation(value, rule, modifier, data);
+            Object.keys(validation).forEach((key) => {
+                this[key] = validation[key];
+            })
+        }
+
+        return modifier ? validateRules.call(this, rule.modifier[modifier]) : validateRules.call(this, rule);
+    }
+
+    return({
+        validate
+    });
+}

package/src/main.js

@@ -0,0 +1,5 @@
+import { dataValidate } from  './js/dataValidate.js';
+
+export {
+    dataValidate,
+}

package/src/types.js

@@ -0,0 +1,62 @@
+/**
+ * @module typedefs
+ * This file contains all typedefs used in the project.
+ */
+
+/**
+ * @typedef {Object} DataField
+ * @property {string} name - The name and key of the field
+ * @property {string} value - the value of the field
+ */
+
+/**
+ * @typedef {Object} DataValidatorConfigs
+ * @property {ValidationHelpers} validationHelpers - The validator functions to help your validations
+ * @property {Object} rules - The rules you want to use through validation
+ * @property {dataRule} dataRule - The rules you want to use per field
+ * @property {Object} dataErrorMessages - The error messages you want to show during errors
+ */
+
+/**
+ * @typedef {Function} ValidatorHelper
+ * @param {any} value - The value to be validate
+ * @param {string} rule - The rules to be followed during validation
+ * @param {string} modifier - If rule has a modifier applied
+ * @param {[DataField]} data - The data fields object
+ * @returns {boolean} The validation result of the value
+ */
+
+/**
+ * @typedef {Object.<string, ValidatorHelper>} ValidationHelpers
+ */
+
+/**
+ * @typedef {Object} DataRule
+ * @property {dataRuleFiVeld} field - The field which will use the rule
+ */
+
+/**
+ * @typedef {Object} DataRuleField
+ * @property {string} rule - The validation rule for the field (e.g., "name", "email", "phone", "hasText").
+ * @property {boolean} required - Indicates whether the field is required.
+ */
+
+/**
+ * @typedef {Object.<string, DataRule>} DataRule - A dynamic object where the keys are field names and the values define the field rules.
+ */
+
+/**
+ * Represents a successful response.
+ *
+ * @typedef {Object} DataValidatorSuccessResponse
+ * @property {boolean} ok - Indicates the operation was successful.
+ */
+
+/**
+ * Represents an error response.
+ *
+ * @typedef {Object} DataValidatorErrorResponse
+ * @property {boolean} error - Indicates an error occurred.
+ * @property {string} [errorMessage] - A message describing the error (optional).
+ * @property {Object} [dataErrors] - Additional error details (optional).
+ */