{"id":21863969,"url":"https://github.com/callstack/ts-regex-builder","last_synced_at":"2025-06-28T23:42:13.937Z","repository":{"id":210869736,"uuid":"727637018","full_name":"callstack/ts-regex-builder","owner":"callstack","description":"Maintainable regular expressions for TypeScript and JavaScript.","archived":false,"fork":false,"pushed_at":"2024-04-30T21:25:22.000Z","size":3291,"stargazers_count":97,"open_issues_count":5,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-05-01T11:44:13.064Z","etag":null,"topics":["javascript","regex","regexes","regular-expressions","typescript"],"latest_commit_sha":null,"homepage":"https://callstack.github.io/ts-regex-builder/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/callstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-05T09:13:28.000Z","updated_at":"2024-05-04T11:38:25.767Z","dependencies_parsed_at":"2024-01-18T01:35:20.212Z","dependency_job_id":"5783bbed-d12f-41a2-81d5-301cab565bd0","html_url":"https://github.com/callstack/ts-regex-builder","commit_stats":null,"previous_names":["callstack/ts-regex","callstack/ts-regex-builder"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/callstack%2Fts-regex-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/callstack%2Fts-regex-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/callstack%2Fts-regex-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/callstack%2Fts-regex-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/callstack","download_url":"https://codeload.github.com/callstack/ts-regex-builder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226857087,"owners_count":17693016,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","regex","regexes","regular-expressions","typescript"],"created_at":"2024-11-28T04:02:11.844Z","updated_at":"2025-06-28T23:42:13.909Z","avatar_url":"https://github.com/callstack.png","language":"TypeScript","readme":"[![npm version](https://badge.fury.io/js/ts-regex-builder.svg)](https://badge.fury.io/js/ts-regex-builder)\n![Build](https://github.com/callstack/ts-regex-builder/actions/workflows/ci.yml/badge.svg)\n![npm bundle size](https://deno.bundlejs.com/badge?q=ts-regex-builder)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)\n[![Star on GitHub](https://img.shields.io/github/stars/callstack/ts-regex-builder.svg?style=social)](https://github.com/callstack/ts-regex-builder/stargazers)\n\n# TS Regex Builder\n\nBuild maintainable regular expressions for TypeScript and JavaScript.\n\n[API docs](https://callstack.github.io/ts-regex-builder/api) | [Examples](https://callstack.github.io/ts-regex-builder/examples)\n\n## Goal\n\nRegular 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.\n\nThis 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.\n\n```ts\n// Regular JS RegExp\nconst hexColor = /^#?([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$/;\n\n// TS Regex Builder DSL\nconst hexDigit = /[a-fA-F0-9]/; // or: charClass(charRange('a', 'f'), charRange('A', 'F'), charRange('0', '9'));\n\nconst hexColor = buildRegExp([\n  startOfString,\n  optional('#'),\n  capture(\n    choiceOf(\n      repeat(hexDigit, 6), // #rrggbb\n      repeat(hexDigit, 3), // #rgb\n    ),\n  ),\n  endOfString,\n]);\n```\n\n## Installation\n\n```sh\nnpm install ts-regex-builder\n```\n\nor\n\n```sh\nyarn add ts-regex-builder\n```\n\nor\n\n```sh\npnpm add ts-regex-builder\n```\n\n## Basic usage\n\n```js\nimport { buildRegExp, capture, oneOrMore } from 'ts-regex-builder';\n\n// /Hello (\\w+)/\nconst regex = buildRegExp(['Hello ', capture(oneOrMore(word))]);\n```\n\n## Regex domain-specific language\n\nTS Regex Builder allows you to build complex regular expressions using domain-specific language.\n\nTerminology:\n\n- regex construct (`RegexConstruct`) - common name for all regex constructs like character classes, quantifiers, and anchors.\n- regex element (`RegexElement`) - a fundamental building block of a regular expression, defined as either a regex construct, a string, or `RegExp` literal (`/.../`).\n- 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.\n\nMost of the regex constructs accept a regex sequence as their argument.\n\nExamples of sequences:\n\n- single element (construct): `capture('Hello')`\n- single element (string): `'Hello'`\n- single element (`RegExp` literal): `/Hello/`\n- array of elements: `['USD', oneOrMore(digit), /Hello/]`\n\nRegex constructs can be composed into a tree structure:\n\n```ts\nconst currencyCode = repeat(charRange('A', 'Z'), 3);\nconst currencyAmount = buildRegExp([\n  choiceOf('$', '€', currencyCode), // currency\n  capture(\n    oneOrMore(digit), // integer part\n    optional(['.', repeat(digit, 2)]), // fractional part\n  ),\n]);\n```\n\nSee [Types API doc](https://callstack.github.io/ts-regex-builder/api/types) for more info.\n\n### Regex Builders\n\n| Builder                                  | Regex Syntax | Description                         |\n| ---------------------------------------- | ------------ | ----------------------------------- |\n| `buildRegExp(...)`                       | `/.../`      | Create `RegExp` instance            |\n| `buildRegExp(..., { ignoreCase: true })` | `/.../i`     | Create `RegExp` instance with flags |\n\nSee [Builder API doc](https://callstack.github.io/ts-regex-builder/api/builder) for more info.\n\n### Regex Constructs\n\n| Construct           | Regex Syntax | Notes                           |\n| ------------------- | ------------ | ------------------------------- |\n| `choiceOf(x, y, z)` | `x\\|y\\|z`    | Match one of provided sequences |\n| `capture(...)`      | `(...)`      | Create a capture group          |\n\nSee [Constructs API doc](https://callstack.github.io/ts-regex-builder/api/constructs) for more info.\n\n\u003e [!NOTE]\n\u003e TS Regex Builder does not have a construct for non-capturing groups. Such groups are implicitly added when required.\n\n### Quantifiers\n\n| Quantifier                       | Regex Syntax | Description                                       |\n| -------------------------------- | ------------ | ------------------------------------------------- |\n| `zeroOrMore(x)`                  | `x*`         | Zero or more occurrence of a pattern              |\n| `oneOrMore(x)`                   | `x+`         | One or more occurrence of a pattern               |\n| `optional(x)`                    | `x?`         | Zero or one occurrence of a pattern               |\n| `repeat(x, n)`                   | `x{n}`       | Pattern repeats exact number of times             |\n| `repeat(x, { min: n, })`         | `x{n,}`      | Pattern repeats at least given number of times    |\n| `repeat(x, { min: n, max: n2 })` | `x{n1,n2}`   | Pattern repeats between n1 and n2 number of times |\n\nSee [Quantifiers API doc](https://callstack.github.io/ts-regex-builder/api/quantifiers) for more info.\n\n### Assertions\n\n| Assertion                 | Regex Syntax | Description                                                              |\n| ------------------------- | ------------ | ------------------------------------------------------------------------ |\n| `startOfString`           | `^`          | Match the start of the string (or the start of a line in multiline mode) |\n| `endOfString`             | `$`          | Match the end of the string (or the end of a line in multiline mode)     |\n| `wordBoundary`            | `\\b`         | Match the start or end of a word without consuming characters            |\n| `lookahead(...)`          | `(?=...)`    | Match subsequent text without consuming it                               |\n| `negativeLookahead(...)`  | `(?!...)`    | Reject subsequent text without consuming it                              |\n| `lookbehind(...)`         | `(?\u003c=...)`   | Match preceding text without consuming it                                |\n| `negativeLookbehind(...)` | `(?\u003c!...)`   | Reject preceding text without consuming it                               |\n\nSee [Assertions API doc](https://callstack.github.io/ts-regex-builder/api/assertions) for more info.\n\n### Character classes\n\n\u003e [!TIP]\n\u003e You may also use inline regexes for specifying character classes, as they offer a concise yet readable syntax. For example, `/[a-z0-9_]/`.\n\n| Character class       | Regex Syntax | Description                                       |\n| --------------------- | ------------ | ------------------------------------------------- |\n| `any`                 | `.`          | Any character                                     |\n| `word`                | `\\w`         | Word character: letter, digit, underscore         |\n| `digit`               | `\\d`         | Digit character: 0 to 9                           |\n| `whitespace`          | `\\s`         | Whitespace character: space, tab, line break, ... |\n| `anyOf('abc')`        | `[abc]`      | Any of provided characters                        |\n| `charRange('a', 'z')` | `[a-z]`      | Character in a range                              |\n| `charClass(...)`      | `[...]`      | Union of multiple character classes               |\n| `negated(...)`        | `[^...]`     | Negation of a given character class               |\n\nSee [Character Classes API doc](https://callstack.github.io/ts-regex-builder/api/character-classes) and [Unicode API doc](https://callstack.github.io/ts-regex-builder/api/unicode) for more info.\n\n## Examples\n\nSee [Examples](https://callstack.github.io/ts-regex-builder/examples).\n\n## Performance\n\nRegular 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.\n\n## Contributing\n\nSee the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.\nSee the [project guidelines](GUIDELINES.md) to understand our core principles.\n\n## License\n\nMIT\n\n## Inspiration\n\nTS Regex Builder is inspired by [Swift Regex Builder API](https://developer.apple.com/documentation/regexbuilder).\n\n## Reference\n\n- [ECMAScript Regular Expression BNF Grammar](https://tc39.es/ecma262/#sec-regular-expressions)\n- [Unicode Regular Expressions](https://www.unicode.org/reports/tr18/)\n- [Swift Evolution 351: Regex Builder DSL](https://github.com/apple/swift-evolution/blob/main/proposals/0351-regex-builder.md)\n- [Swift Regex Builder API docs](https://developer.apple.com/documentation/regexbuilder)\n\n---\n\nMade with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcallstack%2Fts-regex-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcallstack%2Fts-regex-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcallstack%2Fts-regex-builder/lists"}