ts-regexp

A RegExp wrapper providing stronger type safety.

const groups1 = new RegExp('^(?<year>\\d{4})-(?<month>\\d{2})-(?<day>\\d{2})$', 'g').exec('9999-12-31')!.groups;
//      ⤴ '{ [key: string]: string; } | undefined' 🤮
const groups2 = regex('^(?<year>\\d{4})-(?<month>\\d{2})-(?<day>\\d{2})$', 'g').exec('9999-12-31')!.groups;
//      ⤴ '{ year: string, month: string, day: string }' 🥰

👉 Try it in the TypeScript Playground

🚀 Setup

1. Install ts-regexp

# Using npm
npm install ts-regexp

# Using yarn
yarn add ts-regexp

# Using pnpm
pnpm add ts-regexp

1. Import regex:

import { regex } from 'ts-regexp';

🧩 Usage

Runtime wrapper

Import and use regex just like the native RegExp constructor:

import { regex } from 'ts-regexp';

const datePattern = regex('(?<year>\\d{4})-(?<month>\\d{2})-(?<day>\\d{2})');
const emailPattern = regex('^(?<local>[a-z0-9._%+-]+)@(?<domain>[a-z0-9.-]+\.[a-z]{2,})$', 'i');

The function signature is:

regex(pattern: string, flags?: string)

Note: regex returns a plain object, not a RegExp instance.

Standard RegExp Methods

All standard RegExp methods work exactly as expected, but with equivalent or improved typing:

const pattern = regex('(?<year>\\d{4})-(?<month>\\d{2})-(?<day>\\d{2})', 'gid');

// Standard methods
pattern.exec('1970-01-01')!.groups;  // { year: string; month: string; day: string; }
pattern.test('1970-01-01');  // boolean

// Access RegExp properties
pattern.source;  // "(?<year>\\d{4})-(?<month>\\d{2})-(?<day>\\d{2})"
pattern.flags;   // "dgi"
pattern.global;  // true
pattern.sticky;  // false
//  ...

Regex-first Methods

Each RegExp-related string.prototype method is available as ${MethodName}In with equivalent or improved typing:

const pattern = regex('(?<year>\\d{4})-(?<month>\\d{2})-(?<day>\\d{2})');
const string = '1976-11-21';

// Instead of: string.match(pattern)
const match = pattern.matchIn(string); // typed match

// Instead of: string.replace(pattern, replacement)
const formatted1 = pattern.replaceIn(string, '$<day>/$<month>/$<year>');
const formatted2 = pattern.replaceIn(string, (match, year, month, day, offset, string, groups) => `${groups.day}/${groups.month}/${groups.year}`); // typed arguments

// Other inversed methods
pattern.searchIn(string);    // like string.search(pattern)
pattern.splitIn(string);     // like string.split(pattern)

Global Flag Methods

When using the global (g) flag, additional methods become available:

const pattern = regex('\\d', 'g');

// Only available with 'g' flag
pattern.matchAllIn('1973-12-08');     // like string.matchAll(pattern)
pattern.replaceAllIn('123-456', '#'); // like string.replaceAll(pattern, replacement)

Fallback

If you need access to the underlying RegExp instance:

const pattern = regex('\\d+');
const nativeRegExp = pattern.regExp; // Regular RegExp instance

Type Utilities

ts-regexp exposes utility types for parsing regex patterns at the type level:

Parse<T extends string>

Extracts both positional and named capture groups from a regex pattern.

type Result = Parse<'(?<a>0)|(?<b>1)'>;
/*
type Result = {
    captures: [string, string, undefined];
    namedCaptures: {
        a: string;
        b: undefined;
    };
} | {
    captures: [string, undefined, string];
    namedCaptures: {
        b: string;
        a: undefined;
    };
}
*/

ParseCaptures<T extends string>

Extracts only the positional capture groups as a tuple.

type Result = ParseCaptures<'(?<a>0)|(?<b>1)'>;
/*
type Result = [string, string, undefined] | [string, undefined, string]
*/

ParseNamedCaptures<T extends string>

Extracts only the named capture groups as an object type.

type Result = ParseNamedCaptures<'(?<a>0)|(?<b>1)'>;
/*
type Result = {
    a: string;
    b: undefined;
} | {
    b: string;
    a: undefined;
}
*/

✨ Features

• Strictly typed named & unnamed capture groups
• Supports contextual awareness
• Parses:
• different group types (non-capturing, lookarounds, named captures, etc.)
• nested groups
• alternation
• character classes and escaped characters
• Infers group optionality from quantifiers (?, *, {n,m})
• Validates flags
• Supports dynamic (non-literal) pattern + flag inputs

Alternatives

• arkregex - A drop-in replacement for new RegExp that, in addition to this library, offers strict literal group typings, readable error messages with powerful validation and best practices suggestions. Maintained by David Blass (creator of ArkType) and actively updated.
• magic-regexp - A compiled-away, type-safe alternative with a fluent, chainable API that makes regex patterns more readable and maintainable. Instead of cryptic regex syntax, you write exactly('foo').or('bar') which compiles to native RegExp at build time with no runtime cost. Part of the unjs ecosystem.