@plures/pluresdb 1.5.3 → 2.9.6

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"
+  }
+}

package/dist/napi/index.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * NAPI-based entry point for PluresDB Node.js bindings.
+ *
+ * This is the primary interface for Node.js consumers.
+ * The native Rust bindings provide direct in-process access to the database,
+ * eliminating the need to spawn a separate Deno server process.
+ *
+ * For the legacy HTTP-based interface, use '@plures/pluresdb/legacy'.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluresDatabase = void 0;
+const path = __importStar(require("node:path"));
+// The crates/pluresdb-node/index.js loader selects the correct platform-specific
+// .node binary and falls back to scoped npm packages (e.g.
+// @plures/pluresdb-native-linux-x64-gnu) when no local binary is present.
+//
+// Path calculation: this file compiles to dist/napi/index.js, so __dirname at
+// runtime is <pkg-root>/dist/napi/ and ../../ resolves to <pkg-root>/, which is
+// exactly where crates/pluresdb-node/index.js lives (included in the npm package
+// via the "files" field in package.json).
+const nativeLoaderPath = path.resolve(__dirname, "../../crates/pluresdb-node/index.js");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const native = require(nativeLoaderPath);
+exports.PluresDatabase = native.PluresDatabase;
+exports.default = exports.PluresDatabase;
+//# sourceMappingURL=index.js.map

package/embedded.d.ts

@@ -0,0 +1 @@
+export { PluresDatabase, QueryResult, ExecutionResult, NodeWithMetadata, SearchResult, DatabaseStats, init } from './crates/pluresdb-node/index';

package/embedded.js

@@ -0,0 +1,46 @@
+/**
+ * PluresDB Embedded - Pure embedded database (no server process required)
+ *
+ * Re-exports the native N-API bindings from @plures/pluresdb-native.
+ * Requires the native `.node` binary to be built first:
+ *   cd crates/pluresdb-node && npm run build
+ *
+ * Usage:
+ *   const { PluresDatabase } = require('@plures/pluresdb/embedded');
+ *   const db = new PluresDatabase('my-actor', '/tmp/my.db');
+ */
+
+const path = require('path');
+
+let nativeModule;
+try {
+  // Try loading the platform-specific binary via napi-rs conventions
+  const platformTriple = `${process.arch === 'x64' ? 'x86_64' : process.arch === 'arm64' ? 'aarch64' : process.arch}-${
+    process.platform === 'linux' ? 'unknown-linux-gnu' :
+    process.platform === 'darwin' ? 'apple-darwin' :
+    process.platform === 'win32' ? 'pc-windows-msvc' : process.platform
+  }`;
+
+  try {
+    // Try platform-specific package first (npm optional deps pattern)
+    nativeModule = require(`@plures/pluresdb-native-${platformTriple}`);
+  } catch {
+    // Fall back to local build output in crates/pluresdb-node/
+    nativeModule = require(path.join(__dirname, 'crates', 'pluresdb-node', `pluresdb-node.${process.platform}-${process.arch === 'x64' ? 'x86_64' : process.arch}-${process.platform === 'linux' ? 'gnu' : ''}.node`));
+  }
+} catch (err) {
+  // Final fallback: try loading index.js from the native crate directory
+  try {
+    nativeModule = require(path.join(__dirname, 'crates', 'pluresdb-node', 'index.js'));
+  } catch {
+    throw new Error(
+      `Failed to load PluresDB native bindings. ` +
+      `The native .node binary must be built first:\n` +
+      `  cd crates/pluresdb-node && npm run build\n` +
+      `Or install the pre-built binary: npm install @plures/pluresdb-native\n` +
+      `Original error: ${err.message}`
+    );
+  }
+}
+
+module.exports = nativeModule;

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "@plures/pluresdb",
-  "version": "1.5.3",
+  "version": "2.9.6",
   "description": "P2P Graph Database with SQLite Compatibility - Local-first, offline-first database for modern applications",
-  "main": "dist/node-index.js",
-  "types": "dist/node-index.d.ts",
+  "main": "dist/napi/index.js",
+  "types": "dist/napi/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/napi/index.d.ts",
+      "require": "./dist/napi/index.js",
+      "default": "./dist/napi/index.js"
+    },
+    "./legacy": {
       "types": "./dist/node-index.d.ts",
       "require": "./dist/node-index.js",
       "default": "./dist/node-index.js"
@@ -20,6 +25,11 @@
       "require": "./dist/better-sqlite3.js",
       "default": "./dist/better-sqlite3.js"
     },
+    "./embedded": {
+      "types": "./embedded.d.ts",
+      "require": "./embedded.js",
+      "default": "./embedded.js"
+    },
     "./vscode": {
       "types": "./dist/vscode/extension.d.ts",
       "require": "./dist/vscode/extension.js",
@@ -35,6 +45,11 @@
       "require": "./dist/types/node-types.js",
       "default": "./dist/types/node-types.js"
     },
+    "./local-first": {
+      "types": "./dist/local-first/unified-api.d.ts",
+      "require": "./dist/local-first/unified-api.js",
+      "default": "./dist/local-first/unified-api.js"
+    },
     "./package.json": "./package.json"
   },
   "bin": {
@@ -46,7 +61,7 @@
     "build:web": "cd web/svelte && npm install && npm run build",
     "dev": "deno run -A --unstable-kv --watch src/main.ts serve --port 34567",
     "start": "node dist/cli.js serve",
-    "test": "deno test -A --unstable-kv",
+    "test": "deno test -A --unstable-kv --sloppy-imports",
     "test:azure:relay": "deno test --allow-net --allow-env azure/tests/relay-tests.ts",
     "test:azure:full": "npm run test:azure:relay",
     "lint": "eslint . --ext .js,.ts,.tsx",
@@ -55,6 +70,7 @@
     "verify": "npm run build:lib && npm test",
     "prepare": "npm run build:lib",
     "prepublishOnly": "npm run verify && npm run build:web",
+    "validate-publish": "node scripts/validate-npm-publish.js",
     "postinstall": "node scripts/postinstall.js",
     "release-check": "node scripts/release-check.js",
     "update-changelog": "node scripts/update-changelog.js"
@@ -91,11 +107,11 @@
     "npm": ">=8.0.0"
   },
   "files": [
-    "dist/",
-    "web/svelte/dist/",
-    "legacy/",
-    "examples/",
-    "scripts/",
+    "embedded.js",
+    "embedded.d.ts",
+    "crates/pluresdb-node/index.d.ts",
+    "crates/pluresdb-node/index.js",
+    "crates/pluresdb-node/*.node",
     "README.md",
     "LICENSE",
     "package.json"
@@ -103,12 +119,13 @@
   "dependencies": {
     "cors": "^2.8.5",
     "express": "^5.1.0",
+    "hyperswarm": "^4.8.4",
     "ws": "^8.18.3"
   },
   "devDependencies": {
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.0",
-    "@types/node": "^22.10.0",
+    "@types/node": "^22.19.11",
     "@types/vscode": "^1.104.0",
     "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.46.4",