{"_id":"@caplab/grep-search","_rev":"2-ef311d27f913fb1048b80b271b31b39e","name":"@caplab/grep-search","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@caplab/grep-search","version":"0.1.0","keywords":["search","grep","text-search","code-search","streaming","deterministic"],"author":"","license":"MIT","_id":"@caplab/grep-search@0.1.0","maintainers":[{"name":"cuongcon333","email":"cuongcon333.dev@gmail.com"}],"homepage":"https://github.com/cuonqcon333/grep-search#readme","bugs":{"url":"https://github.com/cuonqcon333/grep-search/issues"},"dist":{"shasum":"593c4c84b117d28186837a29a0591591d6a7d6b3","tarball":"https://registry.npmjs.org/@caplab/grep-search/-/grep-search-0.1.0.tgz","fileCount":84,"integrity":"sha512-O0AYsT9htK1QVERMSPXfCX6UjCKvziMVTA/8QbGeSXAUHr4BrodxqJXzCENXK+VgtVkv6JQY+usfNsfZ7LK9qw==","signatures":[{"sig":"MEYCIQDB+aPrkyuv8NOlGJbwsCrKmmD0JCR6F+7wS9HuXGbGVAIhAMjBaK9xk86X/hVWJuMX5f0PHw3yA9U/iJlViBmQUc3B","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":86750},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"dcadae8f2715f1820a4b76f2f9b31280039f0ee1","scripts":{"dev":"tsc --watch","test":"vitest","build":"tsc","prepack":"npm run build","test:coverage":"vitest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"cuongcon333","email":"cuongcon333.dev@gmail.com"},"repository":{"url":"git+https://github.com/cuonqcon333/grep-search.git","type":"git"},"_npmVersion":"10.8.2","description":"Deterministic streaming text search engine with accurate line/column mapping","directories":{},"_nodeVersion":"20.20.2","dependencies":{"ignore":"^5.3.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.2.0","typescript":"^5.3.3","@types/node":"^20.11.0","@vitest/coverage-v8":"^1.2.0"},"_npmOperationalInternal":{"tmp":"tmp/grep-search_0.1.0_1778922991934_0.8492121568705819","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@caplab/grep-search","version":"0.2.0","description":"Deterministic streaming text search engine with accurate line/column mapping","type":"module","main":"./dist/cjs/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/cjs/index.d.ts","default":"./dist/cjs/index.js"}}},"scripts":{"build":"npm run build:esm && npm run build:cjs","build:esm":"tsc -p tsconfig.esm.json","build:cjs":"tsc -p tsconfig.cjs.json","test":"vitest","test:coverage":"vitest --coverage","dev":"tsc --watch","prepublishOnly":"npm run build","prepack":"npm run build"},"keywords":["search","grep","text-search","code-search","streaming","deterministic"],"author":"","license":"MIT","repository":{"type":"git","url":"git+https://github.com/cuonqcon333/grep-search.git"},"publishConfig":{"access":"public"},"devDependencies":{"@types/node":"^20.11.0","@vitest/coverage-v8":"^1.2.0","typescript":"^5.3.3","vitest":"^1.2.0"},"dependencies":{"ignore":"^5.3.0"},"engines":{"node":">=20.0.0"},"_id":"@caplab/grep-search@0.2.0","gitHead":"8ad44862a2b41c300ac10436e143bc48aa4f96ac","bugs":{"url":"https://github.com/cuonqcon333/grep-search/issues"},"homepage":"https://github.com/cuonqcon333/grep-search#readme","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-yIiWuDXZgTMZP6iSEdq7Rxhf1uNwZh+2fmne2mpTD4WVd+oNW1sr2eFgbm2Xgnl/daUSIXx8Nffwypi3u+zP/w==","shasum":"ec9a4e93e5630c04d89a32c58d76f1d1cc8a099a","tarball":"https://registry.npmjs.org/@caplab/grep-search/-/grep-search-0.2.0.tgz","fileCount":165,"unpackedSize":170124,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDd8fQ7rqD+OX2cVOQSiANXHoqmjbTuJvwb6Py91NRiBQIhAKcCEMCYUjtCtod+VBRZCvkNadPR3ZMSKeuFVJGqzdIb"}]},"_npmUser":{"name":"cuongcon333","email":"cuongcon333.dev@gmail.com"},"directories":{},"maintainers":[{"name":"cuongcon333","email":"cuongcon333.dev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/grep-search_0.2.0_1778924560547_0.6715656215472494"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-16T09:16:31.827Z","modified":"2026-05-16T09:42:40.856Z","0.1.0":"2026-05-16T09:16:32.081Z","0.2.0":"2026-05-16T09:42:40.728Z"},"bugs":{"url":"https://github.com/cuonqcon333/grep-search/issues"},"license":"MIT","homepage":"https://github.com/cuonqcon333/grep-search#readme","keywords":["search","grep","text-search","code-search","streaming","deterministic"],"repository":{"type":"git","url":"git+https://github.com/cuonqcon333/grep-search.git"},"description":"Deterministic streaming text search engine with accurate line/column mapping","maintainers":[{"name":"cuongcon333","email":"cuongcon333.dev@gmail.com"}],"readme":"\n\n\n \n ![\"npm](\"https://badge.fury.io/js/@caplab%2Fgrep-search.svg\")
\n \n \n ![\"license\"](\"https://img.shields.io/badge/License-MIT-yellow.svg\")
\n \n
\n\n\nA fast, deterministic text search engine for codebases. Think of it as a modern, streaming `grep` built for AI agents and developers.\n\n## Overview\n\n`@caplab/grep-search` is a pure JavaScript/TypeScript search engine designed for:\n- AI agents requiring deterministic, reproducible results\n- Code search with precise line/column offsets\n- Streaming architecture for memory-safe large repository searches\n- Encoding-safe processing (UTF-8, UTF-16 LE/BE, BOM handling)\n\n## Why use this?\n\n- **Streaming**: Search large files without loading everything into memory\n- **Accurate**: Get precise line/column numbers for every match\n- **Deterministic**: Same search always returns the same results\n- **Cross-platform**: Works on Windows, Linux, and macOS\n- **TypeScript**: Full type safety and modern async API\n- **Encoding-safe**: Handles UTF-8, UTF-16 LE/BE with BOM detection\n\n## Installation\n\n```bash\nnpm install @caplab/grep-search\n```\n\n## Quick Start\n\n### ESM (ECMAScript Modules)\n\n```javascript\nimport { grepSearch } from '@caplab/grep-search';\n\n// Search for \"const\" in TypeScript files\nfor await (const match of grepSearch({\n cwd: './my-project',\n query: 'const',\n extensions: ['ts', 'js'],\n})) {\n console.log(`${match.file}:${match.line}:${match.column} - ${match.text}`);\n}\n```\n\n### CommonJS\n\n```javascript\nconst { grepSearch } = require('@caplab/grep-search');\n\n// Search for \"const\" in TypeScript files\n(async () => {\n for await (const match of grepSearch({\n cwd: './my-project',\n query: 'const',\n extensions: ['ts', 'js'],\n })) {\n console.log(`${match.file}:${match.line}:${match.column} - ${match.text}`);\n }\n})();\n```\n\n**Output:**\n```\nsrc/utils.ts:10:0 - const\nsrc/api.ts:64:2 - const\nsrc/config.ts:87:4 - const\n```\n\n## Requirements\n\n- Node.js >= 20.0.0\n- Supports both ESM and CommonJS\n\n## Common Use Cases\n\n### Find all function declarations\n\n```javascript\nimport { grepSearch } from '@caplab/grep-search';\n\nfor await (const match of grepSearch({\n cwd: './my-project',\n query: 'function',\n extensions: ['ts', 'js'],\n})) {\n console.log(`${match.file}:${match.line} - ${match.text.trim()}`);\n}\n```\n\n### Search with regex\n\n```javascript\nimport { grepSearch } from '@caplab/grep-search';\n\nfor await (const match of grepSearch({\n cwd: './my-project',\n query: 'const\\\\s+\\\\w+\\\\s*=',\n regex: true,\n extensions: ['ts'],\n})) {\n console.log(`${match.file}:${match.line} - ${match.text}`);\n}\n```\n\n### Case-insensitive search\n\n```javascript\nimport { grepSearch } from '@caplab/grep-search';\n\nfor await (const match of grepSearch({\n cwd: './my-project',\n query: 'useeffect',\n caseSensitive: false,\n extensions: ['ts', 'tsx'],\n})) {\n console.log(`${match.file}:${match.line} - ${match.text}`);\n}\n```\n\n### Whole word matching\n\n```javascript\nimport { grepSearch } from '@caplab/grep-search';\n\nfor await (const match of grepSearch({\n cwd: './my-project',\n query: 'const',\n wholeWord: true,\n extensions: ['ts', 'js'],\n})) {\n console.log(`${match.file}:${match.line} - ${match.text}`);\n}\n```\n\n### Get context around matches\n\n```javascript\nimport { grepSearch } from '@caplab/grep-search';\n\nfor await (const match of grepSearch({\n cwd: './my-project',\n query: 'export',\n extensions: ['ts'],\n beforeContext: 2,\n afterContext: 2,\n})) {\n console.log(`\\n${match.file}:${match.line}`);\n if (match.before) console.log('Before:', match.before.join('\\n'));\n console.log('Match:', match.text);\n if (match.after) console.log('After:', match.after.join('\\n'));\n}\n```\n\n## API Reference\n\n### Search Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `cwd` | string | required | Directory to search |\n| `query` | string | required | Text or pattern to find |\n| `regex` | boolean | false | Use regex pattern |\n| `wholeWord` | boolean | false | Match whole words only |\n| `caseSensitive` | boolean | false | Case-sensitive search |\n| `multiline` | boolean | false | Enable multiline patterns |\n| `extensions` | string[] | all | File extensions to include |\n| `ignore` | string[] | none | Ignore patterns (gitignore-style) |\n| `maxDepth` | number | none | Max directory depth |\n| `beforeContext` | number | 0 | Lines before match |\n| `afterContext` | number | 0 | Lines after match |\n| `maxResults` | number | none | Max results to return |\n| `maxConcurrency` | number | 10 | Max concurrent file operations |\n| `useCache` | boolean | true | Enable caching |\n| `cacheTTL` | number | 300000 | Cache TTL in ms |\n| `cacheMaxSize` | number | 1000 | Max cache size |\n\n### Match Result\n\n```javascript\n{\n file: 'src/api.ts', // File path\n line: 63, // Line number (1-indexed)\n column: 0, // Column number (0-indexed)\n endLine: 63,\n endColumn: 8,\n byteStart: 1234, // Byte offset in file\n byteEnd: 1242,\n charStart: 1234, // Character offset\n charEnd: 1242,\n text: 'function', // Matched text\n match: 'function',\n before: ['// comment'], // Context before\n after: [' const x = 1;'], // Context after\n hash: 'abc123...' // Stable hash\n}\n```\n\n### `grepSearch(options: SearchQuery): AsyncGenerator`\n\nMain search function. Returns an async generator that yields search matches.\n\n## Features\n\n### Core Capabilities\n\n- **Streaming**: Memory-safe processing of large files\n- **Deterministic**: Same input always produces same output\n- **Encoding-safe**: UTF-8, UTF-16 LE/BE, BOM handling\n- **Accurate**: Precise line/column and byte/char mapping\n- **Cross-platform**: Works on Windows, Linux, macOS\n- **Async**: Modern async generator API\n- **Caching**: Built-in file and line map caching\n- **Concurrent**: Configurable concurrent file operations\n\n### Search Modes\n\n- **Literal search**: Exact string matching\n- **Regex search**: Full JavaScript regex support\n- **Whole word**: Boundary-aware matching\n- **Case insensitive**: Case folding support\n- **Multiline**: Cross-line pattern matching\n\n## Global Invariants\n\nThese invariants hold at all times:\n\n1. **Match Uniqueness**: A match is defined only once (no duplicates allowed)\n2. **Line/Column Space**: Line/column maps to decoded string space (NOT raw bytes)\n3. **Byte Offset Space**: Byte offset maps to original file space (for stable references)\n4. **Determinism**: Output is deterministic across runs (same input → same output)\n5. **Boundary Safety**: No chunk boundary affects correctness (no missed/duplicate matches)\n\n## Deterministic Ordering\n\nResults are sorted in this order:\n1. File path (ASC)\n2. Line number (ASC)\n3. Column number (ASC)\n4. Byte offset (ASC) - **Critical tie-breaker**\n\n## Performance\n\n- Line indexing: 30k lines in ~10ms\n- Literal matching: 10k occurrences in ~1.5ms\n- Regex matching: 10k occurrences in ~4.5ms\n- Hash generation: 85k ops/sec\n- File hash cache: 20k ops/sec\n- Line map cache: 1.7M ops/sec\n\n## Testing\n\n```bash\ncd active/grep-search\nnpm run build\nnode test-script.mjs\n```\n\nThis tests the package on a real project and works on both Windows and Linux.\n\n## Development\n\n### Setup\n\n```bash\n# Install dependencies\nnpm install\n\n# Build TypeScript\nnpm run build\n\n# Run tests\nnpm test\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Watch mode\nnpm run dev\n```\n\n### Project Structure\n\n```\n.\n├── src/ # Source code\n│ ├── core/ # Core search engine\n│ ├── fs/ # File system utilities\n│ ├── matcher/ # Pattern matchers\n│ ├── parser/ # Encoding and parsing\n│ ├── cache/ # Caching utilities\n│ ├── output/ # Output formatting\n│ ├── patch/ # Patch application\n│ ├── reference/ # Reference finding\n│ ├── replace/ # Replace engine\n│ ├── symbol/ # Symbol search\n│ ├── ast/ # AST integration\n│ ├── utils/ # Utilities\n│ └── types/ # TypeScript types\n├── tests/ # Test files\n├── benchmarks/ # Performance benchmarks\n├── docs/ # Documentation\n├── dist/ # Compiled output\n└── package.json\n```\n\n## Contributing\n\nThis is a core infrastructure package. Contributions should focus on:\n- Correctness improvements\n- Determinism guarantees\n- Edge case handling\n- Performance optimizations\n\nPlease ensure all tests pass and coverage remains ≥ 90%.\n\n### Commit Guidelines\n\n- Use conventional commit format (feat:, fix:, docs:, etc.)\n- Add tests for new features\n- Update documentation as needed\n- Ensure TypeScript compilation succeeds\n- Run tests before pushing\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Links\n\n- [API Documentation](docs/API.md)\n- [GitHub Repository](https://github.com/cuonqcon333/grep-search)\n\n## Support\n\nFor issues, questions, or contributions, please visit our GitHub repository.\n","readmeFilename":"README.md"}