rgex

RGex

A powerful, chainable regex builder platform with comprehensive validation utilities and natural language processing to convert human text into regular expressions.

Features

• Fluent Regex Builder: Construct complex regular expressions with a simple, chainable API.
• Text-to-Regex (t2r): Convert natural language descriptions into regex patterns.
• Advanced Password Validation: Analyze password strength against multiple criteria and generate strong passwords.
• Pre-built Patterns: A large library of common patterns for emails, URLs, credit cards, and more.
• Modular & Lightweight: Import only the features you need to keep your bundle size small.
• Fully Typed: Written in TypeScript for a great developer experience.

Installation

npm install rgex

bun install rgex

Quick Start

RGex offers multiple ways to create and use regular expressions, from natural language to a fluent builder.

Text-to-Regex (t2r)

Instantly convert a human-readable string into a regex pattern.

import { t2r } from 'rgex';

// Simple email pattern
const emailResult = t2r('email address');
const emailRegex = emailResult.pattern; // /^[a-zA-Z0-9...
console.log(emailRegex.test('[e-mail]')); // true

// Complex pattern
const result = t2r('password with 2 uppercase, 2 numbers, and 12+ characters');
console.log(result.pattern.test('MyP@ssword123')); // true

Fluent Builder (rgex)

Chain methods together to build a custom regex pattern.

import { rgex } from 'rgex';

const pattern = rgex()
	.start()
	.literal('user-')
	.digit()
	.quantifier(4)
	.end()
	.build(); // /^user-\d{4}$/

console.log(pattern.test('user-1234')); // true
console.log(pattern.test('user-abcd')); // false

Password Validation

Analyze password strength or generate a new strong password.

import { validatePassword, generateStrongPassword } from 'rgex';

// Validate a password
const validation = validatePassword('WeakPass1');
console.log(validation.strength); // 'fair'
console.log(validation.score); // 55
console.log(validation.error); // { message: '...', requirements: ['...'] }

// Generate a strong password
const newPassword = generateStrongPassword(16);
// e.g., 'aB5!cDe6$fGh7#iJk'
console.log(newPassword);

API Reference

Top-Level Functions

t2r(humanText, [testValue])

Converts a human-readable text description into a regex pattern. This is the core of the natural language processing feature. Aliases: h2r, textToRegex, humanToRegex, parseHumanTextToRegex.

• humanText: string - The natural language description of the pattern.
• testValue: string (optional) - A string to test the generated pattern against to improve confidence.
• Returns: TextExtractionResult - An object containing the pattern, confidence score, and description.

import { t2r } from 'rgex';

const result = t2r('url with https only');

if (result.success) {
	console.log(result.pattern);
	// /https:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_\+.~#?&//=]*)/
	console.log(result.confidence); // e.g., 0.8
}

rgex([pattern], [options])

Factory function to create a new RGex builder instance.

• pattern: string (optional) - An initial regex pattern string.
• options: RegexBuilderOptions (optional) - Initial regex flags.
• Returns: A new RGex instance.

import { rgex } from 'rgex';

const pattern = rgex('\\d{3}', { global: true });
console.log(pattern.toString()); // /\d{3}/g

RGex Class

The core class for building regular expressions.

new RGex([pattern], [options]) or RGex.create([pattern], [options])

Creates a new RGex instance.

import { RGex } from 'rgex';

const builder = new RGex();
// or
const builder = RGex.create();

Builder Methods

All builder methods are chainable.

• .start(): Asserts the start of the string (^).
• .end(): Asserts the end of the string ($).
• .literal(text): Appends a literal string, escaping special characters.
• .raw(pattern): Appends a raw, unescaped regex pattern string.
• .digit(): Matches any digit (\d).
• .word(): Matches any word character (\w).
• .whitespace(): Matches any whitespace character (\s).
• .any(): Matches any character except newline (.).
• .group(pattern): Creates a capturing group (...).
• .or(pattern): Appends an OR operator (|).
• .quantifier(min, [max]): Specifies repetitions {min,max}.
• .oneOrMore(): Appends +.
• .zeroOrMore(): Appends *.
• .optional(): Appends ?.
• .lookahead(pattern, [negative]): Appends a positive (?=...) or negative (?!...) lookahead.
• .lookbehind(pattern, [negative]): Appends a positive (?<=...) or negative (?<!...) lookbehind.
• .email(), .url(), .phone(), etc.: Appends pre-built patterns.
• .global(true), .ignoreCase(true), etc.: Sets regex flags.
• .build(): Returns the final RegExp object.
• .test(input): Tests the pattern against a string.

import { RGex } from 'rgex';

const usernameRegex = RGex.create()
	.start()
	.charClass('a-zA-Z') // Must start with a letter
	.charClass('a-zA-Z0-9_')
	.quantifier(2, 19) // Followed by 2-19 word chars
	.end()
	.ignoreCase()
	.build(); // /^[a-zA-Z][a-zA-Z0-9_]{2,19}$/i

console.log(usernameRegex.test('ValidUser_123')); // true

Password Utilities

validatePassword(password, [options])

Analyzes a password against a set of rules.

• password: string - The password to validate.
• options: PasswordValidationOptions (optional) - Customize validation rules (e.g., minLength, hasNumber).
• Returns: PasswordValidationResult - An object with score, strength, and pass/fail details for each rule.

import { validatePassword } from 'rgex';

const result = validatePassword('P@ssw0rd123', {
	minLength: 10,
	noCommonWords: true,
});

console.log(result.strength); // 'strong'
console.log(result.score); // 85

generateStrongPassword([length], [options])

Generates a strong, random password.

• length: number (optional, default: 12) - The desired password length.
• options: PasswordValidationOptions (optional) - Customize required character sets.
• Returns: string - A securely generated password.

import { generateStrongPassword } from 'rgex';

const password = generateStrongPassword(16, { hasSymbol: true });
console.log(password);

Other Utility Functions

escapeRegex(text)

Escapes special regex characters in a string.

import { escapeRegex } from 'rgex';

console.log(escapeRegex('hello (world)')); // 'hello \(world\)'

isValidRegex(pattern)

Checks if a string is a valid regex pattern.

import { isValidRegex } from 'rgex';

console.log(isValidRegex('^[a-z]+$')); // true
console.log(isValidRegex('[a-z')); // false

Constants

REGEX_PATTERNS

An object containing a large collection of pre-built regex patterns as strings.

import { REGEX_PATTERNS } from 'rgex';

const uuidRegex = new RegExp(REGEX_PATTERNS.UUID);
console.log(uuidRegex.test('123e4567-e89b-12d3-a456-426614174000')); // true

COMMON_PASSWORDS

An array of common passwords used by the validatePassword function.

import { COMMON_PASSWORDS } from 'rgex';

console.log(COMMON_PASSWORDS.includes('password')); // true

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue.

License

This project is licensed under the MIT License.

A project by @duonguyen.site AKA codetails.site