Registry / serialization / oniguruma-parser

oniguruma-parser

library0.12.2jsnpmunverified

The `oniguruma-parser` library provides a robust TypeScript solution for working with Oniguruma regular expressions, offering functionalities such as parsing, validation, AST traversal, transformation, and optimization. The current stable version is 0.12.2, with minor releases frequently introducing new features like optimizer improvements (v0.12.1), support for new flags (v0.12.0), and quality-of-life enhancements for AST manipulation (v0.10.0). Its primary distinction lies in its deep understanding and accurate representation of the Oniguruma regex engine's specific syntax and semantics, which differs from standard ECMAScript regexes. It is widely utilized and battle-tested in critical projects like `Oniguruma-To-ES` and `tm-grammars`, which process tens of thousands of real-world Oniguruma regexes for tools such as VS Code and Shiki, ensuring high fidelity and reliability for TextMate grammars, Ruby, and PHP environments.

serialization

npm install oniguruma-parser

github ↗package ↗

INSTALL

IMPORT

SIG · ONIGURUMA-PARSER

oniguruma-parser

serializationjavascriptv0.12.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

toOnigurumaAst

✓ import { toOnigurumaAst } from 'oniguruma-parser';

✗ const { toOnigurumaAst } = require('oniguruma-parser-cjs');

ESM is the primary distribution method. `oniguruma-parser-cjs` is a third-party CommonJS wrapper and may not always be up-to-date with the latest features or bug fixes.

parse

✓ import { parse } from 'oniguruma-parser/parser';

The core `parse` function, wrapped by `toOnigurumaAst`, is available from the dedicated parser submodule for more granular control over AST node creation and options.

traverse

✓ import { traverse } from 'oniguruma-parser/traverser';

For advanced AST manipulation, the `traverse` function enables visitor pattern-based traversal and transformation of `OnigurumaAst` nodes.

Parses an Oniguruma regular expression pattern into its Abstract Syntax Tree (AST) representation, demonstrating basic usage with flags and compile-time rules.

import { toOnigurumaAst } from 'oniguruma-parser'; const pattern = '^(?:foo|bar)a?([A-Z]+)*\\d'; const ast = toOnigurumaAst(pattern, { flags: 'im', rules: { captureGroup: true, singleline: false } }); console.log(`Parsed AST for pattern '${pattern}':`); console.log(JSON.stringify(ast, null, 2)); /* Example of a simplified output structure: { "type": "Regex", "body": [ { "type": "Alternative", "body": [ { "type": "Assertion", "kind": "line_start" }, // ... more nodes ] } ], "flags": { "type": "Flags", "ignoreCase": true, "dotAll": false, // ... more flags } } */

Debug

Known issues

breakingThe AST format underwent significant changes in v0.10.0. Node properties like `alternatives`, `elements`, `element`, and `pattern` were renamed to `body`. Additionally, the `Pattern` node type was removed, with its children now residing directly within the `Regex` node's `body` array. The `AbsentFunction` node was also renamed.

fix

Refactor AST traversal and manipulation logic to use the `body` property for node content and adjust for the removal of the `Pattern` node. Review the updated AST structure by logging parsed regexes.

affects: >=0.10.0

breakingIn v0.11.0, the `CapturingGroup` node property `hasSubroutine` was renamed to `isSubroutined` to more accurately reflect its meaning (indicating if the group is directly referenced by one or more subroutines).

fix

Update any code accessing `CapturingGroup` properties to use `isSubroutined` instead of `hasSubroutine`.

affects: >=0.11.0

breakingVersion 0.12.0 introduced changes to the AST format, renaming a couple of `kind` values for nodes that can switch their specific type.

fix

Consult the updated AST types for `kind` property values and adjust any code that relies on specific `kind` values for pattern matching or conditional logic.

affects: >=0.12.0

breakingThe `createQuantifier` function API changed in v0.8.0. The order of its first and last arguments (`kind` and `element`) was swapped, `kind` became a required argument (previously defaulted to `'greedy'`), and it no longer automatically changes `kind` to `'possessive'` for reversed `min`/`max` values.

fix

Review all calls to `createQuantifier` and ensure arguments are in the correct order (`kind` before `element`), `kind` is explicitly provided, and `min`/`max` values are set accurately without relying on implicit possessive conversion.

affects: >=0.8.0

breakingIn v0.9.0, the `Traverser`'s visitor execution order changed: the `'*'` `exit` function now runs *last*, after any node type's specific `exit` function. This affects how post-processing logic is applied.

fix

Adjust `Traverser` visitor logic, especially if relying on the order of `exit` calls for `'*'` and specific node types. Ensure that general cleanup or finalization logic in `'*'` `exit` accounts for this change.

affects: >=0.9.0

gotchaUsing `require('oniguruma-parser-cjs')` for CommonJS environments is documented, but this is a *third-party wrapper* and not officially maintained by the `oniguruma-parser` library authors. It may not always be in sync with the latest official releases, potentially leading to outdated APIs or missing features.

fix

Prefer using ESM imports if possible, or closely monitor the `oniguruma-parser-cjs` project for updates and compatibility with the official `oniguruma-parser` releases.

affects: All

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'body')

Attempting to access old AST properties like `alternatives`, `elements`, `element`, or `pattern` after the v0.10.0 breaking change, which renamed them to `body`.

fix

Update your AST traversal and manipulation code to use the `body` property for accessing child nodes or content, as well as accounting for the removal of the `Pattern` node type.

Property 'hasSubroutine' does not exist on type 'CapturingGroup'. Did you mean 'isSubroutined'?

Accessing the deprecated `hasSubroutine` property on a `CapturingGroup` node after v0.11.0, where it was renamed for clarity.

fix

Replace all instances of `capturingGroup.hasSubroutine` with `capturingGroup.isSubroutined` in your code.

Argument of type 'string' is not assignable to parameter of type 'OnigurumaAstNodeKind'.

Incorrect usage of `createQuantifier` from the parser API, specifically passing arguments in the wrong order or omitting the required `kind` argument introduced in v0.8.0.

fix

Review the `createQuantifier` function signature. Ensure that the `kind` argument (e.g., `'greedy'`, `'lazy'`, `'possessive'`) is explicitly provided as the second argument, followed by the `element` and then `min`/`max` values.

Upgrade

Version history

0.12.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/slevithan/oniguruma-parser ↗

packagehttps://www.npmjs.com/package/oniguruma-parser ↗