@maiyunnet/kebab 9.15.0 → 9.15.2

package/index.d.ts

@@ -5,7 +5,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export declare const VER = "9.15.0";
+export declare const VER = "9.15.2";
 /** --- 框架根目录，以 / 结尾  --- */
 export declare const ROOT_PATH: string;
 /** --- 框架的 LIB，以 / 结尾 --- */

package/index.js

@@ -6,7 +6,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export const VER = '9.15.0';
+export const VER = '9.15.2';
 // --- 服务端用的路径 ---
 const imu = decodeURIComponent(import.meta.url).replace('file://', '').replace(/^\/(\w:)/, '$1');
 /** --- /xxx/xxx --- */

package/lib/db/conn.js

@@ -2,6 +2,7 @@ import * as pg from 'pg';
 import * as lCore from '#kebab/lib/core.js';
 import * as lTime from '#kebab/lib/time.js';
 import * as lDb from '#kebab/lib/db.js';
+import * as lSqlValue from '#kebab/lib/sql/value.js';
 // --- 注册解析器 ---
 // --- pg 库对以下类型默认返回 string，为与 MySQL 行为保持一致，在此注册解析器转为 JS 原生类型 ---
 // --- POLYGON: 返回如 ((1,1),(2,2)) 的字符串，解析为 {x, y}[] ---
