singularity-forge/native

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, adapted for GSD's Node.js runtime.

Prerequisites

• Rust (stable, 1.70+): https://rustup.rs
• Node.js (20.6+)

Build

# 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

# 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:

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