ts-regex-builder

1.8.2 verified Sat May 09 auth: no javascript

A TypeScript-first library for building maintainable regular expressions using a structured, composable DSL. Version 1.8.2 (September 2024) supports Unicode mode, named capture groups, lookahead/lookbehind assertions, and tree-shaking optimizations. Unlike raw regex strings or other builders (e.g., verbal-expressions), ts-regex-builder provides full TypeScript type safety, automatic escaping, and seamless interop with native RegExp. Released under the Callstack organization with monthly updates.

Common errors

error Cannot find module 'ts-regex-builder' or its corresponding type declarations. ↓

cause Project uses CommonJS and Node < 18 or missing ESM support.

fix

Upgrade to Node >= 18 and use ESM (type: 'module' in package.json or .mjs extension).

error TypeError: ts_regex_builder_1.buildRegExp is not a function ↓

cause Default import used instead of named import.

fix

Change to import { buildRegExp } from 'ts-regex-builder'

error SyntaxError: Unexpected token '?' (at ...) ↓

cause Using optional chaining on regex construct results incorrectly.

fix

Ensure regex constructs are used within buildRegExp arrays.

Warnings

breaking ESM-only since v1.5.0; CommonJS require() will throw. ↓

fix Use import syntax or switch to dynamic import().

deprecated The 'any' construct is deprecated since v1.4.0; use '.' (string) instead. ↓

fix Replace any() with '.' in regex sequences.

gotcha RegExp literals passed directly are not escaped; they must be valid regex patterns. ↓

fix Ensure strings used in sequences are escaped if needed, or use construct methods.

gotcha Node version requirement >= 18.0.0; may fail on older runtimes. ↓

fix Use Node 18+ or configure bundler to polyfill.

deprecated The 'wordBoundary' construct was renamed to 'wordBoundary' (already correct); no action needed. ↓

fix No fix needed; name is stable.

Install

npm install ts-regex-builder

yarn add ts-regex-builder

pnpm add ts-regex-builder

Imports

buildRegExp

wrong

import buildRegExp from 'ts-regex-builder'

correct

import { buildRegExp } from 'ts-regex-builder'

Named export; default import is not available. ESM-only since v1.5.0.

capture

wrong

const { capture } = require('ts-regex-builder')

correct

import { capture } from 'ts-regex-builder'

ESM-only; CommonJS require() will fail in Node >= 18.

choiceOf

wrong

import { choiceOf } from 'ts-regex-builder'

correct

import { choiceOf } from 'ts-regex-builder'

Correct usage shown. No common wrong pattern beyond CJS require.

Quickstart

Shows regex building with constructs like capture, choiceOf, repeat, and charRange, plus usage of test() and exec().

import { buildRegExp, capture, oneOrMore, digit, startOfString, endOfString, optional, choiceOf, charRange, repeat, anyOf, word } from 'ts-regex-builder';

// Match a hex color (#rgb or #rrggbb)
const hexDigit = /[a-fA-F0-9]/;
const hexColor = buildRegExp([
  startOfString,
  optional('#'),
  capture(
    choiceOf(
      repeat(hexDigit, 6), // #rrggbb
      repeat(hexDigit, 3), // #rgb
    ),
  ),
  endOfString,
]);

console.log(hexColor.test('#abc')); // true
console.log(hexColor.test('#123456')); // true
console.log(hexColor.test('xyz')); // false

// Match currency amounts: $100, €50, USD 25.50
const currencyCode = repeat(charRange('A', 'Z'), 3);
const currencyAmount = buildRegExp([
  choiceOf('$', '€', currencyCode),
  capture(
    oneOrMore(digit),
    optional(['.', repeat(digit, 2)]),
  ),
]);

console.log(currencyAmount.test('$100')); // true
console.log(currencyAmount.test('USD 25.50')); // true
console.log(currencyAmount.exec('€50')); // ['€50', '50']