graphmatch 1.0.0

package/asd.js

@@ -0,0 +1,81 @@
+
+import graphmatch from './dist/index.js';
+
+
+const GRAPH = {
+  regex: /foo/,
+  children: [
+    {
+      regex: /\//,
+      children: [
+        {
+          regex: /bar/,
+          children: [
+            {
+              regex: /\//,
+              children: [
+                {
+                  regex: /qux/
+                }
+              ]
+            }
+          ]
+        },
+        {
+          regex: /baz/,
+          children: [
+            {
+              regex: /\//,
+              children: [
+                {
+                  regex: /qux/
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+};
+
+// Let's now match against the graph, fully
+
+console.log ('1.');
+
+console.log ( graphmatch ( GRAPH, 'foo/bar/qux' ) ); // => true
+console.log ( graphmatch ( GRAPH, 'foo/baz/qux' ) ); // => true
+
+console.log ( graphmatch ( GRAPH, 'foo/bar/whoops' ) ); // => false
+console.log ( graphmatch ( GRAPH, 'foo/baz' ) ); // => false
+
+// Let's now match against the graph, partially
+// A partial match happens when any matching node in the graph reaches the end of the string
+
+console.log ('2.');
+
+console.log ( graphmatch ( GRAPH, 'foo/bar/qux', { partial: true } ) ); // => true
+console.log ( graphmatch ( GRAPH, 'foo/bar/', { partial: true } ) ); // => true
+console.log ( graphmatch ( GRAPH, 'foo/bar', { partial: true } ) ); // => true
+console.log ( graphmatch ( GRAPH, 'foo/', { partial: true } ) ); // => true
+console.log ( graphmatch ( GRAPH, 'foo', { partial: true } ) ); // => true
+
+console.log ( graphmatch ( GRAPH, 'foo/bar/whoops', { partial: true } ) ); // => false
+console.log ( graphmatch ( GRAPH, 'foo/barsomething', { partial: true } ) ); // => false
+console.log ( graphmatch ( GRAPH, 'bar', { partial: true } ) ); // => false
+
+// Let's now compile the whole graph to a single regex
+// This is useful if you expect to match against the graph multiple times
+// It's faster to compile the graph once and match against it multiple times
+
+console.log ('3.');
+
+const fullRe = graphmatch.compile ( GRAPH ); // => RegExp
+
+console.log ( fullRe.test ( 'foo/bar/qux' ) ); // => true
+console.log ( fullRe.test ( 'foo/bar' ) ); // => false
+
+const partialRe = graphmatch.compile ( GRAPH, { partial: true } ); // => RegExp
+
+console.log ( partialRe.test ( 'foo/bar/qux' ) ); // => true
+console.log ( partialRe.test ( 'foo/bar' ) ); // => true

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import type { Node, Options } from './types.js';
+declare const graphmatch: {
+    (node: Node, input: string, options?: Options): boolean;
+    compile(node: Node, options?: Options): RegExp;
+};
+export type { Node, Options };
+export default graphmatch;

package/dist/index.js

@@ -0,0 +1,14 @@
+/* IMPORT */
+import { getNodeFlags, getNodeSource } from './utils.js';
+/* MAIN */
+const graphmatch = (node, input, options) => {
+    return graphmatch.compile(node, options).test(input);
+};
+/* UTILITIES */
+graphmatch.compile = (node, options) => {
+    const partial = options?.partial ?? false;
+    const source = getNodeSource(node, partial);
+    const flags = getNodeFlags(node);
+    return new RegExp(`^(?:${source})$`, flags);
+};
+export default graphmatch;

package/dist/types.d.ts

@@ -0,0 +1,8 @@
+type Node = {
+    regex?: RegExp;
+    children?: Node[];
+};
+type Options = {
+    partial?: boolean;
+};
+export type { Node, Options };

package/dist/types.js

@@ -0,0 +1,2 @@
+/* MAIN */
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,5 @@
+import type { Node } from './types.js';
+declare const getNodeFlags: (node: Node) => string;
+declare const getNodeSource: (node: Node, partial: boolean) => string;
+declare const visitNode: (node: Node, visitor: (node: Node) => void) => void;
+export { getNodeFlags, getNodeSource, visitNode };

package/dist/utils.js

@@ -0,0 +1,43 @@
+/* IMPORT */
+/* MAIN */
+const getNodeFlags = (node) => {
+    let flags = '';
+    visitNode(node, node => {
+        if (!node.regex)
+            return;
+        const nodeFlags = node.regex.flags;
+        flags || (flags = nodeFlags);
+        if (flags !== nodeFlags) {
+            throw new Error(`Inconsistent RegExp flags used: "${flags}" and "${nodeFlags}"`);
+        }
+    });
+    return flags;
+};
+const getNodeSource = (node, partial) => {
+    let source = '';
+    if (node.regex) {
+        source += partial ? '(?:$|' : '';
+        source += node.regex.source;
+    }
+    if (node.children?.length) {
+        const children = node.children.map(node => getNodeSource(node, partial)).filter(Boolean);
+        if (children.length) {
+            const needsWrapperGroup = (children.length > 1) || (partial && !source.length);
+            source += needsWrapperGroup ? partial ? '(?:$|' : '(?:' : '';
+            source += children.join('|');
+            source += needsWrapperGroup ? ')' : '';
+        }
+    }
+    if (node.regex) {
+        source += partial ? ')' : '';
+    }
+    return source;
+};
+const visitNode = (node, visitor) => {
+    visitor(node);
+    node.children?.forEach(node => {
+        visitNode(node, visitor);
+    });
+};
+/* EXPORT */
+export { getNodeFlags, getNodeSource, visitNode };

package/license

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025-present Fabio Spampinato
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "graphmatch",
+  "repository": "github:fabiospampinato/graphmatch",
+  "description": "A low-level utility for matching a string against a directed acyclic graph of regexes.",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "benchmark": "tsex benchmark",
+    "benchmark:watch": "tsex benchmark --watch",
+    "clean": "tsex clean",
+    "compile": "tsex compile",
+    "compile:watch": "tsex compile --watch",
+    "test": "tsex test",
+    "test:watch": "tsex test --watch",
+    "prepublishOnly": "tsex prepare"
+  },
+  "keywords": [
+    "regex",
+    "regexp",
+    "dag",
+    "graph",
+    "match"
+  ],
+  "devDependencies": {
+    "benchloop": "^2.1.1",
+    "fava": "^0.3.5",
+    "tsex": "^4.0.2",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "lodash": "^4.17.21"
+  }
+}

package/readme.md

@@ -0,0 +1,100 @@
+# Graphmatch
+
+A low-level utility for matching a string against a directed acyclic graph of regexes.
+
+- It supports matching strings partially too.
+- It supports compiling the whole graph to a regex, even for partial matches.
+- The graph will always be matched against the input string from the very start.
+- RegExp flags are supported as long as they are the same for all the regexes in the graph.
+
+## Install
+
+```sh
+npm install graphmatch
+```
+
+## Usage
+
+```ts
+import graphmatch from 'graphmatch';
+
+// Let's say we would like to match against this glob: foo/{bar,baz}/qux
+// Let's express that as a graph of regexes that this library can match against
+// Whether you reuse the "qux" node or not doesn't matter, both are supported
+
+const GRAPH = {
+  regex: /foo/,
+  children: [
+    {
+      regex: /\//,
+      children: [
+        {
+          regex: /bar/,
+          children: [
+            {
+              regex: /\//,
+              children: [
+                {
+                  regex: /qux/
+                }
+              ]
+            }
+          ]
+        },
+        {
+          regex: /baz/,
+          children: [
+            {
+              regex: /\//,
+              children: [
+                {
+                  regex: /qux/
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+};
+
+// Let's now match against the graph, fully
+
+graphmatch ( GRAPH, 'foo/bar/qux' ); // => true
+graphmatch ( GRAPH, 'foo/baz/qux' ); // => true
+
+graphmatch ( GRAPH, 'foo/bar/whoops' ); // => false
+graphmatch ( GRAPH, 'foo/baz' ); // => false
+
+// Let's now match against the graph, partially
+// A partial match happens when any matching node in the graph reaches the end of the string
+
+graphmatch ( GRAPH, 'foo/bar/qux', { partial: true } ); // => true
+graphmatch ( GRAPH, 'foo/bar/', { partial: true } ); // => true
+graphmatch ( GRAPH, 'foo/bar', { partial: true } ); // => true
+graphmatch ( GRAPH, 'foo/', { partial: true } ); // => true
+graphmatch ( GRAPH, 'foo', { partial: true } ); // => true
+
+graphmatch ( GRAPH, 'foo/bar/whoops', { partial: true } ); // => false
+graphmatch ( GRAPH, 'foo/barsomething', { partial: true } ); // => false
+graphmatch ( GRAPH, 'bar', { partial: true } ); // => false
+
+// Let's now compile the whole graph to a single regex
+// This is useful if you expect to match against the graph multiple times
+// It's faster to compile the graph once and match against it multiple times
+
+const fullRe = graphmatch.compile ( GRAPH ); // => RegExp
+
+fullRe.test ( 'foo/bar/qux' ); // => true
+fullRe.test ( 'foo/bar' ); // => false
+
+const partialRe = graphmatch.compile ( GRAPH, { partial: true } ); // => RegExp
+
+partialRe.test ( 'foo/bar/qux' ); // => true
+partialRe.test ( 'foo/bar' ); // => true
+```
+
+## License
+
+MIT © Fabio Spampinato