81 lines
1.8 KiB
Markdown
81 lines
1.8 KiB
Markdown
|
# GSD Native Engine
|
||
|
|
|
||
|
|
Rust N-API addon providing high-performance native modules for GSD.
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
```
|
||
|
|
JS (packages/native) -> N-API -> Rust crates
|
||
|
|
├── engine/ (N-API bindings, cdylib)
|
||
|
|
└── grep/ (ripgrep internals, pure Rust lib)
|
||
|
|
```
|
||
|
|
|
||
|
|
Inspired by [Oh My Pi's pi-natives](https://github.com/can1357/oh-my-pi), adapted for GSD's Node.js runtime.
|
||
|
|
|
||
|
|
## Prerequisites
|
||
|
|
|
||
|
|
- **Rust** (stable, 1.70+): https://rustup.rs
|
||
|
|
- **Node.js** (20.6+)
|
||
|
|
|
||
|
|
## Build
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Release build (optimized)
|
||
|
|
npm run build:native
|
||
|
|
|
||
|
|
# Debug build (fast compile, no optimizations)
|
||
|
|
npm run build:native:dev
|
||
|
|
```
|
||
|
|
|
||
|
|
The build script compiles the Rust code and copies the `.node` shared library to `native/addon/`.
|
||
|
|
|
||
|
|
## Test
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Rust unit tests
|
||
|
|
cd native && cargo test
|
||
|
|
|
||
|
|
# Node.js integration tests
|
||
|
|
npm run test:native
|
||
|
|
```
|
||
|
|
|
||
|
|
## Modules
|
||
|
|
|
||
|
|
### grep
|
||
|
|
|
||
|
|
Ripgrep-backed regex search using the `grep-regex`, `grep-searcher`, and `grep-matcher` crates.
|
||
|
|
|
||
|
|
**Functions:**
|
||
|
|
|
||
|
|
- `search(content, options)` — Search in-memory Buffer/Uint8Array content
|
||
|
|
- `grep(options)` — Search files on disk with glob filtering and .gitignore support
|
||
|
|
|
||
|
|
**TypeScript usage:**
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
import { grep, searchContent } from "@gsd/native";
|
||
|
|
|
||
|
|
// Search files
|
||
|
|
const result = grep({
|
||
|
|
pattern: "TODO",
|
||
|
|
path: "./src",
|
||
|
|
glob: "*.ts",
|
||
|
|
ignoreCase: true,
|
||
|
|
maxCount: 100,
|
||
|
|
});
|
||
|
|
|
||
|
|
// Search content
|
||
|
|
const contentResult = searchContent(Buffer.from(fileContent), {
|
||
|
|
pattern: "function\\s+\\w+",
|
||
|
|
contextBefore: 2,
|
||
|
|
contextAfter: 2,
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
## Adding New Modules
|
||
|
|
|
||
|
|
1. Create a new crate in `native/crates/` (pure Rust library)
|
||
|
|
2. Add N-API bindings in `native/crates/engine/src/`
|
||
|
|
3. Add TypeScript wrapper in `packages/native/src/`
|
||
|
|
4. Add the crate to `engine/Cargo.toml` dependencies
|