Parse your first pattern

Use parseRegex for regex patterns and parseSubstitution for substitution strings. Both functions parse syntax without executing a regex.

Requirements

You need package access and a license that covers your intended use. Contact regex101 for the package and its distribution instructions.

Use the supplied TypeScript definitions for token types, options, and results.

Install

Follow the installation instructions supplied with your package access. They define the package source, version, and any required registry configuration.

The examples below import @r101/parser. They assume that this package is already installed in your project.

Core API

Parse a pattern with explicit flavor settings:

import { Flavors, parseRegex } from '@r101/parser'

const result = parseRegex('^(?<prefix>ORD)-(?<id>[0-9]{4})$', {
  flavor: Flavors.PCRE2,
  flags: '',
  delimiter: '/',
})

console.log(result.source)
console.log(result.patternError)
console.log(result.tokens)

The pattern describes ORD- followed by four ASCII digits. A successful parse reports patternError: false.

The flags option is required. Use an empty string when you do not need flags.

Parse a substitution independently:

import { Flavors, parseSubstitution } from '@r101/parser'

const result = parseSubstitution('Order received', {
  flavor: Flavors.PCRE2,
  flags: '',
  delimiter: '/',
})

console.log(result.patternError)
console.log(result.tokens)

This input contains literal replacement text. To validate group references, supply capture information from the pattern.

For a substitution with group references, pass the pattern's capture count and names through overrideState:

import { Flavors, parseRegex, parseSubstitution } from '@r101/parser'

const options = { flavor: Flavors.PCRE2, flags: '', delimiter: '/' }
const pattern = parseRegex('^(?<prefix>ORD)-(?<id>[0-9]{4})$', options)

const substitution = parseSubstitution('${id}: ${prefix}', {
  ...options,
  overrideState: {
    tables: { subpatternNames: pattern.state.tables.subpatternNames },
    status: { captureGroupCount: pattern.state.status.captureGroupCount },
  },
})

console.log(substitution.patternError) // false

The pattern has two named groups, prefix and id. Supplying their state lets the substitution parser recognize both references.

Parse result

Both functions return this shape. The token type depends on the parser:

type ParseResult<T extends Token = Token> = {
  readonly source: string
  tokens: T[]
  state: ParserState
  patternError: boolean
}

Field	Use
`source`	Original parsed input.
`tokens`	Typed syntax tokens, including available error information.
`state`	Parser configuration, status, and syntax data.
`patternError`	Whether the parser found a syntax error.

A syntax error can leave a partial token tree. Use an unclosed [ to test error highlighting.

Options

Option	Meaning
`flavor`	Required member of `Flavors`.
`flags`	Required string of active flags.
`delimiter`	Optional delimiter; defaults to `/`.
`invalidFlagsBehavior`	`throw` or `sanitize`; defaults to `throw`.
`featureFlags`	Override optional syntax features for a flavor.
`overrideState`	Supply related parser state, excluding the environment configuration.
`decomposeQuotedLiterals`	Expose individual atoms inside quoted literals such as `\Q...\E`; defaults to `false`.

Invalid flags can throw instead of returning a parse result. Handle this separately from a result with patternError: true.

Keep the default flavor features unless your integration requires a specific override. Such overrides do not change the target engine's capabilities.

Runtime compatibility

The package provides ESM and CommonJS entry points, with TypeScript declarations. Use ESM imports or CommonJS require to load it.

Request the runtime requirements with your package version.

Requirements​

Install​

Core API​

Parse result​

Options​

Runtime compatibility​