@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.
Files changed (103) hide show
  1. package/README.md +106 -414
  2. package/crates/README.md +99 -0
  3. package/crates/pluresdb-node/README.md +181 -0
  4. package/crates/pluresdb-node/index.d.ts +0 -0
  5. package/crates/pluresdb-node/index.js +265 -0
  6. package/crates/pluresdb-node/package.json +35 -0
  7. package/dist/napi/index.js +60 -0
  8. package/embedded.d.ts +1 -0
  9. package/embedded.js +46 -0
  10. package/package.json +27 -10
  11. package/dist/.tsbuildinfo +0 -1
  12. package/dist/better-sqlite3-shared.d.ts +0 -12
  13. package/dist/better-sqlite3-shared.d.ts.map +0 -1
  14. package/dist/better-sqlite3-shared.js +0 -143
  15. package/dist/better-sqlite3-shared.js.map +0 -1
  16. package/dist/better-sqlite3.d.ts +0 -4
  17. package/dist/better-sqlite3.d.ts.map +0 -1
  18. package/dist/better-sqlite3.js +0 -8
  19. package/dist/better-sqlite3.js.map +0 -1
  20. package/dist/cli.d.ts +0 -7
  21. package/dist/cli.d.ts.map +0 -1
  22. package/dist/cli.js.map +0 -1
  23. package/dist/node-index.d.ts +0 -148
  24. package/dist/node-index.d.ts.map +0 -1
  25. package/dist/node-index.js +0 -665
  26. package/dist/node-index.js.map +0 -1
  27. package/dist/node-wrapper.d.ts +0 -44
  28. package/dist/node-wrapper.d.ts.map +0 -1
  29. package/dist/node-wrapper.js +0 -296
  30. package/dist/node-wrapper.js.map +0 -1
  31. package/dist/types/index.d.ts +0 -28
  32. package/dist/types/index.d.ts.map +0 -1
  33. package/dist/types/index.js +0 -3
  34. package/dist/types/index.js.map +0 -1
  35. package/dist/types/node-types.d.ts +0 -71
  36. package/dist/types/node-types.d.ts.map +0 -1
  37. package/dist/types/node-types.js +0 -6
  38. package/dist/types/node-types.js.map +0 -1
  39. package/dist/vscode/extension.d.ts +0 -81
  40. package/dist/vscode/extension.d.ts.map +0 -1
  41. package/dist/vscode/extension.js +0 -309
  42. package/dist/vscode/extension.js.map +0 -1
  43. package/examples/basic-usage.d.ts +0 -2
  44. package/examples/basic-usage.d.ts.map +0 -1
  45. package/examples/basic-usage.js +0 -26
  46. package/examples/basic-usage.js.map +0 -1
  47. package/examples/basic-usage.ts +0 -29
  48. package/examples/vscode-extension-example/README.md +0 -95
  49. package/examples/vscode-extension-example/package.json +0 -49
  50. package/examples/vscode-extension-example/src/extension.ts +0 -172
  51. package/examples/vscode-extension-example/tsconfig.json +0 -12
  52. package/examples/vscode-extension-integration.d.ts +0 -31
  53. package/examples/vscode-extension-integration.d.ts.map +0 -1
  54. package/examples/vscode-extension-integration.js +0 -319
  55. package/examples/vscode-extension-integration.js.map +0 -1
  56. package/examples/vscode-extension-integration.ts +0 -41
  57. package/legacy/benchmarks/memory-benchmarks.ts +0 -350
  58. package/legacy/benchmarks/run-benchmarks.ts +0 -315
  59. package/legacy/better-sqlite3-shared.ts +0 -157
  60. package/legacy/better-sqlite3.ts +0 -4
  61. package/legacy/cli.ts +0 -241
  62. package/legacy/config.ts +0 -50
  63. package/legacy/core/crdt.ts +0 -107
  64. package/legacy/core/database.ts +0 -529
  65. package/legacy/healthcheck.ts +0 -162
  66. package/legacy/http/api-server.ts +0 -438
  67. package/legacy/index.ts +0 -28
  68. package/legacy/logic/rules.ts +0 -46
  69. package/legacy/main.rs +0 -3
  70. package/legacy/main.ts +0 -197
  71. package/legacy/network/websocket-server.ts +0 -115
  72. package/legacy/node-index.ts +0 -823
  73. package/legacy/node-wrapper.ts +0 -329
  74. package/legacy/sqlite-compat.ts +0 -633
  75. package/legacy/sqlite3-compat.ts +0 -55
  76. package/legacy/storage/kv-storage.ts +0 -73
  77. package/legacy/tests/core.test.ts +0 -305
  78. package/legacy/tests/fixtures/performance-data.json +0 -71
  79. package/legacy/tests/fixtures/test-data.json +0 -129
  80. package/legacy/tests/integration/api-server.test.ts +0 -334
  81. package/legacy/tests/integration/mesh-network.test.ts +0 -303
  82. package/legacy/tests/logic.test.ts +0 -34
  83. package/legacy/tests/performance/load.test.ts +0 -290
  84. package/legacy/tests/security/input-validation.test.ts +0 -286
  85. package/legacy/tests/unit/core.test.ts +0 -226
  86. package/legacy/tests/unit/subscriptions.test.ts +0 -135
  87. package/legacy/tests/unit/vector-search.test.ts +0 -173
  88. package/legacy/tests/vscode_extension_test.ts +0 -281
  89. package/legacy/types/index.ts +0 -32
  90. package/legacy/types/node-types.ts +0 -80
  91. package/legacy/util/debug.ts +0 -14
  92. package/legacy/vector/index.ts +0 -59
  93. package/legacy/vscode/extension.ts +0 -387
  94. package/scripts/compiled-crud-verify.ts +0 -30
  95. package/scripts/dogfood.ts +0 -297
  96. package/scripts/postinstall.js +0 -156
  97. package/scripts/publish-crates.sh +0 -95
  98. package/scripts/release-check.js +0 -224
  99. package/scripts/run-tests.ts +0 -178
  100. package/scripts/setup-libclang.ps1 +0 -209
  101. package/scripts/update-changelog.js +0 -214
  102. package/web/README.md +0 -27
  103. package/web/svelte/package.json +0 -31
