@gfhfyjbr/grep-js

Node.js bindings for the grep crate - the same regex search library that powers ripgrep.

Fast, line-oriented regex searching with support for:

• Multi-line search
• Context lines (before/after matches)
• Binary detection
• Inverted matching
• Smart case sensitivity
• Word boundary matching

Supported Platforms

| OS | Architecture | | ------------- | -------------------------- | | Windows | x64, arm64 | | macOS | x64, arm64 (Apple Silicon) | | Linux (glibc) | x64, arm64 | | Linux (musl) | x64, arm64 |

Installation

npm install @gfhfyjbr/grep-js

Usage

ES Modules

// Import everything
import { search, RegexMatcher, Searcher } from '@gfhfyjbr/grep-js'

// Or import specific modules
import { RegexMatcher, RegexMatcherBuilder } from '@gfhfyjbr/grep-js/matcher'
import { Searcher, SearcherBuilder, BinaryDetectionMode } from '@gfhfyjbr/grep-js/searcher'

CommonJS

const { search, RegexMatcher } = require('@gfhfyjbr/grep-js')

const { RegexMatcher, RegexMatcherBuilder } = require('@gfhfyjbr/grep-js/matcher')
const { Searcher, SearcherBuilder } = require('@gfhfyjbr/grep-js/searcher')

Quick Start

import { search, searchFile, isMatch, find, findAll } from '@gfhfyjbr/grep-js'

// Search in a string
const result = search('hello\\s+\\w+', 'hello world\nhello there\ngoodbye')
console.log(result.matches)
// [
//   { lineNumber: 1, line: 'hello world\n', matches: [{ start: 0, end: 11 }] },
//   { lineNumber: 2, line: 'hello there\n', matches: [{ start: 0, end: 11 }] }
// ]

// Search in a file
const fileResult = searchFile('TODO|FIXME', './src/lib.rs')

// Quick match check
if (isMatch('error', logContent)) {
  console.log('Errors found!')
}

// Find first match
const match = find('\\d+', 'abc123def')
// { start: 3, end: 6 }

// Find all matches
const allMatches = findAll('\\d+', 'a1b2c3')
// [{ start: 1, end: 2 }, { start: 3, end: 4 }, { start: 5, end: 6 }]

Advanced Usage

RegexMatcherBuilder

import { RegexMatcherBuilder, Searcher } from '@gfhfyjbr/grep-js'

const matcher = new RegexMatcherBuilder().caseInsensitive(true).multiLine(true).word(true).build('error')

const searcher = new Searcher()
const result = searcher.searchSlice(matcher, 'ERROR: failed\nWarning: error detected')

Options

| Method | Description | | ------------------------- | ----------------------------------------------- | | caseInsensitive(bool) | Case-insensitive matching | | caseSmart(bool) | Auto case-insensitivity if pattern is lowercase | | multiLine(bool) | ^ and $ match line boundaries | | dotMatchesNewLine(bool) | . matches newlines | | word(bool) | Match only at word boundaries | | fixedStrings(bool) | Treat pattern as literal string | | wholeLine(bool) | Pattern must match entire line | | unicode(bool) | Enable Unicode support |

SearcherBuilder

import { RegexMatcher, SearcherBuilder, BinaryDetectionMode } from '@gfhfyjbr/grep-js'

const matcher = RegexMatcher.fromPattern('function\\s+\\w+')

const searcher = new SearcherBuilder()
  .lineNumber(true)
  .beforeContext(2)
  .afterContext(2)
  .binaryDetection(BinaryDetectionMode.Quit)
  .maxMatches(100)
  .build()

const result = searcher.searchPath(matcher, './src/index.ts')

for (const match of result.matches) {
  console.log(`${match.lineNumber}: ${match.line}`)
}

Options

| Method | Description | | ----------------------- | ------------------------------------ | | lineNumber(bool) | Include line numbers (default: true) | | invertMatch(bool) | Report non-matching lines | | multiLine(bool) | Enable multi-line matching | | beforeContext(n) | Lines of context before match | | afterContext(n) | Lines of context after match | | binaryDetection(mode) | Binary detection mode | | maxMatches(n) | Maximum number of matches |

Binary Detection

import { BinaryDetectionMode } from '@gfhfyjbr/grep-js'

BinaryDetectionMode.None // Search everything
BinaryDetectionMode.Quit // Stop on binary data
BinaryDetectionMode.Convert // Convert NUL bytes

Types

interface SearchResult {
  matches: SearchMatch[]
  context: SearchContext[]
  finish: SearchFinish
}

interface SearchMatch {
  lineNumber?: number
  absoluteByteOffset: number
  line: string
  bytes: Buffer
  matches: MatchRange[]
}

interface MatchRange {
  start: number
  end: number
}

Performance

Uses the same regex engine as ripgrep:

• Fast DFA-based matching
• Optimized literal string matching
• Memory-mapped file support

License

MIT