Ripgrep Node.js Wrapper

Features

• 🚀 Blazingly Fast: Powered by ripgrep, one of the fastest text search tools available
• 🔄 Streaming Support: Real-time results with async iterators
• 🎯 TypeScript First: Full TypeScript support with comprehensive type definitions
• 🎨 Developer Friendly: Simple, intuitive API with sensible defaults
• 📁 File Type Filtering: Built-in support for common file patterns
• 🔍 Regex Support: Full regular expression search capabilities
• ⚡ Zero Configuration: Works out of the box with smart defaults

Installation

npm install @agent-contrib/ripgrep
# or
yarn add @agent-contrib/ripgrep
# or
pnpm add @agent-contrib/ripgrep

Quick Start

Basic Search

import { searchCode } from '@agent-contrib/ripgrep';

// Search for "function" in current directory
const results = await searchCode('function', process.cwd());

console.log(`Found ${results.length} matches:`);
results.forEach(result => {
  console.log(`${result.file}:${result.line} - ${result.text}`);
});

Advanced Search with Options

import { searchCode, SearchOptions } from '@agent-contrib/ripgrep';

const options: SearchOptions = {
  regex: true,                                    // Enable regex search
  fileTypes: ['*.ts', '*.js', '*.tsx', '*.jsx'], // Target specific file types
  maxResults: 100,                               // Limit results
  caseSensitive: false,                          // Case-insensitive search
};

const results = await searchCode('export.*function', './src', options);

Streaming Search (Real-time Results)

import { searchCode } from '@agent-contrib/ripgrep';

// Enable streaming for real-time results
const searchStream = await searchCode('TODO', './src', { stream: true });

for await (const result of searchStream) {
  console.log(`Found: ${result.file}:${result.line} - ${result.text}`);
}

API Reference

searchCode(keyword, cwd, options?)

Search for text patterns in files using ripgrep.

Parameters

• keyword (string): The text or regex pattern to search for
• cwd (string): Directory path to search in
• options (SearchOptions, optional): Search configuration

SearchOptions

interface SearchOptions {
  /** Whether to treat the keyword as a regular expression */
  regex?: boolean;
  /** File type patterns to include (e.g., ['*.js', '*.ts']) */
  fileTypes?: string[];
  /** Maximum number of results to return */
  maxResults?: number;
  /** Whether to enable case-sensitive search */
  caseSensitive?: boolean;
  /** Whether to enable streaming results */
  stream?: boolean;
}

SearchResult

interface SearchResult {
  /** Relative file path */
  file: string;
  /** Line number (1-based) */
  line: number;
  /** Matched line content */
  text: string;
  /** Column position of the match */
  column?: number;
}

Return Value

• Non-streaming: Promise<SearchResult[]>
• Streaming: Promise<AsyncIterable<SearchResult>>

Examples

Search for React Components

const components = await searchCode('export.*Component', './src', {
  regex: true,
  fileTypes: ['*.tsx', '*.jsx'],
  maxResults: 50
});

Find TODO Comments

const todos = await searchCode('TODO|FIXME|HACK', '.', {
  regex: true,
  fileTypes: ['*.ts', '*.js', '*.tsx', '*.jsx'],
  caseSensitive: false
});

Search with Streaming (Large Codebases)

const searchStream = await searchCode('import.*from', './src', {
  stream: true,
  fileTypes: ['*.ts', '*.tsx']
});

let count = 0;
for await (const result of searchStream) {
  console.log(`${++count}. ${result.file}:${result.line}`);
  if (count >= 10) break; // Limit output
}

Development

Setup

# Clone the repository
git clone https://github.com/agent-contrib/ripgrep.git
cd ripgrep

# Install dependencies
npm install
# or
pnpm install

Available Scripts

npm run dev         # Development mode with watch
npm run build       # Build for production
npm run test        # Run tests
npm run test:watch  # Run tests in watch mode
npm run test:coverage # Generate coverage report
npm run lint        # Lint code
npm run lint:fix    # Fix linting issues

Running Examples

# Simple search example
npm run example:simple [keyword]

# Advanced example with streaming
npm run example:basic [keyword]

Why Ripgrep?

Ripgrep is a line-oriented search tool that recursively searches your current directory for a regex pattern. It's incredibly fast and has excellent support for:

• Speed: Often faster than grep, ag, and ack
• Unicode Support: Full Unicode support including multi-byte characters
• Gitignore Integration: Automatically respects .gitignore files
• File Type Detection: Smart file type filtering
• Large File Handling: Efficiently handles large files and directories

Performance

This wrapper maintains ripgrep's performance characteristics while providing a convenient JavaScript API. For large codebases, consider using the streaming API to process results incrementally.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Guidelines

1. Ensure TypeScript types are properly defined
2. Add tests for new functionality
3. Update documentation for API changes
4. Follow conventional commit standards

License

MIT © ULIVZ

Related

• ripgrep - The underlying search tool
• @lvce-editor/ripgrep - Ripgrep binaries for Node.js