dolphindb 3.0.38 → 3.0.40

package/README.zh.md

@@ -64,20 +64,23 @@ https://www.npmjs.com/package/dolphindb
 
 ##### 1. 安装
 
-1.1. 在机器上安装最新版的 Node.js 及浏览器。
-    - windows: https://nodejs.org/en/download/current/
-    - linux: https://github.com/nodesource/distributions?tab=readme-ov-file#debian-and-ubuntu-based-distributions
+1.1. 在机器上安装最新版的 Node.js 及浏览器。  
+- windows: https://nodejs.org/en/download/prebuilt-installer/current
+- linux: https://github.com/nodesource/distributions?tab=readme-ov-file#debian-and-ubuntu-based-distributions  
+
 1.2. （可选）使用以下命令创建新项目。如果已有项目，可跳过此步。
-    ```bash
-    mkdir dolphindb-example
-    cd dolphindb-example
-    npm init --yes
-    ```
+```bash
+mkdir dolphindb-example
+cd dolphindb-example
+npm init --yes
+```
+
 1.3. 用编辑器打开 package.json 文件，在 `"main": "./index.js"` 下方加入一行 "type": "module", 这样能够启用 ECMAScript modules，在后面代码中可以使用 `import { DDB } from 'dolphindb'` 导入 npm 包。
+
 1.4. 在项目中安装 npm 包。
-    ```bash
-    npm install dolphindb
-    ```
+```bash
+npm install dolphindb
+```
 
 ##### 2. 使用
 

package/browser.d.ts

