ts-regex-builder
v1.8.1
Published
Maintainable regular expressions for TypeScript and JavaScript.
Downloads
66,452
Readme
TS Regex Builder
Build maintainable regular expressions for TypeScript and JavaScript.
Goal
Regular expressions are a powerful tool for matching text patterns, yet they are notorious for their hard-to-parse syntax, especially in the case of more complex patterns.
This library allows users to create regular expressions in a structured way, making them easy to write and review. It provides a domain-specific langauge for defining regular expressions, which are finally turned into JavaScript-native RegExp
objects for fast execution.
// Regular JS RegExp
const hexColor = /^#?([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$/;
// TS Regex Builder DSL
const hexDigit = charClass(charRange('a', 'f'), charRange('A', 'F'), charRange('0', '9'));
const hexColor = buildRegExp([
startOfString,
optional('#'),
capture(
choiceOf(
repeat(hexDigit, 6), // #rrggbb
repeat(hexDigit, 3), // #rgb
),
),
endOfString,
]);
Installation
npm install ts-regex-builder
or
yarn add ts-regex-builder
Basic usage
import { buildRegExp, capture, oneOrMore } from 'ts-regex-builder';
// /Hello (\w+)/
const regex = buildRegExp(['Hello ', capture(oneOrMore(word))]);
Regex domain-specific language
TS Regex Builder allows you to build complex regular expressions using domain-specific language.
Terminology:
- regex construct (
RegexConstruct
) - common name for all regex constructs like character classes, quantifiers, and anchors. - regex element (
RegexElement
) - a fundamental building block of a regular expression, defined as either a regex construct, a string, orRegExp
literal (/.../
). - regex sequence (
RegexSequence
) - a sequence of regex elements forming a regular expression. For developer convenience, it also accepts a single element instead of an array.
Most of the regex constructs accept a regex sequence as their argument.
Examples of sequences:
- single element (construct):
capture('Hello')
- single element (string):
'Hello'
- single element (
RegExp
literal):/Hello/
- array of elements:
['USD', oneOrMore(digit), /Hello/]
Regex constructs can be composed into a tree structure:
const currencyCode = repeat(charRange('A', 'Z'), 3);
const currencyAmount = buildRegExp([
choiceOf('$', '€', currencyCode), // currency
capture(
oneOrMore(digit), // integer part
optional(['.', repeat(digit, 2)]), // fractional part
),
]);
See Types API doc for more info.
Regex Builders
| Builder | Regex Syntax | Description |
| ---------------------------------------- | ------------ | ----------------------------------- |
| buildRegExp(...)
| /.../
| Create RegExp
instance |
| buildRegExp(..., { ignoreCase: true })
| /.../i
| Create RegExp
instance with flags |
See Builder API doc for more info.
Regex Constructs
| Construct | Regex Syntax | Notes |
| ------------------- | ------------ | ------------------------------- |
| choiceOf(x, y, z)
| x\|y\|z
| Match one of provided sequences |
| capture(...)
| (...)
| Create a capture group |
See Constructs API doc for more info.
[!NOTE] TS Regex Builder does not have a construct for non-capturing groups. Such groups are implicitly added when required.
Quantifiers
| Quantifier | Regex Syntax | Description |
| -------------------------------- | ------------ | ------------------------------------------------- |
| zeroOrMore(x)
| x*
| Zero or more occurence of a pattern |
| oneOrMore(x)
| x+
| One or more occurence of a pattern |
| optional(x)
| x?
| Zero or one occurence of a pattern |
| repeat(x, n)
| x{n}
| Pattern repeats exact number of times |
| repeat(x, { min: n, })
| x{n,}
| Pattern repeats at least given number of times |
| repeat(x, { min: n, max: n2 })
| x{n1,n2}
| Pattern repeats between n1 and n2 number of times |
See Quantifiers API doc for more info.
Character classes
| Character class | Regex Syntax | Description |
| ---------------------- | ------------ | ------------------------------------------------- |
| any
| .
| Any character |
| word
| \w
| Word character: letter, digit, underscore |
| digit
| \d
| Digit character: 0 to 9 |
| whitespace
| \s
| Whitespace character: space, tab, line break, ... |
| anyOf('abc')
| [abc]
| Any of provided characters |
| charRange('a', 'z')
| [a-z]
| Character in a range |
| charClass(...)
| [...]
| Union of multiple character classes |
| negated(...)
| [^...]
| Negation of a given character class |
| char(...)
| \uXXXX
| Character specified given Unicode code point |
| unicodeProperty(...)
| \p{...}
| Characters with given Unicode property |
See Character Classes API doc and Unicode API doc for more info.
Assertions
| Assertion | Regex Syntax | Description |
| ------------------------- | ------------ | ------------------------------------------------------------------------ |
| startOfString
| ^
| Match the start of the string (or the start of a line in multiline mode) |
| endOfString
| $
| Match the end of the string (or the end of a line in multiline mode) |
| wordBoundary
| \b
| Match the start or end of a word without consuming characters |
| lookahead(...)
| (?=...)
| Match subsequent text without consuming it |
| negativeLookhead(...)
| (?!...)
| Reject subsequent text without consuming it |
| lookbehind(...)
| (?<=...)
| Match preceding text without consuming it |
| negativeLookbehind(...)
| (?<!...)
| Reject preceding text without consuming it |
See Assertions API doc for more info.
Examples
See Examples.
Performance
Regular expressions created with this library are executed at runtime, so you should avoid creating them in a context where they would need to be executed multiple times, e.g., inside loops or functions. We recommend that you create a top-level object for each required regex.
Contributing
See the contributing guide to learn how to contribute to the repository and the development workflow. See the project guidelines to understand our core principles.
License
MIT
Inspiration
TS Regex Builder is inspired by Swift Regex Builder API.
Reference
- ECMAScript Regular Expression BNF Grammar
- Unicode Regular Expressions
- Swift Evolution 351: Regex Builder DSL
- Swift Regex Builder API docs
Made with create-react-native-library