jsql-neo 6.5.11 → 6.5.13

package/lib/xql/src/jsql.js

@@ -0,0 +1,46 @@
+'use strict';
+/**
+ * XQL ↔ JSQL 适配器（浅集成）
+ *
+ * 把 JSQL 表加载成 XQL 集合，只读：加载后可用 XQL 查询与索引，
+ * 不做写回（XQL 目前没有 UPDATE / DELETE / 持久化）。
+ *
+ * 适配任何实现了 `find(table, filter, opts) -> Promise<rows[]>` 的数据库对象
+ * （JSQL 的 NativeJSQL / Database / WASM 均满足）。`find` 有默认 limit=100，
+ * 所以这里自动分页把整表读出来。
+ *
+ * @example
+ * const { xql } = require('@vexify/xql');
+ * const coll = await xql.fromJSQL(db, 'users', {
+ *   indexes: ['id', ['score', 'range']],
+ * });
+ * coll.query("SELECT name FROM users WHERE age > 18 ORDER BY name");
+ */
+
+async function fromJSQL(db, table, opts = {}) {
+  if (!db || typeof db.find !== 'function') {
+    throw new Error('fromJSQL: 需要一个实现了 find(table, filter, opts) 的数据库对象');
+  }
+  const { Collection } = require('../index.js');
+  const pageSize = opts.pageSize || 1000;
+  const rows = [];
+  let offset = 0;
+  for (;;) {
+    const batch = await db.find(table, opts.filter || {}, { limit: pageSize, offset });
+    if (!Array.isArray(batch) || batch.length === 0) break;
+    rows.push(...batch);
+    if (batch.length < pageSize) break;
+    offset += batch.length;
+  }
+  const coll = new Collection(table, rows);
+  if (opts.indexes) {
+    for (const spec of opts.indexes) {
+      const field = Array.isArray(spec) ? spec[0] : spec;
+      const type = Array.isArray(spec) ? spec[1] : null;
+      coll.index(field, type);
+    }
+  }
+  return coll;
+}
+
+module.exports = { fromJSQL };

package/lib/xql/src/parser.js

