...

Human Regex

Human-friendly regular expression builder with English-like syntax.
GitHub
271
Created 19 days ago, last commit 3 days ago
3 contributors
89 commits
12 added yesterday
npmPackage on NPM
human-regex
2.1.5
Monthly downloads on NPM
0
0
0
0
0
0
0
0
0
0
0
2
3
4
5
6
7
8
9
10
11
12
1
2024
2025
README

npm version Build Status Coverage Status

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

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("test@example.com")); // true

// International phone number
console.log(Patterns.phoneInternational().test("+123-4567890")); // 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. |
.range("digit") Adds a range pattern for digits (0-9). [0-9]
.notRange("aeiou") Excludes characters from the pattern. [^aeiou]

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.

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.