nanograph-db 0.8.0

package/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "nanograph-ts"
+version = "0.8.0"
+edition = "2024"
+description = "NanoGraph TypeScript/Node.js SDK via napi-rs"
+repository = "https://github.com/aaltshuler/nanograph"
+license = "MIT"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+nanograph = { path = "../nanograph", version = "0.8.0" }
+napi = { workspace = true }
+napi-derive = { workspace = true }
+tokio = { workspace = true }
+serde_json = { workspace = true }
+
+[build-dependencies]
+napi-build = "2"

package/build.rs

@@ -0,0 +1,5 @@
+extern crate napi_build;
+
+fn main() {
+    napi_build::setup();
+}

package/index.d.ts

@@ -0,0 +1,126 @@
+/* nanograph-db — TypeScript type definitions (hand-written) */
+
+export interface PropDef {
+  name: string;
+  propId: number;
+  type: string;
+  nullable: boolean;
+  list?: boolean;
+  key?: boolean;
+  unique?: boolean;
+  index?: boolean;
+  enumValues?: string[];
+  embedSource?: string;
+}
+
+export interface NodeType {
+  name: string;
+  typeId: number;
+  properties: PropDef[];
+}
+
+export interface EdgeType {
+  name: string;
+  srcType: string;
+  dstType: string;
+  typeId: number;
+  properties: PropDef[];
+}
+
+export interface DescribeResult {
+  nodeTypes: NodeType[];
+  edgeTypes: EdgeType[];
+}
+
+export interface CheckResult {
+  name: string;
+  kind: "read" | "mutation";
+  status: "ok" | "error";
+  error?: string;
+}
+
+export interface MutationResult {
+  affectedNodes: number;
+  affectedEdges: number;
+}
+
+export interface CompactOptions {
+  targetRowsPerFragment?: number;
+  materializeDeletions?: boolean;
+  materializeDeletionsThreshold?: number;
+}
+
+export interface CompactResult {
+  datasetsConsidered: number;
+  datasetsCompacted: number;
+  fragmentsRemoved: number;
+  fragmentsAdded: number;
+  filesRemoved: number;
+  filesAdded: number;
+  manifestCommitted: boolean;
+}
+
+export interface CleanupOptions {
+  retainTxVersions?: number;
+  retainDatasetVersions?: number;
+}
+
+export interface CleanupResult {
+  txRowsRemoved: number;
+  txRowsKept: number;
+  cdcRowsRemoved: number;
+  cdcRowsKept: number;
+  datasetsCleaned: number;
+  datasetOldVersionsRemoved: number;
+  datasetBytesRemoved: number;
+}
+
+export interface DoctorResult {
+  healthy: boolean;
+  issues: string[];
+  warnings: string[];
+  manifestDbVersion: number;
+  datasetsChecked: number;
+  txRows: number;
+  cdcRows: number;
+}
+
+export class Database {
+  /** Create a new database from a schema string. */
+  static init(dbPath: string, schemaSource: string): Promise<Database>;
+
+  /** Open an existing database. */
+  static open(dbPath: string): Promise<Database>;
+
+  /** Load JSONL data into the database. */
+  load(dataSource: string, mode: "overwrite" | "append" | "merge"): Promise<void>;
+
+  /**
+   * Execute a named query from query source text.
+   * Read queries return an array of row objects.
+   * Mutation queries return `{ affectedNodes, affectedEdges }`.
+   */
+  run(
+    querySource: string,
+    queryName: string,
+    params?: Record<string, unknown>,
+  ): Promise<Record<string, unknown>[] | MutationResult>;
+
+  /** Typecheck all queries against the database schema. */
+  check(querySource: string): Promise<CheckResult[]>;
+
+  /** Return schema introspection. */
+  describe(): Promise<DescribeResult>;
+
+  /** Compact Lance datasets to reduce fragmentation. */
+  compact(options?: CompactOptions): Promise<CompactResult>;
+
+  /** Clean up old dataset versions and prune logs. */
+  cleanup(options?: CleanupOptions): Promise<CleanupResult>;
+
+  /** Run health checks on the database. */
+  doctor(): Promise<DoctorResult>;
+
+  /** Close the database, releasing resources. */
+  close(): Promise<void>;
+}

package/index.js