@@ -0,0 +1,287 @@
+'use strict';
+/**
+ * XQL 解析器（递归下降，产出扁平 AST）
+ *
+ * 支持两种写法，解析成**同一棵 AST**：
+ *   管道式：FROM users |> WHERE age > 18 |> SELECT name |> ORDER BY name |> LIMIT 10
+ *   标准式：SELECT name FROM users WHERE age > 18 ORDER BY name LIMIT 10
+ *
+ * AST 保持扁平（不建深层节点），编译期再决定怎么生成代码。
+ */
+
+const { tokenize } = require('./tokenizer');
+
+class Parser {
+  constructor(src) {
+    this.toks = tokenize(src);
+    this.i = 0;
+  }
+
+  peek(k = 0) { return this.toks[this.i + k] || this.toks[this.toks.length - 1]; }
+  next() { return this.toks[this.i++]; }
+  isKw(v) { const t = this.peek(); return t.t === 'kw' && t.v === v; }
+  isOp(v) { const t = this.peek(); return t.t === 'op' && t.v === v; }
+  eatKw(v) { if (!this.isKw(v)) this.err(`期望关键字 ${v}`); return this.next(); }
+  eatOp(v) { if (!this.isOp(v)) this.err(`期望 '${v}'`); return this.next(); }
+  err(msg) {
+    const t = this.peek();
+    throw new Error(`XQL: ${msg}，位置 ${t.p}${t.v !== null && t.v !== undefined ? `（得到 '${t.v}'）` : ''}`);
+  }
+
+  // ---- 顶层 ----
+  parse() {
+    if (this.isKw('FROM')) return this.parsePipeline();
+    if (this.isKw('SELECT')) return this.parseClassic();
+    this.err('期望 FROM 或 SELECT');
+  }
+
+  /** FROM coll [|> STAGE]... —— 首段 WHERE 允许省略 |>（写 SQL 的人常这么写） */
+  parsePipeline() {
+    this.eatKw('FROM');
+    const q = { source: this.parseSource(), where: null, select: null, orderBy: null, limit: null, offset: null };
+    if (this.isKw('WHERE')) { this.next(); q.where = this.parseExpr(); }
+    for (;;) {
+      if (!this.isOp('|>')) break;
+      this.next();
+      this.parseStage(q);
+    }
+    if (this.peek().t !== 'eof') this.err('语句结束后还有多余内容');
+    return q;
+  }
+
+  /** SELECT list FROM coll [WHERE e] [ORDER BY f] [LIMIT n] [OFFSET n] */
+  parseClassic() {
+    this.eatKw('SELECT');
+    const q = { source: null, where: null, select: this.parseSelectList(), orderBy: null, limit: null, offset: null };
+    this.eatKw('FROM');
+    q.source = this.parseSource();
+    if (this.isKw('WHERE')) { this.next(); q.where = this.parseExpr(); }
+    if (this.isKw('ORDER')) { this.next(); this.eatKw('BY'); q.orderBy = this.parseOrderBy(); }
+    if (this.isKw('LIMIT')) { this.next(); q.limit = this.parseCount(); }
+    if (this.isKw('OFFSET') || this.isKw('SKIP')) { this.next(); q.offset = this.parseCount(); }
+    if (this.peek().t !== 'eof') this.err('语句结束后还有多余内容');
+    return q;
+  }
+
+  parseStage(q) {
+    if (this.isKw('WHERE')) {
+      this.next();
+      const e = this.parseExpr();
+      // 多个 WHERE 用 AND 串起来 —— 管道式里每一段都能加，
+      // 重复出现不该是语法错误
+      q.where = q.where ? { k: 'log', op: 'and', l: q.where, r: e } : e;
+      return;
+    }
+    if (this.isKw('SELECT')) { this.next(); if (q.select) this.err('SELECT 只能出现一次'); q.select = this.parseSelectList(); return; }
+    if (this.isKw('ORDER')) { this.next(); this.eatKw('BY'); if (q.orderBy) this.err('ORDER BY 只能出现一次'); q.orderBy = this.parseOrderBy(); return; }
+    if (this.isKw('LIMIT')) { this.next(); if (q.limit !== null) this.err('LIMIT 只能出现一次'); q.limit = this.parseCount(); return; }
+    if (this.isKw('OFFSET') || this.isKw('SKIP')) { this.next(); q.offset = this.parseCount(); return; }
+    this.err('期望 WHERE / SELECT / ORDER BY / LIMIT / OFFSET');
+  }
+
+  parseSource() {
+    const t = this.peek();
+    if (t.t !== 'id') this.err('期望集合名');
+    this.next();
+    return t.v;
+  }
+
+  parseSelectList() {
+    const list = [];
+    for (;;) {
+      // SELECT *
+      if (this.isOp('*')) { this.next(); list.push({ expr: { k: 'star' }, alias: null }); }
+      else {
+        const expr = this.parseExpr();
+        let alias = null;
+        if (this.isKw('AS')) { this.next(); alias = this.parseIdent(); }
+        else if (this.peek().t === 'id') alias = this.next().v;   // SELECT name n
+        list.push({ expr, alias });
+      }
+      if (!this.isOp(',')) break;
+      this.next();
+    }
+    return list;
+  }
+
+  parseOrderBy() {
+    const list = [];
+    for (;;) {
+      const expr = this.parseExpr();
+      let dir = 'asc';
+      if (this.isKw('ASC')) { this.next(); }
+      else if (this.isKw('DESC')) { this.next(); dir = 'desc'; }
+      list.push({ expr, dir });
+      if (!this.isOp(',')) break;
+      this.next();
+    }
+    return list;
+  }
+
+  parseCount() {
+    const t = this.peek();
+    if (t.t !== 'num') this.err('期望数字');
+    this.next();
+    return t.v;
+  }
+
+  parseIdent() {
+    const t = this.peek();
+    if (t.t !== 'id') this.err('期望标识符');
+    this.next();
+    return t.v;
+  }
+
+  // ---- 表达式（优先级递增）----
+  parseExpr() { return this.parseOr(); }
+
+  parseOr() {
+    let l = this.parseAnd();
+    while (this.isKw('OR')) { this.next(); l = { k: 'log', op: 'or', l, r: this.parseAnd() }; }
+    return l;
+  }
+
+  parseAnd() {
+    let l = this.parseNot();
+    while (this.isKw('AND')) { this.next(); l = { k: 'log', op: 'and', l, r: this.parseNot() }; }
+    return l;
+  }
+
+  parseNot() {
+    if (this.isKw('NOT')) { this.next(); return { k: 'not', e: this.parseNot() }; }
+    return this.parseCmp();
+  }
+
+  parseCmp() {
+    const l = this.parseAdd();
+    const t = this.peek();
+    if (t.t === 'op' && (t.v === '=' || t.v === '==' || t.v === '!=' || t.v === '<' || t.v === '>' || t.v === '<=' || t.v === '>=')) {
+      this.next();
+      return { k: 'bin', op: t.v === '==' ? '=' : t.v, l, r: this.parseAdd() };
+    }
+    if (this.isKw('IS')) {
+      this.next();
+      const neg = this.isKw('NOT');
+      if (neg) this.next();
+      this.eatKw('NULL');
+      return { k: 'isnull', e: l, neg };
+    }
+    if (this.isKw('LIKE')) { this.next(); return { k: 'like', e: l, p: this.parseAdd() }; }
+    // IN / NOT IN
+    if (this.isKw('IN') || (this.isKw('NOT') && this.peek(1).t === 'kw' && this.peek(1).v === 'IN')) {
+      const neg = this.isKw('NOT');
+      if (neg) this.next();
+      this.next();                                  // IN
+      this.eatOp('(');
+      const list = [this.parseExpr()];
+      while (this.isOp(',')) { this.next(); list.push(this.parseExpr()); }
+      this.eatOp(')');
+      return { k: 'in', e: l, list, neg };
+    }
+    if (this.isKw('BETWEEN')) {
+      this.next();
+      const lo = this.parseAdd();
+      this.eatKw('AND');
+      const hi = this.parseAdd();
+      return { k: 'between', e: l, lo, hi };
+    }
+    return l;
+  }
+
+  parseAdd() {
+    let l = this.parseMul();
+    for (;;) {
+      const t = this.peek();
+      if (t.t === 'op' && (t.v === '+' || t.v === '-')) { this.next(); l = { k: 'bin', op: t.v, l, r: this.parseMul() }; }
+      else break;
+    }
+    return l;
+  }
+
+  parseMul() {
+    let l = this.parseUnary();
+    for (;;) {
+      const t = this.peek();
+      if (t.t === 'op' && (t.v === '*' || t.v === '/' || t.v === '%')) { this.next(); l = { k: 'bin', op: t.v, l, r: this.parseUnary() }; }
+      else break;
+    }
+    return l;
+  }
+
+  parseUnary() {
+    if (this.isOp('-')) { this.next(); return { k: 'neg', e: this.parseUnary() }; }
+    if (this.isOp('+')) { this.next(); return this.parseUnary(); }
+    return this.parsePostfix();
+  }
+
+  /** 点号路径与数组下标：a.b.c、a[0]、a.b[1] */
+  parsePostfix() {
+    let e = this.parsePrimary();
+    for (;;) {
+      if (this.isOp('.')) {
+        this.next();
+        const t = this.peek();
+        if (t.t !== 'id' && t.t !== 'kw') this.err('点号后期望字段名');
+        this.next();
+        e = e.k === 'path' ? { k: 'path', segs: e.segs.concat(t.v) } : { k: 'path', segs: [t.v], base: e };
+      } else if (this.isOp('[')) {
+        this.next();
+        const idx = this.parseExpr();
+        this.eatOp(']');
+        e = { k: 'idx', obj: e, idx };
+      } else break;
+    }
+    return e;
+  }
+
+  parsePrimary() {
+    const t = this.peek();
+
+    if (t.t === 'num' || t.t === 'str') { this.next(); return { k: 'lit', v: t.v }; }
+    if (this.isKw('NULL')) { this.next(); return { k: 'lit', v: null }; }
+    if (this.isKw('TRUE')) { this.next(); return { k: 'lit', v: true }; }
+    if (this.isKw('FALSE')) { this.next(); return { k: 'lit', v: false }; }
+
+    if (this.isOp('(')) {
+      this.next();
+      const e = this.parseExpr();
+      this.eatOp(')');
+      return e;
+    }
+
+    // 聚合函数
+    if (t.t === 'kw' && (t.v === 'COUNT' || t.v === 'SUM' || t.v === 'AVG' || t.v === 'MIN' || t.v === 'MAX')) {
+      this.next();
+      this.eatOp('(');
+      let arg;
+      if (this.isOp('*')) { this.next(); arg = { k: 'star' }; }
+      else arg = this.parseExpr();
+      this.eatOp(')');
+      return { k: 'agg', fn: t.v, arg };
+    }
+
+    // 标量函数
+    if (t.t === 'id' && this.peek(1).t === 'op' && this.peek(1).v === '(') {
+      const name = this.next().v;
+      this.eatOp('(');
+      const args = [];
+      if (!this.isOp(')')) {
+        args.push(this.parseExpr());
+        while (this.isOp(',')) { this.next(); args.push(this.parseExpr()); }
+      }
+      this.eatOp(')');
+      return { k: 'call', fn: name.toLowerCase(), args };
+    }
+
+    if (t.t === 'id') { this.next(); return { k: 'path', segs: [t.v] }; }
+
+    this.err('期望表达式');
+  }
+}
+
+function parse(src) {
+  if (typeof src !== 'string' || src.trim() === '') throw new Error('XQL: 查询不能为空');
+  return new Parser(src).parse();
+}
+
+module.exports = { parse, Parser };

