feat: named capture groups

Author: mdjastrzebski

docs/API.md

@@ -63,14 +63,28 @@ Example: `choiceOf("color", "colour")` matches either `color` or `colour` patter
 
 ```ts
 function capture(
-  sequence: RegexSequence
-): Capture
+  sequence: RegexSequence,
+  options?: {
+    name?: string;
+  },
+): Capture;
 ```
 
-Regex syntax: `(...)`.
+Regex syntax:
+
+- `(...)` for capturing groups
+- `(?<name>...)` for named capturing groups
 
 Captures, also known as capturing groups, extract and store parts of the matched string for later use.
 
+Capture results are available using array-like [`match()` result object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match#using_match).
+
+#### Named groups
+
+When using `name` options, the group becomes a [named capturing group](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Named_capturing_group) allowing to refer to it using name instead of index.
+
+Named capture results are available using [`groups`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match#using_named_capturing_groups) property on `match()` result.
+
 > [!NOTE]
 > TS Regex Builder does not have a construct for non-capturing groups. Such groups are implicitly added when required. E.g., `zeroOrMore(["abc"])` is encoded as `(?:abc)+`.
 

jest-setup.ts

@@ -1,4 +1,5 @@
 import './test-utils/to-equal-regex';
 import './test-utils/to-match-groups';
+import './test-utils/to-match-named-groups';
 import './test-utils/to-match-all-groups';
 import './test-utils/to-match-string';

src/constructs/__tests__/capture.test.tsx

@@ -12,3 +12,33 @@ test('`capture` matching', () => {
   expect(['a', capture('b')]).toMatchGroups('ab', ['ab', 'b']);
   expect(['a', capture('b'), capture('c')]).toMatchGroups('abc', ['abc', 'b', 'c']);
 });
+
+test('named `capture` pattern', () => {
+  // Note: using regex literal causes them lose the capture name for unknown reason.
+  expect(capture('a', { name: 'x' })).toEqualRegex(new RegExp('(?<x>a)'));
+  expect(capture('abc', { name: 'xyz' })).toEqualRegex(new RegExp('(?<xyz>abc)'));
+  expect(oneOrMore(capture('abc', { name: 'A' }))).toEqualRegex(new RegExp('(?<A>abc)+'));
+  expect([capture('aaa', { name: 'A' }), capture('bbb', { name: 'BB' })]).toEqualRegex(
+    new RegExp('(?<A>aaa)(?<BB>bbb)'),
+  );
+});
+
+test('named `capture` matching', () => {
+  expect(capture('b', { name: 'g1' })).toMatchGroups('ab', ['b', 'b']);
+  expect(capture('b', { name: 'g1' })).toMatchNamedGroups('ab', { g1: 'b' });
+
+  expect(['a', capture('b', { name: 'g2' })]).toMatchGroups('ab', ['ab', 'b']);
+  expect(['a', capture('b', { name: 'g2' })]).toMatchNamedGroups('ab', { g2: 'b' });
+
+  expect(['a', capture('b', { name: 'g3' }), capture('c', { name: 'g4' })]).toMatchGroups('abc', [
+    'abc',
+    'b',
+    'c',
+  ]);
+  expect(['a', capture('b', { name: 'g3' }), capture('c', { name: 'g4' })]).toMatchNamedGroups(
+    'abc',
+    { g3: 'b', g4: 'c' },
+  );
+
+  expect(['a', capture('b'), capture('c', { name: 'g4' })]).toMatchNamedGroups('abc', { g4: 'c' });
+});

src/constructs/capture.ts

@@ -6,17 +6,31 @@ import type { RegexConstruct, RegexElement, RegexSequence } from '../types';
 export interface Capture extends RegexConstruct {
   type: 'capture';
   children: RegexElement[];
+  options?: CaptureOptions;
 }
 
-export function capture(sequence: RegexSequence): Capture {
+export interface CaptureOptions {
+  name?: string;
+}
+
+export function capture(sequence: RegexSequence, options?: CaptureOptions): Capture {
   return {
     type: 'capture',
     children: ensureArray(sequence),
+    options,
     encode: encodeCapture,
   };
 }
 
 function encodeCapture(this: Capture): EncodeResult {
+  const name = this.options?.name;
+  if (name) {
+    return {
+      precedence: 'atom',
+      pattern: `(?<${name}>${encodeSequence(this.children).pattern})`,
+    };
+  }
+
   return {
     precedence: 'atom',
     pattern: `(${encodeSequence(this.children).pattern})`,

src/index.ts

@@ -1,7 +1,13 @@
+// Types
 export type * from './types';
+export type { CaptureOptions } from './constructs/capture';
+export type { QuantifierOptions } from './constructs/quantifiers';
+export type { RepeatOptions } from './constructs/repeat';
 
+// Builders
 export { buildPattern, buildRegExp } from './builders';
 
+// Constructs
 export { endOfString, notWordBoundary, startOfString, wordBoundary } from './constructs/anchors';
 export { capture } from './constructs/capture';
 export {

test-utils/to-match-groups.ts

@@ -4,11 +4,11 @@ import { wrapRegExp } from './utils';
 export function toMatchGroups(
   this: jest.MatcherContext,
   received: RegExp | RegexSequence,
-  expectedString: string,
+  inputText: string,
   expectedGroups: string[],
 ) {
   const receivedRegex = wrapRegExp(received);
-  const matchResult = expectedString.match(receivedRegex);
+  const matchResult = inputText.match(receivedRegex);
   const receivedGroups = matchResult ? [...matchResult] : null;
   const options = {
     isNot: this.isNot,
@@ -30,7 +30,7 @@ declare global {
   namespace jest {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     interface Matchers<R, T = {}> {
-      toMatchGroups(input: string, expected: string[]): R;
+      toMatchGroups(inputText: string, expectedGroups: string[]): R;
     }
   }
 }

test-utils/to-match-named-groups.ts

@@ -0,0 +1,36 @@
+import type { RegexSequence } from '../src/types';
+import { wrapRegExp } from './utils';
+
+export function toMatchNamedGroups(
+  this: jest.MatcherContext,
+  received: RegExp | RegexSequence,
+  inputText: string,
+  expectedGroups: Record<string, string>,
+) {
+  const receivedRegex = wrapRegExp(received);
+  const matchResult = inputText.match(receivedRegex);
+  const receivedGroups = matchResult ? matchResult.groups : null;
+  const options = {
+    isNot: this.isNot,
+  };
+
+  return {
+    pass: this.equals(receivedGroups, expectedGroups),
+    message: () =>
+      this.utils.matcherHint('toMatchGroups', undefined, undefined, options) +
+      '\n\n' +
+      `Expected: ${this.isNot ? 'not ' : ''}${this.utils.printExpected(expectedGroups)}\n` +
+      `Received: ${this.utils.printReceived(receivedGroups)}`,
+  };
+}
+
+expect.extend({ toMatchNamedGroups });
+
+declare global {
+  namespace jest {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    interface Matchers<R, T = {}> {
+      toMatchNamedGroups(inputText: string, expectedGroups: Record<string, string>): R;
+    }
+  }
+}