jsql-neo 4.0.0 → 4.0.1

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 (2) hide show
  1. package/README.md +68 -56
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,78 +1,101 @@
1
- # JSQL-NEO v3.4.3
1
+ # JSQL-NEO v4.0.1
2
2
 
3
- Rust-powered embedded database with **three engines** in one npm package.
3
+ Rust-powered embedded database with **three engines + SQL + Redis-style storage** in one npm package.
4
4
 
5
5
  ## Engines
6
6
 
7
- | Engine | Entry | Use Case | Speed |
8
- |--------|-------|----------|-------|
9
- | **WASM** (Rust → wasm-pack) | `JSQL` | Zero native deps, Node.js | 1.4M rows/sec insert |
10
- | **HTTP** (Rust actix-web) | `HttpJSQL` | Multi-process / remote | 340K rows/sec insert |
11
- | **Pure JS** (Database class) | `Database` | Local JSON file, SQLite-like | 617K rows/sec insert |
7
+ | Engine | Entry | Use Case |
8
+ |--------|-------|----------|
9
+ | **Native** (Rust → N-API, fastest) | `NativeJSQL` | Node.js, best performance |
10
+ | **WASM** (Rust → wasm-pack, zero native deps) | `JSQL` | Node.js / browsers, no native addon |
11
+ | **Pure JS** (local JSON file, SQLite-like) | `Database` | Local file persistence, legacy API |
12
12
 
13
- ## Quick Start
13
+ All engines share the same API (`createTable` / `insert` / `findById` / `find` / `updateById` / `removeById` / `dropTable`) plus `executeSQL()`.
14
14
 
15
- ### WASM (no server, zero deps)
15
+ ## SQL
16
16
 
17
17
  ```js
18
- const { JSQL } = require('jsql-neo');
18
+ const jsql = require('jsql-neo');
19
+ const db = new jsql.NativeJSQL();
20
+ await db.start();
21
+
22
+ await jsql.executeSQL(db, 'CREATE TABLE users (id INTEGER PRIMARY KEY AUTO_INCREMENT, name STRING, age INTEGER)');
23
+ await jsql.executeSQL(db, "INSERT INTO users (name, age) VALUES ('Alice', 30), ('Bob', 25)");
24
+ await jsql.executeSQL(db, "INSERT INTO users VALUES (5, 'Carol', 35) ON DUPLICATE KEY UPDATE age = 30");
25
+ const r = await jsql.executeSQL(db, 'SELECT name, age FROM users WHERE age > 26 ORDER BY age DESC');
26
+ // → rows: [["Carol",35],["Alice",30]]
27
+
28
+ await jsql.executeSQL(db, 'UPDATE users SET age = 31 WHERE id = 1');
29
+ await jsql.executeSQL(db, 'DELETE FROM users WHERE id = 2');
30
+ await db.stop();
31
+ ```
19
32
 
20
- const db = new JSQL();
33
+ Supported: `CREATE/DROP TABLE`, `INSERT` (multi-row, `ON DUPLICATE KEY UPDATE`), `SELECT` (`WHERE`/`ORDER BY`/`LIMIT`/`OFFSET`/`GROUP BY`/`HAVING`/aggregates), `UPDATE`, `DELETE`, prepared statements with `?` placeholders.
34
+
35
+ ## Redis-Style Storage Modes
36
+
37
+ Native and Pure JS engines support three persistence modes (Redis-compatible model: memory-first, async flush, LRU eviction, lazy reload):
38
+
39
+ ```js
40
+ const db = new jsql.NativeJSQL({
41
+ path: '/var/lib/jsql', // storage directory (required for hybrid/disk)
42
+ mode: 'hybrid', // 'memory' (default) | 'hybrid' | 'disk'
43
+ memReserveMB: 512, // keep 512MB RAM headroom before evicting
44
+ flushInterval: 200, // ms between async flushes (hybrid 200 / disk 50)
45
+ evictInterval: 1000, // ms between memory-pressure checks
46
+ });
47
+ await db.start();
48
+ ```
49
+
50
+ - **`memory`** — pure in-memory (default, no path needed)
51
+ - **`hybrid`** — writes go to memory first, async incremental flush to disk; cold tables are LRU-evicted when memory pressure exceeds `total - memReserveMB`, and lazily reloaded on next access
52
+ - **`disk`** — fast flush (50ms), memory acts as read/write cache
53
+
54
+ Data is stored per-table as `<dir>/<table>.jsql.json` + `meta.json`; writes are atomic (tmp + rename).
55
+
56
+ ```js
57
+ // Pure JS engine (same options)
58
+ const db2 = new jsql.Database({ path: '/var/lib/jsql', mode: 'hybrid' });
59
+ ```
60
+
61
+ ## Quick Start
62
+
63
+ ### Native (fastest)
64
+
65
+ ```js
66
+ const { NativeJSQL } = require('jsql-neo');
67
+ const db = new NativeJSQL();
21
68
  await db.start();
22
69
 
23
70
  await db.createTable('users', {
24
71
  name: { type: 'string' },
25
72
  age: { type: 'integer' }
26
73
  });
27
-
28
74
  const [id] = await db.insert('users', { name: 'Alice', age: 30 });
29
75
  const user = await db.findById('users', id);
30
76
  // → { id: 1, fields: { name: 'Alice', age: 30 }, created_at: '...', updated_at: '...' }
31
-
32
77
  await db.stop();
33
78
  ```
