ex-validator

Ex Validator

• A lightweight and flexible TypeScript validation library for validating strings, numbers, booleans, arrays, objects, dates, tuples, URLs, emails, and custom rules.
• Supports required and optional fields, min/max constraints, enums, custom checks, and chaining. Works with ES Modules, CommonJS, and TypeScript.

Installation

npm i ex-validator

Quick summary

• ExValidator is chainable and stores a list of rule functions to evaluate a single value.
• ex(value) is the entry point that returns a new ExValidator.
• .run() executes all rules and returns { valid: boolean, errors: string[] }.
• createReqValidator enforces presence + type + optional min/max.
• createOptValidator skips validation if the value is null, undefined, or "" (empty string).
• A set of shortcut helpers (reqStr, optEmail, etc.) make common checks easy.

Importing

• ES Modules / TypeScript

import { ex, reqStr, optNum, reqEmail, optURL } from "ex-validator";

• CommonJS

const { ex, reqStr, optNum, reqEmail, optURL } = require("ex-validator");

Basic Usage

import { reqStr, reqNum, reqBool } from "ex-validator";

const nameValidation = reqStr("Luna", "Name is required", 3, 50);
console.log(nameValidation);
// { valid: true, errors: [] }

const ageValidation = reqNum(15, "Age is required", 18, 99);
console.log(ageValidation);
// { valid: false, errors: ["Must be at least 18"] }

ExValidator Class

import { ex } from "ex-validator";

const validation = ex("hello")
  .required()
  .type("string")
  .min(3)
  .max(10)
  .run();

console.log(validation);
// { valid: true, errors: [] }

Validation Methods

• • Required

ex(value).required("Field is required").run();

• • Type : Supported types("string" | "number" | "boolean" | "object" | "function" | "array" | "date" | "tuple")

ex([1, 2, 3]).type("tuple").run();
ex(new Date()).type("date").run();
ex(value).type("array", "Must be an array").run();

• • Min / Max / Between: Works for numbers, strings (length), and arrays (length).

ex("hello").min(3).max(10).run();
ex([1, 2]).between(1, 5).run();
ex(42).between(10, 50).run();

• • Enum

ex("blue").enum(["red", "green", "blue"]).run();

• • Custom

ex(10).custom((val) => val % 2 === 0, "Must be even").run();

• • Run

const result = ex(value).required().type("string").run();
console.log(result.valid, result.errors);

Shortcut Helper Functions

• Required Fields : reqStr, reqNum, reqBool, reqArr, reqObj, reqDate, reqTuple, reqURL, reqEmail

//  min and max parameters are optional : reqStr(value, msg, min, max)
reqStr("hello", "Name is required", 3, 20);
reqEmail("[e-mail]", "Invalid email address");
reqURL("https://example.com", "Invalid URL");

• Optional Fields: optStr, optNum, optBool, optArr, optObj, optDate, optTuple, optURL, optEmail

optStr("optional value", "Invalid string", 2, 10);
optEmail("[e-mail]", "Invalid email address");
optURL("https://example.com", "Invalid URL");

Tuples

• Tuples are validated as arrays. For specific element types or lengths, use .custom():

reqTuple([1, "two"], "Invalid tuple").run();

reqTuple([1, 2]).custom(
  (val) => Array.isArray(val) && val.length === 2 && typeof val[0] === "number",
  "Tuple must have a number and a string"
).run();

Dates

reqDate(new Date(), "Invalid date").run();
optDate(undefined, "Invalid date").run();

URLs

reqURL("https://example.com", "Invalid URL").run();
optURL("ftp://example.com", "Invalid URL").run();

Emails

• reqEmail and optEmail doesn't support min and max parameters cause they have minimum length of 3 and maximum length of 254 by default

reqEmail("[e-mail]").run();
optEmail("invalid-email").run();

Custom Validation Example

import { ex } from "ex-validator";

const result = ex("hello123")
  .custom((val) => /^[a-z]+$/.test(val as string), "Only lowercase letters allowed")
  .run();

console.log(result);
// { valid: false, errors: ["Only lowercase letters allowed"] }

Chaining

• All methods support chaining:

ex("abc")
  .required()
  .type("string")
  .min(2)
  .max(10)
  .custom((val) => val.includes("a"), "Must contain 'a'")
  .run();

Validation Result

• All validators return: valid → true if all rules pass, errors → array of error messages

interface ValidationResult {
  valid: boolean;
  errors: string[];
}