@reliverse/rematch

@reliverse/rematch is a high-performance minimal glob matcher, with micromatch-level power, zepto-level size, and reliverse-grade dx.

sponsor — discord — npm — github

---

‼️Attention! The latest implementation of @reliverse/rematch now lives in the framework repository for building libraries — @reliverse/dler. Please use @reliverse/dler-matcher instead of @reliverse/rematch.

Installation

bun add @reliverse/rematch
# bun • pnpm • yarn • npm

Features

You want micromatch/picomatch features in a zeptomatch-sized(🔜) package.

• 🧩 Drop-in replacement for micromatch, zeptomatch, picomatch
• 🧠 Full bash-style globbing support with advanced pattern matching
• 🪶 Tiny (7.5 kB), tree-shakeable, dependency-free implementation
• ⚡ Fast runtime with optimized regex compilation and caching
• 🔧 Complete toolset: escape, parse, compile, and match
• 🔜 1700+ picomatch and zeptomatch tests passed
• 🪄 Rich feature set with intuitive API

Heads Up

• Most of the things mentioned in this doc aren’t implemented yet — they’re part of the vision for ~v1.3.0.
• Got thoughts? Ideas? Send your feedback in Discord or use GitHub Issues.
• Your feedback means the world and helps shape where this project goes next. Thank you!

Features in Detail

Core Pattern Matching

• Wildcards
  • * - Matches any characters except path separators
  • ** - Matches any characters including path separators (globstar)
  • ? - Matches exactly one character except path separators

Advanced Pattern Matching

• Character Classes

  • [abc] - Matches any single character from the set
  • [a-z] - Matches any single character in the range
  • [!abc] or [^abc] - Matches any single character not in the set

• Brace Expansion

  • {a,b,c} - Matches any of the comma-separated patterns
  • Nested braces supported: {a,{b,c}} expands correctly
  • Numeric ranges: {1..5} matches 1,2,3,4,5
  • Padded numeric ranges: {01..05} matches 01,02,03,04,05
  • Alphabetic ranges: {a..e} matches a,b,c,d,e
  • Case-sensitive alphabetic ranges: {A..E} vs {a..e}

• Pattern Negation

  • !pattern - Matches anything that doesn't match the pattern
  • Multiple negations: !!pattern (negates the negation)
  • Combining with other patterns: ['*.js', '!test.js']

Special Features

• Dot File Handling

  • By default, * won't match files starting with a dot
  • Explicit dot matching with .*.js or setting dot: true option

• Path Handling

  • Automatic path normalization (converts backslashes to forward slashes)
  • Proper handling of path separators in globstar patterns

Performance Optimizations

• Pattern Compilation

  • Automatic caching of compiled patterns
  • Efficient regex generation with optimized character classes
  • Smart handling of static vs dynamic patterns

• Memory Efficiency

  • Minimal memory footprint
  • Efficient pattern parsing and compilation
  • Smart caching strategies

API Reference

Main Function

// Returns true if input matches pattern(s)
rematch(pattern: string, input: string, options?: RematchOptions): boolean
rematch(patterns: string[], input: string, options?: RematchOptions): boolean

// Returns a compiled matcher function
rematch(pattern: string, options?: RematchOptions): Matcher
rematch(patterns: string[], options?: RematchOptions): Matcher

Options

interface RematchOptions {
  dot?: boolean;      // Match dotfiles (default: false)
  nocase?: boolean;   // Case-insensitive matching (default: false)
  ignore?: string | string[]; // Patterns to ignore (applies to input)
}

Types

type Matcher = (input: string) => boolean;

type ScanResult = {
  isGlob: boolean;
  negated: boolean;
  glob: string;
  parts?: string[];
};

Utility Functions

All utility functions are available as named exports and as properties on the default export:

compile(pattern: string, options?: RematchOptions): Matcher
makeRegex(pattern: string, options?: RematchOptions): RegExp
makeRe(pattern: string, options?: RematchOptions): RegExp // Alias for makeRegex
normalizePath(pathStr: string): string
escapeGlob(str: string): string
unescapeGlob(str: string): string
isStatic(pattern: string, options?: { dot?: boolean }): boolean
scan(pattern: string, options?: { parts?: boolean }): ScanResult
explode(pattern: string): { static: string[]; dynamic: string[] }

Examples

import rematch, { compile, normalizePath } from "@reliverse/rematch";

// Basic matching
rematch("*.js", "file.js");                  // → true
rematch("**/*.js", "src/utils/file.js");     // → true
rematch("*.js", "file.ts");                  // → false

// Dot files
rematch("*.js", ".hidden.js");               // → false
rematch("*.js", ".hidden.js", { dot: true }); // → true

// Case-insensitive matching
rematch("*.JS", "file.js", { nocase: true }); // → true

// Character classes
rematch("[abc].js", "a.js");                 // → true
rematch("[!a-z].js", "9.js");                // → true

// Brace expansion
rematch("file.{js,ts}", "file.js");          // → true
rematch("file{1..3}.js", "file2.js");        // → true
rematch("file{01..03}.js", "file01.js");     // → true

// Multiple patterns and negation
rematch(["*.js", "!test.js"], "file.js");    // → true
rematch(["*.js", "!file.js"], "file.js");    // → false

// Ignore option
rematch("*.js", "file.js", { ignore: "file.js" }); // → false
rematch(["*.js", "!test.js"], "test.js", { ignore: "test.js" }); // → false

// Compiled matcher
const matcher = compile("**/*.{js,ts}");
matcher("src/file.js");                      // → true
matcher("deep/nested/file.ts");              // → true

// Path normalization (for Windows paths)
rematch("src/*.js", "src\\file.js");         // → true
normalizePath("src\\file.js");               // → "src/file.js"

// Utility: escape/unescape
rematch(escapeGlob("file[1].js"), "file[1].js"); // → true
unescapeGlob("file\\[1\\].js");                // → "file[1].js"

// Utility: isStatic, scan, explode
isStatic("file.js");                         // → true
isStatic("*.js");                            // → false
scan("!src/*.js");                           // → { isGlob: true, negated: true, glob: "src/*.js" }
explode("src/file[1-3].js");                 // → { static: ["src/file"], dynamic: ["[1-3].js"] }

Playground

To test example/e-mod.ts, run:

git clone https://github.com/reliverse/rematch
cd rematch
bun i
bun dev # beginner-friendly example
bun tests # advanced test suite

Contributing

• 🧙 Star it on GitHub
• 💬 Join our Discord
• 💖 Sponsor @blefnk

Related Reliverse Projects

• @reliverse/reglob — Tiny, fast globber
• @reliverse/relifso — Filesystem made fun again
• @reliverse/repackr — Alternative to tar/7zip

License

💖 MIT © blefnk (Nazar Kornienko)