jsql-neo 6.5.10 → 6.5.12

package/README.md

@@ -3,7 +3,7 @@
 > **One engine to rule them all** — a Rust-powered embedded database that speaks your language:
 > MySQL, PostgreSQL, MongoDB, Redis, SQL, TypeScript, **and the browser**.
 
-> **v6.5.10** — stable release · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
+> **v6.5.12** — stable release · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
 
 ![Engines](https://img.shields.io/badge/engines-Native%20%7C%20WASM%20%7C%20Pure%20JS-7ee787)
 ![MySQL](https://img.shields.io/badge/protocol-MySQL%20compatible-1f6feb)
@@ -16,6 +16,17 @@
 
 ---
 
+## Demo
+
+![JSQL-NEO terminal demo](doc/demo.gif)
+
+A real `jsql tui` session: joins, NULL semantics, exact 64-bit integers, and
+savepoint rollback.
+
+[MP4 version](doc/demo.mp4) · [asciinema recording](doc/demo.cast)
+
+---
+
 ## 🚀 Quick Start
 
 ### One-line install
@@ -160,6 +171,33 @@ await db.start();
 
 ---
 
+## ✨ XQL 集成
+
+用 [XQL](https://github.com/vexify-org/XQL) 查询 JSQL 表：把 SQL 直接接到文档上，
+支持等值 hash 索引与范围 range 索引，速度不低于手写 JS 循环，并支持管道式语法。
+
+```js
+const { NativeJSQL } = require('jsql-neo');
+const db = new NativeJSQL();
+await db.start();
+
+db.use(require('jsql-neo/lib/plugins').xql());
+
+// 标准 SQL
+const rows = await db.xql('SELECT name FROM users WHERE age > 18 ORDER BY name');
+// 管道式（同样的语义）
+const pipe = await db.xql('FROM users |> WHERE age > 18 |> SELECT name |> ORDER BY name');
+
+// 索引：等值 → hash 索引 O(1)，范围 → 有序索引 O(log n + k)
+db.xqlIndex('users', 'id');
+db.xqlIndex('users', 'score', 'range');
+```
+
+写入（INSERT / UPDATE / DELETE）后 XQL 缓存自动失效、下次查询重建；XQL 只读，
+不做写回——数据的唯一权威仍是 JSQL 引擎。详见 [PLUGINS.md](PLUGINS.md#xql-插件)。
+
+---
+
 ## 📖 Documentation
 
 Detailed docs live in `doc/` — click to read.

package/index.d.ts

@@ -115,6 +115,22 @@ declare namespace JSQLNeo {
     query(sql: string, paramsOrOpts?: unknown[] | Record<string, unknown>, opts?: Record<string, unknown>): Promise<any>;
     exists(table: string, filter?: Record<string, unknown>): Promise<boolean>;
     prepare(sql: string): PreparedStatement;
+
+    // ── xql 插件（db.use('xql') 后可用）─────────────────────
+    /** 用 XQL 查询（自动加载源表）。opts.table 可显式指定数据源。 */
+    xql(sql: string, opts?: { table?: string }): Promise<Row[]>;
+    /** 显式加载一张表成 XQL 集合 */
+    xqlLoad(table: string): Promise<unknown>;
+    /** 强制重建某表的 XQL 集合 */
+    xqlRefresh(table: string): Promise<unknown>;
+    /** 运行时建索引（type 缺省按字段类型猜，'range' 为有序索引） */
+    xqlIndex(table: string, field: string, type?: 'hash' | 'range'): this;
+    /** 已加载的 XQL 集合名 */
+    xqlTables(): string[];
+    /** 取某表的 XQL 集合（未加载返回 null） */
+    xqlCollection(table: string): unknown | null;
+    /** 清缓存（不传清全部） */
+    xqlClear(table?: string): this;
   }
 
   export interface PreparedStatement {

package/index.js

@@ -1,5 +1,5 @@
 /**
- * JSQL-NEO v6.5.10 — Rust-Powered Embedded Database (WASM + HTTP)
+ * JSQL-NEO v6.5.12 — Rust-Powered Embedded Database (WASM + HTTP)
  *
  * @example
  * const jsql = require('jsql-neo');

package/lib/plugins/index.js

@@ -16,6 +16,7 @@ const { createLogger } = require('./logger');
 const { createMetrics } = require('./metrics');
 const { createAudit } = require('./audit');
 const { createValidation } = require('./validation');
+const { createXql } = require('./xql');
 
 /** 名称 → 插件工厂 */
 const builtins = {
@@ -23,7 +24,8 @@ const builtins = {
   logger: createLogger,
   metrics: createMetrics,
   audit: createAudit,
-  validation: createValidation
+  validation: createValidation,
+  xql: createXql
 };
 
 /** 内置插件名清单 */
@@ -60,11 +62,13 @@ module.exports = {
   createMetrics,
   createAudit,
   createValidation,
+  createXql,
   timestamps: createTimestamps,
   logger: createLogger,
   metrics: createMetrics,
   audit: createAudit,
   validation: createValidation,
+  xql: createXql,
   builtins,
   list,
   create,

package/lib/plugins/xql.js

@@ -0,0 +1,163 @@
+/**
+ * xql —— 用 XQL（eXtend Query Language）查询 JSQL 表
+ *
+ * XQL 把 SQL 直接接到 JS 文档上：支持等值 hash 索引与范围 range 索引，
+ * 查询速度不低于手写 JS 循环，并支持管道式语法（FROM t |> WHERE … |> LIMIT n）。
+ *
+ * 本插件把 JSQL 表加载成 XQL 集合（自动分页读全表），写入时标记失效、
+ * 下次查询重建，从而在 JSQL 之上获得 XQL 的管道语法与索引。XQL 只读，
+ * 不做写回——数据的唯一权威仍然是 JSQL 引擎本身。
+ *
+ * @example
+ * db.use(require('jsql-neo/lib/plugins').xql());
+ *
+ * await db.xql('SELECT name FROM users WHERE age > 18 ORDER BY name');
+ * await db.xql('FROM users |> WHERE age > 18 |> SELECT name |> ORDER BY name');
+ * db.xqlIndex('users', 'id');               // 等值 → hash 索引，O(1)
+ * db.xqlIndex('users', 'score', 'range');   // 范围 → range 索引
+ *
+ * @example 自动建索引 + 显式加载
+ * db.use(require('jsql-neo/lib/plugins').xql({
+ *   indexes: { users: ['id', ['score', 'range']] },
+ *   pageSize: 2000,
+ * }));
+ * await db.xqlLoad('users');
+ */
+const { definePlugin } = require('../plugin');
+
+/** 规整索引配置：'id' | ['score','range'] → ['id', null] | ['score','range'] */
+function normalizeIndexSpecs(specs) {
+  return (specs || []).map(s => Array.isArray(s) ? [s[0], s[1] || null] : [s, null]);
+}
+
+/** 记录索引规格（去重，按字段名） */
+function recordIndexSpec(state, table, field, type) {
+  const list = state.indexSpecs[table] || (state.indexSpecs[table] = []);
+  const exists = list.some(s => (Array.isArray(s) ? s[0] : s) === field);
+  if (!exists) list.push(type ? [field, type] : field);
+}
+
+function createXql(opts = {}) {
+  const pageSize = opts.pageSize || 1000;
+  const autoLoad = opts.autoLoad !== false;
+  const getXql = opts.xql || (() => require('../xql'));
+
+  return definePlugin('xql', {
+    config: { pageSize, autoLoad, indexes: opts.indexes || {} },
+    install(engine, ctx) {
+      const state = {
+        collections: new Map(),   // table -> Collection
+        dirty: new Set(),         // table 需要重建
+        indexSpecs: Object.assign({}, opts.indexes || {}),
+      };
+      ctx.store.set('xql', state);
+
+      const load = async (table) => {
+        const rows = [];
+        let offset = 0;
+        for (;;) {
+          const batch = await engine.find(table, {}, { limit: pageSize, offset });
+          if (!Array.isArray(batch) || batch.length === 0) break;
+          rows.push(...batch);
+          if (batch.length < pageSize) break;
+          offset += batch.length;
+        }
+        const xql = getXql();
+        const coll = new xql.Collection(table, rows);
+        for (const [field, type] of normalizeIndexSpecs(state.indexSpecs[table])) {
+          coll.index(field, type);
+        }
+        state.collections.set(table, coll);
+        state.dirty.delete(table);
+        return coll;
+      };
+
+      const ensure = async (table) => {
+        const has = state.collections.has(table);
+        if (!has && !autoLoad) {
+          throw new Error(`xql: 表 '${table}' 未加载 —— 先 db.xqlLoad('${table}')`);
+        }
+        if (!has || state.dirty.has(table)) return load(table);
+        return state.collections.get(table);
+      };
+
+      const invalidate = (table) => {
+        if (state.collections.has(table)) state.dirty.add(table);
+      };
+
+      // 写入 → 缓存失效（native 只有 beforeUpdate/beforeDelete 会触发，
+      // afterInsert 全引擎都有；用 before* 让三种引擎行为一致）
+      ctx.on('afterInsert', (t) => invalidate(t));
+      ctx.on('beforeUpdate', (t) => invalidate(t));
+      ctx.on('beforeDelete', (t) => invalidate(t));
+      ctx.on('afterDropTable', (t) => {
+        state.collections.delete(t);
+        state.dirty.delete(t);
+      });
+      ctx.on('onStop', () => {
+        state.collections.clear();
+        state.dirty.clear();
+      });
+
+      const api = {
+        version: getXql().version,
+
+        /** 用 XQL 查询（自动加载源表）。opts.table 可显式指定数据源。 */
+        async query(sql, opts = {}) {
+          const xql = getXql();
+          const src = opts.table || xql.compile(sql).__source;
+          const coll = await ensure(src);
+          return coll.query(sql);
+        },
+
+        /** 显式加载一张表成 XQL 集合（含配置的索引） */
+        load(table) { return load(table); },
+
+        /** 强制重建某张表的 XQL 集合 */
+        refresh(table) {
+          state.dirty.add(table);
+          return load(table);
+        },
+
+        /** 给表建索引（运行时）。等值不传 type → hash，传 'range' → 有序索引。 */
+        index(table, field, type) {
+          recordIndexSpec(state, table, field, type);
+          const c = state.collections.get(table);
+          if (c) c.index(field, type);
+          return engine;
+        },
+
+        /** 已加载的 XQL 集合名 */
+        tables() { return Array.from(state.collections.keys()); },
+
+        /** 取某表的 XQL 集合（未加载返回 null） */
+        collection(table) { return state.collections.get(table) || null; },
+
+        /** 清空缓存（可指定表；不传清全部） */
+        clear(table) {
+          if (table) {
+            state.collections.delete(table);
+            state.dirty.delete(table);
+          } else {
+            state.collections.clear();
+            state.dirty.clear();
+          }
+          return engine;
+        },
+      };
+
+      ctx.expose(api);
+
+      // 便捷方法直接挂到引擎上：db.xql / db.xqlIndex / …
+      engine.xql = api.query;
+      engine.xqlLoad = api.load;
+      engine.xqlRefresh = api.refresh;
+      engine.xqlIndex = api.index;
+      engine.xqlTables = api.tables;
+      engine.xqlCollection = api.collection;
+      engine.xqlClear = api.clear;
+    },
+  });
+}
+
+module.exports = { createXql, xql: createXql };

package/lib/sql.js

@@ -708,6 +708,11 @@ class Parser {
         break;
       } else {
         const col = this.parseTableName();
+        // 重复列名必须报错：对象键覆盖会静默丢列（schema[col] = def 直接覆盖），
+        // 用户 CREATE TABLE d(a INT, a INT) 会悄悄变成单列 a。
+        if (schema[col] !== undefined) {
+          throw new Error(`Duplicate column name '${col}' in table '${name}'`);
+        }
         const def = this.parseColumnDef();
         schema[col] = def;
         if (def.primaryKey) hasPk = true;
@@ -755,6 +760,8 @@ class Parser {
     const mapped = typeMap[type];
     if (!mapped) throw new Error(`Unsupported column type: ${typeTok.value}`);
     def.type = mapped;
+    // JSON / JSONB 列保留原始标记，供数据层校验非法 JSON（{bad json 这类字符串会被 JSON.parse 拒绝）
+    if (type === 'json' || type === 'jsonb') def.jsonType = true;
     if (/^(BIG)?SERIAL$/i.test(typeRaw)) { def.autoIncrement = true; def.required = true; }
 
     // 长度限制: TEXT(255) / VARCHAR(100) / INTEGER(11) ...
@@ -3110,10 +3117,6 @@ function resolveOperand(operand, row, ctx) {
     // 布尔类节点出现在"取值"位置时（如 IF(status = 'paid', ...)、SUM(IF(a > b,1,0))），
     // 求值成 true/false 供上层按真值判断
     case 'compare':
-    case 'and':
-    case 'or':
-    case 'xor':
-    case 'not':
     case 'in':
     case 'isNull':
     case 'isTruth':
@@ -3122,6 +3125,25 @@ function resolveOperand(operand, row, ctx) {
     case 'like':
     case 'between':
       return evaluateExpr(operand, row, ctx);
+    case 'and': {
+      const a = sqlTruthy(resolveOperand(operand.left, row, ctx));
+      const b = sqlTruthy(resolveOperand(operand.right, row, ctx));
+      return sqlAnd(a, b);
+    }
+    case 'or': {
+      const a = sqlTruthy(resolveOperand(operand.left, row, ctx));
+      const b = sqlTruthy(resolveOperand(operand.right, row, ctx));
+      return sqlOr(a, b);
+    }
+    case 'xor': {
+      const a = sqlTruthy(resolveOperand(operand.left, row, ctx));
+      const b = sqlTruthy(resolveOperand(operand.right, row, ctx));
+      return sqlXor(a, b);
+    }
+    case 'not': {
+      const v = sqlTruthy(resolveOperand(operand.expr, row, ctx));
+      return v === null ? null : (v ? 0 : 1);
+    }
     case 'unit': {
       // 裸时间单位（MONTH / DAY …）：优先当列取，取不到就返回单位名本身
       const lower = String(operand.name).toLowerCase();
@@ -4422,6 +4444,33 @@ function ciCompare(a, b, cs) {
   return as === bs ? 0 : (as < bs ? -1 : 1);
 }
 
+// ── 三值逻辑（SQL 标准：TRUE / FALSE / UNKNOWN）──────────────────────
+// NULL 参与布尔运算时结果不是 0/1，而是 UNKNOWN（用 null 表示）。
+// 此前 resolveOperand 没有 and/or/xor/not 分支，SELECT TRUE AND TRUE 落到
+// default 返回 undefined → 数值化成 0，所有布尔表达式全部失效。
+function sqlTruthy(v) {
+  if (v === null || v === undefined) return null;
+  if (typeof v === 'boolean') return v;
+  if (typeof v === 'number') return v !== 0;
+  if (typeof v === 'string') return v !== '' && !(Number(v) === 0 && String(v).trim() !== '');
+  return Boolean(v);
+}
+// 三值真值表，入参已归一化为 true / false / null，返回 1 / 0 / null
+function sqlAnd(a, b) {
+  if (a === false || b === false) return 0;
+  if (a === null || b === null) return null;
+  return 1;
+}
+function sqlOr(a, b) {
+  if (a === true || b === true) return 1;
+  if (a === null || b === null) return null;
+  return 0;
+}
+function sqlXor(a, b) {
+  if (a === null || b === null) return null;
+  return a !== b ? 1 : 0;
+}
+
 function evaluateExpr(expr, row, ctx) {
   if (expr === null || expr === undefined) return false;
   switch (expr.type) {
@@ -6347,6 +6396,18 @@ class SQLExecutor {
     walk(statement.where);
     walk(statement.having);
     walk(statement.orderBy);
+    // ORDER BY 的列在解析器里是裸字符串（非 {type:'column'} 对象），walk 检不到。
+    // 字符串可能是输出别名/位置序号（已在 known 里豁免），也可能是真实列；
+    // 两者都不是 → 必须报错（此前静默忽略，用户 ORDER BY nonexistent_col 拿到原序）。
+    if (Array.isArray(statement.orderBy)) {
+      for (const o of statement.orderBy) {
+        const c = o && o.column;
+        if (typeof c !== 'string') continue; // 位置序号（数字）跳过
+        const n = c.toLowerCase();
+        const base = n.indexOf('.') >= 0 ? n.slice(n.indexOf('.') + 1) : n;
+        if (!known.has(n) && !known.has(base)) throw new Error(`no such column: ${c}`);
+      }
+    }
     if (Array.isArray(statement.groupBy)) {
       // groupBy 是列名字符串数组
       for (const g of statement.groupBy) {
@@ -7876,6 +7937,30 @@ async function inferColumnTypes(engine, stmt, r) {
   });
 }
 
+// 结果里的大整数（> MAX_SAFE_INTEGER 的 BigInt）在 JSON.stringify / wasm 绑定下
+// 无法序列化（"Do not know how to serialize a BigInt"）。输出前递归转成字符串，
+// 保留精度且可序列化；内部运算仍走 BigInt，精度不丢。
+function finalizeBigInts(value, seen) {
+  if (typeof value === 'bigint') return value.toString();
+  if (Array.isArray(value)) {
+    if (!seen) seen = new Set();
+    if (seen.has(value)) return value;
+    seen.add(value);
+    for (let i = 0; i < value.length; i++) value[i] = finalizeBigInts(value[i], seen);
+    return value;
+  }
+  if (value && typeof value === 'object') {
+    // Buffer / Date / RegExp 等特殊对象不深入（Buffer 是 Uint8Array，逐字节递归会爆栈）
+    if (value instanceof Buffer || value instanceof Date || value instanceof RegExp) return value;
+    if (!seen) seen = new Set();
+    if (seen.has(value)) return value;
+    seen.add(value);
+    for (const k of Object.keys(value)) value[k] = finalizeBigInts(value[k], seen);
+    return value;
+  }
+  return value;
+}
+
 async function executeSQL(engine, sql, paramsOrOpts, opts = {}) {
   // 参数守卫：engine 必须是引擎对象，sql 必须是字符串。误用时报清晰错误，
   // 而不是在后续像 `reading 'length'` 那样抛出令人费解的 TypeError。
@@ -7934,6 +8019,7 @@ async function executeSQL(engine, sql, paramsOrOpts, opts = {}) {
     let r = await executor.execute(stmt);
     const durationMs = Number(process.hrtime.bigint() - t0) / 1e6;
     r = buildResultEnvelope(stmt, r, Math.round(durationMs * 1000) / 1000);
+    r = finalizeBigInts(r);
     if (r && r.columns && r.columnTypes === undefined) {
       r.columnTypes = await inferColumnTypes(engine, stmt, r);
     }

package/lib/table.js

@@ -1543,6 +1543,11 @@ class Table {
                 else if (typeof v === 'number' || typeof v === 'boolean' || v instanceof Date) result[field] = String(v);
                 else if (Buffer.isBuffer(v)) result[field] = v.toString('utf8');
                 else throw createError('ER_TRUNCATED_WRONG_VALUE', t, v);
+            } else if ((t === 'object' || t === 'array' || t === 'json') && (def.jsonType || t === 'json')) {
+                // JSON / JSONB 列：字符串形式必须是合法 JSON（{bad json 这类会被 JSON.parse 拒绝）
+                if (typeof v === 'string') {
+                    try { JSON.parse(v); } catch (e) { throw createError('ER_TRUNCATED_WRONG_VALUE', t, v); }
+                }
             }
         }
         return result;

package/lib/wasm_client.js

@@ -561,6 +561,18 @@ class JSQL {
     // 难以定位的 "Cannot convert undefined or null to object"，这里直接给明确 TypeError
     const arr = Array.isArray(data) ? data : [data];
     arr.forEach((row, i) => assertRowObject(row, i, arr.length > 1 || Array.isArray(data)));
+    // JSON / JSONB 列：字符串形式必须是合法 JSON（{bad json 这类会被 JSON.parse 拒绝）
+    const schema = this._schemas[table];
+    if (schema) {
+      for (const row of arr) {
+        for (const [f, def] of Object.entries(schema)) {
+          if (def && def.jsonType && typeof row[f] === 'string') {
+            try { JSON.parse(row[f]); }
+            catch (e) { throw new Error(`Truncated incorrect object value: '${row[f]}'`); }
+          }
+        }
+      }
+    }
     if (!(await this._runHooks('beforeInsert', [table, arr]))) return [];
     if (arr.length > 1) {
       await this._flush();

package/lib/xql/NOTICE

@@ -0,0 +1,16 @@
+XQL — eXtend Query Language
+Copyright 2026 Vexify
+
+This product includes software developed at Vexify.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.