@simple-regex/core

Build regular expressions from plain, readable names instead of raw regex syntax — and (best-effort, WIP) explain existing patterns back in plain language.

Status

Early scaffold. The builder API and compiler are functional; explain() only recognizes a handful of common atoms (\d, \s, \w, [A-Z], [a-z], ., literal characters) and does not yet understand groups, alternation, anchors, or lookaround.

Install

npm install @simple-regex/core

Usage

import { simpleRegex, explain } from "@simple-regex/core";

const pattern = simpleRegex()
  .upperCase(1)
  .lowerCase({ min: 2 })
  .number(3)
  .build();

pattern.test("Abcde123"); // true

explain(/\d{3}-\d{4}/);
// "Matches a number (exactly 3 times), then the character "-", then a number (exactly 4 times)."

Available tokens

| Method | Matches | |---|---| | .number(quantifier?) | a digit 0-9 | | .upperCase(quantifier?) | an uppercase letter A-Z | | .lowerCase(quantifier?) | a lowercase letter a-z | | .letter(quantifier?) | any letter | | .whitespace(quantifier?) | a whitespace character | | .alphaNumeric(quantifier?) | a letter or digit | | .symbol(quantifier?) | a common punctuation character | | .anyChar(quantifier?) | any single character | | .literal(text) | the given text, matched exactly (auto-escaped) | | .custom(name, pattern?, quantifier?) | a user-supplied regex fragment |

Custom tokens

.custom() accepts an inline pattern, or looks one up by name if you've registered it with defineToken():

import { simpleRegex, defineToken } from "@simple-regex/core";

// register once, reuse anywhere by name
defineToken("zipCode", "\\d{5}");

simpleRegex().custom("zipCode").literal("-").custom("zipCode").toString();
// "(?:\d{5})-(?:\d{5})"

// or inline, registering "areaCode" as a side effect for later calls
simpleRegex().custom("areaCode", "\\d{3}").toString();
// "(?:\d{3})"

Calling .custom(name) with no matching registration throws, so typos surface immediately rather than compiling into a broken regex.

Quantifiers

Every token method accepts an optional quantifier as its argument:

• omitted → exactly once
• a number → exact count, e.g. .number(3)
• { min, max } → range, e.g. .letter({ min: 2, max: 4 })
• { min } → at least, e.g. .letter({ min: 2 })
• "oneOrMore", "zeroOrMore", "optional"

Development

npm install
npm test
npm run build

Roadmap

• [ ] Extend explain() to cover groups, alternation, anchors, and lookaround
• [ ] String DSL layer that compiles down to builder calls (e.g. parse("3 numbers, 1 symbol"))
• [ ] explain() output that round-trips into builder code, not just prose