dolphindb 3.0.2 → 3.0.20

package/README.md

@@ -516,8 +516,7 @@ export interface StreamingData extends StreamingParams {
 # https://nodejs.org/en/download/current/
 
 # Install the pnpm package manager
-corepack enable
-corepack prepare pnpm@latest --activate
+npm install -g pnpm
 
 git clone https://github.com/dolphindb/api-javascript.git
 

package/README.zh.md

@@ -512,8 +512,7 @@ export interface StreamingData extends StreamingParams {
 # 安装最新版的 nodejs (见上文)
 
 # 安装 pnpm 包管理器
-corepack enable
-corepack prepare pnpm@latest --activate
+npm install -g pnpm
 
 git clone https://github.com/dolphindb/api-javascript.git
 

package/browser.d.ts

@@ -1,11 +1,117 @@
 import 'xshell/prototype.browser.js';
 import { Lock } from 'xshell/utils.browser.js';
 import { type WebSocketConnectionError } from 'xshell/net.browser.js';
-import { type DdbDecimal128Value, type DdbDecimal128VectorValue } from './data-types/decimal-128.js';
-import type { BigInt128Array } from './shared/bigint-128-array.js';
-import { DdbChartType, DdbDurationUnit, DdbForm, DdbFunctionType, DdbType, DdbVoidType } from './shared/constants.js';
-export * from './shared/constants.js';
-export type { DdbDecimal128Value, DdbDecimal128VectorValue } from './data-types/decimal-128.js';
+export declare const nulls: {
+    readonly int8: -128;
+    readonly int16: -32768;
+    readonly int32: -2147483648;
+    readonly int64: -9223372036854775808n;
+    readonly int128: -170141183460469231731687303715884105728n;
+    readonly float32: -3.4028234663852886e+38;
+    /** -Number.MAX_VALUE */
+    readonly double: number;
+    readonly bytes16: Uint8Array;
+};
+export declare enum DdbForm {
+    scalar = 0,
+    vector = 1,
+    pair = 2,
+    matrix = 3,
+    set = 4,
+    dict = 5,
+    table = 6,
+    chart = 7,
+    /** 节点内部通信可能会使用，调用函数执行脚本一般不会返回这种类型 */
+    chunk = 8,
+    /** sysobj */
+    object = 9
+}
+/** DolphinDB DataType
+    对应的 array vector 类型为 64 + 基本类型
+    对应的 extended 类型为 128 + 基本类型 */
+export declare enum DdbType {
+    void = 0,
+    bool = 1,
+    char = 2,
+    short = 3,
+    int = 4,
+    long = 5,
+    date = 6,
+    month = 7,
+    time = 8,
+    minute = 9,
+    second = 10,
+    datetime = 11,
+    timestamp = 12,
+    nanotime = 13,
+    nanotimestamp = 14,
+    float = 15,
+    double = 16,
+    symbol = 17,
+    string = 18,
+    uuid = 19,
+    functiondef = 20,
+    handle = 21,
+    code = 22,
+    datasource = 23,
+    resource = 24,
+    any = 25,
+    compressed = 26,
+    dict = 27,
+    datehour = 28,
+    ipaddr = 30,
+    int128 = 31,
+    blob = 32,
+    complex = 34,
+    point = 35,
+    duration = 36,
+    decimal32 = 37,
+    decimal64 = 38,
+    decimal128 = 39,
+    object = 40,
+    pynone = 41,
+    symbol_extended = 145
+}
+export declare enum DdbFunctionType {
+    SystemFunc = 0,
+    SystemProc = 1,
+    OperatorFunc = 2,
+    UserDefinedFunc = 3,
+    PartialFunc = 4,
+    DynamicFunc = 5,
+    PiecewiseFunc = 6,
+    JitFunc = 7,
+    JitPartialFunc = 8
+}
+export declare enum DdbDurationUnit {
+    ns = 0,
+    us = 1,
+    ms = 2,
+    s = 3,
+    m = 4,
+    H = 5,
+    d = 6,
+    w = 7,
+    M = 8,
+    y = 9,
+    B = 10
+}
+export declare enum DdbChartType {
+    area = 0,
+    bar = 1,
+    column = 2,
+    histogram = 3,
+    line = 4,
+    pie = 5,
+    scatter = 6,
+    trend = 7,
+    kline = 8
+}
+export declare enum DdbVoidType {
+    undefined = 0,
+    null = 1,
+    default = 2
+}
 export interface DdbFunctionDefValue {
     type: DdbFunctionType;
     name: string;
@@ -16,17 +122,23 @@ export interface DdbDurationValue {
     data: number;
 }
 export interface DdbDecimal32Value {
-    /** int32, data 需要除以 10^scale 得到原值  data needs to be divided by 10^scale to get the original value */
+    /** int32, data 需要除以 10^scale 得到原值 */
     scale: number;
     /** int32, 空值为 null  ddb null is js null */
     data: number | null;
 }
 export interface DdbDecimal64Value {
-    /** int32, data 需要除以 10^scale 得到原值  data needs to be divided by 10^scale to get the original value */
+    /** int32, data 需要除以 10^scale 得到原值 */
     scale: number;
     /** int64, 空值为 null  empty value is null */
     data: bigint | null;
 }
+export interface DdbDecimal128Value {
+    /** int32, data 需要除以 10^scale 得到原值 */
+    scale: number;
+    /** int128, 空值为 null  empty value is null */
+    data: bigint | null;
+}
 export interface DdbDecimal32VectorValue {
     scale: number;
     data: Int32Array;
@@ -35,6 +147,11 @@ export interface DdbDecimal64VectorValue {
     scale: number;
     data: BigInt64Array;
 }
+export interface DdbDecimal128VectorValue {
+    scale: number;
+    data: BigInt128Array;
+}
+export type DdbDecimalVectorValue = DdbDecimal32VectorValue | DdbDecimal64VectorValue | DdbDecimal128VectorValue;
 export type DdbDurationVectorValue = DdbDurationValue[];
 export interface DdbSymbolExtendedValue {
     base_id: number;
@@ -50,9 +167,10 @@ export interface DdbArrayVectorBlock {
 export type DdbArrayVectorValue = DdbArrayVectorBlock[] & /* decimal 数据会有这个属性 */ {
     scale?: number;
 };
+export declare const dictables: Set<DdbType>;
 export interface DdbMatrixValue {
-    rows: DdbVectorObj;
-    cols: DdbVectorObj;
+    rows: DdbVectorObj | null;
+    cols: DdbVectorObj | null;
     data: DdbVectorValue;
 }
 export type DdbDictValue = [DdbVectorObj, DdbVectorObj];
@@ -98,6 +216,32 @@ 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>;
+/** DdbObj.data() 返回的表格对象 */
+export interface DdbTableData<TRow = any> {
+    /** 表名 */
+    name: string;
+    /** 每一列的名称 */
+    columns: string[];
+    /** 每一列的原始 ddb 数据类型 */
+    types: DdbType[];
+    /** 表格数据，每一行的对象组成的数组 */
+    data: TRow[];
+}
+/** DdbObj.data() 返回的矩阵对象 */
+export interface DdbMatrixData {
+    /** 原始数据类型 */
+    type: DdbType;
+    /** 行数 */
+    nrows: number;
+    /** 列数 */
+    ncolumns: number;
+    /** 行名称 */
+    rows?: any[];
+    /** 列名称 */
+    columns?: any[];
+    /** 数据， data[0][1] 为第 0 行第 1 列数据 */
+    data: any[][];
+}
 /** 可以表示所有 DolphinDB 数据库中的数据类型  Can represent data types in all DolphinDB databases */
 export declare class DdbObj<TValue extends DdbValue = DdbValue> {
     static dec: TextDecoder;
@@ -118,15 +262,13 @@ export declare class DdbObj<TValue extends DdbValue = DdbValue> {
     length: number;
     /** table name / column name */
     name?: string;
-    /**
-        最低维、第 1 维
+    /** 最低维、第 1 维
         - vector: rows = n, cols = 1
         - pair:   rows = 2, cols = 1
         - matrix: rows = n, cols = m
         - set:    同 vector
         - dict:   包含 keys, values 向量
-        - table:  同 matrix
-    */
+        - table:  同 matrix */
     rows?: number;
     /** 第 2 维 */
     cols?: number;
@@ -142,8 +284,7 @@ export declare class DdbObj<TValue extends DdbValue = DdbValue> {
     static parse(buf: Uint8Array, le: boolean): DdbObj<DdbValue>;
     static parse_scalar(buf: Uint8Array, le: boolean, type: DdbType): [number, DdbScalarValue];
     /** parse: rows, cols, items
-        返回的 ddbobj.length 不包括 vector 的 type 和 form
-    */
+        返回的 ddbobj.length 不包括 vector 的 type 和 form */
     static parse_vector(buf: Uint8Array, le: boolean, type: DdbType): DdbVectorObj;
     /** 有可能没有字节对齐，不能直接使用原有 message 的 arraybuffer, 统一复制出来，让原有 arraybuffer 被回收掉比较好 */
     static parse_vector_items(buf: Uint8Array, le: boolean, type: DdbType, length: number): [
@@ -152,25 +293,36 @@ 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 或者字符串
+        - 数组对应 js 原生数组
+        - 表格对应 DdbTableData
+        - 矩阵对应 DdbMatrixData
+        - 字典对应普通的 js 对象 Record<string, any>
+        - 图对应 DdbChartValue */
+    data<TResult extends any[]>(this: DdbVectorObj): TResult;
+    data<TResult = any>(this: DdbObj): TResult;
     toString(options?: InspectOptions): string;
     inspect_type(): string;
     /** 自动转换 js string, boolean 为 DdbObj */
     static to_ddbobj(value: DdbObj | string | boolean): DdbObj;
     /** 转换 js 数组为 DdbObj[] */
     static to_ddbobjs(values: (DdbObj | string | boolean)[]): DdbObj<DdbValue>[];
+    /** @deprecated 用 data() */
     to_cols(): {
         title: string;
         dataIndex: string;
         render: (value: any) => string;
     }[];
-    /** 将 table 转换为 rows，空值转换为 null */
+    /** 将 table 转换为 rows，空值转换为 null
+        @deprecated 用 data() */
     to_rows<T extends Record<string, any> = Record<string, any>>(): T[];
     /** 将 dict<string, any> 自动转换为 js object (Record<string, any>)  Automatically convert dict<string, any> to js object (Record<string, any>)
+        @deprecated 用 data()
         - options?:
             - strip?: `false` 是否将 dict<string, any> 中的 value 直接提取、剥离出来作为 js object 的 value (丢弃 DdbObj 中的其余信息，只保留 value)
             - deep?: `false` 是否递归转换
-                Whether to convert recursively
-    */
+                Whether to convert recursively */
     to_dict<T extends Record<string, DdbObj> = Record<string, DdbObj>>(): T;
     to_dict<T extends Record<string, any> = Record<string, any>>(options: {
         strip: true;
@@ -180,6 +332,11 @@ export declare class DdbObj<TValue extends DdbValue = DdbValue> {
         deep?: boolean;
     }): T;
 }
+/** 根据 DdbType 获取其名称，array vector type 自动在后面加上 [] */
+export declare function get_type_name(type: DdbType): string;
+export declare function is_decimal_type(type: DdbType): boolean;
+export declare function is_decimal_null_value(type: DdbType, value: number | bigint): boolean;
+export declare function get_duration_unit(code: number): string;
 export interface InspectOptions {
     /** `false` */
     colors?: boolean;
@@ -187,7 +344,7 @@ export interface InspectOptions {
     decimals?: number;
     /** `false` 决定 null 值如何返回. nullstr ? 'null' : '' */
     nullstr?: boolean;
-    /** `false` 决定 string, symbol, char 类型是否加引号 */
+    /** `在 format 中默认为 false，在 toString 中默认为 true` 决定 string, symbol, char 类型是否加引号 */
     quote?: boolean;
     /** `true` 决定格式化后的数据是否有千分位 */
     grouping?: boolean;
@@ -196,6 +353,9 @@ export interface InspectOptions {
 export declare function format(type: DdbType, value: DdbValue, le: boolean, options?: InspectOptions): string;
 /** 格式化向量、集合中的第 index 项为字符串，空值返回 'null' 字符串  formatted vector, the index-th item in the collection is a string, a null value returns a 'null' string */
 export declare function formati(obj: DdbVectorObj, index: number, options?: InspectOptions): string;
+export declare function convert(type: DdbType, value: DdbValue, le: boolean): 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[];
+/** 转换一个向量到 js 原生数组 */
+export declare function converts(type: DdbType, value: DdbVectorValue, rows: number, le: boolean): any[];
 export declare class DdbVoid extends DdbObj<undefined> {
     constructor(value?: DdbVoidType);
 }
@@ -370,15 +530,17 @@ export interface StreamingMessage extends StreamingParams {
     error?: Error;
 }
 export declare const winsize: 100000;
+export interface DdbEvalOptions {
+    urgent?: boolean;
+    listener?: DdbMessageListener;
+    parse_object?: boolean;
+}
 type DdbRpcType = 'script' | 'function' | 'variable' | 'connect';
-export interface DdbRpcOptions {
+export interface DdbRpcOptions extends DdbEvalOptions {
     script?: string;
     func?: string;
     args?: (DdbObj | string | boolean)[];
     vars?: string[];
-    urgent?: boolean;
-    listener?: DdbMessageListener;
-    parse_object?: boolean;
     skip_connection_check?: boolean;
     on_more_messages?: (buffer: Uint8Array) => void;
 }
@@ -410,6 +572,15 @@ export interface DdbOptions {
     sql?: SqlStandard;
     streaming?: StreamingParams;
     verbose?: boolean;
+    proxy?: string;
+}
+export interface DdbCallOptions extends DdbEvalOptions {
+    node?: string;
+    nodes?: string[];
+    func_type?: DdbFunctionType;
+    add_node_alias?: boolean;
+    skip_connection_check?: boolean;
+    on_more_messages?: DdbRpcOptions['on_more_messages'];
 }
 export declare class DDB {
     /** 当前的 session id (http 或 tcp) */
@@ -418,8 +589,7 @@ export declare class DDB {
     dec: TextDecoder;
     enc: TextEncoder;
     /** DolphinDB WebSocket URL
-        e.g. `ws://127.0.0.1:8848/`, `wss://dolphindb.com`
-    */
+        e.g. `ws://127.0.0.1:8848/`, `wss://dolphindb.com` */
     url: string;
     /** 为所有 websocket 操作加锁，包括设置 this.on_message, this.on_error, websocket.send */
     lwebsocket: Lock<WebSocket>;
@@ -445,7 +615,6 @@ export declare class DDB {
     print_object_buffer: boolean;
     print_message: boolean;
     parse_object: boolean;
-    pnode_run_defined: boolean;
     /** 在 websocket 收到的第一个 error 时，
         在 connect_websocket 的 on_error 回调中构造 DdbConnectionError 并保存到 DDB 对象上，
         这个 error 的错误信息最准确 */
@@ -456,6 +625,8 @@ export declare class DDB {
     pconnect: Promise<void>;
     /** 首次定义 pnode_run 的 promise，保证并发调用 rpc 时只定义一次 pnode_run */
     ppnode_run: Promise<DdbVoid>;
+    /** 首次定义 invoke 的 promise，保证并发调用 rpc 时只定义一次 invoke */
+    pinvoke: Promise<DdbVoid>;
     get connected(): boolean;
     /**
         使用 WebSocket URL 初始化连接到 DolphinDB 的实例（不建立实际的网络连接）
@@ -547,13 +718,8 @@ export declare class DDB {
                 不做解析，以便后续转发、序列化
                 Set parse_object during this rpc, and restore the original after the end.
                 When it is false, the returned DdbObj only contains buffer and le without parsing,
-                so as to facilitate subsequent forwarding and serialization
-    */
-    eval<T extends DdbObj>(script: string, { urgent, listener, parse_object, }?: {
-        urgent?: boolean;
-        listener?: DdbMessageListener;
-        parse_object?: boolean;
-    }): Promise<T>;
+                so as to facilitate subsequent forwarding and serialization */
+    eval<T extends DdbObj>(script: string, { urgent, listener, parse_object, }?: DdbEvalOptions): Promise<T>;
     /** call function through websocket (function command)
         - func: 函数名  function name
         - args?: `[ ]` 调用参数 (传入的原生 string 和 boolean 会被自动转换为 DdbObj<string> 和 DdbObj<boolean>)
@@ -580,17 +746,24 @@ export declare class DDB {
                 将这个 flag 设为 true 跳过连接状态检查
                 (internal use) When await ddb.connect() establishes a connection for the first time, you cannot call await this.connect() again to ensure the connection status, which will lead to circular dependencies.
                  Set this flag to true to skip connection status checks */
-    call<TResult extends DdbObj>(func: string, args?: (DdbObj | string | boolean)[], { urgent, node, nodes, func_type, add_node_alias, listener, parse_object, skip_connection_check, on_more_messages }?: {
-        urgent?: boolean;
-        node?: string;
-        nodes?: string[];
-        func_type?: DdbFunctionType;
-        add_node_alias?: boolean;
-        listener?: DdbMessageListener;
-        parse_object?: boolean;
-        skip_connection_check?: boolean;
-        on_more_messages?: DdbRpcOptions['on_more_messages'];
-    }): Promise<TResult>;
+    call<TResult extends DdbObj>(func: string, args?: (DdbObj | string | boolean)[], { urgent, node, nodes, func_type, add_node_alias, listener, parse_object, skip_connection_check, on_more_messages }?: DdbCallOptions): Promise<TResult>;
+    /** 调用 dolphindb 函数，传入 js 原生数组作为参数，返回 js 原生对象或值（调用 DdbObj.data() 后的结果）
+        - func: 函数名
+        - args?: `[ ]` 调用参数，可以是 js 原生数组
+        - options?: 调用选项
+            - urgent?: 紧急 flag。使用 urgent worker 执行，防止被其它作业阻塞
+            - node?: 设置结点 alias 时发送到集群中对应的结点执行 (使用 DolphinDB 中的 rpc 方法)
+            - nodes?: 设置多个结点 alias 时发送到集群中对应的多个结点执行 (使用 DolphinDB 中的 pnodeRun 方法)
+            - func_type?: 设置 node 参数且参数数组为空时必传，需指定函数类型，其它情况下不传
+            - add_node_alias?: 设置 nodes 参数时选传，其它情况不传
+            - listener?: 处理本次 rpc 期间的消息 (DdbMessage) */
+    invoke<TResult = any>(func: string, args?: any[], options?: DdbCallOptions): Promise<TResult>;
+    /** 执行 dolphindb 脚本，返回 js 原生对象或值（调用 DdbObj.data() 后的结果）
+        - script?: 执行的脚本
+        - options?: 执行选项
+            - urgent?: 紧急 flag，确保提交的脚本使用 urgent worker 处理，防止被其它作业阻塞
+            - listener?: 处理本次 rpc 期间的消息 (DdbMessage) */
+    execute<TResult = any>(script: string, options?: DdbEvalOptions): Promise<TResult>;
     /** upload variable through websocket (variable command) */
     upload(
     /** 上传的变量名  Uploaded variables' name */
@@ -623,3 +796,30 @@ export interface DdbErrorMessage {
     data: DdbDatabaseError;
 }
 export type DdbMessage = DdbPrintMessage | DdbObjectMessage | DdbErrorMessage;
+export declare class BigInt128Array {
+    static of(...items: bigint[]): BigInt128Array;
+    static from(arrayLike: ArrayLike<bigint>): BigInt128Array;
+    static from<U>(arrayLike: ArrayLike<U>, mapfn: (v: U, k: number) => bigint, thisArg?: any): BigInt128Array;
+    readonly BYTES_PER_ELEMENT: number;
+    readonly buffer: ArrayBufferLike;
+    readonly byteLength: number;
+    readonly byteOffset: number;
+    constructor(length?: number);
+    constructor(array: Iterable<bigint>);
+    constructor(buffer: ArrayBufferLike, byteOffset?: number, length?: number);
+    get length(): number;
+    set(array: ArrayLike<bigint>, offset?: number): void;
+    at(index: number): bigint;
+    subarray(begin?: number, end?: number): BigInt128Array;
+    [Symbol.iterator](): {
+        next(): {
+            value: bigint;
+            done: boolean;
+        } | {
+            done: boolean;
+            value?: undefined;
+        };
+    };
+    toString(): string;
+}
+export {};