human-regex

Human Regex 🤖➡️👤

Human-friendly regular expression builder with English-like syntax.

Features

• 🧩 Intuitive builder pattern with chainable methods
• 🎯 Prebuilt validators for common patterns (emails, URLs, phone numbers)
• 📚 Comprehensive character classes and quantifiers
• 🛡️ Type-safe implementation with TypeScript
• ⚡ Memoized patterns for better performance
• 🔍 Supports all standard regex flags

Table of Contents

• Installation
• Usage
  • Basic Example
  • Predefined Patterns
• Comprehensive API Reference
  • Core Methods
  • Quantifiers
  • Anchors & Groups
  • Validation Helpers
  • URL Components
  • Flags
  • Unicode Properties
  • Predefined Patterns
• Examples
• Contributing
• License

Installation

npm install human-regex

Usage

Basic Example

import { createRegex } from "human-regex";

// Password validation: 8+ chars with special character, digit, and letter
const passwordRegex = createRegex()
  .startAnchor()
  .hasSpecialCharacter()
  .hasDigit()
  .hasLetter()
  .anyCharacter()
  .atLeast(8)
  .endAnchor()
  .toRegExp();

console.log(passwordRegex.test("P@ssw0rd")); // true

Predefined Patterns

import { Patterns } from "human-regex";

// Email validation
console.log(Patterns.email().test("[e-mail]")); // true

// International phone number
console.log(Patterns.phoneInternational().test("[phone]")); // true

// URL validation
console.log(Patterns.url().test("https://www.example.com/path")); // true

Comprehensive API Reference

createRegex()

Creates a new regex builder instance.

Core Methods

Method	Description	Example Output
.digit()	Adds a digit pattern (\d).	\d
.word()	Adds a word character pattern (\w).	\w
.whitespace()	Adds a whitespace character pattern (\s).	\s
.nonWhitespace()	Adds a non-whitespace character pattern (\S).	\S
.anyCharacter()	Adds a pattern for any character (.).	.
.literal("text")	Adds a literal text pattern.	["text"]
.or()	Adds an OR pattern.	|
.newline()	Adds a pattern for newline characters.	(\r\n|\r|\n)
.range("digit")	Adds a range pattern for digits (0-9).	[0-9]
.notRange("letter")	Adds a range pattern for non-letters	[^a-zA-Z]
.anyOf("aeiou\\s")	Adds list of accepted characters	[aeiou\s]
.notAnyOf("aeiou\\s")	Adds list of excluded characters	[^aeiou\s]

Quantifiers

Method	Description	Example Output
.exactly(n)	Adds an exact quantifier ({n}).	{n}
.atLeast(n)	Adds a minimum quantifier ({n,}).	{n,}
.atMost(n)	Adds a maximum quantifier ({0,n}).	{0,n}
.between(min, max)	Adds a range quantifier ({min,max}).	{min,max}
.oneOrMore()	Adds a one-or-more quantifier (+).	+
.optional()	Adds an optional quantifier (?).	?
.zeroOrMore()	Adds a zero-or-more quantifier (*).	*
.lazy()	Makes the previous quantifier lazy.	?
.repeat(count)	Repeats the previous pattern exactly count times.	{count}

Anchors & Groups

Method	Description	Example Output
.startGroup()	Starts a non-capturing group ((?:).	(?:
.startCaptureGroup()	Starts a capturing group (().	(
.startNamedGroup("name")	Starts a named capturing group.	(?<name>
.endGroup()	Ends a group ()).	)
.startAnchor()	Adds a start anchor (^).	^
.endAnchor()	Adds an end anchor ($).	$
.wordBoundary()	Adds a word boundary assertion (\b).	\b
.nonWordBoundary()	Adds a non-word boundary assertion (\B).	\B

Validation Helpers

Method	Description	Example Output
.hasSpecialCharacter()	Adds a lookahead for special characters.	(?=.*[!@#$%^&*])
.hasDigit()	Adds a lookahead for digits.	(?=.*\d)
.hasLetter()	Adds a lookahead for letters.	(?=.*[a-zA-Z])

URL Components

Method	Description	Example Output
.protocol()	Adds a protocol pattern (https?://).	https?://
.www()	Adds a www pattern ((www\.)?).	(www\.)?
.path()	Adds a path pattern ((/\w+)*).	(/\w+)*
.tld()	Adds a top-level domain pattern.	["(com|org|net)"]

Flags

Method	Description	Example Output
.global()	Adds the global flag (g).	g
.nonSensitive()	Adds the case-insensitive flag (i).	i
.multiline()	Adds the multiline flag (m).	m
.dotAll()	Adds the dot-all flag (s).	s
.sticky()	Adds the sticky flag (y).	y

Unicode Properties

Method	Description	Example Output
.unicodeChar()	Matches Unicode characters.	\p{L}
.unicodeDigit()	Matches Unicode digits.	\p{N}
.unicodePunctuation()	Matches Unicode punctuation.	\p{P}
.unicodeSymbol()	Matches Unicode symbols.	\p{S}

Predefined Patterns

• Patterns.email: Predefined email pattern.
• Patterns.url: Predefined URL pattern.
• Patterns.phoneInternational: Predefined international phone number pattern.

Predefined Ranges

For use with range() and notRange():

digit: "0-9", lowercaseLetter: "a-z", uppercaseLetter: "A-Z", letter: "a-zA-Z", alphanumeric: "a-zA-Z0-9", anyCharacter: ".",

RangeKey	Range value
digit	0-9
lowercaseLetter	a-z
uppercaseLetter	A-Z
letter	a-zA-Z
alphanumeric	a-zA-Z0-9
anyCharacter	.

Examples

Combining with Existing Regex

const basePattern = /^[A-Z]/;
const combined = createRegex().regex(basePattern).digit().exactly(3).toRegExp();

Lookaheads/Lookbehinds

createRegex().literal("(?<=@)").word().oneOrMore().toRegExp();

Named Capture Groups

createRegex()
  .literal("(?<year>\\d{4})")
  .literal("-")
  .literal("(?<month>\\d{2})")
  .toRegExp();

Contributing

We welcome contributions! Please follow the guidelines in CONTRIBUTING.md.

License

This project is licensed under the MIT License - see the LICENSE file for details.