@@ -155,6 +156,7 @@ export class Connection {
             'result': 1,
         };
         try {
+            values = lSqlValue.serializeList(values);
             this.refreshLast();
             if (this._lastSql.length === 2) {
                 this._lastSql.splice(0, 1);
@@ -212,6 +214,7 @@ export class Connection {
             'result': 1,
         };
         try {
+            values = lSqlValue.serializeList(values);
             this.refreshLast();
             if (this._lastSql.length === 2) {
                 this._lastSql.splice(0, 1);

package/lib/db/value.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * --- 数据库特殊值的运行时包装与序列化 ---
+ */
+import * as kebab from '#kebab/index.js';
+/** --- JSON 数据的内部标记，不污染原始对象，也不会参与 JSON 序列化 --- */
+declare const jsonValueSymbol: unique symbol;
+/** --- 延迟到数据库边界序列化的 JSON 值 --- */
+export interface IJsonValue<T> {
+    readonly [jsonValueSymbol]: true;
+    readonly 'value': T;
+}
+/**
+ * --- 创建延迟序列化的 JSON 值 ---
+ * @param value 原始 JSON 值
+ * @returns JSON 包装值
+ */
+export declare function json<T>(value: T): IJsonValue<T>;
+/**
+ * --- 判断是否为 JSON 包装值 ---
+ * @param value 待判断的值
+ * @returns 是否为 JSON 包装值
+ */
+export declare function isJson(value: unknown): value is IJsonValue<unknown>;
+/**
+ * --- 获取 JSON 包装值内的原始值；普通值保持不变 ---
+ * @param value 待解包的值
+ * @returns 原始值
+ */
+export declare function unwrapJson<T>(value: T): T;
+/**
+ * --- 将单个数据库参数转换为驱动可识别的值 ---
+ * @param value 数据库参数
+ * @returns 序列化后的数据库参数
+ */
+export declare function serialize(value: kebab.Json): kebab.Json;
+/**
+ * --- 在进入数据库驱动前序列化特殊参数，不修改调用方数组 ---
+ * @param values 数据库参数列表
+ * @returns 可直接交给数据库驱动的参数列表
+ */
+export declare function serializeList(values?: kebab.DbValue[]): kebab.DbValue[] | undefined;
+export {};

package/lib/db/value.js

@@ -0,0 +1,59 @@
+import * as lText from '#kebab/lib/text.js';
+/** --- JSON 数据的内部标记，不污染原始对象，也不会参与 JSON 序列化 --- */
+const jsonValueSymbol = Symbol('kebab.db.json');
+/**
+ * --- 创建延迟序列化的 JSON 值 ---
+ * @param value 原始 JSON 值
+ * @returns JSON 包装值
+ */
+export function json(value) {
+    return {
+        [jsonValueSymbol]: true,
+        'value': value,
+    };
+}
+/**
+ * --- 判断是否为 JSON 包装值 ---
+ * @param value 待判断的值
+ * @returns 是否为 JSON 包装值
+ */
+export function isJson(value) {
+    return value !== null && typeof value === 'object' &&
+        !!value[jsonValueSymbol];
+}
+/**
+ * --- 获取 JSON 包装值内的原始值；普通值保持不变 ---
+ * @param value 待解包的值
+ * @returns 原始值
+ */
+export function unwrapJson(value) {
+    return (isJson(value) ? value.value : value);
+}
+/**
+ * --- 将单个数据库参数转换为驱动可识别的值 ---
+ * @param value 数据库参数
+ * @returns 序列化后的数据库参数
+ */
+export function serialize(value) {
+    return isJson(value) ? lText.stringifyJson(value.value) : value;
+}
+/**
+ * --- 在进入数据库驱动前序列化特殊参数，不修改调用方数组 ---
+ * @param values 数据库参数列表
+ * @returns 可直接交给数据库驱动的参数列表
+ */
+export function serializeList(values) {
+    if (!values) {
+        return undefined;
+    }
+    let serialized;
+    for (let i = 0; i < values.length; ++i) {
+        const value = values[i];
+        if (!isJson(value)) {
+            continue;
+        }
+        serialized ??= [...values];
+        serialized[i] = lText.stringifyJson(value.value);
+    }
+    return serialized ?? values;
+}

package/lib/fs.js

@@ -434,9 +434,12 @@ export async function readToResponse(path, req, res, stat) {
     // --- 判断缓存以及 MIME 和编码 ---
     let charset = '';
     const mimeData = mime.getData(path);
-    if (['htm', 'html', 'css', 'js', 'mjs', 'xml', 'jpg', 'jpeg', 'svg', 'gif', 'png', 'json'].includes(mimeData.extension)) {
+    // --- 文本类文件统一附加 charset，避免浏览器按本地默认编码解析导致乱码 ---
+    if (mimeData.mime.startsWith('text/') || ['json', 'xml', 'svg', 'js', 'mjs', 'map', 'webmanifest'].includes(mimeData.extension)) {
         charset = '; charset=utf-8';
-        // --- 这些文件可能需要缓存 ---
+    }
+    // --- 这些文件可能需要缓存 ---
+    if (['htm', 'html', 'css', 'js', 'mjs', 'xml', 'jpg', 'jpeg', 'svg', 'gif', 'png', 'json'].includes(mimeData.extension)) {
         const hash = `W/"${stat.size.toString(16)}-${stat.mtime.getTime().toString(16)}"`;
         const lastModified = stat.mtime.toUTCString();
         res.setHeader('etag', hash);

package/lib/sql/value.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * --- SQL 特殊参数的运行时包装与序列化 ---
+ */
+import * as kebab from '#kebab/index.js';
+/** --- JSON 参数的内部标记，不污染原始对象，也不会参与 JSON 序列化 --- */
+declare const jsonValueSymbol: unique symbol;
+/** --- 延迟到数据库边界序列化的 JSON 参数 --- */
+export interface IJsonValue<T> {
+    readonly [jsonValueSymbol]: true;
+    readonly 'value': T;
+}
+/**
+ * --- 创建延迟序列化的 JSON 参数 ---
+ * @param value 原始 JSON 值
+ * @returns JSON 包装值
+ */
+export declare function json<T>(value: T): IJsonValue<T>;
+/**
+ * --- 判断是否为 JSON 包装值 ---
+ * @param value 待判断的值
+ * @returns 是否为 JSON 包装值
+ */
+export declare function isJson(value: unknown): value is IJsonValue<unknown>;
+/**
+ * --- 获取 JSON 包装值内的原始值；普通值保持不变 ---
+ * @param value 待解包的值
+ * @returns 原始值
+ */
+export declare function unwrapJson<T>(value: T): T;
+/**
+ * --- 将单个 SQL 参数转换为数据库驱动可识别的值 ---
+ * @param value SQL 参数
+ * @returns 序列化后的数据库参数
+ */
+export declare function serialize(value: kebab.Json): kebab.Json;
+/**
+ * --- 在进入数据库驱动前序列化特殊参数，不修改调用方数组 ---
+ * @param values SQL 参数列表
+ * @returns 可直接交给数据库驱动的参数列表
+ */
+export declare function serializeList(values?: kebab.DbValue[]): kebab.DbValue[] | undefined;
+export {};

package/lib/sql/value.js

@@ -0,0 +1,59 @@
+import * as lText from '#kebab/lib/text.js';
+/** --- JSON 参数的内部标记，不污染原始对象，也不会参与 JSON 序列化 --- */
+const jsonValueSymbol = Symbol('kebab.sql.json');
+/**
+ * --- 创建延迟序列化的 JSON 参数 ---
+ * @param value 原始 JSON 值
+ * @returns JSON 包装值
+ */
+export function json(value) {
+    return {
+        [jsonValueSymbol]: true,
+        'value': value,
+    };
+}
+/**
+ * --- 判断是否为 JSON 包装值 ---
+ * @param value 待判断的值
+ * @returns 是否为 JSON 包装值
+ */
+export function isJson(value) {
+    return value !== null && typeof value === 'object' &&
+        !!value[jsonValueSymbol];
+}
+/**
+ * --- 获取 JSON 包装值内的原始值；普通值保持不变 ---
+ * @param value 待解包的值
+ * @returns 原始值
+ */
+export function unwrapJson(value) {
+    return (isJson(value) ? value.value : value);
+}
+/**
+ * --- 将单个 SQL 参数转换为数据库驱动可识别的值 ---
+ * @param value SQL 参数
+ * @returns 序列化后的数据库参数
+ */
+export function serialize(value) {
+    return isJson(value) ? lText.stringifyJson(value.value) : value;
+}
+/**
+ * --- 在进入数据库驱动前序列化特殊参数，不修改调用方数组 ---
+ * @param values SQL 参数列表
+ * @returns 可直接交给数据库驱动的参数列表
+ */
+export function serializeList(values) {
+    if (!values) {
+        return undefined;
+    }
+    let serialized;
+    for (let i = 0; i < values.length; ++i) {
+        const value = values[i];
+        if (!isJson(value)) {
+            continue;
+        }
+        serialized ??= [...values];
+        serialized[i] = lText.stringifyJson(value.value);
+    }
+    return serialized ?? values;
+}

package/lib/sql.d.ts

@@ -98,7 +98,7 @@ export declare class Sql {
     /**
      * --- 批量 UPDATE，以子查询作为数据源，纯更新语义（不会插入新行）---
      * --- MySQL: UPDATE t INNER JOIN (SELECT col AS alias ... UNION ALL SELECT ...) AS tmp ON t.key=tmp.key SET t.c=tmp.c ---
-     * --- PostgreSQL: UPDATE t SET c=tmp.c FROM (VALUES ($1,...)) AS tmp(cols) WHERE t.key=tmp.key ---
+     * --- PostgreSQL: UPDATE t SET c=tmp.c FROM (VALUES (typed nulls), ($1,...)) AS tmp(cols) WHERE t.key=tmp.key ---
      * @param table 表名
      * @param key 用于定位待更新记录的字段名，通常为主键或唯一键，至少必须建立索引；
      *         该参数是字段名而不是索引名，仅参与 ON / WHERE 匹配，不会被更新
@@ -192,14 +192,13 @@ export declare class Sql {
     private _whereDataPosition;
     /**
      * --- 筛选器 ---
-     * --- 1. 'city': 'bj', 'type': '2' ---
-     * --- 2. ['type', '>', '1'] ---
-     * --- 3. ['type', 'in', ['1', '2']] ---
-     * --- 4. 'type': ['1', '2'] ---
-     * --- 5. '$or': [{'city': 'bj'}, {'city': 'sh'}, [['age', '>', '10']]], 'type': '2' ---
-     * --- 6. 'city_in': column('city_out') ---
-     * --- 7. ['JSON_CONTAINS(`uid`, ?)', ['hello']] ---
-     * --- 8. ['info', 'json', {'a': 1}] ---
+     * --- 标量相等：'city': 'bj', 'type': '2' ---
+     * --- 运算符条件：['type', '>', '1'] ---
+     * --- 集合条件：['type', 'in', ['1', '2']] 或 'type': ['1', '2'] ---
+     * --- 逻辑分组：'$or': [{'city': 'bj'}, {'city': 'sh'}, [['age', '>', '10']]] ---
+     * --- 字段比较：'city_in': column('city_out') ---
+     * --- 原始条件：['JSON_CONTAINS(`uid`, ?)', ['hello']] ---
+     * --- JSON 条件：['info', 'json', {'a': 1}] ---
      * @param s 筛选数据
      */
     where(s: string | kebab.Json): this;
@@ -274,11 +273,6 @@ export declare class Sql {
     private _isValue;
     /** --- 获取占位符 --- */
     private _placeholder;
-    /**
-     * --- 返回 PostgreSQL VALUES 第一行的显式类型转换后缀，用于帮助 PostgreSQL 推断 VALUES 派生表列类型 ---
-     * @param v 要处理的值
-     */
-    private _pgCastSuffix;
     /**
      * --- 处理单个值,检测数据类型并返回 SQL 和 data ---
      * @param v 要处理的值
@@ -326,7 +320,8 @@ export declare function value(val: kebab.DbValue): {
     'value': kebab.DbValue;
 };
 /**
- * --- 将对象转换为 JSON 字符串并避开类型检查，用于适配 PostgreSQL 的 jsonb 字段 ---
- * @param obj 要转换的 JSON 对象
+ * --- 标记需要写入 JSON/jsonb 字段的值；实际序列化延迟到数据库边界 ---
+ * @param obj 原始 JSON 值
+ * @returns 类型保持不变的 JSON 包装值
  */
 export declare function json<T>(obj: T): T;

package/lib/sql.js

@@ -1,5 +1,6 @@
 import * as lText from '#kebab/lib/text.js';
 import * as lCore from '#kebab/lib/core.js';
+import * as lSqlValue from '#kebab/lib/sql/value.js';
 // --- 第三方 ---
 import * as mysql2 from 'mysql2/promise';
 /** --- 服务商定义 --- */
@@ -198,7 +199,7 @@ export class Sql {
     /**
      * --- 批量 UPDATE，以子查询作为数据源，纯更新语义（不会插入新行）---
      * --- MySQL: UPDATE t INNER JOIN (SELECT col AS alias ... UNION ALL SELECT ...) AS tmp ON t.key=tmp.key SET t.c=tmp.c ---
-     * --- PostgreSQL: UPDATE t SET c=tmp.c FROM (VALUES ($1,...)) AS tmp(cols) WHERE t.key=tmp.key ---
+     * --- PostgreSQL: UPDATE t SET c=tmp.c FROM (VALUES (typed nulls), ($1,...)) AS tmp(cols) WHERE t.key=tmp.key ---
      * @param table 表名
      * @param key 用于定位待更新记录的字段名，通常为主键或唯一键，至少必须建立索引；
      *         该参数是字段名而不是索引名，仅参与 ON / WHERE 匹配，不会被更新
@@ -234,17 +235,18 @@ export class Sql {
             this._sql = [`UPDATE (${selectParts.join(' UNION ALL ')}) AS tmp STRAIGHT_JOIN ${quotedTable} t ON t.${quotedKey} = tmp.${quotedKey} SET ${setClauses}`];
         }
         else {
-            // --- PostgreSQL 使用 UPDATE FROM (VALUES ...) ---
+            // --- PostgreSQL 使用 UPDATE FROM (VALUES ...)；首行从目标表复合类型取得真实列类型，
+            //     避免按 JS 值猜测类型时 uuid、日期、枚举、数组或 NULL 列无法匹配 ---
             const valueParts = [];
-            for (let ri = 0; ri < rows.length; ri++) {
-                const row = rows[ri];
+            const typeParts = allCols.map(c => `(NULL::${quotedTable}).${this.field(c)}`);
+            valueParts.push(`(${typeParts.join(', ')})`);
+            for (const row of rows) {
                 const parts = row.map(v => {
                     const result = this._processValue(v);
                     if (result.data.length > 0) {
                         this._data.push(...result.data);
                     }
-                    // --- 第一行加显式类型转换，帮助 PostgreSQL 推断 VALUES 派生表的列类型 ---
-                    return ri === 0 ? result.sql + this._pgCastSuffix(v) : result.sql;
+                    return result.sql;
                 });
                 valueParts.push(`(${parts.join(', ')})`);
             }
@@ -309,16 +311,15 @@ export class Sql {
     _updateSub(s) {
         /*
         [
-            ['total', '+', '1'],    // 1, '1' 可能也是 1 数字类型
+            ['total', '+', '1'],
             {
-                'type': '6',        // 2
-                'type': column('type2'),   // 3
-                // 'type': ['type3'],  // 4 - 此写法已被禁止，请用 (3) 代替
-                'type': ['(CASE `id` WHEN 1 THEN ? WHEN 2 THEN ? END)', ['val1', 'val2']],     // 5
-                'point': { 'x': 0, 'y': 0 },  // 6
-                'polygon': [ [ { 'x': 0, 'y': 0 }, { ... } ], [ ... ] ],          // 7
-                'json': { 'a': 1, 'b': { 'c': 2 }, 'c': [ { 'c': 2 } ] },         // 8 - 对象类 json，可能为空对象
-                'json2': ['abc']    // 9 - 数组类 json，可能为空数组
+                'type': '6',
+                'type': column('type2'),
+                'type': ['(CASE `id` WHEN 1 THEN ? WHEN 2 THEN ? END)', ['val1', 'val2']],
+                'point': { 'x': 0, 'y': 0 },
+                'polygon': [ [ { 'x': 0, 'y': 0 }, { ... } ], [ ... ] ],
+                'json': json({ 'a': 1, 'b': { 'c': 2 }, 'c': [ { 'c': 2 } ] }),
+                'json2': json(['abc'])
             }
         ]
         */
@@ -327,7 +328,7 @@ export class Sql {
         for (const k in s) {
             const v = s[k];
             if (/^[0-9]+$/.test(k)) {
-                // --- 1 ---
+                // --- 数组运算式：[字段, 运算符, 值] ---
                 const nv = v[2];
                 const isf = this._isField(nv);
                 if (isf) {
@@ -339,17 +340,22 @@ export class Sql {
                     }
                 }
                 else {
+                    /** --- JSON 标记值需要生成 ::jsonb；普通运算值保持原占位符行为 --- */
+                    const result = lSqlValue.isJson(nv) ? this._processValue(nv) : {
+                        'sql': this._placeholder(),
+                        'data': [nv],
+                    };
                     if (v[1] === '=') {
-                        sql += this.field(v[0]) + ' = ' + this._placeholder() + ', ';
+                        sql += this.field(v[0]) + ' = ' + result.sql + ', ';
                     }
                     else {
-                        sql += this.field(v[0]) + ' = ' + this.field(v[0]) + ' ' + v[1] + ' ' + this._placeholder() + ', ';
+                        sql += this.field(v[0]) + ' = ' + this.field(v[0]) + ' ' + v[1] + ' ' + result.sql + ', ';
                     }
-                    this._data.push(nv);
+                    this._data.push(...result.data);
                 }
             }
             else {
-                // --- 2, 3, 4, 5, 6, 7, 8 ---
+                // --- 对象赋值式：{字段: 值} ---
                 sql += this.field(k) + ' = ';
                 const result = this._processValue(v);
                 sql += result.sql + ', ';
@@ -497,14 +503,13 @@ export class Sql {
     _whereDataPosition = [0, 0];
     /**
      * --- 筛选器 ---
-     * --- 1. 'city': 'bj', 'type': '2' ---
-     * --- 2. ['type', '>', '1'] ---
-     * --- 3. ['type', 'in', ['1', '2']] ---
-     * --- 4. 'type': ['1', '2'] ---
-     * --- 5. '$or': [{'city': 'bj'}, {'city': 'sh'}, [['age', '>', '10']]], 'type': '2' ---
-     * --- 6. 'city_in': column('city_out') ---
-     * --- 7. ['JSON_CONTAINS(`uid`, ?)', ['hello']] ---
-     * --- 8. ['info', 'json', {'a': 1}] ---
+     * --- 标量相等：'city': 'bj', 'type': '2' ---
+     * --- 运算符条件：['type', '>', '1'] ---
+     * --- 集合条件：['type', 'in', ['1', '2']] 或 'type': ['1', '2'] ---
+     * --- 逻辑分组：'$or': [{'city': 'bj'}, {'city': 'sh'}, [['age', '>', '10']]] ---
+     * --- 字段比较：'city_in': column('city_out') ---
+     * --- 原始条件：['JSON_CONTAINS(`uid`, ?)', ['hello']] ---
+     * --- JSON 条件：['info', 'json', {'a': 1}] ---
      * @param s 筛选数据
      */
     where(s) {
@@ -546,18 +551,18 @@ export class Sql {
         for (const k in s) {
             const v = s[k];
             if (/^[0-9]+$/.test(k)) {
-                // --- 2, 3, 7 ---
+                // --- 数组条件或原始 SQL 条件 ---
                 if (v[2] === undefined) {
-                    // --- 7 ---
+                    // --- 原始 SQL 条件及参数 ---
                     sql += this.field(v[0]) + ' AND ';
                     if (v[1] !== undefined) {
                         data.push(...v[1]);
                     }
                 }
                 else if (typeof v[1] === 'string' && ['json', 'json_in', 'json_key', 'json_any', 'json_all', 'json_overlaps'].includes(v[1].toLowerCase())) {
-                    // --- json ---
+                    // --- JSON 操作符条件 ---
                     const op = v[1].toLowerCase();
-                    const nv = v[2];
+                    const nv = lSqlValue.unwrapJson(v[2]);
                     if (op === 'json') {
                         if (this._service === ESERVICE.MYSQL) {
                             sql += `JSON_CONTAINS(${this.field(v[0])}, ${this._placeholder()}) AND `;
@@ -614,7 +619,7 @@ export class Sql {
                     }
                 }
                 else if (v[2] === null) {
-                    // --- 3: null ---
+                    // --- NULL 比较 ---
                     let opera = v[1];
                     if (opera === '!=' || opera === '!==' || opera === '<>') {
                         opera = 'IS NOT';
@@ -628,7 +633,7 @@ export class Sql {
                     sql += this.field(v[0]) + ' ' + opera + ' NULL AND ';
                 }
                 else if (Array.isArray(v[2])) {
-                    // --- 3 ---
+                    // --- IN 等集合比较 ---
                     sql += this.field(v[0]) + ' ' + v[1].toUpperCase() + ' (';
                     for (const v1 of v[2]) {
                         if (Array.isArray(v1)) {
@@ -647,7 +652,7 @@ export class Sql {
                     sql = sql.slice(0, -2) + ') AND ';
                 }
                 else {
-                    // --- 2, 6 ---
+                    // --- 普通运算符或字段比较 ---
                     const nv = v[2];
                     // --- v[0] 也可以是 value() 包裹的字面量值，而不一定是字段名 ---
                     const isv0 = this._isValue(v[0]);
@@ -657,19 +662,23 @@ export class Sql {
                     }
                     const isf = this._isField(nv);
                     if (isf) {
-                        // --- 6. field ---
+                        // --- 字段比较 ---
                         sql += v0sql + ' ' + v[1] + ' ' + this.field(nv.value) + ' AND ';
                     }
                     else {
-                        sql += v0sql + ' ' + v[1] + ' ' + this._placeholder() + ' AND ';
-                        data.push(nv);
+                        const result = lSqlValue.isJson(nv) ? this._processValue(nv) : {
+                            'sql': this._placeholder(),
+                            'data': [nv],
+                        };
+                        sql += v0sql + ' ' + v[1] + ' ' + result.sql + ' AND ';
+                        data.push(...result.data);
                     }
                 }
             }
             else {
-                // --- 1, 4, 5, 6 ---
+                // --- 字段映射、逻辑分组与 IN 查询 ---
                 if (k.startsWith('$')) {
-                    // --- 5 - '$or': [{'city': 'bj'}, {'city': 'sh'}] ---
+                    // --- 逻辑条件分组，如 $or ---
                     const sp = ' ' + k.slice(1).split('-')[0].toUpperCase() + ' ';
                     sql += '(';
                     for (let v1 of v) {
@@ -685,21 +694,28 @@ export class Sql {
                     sql = sql.slice(0, -sp.length) + ') AND ';
                 }
                 else {
-                    // --- 1, 4, 6 ---
+                    // --- 单字段条件 ---
                     if (v === null) {
+                        // --- NULL 判断 ---
                         sql += this.field(k) + ' IS NULL AND ';
                     }
                     else if (typeof v === 'string' || typeof v === 'number') {
-                        // --- 1 ---
+                        // --- 标量相等 ---
                         sql += this.field(k) + ' = ' + this._placeholder() + ' AND ';
                         data.push(v);
                     }
+                    else if (lSqlValue.isJson(v)) {
+                        // --- JSON 相等 ---
+                        const result = this._processValue(v);
+                        sql += this.field(k) + ' = ' + result.sql + ' AND ';
+                        data.push(...result.data);
+                    }
                     else if (this._isField(v)) {
-                        // --- 6 ---
+                        // --- 字段相等 ---
                         sql += this.field(k) + ' = ' + this.field(v.value) + ' AND ';
                     }
                     else {
-                        // --- 4 - 'type': ['1', '2'] ---
+                        // --- IN 查询，如 'type': ['1', '2'] ---
                         if (v.length > 0) {
                             sql += this.field(k) + ' IN (';
                             for (const v1 of v) {
@@ -935,7 +951,7 @@ export class Sql {
      * --- 获取全部 data ---
      */
     getData() {
-        return this._data;
+        return lSqlValue.serializeList(this._data) ?? [];
     }
     /**
      * --- 获取定义的 pre ---
@@ -1096,48 +1112,6 @@ export class Sql {
     _placeholder() {
         return this._service === ESERVICE.MYSQL ? '?' : `$${this._placeholderCounter++}`;
     }
-    /**
-     * --- 返回 PostgreSQL VALUES 第一行的显式类型转换后缀，用于帮助 PostgreSQL 推断 VALUES 派生表列类型 ---
-     * @param v 要处理的值
-     */
-    _pgCastSuffix(v) {
-        if (v === null || v === undefined) {
-            return '';
-        }
-        if (typeof v === 'number') {
-            return Number.isInteger(v) ? '::bigint' : '::float8';
-        }
-        if (typeof v === 'boolean') {
-            return '::boolean';
-        }
-        if (v instanceof Buffer) {
-            return '::bytea';
-        }
-        if (Array.isArray(v)) {
-            // --- 函数式语法 ['FUNC(?)', [...]]，不加转换 ---
-            if (typeof v[0] === 'string' && v[0].includes('(')) {
-                return '';
-            }
-            // --- POLYGON ---
-            if (v[0]?.y !== undefined) {
-                return '::polygon';
-            }
-            // --- JSON 数组或 PG 原生数组（text[]、int[] 等），
-            //     不加转换，由 pg 驱动与目标列类型决定 ---
-            return '';
-        }
-        if (typeof v === 'object') {
-            // --- POINT ---
-            if (v.y !== undefined) {
-                return '::point';
-            }
-            // --- JSON 对象（用户应通过 sql.json() 包裹为字符串后传入），不加转换 ---
-            return '';
-        }
-        // --- string：保持 unknown 类型，兼容 text/varchar/jsonb 等目标列类型；
-        //     使用 sql.json() 包裹的 jsonb 数据经此路径，unknown 可隐式 cast 到 jsonb ---
-        return '';
-    }
     /**
      * --- 处理单个值,检测数据类型并返回 SQL 和 data ---
      * @param v 要处理的值
@@ -1151,6 +1125,12 @@ export class Sql {
         else if (v === null) {
             return { 'sql': 'NULL', 'data': [] };
         }
+        else if (lSqlValue.isJson(v)) {
+            return {
+                'sql': this._placeholder() + (this._service === ESERVICE.PGSQL ? '::jsonb' : ''),
+                'data': [lSqlValue.serialize(v)]
+            };
+        }
         else if (typeof v === 'string' || typeof v === 'number') {
             return { 'sql': this._placeholder(), 'data': [v] };
         }
@@ -1278,6 +1258,7 @@ export function get(opt) {
  * @param service 服务商，默认 MySQL
  */
 export function format(sql, data, service = ESERVICE.MYSQL) {
+    data = lSqlValue.serializeList(data) ?? [];
     if (service === ESERVICE.MYSQL) {
         return mysql2.format(sql, data);
     }
@@ -1359,9 +1340,10 @@ export function value(val) {
     };
 }
 /**
- * --- 将对象转换为 JSON 字符串并避开类型检查，用于适配 PostgreSQL 的 jsonb 字段 ---
- * @param obj 要转换的 JSON 对象
+ * --- 标记需要写入 JSON/jsonb 字段的值；实际序列化延迟到数据库边界 ---
+ * @param obj 原始 JSON 值
+ * @returns 类型保持不变的 JSON 包装值
  */
 export function json(obj) {
-    return lText.stringifyJson(obj);
+    return lSqlValue.json(obj);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maiyunnet/kebab",
-  "version": "9.15.0",
+  "version": "9.15.2",
   "description": "Simple, easy-to-use, and fully-featured Node.js framework that is ready-to-use out of the box.",
   "type": "module",
   "keywords": [