Graphmatch

1.1.1 · active · verified Sun Apr 19

Graphmatch is a low-level utility designed for matching a string against a directed acyclic graph (DAG) composed of regular expressions. It provides flexible matching capabilities, supporting both full and partial string matches against these complex regex structures. Developers can exercise fine-grained control over partial matching behavior at the individual node level within the graph. A key feature is the ability to compile the entire graph into a single JavaScript RegExp object, which significantly optimizes performance for scenarios requiring multiple matches against the same graph. The package is currently at version 1.1.1 and appears to be actively maintained, though no specific release cadence is outlined in the documentation. Its core differentiation lies in offering a programmatic, graph-based approach to regex matching, which is more powerful and manageable than composing single, overly complex regular expressions or chaining multiple simple ones, particularly useful for structured pattern recognition like advanced globbing.

Common errors

```
TypeError: (0 , graphmatch_1.default) is not a function
```
cause Incorrect CommonJS `require` usage for a package that primarily offers an ESM default export, or attempting to use a default import in a CommonJS context without proper transpilation.

fix For native ESM, use `import graphmatch from 'graphmatch';`. If in a CommonJS environment, you might need to use `const graphmatch = require('graphmatch').default;` or ensure your build setup correctly transpiles ESM imports.
```
TypeError: Cannot read properties of undefined (reading 'compile')
```
cause Attempting to access `compile` on an undefined `graphmatch` object, often due to an incorrect import where the default export was not successfully captured, or treating `compile` as a named export.

fix Verify that `import graphmatch from 'graphmatch';` is correctly acquiring the default export. The `compile` method is a property of the default `graphmatch` function, not a separate named export.
```
TypeError: Invalid regular expression: /.../: Flags can't be modified (or similar error related to RegExp flags)
```
cause Using regular expressions within the graph that have inconsistent flags (e.g., one with 'i' and another without), which `graphmatch` does not support across a single graph structure.

fix Review all `regex` properties in your graph definition and ensure that they all use the exact same set of RegExp flags, or no flags at all. For example, `regex: /pattern/i` should be consistent for all regexes if `i` is desired.

Warnings

gotcha All regular expressions within a single graph must use the same RegExp flags (e.g., 'i', 'g', 'm'). Mixing flags across different nodes in the same graph is not supported and will lead to unexpected behavior or errors.
Fix: Ensure all `regex` properties in your graph nodes are created with identical flags, or no flags, consistently across the entire graph structure.
gotcha The graph matching process always begins from the very start of the input string. It does not support arbitrary starting positions within the string.
Fix: If matching needs to occur at arbitrary positions, you must manually iterate through substrings or modify your graph's root regex to optionally match leading characters, such as `/.*/`.
gotcha As a 'low-level utility', `graphmatch` expects a well-formed graph of regexes. Malformed graph structures (e.g., cycles in a DAG, invalid `regex` properties, or incorrect `children` arrays) are not explicitly validated beyond basic runtime checks and can lead to unexpected behavior or crashes.
Fix: Thoroughly test your graph definitions, especially complex ones. Ensure `children` are always arrays of valid graph nodes and that `regex` properties are actual `RegExp` instances.
gotcha For repeated matching against the same graph, directly calling the `graphmatch` function multiple times can be less performant than pre-compiling the graph. The internal compilation step has an overhead.
Fix: If you intend to match the same graph many times, use `graphmatch.compile(GRAPH_DEFINITION)` once to get a compiled RegExp and then use `compiledRe.test(string)` for subsequent checks.

Install

npm install graphmatch npm
yarn add graphmatch yarn
pnpm add graphmatch pnpm

Imports

graphmatch
wrong:
```
const graphmatch = require('graphmatch');
```
correct:
```
import graphmatch from 'graphmatch';
```
The primary export is a default function. While CommonJS `require` might work in some transpiled environments, native ESM import is the intended and recommended approach.

graphmatch.compile

wrong:

import { compile } from 'graphmatch'; // This is incorrect, compile is a property of the default export

correct:

import graphmatch from 'graphmatch';
const compiledRegex = graphmatch.compile(GRAPH_DEFINITION);

The `compile` method is a property of the default `graphmatch` function, not a named export. It's used to pre-process a graph into a single RegExp for efficiency.

GraphNode
```
type GraphNode = { regex: RegExp; children?: GraphNode[]; partial?: boolean; };
```
While not directly imported, understanding the `GraphNode` type (as implicitly defined in examples) is crucial for constructing the input graph. The library ships with TypeScript types.

Quickstart

Demonstrates basic full and partial string matching against a regex graph, and the compilation of a graph to a single RegExp for performance.

import graphmatch from 'graphmatch';

const GRAPH = {
  regex: /foo/,
  children: [
    {
      regex: /\//,
      children: [
        {
          regex: /bar/,
          children: [
            {
              regex: /\//,
              children: [
                {
                  regex: /qux/
                }
              ]
            }
          ]
        },
        {
          regex: /baz/,
          children: [
            {
              regex: /\//,
              children: [
                {
                  regex: /qux/
                }
              ]
            }
          ]
        }
      ]
    }
  ]
};

// Match against the graph fully
console.log('Full match `foo/bar/qux`:', graphmatch(GRAPH, 'foo/bar/qux')); // => true
console.log('Full match `foo/baz`:', graphmatch(GRAPH, 'foo/baz'));     // => false

// Match against the graph partially
console.log('Partial match `foo/bar/`:', graphmatch(GRAPH, 'foo/bar/', { partial: true })); // => true
console.log('Partial match `bar`:', graphmatch(GRAPH, 'bar', { partial: true }));         // => false

// Compile the graph to a single regex for repeated, efficient matching
const fullCompiledRe = graphmatch.compile(GRAPH);
console.log('Compiled regex test `foo/bar/qux`:', fullCompiledRe.test('foo/bar/qux')); // => true
console.log('Compiled regex test `foo/bar`:', fullCompiledRe.test('foo/bar'));       // => false

const partialCompiledRe = graphmatch.compile(GRAPH, { partial: true });
console.log('Compiled partial regex test `foo/bar`:', partialCompiledRe.test('foo/bar')); // => true

view raw JSON →