@maiyunnet/kebab 9.15.1 → 9.15.3

package/index.d.ts

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

package/index.js

@@ -6,7 +6,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export const VER = '9.15.1';
+export const VER = '9.15.3';
 // --- 服务端用的路径 ---
 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/s3.d.ts

@@ -101,6 +101,13 @@ export declare class S3 {
      * @param bucket bucket 名
      */
     getObject(key: string, bucket?: string): Promise<false | (stream.Readable & import("@smithy/types").SdkStreamMixin) | (Blob & import("@smithy/types").SdkStreamMixin) | (ReadableStream<any> & import("@smithy/types").SdkStreamMixin) | undefined>;
+    /**
+     * --- 获取对象 Buffer ---
+     * @param key 对象路径
+     * @param bucket bucket 名
+     * @returns 对象内容，获取失败或对象无内容时返回 false
+     */
+    getObjectBuffer(key: string, bucket?: string): Promise<Buffer | false>;
     /**
      * --- 删除对象 ---
      * @param key 对象路径

package/lib/s3.js

@@ -163,6 +163,29 @@ export class S3 {
             return false;
         }
     }
+    /**
+     * --- 获取对象 Buffer ---
+     * @param key 对象路径
+     * @param bucket bucket 名
+     * @returns 对象内容，获取失败或对象无内容时返回 false
+     */
+    async getObjectBuffer(key, bucket) {
+        try {
+            const go = new s3.GetObjectCommand({
+                'Bucket': bucket ?? this._bucket,
+                'Key': key
+            });
+            const r = await this._link.send(go);
+            if (!r.Body) {
+                return false;
+            }
+            return Buffer.from(await r.Body.transformToByteArray());
+        }
+        catch (e) {
+            lCore.log(this._ctr, '[LIB][S3][getObjectBuffer] ' + lText.stringifyJson(e.message ?? '').slice(1, -1).replace(/"/g, '""'), '-error');
+            return false;
+        }
+    }
     /**
      * --- 删除对象 ---
      * @param key 对象路径

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;