huex

Huex - Human Readable Regex Builder

Huex is a TypeScript library that makes regular expressions easy to write and understand. Instead of writing cryptic regex patterns, you can use simple, readable methods.

🎯 What it does:

• Makes regex human-readable - No more memorizing regex syntax
• Provides validation descriptions - Get clear error messages when validation fails
• Includes common patterns - Email, password, phone, URL, etc. ready to use
• Chainable API - Build complex patterns step by step
• TypeScript support - Full type safety and IntelliSense

🚀 Quick Start

import { regex, patterns } from 'huex';

// Instead of: /^[a-zA-Z]{6,20}$/
const username = regex()
    .start()
    .letter()
    .between(6, 20)
    .end()
    .description("Username must be 6-20 letters only");

// Test with clear error messages
username.test("abc123") 
// Returns: {success: false, errors: ["Username must be 6-20 letters only"]}

username.test("abcdef") 
// Returns: {success: true, errors: []}

📚 Examples

Basic Pattern Building

// Email validation
const email = regex()
    .start()
    .email()
    .end()
    .description("Must be a valid email address");

// Phone number validation
const phone = regex()
    .start()
    .phone()
    .end()
    .description("Must be a valid phone number");

// Custom pattern
const custom = regex()
    .start()
    .digit()
    .exactly(3)
    .literal('-')
    .letter()
    .between(2, 4)
    .end()
    .description("Format: 3 digits, dash, 2-4 letters");

Combining Patterns

const lengthValidation = regex()
    .start()
    .notChar('')
    .between(6, 20)
    .end()
    .description("Input must be more than 6 and less than 20 characters");

const alphabetValidation = regex()
    .start()
    .letter()
    .oneOrMore()
    .end()
    .description("must be only alphabets");

const password = regex()
    .use(lengthValidation)
    .use(alphabetValidation);

Pre-built Patterns

import { patterns } from 'huex';

// Common validation patterns
const emailPattern = patterns.email();
const urlPattern = patterns.url();
const phonePattern = patterns.phone();
const strongPasswordPattern = patterns.strongPassword();
const usernamePattern = patterns.username();

// Length patterns
const minLength8 = patterns.minLength(8);
const maxLength20 = patterns.maxLength(20);
const lengthBetween = patterns.lengthBetween(6, 20);

// Character patterns
const alphanumeric = patterns.alphanumeric();
const numeric = patterns.numeric();
const alphabetic = patterns.alphabetic();
const noWhitespace = patterns.noWhitespace();
const noSpecialChars = patterns.noSpecialChars();

Multiple Validation

import { validate } from 'huex';

const result = validate("test123", 
    patterns.minLength(8),
    patterns.alphanumeric()
);

// Returns: {success: false, errors: ["Must be at least 8 characters long"]}

🔧 API Reference

Core Methods

Pattern Building

• .start() - Add start anchor ^
• .end() - Add end anchor $
• .letter() - Match letters [a-zA-Z]
• .digit() - Match digits \d
• .lowercase() - Match lowercase letters [a-z]
• .uppercase() - Match uppercase letters [A-Z]
• .alphanumeric() - Match letters and numbers [a-zA-Z0-9]
• .whitespace() - Match whitespace \s
• .word() - Match word characters \w

Quantifiers

• .oneOrMore() - Match one or more +
• .zeroOrMore() - Match zero or more *
• .optional() - Match zero or one ?
• .exactly(count) - Match exactly {count}
• .atLeast(count) - Match at least {count,}
• .atMost(count) - Match at most {0,count}
• .between(min, max) - Match between {min,max}

Custom Patterns

• .char(chars) - Match specific characters [chars]
• .notChar(chars) - Match any character except [^chars]
• .literal(text) - Match exact text (escaped)
• .email() - Match email pattern
• .url() - Match URL pattern
• .phone() - Match phone number pattern
• .ipv4() - Match IPv4 address pattern
• .strongPassword() - Match strong password pattern

Grouping and Alternation

• .group(pattern) - Create capturing group (pattern)
• .or(pattern) - Create alternation |pattern

Combining

• .use(otherBuilder) - Combine with another pattern
• .description(text) - Set validation description

Flags

• .caseInsensitive() - Add i flag
• .global() - Add g flag
• .multiline() - Add m flag

Testing Methods

• .test(input) - Test input and return validation result
• .match(input) - Find matches in input
• .replace(input, replacement) - Replace matches
• .build() - Get final RegExp object
• .getPattern() - Get pattern string
• .getDescription() - Get description
• .getFlags() - Get flags string
• .getInfo() - Get pattern info object

Utility Functions

• regex() - Create new builder
• patterns.* - Pre-built common patterns
• combine(...builders) - Combine multiple builders
• validate(input, ...builders) - Validate against multiple patterns

🎨 Advanced Examples

Complex Email Validation

const complexEmail = regex()
    .start()
    .group(() => regex().alphanumeric().oneOrMore())
    .literal('@')
    .group(() => regex().alphanumeric().oneOrMore())
    .literal('.')
    .group(() => regex().letter().between(2, 4))
    .end()
    .description("Custom email validation");

Password with Multiple Requirements

const password = regex()
    .start()
    .group(() => regex().lowercase().oneOrMore()) // At least one lowercase
    .group(() => regex().uppercase().oneOrMore()) // At least one uppercase
    .group(() => regex().digit().oneOrMore())     // At least one digit
    .group(() => regex().char('@$!%*?&').oneOrMore()) // At least one special char
    .between(8, 128) // Length between 8-128
    .end()
    .description("Strong password requirements");

Case Insensitive Pattern

const caseInsensitive = regex()
    .start()
    .literal('hello')
    .end()
    .caseInsensitive()
    .description("Case insensitive hello");

📦 Installation

# Using Bun (recommended)
bun add huex

# Using npm
npm install huex

# Using yarn
yarn add huex

# Using pnpm
pnpm add huex

🔍 TypeScript Support

Huex is written in TypeScript and provides full type safety:

import { HuexBuilder, ValidationResult } from 'huex';

const builder: HuexBuilder = regex();
const result: ValidationResult = builder.test("test");

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License.

Bottom line: Write regex patterns that actually make sense! 🎯