@plures/pluresdb 1.5.3 → 2.9.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +106 -414
- package/crates/README.md +99 -0
- package/crates/pluresdb-node/README.md +181 -0
- package/crates/pluresdb-node/index.d.ts +0 -0
- package/crates/pluresdb-node/index.js +265 -0
- package/crates/pluresdb-node/package.json +35 -0
- package/dist/napi/index.js +60 -0
- package/embedded.d.ts +1 -0
- package/embedded.js +46 -0
- package/package.json +27 -10
- package/dist/.tsbuildinfo +0 -1
- package/dist/better-sqlite3-shared.d.ts +0 -12
- package/dist/better-sqlite3-shared.d.ts.map +0 -1
- package/dist/better-sqlite3-shared.js +0 -143
- package/dist/better-sqlite3-shared.js.map +0 -1
- package/dist/better-sqlite3.d.ts +0 -4
- package/dist/better-sqlite3.d.ts.map +0 -1
- package/dist/better-sqlite3.js +0 -8
- package/dist/better-sqlite3.js.map +0 -1
- package/dist/cli.d.ts +0 -7
- package/dist/cli.d.ts.map +0 -1
- package/dist/cli.js.map +0 -1
- package/dist/node-index.d.ts +0 -148
- package/dist/node-index.d.ts.map +0 -1
- package/dist/node-index.js +0 -665
- package/dist/node-index.js.map +0 -1
- package/dist/node-wrapper.d.ts +0 -44
- package/dist/node-wrapper.d.ts.map +0 -1
- package/dist/node-wrapper.js +0 -296
- package/dist/node-wrapper.js.map +0 -1
- package/dist/types/index.d.ts +0 -28
- package/dist/types/index.d.ts.map +0 -1
- package/dist/types/index.js +0 -3
- package/dist/types/index.js.map +0 -1
- package/dist/types/node-types.d.ts +0 -71
- package/dist/types/node-types.d.ts.map +0 -1
- package/dist/types/node-types.js +0 -6
- package/dist/types/node-types.js.map +0 -1
- package/dist/vscode/extension.d.ts +0 -81
- package/dist/vscode/extension.d.ts.map +0 -1
- package/dist/vscode/extension.js +0 -309
- package/dist/vscode/extension.js.map +0 -1
- package/examples/basic-usage.d.ts +0 -2
- package/examples/basic-usage.d.ts.map +0 -1
- package/examples/basic-usage.js +0 -26
- package/examples/basic-usage.js.map +0 -1
- package/examples/basic-usage.ts +0 -29
- package/examples/vscode-extension-example/README.md +0 -95
- package/examples/vscode-extension-example/package.json +0 -49
- package/examples/vscode-extension-example/src/extension.ts +0 -172
- package/examples/vscode-extension-example/tsconfig.json +0 -12
- package/examples/vscode-extension-integration.d.ts +0 -31
- package/examples/vscode-extension-integration.d.ts.map +0 -1
- package/examples/vscode-extension-integration.js +0 -319
- package/examples/vscode-extension-integration.js.map +0 -1
- package/examples/vscode-extension-integration.ts +0 -41
- package/legacy/benchmarks/memory-benchmarks.ts +0 -350
- package/legacy/benchmarks/run-benchmarks.ts +0 -315
- package/legacy/better-sqlite3-shared.ts +0 -157
- package/legacy/better-sqlite3.ts +0 -4
- package/legacy/cli.ts +0 -241
- package/legacy/config.ts +0 -50
- package/legacy/core/crdt.ts +0 -107
- package/legacy/core/database.ts +0 -529
- package/legacy/healthcheck.ts +0 -162
- package/legacy/http/api-server.ts +0 -438
- package/legacy/index.ts +0 -28
- package/legacy/logic/rules.ts +0 -46
- package/legacy/main.rs +0 -3
- package/legacy/main.ts +0 -197
- package/legacy/network/websocket-server.ts +0 -115
- package/legacy/node-index.ts +0 -823
- package/legacy/node-wrapper.ts +0 -329
- package/legacy/sqlite-compat.ts +0 -633
- package/legacy/sqlite3-compat.ts +0 -55
- package/legacy/storage/kv-storage.ts +0 -73
- package/legacy/tests/core.test.ts +0 -305
- package/legacy/tests/fixtures/performance-data.json +0 -71
- package/legacy/tests/fixtures/test-data.json +0 -129
- package/legacy/tests/integration/api-server.test.ts +0 -334
- package/legacy/tests/integration/mesh-network.test.ts +0 -303
- package/legacy/tests/logic.test.ts +0 -34
- package/legacy/tests/performance/load.test.ts +0 -290
- package/legacy/tests/security/input-validation.test.ts +0 -286
- package/legacy/tests/unit/core.test.ts +0 -226
- package/legacy/tests/unit/subscriptions.test.ts +0 -135
- package/legacy/tests/unit/vector-search.test.ts +0 -173
- package/legacy/tests/vscode_extension_test.ts +0 -281
- package/legacy/types/index.ts +0 -32
- package/legacy/types/node-types.ts +0 -80
- package/legacy/util/debug.ts +0 -14
- package/legacy/vector/index.ts +0 -59
- package/legacy/vscode/extension.ts +0 -387
- package/scripts/compiled-crud-verify.ts +0 -30
- package/scripts/dogfood.ts +0 -297
- package/scripts/postinstall.js +0 -156
- package/scripts/publish-crates.sh +0 -95
- package/scripts/release-check.js +0 -224
- package/scripts/run-tests.ts +0 -178
- package/scripts/setup-libclang.ps1 +0 -209
- package/scripts/update-changelog.js +0 -214
- package/web/README.md +0 -27
- package/web/svelte/package.json +0 -31
package/README.md
CHANGED
|
@@ -5,446 +5,138 @@
|
|
|
5
5
|
[](https://deno.land)
|
|
6
6
|
[](https://opensource.org/licenses/AGPL-3.0)
|
|
7
7
|
|
|
8
|
-
**P2P Graph Database
|
|
8
|
+
**Local-First P2P Graph Database — v2.0**
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
PluresDB is a CRDT-based graph database built with Rust and TypeScript. It
|
|
11
|
+
provides a native sled-backed storage layer with CRDT conflict resolution,
|
|
12
|
+
vector search, and P2P synchronisation — ideal for desktop apps, VSCode
|
|
13
|
+
extensions, and personal knowledge management.
|
|
11
14
|
|
|
12
|
-
|
|
15
|
+
> **v2.0 breaking change:** The `rusqlite` dependency has been removed from
|
|
16
|
+
> `pluresdb-core` by default. `CrdtStore::with_persistence()` now accepts
|
|
17
|
+
> `Arc<dyn StorageEngine>` instead of `Arc<Database>`. If you need the legacy
|
|
18
|
+
> SQL layer, enable the `sqlite-compat` Cargo feature. See
|
|
19
|
+
> [MIGRATION.md](MIGRATION.md) for upgrade instructions.
|
|
13
20
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
- **Winget:** Published as `pluresdb.pluresdb` ([manifest](https://github.com/plures/pluresdb/blob/main/packaging/winget/pluresdb.yaml)) for Windows installs
|
|
17
|
-
- **npm:** [`pluresdb`](https://www.npmjs.com/package/pluresdb) (Node.js + better-sqlite3 compatibility)
|
|
18
|
-
- **crates.io:** [`pluresdb-core`](https://crates.io/crates/pluresdb-core), [`pluresdb-storage`](https://crates.io/crates/pluresdb-storage), [`pluresdb-sync`](https://crates.io/crates/pluresdb-sync), [`pluresdb-cli`](https://crates.io/crates/pluresdb-cli) (Rust crates)
|
|
19
|
-
- **JSR:** [`@plures/pluresdb`](https://jsr.io/@plures/pluresdb) (Deno module)
|
|
20
|
-
- **Docker Hub:** [`pluresdb/pluresdb`](https://hub.docker.com/r/pluresdb/pluresdb) (containerized deployment)
|
|
21
|
-
- **GitHub Releases:** Pre-built binaries for Windows, macOS, and Linux
|
|
22
|
-
|
|
23
|
-
For version-specific information and release notes, see the [CHANGELOG](CHANGELOG.md).
|
|
24
|
-
|
|
25
|
-
### Install
|
|
21
|
+
## Install
|
|
26
22
|
|
|
27
23
|
```bash
|
|
28
|
-
#
|
|
29
|
-
npm install pluresdb
|
|
30
|
-
|
|
31
|
-
# yarn
|
|
32
|
-
yarn add pluresdb
|
|
24
|
+
# Node.js
|
|
25
|
+
npm install @plures/pluresdb
|
|
33
26
|
|
|
34
|
-
#
|
|
35
|
-
pnpm add pluresdb
|
|
36
|
-
|
|
37
|
-
# Deno (JSR)
|
|
27
|
+
# Deno
|
|
38
28
|
deno add @plures/pluresdb
|
|
39
29
|
|
|
40
|
-
# Rust
|
|
41
|
-
cargo add pluresdb-core
|
|
42
|
-
|
|
43
|
-
# Docker
|
|
44
|
-
docker pull pluresdb/pluresdb:latest
|
|
45
|
-
|
|
46
|
-
# Windows (Winget)
|
|
47
|
-
winget install pluresdb.pluresdb
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
### Development Prerequisites (Rust Components)
|
|
51
|
-
|
|
52
|
-
If you plan to build or test the Rust crates in this repository, make sure `libclang` is available so
|
|
53
|
-
bindgen-based dependencies (like `zstd-sys`) can compile. On Windows you can automate this setup with:
|
|
54
|
-
|
|
55
|
-
```powershell
|
|
56
|
-
pwsh ./scripts/setup-libclang.ps1 -ConfigureCurrentProcess
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
The script will detect or install LLVM (via `winget`/`choco`), set the `LIBCLANG_PATH` environment variable,
|
|
60
|
-
and update the current session so that `cargo build` / `cargo test` can run without manual configuration.
|
|
61
|
-
Restart your terminal if you omit the `-ConfigureCurrentProcess` flag.
|
|
62
|
-
|
|
63
|
-
## 📦 Packaging Artifacts
|
|
64
|
-
|
|
65
|
-
Generate Windows, MSI, Deno, and Nix release bundles with the helper script:
|
|
66
|
-
|
|
67
|
-
```powershell
|
|
68
|
-
pwsh ./packaging/scripts/build-packages.ps1
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
The script automatically reads the release version from `Cargo.toml`. Override it for pre-release cuts if needed:
|
|
72
|
-
|
|
73
|
-
```powershell
|
|
74
|
-
pwsh ./packaging/scripts/build-packages.ps1 -Version 1.1.0-rc1
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
### Basic Usage
|
|
78
|
-
|
|
79
|
-
```typescript
|
|
80
|
-
import { PluresNode, SQLiteCompatibleAPI } from "pluresdb";
|
|
81
|
-
|
|
82
|
-
// Start the database
|
|
83
|
-
const db = new PluresNode({
|
|
84
|
-
config: {
|
|
85
|
-
port: 34567,
|
|
86
|
-
host: "localhost",
|
|
87
|
-
dataDir: "./data",
|
|
88
|
-
},
|
|
89
|
-
autoStart: true,
|
|
90
|
-
});
|
|
91
|
-
|
|
92
|
-
// Use SQLite-compatible API
|
|
93
|
-
const sqlite = new SQLiteCompatibleAPI();
|
|
94
|
-
|
|
95
|
-
// Create tables
|
|
96
|
-
await sqlite.exec(`
|
|
97
|
-
CREATE TABLE users (
|
|
98
|
-
id INTEGER PRIMARY KEY,
|
|
99
|
-
name TEXT,
|
|
100
|
-
email TEXT
|
|
101
|
-
)
|
|
102
|
-
`);
|
|
103
|
-
|
|
104
|
-
// Insert data
|
|
105
|
-
await sqlite.run("INSERT INTO users (name, email) VALUES (?, ?)", [
|
|
106
|
-
"John",
|
|
107
|
-
"john@example.com",
|
|
108
|
-
]);
|
|
109
|
-
|
|
110
|
-
// Query data
|
|
111
|
-
const users = await sqlite.all("SELECT * FROM users");
|
|
112
|
-
|
|
113
|
-
// Vector search
|
|
114
|
-
const results = await sqlite.vectorSearch("machine learning", 10);
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
#### In Deno
|
|
118
|
-
|
|
119
|
-
```ts
|
|
120
|
-
import { GunDB, startApiServer } from "jsr:@plures/pluresdb";
|
|
121
|
-
|
|
122
|
-
const db = new GunDB();
|
|
123
|
-
await db.ready();
|
|
124
|
-
|
|
125
|
-
// start the mesh listener and optional HTTP API
|
|
126
|
-
db.serve({ port: 34567 });
|
|
127
|
-
const api = startApiServer({ port: 8080, db });
|
|
128
|
-
|
|
129
|
-
await db.put("user:alice", { name: "Alice", email: "alice@example.com" });
|
|
130
|
-
const record = await db.get("user:alice");
|
|
131
|
-
console.log(record);
|
|
132
|
-
|
|
133
|
-
// remember to close when the process exits
|
|
134
|
-
await db.close();
|
|
135
|
-
api.close();
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
## 🎯 Features
|
|
139
|
-
|
|
140
|
-
### Core Database
|
|
141
|
-
|
|
142
|
-
- **P2P Graph Database**: Distributed, peer-to-peer data storage
|
|
143
|
-
- **SQLite Compatibility**: 95% SQLite API compatibility for easy migration
|
|
144
|
-
- **CRDT Conflict Resolution**: Automatic conflict resolution for distributed data
|
|
145
|
-
- **Vector Search**: Built-in vector embeddings and similarity search
|
|
146
|
-
- **Local-First**: Offline-first data storage with sync when online
|
|
147
|
-
|
|
148
|
-
### P2P Ecosystem
|
|
149
|
-
|
|
150
|
-
- **Identity Management**: Public key infrastructure for peer identification
|
|
151
|
-
- **Encrypted Sharing**: End-to-end encrypted data sharing between peers
|
|
152
|
-
- **Cross-Device Sync**: Automatic synchronization across all your devices
|
|
153
|
-
- **Acceptance Policies**: Granular control over what data to accept from peers
|
|
154
|
-
|
|
155
|
-
### Developer Experience
|
|
156
|
-
|
|
157
|
-
- **TypeScript Support**: Full TypeScript definitions included
|
|
158
|
-
- **VSCode Integration**: Easy integration with VSCode extensions
|
|
159
|
-
- **Web UI**: Comprehensive 24-tab management interface
|
|
160
|
-
- **REST API**: Full REST API for web applications
|
|
161
|
-
- **WebSocket API**: Real-time updates and synchronization
|
|
30
|
+
# Rust
|
|
31
|
+
cargo add pluresdb-core
|
|
162
32
|
|
|
163
|
-
|
|
33
|
+
# CLI
|
|
34
|
+
cargo install pluresdb-cli
|
|
164
35
|
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
**Recommended for Windows users who want a personal database (`pluresdb.pluresdb`):**
|
|
168
|
-
|
|
169
|
-
```powershell
|
|
170
|
-
# Option 1: Using winget
|
|
36
|
+
# Windows
|
|
171
37
|
winget install pluresdb.pluresdb
|
|
172
38
|
|
|
173
|
-
#
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
# Option 3: Download ZIP from releases
|
|
177
|
-
# Extract and run start.bat
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
📖 **[Complete Windows Getting Started Guide →](docs/WINDOWS_GETTING_STARTED.md)**
|
|
181
|
-
|
|
182
|
-
### Package Managers
|
|
183
|
-
|
|
184
|
-
```bash
|
|
185
|
-
# macOS
|
|
186
|
-
brew install plures/pluresdb/pluresdb
|
|
187
|
-
|
|
188
|
-
# Linux (NixOS)
|
|
189
|
-
nix-env -iA nixpkgs.pluresdb
|
|
190
|
-
|
|
191
|
-
# Universal install script
|
|
192
|
-
curl -fsSL https://raw.githubusercontent.com/plures/pluresdb/main/install.sh | bash
|
|
193
|
-
```
|
|
194
|
-
|
|
195
|
-
### Docker
|
|
196
|
-
|
|
197
|
-
```bash
|
|
198
|
-
docker pull plures/pluresdb:latest
|
|
199
|
-
docker run -p 34567:34567 -p 34568:34568 plures/pluresdb:latest
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
## 🔧 VSCode Extension Integration
|
|
203
|
-
|
|
204
|
-
Perfect for VSCode extensions that currently use SQLite:
|
|
205
|
-
|
|
206
|
-
```typescript
|
|
207
|
-
import { SQLiteCompatibleAPI } from "pluresdb";
|
|
208
|
-
|
|
209
|
-
export function activate(context: vscode.ExtensionContext) {
|
|
210
|
-
// Replace your SQLite database with PluresDB
|
|
211
|
-
const db = new SQLiteCompatibleAPI({
|
|
212
|
-
config: {
|
|
213
|
-
dataDir: path.join(context.globalStorageUri.fsPath, "pluresdb"),
|
|
214
|
-
},
|
|
215
|
-
});
|
|
216
|
-
|
|
217
|
-
// Use the same SQLite API you're familiar with
|
|
218
|
-
await db.exec("CREATE TABLE settings (key TEXT, value TEXT)");
|
|
219
|
-
await db.run("INSERT INTO settings VALUES (?, ?)", ["theme", "dark"]);
|
|
220
|
-
const settings = await db.all("SELECT * FROM settings");
|
|
221
|
-
}
|
|
222
|
-
```
|
|
223
|
-
|
|
224
|
-
## 🌐 Web UI
|
|
225
|
-
|
|
226
|
-
Access the comprehensive web interface at `http://localhost:34568`:
|
|
227
|
-
|
|
228
|
-
- **Data Explorer**: Browse and edit your data
|
|
229
|
-
- **Graph Visualization**: Interactive graph view of relationships
|
|
230
|
-
- **Vector Search**: Semantic search across your data
|
|
231
|
-
- **P2P Management**: Manage peers and encrypted sharing
|
|
232
|
-
- **Performance Monitoring**: Real-time performance metrics
|
|
233
|
-
- **Settings**: Configure database and P2P settings
|
|
234
|
-
|
|
235
|
-
## 🔌 API Reference
|
|
236
|
-
|
|
237
|
-
### SQLite-Compatible API
|
|
238
|
-
|
|
239
|
-
```typescript
|
|
240
|
-
// Database operations
|
|
241
|
-
await sqlite.exec(sql); // Execute SQL
|
|
242
|
-
await sqlite.run(sql, params); // Run SQL with parameters
|
|
243
|
-
await sqlite.get(sql, params); // Get single row
|
|
244
|
-
await sqlite.all(sql, params); // Get all rows
|
|
245
|
-
|
|
246
|
-
// Key-value operations
|
|
247
|
-
await sqlite.put(key, value); // Store key-value pair
|
|
248
|
-
await sqlite.getValue(key); // Get value by key
|
|
249
|
-
await sqlite.delete(key); // Delete key
|
|
250
|
-
|
|
251
|
-
// Vector search
|
|
252
|
-
await sqlite.vectorSearch(query, limit); // Semantic search
|
|
253
|
-
```
|
|
254
|
-
|
|
255
|
-
### better-sqlite3-Compatible API
|
|
256
|
-
|
|
257
|
-
Need the synchronous ergonomics of [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3)?
|
|
258
|
-
The Node package now ships a compatibility layer that mirrors its familiar
|
|
259
|
-
`Database`/`Statement` workflow while proxying calls to PluresDB.
|
|
260
|
-
|
|
261
|
-
> **Note:** PluresDB operations run through HTTP and therefore return Promises.
|
|
262
|
-
> You can still keep the same control flow by awaiting each call.
|
|
263
|
-
|
|
264
|
-
```typescript
|
|
265
|
-
import Database from "pluresdb/better-sqlite3";
|
|
266
|
-
|
|
267
|
-
const db = await new Database("./data.db", { autoStart: true }).open();
|
|
268
|
-
await db.exec(
|
|
269
|
-
"CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)",
|
|
270
|
-
);
|
|
271
|
-
|
|
272
|
-
const insert = db.prepare("INSERT INTO users (name) VALUES (?)");
|
|
273
|
-
await insert.run("Ada Lovelace");
|
|
274
|
-
|
|
275
|
-
const select = db.prepare("SELECT id, name FROM users ORDER BY id");
|
|
276
|
-
const people = await select.all();
|
|
277
|
-
```
|
|
278
|
-
|
|
279
|
-
Statements support `run`, `get`, `all`, `iterate`, and common mode toggles like
|
|
280
|
-
`.raw()`, `.pluck()`, and `.expand(true)` for dotted column names.
|
|
281
|
-
|
|
282
|
-
```typescript
|
|
283
|
-
const singleColumnValues = await select.pluck().all();
|
|
284
|
-
const nestedRows = await select.expand().all();
|
|
285
|
-
```
|
|
286
|
-
|
|
287
|
-
Transaction helpers mirror `better-sqlite3` as well:
|
|
288
|
-
|
|
289
|
-
```typescript
|
|
290
|
-
const write = db.transaction(async (users) => {
|
|
291
|
-
for (const user of users) {
|
|
292
|
-
await insert.run(user.name);
|
|
293
|
-
}
|
|
294
|
-
});
|
|
295
|
-
|
|
296
|
-
await write([{ name: "Grace Hopper" }, { name: "Margaret Hamilton" }]);
|
|
297
|
-
```
|
|
298
|
-
|
|
299
|
-
### P2P API
|
|
300
|
-
|
|
301
|
-
```typescript
|
|
302
|
-
// Identity management
|
|
303
|
-
await db.createIdentity({ name: "John", email: "john@example.com" });
|
|
304
|
-
await db.searchPeers("developer");
|
|
305
|
-
|
|
306
|
-
// Encrypted sharing
|
|
307
|
-
await db.shareNode(nodeId, targetPeerId, { accessLevel: "read-only" });
|
|
308
|
-
await db.acceptSharedNode(sharedNodeId);
|
|
309
|
-
|
|
310
|
-
// Cross-device sync
|
|
311
|
-
await db.addDevice({ name: "My Phone", type: "phone" });
|
|
312
|
-
await db.syncWithDevice(deviceId);
|
|
313
|
-
```
|
|
314
|
-
|
|
315
|
-
## 🗂️ Monorepo layout & Rust implementation
|
|
316
|
-
|
|
317
|
-
PluresDB ships as a Rust-first monorepo with language bindings for Deno and Node; the top-level layout is:
|
|
318
|
-
|
|
319
|
-
- **Rust workspace:** `crates/` hosts the production Rust core (`pluresdb-core`, `pluresdb-storage`, `pluresdb-sync`) plus bindings and tools (`pluresdb-cli`, `pluresdb-node`, `pluresdb-deno`).
|
|
320
|
-
- **JavaScript/TypeScript:** `legacy/` retains the original Deno/Node code paths for compatibility and references the same APIs exported via `package.json`/`mod.ts`.
|
|
321
|
-
- **Packaging:** `packaging/` and `packaging/winget/` contain the MSI/winget artifacts that back the published Windows package.
|
|
322
|
-
|
|
323
|
-
## 🚀 Migration from SQLite
|
|
324
|
-
|
|
325
|
-
Migrating from SQLite is straightforward:
|
|
326
|
-
|
|
327
|
-
1. **Install PluresDB**: `npm install pluresdb`
|
|
328
|
-
2. **Replace imports**: Change `sqlite3` to `pluresdb`
|
|
329
|
-
3. **Update initialization**: Use `SQLiteCompatibleAPI` instead of `sqlite3.Database`
|
|
330
|
-
4. **Keep your queries**: All SQL queries work the same way
|
|
331
|
-
|
|
332
|
-
```typescript
|
|
333
|
-
// Before (SQLite)
|
|
334
|
-
import sqlite3 from "sqlite3";
|
|
335
|
-
const db = new sqlite3.Database("./data.db");
|
|
336
|
-
|
|
337
|
-
// After (PluresDB)
|
|
338
|
-
import { SQLiteCompatibleAPI } from "pluresdb";
|
|
339
|
-
const db = new SQLiteCompatibleAPI();
|
|
340
|
-
```
|
|
341
|
-
|
|
342
|
-
## 🔒 Security
|
|
343
|
-
|
|
344
|
-
- **End-to-End Encryption**: All shared data is encrypted
|
|
345
|
-
- **Public Key Infrastructure**: Secure peer identification
|
|
346
|
-
- **Access Control**: Granular permissions and policies
|
|
347
|
-
- **Audit Trail**: Complete logging of all activities
|
|
348
|
-
- **Local-First**: Your data stays on your devices
|
|
349
|
-
- **Payload Sanitization**: Incoming records are scrubbed to neutralize prototype pollution and function injection attempts
|
|
350
|
-
|
|
351
|
-
## 🧪 Testing & Verification
|
|
352
|
-
|
|
353
|
-
PluresDB ships with a unified verification workflow that compiles the TypeScript entry points and runs every Deno test suite (integration, performance, security, and unit).
|
|
354
|
-
|
|
355
|
-
```powershell
|
|
356
|
-
npm run verify
|
|
39
|
+
# Docker
|
|
40
|
+
docker pull pluresdb/pluresdb:latest
|
|
357
41
|
```
|
|
358
42
|
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
43
|
+
## Quick Example
|
|
44
|
+
|
|
45
|
+
```rust
|
|
46
|
+
// Rust
|
|
47
|
+
use pluresdb_core::CrdtStore;
|
|
48
|
+
use pluresdb_storage::{MemoryStorage, StorageEngine};
|
|
49
|
+
use serde_json::json;
|
|
50
|
+
use std::sync::Arc;
|
|
51
|
+
|
|
52
|
+
let storage = Arc::new(MemoryStorage::default());
|
|
53
|
+
let store = CrdtStore::default()
|
|
54
|
+
.with_persistence(storage as Arc<dyn StorageEngine>);
|
|
55
|
+
|
|
56
|
+
store.put("user:1", "actor-a", json!({ "name": "Alice" }));
|
|
57
|
+
let record = store.get("user:1");
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Features
|
|
61
|
+
|
|
62
|
+
- **CRDT Store** — conflict-free replicated data with vector clocks
|
|
63
|
+
- **Native Storage** — sled-backed persistence (WAL, encryption, replay)
|
|
64
|
+
- **Vector Search** — approximate nearest-neighbour via HNSW (cosine similarity)
|
|
65
|
+
- **Auto-Embedding** — pluggable `EmbedText` trait; `FastEmbedder` for local ONNX models
|
|
66
|
+
- **P2P Sync** — Hyperswarm DHT or WebSocket relay, end-to-end encrypted
|
|
67
|
+
- **Local-First** — full functionality offline; sync is opt-in
|
|
68
|
+
- **Multi-Platform** — Node.js (N-API), Deno (JSR), Rust, CLI, Docker, WASM
|
|
69
|
+
- **SQLite optional** — legacy SQL layer via `sqlite-compat` feature flag
|
|
70
|
+
|
|
71
|
+
## Documentation
|
|
72
|
+
|
|
73
|
+
| Document | Description |
|
|
74
|
+
|---|---|
|
|
75
|
+
| [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) | Quick start for Node.js, Deno, Rust, CLI, Docker, Windows |
|
|
76
|
+
| [docs/API.md](docs/API.md) | Complete API reference (Rust, Node.js, Deno, REST, CLI) |
|
|
77
|
+
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Internals: CRDTs, storage, HNSW, P2P protocol |
|
|
78
|
+
| [docs/WINDOWS_GETTING_STARTED.md](docs/WINDOWS_GETTING_STARTED.md) | Windows-specific setup guide |
|
|
79
|
+
| [docs/HYPERSWARM_SYNC.md](docs/HYPERSWARM_SYNC.md) | P2P sync deep-dive |
|
|
80
|
+
| [docs/SYNC_TRANSPORT.md](docs/SYNC_TRANSPORT.md) | Relay transport for corporate networks |
|
|
81
|
+
| [docs/LOCAL_FIRST_INTEGRATION.md](docs/LOCAL_FIRST_INTEGRATION.md) | WASM, Tauri, IPC integration guides |
|
|
82
|
+
| [docs/TESTING.md](docs/TESTING.md) | Test suite and CI notes |
|
|
83
|
+
| [MIGRATION.md](MIGRATION.md) | Upgrade guide: v1.x → v2.0 |
|
|
84
|
+
| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution guide |
|
|
85
|
+
| [CHANGELOG.md](CHANGELOG.md) | Release history |
|
|
86
|
+
| [SECURITY.md](SECURITY.md) | Security policy |
|
|
87
|
+
|
|
88
|
+
## Architecture
|
|
89
|
+
|
|
90
|
+
PluresDB is a Rust-first monorepo:
|
|
91
|
+
|
|
92
|
+
| Crate | Responsibility |
|
|
93
|
+
|---|---|
|
|
94
|
+
| `pluresdb-core` | CRDT store, HNSW vector index, `EmbedText` trait; SQLite optional via `sqlite-compat` |
|
|
95
|
+
| `pluresdb-storage` | Pluggable backends: Sled (WAL, encryption), in-memory |
|
|
96
|
+
| `pluresdb-sync` | `SyncBroadcaster`, `Transport` trait, Hyperswarm / relay / disabled |
|
|
97
|
+
| `pluresdb-cli` | `pluresdb` binary |
|
|
98
|
+
| `pluresdb-node` | N-API bindings for Node.js |
|
|
99
|
+
| `pluresdb-deno` | Deno FFI bindings |
|
|
100
|
+
| `pluresdb-wasm` | `wasm-bindgen` bindings for browsers |
|
|
101
|
+
| `pluresdb-ipc` | Shared-memory IPC server/client |
|
|
102
|
+
| `legacy/` | TypeScript layer (being replaced by Rust crates) |
|
|
103
|
+
|
|
104
|
+
See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for a full description with
|
|
105
|
+
data-flow diagrams.
|
|
106
|
+
|
|
107
|
+
## Testing
|
|
364
108
|
|
|
365
109
|
```bash
|
|
366
|
-
#
|
|
367
|
-
|
|
368
|
-
./deploy.sh --environment test --node-count 3
|
|
369
|
-
|
|
370
|
-
# Run relay tests
|
|
371
|
-
npm run test:azure:relay
|
|
372
|
-
|
|
373
|
-
# Clean up
|
|
374
|
-
./destroy.sh --environment test
|
|
110
|
+
npm run verify # TypeScript build + all Deno tests
|
|
111
|
+
cargo test --workspace # Rust tests
|
|
375
112
|
```
|
|
376
113
|
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
## 📊 Performance
|
|
380
|
-
|
|
381
|
-
- **Vector Search**: Sub-millisecond similarity search
|
|
382
|
-
- **CRDT Sync**: Efficient conflict resolution
|
|
383
|
-
- **Local Storage**: Fast local operations
|
|
384
|
-
- **P2P Sync**: Optimized for bandwidth and latency
|
|
385
|
-
- **Memory Efficient**: Minimal memory footprint
|
|
386
|
-
|
|
387
|
-
## 🌍 Use Cases
|
|
388
|
-
|
|
389
|
-
### Personal Database & Knowledge Management 📝
|
|
390
|
-
|
|
391
|
-
PluresDB is **perfect for personal use on Windows** as a local-first database:
|
|
392
|
-
|
|
393
|
-
- **Digital Journal**: Daily logs, mood tracking, personal reflections
|
|
394
|
-
- **Note-taking System**: Organize notes with tags, relationships, and smart search
|
|
395
|
-
- **Personal Wiki**: Build your own knowledge base with linked concepts
|
|
396
|
-
- **Task Manager**: Track personal and work tasks with custom fields
|
|
397
|
-
- **Research Database**: Collect papers, articles, bookmarks with metadata
|
|
398
|
-
- **Contact Manager**: Store contacts with rich relationships
|
|
399
|
-
- **Recipe Collection**: Searchable recipes with ingredients and ratings
|
|
400
|
-
- **Password Vault**: Encrypted storage for sensitive information
|
|
401
|
-
- **Bookmark Manager**: Save and organize web links with AI-powered search
|
|
402
|
-
|
|
403
|
-
👉 **[Windows Getting Started Guide](docs/WINDOWS_GETTING_STARTED.md)** for personal database setup
|
|
114
|
+
Network-dependent Hyperswarm tests are skipped automatically in CI.
|
|
115
|
+
See [docs/TESTING.md](docs/TESTING.md) for details.
|
|
404
116
|
|
|
405
|
-
|
|
117
|
+
## Distribution
|
|
406
118
|
|
|
407
|
-
- **
|
|
408
|
-
- **
|
|
409
|
-
- **
|
|
410
|
-
- **
|
|
411
|
-
- **
|
|
412
|
-
- **
|
|
119
|
+
- **npm**: [`pluresdb`](https://www.npmjs.com/package/pluresdb)
|
|
120
|
+
- **JSR**: [`@plures/pluresdb`](https://jsr.io/@plures/pluresdb)
|
|
121
|
+
- **crates.io**: [`pluresdb-core`](https://crates.io/crates/pluresdb-core), [`pluresdb-sync`](https://crates.io/crates/pluresdb-sync)
|
|
122
|
+
- **Winget**: `pluresdb.pluresdb`
|
|
123
|
+
- **Docker**: [`pluresdb/pluresdb`](https://hub.docker.com/r/pluresdb/pluresdb)
|
|
124
|
+
- **GitHub Releases**: pre-built binaries for Windows, macOS, Linux
|
|
413
125
|
|
|
414
|
-
##
|
|
126
|
+
## Security
|
|
415
127
|
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
- [VSCode Integration](examples/vscode-extension-integration.ts)
|
|
419
|
-
- [Migration Guide](docs/MIGRATION.md)
|
|
420
|
-
- [P2P Guide](docs/P2P.md)
|
|
128
|
+
All inputs are validated and sanitised. P2P communications are end-to-end
|
|
129
|
+
encrypted. Report vulnerabilities privately — see [SECURITY.md](SECURITY.md).
|
|
421
130
|
|
|
422
|
-
##
|
|
131
|
+
## Contributing
|
|
423
132
|
|
|
424
|
-
|
|
133
|
+
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
134
|
+
All contributions are licensed under AGPL v3.
|
|
425
135
|
|
|
426
|
-
|
|
136
|
+
## License
|
|
427
137
|
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
This project is licensed under the GNU Affero General Public License v3.0 (AGPL v3). This ensures that all modifications to PluresDB remain open source. See [LICENSE](LICENSE) for details.
|
|
431
|
-
|
|
432
|
-
## 🆘 Support
|
|
433
|
-
|
|
434
|
-
- **Issues**: [GitHub Issues](https://github.com/plures/pluresdb/issues)
|
|
435
|
-
- **Discussions**: [GitHub Discussions](https://github.com/plures/pluresdb/discussions)
|
|
436
|
-
|
|
437
|
-
For security issues, please see our [Security Policy](SECURITY.md).
|
|
438
|
-
|
|
439
|
-
## 🙏 Acknowledgments
|
|
440
|
-
|
|
441
|
-
- Built with [Deno](https://deno.land/)
|
|
442
|
-
- Inspired by [Gun.js](https://gun.eco/)
|
|
443
|
-
- Web UI built with [Svelte](https://svelte.dev/)
|
|
444
|
-
- Vector search powered by [HNSW](https://github.com/nmslib/hnswlib)
|
|
138
|
+
GNU Affero General Public License v3.0. See [LICENSE](LICENSE).
|
|
445
139
|
|
|
446
140
|
---
|
|
447
141
|
|
|
448
|
-
**
|
|
449
|
-
|
|
450
|
-
[Get Started](packaging/INSTALLATION.md) | [View Examples](examples/) | [GitHub Discussions](https://github.com/plures/pluresdb/discussions)
|
|
142
|
+
**Built with Rust and TypeScript** 🚀
|
package/crates/README.md
ADDED
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# PluresDB Rust Crates
|
|
2
|
+
|
|
3
|
+
This directory contains all Rust crates for the PluresDB project.
|
|
4
|
+
|
|
5
|
+
## Crates Overview
|
|
6
|
+
|
|
7
|
+
### Main Library Crate (Recommended)
|
|
8
|
+
|
|
9
|
+
- **pluresdb** - Unified main crate that re-exports all core functionality
|
|
10
|
+
|
|
11
|
+
### Core Crates
|
|
12
|
+
|
|
13
|
+
- **pluresdb-core** - Core CRDTs, data structures, and query primitives
|
|
14
|
+
- **pluresdb-sync** - Sync orchestration primitives for PluresDB peers
|
|
15
|
+
- **pluresdb-storage** - Storage abstraction layer with multiple backends
|
|
16
|
+
|
|
17
|
+
### Application Crates
|
|
18
|
+
|
|
19
|
+
- **pluresdb-cli** - Command-line interface for managing PluresDB nodes
|
|
20
|
+
|
|
21
|
+
### Bindings
|
|
22
|
+
|
|
23
|
+
- **pluresdb-node** - Node.js bindings using N-API
|
|
24
|
+
- **pluresdb-deno** - Deno bindings using deno_bindgen FFI
|
|
25
|
+
|
|
26
|
+
## Status
|
|
27
|
+
|
|
28
|
+
| Crate | Status | Registry |
|
|
29
|
+
|-------|--------|----------|
|
|
30
|
+
| pluresdb | ✅ Ready | crates.io |
|
|
31
|
+
| pluresdb-core | ✅ Published | crates.io |
|
|
32
|
+
| pluresdb-sync | ✅ Published | crates.io |
|
|
33
|
+
| pluresdb-storage | ✅ Ready | crates.io |
|
|
34
|
+
| pluresdb-cli | ✅ Ready | crates.io |
|
|
35
|
+
| pluresdb-node | ✅ Ready | npm |
|
|
36
|
+
| pluresdb-deno | ✅ Ready | JSR |
|
|
37
|
+
|
|
38
|
+
## Quick Start
|
|
39
|
+
|
|
40
|
+
### Installing Rust Crates
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
# Install CLI
|
|
44
|
+
cargo install pluresdb-cli
|
|
45
|
+
|
|
46
|
+
# Add main crate to your project (recommended)
|
|
47
|
+
cargo add pluresdb
|
|
48
|
+
|
|
49
|
+
# Or add individual crates if you prefer
|
|
50
|
+
cargo add pluresdb-core
|
|
51
|
+
cargo add pluresdb-storage
|
|
52
|
+
cargo add pluresdb-sync
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Installing Node.js Bindings
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
npm install @plures/pluresdb-native
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### Installing Deno Bindings
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
deno add jsr:@plures/pluresdb
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Building from Source
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
# Build all crates
|
|
71
|
+
cargo build --workspace --release
|
|
72
|
+
|
|
73
|
+
# Build specific crate
|
|
74
|
+
cargo build -p pluresdb-cli --release
|
|
75
|
+
|
|
76
|
+
# Run tests
|
|
77
|
+
cargo test --workspace
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Publishing
|
|
81
|
+
|
|
82
|
+
See [PUBLISHING_GUIDE.md](./PUBLISHING_GUIDE.md) for detailed publishing instructions.
|
|
83
|
+
|
|
84
|
+
## Documentation
|
|
85
|
+
|
|
86
|
+
- [Crate Organization](./CRATE_ORGANIZATION.md) - Guide to choosing the right crate
|
|
87
|
+
- [Implementation Status](./IMPLEMENTATION_STATUS.md)
|
|
88
|
+
- [Completion Summary](./COMPLETION_SUMMARY.md)
|
|
89
|
+
- [Publishing Guide](./PUBLISHING_GUIDE.md)
|
|
90
|
+
- [Next Steps](./NEXT_STEPS.md)
|
|
91
|
+
|
|
92
|
+
## Version
|
|
93
|
+
|
|
94
|
+
All crates use the workspace version: **1.4.2**
|
|
95
|
+
|
|
96
|
+
## License
|
|
97
|
+
|
|
98
|
+
AGPL-3.0
|
|
99
|
+
|