Node.js Native SDK (NAPI)
Relevant source files
The following files were used as context for generating this wiki page:
The Node.js Native SDK provides high-performance bindings for the chkpt filesystem checkpoint engine, allowing JavaScript and TypeScript applications to interact directly with the core Rust implementation. It utilizes N-API (via napi-rs) to expose core operations such as workspace scanning, snapshot management, and content-addressed storage utilities.
The SDK serves as the foundation for other Node-based interfaces in the project, including the MCP (Model Context Protocol) server and the Claude Code plugin. It ensures that heavy computational tasks—like XXH3-128 hashing, LZ4 compression, and SQLite-based indexing—are executed at native speeds while maintaining a user-friendly asynchronous API for Node.js developers.
Sources: crates/chkpt-napi/README.md:1-5, crates/chkpt-napi/package.json:2-10, README.md:16-25
Architecture and Data Flow
The NAPI implementation acts as a translation layer between the Node.js runtime and the chkpt-core Rust library. It converts JavaScript objects and buffers into native Rust types, executes core logic, and returns serialized results back to the event loop.
The diagram above illustrates the request-response cycle where the NAPI layer manages the transition between JavaScript's asynchronous model and Rust's internal operations.
Sources: crates/chkpt-napi/src/ops.rs:17-30, crates/chkpt-napi/src/store.rs:77-84, README.md:86-95
Core Operations API
The SDK exposes several high-level asynchronous functions that map directly to the chkpt command-line interface capabilities. These functions handle the orchestration of scanning, saving, and restoring workspace states.
Snapshot Management
| Function | Parameters | Return Type | Description |
|---|---|---|---|
save | path, msg?, deps? | Promise<JsSaveResult> | Creates a new content-addressed checkpoint of the workspace. |
list | path, limit? | Promise<Array<Snapshot>> | Retrieves metadata for existing checkpoints, sorted newest first. |
restore | path, id, dryRun? | Promise<JsRestoreResult> | Reverts workspace to a specific state. Supports "latest" alias. |
deleteSnapshot | path, id | Promise<void> | Removes a specific checkpoint and its associated metadata. |
Sources: crates/chkpt-napi/src/ops.rs:17-118, crates/chkpt-napi/test/ops.spec.ts:70-78
Low-Level Utilities
In addition to high-level operations, the SDK provides access to internal utilities for hashing and tree manipulation.
blobHash(content: Buffer): Generates an XXH3-128 content hash string for a given buffer.getProjectId(path: String): Deterministically generates a 16-character hex string representing a workspace.treeBuild(dir, entries): Construct a new tree structure from a list of directory entries.
Sources: crates/chkpt-napi/src/store.rs:37-40, crates/chkpt-napi/src/lib.rs:20-25, crates/chkpt-napi/test/config.spec.ts:8-12
Data Structures
The SDK uses specialized TypeScript-compatible objects to communicate results and status from the native layer.
Save and Restore Results
The JsSaveResult and JsRestoreResult structures provide statistics about the operation's impact on the filesystem.
// crates/chkpt-napi/src/ops.rs:11-15
#[napi(object)]
pub struct JsSaveResult {
pub snapshot_id: String,
pub total_files: i64,
pub total_bytes: i64,
pub new_objects: i64,
}
// crates/chkpt-napi/src/ops.rs:90-96
#[napi(object)]
pub struct JsRestoreResult {
pub snapshot_id: String,
pub files_added: i64,
pub files_changed: i64,
pub files_removed: i64,
pub files_unchanged: i64,
}
Sources: crates/chkpt-napi/src/ops.rs:11-15, crates/chkpt-napi/src/ops.rs:90-96
Cross-Platform Support
The NAPI package is distributed with pre-built binaries for multiple platforms to avoid requiring a Rust toolchain on the consumer's machine.
| Target Triple | Platform Label | Binary Extension |
|---|---|---|
aarch64-apple-darwin | darwin-arm64 | .node / .dylib |
x86_64-apple-darwin | darwin-x64 | .node / .dylib |
x86_64-unknown-linux-gnu | linux-x64-gnu | .node / .so |
x86_64-pc-windows-msvc | win32-x64-msvc | .node / .dll |
Sources: crates/chkpt-napi/scripts/build-all.sh:16-22, crates/chkpt-napi/package.json:11-19
Build and Deployment
The build process involves cross-compiling the Rust source into shared libraries (cdylib) and packaging them with platform-specific package.json files.
Conclusion
The Node.js Native SDK (NAPI) bridges the gap between high-level Node.js automation and the high-performance chkpt core. By exposing asynchronous bindings for snapshot creation, restoration, and workspace scanning, it enables the integration of robust filesystem protection into AI agents and developer tools while maintaining native execution speeds across macOS, Linux, and Windows.