@@ -24,7 +24,8 @@ export declare enum DdbForm {
     /** 节点内部通信可能会使用，调用函数执行脚本一般不会返回这种类型 */
     chunk = 8,
     /** sysobj */
-    object = 9
+    object = 9,
+    tensor = 10
 }
 /** DolphinDB DataType
     对应的 array vector 类型为 64 + 基本类型
@@ -173,6 +174,35 @@ export interface DdbMatrixValue {
     cols: DdbVectorObj | null;
     data: DdbVectorValue;
 }
+/** 工具，取得某个 DdbType 的字节数 */
+export declare const ddb_tensor_bytes: Record<DdbType.bool | DdbType.char | DdbType.short | DdbType.int | DdbType.long | DdbType.float | DdbType.double, number>;
+type TensorElem = TensorData | boolean | number | bigint | null | string;
+interface TensorData extends Array<TensorElem> {
+}
+interface DdbTensorMetadata {
+    /** Tensor 的元素的数据类型 */
+    data_type: DdbType;
+    /** Tensor 类型 */
+    tensor_type: number;
+    /** 设备类型 */
+    device_type: number;
+    /** Tensor Flags */
+    tensor_flags: number;
+    /** 维度 */
+    dimensions: number;
+    /** shape, shape[i] 表示第 i 个维度的 size */
+    shape: number[];
+    /** strides, strides[i] 表示在第 i 个维度，一个元素与下一个元素的距离 */
+    strides: number[];
+    /** 保留值 */
+    preserve_value: bigint;
+    /** 元素个数 */
+    elem_count: number;
+}
+export interface DdbTensorValue extends DdbTensorMetadata {
+    /** 数据 */
+    data: Uint8Array;
+}
 export type DdbDictValue = [DdbVectorObj, DdbVectorObj];
 export interface DdbChartValue {
     /** 原属性 chartType  original: chartType */
@@ -207,7 +237,7 @@ export type DdbVectorValue = null | Uint8Array | Int8Array | Int16Array | Int32A
 Uint8Array[] | // blob
 DdbObj[] | // any
 DdbSymbolExtendedValue | DdbArrayVectorValue | DdbDecimal32VectorValue | DdbDecimal64VectorValue | DdbDecimal128VectorValue | DdbDurationVectorValue;
-export type DdbValue = DdbScalarValue | DdbVectorValue | DdbMatrixValue | DdbDictValue | DdbChartValue;
+export type DdbValue = DdbScalarValue | DdbVectorValue | DdbMatrixValue | DdbDictValue | DdbChartValue | DdbTensorValue;
 export type DdbStringObj = DdbObj<string>;
 export type DdbVectorObj<TValue extends DdbVectorValue = DdbVectorValue> = DdbObj<TValue>;
 export type DdbVectorAnyObj = DdbVectorObj<DdbObj[]>;
@@ -216,6 +246,7 @@ export type DdbTableObj<TColumns extends DdbVectorObj[] = DdbVectorObj[]> = DdbO
 export type DdbDictObj<TKeys extends DdbVectorObj = DdbVectorObj, TValues extends DdbVectorObj = DdbVectorObj> = DdbObj<[TKeys, TValues]>;
 export type DdbMatrixObj<TValue extends DdbMatrixValue = DdbMatrixValue> = DdbObj<TValue>;
 export type DdbChartObj = DdbObj<DdbChartValue>;
+export type DdbTensorObj = DdbObj<DdbTensorValue>;
 /** DdbObj.data() 返回的表格对象 */
 export interface DdbTableData<TRow = any> {
     /** 表名 */
@@ -227,6 +258,11 @@ export interface DdbTableData<TRow = any> {
     /** 表格数据，每一行的对象组成的数组 */
     data: TRow[];
 }
+/** DdbObj.data() 返回的 Tensor 对象 */
+export interface DdbTensorData extends DdbTensorMetadata {
+    /** 数据 */
+    data: TensorData;
+}
 /** DdbObj.data() 返回的矩阵对象 */
 export interface DdbMatrixData {
     /** 原始数据类型 */
@@ -294,7 +330,7 @@ export declare class DdbObj<TValue extends DdbValue = DdbValue> {
     pack(): Uint8Array;
     static pack_vector_body(value: DdbVectorValue, type: DdbType, length: number): ArrayBufferView[];
     /** 将 DdbObj 转换为 js 原生数据类型
-        - 标量对应 number, bigint 或者字符串
+        - 标量对应 number, bigint 或者字符串 (其中时间类型转换为常用的字符串表示)
         - 数组对应 js 原生数组
         - 表格对应 DdbTableData
         - 矩阵对应 DdbMatrixData
@@ -302,6 +338,20 @@ export declare class DdbObj<TValue extends DdbValue = DdbValue> {
         - 图对应 DdbChartValue */
     data<TResult extends any[]>(this: DdbVectorObj, options?: ConvertOptions): TResult;
     data<TResult = any>(this: DdbObj, options?: ConvertOptions): TResult;
+    /** 构建 Tensor
+    @param buildParams 构建参数
+    @param limit 限制每个维度最大元素个数（仅用于 log，不作他用）
+    @returns  */
+    static parse_tensor(buildParams: {
+        currentDim: number;
+        dimensions: number;
+        rawData: Uint8Array;
+        le: boolean;
+        dataByte: number;
+        dataType: DdbType;
+        shape: number[];
+        strides: number[];
+    }, limit?: number): TensorData;
     toString(options?: InspectOptions): string;
     inspect_type(): string;
     /** 自动转换 js string, boolean 为 DdbObj */
@@ -357,7 +407,7 @@ export interface ConvertOptions {
     /** `'string'` blob 类型数据的格式 */
     blob?: 'string' | 'binary';
 }
-export declare function convert(type: DdbType, value: DdbValue, le: boolean, { blob }?: ConvertOptions): string | number | bigint | boolean | Uint8Array | DdbFunctionDefValue | DdbDurationValue | DdbDecimal32Value | DdbDecimal64Value | DdbDecimal32VectorValue | Int32Array | DdbDecimal64VectorValue | BigInt64Array | DdbDecimal128VectorValue | BigInt128Array | DdbSymbolExtendedValue | string[] | Int8Array | Int16Array | Float32Array | Float64Array | DdbArrayVectorValue | DdbMatrixValue | Uint8Array[] | DdbObj<DdbValue>[] | DdbDurationVectorValue | DdbChartValue | number[];
+export declare function convert(type: DdbType, value: DdbValue, le: boolean, { blob }?: ConvertOptions): string | number | bigint | boolean | Uint8Array | DdbFunctionDefValue | DdbDurationValue | DdbDecimal32Value | DdbDecimal64Value | DdbDecimal32VectorValue | Int32Array | DdbDecimal64VectorValue | BigInt64Array | DdbDecimal128VectorValue | BigInt128Array | DdbSymbolExtendedValue | string[] | Int8Array | Int16Array | Float32Array | Float64Array | DdbArrayVectorValue | DdbMatrixValue | Uint8Array[] | DdbObj<DdbValue>[] | DdbDurationVectorValue | number[] | DdbTensorValue | DdbChartValue;
 /** 转换一个向量到 js 原生数组 */
 export declare function converts(type: DdbType, value: DdbVectorValue, rows: number, le: boolean, options?: ConvertOptions): any[];
 export declare class DdbVoid extends DdbObj<undefined> {

package/browser.js

@@ -33,6 +33,7 @@ export var DdbForm;
     DdbForm[DdbForm["chunk"] = 8] = "chunk";
     /** sysobj */
     DdbForm[DdbForm["object"] = 9] = "object";
+    DdbForm[DdbForm["tensor"] = 10] = "tensor";
 })(DdbForm || (DdbForm = {}));
 /** DolphinDB DataType
     对应的 array vector 类型为 64 + 基本类型
@@ -129,6 +130,16 @@ export var DdbVoidType;
     DdbVoidType[DdbVoidType["default"] = 2] = "default";
 })(DdbVoidType || (DdbVoidType = {}));
 export const dictables = new Set([DdbType.any, DdbType.string, DdbType.double, DdbType.float, DdbType.int, DdbType.long]);
+/** 工具，取得某个 DdbType 的字节数 */
+export const ddb_tensor_bytes = {
+    [DdbType.bool]: 1,
+    [DdbType.char]: 1,
+    [DdbType.short]: 2,
+    [DdbType.int]: 4,
+    [DdbType.long]: 8,
+    [DdbType.float]: 4,
+    [DdbType.double]: 8,
+};
 /** 可以表示所有 DolphinDB 数据库中的数据类型  Can represent data types in all DolphinDB databases */
 export class DdbObj {
     static dec = new TextDecoder('utf-8');
@@ -366,6 +377,47 @@ export class DdbObj {
                     },
                 });
             }
+            case DdbForm.tensor: {
+                // 元数据
+                const tensorType = buf[2];
+                const deviceType = buf[3];
+                const dv = new DataView(buf.buffer, buf.byteOffset);
+                const tensorFlags = dv.getUint32(4, le);
+                const dimensions = dv.getInt32(8, le);
+                const shapes = [];
+                const strides = [];
+                const shapeStart = 12;
+                const stridesStart = shapeStart + dimensions * 8;
+                const preserveValueStart = stridesStart + dimensions * 8;
+                const preserveValue = dv.getBigInt64(preserveValueStart, le);
+                const storageStart = preserveValueStart + 8;
+                const elemCount = dv.getBigInt64(storageStart, le);
+                const dataStart = storageStart + 8;
+                for (let d = 0; d < dimensions; d++) {
+                    const getNumOffset = d * 8;
+                    shapes.push(Number(dv.getBigInt64(shapeStart + getNumOffset, le)));
+                    strides.push(Number(dv.getBigInt64(stridesStart + getNumOffset, le)));
+                }
+                const dataBuffer = buf.subarray(dataStart);
+                return new this({
+                    le,
+                    form,
+                    type,
+                    length: i_data + buf_data.length,
+                    value: {
+                        data_type: type,
+                        tensor_type: tensorType,
+                        device_type: deviceType,
+                        tensor_flags: tensorFlags,
+                        dimensions,
+                        shape: shapes,
+                        strides,
+                        preserve_value: preserveValue,
+                        elem_count: Number(elemCount),
+                        data: dataBuffer
+                    }
+                });
+            }
             default:
                 return new this({
                     le,
@@ -1016,6 +1068,38 @@ export class DdbObj {
                         ...DdbObj.pack_vector_body(data, this.type, this.rows * this.cols)
                     ];
                 }
+                case DdbForm.tensor: {
+                    const { le, value } = this;
+                    const { tensor_type, device_type, tensor_flags, dimensions, shape, strides, preserve_value, elem_count, data } = value;
+                    // 计算总的字节长度
+                    const totalLength = 10 + dimensions * 8 * 2 + 8 + 8 + data.length; // 12 字节元数据 + 维度信息 + 保留值和元素数量 + 数据部分
+                    const buffer = new ArrayBuffer(totalLength);
+                    const dv = new DataView(buffer);
+                    const uint8Array = new Uint8Array(buffer);
+                    // 写入元数据
+                    // uint8Array[0] = type;
+                    // uint8Array[1] = form;
+                    uint8Array[0] = tensor_type;
+                    uint8Array[1] = device_type;
+                    dv.setUint32(2, tensor_flags, le);
+                    dv.setInt32(6, dimensions, le);
+                    // 写入形状和步长
+                    const shapeStart = 10;
+                    const stridesStart = shapeStart + dimensions * 8;
+                    for (let d = 0; d < dimensions; d++) {
+                        dv.setBigInt64(shapeStart + d * 8, BigInt(shape[d]), le);
+                        dv.setBigInt64(stridesStart + d * 8, BigInt(strides[d]), le);
+                    }
+                    // 写入保留值和元素数量
+                    const preserveValueStart = stridesStart + dimensions * 8;
+                    dv.setBigInt64(preserveValueStart, preserve_value, le);
+                    const storageStart = preserveValueStart + 8;
+                    dv.setBigInt64(storageStart, BigInt(elem_count), le);
+                    // 写入数据
+                    const dataStart = storageStart + 8;
+                    uint8Array.set(data, dataStart);
+                    return [uint8Array];
+                }
                 default:
                     throw new Error(t('vector {{type}} 暂不支持序列化', { type: get_type_name(type) }));
             }
@@ -1166,10 +1250,99 @@ export class DdbObj {
                     data: seq(rows, i => seq(ncolumns, j => jsdata[j * rows + i]))
                 };
             }
