glob-to-regex.js 1.0.1

package/README.md

@@ -0,0 +1,87 @@
+# glob-to-regex.js
+
+Transform GLOB patterns to JavaScript regular expressions for fast file path matching.
+
+This tiny library converts familiar shell-style glob patterns like `**/*.ts` or `src/{a,b}/**/*.js` into JavaScript `RegExp` objects and provides a convenient matcher utility.
+
+## Install
+
+```bash
+yarn add glob-to-regex.js
+# or
+npm i glob-to-regex.js
+```
+
+## Quick start
+
+```ts
+import {toRegex, toMatcher} from 'glob-to-regex.js';
+
+// Build a RegExp from a glob
+const re = toRegex('src/**/test.ts');
+re.test('src/a/b/test.ts'); // true
+re.test('src/test.ts');     // true
+re.test('src/test.tsx');    // false
+
+// Build a predicate function from a pattern or an array of patterns
+const match = toMatcher(['**/*.ts', '!**/*.d.ts']); // negative patterns are not special; use a RegExp if needed
+match('index.ts');    // true
+match('types.d.ts');  // true (negation is not parsed specially)
+```
+
+## API
+
+- toRegex(pattern: string): RegExp
+	- Converts a glob pattern to an anchored regular expression (`^...$`).
+
+- toMatcher(pattern: string | RegExp | Array<string | RegExp>): (path: string) => boolean
+	- Accepts a glob string, a RegExp, or an array of them. If given an array, it returns true if any item matches (logical OR, short-circuited).
+	- Strings starting with `/` and ending with `/flags?` are treated as regular expressions (e.g. `"/\\.test\\.ts$/"`).
+
+## Supported glob features
+
+- `/` separates path segments
+- `*` matches zero or more characters within a single segment (does not cross `/`)
+- `?` matches exactly one character within a single segment
+- `**` matches across path segments, including none
+- `{a,b,c}` alternation groups (no nesting). Each item inside can itself contain glob syntax
+- Character classes: `[abc]`, `[a-z]`, `[!a-z]`, `[!abc]`
+
+Notes:
+- The produced RegExp is anchored at start and end (`^...$`).
+- Character classes are copied through to the output regex. Use standard JavaScript class syntax.
+- Brace groups are not nestable. If an unmatched `{` is found, it is treated literally.
+
+## Examples
+
+```ts
+toRegex('a/b/c.txt').test('a/b/c.txt'); // true
+toRegex('a/*.txt').test('a/file.txt');  // true
+toRegex('a/*.txt').test('a/x/y.txt');   // false
+toRegex('file?.js').test('file1.js');   // true
+toRegex('src/**/test.ts').test('src/a/b/test.ts'); // true
+toRegex('assets/**').test('assets/a/b.png');       // true
+toRegex('*.{html,txt}').test('page.html');         // true
+toRegex('src/{a,b}/**/*.ts').test('src/b/x/y.ts'); // true
+toRegex('file[0-9].txt').test('file5.txt');        // true
+toRegex('file[!0-9].txt').test('filea.txt');       // true
+toRegex('**/*.[jt]s{,x}').test('dir/a/b.jsx');     // true
+```
+
+## TypeScript
+
+Types are bundled. The library targets modern Node.js and browsers.
+
+## Performance
+
+`toRegex` performs a single pass over the pattern and creates a native RegExp. Matching is then performed by V8's highly optimized engine.
+
+## Limitations
+
+- Brace groups are not nested.
+- Negated globs like `!**/*.d.ts` are not parsed specially. If you need exclusion, combine multiple matchers or filter results separately.
+
+## License
+
+Apache-2.0 © streamich
+

package/lib/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Convert a glob pattern to a regular expression
+ *
+ * Supports:
+ * - `/` to separate path segments
+ * - `*` to match zero or more characters in a path segment
+ * - `?` to match one character in a path segment
+ * - `**` to match any number of path segments, including none
+ * - `{}` to group conditions (e.g. `{html,txt}`)
+ * - `[abc]`, `[a-z]`, `[!a-z]`, `[!abc]` character classes
+ */
+export declare const toRegex: (pattern: string) => RegExp;
+/**
+ * A glob pattern to match files paths against. An array or a single pattern
+ * can be provided, if an array is given, then individual patterns will be
+ * tested in order until one matches (OR short-circuits).
+ *
+ * For each pattern a string or a regular expression can be provided. If the
+ * string starts with `/` and ends with `/<flags>?` it is treated as a regular
+ * expression.
+ */
+export type Pattern = string | RegExp | (string | RegExp)[];
+export type Matcher = (path: string) => boolean;
+export declare const toMatcher: (pattern: Pattern) => Matcher;

