@zhin.js/database 1.0.77 → 1.0.79

package/lib/base/database.d.ts

@@ -23,6 +23,10 @@ export declare abstract class Database<D = any, S extends Record<string, object>
     private _logger?;
     private _logging;
     constructor(dialect: Dialect<D, S, Q>, definitions?: Database.DefinitionObj<S>);
+    /**
+     * 若方言支持按列声明类型处理（如 SQLite 读路径的 json 反序列化），向其注册表结构
+     */
+    private registerDialectSchema;
     /**
      * 启用查询日志
      * @param handler 自定义日志处理器，不传则使用默认控制台输出
@@ -123,6 +127,6 @@ export declare namespace Database {
         get<K extends keyof S>(key: K): Model<D, S, Q, K> | undefined;
     }
     type DefinitionObj<S extends Record<string, object>> = {
-        [K in keyof S]: Definition<S[K]>;
+        [K in keyof S]?: Definition<S[K]>;
     };
 }

package/lib/base/database.js

@@ -24,7 +24,20 @@ export class Database {
     constructor(dialect, definitions) {
         this.dialect = dialect;
         for (const key in definitions) {
-            this.definitions.set(key, definitions[key]);
+            const definition = definitions[key];
+            if (!definition)
+                continue;
+            this.definitions.set(key, definition);
+            this.registerDialectSchema(key, definition);
+        }
+    }
+    /**
+     * 若方言支持按列声明类型处理（如 SQLite 读路径的 json 反序列化），向其注册表结构
+     */
+    registerDialectSchema(name, definition) {
+        const d = this.dialect;
+        if (typeof d.registerTableSchema === 'function') {
+            d.registerTableSchema(String(name), definition);
         }
     }
     // ============================================================================
@@ -126,6 +139,7 @@ export class Database {
     }
     define(name, definition) {
         this.definitions.set(name, definition);
+        this.registerDialectSchema(name, definition);
     }
     /**
      * 删除表定义

package/lib/dialects/sqlite.d.ts

@@ -16,8 +16,16 @@ export declare class SQLiteDialect<S extends Record<string, object> = Record<str
     /** node:sqlite 仅支持 number/string/bigint/buffer/null；JSON 列在库内为 TEXT，对象需序列化 */
     private prepareBindParams;
     query<U = any>(sql: string, params?: any[]): Promise<U>;
+    /** 声明为 json 的列名集合（由 Database 层注册表结构时填充），读路径仅对这些列做 JSON 反序列化 */
+    private readonly jsonColumns;
     /**
-     * 处理查询结果，移除字符串字段的多余引号
+     * 注册表的列声明类型，用于读路径按声明类型反序列化（避免对 TEXT 列做启发式 JSON 解析破坏往返）
+     */
+    registerTableSchema(table: string, definition: Record<string, {
+        type: string;
+    }>): void;
+    /**
+     * 处理查询结果，按列声明类型反序列化（json 列）
      */
     private processQueryResults;
     /**
@@ -25,7 +33,8 @@ export declare class SQLiteDialect<S extends Record<string, object> = Record<str
      */
     private processRowData;
     /**
-     * 处理字段值，移除多余的引号并解析 JSON
+     * 处理字段值：仅对声明为 json 的列做 JSON 反序列化；
+     * 普通 TEXT 列原样返回，保证写入什么读出什么（不剥离引号、不启发式 JSON.parse）
      */
     private processFieldValue;
     dispose(): Promise<void>;

package/lib/dialects/sqlite.js

