build: 重建 dist（插件 priority 生效 + 静态连接池类型 + 常量注释修正）

dist/metona-sqlark.cjs

@@ -16623,9 +16623,22 @@ class MetonaSqlark {
         // 初始化执行器和事务管理器
         this.executor = new QueryExecutor(this.engine, this.maxRowsPerQuery);
         this.transactionManager = new TransactionManager(this.engine);
-        // 注册插件
+        // 注册插件。
+        //
+        // v0.8.0：**先按 priority 降序排序再注册** —— 在这之前 PluginManager.register
+        // 虽然会把插件插到正确的位置，但 `install()` 是在 register 里**立即**调用的，
+        // 因此 install 与钩子的实际执行顺序仍等于 config 数组顺序
+        //（实测：priority 为 low/high/mid 的插件，钩子按 low→high→mid 触发，
+        //  只有 getPlugins() 才是 high,mid,low）。而 README/CONTRIBUTING 一直宣称
+        // "priority 越大越先执行" —— 文档与实现不符。
+        // 这里选择**让实现符合文档**（priority 是用户可见的配置项，静默无效比没有更糟）。
+        // 用稳定排序：同优先级保持 config 数组中的相对顺序。
         if (this.config.plugins) {
-            for (const plugin of this.config.plugins) {
+            const ordered = this.config.plugins
+                .map((plugin, index) => ({ plugin, index }))
+                .sort((a, b) => (b.plugin.priority ?? 0) - (a.plugin.priority ?? 0) || a.index - b.index)
+                .map((entry) => entry.plugin);
+            for (const plugin of ordered) {
                 this.pluginManager.register(plugin, this);
             }
         }
@@ -17331,12 +17344,11 @@ class ConnectionManager {
 //  全局单例
 // ---------------------------------------------------------------------------
 const manager = new ConnectionManager();
-// 挂载到 MetonaSqlark 静态方法（通过 any 绕过 TS 类型检查）
+// 挂载到 MetonaSqlark 静态方法（v0.8.0：类型已在类上声明，无需 any 断言）
-const M = MetonaSqlark;
+MetonaSqlark.connect = (config) => manager.connect(config);
-M.connect = (config) => manager.connect(config);
+MetonaSqlark.disconnect = (dbName) => manager.release(dbName);
-M.disconnect = (dbName) => manager.release(dbName);
+MetonaSqlark.disconnectAll = () => manager.closeAll();
-M.disconnectAll = () => manager.closeAll();
+MetonaSqlark.getActiveConnections = () => manager.getActiveConnections();
-M.getActiveConnections = () => manager.getActiveConnections();
 
 /**
  * migrateFromIndexedDB — 旧 IndexedDB 数据迁移到自研 KV 引擎

dist/metona-sqlark.d.ts

@@ -144,7 +144,14 @@ interface DatabaseConfig {
     name: string;
     /** 存储模式 */
     mode?: StorageMode;
-    /** 磁盘引擎（仅 mode='disk'|'hybrid' 时生效） */
+    /**
+     * 磁盘后端选择。
+     *
+     * v0.8.0 修正注释：**仅 `mode: 'aria'` 真正生效**（作为 Aria 的存储后端，
+     * 见 core.ts 的 aria 分支）。`disk` 模式恒用自研 KVStoreEngine，
+     * `hybrid` 的内存+磁盘组合也恒用 KVStoreEngine —— 两者会忽略本项
+     *（此前注释写成"disk 模式生效"，与实现相反）。
+     */
     diskEngine?: DiskEngine;
     /** 版本号 */
     version?: number;
@@ -212,7 +219,13 @@ interface MetonaPlugin {
     version: string;
     /** 描述 */
     description?: string;
-    /** 优先级，越大越先执行 */
+    /**
+     * 优先级：**越大越先执行**（含 `install()` 与钩子触发顺序）。
+     *
+     * v0.8.0 起真正生效 —— Core 会先按 priority 降序稳定排序再注册插件
+     *（同优先级保持 config 数组顺序）。此前 register() 虽按优先级插入数组，
+     * 但 install() 在 register 内立即执行，实际顺序 = config 数组顺序。
+     */
     priority?: number;
     /** 安装 */
     install(db: unknown): void;
@@ -1204,6 +1217,26 @@ declare class MetonaSqlark {
      * 只有经 `connect()` 取得的实例才有，直接调用会抛错（而不是静默无操作）。
      */
     disconnect?: () => Promise<void>;
+    /**
+     * v0.8.0：连接池静态 API 的类型声明。
+     *
+     * 这些方法由 `src/connection-manager.ts` **运行时注入**（`MetonaSqlark.connect = ...`）。
+     * 此前注入侧用 `as unknown as Record<string, unknown>` 绕过类型检查，
+     * 于是 README「连接池」一节里的 `MetonaSqlark.connect(...)` /
+     * `MetonaSqlark.disconnectAll()` 在 TypeScript 下全部报 TS2339
+     *（"属性不存在"），使用者只能 `as any`。
+     *
+     * 声明为 `?` 可选是因为它们**只在 import 了 connection-manager 的构建里存在**：
+     * 核心入口不 import 它（避免无谓的模块副作用）。真正常用的路径是
+     * `MetonaSqlark.create()`。
+     */
+    static connect?: (config: DatabaseConfig) => Promise<MetonaSqlark>;
+    /** 按库名释放一个连接引用（等价于实例上的 `disconnect()`） */
+    static disconnect?: (dbName: string) => Promise<void>;
+    /** 关闭全部连接 */
+    static disconnectAll?: () => Promise<void>;
+    /** 当前活跃连接名列表 */
+    static getActiveConnections?: () => string[];
     /**
      * v0.7.1: 静态工厂（与 connect/disconnect 同一入口风格）。
      * 此前 create 仅存在于 api 对象 / window 挂载 —— README/站点示例的

dist/metona-sqlark.esm.js

@@ -16619,9 +16619,22 @@ class MetonaSqlark {
         // 初始化执行器和事务管理器
         this.executor = new QueryExecutor(this.engine, this.maxRowsPerQuery);
         this.transactionManager = new TransactionManager(this.engine);
-        // 注册插件
+        // 注册插件。
+        //
+        // v0.8.0：**先按 priority 降序排序再注册** —— 在这之前 PluginManager.register
+        // 虽然会把插件插到正确的位置，但 `install()` 是在 register 里**立即**调用的，
+        // 因此 install 与钩子的实际执行顺序仍等于 config 数组顺序
+        //（实测：priority 为 low/high/mid 的插件，钩子按 low→high→mid 触发，
+        //  只有 getPlugins() 才是 high,mid,low）。而 README/CONTRIBUTING 一直宣称
+        // "priority 越大越先执行" —— 文档与实现不符。
+        // 这里选择**让实现符合文档**（priority 是用户可见的配置项，静默无效比没有更糟）。
+        // 用稳定排序：同优先级保持 config 数组中的相对顺序。
         if (this.config.plugins) {
-            for (const plugin of this.config.plugins) {
+            const ordered = this.config.plugins
+                .map((plugin, index) => ({ plugin, index }))
+                .sort((a, b) => (b.plugin.priority ?? 0) - (a.plugin.priority ?? 0) || a.index - b.index)
+                .map((entry) => entry.plugin);
+            for (const plugin of ordered) {
                 this.pluginManager.register(plugin, this);
             }
         }
@@ -17327,12 +17340,11 @@ class ConnectionManager {
 //  全局单例
 // ---------------------------------------------------------------------------
 const manager = new ConnectionManager();
-// 挂载到 MetonaSqlark 静态方法（通过 any 绕过 TS 类型检查）
+// 挂载到 MetonaSqlark 静态方法（v0.8.0：类型已在类上声明，无需 any 断言）
-const M = MetonaSqlark;
+MetonaSqlark.connect = (config) => manager.connect(config);
-M.connect = (config) => manager.connect(config);
+MetonaSqlark.disconnect = (dbName) => manager.release(dbName);
-M.disconnect = (dbName) => manager.release(dbName);
+MetonaSqlark.disconnectAll = () => manager.closeAll();
-M.disconnectAll = () => manager.closeAll();
+MetonaSqlark.getActiveConnections = () => manager.getActiveConnections();
-M.getActiveConnections = () => manager.getActiveConnections();
 
 /**
  * migrateFromIndexedDB — 旧 IndexedDB 数据迁移到自研 KV 引擎

dist/metona-sqlark.js

@@ -16625,9 +16625,22 @@
             // 初始化执行器和事务管理器
             this.executor = new QueryExecutor(this.engine, this.maxRowsPerQuery);
             this.transactionManager = new TransactionManager(this.engine);
-            // 注册插件
+            // 注册插件。
+            //
+            // v0.8.0：**先按 priority 降序排序再注册** —— 在这之前 PluginManager.register
+            // 虽然会把插件插到正确的位置，但 `install()` 是在 register 里**立即**调用的，
+            // 因此 install 与钩子的实际执行顺序仍等于 config 数组顺序
+            //（实测：priority 为 low/high/mid 的插件，钩子按 low→high→mid 触发，
+            //  只有 getPlugins() 才是 high,mid,low）。而 README/CONTRIBUTING 一直宣称
+            // "priority 越大越先执行" —— 文档与实现不符。
+            // 这里选择**让实现符合文档**（priority 是用户可见的配置项，静默无效比没有更糟）。
+            // 用稳定排序：同优先级保持 config 数组中的相对顺序。
             if (this.config.plugins) {
-                for (const plugin of this.config.plugins) {
+                const ordered = this.config.plugins
+                    .map((plugin, index) => ({ plugin, index }))
+                    .sort((a, b) => (b.plugin.priority ?? 0) - (a.plugin.priority ?? 0) || a.index - b.index)
+                    .map((entry) => entry.plugin);
+                for (const plugin of ordered) {
                     this.pluginManager.register(plugin, this);
                 }
             }
@@ -17333,12 +17346,11 @@
     //  全局单例
     // ---------------------------------------------------------------------------
     const manager = new ConnectionManager();
-    // 挂载到 MetonaSqlark 静态方法（通过 any 绕过 TS 类型检查）
+    // 挂载到 MetonaSqlark 静态方法（v0.8.0：类型已在类上声明，无需 any 断言）
-    const M = MetonaSqlark;
+    MetonaSqlark.connect = (config) => manager.connect(config);
-    M.connect = (config) => manager.connect(config);
+    MetonaSqlark.disconnect = (dbName) => manager.release(dbName);
-    M.disconnect = (dbName) => manager.release(dbName);
+    MetonaSqlark.disconnectAll = () => manager.closeAll();
-    M.disconnectAll = () => manager.closeAll();
+    MetonaSqlark.getActiveConnections = () => manager.getActiveConnections();
-    M.getActiveConnections = () => manager.getActiveConnections();
 
     /**
      * migrateFromIndexedDB — 旧 IndexedDB 数据迁移到自研 KV 引擎

dist/react.js

@@ -16608,9 +16608,22 @@ class MetonaSqlark {
         // 初始化执行器和事务管理器
         this.executor = new QueryExecutor(this.engine, this.maxRowsPerQuery);
         this.transactionManager = new TransactionManager(this.engine);
-        // 注册插件
+        // 注册插件。
+        //
+        // v0.8.0：**先按 priority 降序排序再注册** —— 在这之前 PluginManager.register
+        // 虽然会把插件插到正确的位置，但 `install()` 是在 register 里**立即**调用的，
+        // 因此 install 与钩子的实际执行顺序仍等于 config 数组顺序
+        //（实测：priority 为 low/high/mid 的插件，钩子按 low→high→mid 触发，
+        //  只有 getPlugins() 才是 high,mid,low）。而 README/CONTRIBUTING 一直宣称
+        // "priority 越大越先执行" —— 文档与实现不符。
+        // 这里选择**让实现符合文档**（priority 是用户可见的配置项，静默无效比没有更糟）。
+        // 用稳定排序：同优先级保持 config 数组中的相对顺序。
         if (this.config.plugins) {
-            for (const plugin of this.config.plugins) {
+            const ordered = this.config.plugins
+                .map((plugin, index) => ({ plugin, index }))
+                .sort((a, b) => (b.plugin.priority ?? 0) - (a.plugin.priority ?? 0) || a.index - b.index)
+                .map((entry) => entry.plugin);
+            for (const plugin of ordered) {
                 this.pluginManager.register(plugin, this);
             }
         }

dist/vue.js

@@ -16608,9 +16608,22 @@ class MetonaSqlark {
         // 初始化执行器和事务管理器
         this.executor = new QueryExecutor(this.engine, this.maxRowsPerQuery);
         this.transactionManager = new TransactionManager(this.engine);
-        // 注册插件
+        // 注册插件。
+        //
+        // v0.8.0：**先按 priority 降序排序再注册** —— 在这之前 PluginManager.register
+        // 虽然会把插件插到正确的位置，但 `install()` 是在 register 里**立即**调用的，
+        // 因此 install 与钩子的实际执行顺序仍等于 config 数组顺序
+        //（实测：priority 为 low/high/mid 的插件，钩子按 low→high→mid 触发，
+        //  只有 getPlugins() 才是 high,mid,low）。而 README/CONTRIBUTING 一直宣称
+        // "priority 越大越先执行" —— 文档与实现不符。
+        // 这里选择**让实现符合文档**（priority 是用户可见的配置项，静默无效比没有更糟）。
+        // 用稳定排序：同优先级保持 config 数组中的相对顺序。
         if (this.config.plugins) {
-            for (const plugin of this.config.plugins) {
+            const ordered = this.config.plugins
+                .map((plugin, index) => ({ plugin, index }))
+                .sort((a, b) => (b.plugin.priority ?? 0) - (a.plugin.priority ?? 0) || a.index - b.index)
+                .map((entry) => entry.plugin);
+            for (const plugin of ordered) {
                 this.pluginManager.register(plugin, this);
             }
         }