package/README.md CHANGED
@@ -5,446 +5,138 @@
5
5
  [![Deno version](https://img.shields.io/badge/deno-v2.x-blue)](https://deno.land)
6
6
  [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://opensource.org/licenses/AGPL-3.0)
7
7
 
8
- **P2P Graph Database with SQLite Compatibility** - A local-first, offline-first database for modern applications.
8
+ **Local-First P2P Graph Database v2.0**
9
9
 
10
- > 💡 **Perfect for Personal Use on Windows!** PluresDB is ideal for note-taking, knowledge management, personal wikis, task tracking, and more. [Get Started on Windows →](docs/WINDOWS_GETTING_STARTED.md)
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
- ## 🚀 Quick Start
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
- ### Release channels (current)
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
- # npm
29
- npm install pluresdb
30
-
31
- # yarn
32
- yarn add pluresdb
24
+ # Node.js
25
+ npm install @plures/pluresdb
33
26
 
34
- # pnpm
35
- pnpm add pluresdb
36
-
37
- # Deno (JSR)
27
+ # Deno
38
28
  deno add @plures/pluresdb
39
29
 
40
- # Rust (Cargo)
41
- cargo add pluresdb-core pluresdb-storage pluresdb-sync
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
- ## 📦 Installation Methods
33
+ # CLI
34
+ cargo install pluresdb-cli
164
35
 
165
- ### Windows (Personal Database Use)
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
- # Option 2: Using PowerShell installer
174
- irm https://raw.githubusercontent.com/plures/pluresdb/main/install.ps1 | iex
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
- The command executes `tsc -p tsconfig.json` followed by `deno test -A --unstable-kv`, ensuring shipping builds stay green.
360
-
361
- ### Azure Relay Testing
362
-
363
- For testing P2P relay functionality in a cloud environment, PluresDB includes Azure infrastructure automation:
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
- # Deploy test environment with 3 nodes
367
- cd azure/scripts
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
- See [Azure Testing Guide](azure/README.md) and [Quick Start](azure/QUICKSTART.md) for detailed instructions.
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
- ### Application Development 🚀
117
+ ## Distribution
406
118
 
407
- - **VSCode Extensions**: Replace SQLite with P2P capabilities
408
- - **Local-First Apps**: Offline-first applications
409
- - **Collaborative Tools**: Real-time collaboration
410
- - **IoT Applications**: Edge computing and sync
411
- - **Research Projects**: Academic and research data
412
- - **Personal Knowledge Management**: Personal wikis and notes
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
- ## 📚 Documentation
126
+ ## Security
415
127
 
416
- - [Installation Guide](packaging/INSTALLATION.md)
417
- - [API Reference](docs/API.md)
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
- ## 🤝 Contributing
131
+ ## Contributing
423
132
 
424
- We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
133
+ Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
134
+ All contributions are licensed under AGPL v3.
425
135
 
426
- **Note**: By contributing to PluresDB, you agree that your contributions will be licensed under the AGPL v3 license.
136
+ ## License
427
137
 
428
- ## 📄 License
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
- **Ready to build the future of local-first applications?** 🚀
449
-
450
- [Get Started](packaging/INSTALLATION.md) | [View Examples](examples/) | [GitHub Discussions](https://github.com/plures/pluresdb/discussions)
142
+ **Built with Rust and TypeScript** 🚀
@@ -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
+