shelving/util/regexpmodule

Typed wrappers and combinators for working with regular expressions. They let you test, escape, compose, and extract matches with cleaner types than the raw RegExp API.

Things to know:

Matchable is string | RegExp. When a string is used as a Matchable, matching uses === equality rather than RegExp.test().
createRegExpAny([]) returns NEVER_REGEXP (matches nothing); createRegExpAll([]) returns ALWAYS_REGEXP (matches everything) — consistent with "any of nothing" vs "all of nothing" semantics.
NamedRegExp<T> and TypedRegExp<T> are typed interfaces that carry capture group shapes through to exec() return values, avoiding manual casting.
getMatch() returns undefined instead of null on no-match, fitting the rest of the util get* convention.

Usage

Testing strings

import { isMatch, notMatch, allMatch, anyMatch, noneMatch } from "shelving/util";

isMatch("hello", /^hell/);    // true
isMatch("hello", "hello");    // true  (string Matchable = exact equality)
notMatch("world", /^hell/);   // true

allMatch("hello world", /hello/, /world/);  // true
anyMatch("hello", /foo/, /hell/);           // true
noneMatch("hello", /foo/, /bar/);           // true

Building and escaping regexps

import { getRegExp, getRegExpSource, escapeRegExp, createRegExpAny, createRegExpAll } from "shelving/util";

getRegExp("\\d+", "g");         // /\d+/g
getRegExpSource(/\d+/);         // "\\d+"
escapeRegExp("1 + 1 = 2");      // "1 \\+ 1 \\= 2"

createRegExpAny([/foo/, /bar/]); // /(?:foo)|(?:bar)/
createRegExpAll([/foo/, /bar/]); // /^(?=.*?(?:foo))(?=.*?(?:bar))/

Extracting matches

import { getMatch, requireMatch, getMatchGroups, requireMatchGroups } from "shelving/util";

const DATE_RE = /(?<year>\d{4})-(?<month>\d{2})/;

getMatch("2024-03", DATE_RE);         // RegExpExecArray | undefined
getMatchGroups("2024-03", DATE_RE);   // { year: "2024", month: "03" } | undefined

requireMatch("no-date", DATE_RE);         // throws ValueError
requireMatchGroups("no-date", DATE_RE);   // throws ValueError

Type guards

import { isRegExp, assertRegExp } from "shelving/util";

isRegExp(/foo/);      // true
isRegExp("foo");      // false
assertRegExp("foo");  // throws RequiredError

Functions

isRegExp()function

Is an unknown value a RegExp instance?

isRegExp(value: unknown): value is RegExp

assertRegExp()function

Assert that an unknown value is a RegExp instance.

assertRegExp(value: unknown): asserts value is RegExp

getRegExp()function

Convert a possible regular expression into a RegExp instance.

getRegExp(pattern: NamedRegExp<T>, flags?: string): T extends NamedRegExpData ? NamedRegExp<T> : RegExp

getRegExp(pattern: PossibleRegExp, flags?: string): T extends NamedRegExpData ? NamedRegExp<T> : RegExp

getRegExpSource()function

Convert a regular expression to its string source.

getRegExpSource(regexp: PossibleRegExp): string

escapeRegExp()function

Escape special characters in a string regular expression.

escapeRegExp(pattern: string): string

createRegExpAny()function

Create a regular expression that matches any one of a list of other expressions.

createRegExpAny(patterns: Iterable<PossibleRegExp> & NotString, flags?: string): RegExp

createRegExpAll()function

Create a regular expression that matches all of a list of other expressions.

createRegExpAll(patterns: Iterable<PossibleRegExp> & NotString, flags?: string): RegExp

isMatch()function

Does a string match against a regular expressions or string.

isMatch(str: string, regexp: Matchable): boolean

notMatch()function

Does a string not match against a regular expressions or string.

notMatch(str: string, regexp: Matchable): boolean

allMatch()function

All of the provided regular expressions match the string.

allMatch(str: string, ...regexps: Matchables): boolean

anyMatch()function

At least one of the provided regular expressions matches the string.

anyMatch(str: string, ...regexps: Matchables): boolean

noneMatch()function

None of the provided regular expressions match the string.

noneMatch(str: string, ...regexps: Matchables): boolean

getMatch()function

Get an optional regular expression match, or undefined if no match could be made.

getMatch(str: string, regexp: NamedRegExp<T>): NamedRegExpExecArray<T> | undefined

getMatch(str: string, regexp: TypedRegExp<T>): TypedRegExpExecArray<T> | undefined

getMatch(str: string, regexp: RegExp): RegExpExecArray | undefined

requireMatch()function

Get a required regular expression match, or throw ValueError if no match could be made.

requireMatch(str: string, regexp: NamedRegExp<T>): NamedRegExpExecArray<T>

requireMatch(str: string, regexp: TypedRegExp<T>): TypedRegExpExecArray<T>

requireMatch(str: string, regexp: RegExp): RegExpExecArray

getMatchGroups()function

Get the named groups of an optional regular expression match, or undefined if no match could be made.

getMatchGroups(str: string, regexp: NamedRegExp<T>): T | undefined

getMatchGroups(str: string, regexp: RegExp): NamedRegExpData | undefined

requireMatchGroups()function

Get the named groups of a required regular expression match, or throw ValueError if no match could be made.

requireMatchGroups(str: string, regexp: NamedRegExp<T>): T

requireMatchGroups(str: string, regexp: RegExp): NamedRegExpData

Interfaces

TypedRegExpExecArrayinterface

Regular expression match array whose full match is a specific string format.

{
	0: T;
}

TypedRegExpinterface

Regular expression that matches a specific string format.

{
	exec(input: string): TypedRegExpExecArray<T> | null;
}

NamedRegExpExecArrayinterface

Regular expression match array that contains the specified named groups.

{
	groups: T;
}

NamedRegExpinterface

Regular expression that contains the specified named capture groups.

{
	exec(input: string): NamedRegExpExecArray<T> | null;
}

Types

Matchabletype

A thing that a string can be matched against.

string | RegExp

Matchablestype

A list of things that strings can be matched against.

ImmutableArray<Nullish<Matchable>>

PossibleRegExptype

Things that can be converted to a regular expression.

string | RegExp

NamedRegExpDatatype

Set of named match groups from a regular expression.

{
	[named: string]: string;
}