rust-kgdb 0.1.12 → 0.2.1

package/README.md

@@ -5,6 +5,33 @@
 
 **Production-ready RDF/hypergraph database with 100% W3C SPARQL 1.1 + RDF 1.2 compliance, worst-case optimal joins (WCOJ), and pluggable storage backends.**
 
+> **This npm package provides the high-performance in-memory database.**
+> For **distributed cluster deployment** (1B+ triples, horizontal scaling), contact: **gonnect.uk@gmail.com**
+
+---
+
+## Deployment Modes
+
+rust-kgdb supports three deployment modes:
+
+| Mode | Use Case | Scalability | This Package |
+|------|----------|-------------|--------------|
+| **In-Memory** | Development, embedded apps, testing | Single node, volatile | ✅ **Included** |
+| **Single Node (RocksDB/LMDB)** | Production, persistence needed | Single node, persistent | Via Rust crate |
+| **Distributed Cluster** | Enterprise, 1B+ triples | Horizontal scaling, 9+ partitions | Contact us |
+
+### Need Distributed Cluster?
+
+For enterprise deployments requiring:
+- **Subject-Anchored Partitioning**: All triples for a subject guaranteed on same partition for locality
+- Horizontal scaling across multiple nodes (1B+ triples)
+- HDRF (High-Degree Replicated First) with power-law load balancing
+- **OLAP Query Path**: SQL-based analytical execution for aggregations
+- Subject-Hash Filter for accurate COUNT deduplication across replicas
+- Kubernetes-native deployment with StatefulSet executors
+
+**Request a demo: gonnect.uk@gmail.com**
+
 ---
 
 ## Why rust-kgdb?
@@ -559,8 +586,44 @@ Total: ~120 bytes/triple including indexes
 
 ---
 
+## Performance Benchmarks
+
+### By Deployment Mode
+
+| Mode | Lookup | Insert | Memory | Dataset Size |
+|------|--------|--------|--------|--------------|
+| **In-Memory (npm)** | 2.78 µs | 146K/sec | 24 bytes/triple | <10M triples |
+| **Single Node (RocksDB)** | 5-10 µs | 100K/sec | On-disk | <100M triples |
+| **Distributed Cluster** | 10-50 µs | 500K+/sec* | Distributed | **1B+ triples** |
+
+*Aggregate throughput across all executors with HDRF partitioning
+
+### SIMD + PGO Query Performance (LUBM Benchmark)
+
+| Query | Pattern | Time | Improvement |
+|-------|---------|------|-------------|
+| Q5 | 2-hop chain | 53ms | **77% faster** |
+| Q3 | 3-way star | 62ms | **65% faster** |
+| Q4 | 3-hop chain | 101ms | **60% faster** |
+| Q8 | Triangle | 193ms | **53% faster** |
+| Q7 | Hierarchy | 198ms | **42% faster** |
+
+**Average: 44.5% speedup** with zero code changes (compiler optimizations only).
+
+---
+
 ## Version History
 
+### v0.2.0 (2025-12-08) - Distributed Cluster Support
+
+- **NEW: Distributed cluster architecture** with HDRF partitioning
+- **Subject-Hash Filter** for accurate COUNT deduplication across replicas
+- **DataFusion-powered OLAP** with Arrow-native vectorized execution
+- Coordinator-Executor pattern with gRPC communication
+- 9-partition default for optimal data distribution
+- **Contact for cluster deployment**: gonnect.uk@gmail.com
+- **Coming soon**: Embedding support for semantic search (v0.3.0)
+
 ### v0.1.12 (2025-12-01) - LMDB Backend Release
 
 - **LMDB storage backend** fully implemented (31 tests passing)

package/index.js

@@ -1,4 +1,38 @@
-const { GraphDb, getVersion } = require('./rust-kgdb-napi.node')
+// Platform-specific native module loading for NAPI-RS
+const os = require('os')
+const path = require('path')
+
+function loadNativeBinding() {
+  const platform = os.platform()
+  const arch = os.arch()
+
+  // Map Node.js arch/platform to NAPI-RS naming convention
+  let nativeBinding
+
+  if (platform === 'darwin') {
+    if (arch === 'x64') {
+      nativeBinding = require('./rust-kgdb-napi.darwin-x64.node')
+    } else if (arch === 'arm64') {
+      nativeBinding = require('./rust-kgdb-napi.darwin-arm64.node')
+    }
+  } else if (platform === 'linux') {
+    if (arch === 'x64') {
+      nativeBinding = require('./rust-kgdb-napi.linux-x64-gnu.node')
+    } else if (arch === 'arm64') {
+      nativeBinding = require('./rust-kgdb-napi.linux-arm64-gnu.node')
+    }
+  } else if (platform === 'win32' && arch === 'x64') {
+    nativeBinding = require('./rust-kgdb-napi.win32-x64-msvc.node')
+  }
+
+  if (!nativeBinding) {
+    throw new Error(`Unsupported platform: ${platform}-${arch}. Please contact support.`)
+  }
+
+  return nativeBinding
+}
+
+const { GraphDb, getVersion } = loadNativeBinding()
 
 module.exports = {
   GraphDB: GraphDb,  // Export as GraphDB for consistency

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rust-kgdb",
-  "version": "0.1.12",
-  "description": "High-performance RDF/SPARQL database with 100% W3C compliance and WCOJ execution",
+  "version": "0.2.1",
+  "description": "High-performance RDF/SPARQL database with 100% W3C compliance, WCOJ execution, and distributed cluster support",
   "main": "index.js",
   "types": "index.d.ts",
   "napi": {
@@ -21,7 +21,7 @@
     "build:debug": "napi build --platform native/rust-kgdb-napi",
     "prepublishOnly": "napi prepublish -t npm",
     "test": "jest",
-    "version": "0.1.12"
+    "version": "0.2.0"
   },
   "keywords": [
     "rdf",
@@ -56,10 +56,10 @@
     "*.node"
   ],
   "optionalDependencies": {
-    "rust-kgdb-win32-x64-msvc": "0.1.12",
-    "rust-kgdb-darwin-x64": "0.1.12",
-    "rust-kgdb-linux-x64-gnu": "0.1.12",
-    "rust-kgdb-darwin-arm64": "0.1.12",
-    "rust-kgdb-linux-arm64-gnu": "0.1.12"
+    "rust-kgdb-win32-x64-msvc": "0.2.1",
+    "rust-kgdb-darwin-x64": "0.2.1",
+    "rust-kgdb-linux-x64-gnu": "0.2.1",
+    "rust-kgdb-darwin-arm64": "0.2.1",
+    "rust-kgdb-linux-arm64-gnu": "0.2.1"
   }
 }