jsql-neo 6.5.11 → 6.5.13

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.11** — stable release · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
+> **v6.5.13** — 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.11 — Rust-Powered Embedded Database (WASM + HTTP)
+ * JSQL-NEO v6.5.13 — Rust-Powered Embedded Database (WASM + HTTP)
  *
  * @example
  * const jsql = require('jsql-neo');

package/lib/database.js

@@ -1668,12 +1668,19 @@ class Database {
             const pluginName = manifest.name || entry.name;
             // 查找入口文件：manifest.main || manifest.entry || 'index.js'
             const entryFile = manifest.main || manifest.entry || 'index.js';
-            // 兼容两种路径：根级 + plugins/ 子目录
+            // 兼容三种布局：
+            //   1. entry 是仓库相对路径（如 "plugins/xql/index.js"）且文件在根级 → basename
+            //   2. entry 是根级相对路径（如 "index.js"）且文件在根级
+            //   3. plugins/ 子目录（旧布局）
             const candidates = [
                 path.join(dir, entryFile),
                 path.join(dir, entryFile + '.js'),
+                path.join(dir, path.basename(entryFile)),
+                path.join(dir, path.basename(entryFile) + '.js'),
                 path.join(dir, 'plugins', entryFile),
                 path.join(dir, 'plugins', entryFile + '.js'),
+                path.join(dir, 'plugins', path.basename(entryFile)),
+                path.join(dir, 'plugins', path.basename(entryFile) + '.js'),
             ];
             let entryPath = null;
             for (const c of candidates) {

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/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.