+            case DdbForm.tensor: {
+                const { data_type, tensor_type, device_type, tensor_flags, dimensions, shape, strides, preserve_value, elem_count, data, } = this.value;
+                const dataByte = ddb_tensor_bytes[data_type];
+                const returnData = {
+                    data_type,
+                    tensor_type,
+                    device_type,
+                    tensor_flags,
+                    dimensions,
+                    shape,
+                    strides,
+                    preserve_value,
+                    elem_count,
+                    data: DdbObj.parse_tensor({ currentDim: 0, dimensions, rawData: data, le: this.le, dataByte, dataType: data_type, shape, strides })
+                };
+                return returnData;
+            }
             default:
                 throw new Error(t('{{form}} {{type}} 暂不支持 data()', { form, type: get_type_name(type) }));
         }
     }
+    /** 构建 Tensor
+    @param buildParams 构建参数
+    @param limit 限制每个维度最大元素个数（仅用于 log，不作他用）
+    @returns  */
+    static parse_tensor(buildParams, limit = -1) {
+        const { currentDim, dimensions, rawData, le, dataByte, dataType, shape, strides } = buildParams;
+        const tensor = [];
+        const dv = new DataView(rawData.buffer, rawData.byteOffset);
+        for (let i = 0; i < shape[currentDim]; i++)
+            if (currentDim >= dimensions - 1) {
+                if (limit > 0 && i >= limit) {
+                    tensor.push('...');
+                    break;
+                }
+                // 直接转换到对应的数组
+                const offset = i * dataByte * Number(strides[currentDim]);
+                switch (dataType) {
+                    case DdbType.bool: {
+                        const value = dv.getInt8(offset);
+                        tensor.push(value === nulls.int8 ? null : Boolean(value));
+                        break;
+                    }
+                    case DdbType.char: {
+                        const value = dv.getInt8(offset);
+                        tensor.push(value === nulls.int8 ? null : value);
+                        break;
+                    }
+                    case DdbType.short: {
+                        const value = dv.getInt16(offset, le);
+                        tensor.push(value === nulls.int16 ? null : value);
+                        break;
+                    }
+                    case DdbType.int: {
+                        const value = dv.getInt32(offset, le);
+                        tensor.push(value === nulls.int32 ? null : value);
+                        break;
+                    }
+                    case DdbType.long: {
+                        const value = dv.getBigInt64(offset, le);
+                        tensor.push(value === nulls.int64 ? null : value);
+                        break;
+                    }
+                    case DdbType.float: {
+                        const value = dv.getFloat32(offset, le);
+                        tensor.push(value === nulls.float32 ? null : value);
+                        break;
+                    }
+                    case DdbType.double: {
+                        const value = dv.getFloat64(offset, le);
+                        tensor.push(value === nulls.double ? null : value);
+                        break;
+                    }
+                }
+            }
+            else {
+                // 起点
+                const start = strides[currentDim] * i * dataByte;
+                // 终点
+                const end = start + strides[currentDim] * 1 * dataByte;
+                tensor.push(DdbObj.parse_tensor({
+                    currentDim: currentDim + 1,
+                    dimensions,
+                    rawData: rawData.subarray(Number(start), Number(end)),
+                    le,
+                    dataByte,
+                    shape,
+                    strides,
+                    dataType
+                }, limit));
+            }
+        return tensor;
+    }
     toString(options = { nullstr: true, quote: true }) {
         const type = this.inspect_type();
         const data = (() => {
@@ -1298,6 +1471,20 @@ export class DdbObj {
                 }
                 case DdbForm.chart:
                     return JSON.stringify(this.value, (key, value) => key === 'data' ? value.toString(options) : value, 4);
+                case DdbForm.tensor: {
+                    const tensorVal = this.value;
+                    const retd = DdbObj.parse_tensor({
+                        currentDim: 0,
+                        dimensions: tensorVal.dimensions,
+                        rawData: tensorVal.data,
+                        le: this.le,
+                        dataByte: ddb_tensor_bytes[tensorVal.data_type],
+                        dataType: tensorVal.data_type,
+                        shape: tensorVal.shape,
+                        strides: tensorVal.strides
+                    }, 5);
+                    return JSON.stringify(retd).replaceAll('"..."', '...');
+                }
             }
             return String(this.value);
         })();
@@ -1330,6 +1517,8 @@ export class DdbObj {
                 return `chart<${DdbChartType[this.value.type]}>`;
             case DdbForm.matrix:
                 return `matrix<${tname}>[${this.rows}r][${this.cols}c]`;
+            case DdbForm.tensor:
+                return `tensor<${generate_array_type(DdbType[this.value.data_type], this.value.shape)}>`;
             default:
                 return `${DdbForm[this.form]} ${tname}`;
         }
@@ -3361,6 +3550,13 @@ function set_big_uint_128(dataView, byte_offset, value, le = true) {
 function set_big_int_128(dataview, byte_offset, value, le = true) {
     set_big_uint_128(dataview, byte_offset, value, le);
 }
+function generate_array_type(baseType, dimensions) {
+    let result = baseType;
+    dimensions.forEach(dimension => {
+        result += `[${dimension}]`;
+    });
+    return result;
+}
 // 大端
 // const dataBE = new ArrayBuffer(16)
 // const dataViewBE = new DataView(dataBE)