jsql-neo 4.2.0 → 4.4.0

package/README.md

@@ -1,9 +1,6 @@
-# JSQL-NEO v4.2.0
+# JSQL-NEO v4.0.1
 
-Rust-powered embedded database with **three engines + SQL + MySQL-compatible server + Redis-style storage** in one npm package.
-
-> **Docs & Help:** [https://help.vexify.top](https://help.vexify.top)  
-> **GitHub:** [https://github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo)
+Rust-powered embedded database with **three engines + SQL + Redis-style storage** in one npm package.
 
 ## Engines
 
@@ -33,54 +30,7 @@ await jsql.executeSQL(db, 'DELETE FROM users WHERE id = 2');
 await db.stop();
 ```
 
-Supported SQL: `CREATE/DROP TABLE` (incl. `IF [NOT] EXISTS`), `CREATE/DROP DATABASE`, `USE` / `SHOW DATABASES` / `SHOW TABLES [FROM db]`, `INSERT` (multi-row, `ON DUPLICATE KEY UPDATE`), `SELECT` (`WHERE` / `ORDER BY` / `LIMIT` / `OFFSET` / `GROUP BY` / `HAVING` / aggregates `COUNT`/`SUM`/`AVG`/`MIN`/`MAX` / `DISTINCT` / `JOIN` / `UNION [ALL]` / `CASE WHEN` / subqueries `IN (…)` & scalar `(SELECT …)` / `BETWEEN`/`LIKE`/`IS NULL`), `UPDATE`, `DELETE`, `BEGIN`/`COMMIT`/`ROLLBACK`, prepared statements with `?` placeholders.
-
-Type names accept MySQL aliases: `INTEGER/INT/BIGINT/TINYINT/SMALLINT`, `STRING/TEXT/VARCHAR(n)/CHAR(n)`, `FLOAT/DOUBLE/REAL/NUMERIC/DECIMAL`, `BOOLEAN/BOOL`, `DATE/DATETIME/TIMESTAMP`, `JSON/OBJECT/ARRAY`.
-
-## MySQL-Compatible Server (multi-database)
-
-A native MySQL protocol server on TCP 3306 — any `mysql` / `mysql2` / GUI client connects directly.
-
-```bash
-npx jsql server start --port 3306 --data-dir ./data        # 后台常驻
-npx jsql server status                                     # 状态
-npx jsql server stop                                       # 停止
-```
-
-**Multi-database & 一键建表:** each database is an independent directory (`<dataDir>/<db>`).
-
-```sql
--- 随意连接即可直接建表（自动落到默认库 default）
-CREATE TABLE users (id INTEGER PRIMARY KEY AUTO_INCREMENT, name VARCHAR(50));
-
--- 一条 SQL 跨库建库+建表（库不存在自动创建）
-CREATE TABLE shop.orders (id INTEGER PRIMARY KEY, amount FLOAT, `user` STRING);
-
--- 连接时指定尚不存在的库会自动创建：mysql -uroot -D mydb
--- 查询/增删改也能带库前缀：INSERT INTO shop.orders ..., SELECT * FROM shop.orders, SHOW TABLES FROM shop;
-```
-
-- 连接指定未存在的库 → **自动建库**，无需先 `CREATE DATABASE`
-- 未 `USE` 任何库 → 落到默认库，可直接 `CREATE TABLE`
-- 全量多库 DDL/DML 支持 `db.table` 点号语法 + `SHOW TABLES FROM db`
-- **多用户 + 库级权限**: 每个用户可配置可访问的数据库白名单（`{ user: { password, databases: [...] } }`）
-
-```json
-{ "port": 3306, "dataDir": "/var/lib/jsql",
-  "auth": { "admin": { "password": "secret", "databases": ["shop", "blog"] }, "reader": "readpass" } }
-```
-
-## Transactions
-
-```js
-db.begin();            // 默认 REPEATABLE_READ：begin 时保存行快照
-db.insert('t', { id: 2 });
-db.rollback();         // 删除新增、还原更新、恢复自增 —— 回滚生效
-db.begin(); db.insert('t', { id: 3 }); db.commit();
-// 也支持 SQL：BEGIN ... COMMIT / ROLLBACK
-```
-
-`begin(isolationLevel)` 可选 `'REPEATABLE_READ'`（快照回滚，默认）或 `'READ_COMMITTED'`（仅回滚自增）。
+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.
 
 ## Redis-Style Storage Modes
 
@@ -154,58 +104,126 @@ db.save();
 | `updateById(table, id, data)` | ✅ | ✅ | ✅ | O(1) PK update |
 | `removeById(table, id)` | ✅ | ✅ | ✅ | O(1) PK delete |
 | `dropTable(name)` | ✅ | ✅ | ✅ | Remove table |
-| `insertMany(table, items)` | ✅ | ✅ | ✅ | Batch insert |
-| `update(table, query, updates)` | ✅ | ✅ | ✅ | Batch update by query |
-| `delete(table, query)` | ✅ | ✅ | ✅ | Batch delete by query |
-| `truncate(table)` | ✅ | ✅ | ✅ | Delete all rows |
-| `begin()/commit()/rollback()` | ✅ | ✅ | ✅ | Transactions (snapshot rollback) |
 | `executeSQL(db, sql, params?)` | ✅ | ✅ | ✅ | Run SQL statements |
 
 ## Schema Field Options
 
 ```js
 {
-  type: 'string' | 'integer' | 'float' | 'boolean' | 'date' | 'object' | 'array',
-  primaryKey: true,       // PK field (auto-indexed) — `primary: true` 也接受
+  type: 'string' | 'integer' | 'float' | 'boolean',
+  primaryKey: true,       // PK field (auto-indexed)
   autoIncrement: true,    // Auto-generate integer PK
-  unique: true,           // Unique constraint (auto-indexed)
   length: 32,             // Max string length
   default: 'value',       // Default value
-  nullable: true,         // Allow null
-  required: true,         // Not-null constraint
-  foreignKey: { table, field, onDelete },  // FK constraint
-  check: (val) => bool,   // CHECK constraint
-  computed: (row) => val  // Computed field
+  nullable: true          // Allow null
 }
 ```
 
+## ORM Compatibility
+
+The MySQL-compatible server mode accepts standard MySQL clients, so popular Node.js ORMs work without a plugin. Tested against a live `createMysqlServer()` instance:
+
+| ORM | Version | Results |
+|-----|---------|---------|
+| [Sequelize](https://sequelize.org) | v6 | ✅ 10/10 — connect, authenticate, sync (CREATE TABLE), create, bulkCreate, find, count, update, destroy, MAX() |
+| [Knex](https://knexjs.org) | v3 | ✅ 9/9 — schema builder, insert, select, where + orderBy, count, update, delete, raw `SELECT VERSION()` |
+| [TypeORM](https://typeorm.io) | v0.3 | ✅ 8/8 — initialize, synchronize, save, findOne, find, count, update, delete |
+
+```js
+// Sequelize
+const { Sequelize, DataTypes } = require('sequelize');
+const sequelize = new Sequelize('default', 'root', '', {
+  host: '127.0.0.1', port: 33306, dialect: 'mysql',
+});
+
+// Knex
+const knex = require('knex')({
+  client: 'mysql2',
+  connection: { host: '127.0.0.1', port: 33306, user: 'root', database: 'default' },
+});
+
+// TypeORM
+const ds = new DataSource({
+  type: 'mysql',
+  host: '127.0.0.1', port: 33306, username: 'root', database: 'default',
+  synchronize: true, entities: [User],
+});
+```
+
+Supported for ORM compatibility: prepared statements (`COM_STMT_PREPARE`/`EXECUTE`), binary protocol result sets, `SHOW COLUMNS` / `SHOW INDEX` / `SHOW CREATE TABLE` / `SHOW VARIABLES` / `SHOW GRANTS`, `information_schema` queries, `START TRANSACTION`, `TRUNCATE TABLE`, `SET` statements, scalar functions (`VERSION()`, `NOW()`, `CONCAT()`, `IFNULL()`, ...), and MySQL DDL forms (`int unsigned`, `auto_increment`, `ENGINE=InnoDB`, `DEFAULT CHARSET`).
+
+## Redis-compatible server
+
+```bash
+jsql redis -p 6379 --data-dir ./redis-data [--auth secret]
+```
+
+or from code:
+
+```js
+const { createRedisServer } = require('jsql-neo');
+createRedisServer({ port: 6379, dataDir: './redis-data' }).listen();
+```
+
+Speaks RESP2 (works with `redis-cli` / ioredis / node-redis). Strings, hashes, lists, sets, counters, TTL, `KEYS`/`EXISTS`/`DEL`, multi-select DBs, `AUTH`, and snapshot persistence to `data.rdb.json` (debounced 500ms + on shutdown).
+
+## Web UI
+
+```bash
+jsql ui -p 8080 --data-dir ./data     # then open http://localhost:8080
+```
+
+or from code: `new WebUI({ port: 8080, dataDir: './data' }).start()`. Zero-dependency management console: browse databases/tables, run SQL in the browser.
+
+## CLI
+
+`jsql serve` (foreground MySQL server), `jsql server start|stop|status` (background daemon), `jsql import <dump.sql|.json|.csv>`, `jsql export <table> <file>`, `jsql bench`, `jsql redis`, `jsql ui`, `jsql mod` (plugin registry), `jsql version`.
+
+## Browser playground
+
+`examples/playground/` is a self-contained SQL playground that runs the full engine in the browser (WASM + IndexedDB, no server):
+
+```bash
+cd examples/playground && npm install && npm run dev
+```
+
+## Testing
+
+```bash
+npm test          # zero-dependency SQL engine smoke tests
+npm run test:orms # ORM compatibility suites (start examples/orms/start-server.js first)
+```
+
+The ORM suites in `examples/orms/` run Sequelize (10/10), Knex (9/9) and TypeORM (8/8) against a live MySQL-compatible server.
+
+## Benchmark
+
+```bash
+cd bench && npm install && npm run bench
+```
+
+`bench/bench.js` compares the four engines on 100k rows (insert / point query / range query / count / update):
+
+| Engine | Insert/s | Point query (500x) | Range query (500x) | Total |
+|--------|----------|--------------------|--------------------|-------|
+| **Native** (Rust N-API) | 0.66M | 930ms | 685ms | **1.77s** |
+| better-sqlite3 (WAL) | 0.40M | 3258ms | 149ms | 3.66s |
+| sql.js (WASM sqlite) | 0.30M | 5852ms | 366ms | 6.57s |
+| Pure JS | 0.38M | 11278ms | 18138ms | 29.7s |
+
+Native is ~2x faster than better-sqlite3 and ~17x faster than the pure-JS engine overall (Linux x64 / Node 24). Full breakdown: `bench/report.md`.
+
 ## Features
 
-**Engines & Storage**
-- Three engines with one shared API: Native (N-API Rust, fastest), WASM (wasm-pack, zero native deps), Pure JS (`Database`)
-- Redis-style storage modes: `memory` / `hybrid` (async flush + LRU eviction + lazy reload) / `disk` (fast flush, memory as cache)
-- Atomic per-table files (`<dir>/<table>.jsql.json` + `meta.json`, tmp + rename)
-- WAL + snapshot crash recovery
-- O(1) primary-key hash index (`FxHashMap` / `Map`) + B-Tree range indexes
-
-**SQL**
-- Full statement coverage: DDL / DML / SELECT (aggregates, `GROUP BY`/`HAVING`, `JOIN`, `UNION`, `CASE WHEN`, subqueries) / transactions
-- Prepared statements with `?` placeholders
-- MySQL type-name aliases + `db.table` cross-database syntax + `SHOW TABLES FROM db`
-
-**MySQL Server & CLI**
-- MySQL protocol server (TCP 3306), compatible with `mysql`/`mysql2`/GUI clients
-- Multi-database (one dir per DB), auto-create on connect / on `db.table` usage, default-DB fallback for one-click `CREATE TABLE`
-- Multi-user authentication with per-database access lists (`1044`/`1049` enforcement)
-- `jsql server start/stop/status` background daemon with graceful shutdown
-
-**Data API**
-- Typed schema with constraints: PK / auto-increment / unique / required / length / default / FK / CHECK / computed fields
-- Batch insert / update / delete, cursor-based pagination, upsert
-- Transactions with snapshot rollback (default `REPEATABLE_READ`)
-- CSV import/export, JSON schema validation, soft delete, versioning, views, triggers, attachable databases
-- Hooks & change events (`beforeInsert`/`afterUpdate`/…) for plugins and audit
-
-**Security**
-- SQL injection hardening: comments/`LOAD_FILE`/dangerous statements blocked by default, ReDoS-safe regex
-- Rate-limited auth (max auth fails), oversized-row protection, safe name/path validation (`..` blocked)
+- Three engines: Native (N-API Rust), WASM (wasm-pack Rust), Pure JS (local JSON)
+- SQL engine with prepared statements
+- Redis-style hybrid/disk storage: memory-first + async flush + LRU eviction + lazy reload
+- O(1) primary key hash index (`FxHashMap` / `Map`)
+- B-Tree indexing for range queries
+- WAL + snapshot crash recovery (server engine)
+- Batch insert / update / delete
+- Cursor-based pagination
+- Transaction support (server engine)
+- Built-in web management UI (`jsql ui` / `new WebUI(...)`): browse databases & tables, run SQL from the browser
+- CLI: `jsql serve|server|import|export|bench|ui|mod|version`
+- Migration tools: mysqldump import, JSON/CSV export/import

package/bin/jsql

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
+const path = require('path');
+const fs = require('fs');
 const yaggs = require('@vexify-org/yaggs');
 const { ModuleManager } = require('../lib/mod');
+const Database = require('../lib/database');
+const migrate = require('../lib/migrate');
 
 function printModules(list) {
   if (list.length === 0) {
@@ -93,6 +97,140 @@ const cli = yaggs()
       fail(e);
     }
   })
+  .command('export', 'Export a table to JSON or CSV', (sub) => {
+    sub.option('db', { type: 'string', description: 'Database file path (default ./db.json)' });
+    sub.option('json', { type: 'boolean', description: 'Output metadata as JSON' });
+  }, async (argv) => {
+    const table = argv._[0];
+    const outFile = argv._[1];
+    const fail = (e) => { console.error(`Error: ${e.message}`); process.exitCode = 1; };
+    try {
+      if (!table || !outFile) throw new Error('Usage: jsql export <table> <file.json|csv> [--db <path>]');
+      const db = new Database(argv.db || './db.json', { autoSave: false });
+      await db.loadDatabase ? db.loadDatabase() : null;
+      const bytes = await migrate.exportToFile(db, table, outFile);
+      if (argv.json) console.log(JSON.stringify({ ok: true, table, file: outFile, bytes }));
+      else console.log(`Exported '${table}' (${bytes} bytes) to ${outFile}`);
+    } catch (e) { fail(e); }
+  })
+  .command('import', 'Import a mysqldump (.sql), JSON (.json) or CSV (.csv) file', (sub) => {
+    sub.option('db', { type: 'string', description: 'Database file path (default ./db.json)' });
+    sub.option('table', { type: 'string', description: 'Target table for CSV import' });
+    sub.option('strict', { type: 'boolean', description: 'Abort on first import error' });
+    sub.option('json', { type: 'boolean', description: 'Output metadata as JSON' });
+  }, async (argv) => {
+    const file = argv._[0];
+    const fail = (e) => { console.error(`Error: ${e.message}`); process.exitCode = 1; };
+    try {
+      if (!file) throw new Error('Usage: jsql import <file.sql|.json|.csv> [--db <path>] [--table <name>]');
+      const db = new Database(argv.db || './db.json', { autoSave: false });
+      await db.loadDatabase ? db.loadDatabase() : null;
+      const ext = path.extname(file).toLowerCase();
+      let result;
+      if (ext === '.sql') {
+        result = await migrate.importDumpFile(db, file, { strict: !!argv.strict });
+      } else if (ext === '.json') {
+        const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+        result = await migrate.importFromJSON(db, data);
+      } else if (ext === '.csv') {
+        if (!argv.table) throw new Error('CSV import requires --table <name>');
+        const schemaFile = file.replace(/\.csv$/i, '.schema.json');
+        const schema = fs.existsSync(schemaFile) ? JSON.parse(fs.readFileSync(schemaFile, 'utf8')) : null;
+        result = await migrate.importFromCSV(db, argv.table, fs.readFileSync(file, 'utf8'), { schema });
+      } else {
+        throw new Error('Unsupported file type: ' + ext);
+      }
+      if (argv.json) {
+        console.log(JSON.stringify({ ok: true, ...result }));
+      } else {
+        const errs = result.errors && result.errors.length;
+        console.log(`Imported: ${result.created ? result.created.length + ' table(s), ' : ''}${result.inserted || 0} row(s)` + (errs ? `, ${errs} error(s)` : ''));
+      }
+    } catch (e) { fail(e); }
+  })
+  .command('serve', 'Run the MySQL-compatible server in the foreground', (sub) => {
+    sub.option('port', { alias: 'p', type: 'number', description: 'Listen port (default 3306)' });
+    sub.option('host', { type: 'string', description: 'Listen host (default 127.0.0.1)' });
+    sub.option('data-dir', { type: 'string', description: 'Directory to store databases' });
+    sub.option('no-auth', { type: 'boolean', description: 'Allow connections without authentication' });
+    sub.option('log', { type: 'boolean', description: 'Log queries to stdout' });
+  }, async (argv) => {
+    const { createMysqlServer } = require('../lib/mysql_server');
+    const options = {
+      port: argv.port != null ? argv.port : 3306,
+      host: argv.host || '127.0.0.1',
+      dataDir: argv['data-dir'],
+      noAuth: argv['no-auth'] === true,
+    };
+    if (argv.log) options.onQuery = (q) => console.log('[sql]', q);
+    const srv = createMysqlServer(options);
+    srv.listen();
+    console.log(`jsql-neo MySQL server on ${options.host}:${options.port}${options.dataDir ? ' (data: ' + options.dataDir + ')' : ' (in-memory)'}`);
+    setInterval(() => {}, 1 << 30);
+  })
+  .command('bench', 'Insert + query benchmark against a data directory', (sub) => {
+    sub.option('n', { type: 'number', description: 'Number of rows (default 10000)' });
+    sub.option('data-dir', { type: 'string', description: 'Data directory (default :memory:)' });
+    sub.option('json', { type: 'boolean', description: 'Output as JSON' });
+  }, async (argv) => {
+    const N = argv.n || 10000;
+    const dataDir = argv['data-dir'] || ':memory:';
+    try {
+      const db = new Database(dataDir === ':memory:' ? ':memory:' : path.join(dataDir, 'bench.json'), { autoSave: false });
+      await db.createTable('bench', { id: { type: 'integer', primaryKey: true, autoIncrement: true }, name: { type: 'string' }, score: { type: 'float' } });
+      let t0 = Date.now();
+      const batch = [];
+      for (let i = 0; i < N; i++) batch.push({ name: 'user_' + i, score: Math.random() * 1000 });
+      for (let i = 0; i < batch.length; i += 1000) await db.insert('bench', batch.slice(i, i + 1000));
+      const insertMs = Date.now() - t0;
+      t0 = Date.now();
+      let hits = 0;
+      for (let i = 0; i < 100; i++) hits += (await db.find('bench', { score: { $gt: 500 } }, { limit: 10 })).length;
+      const queryMs = Date.now() - t0;
+      const total = await db.count('bench');
+      const out = { ok: true, rows: N, inserted: total, insertMs, insertPerSec: Math.round(N / (insertMs / 1000)), queryMs, queryCount: 100 };
+      if (argv.json) console.log(JSON.stringify(out));
+      else console.log(`Inserted ${total} rows in ${insertMs}ms (${out.insertPerSec}/s), 100 queries in ${queryMs}ms`);
+    } catch (e) { console.error(`Error: ${e.message}`); process.exitCode = 1; }
+  })
+  .command('ui', 'Serve the built-in web management console', (sub) => {
+    sub.option('port', { alias: 'p', type: 'number', description: 'HTTP port (default 8080)' });
+    sub.option('host', { type: 'string', description: 'Listen host (default 0.0.0.0)' });
+    sub.option('data-dir', { type: 'string', description: 'Directory containing *.json databases (default .)' });
+    sub.option('readonly', { type: 'boolean', description: 'Never write back to disk' });
+  }, async (argv) => {
+    const { WebUI } = require('../lib/web_ui');
+    const ui = new WebUI({
+      port: argv.port != null ? argv.port : 8080,
+      host: argv.host || '0.0.0.0',
+      dataDir: argv['data-dir'] || '.',
+      readonly: argv.readonly === true,
+    });
+    try {
+      const port = await ui.start();
+      console.log(`JSQL-NEO web UI on http://${argv.host || '0.0.0.0'}:${port} (data: ${ui.dataDir})`);
+      setInterval(() => {}, 1 << 30);
+    } catch (e) { console.error(`Error: ${e.message}`); process.exitCode = 1; }
+  })
+  .command('redis', 'Run the Redis-compatible server', (sub) => {
+    sub.option('port', { alias: 'p', type: 'number', description: 'Listen port (default 6379)' });
+    sub.option('host', { type: 'string', description: 'Listen host (default 127.0.0.1)' });
+    sub.option('data-dir', { type: 'string', description: 'Directory for data.rdb.json snapshot' });
+    sub.option('auth', { type: 'string', description: 'Require this password for AUTH' });
+    sub.option('log', { type: 'boolean', description: 'Log commands to stdout' });
+  }, (argv) => {
+    const { createRedisServer } = require('../lib/redis_server');
+    const srv = createRedisServer({
+      port: argv.port != null ? argv.port : 6379,
+      host: argv.host || '127.0.0.1',
+      dataDir: argv['data-dir'],
+      password: argv.auth || null,
+      onQuery: argv.log ? (c) => console.log('[redis]', c.join(' ')) : null,
+    });
+    srv.listen();
+    console.log(`jsql-neo Redis server on ${argv.host || '127.0.0.1'}:${argv.port != null ? argv.port : 6379}${argv['data-dir'] ? ' (data: ' + argv['data-dir'] + ')' : ''}`);
+    setInterval(() => {}, 1 << 30);
+  })
   .command('version', 'Show version', null, () => {
     console.log(require('../package.json').version);
   })