Ripgrep Node.js Wrapper

🔍 A fast and developer-friendly Node.js wrapper for ripgrep - the blazingly fast text search tool

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

``bash
npm install @agent-contrib/ripgrep


or

yarn add @agent-contrib/ripgrep

or

pnpm add @agent-contrib/ripgrep
`

Quick Start

$3

`typescript
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});
});
`

$3

`typescript
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);
`

$3

`typescript
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

$3

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

`typescript
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

`typescript
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
- Streaming: Promise>

Examples

$3

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

$3

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

$3

`typescript
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

$3

`bash


Clone the repository

git clone https://github.com/agent-contrib/ripgrep.git
cd ripgrep

Install dependencies

npm install

or

pnpm install
`

$3

`bash
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
`

$3

`bash


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.

$3

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