package/lib/xql/src/tokenizer.js

@@ -0,0 +1,129 @@
+'use strict';
+/**
+ * XQL 词法分析器
+ *
+ * 设计约束：只做一次扫描，产出扁平 token 数组。
+ * 不分配嵌套结构、不做回溯 —— 词法层省下的每一纳秒都会在编译期还回来。
+ */
+
+const KEYWORDS = new Set([
+  'FROM', 'WHERE', 'SELECT', 'ORDER', 'BY', 'LIMIT', 'OFFSET', 'SKIP',
+  'GROUP', 'HAVING', 'AS', 'ASC', 'DESC', 'AND', 'OR', 'NOT', 'NULL',
+  'TRUE', 'FALSE', 'IN', 'LIKE', 'BETWEEN', 'IS', 'DISTINCT', 'COUNT',
+  'SUM', 'AVG', 'MIN', 'MAX', 'PIPE',
+]);
+
+const OPS = new Set([
+  '=', '==', '!=', '<>', '<', '>', '<=', '>=',
+  '+', '-', '*', '/', '%', '(', ')', ',', '.', '[', ']', '{', '}', ':',
+  '|>', '=>',
+]);
+
+/**
+ * @param {string} src
+ * @returns {Array<{t:string, v:string, p:number}>} t=类型 v=值 p=起始位置
+ */
+function tokenize(src) {
+  const out = [];
+  let i = 0;
+  const n = src.length;
+
+  while (i < n) {
+    const c = src[i];
+
+    // 空白
+    if (c === ' ' || c === '\t' || c === '\n' || c === '\r') { i++; continue; }
+
+    // 注释 -- 与 //
+    if (c === '-' && src[i + 1] === '-') { while (i < n && src[i] !== '\n') i++; continue; }
+    if (c === '/' && src[i + 1] === '/') { while (i < n && src[i] !== '\n') i++; continue; }
+
+    // 管道 |> 必须先于 | 与 > 匹配
+    if (c === '|' && src[i + 1] === '>') { out.push({ t: 'op', v: '|>', p: i }); i += 2; continue; }
+
+    // 字符串（单引号优先，双引号亦可）
+    if (c === "'" || c === '"') {
+      const q = c;
+      let j = i + 1;
+      let s = '';
+      while (j < n) {
+        if (src[j] === '\\' && j + 1 < n) {
+          const e = src[j + 1];
+          s += ({ n: '\n', t: '\t', r: '\r', '0': '\0' })[e] !== undefined ? ({ n: '\n', t: '\t', r: '\r', '0': '\0' })[e] : e;
+          j += 2;
+        } else if (src[j] === q) break;
+        else { s += src[j]; j++; }
+      }
+      if (j >= n) throw new Error(`XQL: 字符串未闭合，位置 ${i}`);
+      out.push({ t: 'str', v: s, p: i });
+      i = j + 1;
+      continue;
+    }
+
+    // 数字（含小数与负号）
+    if ((c >= '0' && c <= '9') || (c === '.' && src[i + 1] >= '0' && src[i + 1] <= '9')) {
+      let j = i;
+      while (j < n && ((src[j] >= '0' && src[j] <= '9') || src[j] === '.')) j++;
+      // 科学计数法
+      if (j < n && (src[j] === 'e' || src[j] === 'E')) {
+        let k = j + 1;
+        if (src[k] === '+' || src[k] === '-') k++;
+        if (src[k] >= '0' && src[k] <= '9') { while (k < n && src[k] >= '0' && src[k] <= '9') k++; j = k; }
+      }
+      out.push({ t: 'num', v: Number(src.slice(i, j)), p: i });
+      i = j;
+      continue;
+    }
+
+    // 负号：前面是操作符/开头时当作数字一部分
+    if (c === '-' && (src[i + 1] >= '0' && src[i + 1] <= '9')) {
+      const prev = out.length ? out[out.length - 1] : null;
+      if (!prev || prev.t === 'op' || (prev.t === 'kw' && prev.v !== 'TRUE' && prev.v !== 'FALSE' && prev.v !== 'NULL')) {
+        let j = i + 1;
+        while (j < n && ((src[j] >= '0' && src[j] <= '9') || src[j] === '.')) j++;
+        out.push({ t: 'num', v: -Number(src.slice(i + 1, j)), p: i });
+        i = j;
+        continue;
+      }
+    }
+
+    // 标识符 / 关键字（含点号路径由 parser 组装）
+    if (/[A-Za-z_$@]/.test(c)) {
+      let j = i;
+      while (j < n && /[A-Za-z0-9_$@]/.test(src[j])) j++;
+      const w = src.slice(i, j);
+      const up = w.toUpperCase();
+      out.push(KEYWORDS.has(up) ? { t: 'kw', v: up, p: i } : { t: 'id', v: w, p: i });
+      i = j;
+      continue;
+    }
+
+    // 反引号标识符
+    if (c === '`') {
+      let j = i + 1;
+      let s = '';
+      while (j < n && src[j] !== '`') { s += src[j]; j++; }
+      if (j >= n) throw new Error(`XQL: 反引号标识符未闭合，位置 ${i}`);
+      out.push({ t: 'id', v: s, p: i });
+      i = j + 1;
+      continue;
+    }
+
+    // 双字符操作符
+    const two = src.slice(i, i + 2);
+    if (two === '<=' || two === '>=' || two === '==' || two === '!=' || two === '<>') {
+      out.push({ t: 'op', v: two === '<>' ? '!=' : two, p: i });
+      i += 2;
+      continue;
+    }
+
+    if (OPS.has(c)) { out.push({ t: 'op', v: c, p: i }); i++; continue; }
+
+    throw new Error(`XQL: 无法识别的字符 '${c}'，位置 ${i}`);
+  }
+
+  out.push({ t: 'eof', v: null, p: n });
+  return out;
+}
+
+module.exports = { tokenize, KEYWORDS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsql-neo",
-  "version": "6.5.11",
+  "version": "6.5.13",
   "description": "JSQL-NEO \u2014 Rust-powered embedded database with WASM, REST API, B-Tree indexes, WAL, crash recovery",
   "main": "index.js",
   "types": "index.d.ts",
@@ -35,6 +35,7 @@
     "index.d.ts",
     "lib/",
     "bin/",
+    "src/",
     "wasm/",
     "native/",
     "nativesrc/",
@@ -46,7 +47,7 @@
   ],
   "scripts": {
     "postinstall": "node postinstall.js",
-    "test": "node test/smoke.js && node test/native.test.js && node test/json-functions.test.js && node test/sql-parser.test.js && node test/readme-audit.test.js && node test/query-opt.test.js && node test/wal-recovery.test.js && node test/mysql-compat-hijack.test.js && node test/dml-constraints.test.js && node test/star-nag.test.js",
+    "test": "node test/smoke.js && node test/native.test.js && node test/json-functions.test.js && node test/sql-parser.test.js && node test/readme-audit.test.js && node test/query-opt.test.js && node test/wal-recovery.test.js && node test/mysql-compat-hijack.test.js && node test/dml-constraints.test.js && node test/star-nag.test.js && node test/plugin-xql.test.js",
     "test:parser": "node test/sql-parser.test.js",
     "test:btree": "node test/btree.test.js",
     "test:native": "node test/native.test.js",

package/src/cli/index.js

@@ -0,0 +1,12 @@
+/**
+ * JSQL CLI — 模块化入口
+ *
+ * 将各子命令拆分为独立模块，bin/jsql 通过此文件加载。
+ * 当前包含: plugin 命令
+ */
+
+const plugin = require('./plugin');
+
+module.exports = {
+  plugin,
+};