{"id":16517,"library":"regex-fun","title":"regex-fun: Functional Regular Expression Builder","description":"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.","status":"active","version":"3.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/TehShrike/regex-fun","tags":["javascript","regex","compose","functions","regular","expressions","typescript"],"install":[{"cmd":"npm install regex-fun","lang":"bash","label":"npm"},{"cmd":"yarn add regex-fun","lang":"bash","label":"yarn"},{"cmd":"pnpm add regex-fun","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Most `regex-fun` utilities are named exports. Using CommonJS `require()` for destructuring is generally not the idiomatic way to consume this ESM-first library.","wrong":"const { combine, optional, capture, either } = require('regex-fun')","symbol":"combine, optional, capture, either","correct":"import { combine, optional, capture, either } from 'regex-fun'"},{"note":"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.","wrong":"const r = require('regex-fun')","symbol":"* as r","correct":"import * as r from 'regex-fun'"},{"note":"When using TypeScript, import types explicitly using `import type` for clarity and to ensure type-only imports are removed during transpilation.","symbol":"RegexInput, RegexFunction","correct":"import type { RegexInput, RegexFunction } from 'regex-fun'"}],"quickstart":{"code":"import { combine, optional, capture, either } from 'regex-fun';\n\nconst anyGreeting = either('howdy', 'hi', 'hey');\n// The comma is optional, followed by a space, then a captured word.\nconst regex = combine(anyGreeting, optional(','), ' ', capture(/\\w+/));\n\nconsole.log(regex); // => /(?:howdy|hi|hey)(?:,)? (\\w+)/\n\nconst matchResult = 'hey bub'.match(regex);\nif (matchResult && matchResult[1]) {\n  console.log(matchResult[1]); // => 'bub'\n} else {\n  console.log('No match found.');\n}\n\n// Example of automatic string escaping:\nconst escapedRegex = combine('a+');\nconsole.log(escapedRegex); // => /a\\+/\n// This will match 'a+' literally, not one or more 'a's.\nconsole.log('a+'.match(escapedRegex)); // => ['a+', index: 0, input: 'a+', groups: undefined]","lang":"typescript","description":"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."},"warnings":[{"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')`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Wrap the desired part of your regex in `capture(...)` to create a capturing group, e.g., `combine('prefix', capture(/\\w+/), 'suffix')`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use `import` statements in a CommonJS (CJS) environment (e.g., an older Node.js script without `\"type\": \"module\"` in `package.json`).","error":"SyntaxError: Cannot use import statement outside a module"},{"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.","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.","error":"TypeError: 'combine' is not a function"}],"ecosystem":"npm"}