@@ -0,0 +1,128 @@
+/* eslint-disable */
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 12, is-linux-musl is not available so check /usr/bin/ldd
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'darwin':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'nanograph.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./nanograph.darwin-x64.node')
+          } else {
+            nativeBinding = require('nanograph-db-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'nanograph.darwin-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./nanograph.darwin-arm64.node')
+          } else {
+            nativeBinding = require('nanograph-db-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          throw new Error('musl libc is not supported')
+        } else {
+          localFileExisted = existsSync(join(__dirname, 'nanograph.linux-x64-gnu.node'))
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./nanograph.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('nanograph-db-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          throw new Error('musl libc is not supported')
+        } else {
+          localFileExisted = existsSync(join(__dirname, 'nanograph.linux-arm64-gnu.node'))
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./nanograph.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('nanograph-db-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'nanograph.win32-x64-msvc.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./nanograph.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('nanograph-db-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { Database } = nativeBinding
+
+module.exports.Database = Database

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "nanograph-db",
+  "version": "0.8.0",
+  "description": "NanoGraph — embedded typed property graph DB for TypeScript/Node.js",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "napi": {
+    "binaryName": "nanograph",
+    "targets": [
+      "aarch64-apple-darwin",
+      "x86_64-apple-darwin",
+      "x86_64-unknown-linux-gnu",
+      "aarch64-unknown-linux-gnu",
+      "x86_64-pc-windows-msvc"
+    ]
+  },
+  "scripts": {
+    "install": "napi build --platform --js index.js --release",
+    "build": "napi build --platform --js index.js --release",
+    "build:debug": "napi build --platform --js index.js",
+    "test": "node --test __test__/index.spec.mjs"
+  },
+  "dependencies": {
+    "@napi-rs/cli": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aaltshuler/nanograph"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src/",
+    "build.rs",
+    "Cargo.toml"
+  ]
+}

package/src/convert.rs

@@ -0,0 +1,461 @@
+use nanograph::ParamMap;
+use nanograph::json_output::{JS_MAX_SAFE_INTEGER_U64, is_js_safe_integer_i64};
+use nanograph::query::ast::{Literal, Param};
+use nanograph::store::database::{CleanupOptions, CompactOptions, LoadMode};
+
+fn parse_i64_param(key: &str, value: &serde_json::Value) -> napi::Result<i64> {
+    match value {
+        serde_json::Value::Number(n) => {
+            let parsed = if let Some(parsed) = n.as_i64() {
+                parsed
+            } else if let Some(parsed) = n.as_f64() {
+                if !parsed.is_finite() || parsed.fract() != 0.0 {
+                    return Err(napi::Error::from_reason(format!(
+                        "param '{}': expected integer, got number",
+                        key
+                    )));
+                }
+                if parsed < i64::MIN as f64 || parsed > i64::MAX as f64 {
+                    return Err(napi::Error::from_reason(format!(
+                        "param '{}': integer {} is outside i64 range",
+                        key, parsed
+                    )));
+                }
+                parsed as i64
+            } else {
+                return Err(napi::Error::from_reason(format!(
+                    "param '{}': expected integer, got number",
+                    key
+                )));
+            };
+            if !is_js_safe_integer_i64(parsed) {
+                return Err(napi::Error::from_reason(format!(
+                    "param '{}': integer {} exceeds JS safe integer range; pass a decimal string for exact values",
+                    key, parsed
+                )));
+            }
+            Ok(parsed)
+        }
+        serde_json::Value::String(s) => s.parse::<i64>().map_err(|_| {
+            napi::Error::from_reason(format!(
+                "param '{}': expected integer string, got '{}'",
+                key, s
+            ))
+        }),
+        _ => Err(napi::Error::from_reason(format!(
+            "param '{}': expected integer, got {}",
+            key,
+            json_type_name(value)
+        ))),
+    }
+}
+
+fn parse_u64_param(key: &str, value: &serde_json::Value) -> napi::Result<u64> {
+    match value {
+        serde_json::Value::Number(n) => {
+            let parsed = if let Some(parsed) = n.as_u64() {
+                parsed
+            } else if let Some(parsed) = n.as_f64() {
+                if !parsed.is_finite() || parsed.fract() != 0.0 || parsed < 0.0 {
+                    return Err(napi::Error::from_reason(format!(
+                        "param '{}': expected unsigned integer, got number",
+                        key
+                    )));
+                }
+                if parsed > u64::MAX as f64 {
+                    return Err(napi::Error::from_reason(format!(
+                        "param '{}': integer {} is outside u64 range",
+                        key, parsed
+                    )));
+                }
+                parsed as u64
+            } else {
+                return Err(napi::Error::from_reason(format!(
+                    "param '{}': expected unsigned integer, got number",
+                    key
+                )));
+            };
+            if parsed > JS_MAX_SAFE_INTEGER_U64 {
+                return Err(napi::Error::from_reason(format!(
+                    "param '{}': integer {} exceeds JS safe integer range; pass a decimal string for exact values",
+                    key, parsed
+                )));
+            }
+            Ok(parsed)
+        }
+        serde_json::Value::String(s) => s.parse::<u64>().map_err(|_| {
+            napi::Error::from_reason(format!(
+                "param '{}': expected unsigned integer string, got '{}'",
+                key, s
+            ))
+        }),
+        _ => Err(napi::Error::from_reason(format!(
+            "param '{}': expected unsigned integer, got {}",
+            key,
+            json_type_name(value)
+        ))),
+    }
+}
+
+fn parse_i32_param(key: &str, value: &serde_json::Value) -> napi::Result<i32> {
+    let parsed = parse_i64_param(key, value)?;
+    i32::try_from(parsed).map_err(|_| {
+        napi::Error::from_reason(format!(
+            "param '{}': value {} exceeds I32 range",
+            key, parsed
+        ))
+    })
+}
+
+/// Convert a JS params object to a ParamMap, using query param type declarations
+/// for type-guided conversion.
+pub fn js_object_to_param_map(
+    params: Option<&serde_json::Value>,
+    query_params: &[Param],
+) -> napi::Result<ParamMap> {
+    let mut map = ParamMap::new();
+    let obj = match params {
+        Some(serde_json::Value::Object(obj)) => obj,
+        Some(serde_json::Value::Null) | None => return Ok(map),
+        Some(other) => {
+            return Err(napi::Error::from_reason(format!(
+                "params must be an object, got {}",
+                json_type_name(other)
+            )));
+        }
+    };
+
+    for (key, value) in obj {
+        let decl = query_params.iter().find(|p| p.name == *key);
+        let lit = if let Some(decl) = decl {
+            convert_with_type_hint(key, value, &decl.type_name)?
+        } else {
+            convert_inferred(key, value)?
+        };
+        map.insert(key.clone(), lit);
+    }
+    Ok(map)
+}
+
+/// Convert a JS value to a Literal using the declared query param type.
+fn convert_with_type_hint(
+    key: &str,
+    value: &serde_json::Value,
+    type_name: &str,
+) -> napi::Result<Literal> {
+    match type_name {
+        "String" => match value {
+            serde_json::Value::String(s) => Ok(Literal::String(s.clone())),
+            other => Err(napi::Error::from_reason(format!(
+                "param '{}': expected string, got {}",
+                key,
+                json_type_name(other)
+            ))),
+        },
+        "I32" => {
+            let n = parse_i32_param(key, value)?;
+            Ok(Literal::Integer(n as i64))
+        }
+        "I64" => {
+            let n = parse_i64_param(key, value)?;
+            Ok(Literal::Integer(n))
+        }
+        "U32" => {
+            let n = parse_u64_param(key, value)?;
+            if n > u32::MAX as u64 {
+                return Err(napi::Error::from_reason(format!(
+                    "param '{}': value {} exceeds U32 range",
+                    key, n
+                )));
+            }
+            Ok(Literal::Integer(n as i64))
+        }
+        "U64" => {
+            let n = parse_u64_param(key, value)?;
+            let n = i64::try_from(n).map_err(|_| {
+                napi::Error::from_reason(format!(
+                    "param '{}': value {} exceeds current engine range for U64 parameters (max {})",
+                    key,
+                    n,
+                    i64::MAX
+                ))
+            })?;
+            Ok(Literal::Integer(n))
+        }
+        "F32" | "F64" => {
+            let f = value.as_f64().ok_or_else(|| {
+                napi::Error::from_reason(format!(
+                    "param '{}': expected float, got {}",
+                    key,
+                    json_type_name(value)
+                ))
+            })?;
+            Ok(Literal::Float(f))
+        }
+        "Bool" => {
+            let b = value.as_bool().ok_or_else(|| {
+                napi::Error::from_reason(format!(
+                    "param '{}': expected boolean, got {}",
+                    key,
+                    json_type_name(value)
+                ))
+            })?;
+            Ok(Literal::Bool(b))
+        }
+        "Date" => match value {
+            serde_json::Value::String(s) => Ok(Literal::Date(s.clone())),
+            other => Err(napi::Error::from_reason(format!(
+                "param '{}': expected date string, got {}",
+                key,
+                json_type_name(other)
+            ))),
+        },
+        "DateTime" => match value {
+            serde_json::Value::String(s) => Ok(Literal::DateTime(s.clone())),
+            other => Err(napi::Error::from_reason(format!(
+                "param '{}': expected datetime string, got {}",
+                key,
+                json_type_name(other)
+            ))),
+        },
+        other if other.starts_with("Vector(") => {
+            let expected_dim = parse_vector_dim(other).ok_or_else(|| {
+                napi::Error::from_reason(format!(
+                    "param '{}': invalid vector type '{}' (expected Vector(N))",
+                    key, other
+                ))
+            })?;
+            let items = value.as_array().ok_or_else(|| {
+                napi::Error::from_reason(format!(
+                    "param '{}': expected array for {}, got {}",
+                    key,
+                    other,
+                    json_type_name(value)
+                ))
+            })?;
+            if items.len() != expected_dim {
+                return Err(napi::Error::from_reason(format!(
+                    "param '{}': expected {} values for {}, got {}",
+                    key,
+                    expected_dim,
+                    other,
+                    items.len()
+                )));
+            }
+            let mut out = Vec::with_capacity(items.len());
+            for item in items {
+                let num = item.as_f64().ok_or_else(|| {
+                    napi::Error::from_reason(format!(
+                        "param '{}': vector element '{}' is not numeric",
+                        key, item
+                    ))
+                })?;
+                out.push(Literal::Float(num));
+            }
+            Ok(Literal::List(out))
+        }
+        _ => {
+            // Enum or unknown type — require string
+            match value {
+                serde_json::Value::String(s) => Ok(Literal::String(s.clone())),
+                other => Err(napi::Error::from_reason(format!(
+                    "param '{}': expected string for type '{}', got {}",
+                    key, type_name, json_type_name(other)
+                ))),
+            }
+        }
+    }
+}
+
+/// Infer Literal type from JS value when no type declaration is available.
+fn convert_inferred(key: &str, value: &serde_json::Value) -> napi::Result<Literal> {
+    match value {
+        serde_json::Value::String(s) => Ok(Literal::String(s.clone())),
+        serde_json::Value::Bool(b) => Ok(Literal::Bool(*b)),
+        serde_json::Value::Number(n) => {
+            if let Some(i) = n.as_i64() {
+                if !is_js_safe_integer_i64(i) {
+                    return Err(napi::Error::from_reason(format!(
+                        "param '{}': integer {} exceeds JS safe integer range; use a decimal string and a typed query parameter for exact values",
+                        key, i
+                    )));
+                }
+                Ok(Literal::Integer(i))
+            } else if let Some(u) = n.as_u64() {
+                if u > JS_MAX_SAFE_INTEGER_U64 {
+                    return Err(napi::Error::from_reason(format!(
+                        "param '{}': integer {} exceeds JS safe integer range; use a decimal string and a typed query parameter for exact values",
+                        key, u
+                    )));
+                }
+                let i = i64::try_from(u).map_err(|_| {
+                    napi::Error::from_reason(format!(
+                        "param '{}': integer {} exceeds supported range (max {})",
+                        key,
+                        u,
+                        i64::MAX
+                    ))
+                })?;
+                Ok(Literal::Integer(i))
+            } else if let Some(f) = n.as_f64() {
+                Ok(Literal::Float(f))
+            } else {
+                Err(napi::Error::from_reason(format!(
+                    "param '{}': unsupported number value",
+                    key
+                )))
+            }
+        }
+        serde_json::Value::Array(arr) => {
+            let mut items = Vec::with_capacity(arr.len());
+            for item in arr {
+                items.push(convert_inferred(key, item)?);
+            }
+            Ok(Literal::List(items))
+        }
+        serde_json::Value::Null => Err(napi::Error::from_reason(format!(
+            "param '{}': null values are not supported as query parameters",
+            key
+        ))),
+        serde_json::Value::Object(_) => Err(napi::Error::from_reason(format!(
+            "param '{}': object values are not supported as query parameters",
+            key
+        ))),
+    }
+}
+
+fn parse_vector_dim(type_name: &str) -> Option<usize> {
+    let dim = type_name
+        .strip_prefix("Vector(")?
+        .strip_suffix(')')?
+        .parse::<usize>()
+        .ok()?;
+    if dim == 0 { None } else { Some(dim) }
+}
+
+fn json_type_name(v: &serde_json::Value) -> &'static str {
+    match v {
+        serde_json::Value::Null => "null",
+        serde_json::Value::Bool(_) => "boolean",
+        serde_json::Value::Number(_) => "number",
+        serde_json::Value::String(_) => "string",
+        serde_json::Value::Array(_) => "array",
+        serde_json::Value::Object(_) => "object",
+    }
+}
+
+pub fn parse_load_mode(mode: &str) -> napi::Result<LoadMode> {
+    match mode {
+        "overwrite" => Ok(LoadMode::Overwrite),
+        "append" => Ok(LoadMode::Append),
+        "merge" => Ok(LoadMode::Merge),
+        _ => Err(napi::Error::from_reason(format!(
+            "invalid load mode '{}': expected 'overwrite', 'append', or 'merge'",
+            mode
+        ))),
+    }
+}
+
+pub fn parse_compact_options(opts: Option<&serde_json::Value>) -> napi::Result<CompactOptions> {
+    let mut result = CompactOptions::default();
+    let obj = match opts {
+        Some(serde_json::Value::Object(obj)) => obj,
+        Some(serde_json::Value::Null) | None => return Ok(result),
+        Some(_) => {
+            return Err(napi::Error::from_reason(
+                "compact options must be an object",
+            ));
+        }
+    };
+    for key in obj.keys() {
+        match key.as_str() {
+            "targetRowsPerFragment" | "materializeDeletions" | "materializeDeletionsThreshold" => {
+            }
+            _ => {
+                return Err(napi::Error::from_reason(format!(
+                    "unknown compact option '{}'",
+                    key
+                )));
+            }
+        }
+    }
+    if let Some(v) = obj.get("targetRowsPerFragment") {
+        let parsed = v.as_u64().ok_or_else(|| {
+            napi::Error::from_reason("targetRowsPerFragment must be a positive integer")
+        })?;
+        if parsed == 0 {
+            return Err(napi::Error::from_reason(
+                "targetRowsPerFragment must be a positive integer",
+            ));
+        }
+        result.target_rows_per_fragment = usize::try_from(parsed).map_err(|_| {
+            napi::Error::from_reason("targetRowsPerFragment is too large for this platform")
+        })?;
+    }
+    if let Some(v) = obj.get("materializeDeletions") {
+        result.materialize_deletions = v
+            .as_bool()
+            .ok_or_else(|| napi::Error::from_reason("materializeDeletions must be a boolean"))?;
+    }
+    if let Some(v) = obj.get("materializeDeletionsThreshold") {
+        let threshold = v.as_f64().ok_or_else(|| {
+            napi::Error::from_reason("materializeDeletionsThreshold must be a number")
+        })?;
+        if !(0.0..=1.0).contains(&threshold) {
+            return Err(napi::Error::from_reason(
+                "materializeDeletionsThreshold must be between 0.0 and 1.0",
+            ));
+        }
+        result.materialize_deletions_threshold = threshold as f32;
+    }
+    Ok(result)
+}
+
+pub fn parse_cleanup_options(opts: Option<&serde_json::Value>) -> napi::Result<CleanupOptions> {
+    let mut result = CleanupOptions::default();
+    let obj = match opts {
+        Some(serde_json::Value::Object(obj)) => obj,
+        Some(serde_json::Value::Null) | None => return Ok(result),
+        Some(_) => {
+            return Err(napi::Error::from_reason(
+                "cleanup options must be an object",
+            ));
+        }
+    };
+    for key in obj.keys() {
+        match key.as_str() {
+            "retainTxVersions" | "retainDatasetVersions" => {}
+            _ => {
+                return Err(napi::Error::from_reason(format!(
+                    "unknown cleanup option '{}'",
+                    key
+                )));
+            }
+        }
+    }
+    if let Some(v) = obj.get("retainTxVersions") {
+        let parsed = v.as_u64().ok_or_else(|| {
+            napi::Error::from_reason("retainTxVersions must be a positive integer")
+        })?;
+        if parsed == 0 {
+            return Err(napi::Error::from_reason(
+                "retainTxVersions must be a positive integer",
+            ));
+        }
+        result.retain_tx_versions = parsed;
+    }
+    if let Some(v) = obj.get("retainDatasetVersions") {
+        let parsed = v.as_u64().ok_or_else(|| {
+            napi::Error::from_reason("retainDatasetVersions must be a positive integer")
+        })?;
+        if parsed == 0 {
+            return Err(napi::Error::from_reason(
+                "retainDatasetVersions must be a positive integer",
+            ));
+        }
+        result.retain_dataset_versions = usize::try_from(parsed).map_err(|_| {
+            napi::Error::from_reason("retainDatasetVersions is too large for this platform")
+        })?;
+    }
+    Ok(result)
+}

package/src/lib.rs

@@ -0,0 +1,358 @@
+#![recursion_limit = "256"]
+
+mod convert;
+
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+use tokio::sync::Mutex;
+
+use nanograph::error::NanoError;
+use nanograph::json_output::record_batches_to_json_rows;
+use nanograph::query::parser::parse_query;
+use nanograph::query::typecheck::{CheckedQuery, typecheck_query, typecheck_query_decl};
+use nanograph::store::database::Database;
+use nanograph::{ParamMap, execute_mutation, execute_query, lower_mutation_query, lower_query};
+
+use convert::{
+    js_object_to_param_map, parse_cleanup_options, parse_compact_options, parse_load_mode,
+};
+
+fn to_napi_err(e: NanoError) -> napi::Error {
+    napi::Error::from_reason(e.to_string())
+}
+
+#[napi(js_name = "Database")]
+pub struct JsDatabase {
+    inner: Arc<Mutex<Option<Database>>>,
+}
+
+impl JsDatabase {
+    fn db_path(path: &str) -> PathBuf {
+        PathBuf::from(path)
+    }
+}
+
+fn prop_def_to_json(prop: &nanograph::schema_ir::PropDef) -> serde_json::Value {
+    let mut obj = serde_json::json!({
+        "name": prop.name,
+        "propId": prop.prop_id,
+        "type": prop.scalar_type,
+        "nullable": prop.nullable,
+    });
+    if prop.list {
+        obj["list"] = serde_json::Value::Bool(true);
+    }
+    if prop.key {
+        obj["key"] = serde_json::Value::Bool(true);
+    }
+    if prop.unique {
+        obj["unique"] = serde_json::Value::Bool(true);
+    }
+    if prop.index {
+        obj["index"] = serde_json::Value::Bool(true);
+    }
+    if !prop.enum_values.is_empty() {
+        obj["enumValues"] = serde_json::json!(prop.enum_values);
+    }
+    if let Some(ref src) = prop.embed_source {
+        obj["embedSource"] = serde_json::Value::String(src.clone());
+    }
+    obj
+}
+
+#[napi]
+impl JsDatabase {
+    /// Create a new database from a schema string.
+    ///
+    /// ```js
+    /// const db = await Database.init("my.nano", schemaSource);
+    /// ```
+    #[napi(factory)]
+    pub async fn init(db_path: String, schema_source: String) -> Result<Self> {
+        let path = Self::db_path(&db_path);
+        let db = Database::init(&path, &schema_source)
+            .await
+            .map_err(to_napi_err)?;
+        Ok(JsDatabase {
+            inner: Arc::new(Mutex::new(Some(db))),
+        })
+    }
+
+    /// Open an existing database.
+    ///
+    /// ```js
+    /// const db = await Database.open("my.nano");
+    /// ```
+    #[napi(factory)]
+    pub async fn open(db_path: String) -> Result<Self> {
+        let path = Self::db_path(&db_path);
+        let db = Database::open(&path).await.map_err(to_napi_err)?;
+        Ok(JsDatabase {
+            inner: Arc::new(Mutex::new(Some(db))),
+        })
+    }
+
+    /// Load JSONL data into the database.
+    ///
+    /// ```js
+    /// await db.load(jsonlString, "overwrite");
+    /// ```
+    #[napi]
+    pub async fn load(&self, data_source: String, mode: String) -> Result<()> {
+        let load_mode = parse_load_mode(&mode)?;
+        let mut guard = self.inner.lock().await;
+        let db = guard
+            .as_mut()
+            .ok_or_else(|| napi::Error::from_reason("database is closed"))?;
+        db.load_with_mode(&data_source, load_mode)
+            .await
+            .map_err(to_napi_err)
+    }
+
+    /// Execute a named query from query source text.
+    ///
+    /// For read queries, returns an array of row objects.
+    /// For mutation queries, returns `{ affectedNodes, affectedEdges }`.
+    ///
+    /// ```js
+    /// const rows = await db.run(querySource, "findPeople", { minAge: 21 });
+    /// ```
+    #[napi]
+    pub async fn run(
+        &self,
+        query_source: String,
+        query_name: String,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let queries = parse_query(&query_source).map_err(to_napi_err)?;
+        let query = queries
+            .queries
+            .iter()
+            .find(|q| q.name == query_name)
+            .ok_or_else(|| napi::Error::from_reason(format!("query '{}' not found", query_name)))?
+            .clone();
+
+        let param_map: ParamMap = js_object_to_param_map(params.as_ref(), &query.params)?;
+
+        if query.mutation.is_some() {
+            // Mutation path — holds lock for the entire operation
+            let mut guard = self.inner.lock().await;
+            let db = guard
+                .as_mut()
+                .ok_or_else(|| napi::Error::from_reason("database is closed"))?;
+
+            let checked = typecheck_query_decl(db.catalog(), &query).map_err(to_napi_err)?;
+            if !matches!(checked, CheckedQuery::Mutation(_)) {
+                return Err(napi::Error::from_reason("expected mutation query"));
+            }
+
+            let mutation_ir = lower_mutation_query(&query).map_err(to_napi_err)?;
+            let result = execute_mutation(&mutation_ir, db, &param_map)
+                .await
+                .map_err(to_napi_err)?;
+
+            Ok(serde_json::json!({
+                "affectedNodes": result.affected_nodes,
+                "affectedEdges": result.affected_edges,
+            }))
+        } else {
+            // Read path — clone catalog + snapshot, then release lock
+            let (catalog, storage) = {
+                let guard = self.inner.lock().await;
+                let db = guard
+                    .as_ref()
+                    .ok_or_else(|| napi::Error::from_reason("database is closed"))?;
+                (db.catalog().clone(), db.snapshot())
+            };
+
+            let type_ctx = typecheck_query(&catalog, &query).map_err(to_napi_err)?;
+            let ir = lower_query(&catalog, &query, &type_ctx).map_err(to_napi_err)?;
+            let results = execute_query(&ir, storage, &param_map)
+                .await
+                .map_err(to_napi_err)?;
+
+            let rows = record_batches_to_json_rows(&results);
+            Ok(serde_json::Value::Array(rows))
+        }
+    }
+
+    /// Typecheck all queries in the source text against the database schema.
+    ///
+    /// Returns an array of `{ name, kind, status, error? }` objects.
+    ///
+    /// ```js
+    /// const checks = await db.check(querySource);
+    /// ```
+    #[napi]
+    pub async fn check(&self, query_source: String) -> Result<serde_json::Value> {
+        let queries = parse_query(&query_source).map_err(to_napi_err)?;
+
+        let guard = self.inner.lock().await;
+        let db = guard
+            .as_ref()
+            .ok_or_else(|| napi::Error::from_reason("database is closed"))?;
+        let catalog = db.catalog().clone();
+        drop(guard);
+
+        let mut checks = Vec::with_capacity(queries.queries.len());
+        for q in &queries.queries {
+            match typecheck_query_decl(&catalog, q) {
+                Ok(CheckedQuery::Read(_)) => {
+                    checks.push(serde_json::json!({
+                        "name": q.name,
+                        "kind": "read",
+                        "status": "ok",
+                    }));
+                }
+                Ok(CheckedQuery::Mutation(_)) => {
+                    checks.push(serde_json::json!({
+                        "name": q.name,
+                        "kind": "mutation",
+                        "status": "ok",
+                    }));
+                }
+                Err(e) => {
+                    checks.push(serde_json::json!({
+                        "name": q.name,
+                        "kind": if q.mutation.is_some() { "mutation" } else { "read" },
+                        "status": "error",
+                        "error": e.to_string(),
+                    }));
+                }
+            }
+        }
+
+        Ok(serde_json::Value::Array(checks))
+    }
+
+    /// Return schema introspection as a JSON object.
+    ///
+    /// ```js
+    /// const info = await db.describe();
+    /// ```
+    #[napi]
+    pub async fn describe(&self) -> Result<serde_json::Value> {
+        let ir = {
+            let guard = self.inner.lock().await;
+            let db = guard
+                .as_ref()
+                .ok_or_else(|| napi::Error::from_reason("database is closed"))?;
+            db.schema_ir.clone()
+        };
+
+        let mut node_types = Vec::new();
+        for nt in ir.node_types() {
+            let props: Vec<serde_json::Value> =
+                nt.properties.iter().map(prop_def_to_json).collect();
+            node_types.push(serde_json::json!({
+                "name": nt.name,
+                "typeId": nt.type_id,
+                "properties": props,
+            }));
+        }
+
+        let mut edge_types = Vec::new();
+        for et in ir.edge_types() {
+            let props: Vec<serde_json::Value> =
+                et.properties.iter().map(prop_def_to_json).collect();
+            edge_types.push(serde_json::json!({
+                "name": et.name,
+                "srcType": et.src_type_name,
+                "dstType": et.dst_type_name,
+                "typeId": et.type_id,
+                "properties": props,
+            }));
+        }
+
+        Ok(serde_json::json!({
+            "nodeTypes": node_types,
+            "edgeTypes": edge_types,
+        }))
+    }
+
+    /// Compact Lance datasets to reduce fragmentation.
+    ///
+    /// ```js
+    /// const result = await db.compact({ targetRowsPerFragment: 1048576 });
+    /// ```
+    #[napi]
+    pub async fn compact(&self, options: Option<serde_json::Value>) -> Result<serde_json::Value> {
+        let opts = parse_compact_options(options.as_ref())?;
+        let mut guard = self.inner.lock().await;
+        let db = guard
+            .as_mut()
+            .ok_or_else(|| napi::Error::from_reason("database is closed"))?;
+        let result = db.compact(opts).await.map_err(to_napi_err)?;
+        Ok(serde_json::json!({
+            "datasetsConsidered": result.datasets_considered,
+            "datasetsCompacted": result.datasets_compacted,
+            "fragmentsRemoved": result.fragments_removed,
+            "fragmentsAdded": result.fragments_added,
+            "filesRemoved": result.files_removed,
+            "filesAdded": result.files_added,
+            "manifestCommitted": result.manifest_committed,
+        }))
+    }
+
+    /// Clean up old dataset versions and prune transaction/CDC logs.
+    ///
+    /// ```js
+    /// const result = await db.cleanup({ retainTxVersions: 128 });
+    /// ```
+    #[napi]
+    pub async fn cleanup(&self, options: Option<serde_json::Value>) -> Result<serde_json::Value> {
+        let opts = parse_cleanup_options(options.as_ref())?;
+        let mut guard = self.inner.lock().await;
+        let db = guard
+            .as_mut()
+            .ok_or_else(|| napi::Error::from_reason("database is closed"))?;
+        let result = db.cleanup(opts).await.map_err(to_napi_err)?;
+        Ok(serde_json::json!({
+            "txRowsRemoved": result.tx_rows_removed,
+            "txRowsKept": result.tx_rows_kept,
+            "cdcRowsRemoved": result.cdc_rows_removed,
+            "cdcRowsKept": result.cdc_rows_kept,
+            "datasetsCleaned": result.datasets_cleaned,
+            "datasetOldVersionsRemoved": result.dataset_old_versions_removed,
+            "datasetBytesRemoved": result.dataset_bytes_removed,
+        }))
+    }
+
+    /// Run health checks on the database.
+    ///
+    /// ```js
+    /// const report = await db.doctor();
+    /// ```
+    #[napi]
+    pub async fn doctor(&self) -> Result<serde_json::Value> {
+        let guard = self.inner.lock().await;
+        let db = guard
+            .as_ref()
+            .ok_or_else(|| napi::Error::from_reason("database is closed"))?;
+        let report = db.doctor().await.map_err(to_napi_err)?;
+        Ok(serde_json::json!({
+            "healthy": report.healthy,
+            "issues": report.issues,
+            "warnings": report.warnings,
+            "manifestDbVersion": report.manifest_db_version,
+            "datasetsChecked": report.datasets_checked,
+            "txRows": report.tx_rows,
+            "cdcRows": report.cdc_rows,
+        }))
+    }
+
+    /// Close the database, releasing resources.
+    ///
+    /// ```js
+    /// await db.close();
+    /// ```
+    #[napi]
+    pub async fn close(&self) -> Result<()> {
+        let mut guard = self.inner.lock().await;
+        *guard = None;
+        Ok(())
+    }
+}