@plures/pluresdb 1.6.10 → 2.9.7

package/crates/pluresdb-node/README.md

@@ -0,0 +1,181 @@
+# @plures/pluresdb-native
+
+Native Node.js bindings for PluresDB - a P2P Graph Database with SQLite compatibility.
+
+[![npm version](https://badge.fury.io/js/@plures%2Fpluresdb-native.svg)](https://www.npmjs.com/package/@plures/pluresdb-native)
+[![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](../../LICENSE)
+
+This package provides high-performance N-API bindings to the PluresDB Rust core, enabling native database operations directly from Node.js.
+
+## ✅ Features
+
+- **CRUD Operations** - Create, read, update, and delete nodes with CRDT synchronization
+- **SQL Support** - Execute SQL queries with parameterized statements (95% SQLite compatible)
+- **BLOB Support** - Store binary data including embedding vectors
+- **Search** - Text-based and vector similarity search  
+- **Type Filtering** - Filter nodes by type
+- **Subscriptions** - Subscribe to database changes
+- **Native Performance** - Rust-powered N-API bindings for maximum speed
+
+## Installation
+
+```bash
+npm install @plures/pluresdb-native
+```
+
+Pre-built binaries are available for:
+- **Linux**: x86_64, aarch64 (GNU libc)
+- **macOS**: x86_64 (Intel), aarch64 (Apple Silicon)  
+- **Windows**: x86_64, aarch64 (MSVC)
+
+## Quick Start
+
+```javascript
+const { PluresDatabase } = require('@plures/pluresdb-native');
+
+// Create a new database instance
+const db = new PluresDatabase('my-actor');
+
+// Insert a node
+const id = db.put('user-1', { 
+  name: 'Alice', 
+  email: 'alice@example.com',
+  type: 'User' 
+});
+
+// Retrieve a node
+const user = db.get('user-1');
+console.log(user); // { name: 'Alice', email: 'alice@example.com', type: 'User' }
+
+// List all nodes
+const all = db.list();
+
+// Delete a node
+db.delete('user-1');
+```
+
+## SQL Support
+
+```javascript
+// Create database with SQL support (provide db_path)
+const db = new PluresDatabase('my-actor', './data.db');
+
+// Create table
+db.exec(`
+  CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    email TEXT UNIQUE,
+    embedding BLOB
+  )
+`);
+
+// Insert data
+db.exec(`INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')`);
+
+// Query with parameters (supports ? placeholders)
+const result = db.query('SELECT * FROM users WHERE name = ?', ['Alice']);
+console.log(result.rows); // [{ id: 1, name: 'Alice', email: 'alice@example.com', embedding: null }]
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new PluresDatabase(actorId?: string, dbPath?: string)
+```
+
+- `actorId` (optional): Unique identifier for this database instance. Default: `"node-actor"`
+- `dbPath` (optional): Path to SQLite database file for SQL support
+
+### Methods
+
+#### CRUD Operations
+
+- `put(id: string, data: any): string` - Insert or update a node
+- `get(id: string): any | null` - Retrieve a node by ID
+- `getWithMetadata(id: string): NodeWithMetadata | null` - Get node with vector clock and timestamp
+- `delete(id: string): void` - Delete a node
+- `list(): Array<{id, data, timestamp}>` - List all nodes
+- `listByType(nodeType: string): Array<{id, data, timestamp}>` - Filter nodes by type
+
+#### SQL Operations
+
+- `query(sql: string, params?: any[]): QueryResult` - Execute SQL SELECT with parameters
+- `exec(sql: string): ExecutionResult` - Execute SQL statement (INSERT, UPDATE, DELETE, CREATE)
+
+**Example:**
+```javascript
+const result = db.query('SELECT * FROM users WHERE age > ?', [25]);
+console.log(result.rows); // Array of matching rows
+```
+
+#### Search
+
+- `search(query: string, limit?: number): SearchResult[]` - Text search across node data
+- `vectorSearch(query: string, limit?: number, threshold?: number): SearchResult[]` - Vector similarity search
+
+#### Utilities
+
+- `subscribe(): string` - Subscribe to database changes
+- `getActorId(): string` - Get the actor ID
+- `stats(): DatabaseStats` - Get database statistics (`{totalNodes, typeCounts}`)
+
+## TypeScript Support
+
+TypeScript definitions are included in the package.
+
+```typescript
+import { PluresDatabase, QueryResult, ExecutionResult } from '@plures/pluresdb-native';
+
+const db = new PluresDatabase('my-actor', './data.db');
+const result: QueryResult = db.query('SELECT * FROM users WHERE id = ?', [1]);
+```
+
+## SLM (superlocalmemory) Compatibility
+
+This package is designed as a drop-in replacement for better-sqlite3 in the superlocalmemory project:
+
+- ✅ Parameterized SQL with `?` placeholders
+- ✅ BLOB column support for embedding vectors
+- ✅ Synchronous API (no async/await required)
+- ✅ 95% SQLite compatibility
+
+See the [SLM Migration Guide](https://github.com/plures/development-guide/blob/main/goals/SLM-PLURESDB-MIGRATION.md) for details.
+
+## Building from Source
+
+If a pre-built binary is not available for your platform:
+
+```bash
+# Clone the repository
+git clone https://github.com/plures/pluresdb.git
+cd pluresdb/crates/pluresdb-node
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Test
+npm test
+```
+
+### Requirements
+
+- Rust 1.70 or later
+- Node.js 20 or later
+- C compiler (for rusqlite native dependencies)
+
+## License
+
+AGPL-3.0 - see [LICENSE](../../LICENSE) for details.
+
+## Links
+
+- [GitHub Repository](https://github.com/plures/pluresdb)
+- [PluresDB Documentation](https://github.com/plures/pluresdb#readme)
+- [Issue Tracker](https://github.com/plures/pluresdb/issues)
+- [NPM Package](https://www.npmjs.com/package/@plures/pluresdb-native)

package/crates/pluresdb-node/index.js

@@ -0,0 +1,265 @@
+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 non-glibc Linux systems we must check if musl is used instead
+  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 (e) {
+      return true;
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header;
+    return !glibcVersionRuntime;
+  }
+}
+
+switch (platform) {
+  case "android":
+    switch (arch) {
+      case "arm64":
+        localFileExisted = existsSync(
+          join(__dirname, "pluresdb-node.android-arm64.node")
+        );
+        try {
+          if (localFileExisted) {
+            nativeBinding = require("./pluresdb-node.android-arm64.node");
+          } else {
+            nativeBinding = require("@plures/pluresdb-native-android-arm64");
+          }
+        } catch (e) {
+          loadError = e;
+        }
+        break;
+      case "arm":
+        localFileExisted = existsSync(
+          join(__dirname, "pluresdb-node.android-arm-eabi.node")
+        );
+        try {
+          if (localFileExisted) {
+            nativeBinding = require("./pluresdb-node.android-arm-eabi.node");
+          } else {
+            nativeBinding = require("@plures/pluresdb-native-android-arm-eabi");
+          }
+        } catch (e) {
+          loadError = e;
+        }
+        break;
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`);
+    }
+    break;
+  case "win32":
+    switch (arch) {
+      case "x64":
+        localFileExisted = existsSync(
+          join(__dirname, "pluresdb-node.win32-x64-msvc.node")
+        );
+        try {
+          if (localFileExisted) {
+            nativeBinding = require("./pluresdb-node.win32-x64-msvc.node");
+          } else {
+            nativeBinding = require("@plures/pluresdb-native-win32-x64-msvc");
+          }
+        } catch (e) {
+          loadError = e;
+        }
+        break;
+      case "ia32":
+        localFileExisted = existsSync(
+          join(__dirname, "pluresdb-node.win32-ia32-msvc.node")
+        );
+        try {
+          if (localFileExisted) {
+            nativeBinding = require("./pluresdb-node.win32-ia32-msvc.node");
+          } else {
+            nativeBinding = require("@plures/pluresdb-native-win32-ia32-msvc");
+          }
+        } catch (e) {
+          loadError = e;
+        }
+        break;
+      case "arm64":
+        localFileExisted = existsSync(
+          join(__dirname, "pluresdb-node.win32-arm64-msvc.node")
+        );
+        try {
+          if (localFileExisted) {
+            nativeBinding = require("./pluresdb-node.win32-arm64-msvc.node");
+          } else {
+            nativeBinding = require("@plures/pluresdb-native-win32-arm64-msvc");
+          }
+        } catch (e) {
+          loadError = e;
+        }
+        break;
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`);
+    }
+    break;
+  case "darwin":
+    localFileExisted = existsSync(
+      join(__dirname, "pluresdb-node.darwin-universal.node")
+    );
+    try {
+      if (localFileExisted) {
+        nativeBinding = require("./pluresdb-node.darwin-universal.node");
+      } else {
+        nativeBinding = require("@plures/pluresdb-native-darwin-universal");
+      }
+      break;
+    } catch {}
+    switch (arch) {
+      case "x64":
+        localFileExisted = existsSync(
+          join(__dirname, "pluresdb-node.darwin-x64.node")
+        );
+        try {
+          if (localFileExisted) {
+            nativeBinding = require("./pluresdb-node.darwin-x64.node");
+          } else {
+            nativeBinding = require("@plures/pluresdb-native-darwin-x64");
+          }
+        } catch (e) {
+          loadError = e;
+        }
+        break;
+      case "arm64":
+        localFileExisted = existsSync(
+          join(__dirname, "pluresdb-node.darwin-arm64.node")
+        );
+        try {
+          if (localFileExisted) {
+            nativeBinding = require("./pluresdb-node.darwin-arm64.node");
+          } else {
+            nativeBinding = require("@plures/pluresdb-native-darwin-arm64");
+          }
+        } catch (e) {
+          loadError = e;
+        }
+        break;
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`);
+    }
+    break;
+  case "freebsd":
+    if (arch !== "x64") {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`);
+    }
+    localFileExisted = existsSync(
+      join(__dirname, "pluresdb-node.freebsd-x64.node")
+    );
+    try {
+      if (localFileExisted) {
+        nativeBinding = require("./pluresdb-node.freebsd-x64.node");
+      } else {
+        nativeBinding = require("@plures/pluresdb-native-freebsd-x64");
+      }
+    } catch (e) {
+      loadError = e;
+    }
+    break;
+  case "linux":
+    switch (arch) {
+      case "x64":
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, "pluresdb-node.linux-x64-musl.node")
+          );
+          try {
+            if (localFileExisted) {
+              nativeBinding = require("./pluresdb-node.linux-x64-musl.node");
+            } else {
+              nativeBinding = require("@plures/pluresdb-native-linux-x64-musl");
+            }
+          } catch (e) {
+            loadError = e;
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, "pluresdb-node.linux-x64-gnu.node")
+          );
+          try {
+            if (localFileExisted) {
+              nativeBinding = require("./pluresdb-node.linux-x64-gnu.node");
+            } else {
+              nativeBinding = require("@plures/pluresdb-native-linux-x64-gnu");
+            }
+          } catch (e) {
+            loadError = e;
+          }
+        }
+        break;
+      case "arm64":
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, "pluresdb-node.linux-arm64-musl.node")
+          );
+          try {
+            if (localFileExisted) {
+              nativeBinding = require("./pluresdb-node.linux-arm64-musl.node");
+            } else {
+              nativeBinding = require("@plures/pluresdb-native-linux-arm64-musl");
+            }
+          } catch (e) {
+            loadError = e;
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, "pluresdb-node.linux-arm64-gnu.node")
+          );
+          try {
+            if (localFileExisted) {
+              nativeBinding = require("./pluresdb-node.linux-arm64-gnu.node");
+            } else {
+              nativeBinding = require("@plures/pluresdb-native-linux-arm64-gnu");
+            }
+          } catch (e) {
+            loadError = e;
+          }
+        }
+        break;
+      case "arm":
+        localFileExisted = existsSync(
+          join(__dirname, "pluresdb-node.linux-arm-gnueabihf.node")
+        );
+        try {
+          if (localFileExisted) {
+            nativeBinding = require("./pluresdb-node.linux-arm-gnueabihf.node");
+          } else {
+            nativeBinding = require("@plures/pluresdb-native-linux-arm-gnueabihf");
+          }
+        } catch (e) {
+          loadError = e;
+        }
+        break;
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${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 { PluresDatabase, init } = nativeBinding;
+
+module.exports.PluresDatabase = PluresDatabase;
+module.exports.init = init;

package/crates/pluresdb-node/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@plures/pluresdb-native",
+  "version": "2.0.0-alpha.1",
+  "description": "Native Node.js bindings for PluresDB",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "napi": {
+    "binaryName": "pluresdb-node",
+    "targets": [
+      "x86_64-unknown-linux-gnu",
+      "aarch64-unknown-linux-gnu",
+      "x86_64-apple-darwin",
+      "aarch64-apple-darwin",
+      "x86_64-pc-windows-msvc",
+      "aarch64-pc-windows-msvc"
+    ]
+  },
+  "scripts": {
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "test": "node test-node.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "database",
+    "pluresdb",
+    "native",
+    "napi"
+  ],
+  "author": "Plures Organization",
+  "license": "AGPL-3.0",
+  "devDependencies": {
+    "@napi-rs/cli": "^3.5.1"
+  }
+}