Validator

Dependency-light validation rules, assertions, and string normalization helpers.

Capabilities

• Extensive collection of string/value predicates (email, URL, JWT, UUID, date, IP address, credit cards, etc.)
• Normalization and sanitization tools (trim, escape HTML, blacklist/whitelist characters, email lowercasing)
• Structured rule executor (validateValue, assertValid) throwing descriptive ValidationError on failure
• Monolithic frozen validator object exporting all package utilities on a single import surface

AI Agent Quick Reference

Core Exports

| Export | Type | Description | | --- | --- | --- | | validateValue<V>(val: V, rules: ValidatorRule[]): ValidationResult | Function | Runs validation checklist against target value. Returns result status list. | | assertValid<V>(val: V, rules: ValidatorRule[]): ValidationResult | Function | Runs checks. Throws ValidationError if validation fails. | | createRule<V>(code: string, test: (...) => boolean, msg?: string): ValidatorRule | Function | Instantiates a custom reusable validation rule. | | validator | Object | Frozen namespace exposing all validation predicates and sanitizers. | | ValidationError | Class | Custom error throwing on validation failures. |

Core Types

• ValidatorRule<V>:
  • code: string
  • message?: string
  • test: (context: ValidatorRuleContext<V>) => boolean
• ValidationResult<V>:
  • value: V
  • normalizedValue: string
  • isValid: boolean
  • issues: ValidationIssue[] (where issue has code: string and optional message?: string)

Common Validation Rules

import { assertValid, createRule, isEmail, isPresent } from "@azlib/validator";

const required = createRule("required", ({ normalizedValue }) => isPresent(normalizedValue), "Value is required");
const email = createRule("email", ({ value }) => isEmail(value), "Must be an email address");

// Throws ValidationError if rules fail
assertValid("[email protected]", [required, email]);

Validator Facade

For codebases that prefer a single namespace import instead of named function imports:

import { validator } from "@azlib/validator";

const isURL = validator.isURL("https://google.com");
const booled = validator.toBoolean("1"); // true
const safeHtml = validator.escapeHtml("<script>"); // "&lt;script&gt;"

Behavioral Gotchas

• Coercion Defaults: Calling normalizeValidationValue (or checking predicates) with null or undefined normalizes values into an empty string "" by default, rather than throwing type errors.
• Email Normalizer: normalizeEmail lowercase transforms local parts and domains by default, and trims Gmail sub-addresses (e.g. [email protected] -> [email protected]).
• No Heavy Dependencies: Unlike libraries such as Zod, this package is designed for fast, dependency-light string parsing and formatting assertions, and does not require complex object schema compiling.