Tiny Route Pattern to RegExp Utility

Common errors

• TypeError: regexparam is not a function

  cause Attempting to call `require('regexparam')()` directly in CommonJS after v2.0.0, where the default export was removed.
  fix Change your CommonJS import and usage from `const regexparam = require('regexparam'); regexparam('/path')` to `const { parse } = require('regexparam'); parse('/path')`.

• SyntaxError: The requested module 'regexparam' does not provide an export named 'parse'

  cause Using `import { parse } from 'regexparam'` with a version prior to v2.0.0, where `parse` was not a named export but the default export.
  fix Either update `regexparam` to v2.0.0 or later, or change your import to `import regexparam from 'regexparam'` and use `regexparam('/path')`.

• Route with optional wildcard /users/*? matches incorrectly.

  cause Behavioral change in optional wildcard matching between v2.x and v3.x of `regexparam`.
  fix Upgrade to `regexparam` v3.0.0 and thoroughly test routes using optional wildcards (`*?`) to confirm expected matching behavior.

Warnings

• breaking The behavior of optional wildcard patterns (e.g., `/books/*?`) has been corrected in v3.0.0. Previously, the optional part was ignored, making them behave like regular wildcards. This fix changes the generated `RegExp` and thus the matching behavior for these patterns.
  Fix: Review all routes utilizing optional wildcard patterns and verify their matching behavior against the new specification. Adjust application logic if the previous, incorrect behavior was relied upon.
• breaking The default export of the library was converted to a named `parse` export in v2.0.0. This means the import method for the primary parsing function has changed.
  Fix: Update import statements from `import regexparam from 'regexparam'` to `import { parse } from 'regexparam'` for ESM. For CommonJS, change `const regexparam = require('regexparam'); regexparam(...)` to `const { parse } = require('regexparam'); parse(...)`.
• breaking Version 2.0.0 increased the minimum required Node.js runtime from 6.x to 8.x.
  Fix: Ensure your Node.js environment is version 8 or higher before upgrading to regexparam v2.0.0 or later.
• gotcha When matching or testing against a generated `RegExp` pattern, the input path string MUST begin with a leading slash (`/`). Paths without a leading slash will not match correctly.
  Fix: Always prepend a leading slash to any path string passed to `pattern.test()` or `pattern.exec()` methods derived from `regexparam`.
• gotcha The `inject` function will leave non-optional parameter placeholders in the output string if the corresponding value is not provided in the parameters object.
  Fix: Ensure all non-optional parameters defined in your route pattern are provided to the `inject` function to ensure complete path generation.

Install

• npm install regexparam npm
• yarn add regexparam yarn
• pnpm add regexparam pnpm

Imports

• parse
  wrong:

  import regexparam from 'regexparam'

  correct:

  import { parse } from 'regexparam'

  Since v2.0.0, `parse` is a named export. Previously, it was the default export.
• inject
  wrong:

  const inject = require('regexparam').inject

  correct:

  import { inject } from 'regexparam'

  `inject` is a named export, primarily used with ESM. For CommonJS, you might need `const { inject } = require('regexparam')` in some environments, but ESM is preferred.
• Result type

  import type { Result } from 'regexparam'

  TypeScript type for the return value of `parse` (object with `keys` and `pattern`).

Quickstart

Demonstrates how to parse a route pattern into a RegExp and keys, test paths against it, extract parameters, and inject parameters into a route string using `parse` and `inject`.

import { parse, inject } from 'regexparam';

// A helper function to extract parameters from a matched path
function exec(path: string, result: ReturnType<typeof parse>): Record<string, string | null> {
  let i = 0;
  const out: Record<string, string | null> = {};
  const matches = result.pattern.exec(path);

  if (!matches) {
    return {}; // No match
  }

  while (i < result.keys.length) {
    // Matches array index starts from 1 for captured groups
    out[result.keys[i]] = matches[++i] || null;
  }
  return out;
}

// Example 1: Parsing a route with optional parameters
const route1 = parse('/books/:genre/:title?');
console.log('Route 1 pattern:', route1.pattern.source);
console.log('Route 1 keys:', route1.keys);

const path1a = '/books/horror';
console.log(`Matching "${path1a}":`, route1.pattern.test(path1a));
console.log(`Extracted params for "${path1a}":`, exec(path1a, route1));

const path1b = '/books/science-fiction/dune';
console.log(`Matching "${path1b}":`, route1.pattern.test(path1b));
console.log(`Extracted params for "${path1b}":`, exec(path1b, route1));

// Example 2: Injecting parameters into a route
const injectedPath1 = inject('/users/:id', { id: 'alice' });
console.log('Injected path (user alice):', injectedPath1);

const injectedPath2 = inject('/posts/:slug/*', { slug: 'my-post', '*': 'comments/123' });
console.log('Injected path (post with wildcard):', injectedPath2);

// Example 3: Handling missing non-optional parameters during injection
const incompleteInjection = inject('/products/:category/:item', { category: 'electronics' });
console.log('Incomplete injection:', incompleteInjection); // Missing 'item' parameter