34
79
 
35
- ### Pure JS (local file, SQLite-like)
80
+ ### Pure JS (local file)
36
81
 
37
82
  ```js
38
83
  const { Database } = require('jsql-neo');
39
-
40
- const db = new Database('/tmp/mydb.json');
84
+ const db = new Database('/tmp/mydb.json'); // or { path, mode } for hybrid/disk
41
85
  const users = db.createTable('users', {
42
86
  id: { type: 'integer', autoIncrement: true, primaryKey: true },
43
87
  name: { type: 'string', length: 32 },
44
88
  age: { type: 'integer' }
45
89
  });
46
-
47
90
  const ids = users.insertMany([{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }]);
48
91
  users.updateById(ids[0], { age: 31 });
49
- const user = users.findById(ids[0]);
50
92
  db.save();
51
93
  ```
52
94
 
53
- ### HTTP Server
54
-
55
- ```bash
56
- JSQL_DATA_DIR=/tmp/jsql-neo npx jsql-neo
57
- ```
58
-
59
- ```js
60
- const { HttpJSQL } = require('jsql-neo');
61
-
62
- const db = new HttpJSQL({ host: '127.0.0.1', port: 6379 });
63
- await db.start();
64
-
65
- await db.createTable('users', { name: { type: 'string' }, age: { type: 'integer' } });
66
- const [id] = await db.insert('users', { name: 'Alice', age: 30 });
67
- const user = await db.findById('users', id);
68
-
69
- await db.stop();
70
- ```
71
-
72
95
  ## API
73
96
 
74
- | Method | WASM | HTTP | Pure JS | Description |
75
- |--------|------|------|---------|-------------|
97
+ | Method | Native | WASM | Pure JS | Description |
98
+ |--------|--------|------|---------|-------------|
76
99
  | `createTable(name, schema)` | ✅ | ✅ | ✅ | Define table with typed fields |
77
100
  | `insert(table, data)` | ✅ | ✅ | ✅ | Insert row(s), returns IDs |
78
101
  | `findById(table, id)` | ✅ | ✅ | ✅ | O(1) PK lookup |
@@ -81,19 +104,7 @@ await db.stop();
81
104
  | `updateById(table, id, data)` | ✅ | ✅ | ✅ | O(1) PK update |
82
105
  | `removeById(table, id)` | ✅ | ✅ | ✅ | O(1) PK delete |
83
106
  | `dropTable(name)` | ✅ | ✅ | ✅ | Remove table |
84
-
85
- All engines share the same async API for CRUD operations.
86
-
87
- ## Performance (Pure JS, 100K rows)
88
-
89
- | Operation | Time | Rate |
90
- |-----------|------|------|
91
- | Insert 100K | 128 ms | 781K rows/sec |
92
- | findById × 10,000 | 3 ms | 0.3 μs each |
93
- | updateById × 10,000 | 82 ms | 8.2 μs each (O(1) hash index) |
94
- | count × 100 | 0 ms | — |
95
- | findAll × 5 | 16 ms | — |
96
- | Filtered query × 100 | 407 ms | — |
107
+ | `executeSQL(db, sql, params?)` | ✅ | ✅ | ✅ | Run SQL statements |
97
108
 
98
109
  ## Schema Field Options
99
110
 
@@ -110,11 +121,12 @@ All engines share the same async API for CRUD operations.
110
121
 
111
122
  ## Features
112
123
 
113
- - Three engines: WASM (native Rust), HTTP (actix-web), Pure JS (local JSON)
124
+ - Three engines: Native (N-API Rust), WASM (wasm-pack Rust), Pure JS (local JSON)
125
+ - SQL engine with prepared statements
126
+ - Redis-style hybrid/disk storage: memory-first + async flush + LRU eviction + lazy reload
114
127
  - O(1) primary key hash index (`FxHashMap` / `Map`)
115
128
  - B-Tree indexing for range queries
116
- - WAL + snapshot crash recovery (HTTP engine)
117
- - Strings Pool for memory-efficient storage
129
+ - WAL + snapshot crash recovery (server engine)
118
130
  - Batch insert / update / delete
119
131
  - Cursor-based pagination
120
- - Transaction support (HTTP engine)
132
+ - Transaction support (server engine)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "jsql-neo",
3
- "version": "4.0.0",
3
+ "version": "4.0.1",
4
4
  "description": "JSQL-NEO — Rust-powered embedded database with WASM, REST API, B-Tree indexes, WAL, crash recovery",
5
5
  "main": "index.js",
6
6
  "bin": {