{"id":10966,"library":"graphmatch","title":"Graphmatch","description":"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.","status":"active","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/fabiospampinato/graphmatch","tags":["javascript","regex","regexp","dag","graph","match","typescript"],"install":[{"cmd":"npm install graphmatch","lang":"bash","label":"npm"},{"cmd":"yarn add graphmatch","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphmatch","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const graphmatch = require('graphmatch');","symbol":"graphmatch","correct":"import graphmatch from 'graphmatch';"},{"note":"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.","wrong":"import { compile } from 'graphmatch'; // This is incorrect, compile is a property of the default export","symbol":"graphmatch.compile","correct":"import graphmatch from 'graphmatch';\nconst compiledRegex = graphmatch.compile(GRAPH_DEFINITION);"},{"note":"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.","symbol":"GraphNode","correct":"type GraphNode = { regex: RegExp; children?: GraphNode[]; partial?: boolean; };"}],"quickstart":{"code":"import graphmatch from 'graphmatch';\n\nconst GRAPH = {\n  regex: /foo/,\n  children: [\n    {\n      regex: /\\//,\n      children: [\n        {\n          regex: /bar/,\n          children: [\n            {\n              regex: /\\//,\n              children: [\n                {\n                  regex: /qux/\n                }\n              ]\n            }\n          ]\n        },\n        {\n          regex: /baz/,\n          children: [\n            {\n              regex: /\\//,\n              children: [\n                {\n                  regex: /qux/\n                }\n              ]\n            }\n          ]\n        }\n      ]\n    }\n  ]\n};\n\n// Match against the graph fully\nconsole.log('Full match `foo/bar/qux`:', graphmatch(GRAPH, 'foo/bar/qux')); // => true\nconsole.log('Full match `foo/baz`:', graphmatch(GRAPH, 'foo/baz'));     // => false\n\n// Match against the graph partially\nconsole.log('Partial match `foo/bar/`:', graphmatch(GRAPH, 'foo/bar/', { partial: true })); // => true\nconsole.log('Partial match `bar`:', graphmatch(GRAPH, 'bar', { partial: true }));         // => false\n\n// Compile the graph to a single regex for repeated, efficient matching\nconst fullCompiledRe = graphmatch.compile(GRAPH);\nconsole.log('Compiled regex test `foo/bar/qux`:', fullCompiledRe.test('foo/bar/qux')); // => true\nconsole.log('Compiled regex test `foo/bar`:', fullCompiledRe.test('foo/bar'));       // => false\n\nconst partialCompiledRe = graphmatch.compile(GRAPH, { partial: true });\nconsole.log('Compiled partial regex test `foo/bar`:', partialCompiledRe.test('foo/bar')); // => true","lang":"typescript","description":"Demonstrates basic full and partial string matching against a regex graph, and the compilation of a graph to a single RegExp for performance."},"warnings":[{"fix":"Ensure all `regex` properties in your graph nodes are created with identical flags, or no flags, consistently across the entire graph structure.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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 `/.*/`.","message":"The graph matching process always begins from the very start of the input string. It does not support arbitrary starting positions within the string.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: (0 , graphmatch_1.default) is not a function"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'compile')"},{"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.","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.","error":"TypeError: Invalid regular expression: /.../: Flags can't be modified (or similar error related to RegExp flags)"}],"ecosystem":"npm"}