graphmatch

library1.1.1jsnpmunverified

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.

data

npm install graphmatch

github ↗package ↗

INSTALL

IMPORT

SIG · GRAPHMATCH

graphmatch

datajavascriptv1.1.1

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.

graphmatch

✓ import graphmatch from 'graphmatch';

✗ const graphmatch = require('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

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

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

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.

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

Debug

Known issues

gotchaAll 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.

affects: >=1.0.0

gotchaThe 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 `/.*/`.

affects: >=1.0.0

gotchaAs 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.

affects: >=1.0.0

gotchaFor 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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: (0 , graphmatch_1.default) is not a function

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')

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)

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.

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/fabiospampinato/graphmatch ↗

packagehttps://www.npmjs.com/package/graphmatch ↗