arc-validate*

*readme generated by AI

A lightweight, dependency-minimal runtime type validator for JavaScript and Node.js.

It integrates with arc-is for general type detection and email-validator for email verification, while adding explicit handling for common validation cases like integers, floats, UUIDs, and explicit literal matching.

✨ Features

• Validates primitive and structured types using arc-is
• Custom checks for:
  • parseInt / parseFloat numeric validation
  • email using email-validator
  • uuid (RFC 4122 v1–v5 pattern)
  • explicit matching for literal values
  • null inclusion when allowed in _types
• Consistent TypeError messages with optional customError override
• Lightweight and dependency-minimal

📦 Installation

npm install arc-validate

🧩 Usage

import validateTypes from 'arc-validate';

// ✅ Strings
validateTypes('hello', ['string']); // ok

// ✅ Numbers
validateTypes(123, ['number']); // ok

// ✅ Integer Parsing
validateTypes('42', ['parseInt']); // ok
validateTypes('abc', ['parseInt']); // throws TypeError

// ✅ Float Parsing
validateTypes('3.14', ['parseFloat']); // ok
validateTypes('NaN', ['parseFloat']); // throws TypeError

// ✅ Emails
validateTypes('[email protected]', ['email']); // ok
validateTypes('invalid', ['email']); // throws TypeError

// ✅ UUIDs
validateTypes('123e4567-e89b-42d3-a456-426614174000', ['uuid']); // ok
validateTypes('invalid-uuid', ['uuid']); // throws TypeError

// ✅ Explicit literals
validateTypes('on', ['explicit', 'on', 'off']); // ok
validateTypes('maybe', ['explicit', 'on', 'off']); // throws TypeError

// ✅ Allow nulls explicitly
validateTypes(null, ['string', null]); // ok

// ✅ Custom Error
const customErr = new RangeError('Custom validation failed');
validateTypes('bad', ['email'], customErr); // throws customErr

🧠 Behavior Summary

| Type Token | Behavior | |-------------|-----------| | 'parseInt' | Checks that parseInt(_unknown) returns a valid number. | | 'parseFloat' | Checks that parseFloat(_unknown) returns a valid number. | | 'email' | Validates with email-validator. | | 'uuid' | Validates against RFC 4122 v1–v5 UUID regex. | | 'explicit' | Removes "explicit" from _types and requires _unknown to equal one of the remaining values. | | null | If _types includes null and _unknown === null, validation passes. | | Default | Uses arc-is’s is(_unknown) result and compares against _types. |

🧪 Example: Integration

import validateTypes from 'arc-validate';

function processUser(input) {
  validateTypes(input.email, ['email']);
  validateTypes(input.id, ['uuid']);
  validateTypes(input.role, ['explicit', 'admin', 'user', 'guest']);
  console.log('All fields validated!');
}

processUser({
  email: '[email protected]',
  id: '123e4567-e89b-42d3-a456-426614174000',
  role: 'admin'
});

🧱 Error Handling

All validation failures throw a TypeError (or a custom error if provided).

try {
  validateTypes('not-an-email', ['email']);
} catch (err) {
  console.error(err.message); // "Expected email. Received: not-an-email"
  console.error(err instanceof TypeError); // true
}

✅ Testing

Comprehensive Jest tests are included. Run:

npm test

📄 License

This project is released under The Unlicense, placing it in the public domain.