regex-fun: Functional Regular Expression Builder

3.1.0 · active · verified Wed Apr 22

regex-fun is a utility library for JavaScript and TypeScript that facilitates the programmatic construction of regular expressions using a functional, composable API. It provides a comprehensive set of functions like `combine`, `either`, `capture`, and various quantifiers (e.g., `optional`, `anyNumber`, `oneOrMore`, `exactly`, `atLeast`, `between`, and their non-greedy counterparts) to build complex regex patterns from smaller, readable components. A key differentiator is its automatic escaping of string inputs, which prevents common regex syntax errors when embedding literal strings, treating them as fixed text rather than regex patterns. The library ships with TypeScript types, ensuring strong type-checking and autocompletion for users in modern development environments. The current stable version is 3.1.0, and new functions are added on an ad-hoc basis driven by maintainer needs, rather than a strict release cadence.

Common errors

```
SyntaxError: Cannot use import statement outside a module
```
cause Attempting to use `import` statements in a CommonJS (CJS) environment (e.g., an older Node.js script without `"type": "module"` in `package.json`).

fix Ensure your project is configured for ES Modules by adding `"type": "module"` to your `package.json` file, or by renaming your file to end with `.mjs`. If you must use CommonJS, consider dynamic `import()` or transpilation.
```
TypeError: 'combine' is not a function
```
cause This usually indicates an incorrect module import, meaning the `combine` function (or any other `regex-fun` utility) was not properly imported or resolved from the package.

fix Verify your import statement: `import { combine } from 'regex-fun'`. Check for typos in function names or the package name. Ensure your module resolver is correctly configured if you are using a bundler.

Warnings

gotcha All string inputs to `regex-fun` functions (e.g., `combine('a+')`) are automatically escaped. This is a design choice to prevent common regex syntax errors and ensures that string literals are matched verbatim. If you intend to pass a raw regex pattern, it *must* be provided as a `RegExp` object (e.g., `combine(/a+/))`, not a string.
Fix: To include a raw regex pattern, always wrap it in a `RegExp` literal or constructor: `combine(/your_pattern_here/)` instead of `combine('your_pattern_here')`.
gotcha By default, most `regex-fun` functions (like `combine`, `either`, `optional`) create non-capturing groups `(?:...)` around their generated patterns. If you explicitly need a capturing group, you must use the `capture()` function.
Fix: Wrap the desired part of your regex in `capture(...)` to create a capturing group, e.g., `combine('prefix', capture(/\w+/), 'suffix')`.

Install

npm install regex-fun npm
yarn add regex-fun yarn
pnpm add regex-fun pnpm

Imports

combine, optional, capture, either
wrong:
```
const { combine, optional, capture, either } = require('regex-fun')
```
correct:
```
import { combine, optional, capture, either } from 'regex-fun'
```
Most `regex-fun` utilities are named exports. Using CommonJS `require()` for destructuring is generally not the idiomatic way to consume this ESM-first library.
* as r
wrong:
```
const r = require('regex-fun')
```
correct:
```
import * as r from 'regex-fun'
```
A convenient way to import all functions under a namespace, e.g., `r.combine()`. While `require('regex-fun')` might work in some CJS setups, `import * as r` is the preferred ESM pattern.
RegexInput, RegexFunction
```
import type { RegexInput, RegexFunction } from 'regex-fun'
```
When using TypeScript, import types explicitly using `import type` for clarity and to ensure type-only imports are removed during transpilation.

Quickstart

This quickstart demonstrates building a complex regular expression using `either`, `optional`, `combine`, and `capture` to parse a greeting followed by a word. It also shows the automatic string escaping feature.

import { combine, optional, capture, either } from 'regex-fun';

const anyGreeting = either('howdy', 'hi', 'hey');
// The comma is optional, followed by a space, then a captured word.
const regex = combine(anyGreeting, optional(','), ' ', capture(/\w+/));

console.log(regex); // => /(?:howdy|hi|hey)(?:,)? (\w+)/

const matchResult = 'hey bub'.match(regex);
if (matchResult && matchResult[1]) {
  console.log(matchResult[1]); // => 'bub'
} else {
  console.log('No match found.');
}

// Example of automatic string escaping:
const escapedRegex = combine('a+');
console.log(escapedRegex); // => /a\+/
// This will match 'a+' literally, not one or more 'a's.
console.log('a+'.match(escapedRegex)); // => ['a+', index: 0, input: 'a+', groups: undefined]

view raw JSON →