package/lib/index.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toMatcher = exports.toRegex = void 0;
+const escapeRe = (ch) => (/[.^$+{}()|\\]/.test(ch) ? `\\${ch}` : ch);
+/**
+ * Convert a glob pattern to a regular expression
+ *
+ * Supports:
+ * - `/` to separate path segments
+ * - `*` to match zero or more characters in a path segment
+ * - `?` to match one character in a path segment
+ * - `**` to match any number of path segments, including none
+ * - `{}` to group conditions (e.g. `{html,txt}`)
+ * - `[abc]`, `[a-z]`, `[!a-z]`, `[!abc]` character classes
+ */
+const toRegex = (pattern) => {
+    let regexStr = '';
+    let i = 0;
+    // Helper to parse a brace group like {a,b,c}. No nesting support.
+    const parseBraceGroup = () => {
+        // Assume current char is '{'
+        i++; // skip '{'
+        const parts = [];
+        let cur = '';
+        let closed = false;
+        while (i < pattern.length) {
+            const ch = pattern[i];
+            if (ch === '}') {
+                parts.push(cur);
+                i++; // consume '}'
+                closed = true;
+                break;
+            }
+            if (ch === ',') {
+                parts.push(cur);
+                cur = '';
+                i++;
+                continue;
+            }
+            cur += ch;
+            i++;
+        }
+        if (!closed) {
+            // treat as literal '{...'
+            return '\\{' + escapeRe(cur);
+        }
+        // Convert each part recursively to support globs inside braces
+        const alt = parts.map((p) => (0, exports.toRegex)(p).source.replace(/^\^/, '').replace(/\$$/, '')).join('|');
+        return `(?:${alt})`;
+    };
+    while (i < pattern.length) {
+        const char = pattern[i];
+        switch (char) {
+            case '*': {
+                // Check for double star **
+                if (pattern[i + 1] === '*') {
+                    // Collapse consecutive * beyond two (e.g., *** -> **)
+                    let j = i + 2;
+                    while (pattern[j] === '*')
+                        j++;
+                    // If followed by a slash, make it optional to allow zero segments
+                    if (pattern[j] === '/') {
+                        regexStr += '(?:.*/)?';
+                        i = j + 1; // consume **/
+                    }
+                    else {
+                        regexStr += '.*';
+                        i = j; // consume **
+                    }
+                }
+                else {
+                    regexStr += '[^/]*';
+                    i++;
+                }
+                break;
+            }
+            case '?':
+                regexStr += '[^/]';
+                i++;
+                break;
+            case '[': {
+                // Copy character class as-is with support for leading '!'
+                let cls = '[';
+                i++;
+                if (i < pattern.length && pattern[i] === '!') {
+                    cls += '^';
+                    i++;
+                }
+                // if first after [ or [^ is ']' include it literally
+                if (i < pattern.length && pattern[i] === ']') {
+                    cls += ']';
+                    i++;
+                }
+                while (i < pattern.length && pattern[i] !== ']') {
+                    const ch = pattern[i];
+                    // Escape backslash inside class
+                    cls += ch === '\\' ? '\\\\' : ch;
+                    i++;
+                }
+                if (i < pattern.length && pattern[i] === ']') {
+                    cls += ']';
+                    i++;
+                }
+                else {
+                    // Unclosed class -> treat '[' literally
+                    regexStr += '\\[';
+                    continue;
+                }
+                regexStr += cls;
+                break;
+            }
+            case '{': {
+                regexStr += parseBraceGroup();
+                break;
+            }
+            case '/':
+                regexStr += '/';
+                i++;
+                break;
+            case '.':
+            case '^':
+            case '$':
+            case '+':
+            case '(':
+            case ')':
+            case '|':
+            case '\\':
+                regexStr += `\\${char}`;
+                i++;
+                break;
+            default:
+                regexStr += char;
+                i++;
+                break;
+        }
+    }
+    return new RegExp('^' + regexStr + '$');
+};
+exports.toRegex = toRegex;
+const isRegExp = /^\/(.{1,4096})\/([gimsuy]{0,6})$/;
+const toMatcher = (pattern) => {
+    const regexes = [];
+    const patterns = Array.isArray(pattern) ? pattern : [pattern];
+    for (const pat of patterns) {
+        if (typeof pat === 'string') {
+            const match = isRegExp.exec(pat);
+            if (match) {
+                const [, expr, flags] = match;
+                regexes.push(new RegExp(expr, flags));
+            }
+            else {
+                regexes.push((0, exports.toRegex)(pat));
+            }
+        }
+        else {
+            regexes.push(pat);
+        }
+    }
+    const length = regexes.length;
+    return (path) => {
+        for (let i = 0; i < length; i++)
+            if (regexes[i].test(path))
+                return true;
+        return false;
+    };
+};
+exports.toMatcher = toMatcher;

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "glob-to-regex.js",
+  "packageManager": "yarn@4.9.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.0.1",
+  "description": "Transform GLOB patterns to JavaScript regular expressions for fast file path matching.",
+  "author": {
+    "name": "streamich",
+    "url": "https://github.com/streamich"
+  },
+  "homepage": "https://github.com/streamich/glob-to-regex",
+  "repository": "streamich/glob-to-regex",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/streamich"
+  },
+  "keywords": [
+    "glob",
+    "regex",
+    "regexp",
+    "pattern",
+    "matcher",
+    "path",
+    "filesystem",
+    "wildcard"
+  ],
+  "engines": {
+    "node": ">=10.0"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "typings": "lib/index.d.ts",
+  "files": [
+    "LICENSE",
+    "lib/"
+  ],
+  "license": "Apache-2.0",
+  "scripts": {
+    "format": "biome format ./src",
+    "format:fix": "biome format --write ./src",
+    "lint": "biome lint ./src",
+    "lint:fix": "biome lint --apply ./src",
+    "clean": "npx rimraf@6.0.1 lib typedocs coverage gh-pages yarn-error.log",
+    "build": "tsc --project tsconfig.build.json --module commonjs --target es2020 --outDir lib",
+    "test": "vitest ./src",
+    "coverage": "vitest run --coverage",
+    "typedoc": "npx typedoc@0.25.13 --tsconfig tsconfig.build.json",
+    "build:pages": "npx rimraf@6.0.1 gh-pages && mkdir -p gh-pages && cp -r typedocs/* gh-pages && cp -r coverage gh-pages/coverage",
+    "deploy:pages": "gh-pages -d gh-pages",
+    "publish-coverage-and-typedocs": "yarn typedoc && yarn coverage && yarn build:pages && yarn deploy:pages"
+  },
+  "peerDependencies": {
+    "tslib": "2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.1.2",
+    "@vitest/coverage-v8": "^3.2.4",
+    "config-galore": "^1.0.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  }
+}