@@ -62,36 +62,42 @@ export class SQLiteDialect extends Dialect {
         if (!this.db)
             throw new Error('SQLite 未连接');
         const trimmedSql = sql.trim().toLowerCase();
-        const isSelect = trimmedSql.startsWith('select');
         const isInsert = trimmedSql.startsWith('insert');
         const isUpdateOrDelete = trimmedSql.startsWith('update') || trimmedSql.startsWith('delete');
+        // 带 RETURNING 的 DML 有结果集，不能走 run 丢行
+        const hasReturning = /\breturning\b/.test(trimmedSql);
         const args = this.prepareBindParams(params ?? []);
-        try {
-            const stmt = this.db.prepare(sql);
-            if (isSelect) {
-                const rows = stmt.all(...args);
-                return this.processQueryResults(rows);
-            }
-            if (isInsert) {
-                const result = stmt.run(...args);
-                return {
-                    lastID: Number(result.lastInsertRowid),
-                    changes: Number(result.changes),
-                };
-            }
-            if (isUpdateOrDelete) {
-                const result = stmt.run(...args);
-                return Number(result.changes);
-            }
-            stmt.run(...args);
-            return undefined;
+        const stmt = this.db.prepare(sql);
+        if (isInsert && !hasReturning) {
+            const result = stmt.run(...args);
+            return {
+                lastID: Number(result.lastInsertRowid),
+                changes: Number(result.changes),
+            };
         }
-        catch (err) {
-            throw err;
+        if (isUpdateOrDelete && !hasReturning) {
+            const result = stmt.run(...args);
+            return Number(result.changes);
+        }
+        // SELECT / WITH / PRAGMA / DDL / 带 RETURNING 的 DML：按可能有结果集处理。
+        // node:sqlite 的 all() 对无结果集语句返回空数组，不会抛错。
+        const rows = stmt.all(...args);
+        return this.processQueryResults(rows);
+    }
+    /** 声明为 json 的列名集合（由 Database 层注册表结构时填充），读路径仅对这些列做 JSON 反序列化 */
+    jsonColumns = new Set();
+    /**
+     * 注册表的列声明类型，用于读路径按声明类型反序列化（避免对 TEXT 列做启发式 JSON 解析破坏往返）
+     */
+    registerTableSchema(table, definition) {
+        for (const [columnName, column] of Object.entries(definition)) {
+            if (column && column.type === 'json') {
+                this.jsonColumns.add(columnName);
+            }
         }
     }
     /**
-     * 处理查询结果，移除字符串字段的多余引号
+     * 处理查询结果，按列声明类型反序列化（json 列）
      */
     processQueryResults(data) {
         if (!data)
@@ -112,42 +118,26 @@ export class SQLiteDialect extends Dialect {
             return row;
         const processedRow = {};
         for (const [key, value] of Object.entries(row)) {
-            processedRow[key] = this.processFieldValue(value);
+            processedRow[key] = this.processFieldValue(key, value);
         }
         return processedRow;
     }
     /**
-     * 处理字段值，移除多余的引号并解析 JSON
+     * 处理字段值：仅对声明为 json 的列做 JSON 反序列化；
+     * 普通 TEXT 列原样返回，保证写入什么读出什么（不剥离引号、不启发式 JSON.parse）
      */
-    processFieldValue(value) {
+    processFieldValue(key, value) {
         if (typeof value !== 'string')
             return value;
-        // 移除字符串两端的引号（如果存在）
-        if ((value.startsWith("'") && value.endsWith("'")) ||
-            (value.startsWith('"') && value.endsWith('"'))) {
-            const unquoted = value.slice(1, -1);
-            // 尝试解析为 JSON（用于 json 类型字段）
-            if (unquoted.startsWith('{') || unquoted.startsWith('[')) {
-                try {
-                    return JSON.parse(unquoted);
-                }
-                catch {
-                    // 如果解析失败，返回去除引号的字符串
-                    return unquoted;
-                }
-            }
-            return unquoted;
+        if (!this.jsonColumns.has(key))
+            return value;
+        try {
+            return JSON.parse(value);
         }
-        // 尝试解析没有引号包裹但看起来像 JSON 的值（SQLite 驱动返回的 json 类型字段）
-        if (value.startsWith('{') || value.startsWith('[')) {
-            try {
-                return JSON.parse(value);
-            }
-            catch {
-                // 解析失败，返回原始字符串
-            }
+        catch {
+            // 解析失败，返回原始字符串
+            return value;
         }
-        return value;
     }
     async dispose() {
         if (this.db) {

package/lib/migration.js

@@ -4,49 +4,65 @@
  */
 class RecordingMigrationContext {
     baseContext;
+    execute;
     _operations = [];
-    constructor(baseContext) {
+    /**
+     * @param baseContext 实际执行的上下文
+     * @param execute 是否真正执行操作；false 时为 dry-run，仅记录操作不触碰数据库
+     */
+    constructor(baseContext, execute = true) {
         this.baseContext = baseContext;
+        this.execute = execute;
     }
     get operations() {
         return this._operations;
     }
     async createTable(tableName, columns) {
         this._operations.push({ type: 'createTable', tableName, columns });
-        await this.baseContext.createTable(tableName, columns);
+        if (this.execute)
+            await this.baseContext.createTable(tableName, columns);
     }
     async dropTable(tableName) {
         this._operations.push({ type: 'dropTable', tableName });
-        await this.baseContext.dropTable(tableName);
+        if (this.execute)
+            await this.baseContext.dropTable(tableName);
     }
     async addColumn(tableName, columnName, column) {
         this._operations.push({ type: 'addColumn', tableName, columnName, column });
-        await this.baseContext.addColumn(tableName, columnName, column);
+        if (this.execute)
+            await this.baseContext.addColumn(tableName, columnName, column);
     }
     async dropColumn(tableName, columnName) {
         this._operations.push({ type: 'dropColumn', tableName, columnName });
-        await this.baseContext.dropColumn(tableName, columnName);
+        if (this.execute)
+            await this.baseContext.dropColumn(tableName, columnName);
     }
     async modifyColumn(tableName, columnName, column) {
         // modifyColumn 不能自动反向，需要原始列定义
-        await this.baseContext.modifyColumn(tableName, columnName, column);
+        if (this.execute)
+            await this.baseContext.modifyColumn(tableName, columnName, column);
     }
     async renameColumn(tableName, oldName, newName) {
         this._operations.push({ type: 'renameColumn', tableName, oldName, newName });
-        await this.baseContext.renameColumn(tableName, oldName, newName);
+        if (this.execute)
+            await this.baseContext.renameColumn(tableName, oldName, newName);
     }
     async addIndex(tableName, indexName, columns, unique) {
         this._operations.push({ type: 'addIndex', tableName, indexName, columns, unique });
-        await this.baseContext.addIndex(tableName, indexName, columns, unique);
+        if (this.execute)
+            await this.baseContext.addIndex(tableName, indexName, columns, unique);
     }
     async dropIndex(tableName, indexName) {
         this._operations.push({ type: 'dropIndex', tableName, indexName });
-        await this.baseContext.dropIndex(tableName, indexName);
+        if (this.execute)
+            await this.baseContext.dropIndex(tableName, indexName);
     }
     async query(sql, params) {
         // query 操作记录但无法自动反向
         this._operations.push({ type: 'query', sql, params });
-        return this.baseContext.query(sql, params);
+        if (this.execute)
+            return this.baseContext.query(sql, params);
+        return undefined;
     }
 }
 /**
@@ -333,12 +349,15 @@ export class MigrationRunner {
         const migrated = [];
         for (const migration of pending) {
             try {
-                // 如果没有显式的 down，使用记录型上下文来记录操作
+                // 如果没有显式的 down，先 dry-run 记录操作并验证可以自动反向，通过后再真正执行
                 if (!migration.down) {
+                    const dryRunContext = new RecordingMigrationContext(baseContext, false);
+                    await migration.up(dryRunContext);
+                    // 提前校验操作可反向（不可反向时抛错，此时数据库尚未被修改）
+                    generateReverseOperations(dryRunContext.operations);
+                    // 校验通过，真正执行并记录操作
                     const recordingContext = new RecordingMigrationContext(baseContext);
                     await migration.up(recordingContext);
-                    // 验证操作可以反向（提前检查）
-                    generateReverseOperations(recordingContext.operations);
                     await this.recordMigration(migration.name, batch, recordingContext.operations);
                 }
                 else {
@@ -438,8 +457,9 @@ function mapColumnType(type) {
 function formatDefault(value) {
     if (value === null)
         return 'NULL';
+    // 与各方言 escapeString 一致：单引号 doubling，避免默认值中的引号破坏 SQL
     if (typeof value === 'string')
-        return `'${value}'`;
+        return `'${value.replace(/'/g, "''")}'`;
     if (typeof value === 'boolean')
         return value ? '1' : '0';
     return String(value);

package/lib/type/related/database.js

@@ -400,7 +400,13 @@ export class RelatedDatabase extends Database {
             }
             else {
                 const value = condition[key];
-                if (value && typeof value === 'object' && !Array.isArray(value)) {
+                // 只有普通对象才视为操作符集合；Date 等带原型的对象按标量等值处理，避免条件被静默丢弃
+                const isPlainObject = value !== null &&
+                    typeof value === 'object' &&
+                    !Array.isArray(value) &&
+                    !isSubquery(value) &&
+                    (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+                if (isPlainObject) {
                     for (const op in value) {
                         const quotedKey = formatField(key);
                         const placeholder = this.dialect.getParameterPlaceholder(params.length);
@@ -476,6 +482,8 @@ export class RelatedDatabase extends Database {
                                 clauses.push(`${quotedKey} NOT LIKE ${placeholder}`);
                                 params.push(value[op]);
                                 break;
+                            default:
+                                throw new Error(`parseCondition: unknown operator "${op}" for field "${String(key)}"`);
                         }
                     }
                 }

package/lib/type/related/model.js

@@ -323,7 +323,8 @@ export class RelatedModel extends Model {
                 const { table: pivotTable, foreignPivotKey, relatedPivotKey, pivotFields } = relation.pivot;
                 const targetKey = relation.targetKey || 'id';
                 // 查询中间表获取关联的目标ID
-                const pivotRecords = await targetDb.query(`SELECT * FROM "${pivotTable}" WHERE "${foreignPivotKey}" = ?`, [localValue]);
+                const pivotDialect = targetDb.dialect;
+                const pivotRecords = await targetDb.query(`SELECT * FROM ${pivotDialect.quoteIdentifier(pivotTable)} WHERE ${pivotDialect.quoteIdentifier(foreignPivotKey)} = ${pivotDialect.getParameterPlaceholder(0)}`, [localValue]);
                 if (pivotRecords.length === 0) {
                     return [];
                 }
@@ -420,8 +421,9 @@ export class RelatedModel extends Model {
                     return;
                 }
                 // 批量查询中间表
-                const placeholders = localValues.map(() => '?').join(', ');
-                const pivotRecords = await targetDb.query(`SELECT * FROM "${pivotTable}" WHERE "${foreignPivotKey}" IN (${placeholders})`, localValues);
+                const batchDialect = targetDb.dialect;
+                const placeholders = localValues.map((_, i) => batchDialect.getParameterPlaceholder(i)).join(', ');
+                const pivotRecords = await targetDb.query(`SELECT * FROM ${batchDialect.quoteIdentifier(pivotTable)} WHERE ${batchDialect.quoteIdentifier(foreignPivotKey)} IN (${placeholders})`, localValues);
                 if (pivotRecords.length === 0) {
                     records.forEach(r => r[relationName] = []);
                     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/database",
-  "version": "1.0.77",
+  "version": "1.0.79",
   "description": "Universal database abstraction layer for Zhin.js - supports SQLite, MySQL, PostgreSQL, MongoDB, Redis",
   "type": "module",
   "main": "./lib/index.js",
@@ -20,7 +20,7 @@
     "node": ">=22.5.0"
   },
   "dependencies": {
-    "@zhin.js/logger": "1.0.75"
+    "@zhin.js/logger": "1.0.76"
   },
   "peerDependencies": {
     "mongodb": ">=3.1.13",
@@ -43,9 +43,9 @@
     }
   },
   "devDependencies": {
-    "@types/pg": "^8.15.0",
+    "@types/pg": "^8.20.0",
     "mongodb": "^7.5.0",
-    "mysql2": "^3.22.6",
+    "mysql2": "^3.23.2",
     "pg": "^8.22.0",
     "redis": "latest",
     "typescript": "^6.0.3"