PCRE to JavaScript RegExp Converter

Common errors

• TypeError: PCRE is not a function

  cause Attempting to use `require('pcre-to-regexp')` and then directly calling `PCRE()`, but the CommonJS import might resolve differently in some environments, or in ESM contexts, a default import was not used.
  fix For CommonJS, try `const PCRE = require('pcre-to-regexp').default;` or ensure your module resolver correctly handles default exports from ESM. For ESM, use `import PCRE from 'pcre-to-regexp';`.

• TS2305: Module '"pcre-to-regexp"' has no exported member 'PCRE'.

  cause Attempting to import `PCRE` as a named export when it's primarily a default export, or trying to import a type that is within a namespace without the correct syntax.
  fix For the default function, use `import PCRE from 'pcre-to-regexp';`. For types, ensure you are using `import type { PCRE } from 'pcre-to-regexp';` as of v1.1.0, specifically for type-related imports.

Warnings

• breaking Version 1.0.0 introduced a significant refactor to TypeScript, which might cause subtle type-related issues or require minor adjustments in existing TypeScript projects.
  Fix: Ensure your TypeScript configuration is up-to-date and re-evaluate any type assertions or inferences if upgrading from pre-1.0.0 versions.
• gotcha The library is not fully feature-complete for all PCRE constructs. Complex or very specific PCRE features might not be correctly translated, leading to unexpected behavior or incorrect RegExp patterns.
  Fix: Thoroughly test the generated JavaScript RegExp with a comprehensive suite of test cases, especially for complex PCRE patterns, to ensure accurate translation. Consult the project's issues for known limitations.
• gotcha Named capture groups are not automatically added as properties to the `RegExpMatchArray` object returned by `RegExp.prototype.exec()`. A manual iteration over the `keys` array is required.
  Fix: After obtaining the `match` array and `keys` array, iterate through `keys` and manually assign `match[i + 1]` to `match[keys[i]]` for each named capture, as shown in the quickstart example.
• gotcha Incorrect handling of PCRE delimiters (e.g., unmatched delimiters or delimiters appearing within the pattern without proper escaping) can lead to parsing errors or malformed JavaScript RegExp objects.
  Fix: Ensure PCRE strings adhere to standard PCRE syntax, with consistent delimiters (e.g., `%...%`, `/.../`) and proper escaping of delimiters if they appear within the pattern itself.

Install

• npm install pcre-to-regexp npm
• yarn add pcre-to-regexp yarn
• pnpm add pcre-to-regexp pnpm

Imports

• PCRE
  wrong:

  const PCRE = require('pcre-to-regexp');

  correct:

  import PCRE from 'pcre-to-regexp';

  The library primarily exports a default function. Since v1.0.0, types are shipped, supporting TypeScript's default import syntax. The CJS require is also common for older Node.js projects.
• PCRE (TypeScript type)
  wrong:

  import { PCRE } from 'pcre-to-regexp';

  correct:

  import type { PCRE } from 'pcre-to-regexp';

  While the main export is a default function, the type definitions are exported as named exports within a namespace since v1.1.0.

Quickstart

This example demonstrates how to convert a PCRE string to a JavaScript RegExp, extract named capture group keys, and then use the resulting RegExp to match a string, showcasing access to named captures.

import PCRE from 'pcre-to-regexp';

const url = '%^https?://twitter\\.com(/\\#\\!)?/(?P<username>[a-zA-Z0-9_]{1,20})\\/status(es)?/(?P<id>\\d+)/?$%ig';

// parse the PCRE regexp into a JS RegExp
const keys = [];
const re = PCRE(url, keys);

console.log('Extracted keys:', keys);
// Expected: [ , 'username', , 'id' ]

console.log('Resulting RegExp:', re);
// Expected: /^https?:\/\/twitter\\.com(\/\\#\\!)?\/([a-zA-Z0-9_]{1,20})\\/status(es)?\/(\\d+)\/?)?$/gi

const match = re.exec('https://twitter.com/tootallnate/status/481604870626349056');
console.log('Match result:', match);

// Example of copying named captures to the match object
if (match) {
  for (let i = 0; i < keys.length; i++) {
    if (typeof keys[i] === 'string') {
      match[keys[i]] = match[i + 1];
    }
  }
  console.log('Username from named capture:', match.username);
  console.log('ID from named capture:', match.id);
} else {
  console.log('No match found.');
}