@plures/pluresdb 1.5.1 โ 1.6.10
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 +174 -290
- package/dist/.tsbuildinfo +1 -1
- package/dist/local-first/unified-api.d.ts +110 -0
- package/dist/local-first/unified-api.d.ts.map +1 -0
- package/dist/local-first/unified-api.js +348 -0
- package/dist/local-first/unified-api.js.map +1 -0
- package/dist/node-index.d.ts +2 -0
- package/dist/node-index.d.ts.map +1 -1
- package/dist/node-index.js +4 -1
- package/dist/node-index.js.map +1 -1
- package/dist/util/debug.d.ts +3 -0
- package/dist/util/debug.d.ts.map +1 -0
- package/dist/util/debug.js +34 -0
- package/dist/util/debug.js.map +1 -0
- package/examples/browser-demo/README.md +204 -0
- package/examples/browser-demo/index.html +466 -0
- package/examples/browser-wasm-integration.md +411 -0
- package/examples/ipc-demo/README.md +127 -0
- package/examples/local-first-usage.ts +138 -0
- package/examples/native-ipc-integration.md +526 -0
- package/examples/tauri-demo/README.md +240 -0
- package/examples/tauri-integration.md +260 -0
- package/legacy/http/api-server.ts +131 -0
- package/legacy/index.ts +3 -0
- package/legacy/local-first/unified-api.ts +449 -0
- package/legacy/node-index.ts +4 -0
- package/legacy/plugins/README.md +181 -0
- package/legacy/plugins/example-embedding-plugin.ts +56 -0
- package/legacy/plugins/plugin-system.ts +315 -0
- package/legacy/tests/unit/local-first-api.test.ts +65 -0
- package/legacy/tests/unit/plugin-system.test.ts +388 -0
- package/legacy/util/debug.ts +14 -1
- package/package.json +8 -2
- package/scripts/release-check.js +34 -0
- package/scripts/validate-npm-publish.js +228 -0
package/README.md
CHANGED
|
@@ -5,88 +5,42 @@
|
|
|
5
5
|
[](https://deno.land)
|
|
6
6
|
[](https://opensource.org/licenses/AGPL-3.0)
|
|
7
7
|
|
|
8
|
-
**
|
|
8
|
+
**Local-First Graph Database with SQLite Compatibility**
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
PluresDB is a CRDT-based graph database that speaks SQLite. Built with Rust for performance and TypeScript for accessibility, it provides SQLite API compatibility while adding graph relationships, vector search, and P2P synchronization. Perfect for desktop applications, VSCode extensions, and personal knowledge management.
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
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
|
|
12
|
+
> ๐ก **Ideal for Windows Desktop Apps**: Drop-in SQLite replacement with graph capabilities, vector search, and a comprehensive web UI. [Get Started on Windows โ](docs/WINDOWS_GETTING_STARTED.md)
|
|
22
13
|
|
|
23
|
-
|
|
14
|
+
## ๐ Quick Start
|
|
24
15
|
|
|
25
16
|
### Install
|
|
26
17
|
|
|
27
18
|
```bash
|
|
28
|
-
# npm
|
|
19
|
+
# Node.js / npm
|
|
29
20
|
npm install pluresdb
|
|
30
21
|
|
|
31
|
-
#
|
|
32
|
-
yarn add pluresdb
|
|
33
|
-
|
|
34
|
-
# pnpm
|
|
35
|
-
pnpm add pluresdb
|
|
36
|
-
|
|
37
|
-
# Deno (JSR)
|
|
22
|
+
# Deno
|
|
38
23
|
deno add @plures/pluresdb
|
|
39
24
|
|
|
40
|
-
# Rust
|
|
41
|
-
cargo add pluresdb-core pluresdb-storage
|
|
42
|
-
|
|
43
|
-
# Docker
|
|
44
|
-
docker pull pluresdb/pluresdb:latest
|
|
25
|
+
# Rust
|
|
26
|
+
cargo add pluresdb-core pluresdb-storage
|
|
45
27
|
|
|
46
28
|
# Windows (Winget)
|
|
47
29
|
winget install pluresdb.pluresdb
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
### Development Prerequisites (Rust Components)
|
|
51
30
|
|
|
52
|
-
|
|
53
|
-
|
|
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
|
|
31
|
+
# Docker
|
|
32
|
+
docker pull pluresdb/pluresdb:latest
|
|
75
33
|
```
|
|
76
34
|
|
|
77
|
-
###
|
|
35
|
+
### Use It
|
|
78
36
|
|
|
79
37
|
```typescript
|
|
80
38
|
import { PluresNode, SQLiteCompatibleAPI } from "pluresdb";
|
|
81
39
|
|
|
82
40
|
// Start the database
|
|
83
41
|
const db = new PluresNode({
|
|
84
|
-
config: {
|
|
85
|
-
|
|
86
|
-
host: "localhost",
|
|
87
|
-
dataDir: "./data",
|
|
88
|
-
},
|
|
89
|
-
autoStart: true,
|
|
42
|
+
config: { port: 34567, dataDir: "./data" },
|
|
43
|
+
autoStart: true
|
|
90
44
|
});
|
|
91
45
|
|
|
92
46
|
// Use SQLite-compatible API
|
|
@@ -94,18 +48,14 @@ const sqlite = new SQLiteCompatibleAPI();
|
|
|
94
48
|
|
|
95
49
|
// Create tables
|
|
96
50
|
await sqlite.exec(`
|
|
97
|
-
CREATE TABLE users (
|
|
98
|
-
id INTEGER PRIMARY KEY,
|
|
99
|
-
name TEXT,
|
|
100
|
-
email TEXT
|
|
101
|
-
)
|
|
51
|
+
CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)
|
|
102
52
|
`);
|
|
103
53
|
|
|
104
54
|
// Insert data
|
|
105
|
-
await sqlite.run(
|
|
106
|
-
"
|
|
107
|
-
"
|
|
108
|
-
|
|
55
|
+
await sqlite.run(
|
|
56
|
+
"INSERT INTO users (name, email) VALUES (?, ?)",
|
|
57
|
+
["Alice", "alice@example.com"]
|
|
58
|
+
);
|
|
109
59
|
|
|
110
60
|
// Query data
|
|
111
61
|
const users = await sqlite.all("SELECT * FROM users");
|
|
@@ -114,337 +64,271 @@ const users = await sqlite.all("SELECT * FROM users");
|
|
|
114
64
|
const results = await sqlite.vectorSearch("machine learning", 10);
|
|
115
65
|
```
|
|
116
66
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
```ts
|
|
120
|
-
import { GunDB, startApiServer } from "jsr:@plures/pluresdb";
|
|
121
|
-
|
|
122
|
-
const db = new GunDB();
|
|
123
|
-
await db.ready();
|
|
67
|
+
## ๐ฏ What PluresDB Does
|
|
124
68
|
|
|
125
|
-
|
|
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
|
-
```
|
|
69
|
+
### Core Capabilities
|
|
137
70
|
|
|
138
|
-
|
|
71
|
+
- **SQLite Compatibility**: Drop in for SQLite with 95% API compatibility
|
|
72
|
+
- **Graph Relationships**: Store and query connected data with CRDT conflict resolution
|
|
73
|
+
- **Vector Search**: Semantic similarity search with HNSW indexing
|
|
74
|
+
- **Local-First**: Runs entirely on your machine, syncs when you want
|
|
75
|
+
- **P2P Sync**: Encrypted data sharing across devices without servers
|
|
76
|
+
- **Web UI**: 24-tab management interface for data exploration
|
|
139
77
|
|
|
140
|
-
###
|
|
78
|
+
### Built For
|
|
141
79
|
|
|
142
|
-
- **
|
|
143
|
-
- **
|
|
144
|
-
- **
|
|
145
|
-
- **
|
|
146
|
-
- **
|
|
80
|
+
- **Desktop Applications**: Embedded database with graph and vector capabilities
|
|
81
|
+
- **VSCode Extensions**: SQLite-compatible storage with enhanced features
|
|
82
|
+
- **Knowledge Management**: Personal wikis, note-taking, research databases
|
|
83
|
+
- **Offline-First Apps**: Full functionality without network connectivity
|
|
84
|
+
- **Prototyping**: Quick database setup with TypeScript/Rust support
|
|
147
85
|
|
|
148
|
-
|
|
86
|
+
## ๐ How to Use PluresDB
|
|
149
87
|
|
|
150
|
-
|
|
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
|
|
88
|
+
### For Node.js Applications
|
|
154
89
|
|
|
155
|
-
|
|
90
|
+
```typescript
|
|
91
|
+
import { SQLiteCompatibleAPI } from "pluresdb";
|
|
156
92
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
- **REST API**: Full REST API for web applications
|
|
161
|
-
- **WebSocket API**: Real-time updates and synchronization
|
|
93
|
+
const db = new SQLiteCompatibleAPI({
|
|
94
|
+
config: { dataDir: "./data" }
|
|
95
|
+
});
|
|
162
96
|
|
|
163
|
-
|
|
97
|
+
// Use familiar SQLite methods
|
|
98
|
+
await db.exec("CREATE TABLE ...");
|
|
99
|
+
await db.run("INSERT INTO ...", params);
|
|
100
|
+
const rows = await db.all("SELECT ...");
|
|
101
|
+
```
|
|
164
102
|
|
|
165
|
-
###
|
|
103
|
+
### For Deno Applications
|
|
166
104
|
|
|
167
|
-
|
|
105
|
+
```typescript
|
|
106
|
+
import { GunDB, startApiServer } from "jsr:@plures/pluresdb";
|
|
168
107
|
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
winget install pluresdb.pluresdb
|
|
108
|
+
const db = new GunDB();
|
|
109
|
+
await db.ready();
|
|
172
110
|
|
|
173
|
-
|
|
174
|
-
|
|
111
|
+
db.serve({ port: 34567 });
|
|
112
|
+
const api = startApiServer({ port: 8080, db });
|
|
175
113
|
|
|
176
|
-
|
|
177
|
-
|
|
114
|
+
await db.put("user:alice", { name: "Alice" });
|
|
115
|
+
const user = await db.get("user:alice");
|
|
178
116
|
```
|
|
179
117
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
### Package Managers
|
|
118
|
+
### For Rust Applications
|
|
183
119
|
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
brew install plures/pluresdb/pluresdb
|
|
120
|
+
```rust
|
|
121
|
+
use pluresdb_core::{Database, DatabaseOptions};
|
|
187
122
|
|
|
188
|
-
|
|
189
|
-
|
|
123
|
+
let db = Database::open(
|
|
124
|
+
DatabaseOptions::with_file("./data/plures.db")
|
|
125
|
+
.create_if_missing(true)
|
|
126
|
+
)?;
|
|
190
127
|
|
|
191
|
-
|
|
192
|
-
|
|
128
|
+
db.put("user:1", json!({"name": "Alice"}))?;
|
|
129
|
+
let user = db.get("user:1")?;
|
|
193
130
|
```
|
|
194
131
|
|
|
195
|
-
###
|
|
196
|
-
|
|
197
|
-
```bash
|
|
198
|
-
docker pull plures/pluresdb:latest
|
|
199
|
-
docker run -p 34567:34567 -p 34568:34568 plures/pluresdb:latest
|
|
200
|
-
```
|
|
132
|
+
### For VSCode Extensions
|
|
201
133
|
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
Perfect for VSCode extensions that currently use SQLite:
|
|
134
|
+
Replace SQLite in your VSCode extension with PluresDB:
|
|
205
135
|
|
|
206
136
|
```typescript
|
|
207
137
|
import { SQLiteCompatibleAPI } from "pluresdb";
|
|
208
138
|
|
|
209
139
|
export function activate(context: vscode.ExtensionContext) {
|
|
210
|
-
// Replace your SQLite database with PluresDB
|
|
211
140
|
const db = new SQLiteCompatibleAPI({
|
|
212
141
|
config: {
|
|
213
|
-
dataDir: path.join(context.globalStorageUri.fsPath, "pluresdb")
|
|
214
|
-
}
|
|
142
|
+
dataDir: path.join(context.globalStorageUri.fsPath, "pluresdb")
|
|
143
|
+
}
|
|
215
144
|
});
|
|
216
145
|
|
|
217
|
-
//
|
|
146
|
+
// Same SQLite API, enhanced capabilities
|
|
218
147
|
await db.exec("CREATE TABLE settings (key TEXT, value TEXT)");
|
|
219
148
|
await db.run("INSERT INTO settings VALUES (?, ?)", ["theme", "dark"]);
|
|
220
|
-
const settings = await db.all("SELECT * FROM settings");
|
|
221
149
|
}
|
|
222
150
|
```
|
|
223
151
|
|
|
224
|
-
## ๐ Web
|
|
152
|
+
## ๐ Web Interface
|
|
225
153
|
|
|
226
|
-
|
|
154
|
+
PluresDB includes a comprehensive Svelte-based web UI at `http://localhost:34568`:
|
|
227
155
|
|
|
228
|
-
- **Data Explorer**: Browse and
|
|
229
|
-
- **Graph Visualization**: Interactive graph
|
|
230
|
-
- **Vector Search**: Semantic search
|
|
231
|
-
- **
|
|
232
|
-
- **
|
|
233
|
-
- **
|
|
156
|
+
- **Data Explorer**: Browse, edit, and manage your data with JSON editing
|
|
157
|
+
- **Graph Visualization**: Interactive Cytoscape.js graph views
|
|
158
|
+
- **Vector Search UI**: Semantic search with similarity scoring
|
|
159
|
+
- **Type Management**: Define schemas and validate data
|
|
160
|
+
- **P2P Controls**: Manage peers, encryption, and cross-device sync
|
|
161
|
+
- **Performance Monitoring**: Real-time metrics and profiling
|
|
162
|
+
- **History & Time Travel**: Version history with diff and restore
|
|
234
163
|
|
|
235
|
-
## ๐ API
|
|
164
|
+
## ๐ API Options
|
|
236
165
|
|
|
237
166
|
### SQLite-Compatible API
|
|
238
167
|
|
|
239
168
|
```typescript
|
|
240
169
|
// Database operations
|
|
241
|
-
await sqlite.exec(sql);
|
|
242
|
-
await sqlite.run(sql, params);
|
|
243
|
-
await sqlite.get(sql, params);
|
|
244
|
-
await sqlite.all(sql, params);
|
|
170
|
+
await sqlite.exec(sql); // Execute SQL
|
|
171
|
+
await sqlite.run(sql, params); // Run with parameters
|
|
172
|
+
await sqlite.get(sql, params); // Get single row
|
|
173
|
+
await sqlite.all(sql, params); // Get all rows
|
|
245
174
|
|
|
246
175
|
// Key-value operations
|
|
247
|
-
await sqlite.put(key, value);
|
|
248
|
-
await sqlite.getValue(key);
|
|
249
|
-
await sqlite.delete(key);
|
|
176
|
+
await sqlite.put(key, value); // Store data
|
|
177
|
+
await sqlite.getValue(key); // Retrieve data
|
|
178
|
+
await sqlite.delete(key); // Remove data
|
|
250
179
|
|
|
251
180
|
// Vector search
|
|
252
|
-
await sqlite.vectorSearch(query, limit);
|
|
181
|
+
await sqlite.vectorSearch(query, limit); // Semantic search
|
|
253
182
|
```
|
|
254
183
|
|
|
255
184
|
### better-sqlite3-Compatible API
|
|
256
185
|
|
|
257
|
-
|
|
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.
|
|
186
|
+
For synchronous-style ergonomics:
|
|
263
187
|
|
|
264
188
|
```typescript
|
|
265
189
|
import Database from "pluresdb/better-sqlite3";
|
|
266
190
|
|
|
267
191
|
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
192
|
|
|
272
193
|
const insert = db.prepare("INSERT INTO users (name) VALUES (?)");
|
|
273
194
|
await insert.run("Ada Lovelace");
|
|
274
195
|
|
|
275
|
-
const select = db.prepare("SELECT
|
|
276
|
-
const
|
|
196
|
+
const select = db.prepare("SELECT * FROM users");
|
|
197
|
+
const users = await select.all();
|
|
277
198
|
```
|
|
278
199
|
|
|
279
|
-
|
|
280
|
-
`.raw()`, `.pluck()`, and `.expand(true)` for dotted column names.
|
|
200
|
+
### REST API
|
|
281
201
|
|
|
282
|
-
```
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
202
|
+
```bash
|
|
203
|
+
# Create/update node
|
|
204
|
+
curl -X POST http://localhost:34567/api/put \
|
|
205
|
+
-H "Content-Type: application/json" \
|
|
206
|
+
-d '{"id": "user:1", "data": {"name": "Alice"}}'
|
|
286
207
|
|
|
287
|
-
|
|
208
|
+
# Retrieve node
|
|
209
|
+
curl http://localhost:34567/api/get?id=user:1
|
|
288
210
|
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
for (const user of users) {
|
|
292
|
-
await insert.run(user.name);
|
|
293
|
-
}
|
|
294
|
-
});
|
|
211
|
+
# Delete node
|
|
212
|
+
curl -X DELETE http://localhost:34567/api/delete?id=user:1
|
|
295
213
|
|
|
296
|
-
|
|
214
|
+
# List all nodes
|
|
215
|
+
curl http://localhost:34567/api/list
|
|
216
|
+
|
|
217
|
+
# Vector search
|
|
218
|
+
curl -X POST http://localhost:34567/api/search \
|
|
219
|
+
-H "Content-Type: application/json" \
|
|
220
|
+
-d '{"query": "machine learning", "limit": 10}'
|
|
297
221
|
```
|
|
298
222
|
|
|
299
|
-
###
|
|
223
|
+
### Local-First APIs
|
|
300
224
|
|
|
301
|
-
|
|
302
|
-
// Identity management
|
|
303
|
-
await db.createIdentity({ name: "John", email: "john@example.com" });
|
|
304
|
-
await db.searchPeers("developer");
|
|
225
|
+
PluresDB provides production-ready Rust implementations for local-first integration:
|
|
305
226
|
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
227
|
+
**WASM (Browser)** - Rust implementation complete, use directly:
|
|
228
|
+
```javascript
|
|
229
|
+
// Via wasm-bindgen (compile from source)
|
|
230
|
+
import { PluresDBBrowser } from "./pluresdb-wasm/pkg";
|
|
231
|
+
const db = new PluresDBBrowser("my-app");
|
|
232
|
+
await db.init_persistence();
|
|
233
|
+
await db.put("user:1", { name: "Alice" });
|
|
234
|
+
```
|
|
309
235
|
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
236
|
+
**Tauri (Desktop Apps)**
|
|
237
|
+
```rust
|
|
238
|
+
#[tauri::command]
|
|
239
|
+
async fn db_put(state: State<'_, AppState>, id: String, data: Value) -> Result<String> {
|
|
240
|
+
state.db.lock().put(id, data)
|
|
241
|
+
}
|
|
313
242
|
```
|
|
314
243
|
|
|
315
|
-
|
|
244
|
+
**IPC (Native Apps)**
|
|
245
|
+
```rust
|
|
246
|
+
let mut server = IPCServer::new("my-app", store)?;
|
|
247
|
+
server.start()?;
|
|
248
|
+
// Client connects via shared memory
|
|
249
|
+
```
|
|
316
250
|
|
|
317
|
-
|
|
251
|
+
See [Local-First Integration](docs/LOCAL_FIRST_INTEGRATION.md) for complete guides.
|
|
318
252
|
|
|
319
|
-
|
|
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.
|
|
253
|
+
## ๐๏ธ Architecture
|
|
322
254
|
|
|
323
|
-
|
|
255
|
+
PluresDB is built as a Rust-first monorepo:
|
|
324
256
|
|
|
325
|
-
|
|
257
|
+
- **`crates/pluresdb-core`**: CRDT storage engine
|
|
258
|
+
- **`crates/pluresdb-storage`**: Storage backends (Sled, SQLite, RocksDB)
|
|
259
|
+
- **`crates/pluresdb-sync`**: P2P synchronization
|
|
260
|
+
- **`crates/pluresdb-cli`**: Command-line interface
|
|
261
|
+
- **`crates/pluresdb-wasm`**: WebAssembly bindings
|
|
262
|
+
- **`crates/pluresdb-ipc`**: IPC shared memory
|
|
263
|
+
- **`legacy/`**: TypeScript/Node.js/Deno implementations
|
|
264
|
+
- **`web/svelte/`**: Web UI components
|
|
326
265
|
|
|
327
|
-
|
|
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
|
|
266
|
+
## ๐ฆ Distribution
|
|
331
267
|
|
|
332
|
-
|
|
333
|
-
// Before (SQLite)
|
|
334
|
-
import sqlite3 from "sqlite3";
|
|
335
|
-
const db = new sqlite3.Database("./data.db");
|
|
268
|
+
PluresDB is available through multiple channels:
|
|
336
269
|
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
270
|
+
- **npm**: [`pluresdb`](https://www.npmjs.com/package/pluresdb) - Node.js package
|
|
271
|
+
- **JSR**: [`@plures/pluresdb`](https://jsr.io/@plures/pluresdb) - Deno module
|
|
272
|
+
- **crates.io**: Rust crates ([pluresdb-core](https://crates.io/crates/pluresdb-core), [pluresdb-storage](https://crates.io/crates/pluresdb-storage), [pluresdb-sync](https://crates.io/crates/pluresdb-sync))
|
|
273
|
+
- **Winget**: `pluresdb.pluresdb` - Windows package manager
|
|
274
|
+
- **Docker Hub**: [`pluresdb/pluresdb`](https://hub.docker.com/r/pluresdb/pluresdb) - Container images
|
|
275
|
+
- **GitHub Releases**: Pre-built binaries for Windows, macOS, Linux
|
|
341
276
|
|
|
342
277
|
## ๐ Security
|
|
343
278
|
|
|
344
|
-
|
|
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
|
|
279
|
+
PluresDB implements comprehensive security measures:
|
|
350
280
|
|
|
351
|
-
|
|
281
|
+
- **Input Validation**: All user inputs are validated and sanitized
|
|
282
|
+
- **Prototype Pollution Protection**: Safe object handling
|
|
283
|
+
- **Audit Logging**: Complete operation logs
|
|
284
|
+
- **Local Storage**: Data stays on your machine by default
|
|
285
|
+
- **End-to-End Encryption**: Secure P2P synchronization
|
|
286
|
+
- **AGPL v3 License**: Ensures modifications remain open source
|
|
352
287
|
|
|
353
|
-
|
|
288
|
+
Report security issues privately via our [Security Policy](SECURITY.md).
|
|
354
289
|
|
|
355
|
-
|
|
356
|
-
npm run verify
|
|
357
|
-
```
|
|
290
|
+
## ๐ Performance
|
|
358
291
|
|
|
359
|
-
|
|
292
|
+
- **CRDT Operations**: Efficient conflict-free data structures in Rust
|
|
293
|
+
- **Vector Search**: HNSW-based similarity search
|
|
294
|
+
- **Storage Backends**: Sled, SQLite, or RocksDB
|
|
295
|
+
- **Local Operations**: ~5-10ms REST API latency
|
|
296
|
+
- **Zero Network**: Full functionality without internet
|
|
360
297
|
|
|
361
|
-
|
|
298
|
+
## ๐งช Testing
|
|
362
299
|
|
|
363
|
-
|
|
300
|
+
Run the comprehensive test suite:
|
|
364
301
|
|
|
365
302
|
```bash
|
|
366
|
-
|
|
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
|
|
303
|
+
npm run verify
|
|
375
304
|
```
|
|
376
305
|
|
|
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
|
|
404
|
-
|
|
405
|
-
### Application Development ๐
|
|
406
|
-
|
|
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
|
|
306
|
+
This executes TypeScript compilation and all Deno test suites (unit, integration, performance, security).
|
|
413
307
|
|
|
414
308
|
## ๐ Documentation
|
|
415
309
|
|
|
416
|
-
- [
|
|
417
|
-
- [
|
|
418
|
-
- [VSCode
|
|
419
|
-
- [
|
|
420
|
-
- [
|
|
310
|
+
- [Windows Getting Started Guide](docs/WINDOWS_GETTING_STARTED.md)
|
|
311
|
+
- [Local-First Integration](docs/LOCAL_FIRST_INTEGRATION.md)
|
|
312
|
+
- [VSCode Extension Example](examples/vscode-extension-integration.ts)
|
|
313
|
+
- [Contributing Guide](CONTRIBUTING.md)
|
|
314
|
+
- [CHANGELOG](CHANGELOG.md)
|
|
421
315
|
|
|
422
316
|
## ๐ค Contributing
|
|
423
317
|
|
|
424
|
-
|
|
318
|
+
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
|
425
319
|
|
|
426
|
-
|
|
320
|
+
All contributions are licensed under AGPL v3.
|
|
427
321
|
|
|
428
322
|
## ๐ License
|
|
429
323
|
|
|
430
|
-
|
|
324
|
+
GNU Affero General Public License v3.0 (AGPL v3). See [LICENSE](LICENSE) for details.
|
|
431
325
|
|
|
432
326
|
## ๐ Support
|
|
433
327
|
|
|
434
328
|
- **Issues**: [GitHub Issues](https://github.com/plures/pluresdb/issues)
|
|
435
329
|
- **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)
|
|
330
|
+
- **Security**: [Security Policy](SECURITY.md)
|
|
445
331
|
|
|
446
332
|
---
|
|
447
333
|
|
|
448
|
-
**
|
|
449
|
-
|
|
450
|
-
[Get Started](packaging/INSTALLATION.md) | [View Examples](examples/) | [GitHub Discussions](https://github.com/plures/pluresdb/discussions)
|
|
334
|
+
**Built with Rust and TypeScript** ๐
|