dolphindb 2.0.502 → 2.0.505

package/README.md

@@ -54,23 +54,24 @@ let ddb = new DDB('ws://127.0.0.1:8848')
 await ddb.connect()
 ```
 
-#### Connect Method Declaration
+#### DDB options
 ```ts
-async connect (
-    options?: {
-        /** by default, the WebSocket URL passed in when the instance is initialized is used */
-        ws_url?: string
-        
-        /** whether to automatically log in after the connection is established, the default is true */
-        login?: boolean
-        
-        /** DolphinDB username */
-        username?: string
-        
-        /** DolphinDB password */
-        password?: string
-    } = { }
-): Promise<void>
+let ddb = new DDB('ws://127.0.0.1:8848')
+
+// Encrypt with HTTPS
+let ddbsecure = new DDB('wss://dolphindb.com', {
+    // Whether to log in automatically after establishing a connection, default `true`
+    autologin: true,
+    
+    // DolphinDB username, default `'admin'`
+    username: 'admin',
+    
+    // DolphinDB password, default `'123456'`
+    password: '123456',
+    
+    // set python session flag, default `false`
+    python: false
+})
 ```
 
 
@@ -187,37 +188,41 @@ enum DdbType {
 }
 ```
 
-##### For types that are not in the utility classes, such as the datetime type in DolphinDB, we can specify form and type to create a DdbObj object
+##### If there is no shortcut class, you can also specify form and type to manually create a DdbObj object
 ```ts
+// Created by the DdbDateTime shortcut class
+new DdbDateTime(1644573600)
+
+// Equivalent to manually creating an object of form = scalar, type = datetime through DdbObj
 const obj = new DdbObj({
-    form: DdbForm.scalar,
-    type: DdbType.datetime,
-    value: 1644573600,
-    length: 0
+     form: DdbForm.scalar,
+     type: DdbType.datetime,
+     value: 1644573600,
+     length: 0
 })
-```
 
-The corresponding type and value of value property in js can refer to the result returned by `ddb.eval` (see below: `eval` Method Declaration)
 
-```ts
+// The corresponding type and value of value in js can refer to the result returned by ddb.eval (see the `eval` method declaration below)
 const obj = await ddb.eval('2022.02.11 10:00:00')
 console.log(obj.form === DdbForm.scalar)
 console.log(obj.type === DdbType.datetime)
 console.log(obj.value)
-```
 
-##### Another example is to create a set
-```ts
+// Another example is to create a set
 // refer to ddb.eval
 // const obj = await ddb.eval('set([1, 2, 3])')
 // console.log(obj.value)
-
 const obj = new DdbObj({
-    form: DdbForm.set,
-    type: DdbType.int,
-    value: Int32Array.of(1, 2, 3),
-    length: 0
+     form: DdbForm.set,
+     type: DdbType.int,
+     value: Int32Array.of(1, 2, 3),
+     length: 0
 })
+
+// It's easier to use shortcut classes
+const obj = new DdbSetInt(
+     new Set([1, 2, 3])
+)
 ```
 
 ##### NULL object in the form of scalar, the value corresponding to DdbObj is null in JavaScript

package/README.zh.md

@@ -55,23 +55,24 @@ let ddb = new DDB('ws://127.0.0.1:8848')
 await ddb.connect()
 ```
 
-#### connect 方法声明
+#### DDB 选项
 ```ts
-async connect (
-    options?: {
-        /** 默认使用实例初始化时传入的 WebSocket 链接 */
-        ws_url?: string
-        
-        /** 是否在建立连接后自动登录，默认 true */
-        login?: boolean
-        
-        /** DolphinDB 登录用户名 */
-        username?: string
-        
-        /** DolphinDB 登录密码 */
-        password?: string
-    } = { }
-): Promise<void>
+let ddb = new DDB('ws://127.0.0.1:8848')
+
+// 使用 HTTPS 加密
+let ddbsecure = new DDB('wss://dolphindb.com', {
+    // 是否在建立连接后自动登录，默认 `true`
+    autologin: true,
+    
+    // DolphinDB 登录用户名，默认 `'admin'`
+    username: 'admin',
+    
+    // DolphinDB 登录密码，默认 `'123456'`
+    password: '123456',
+    
+    // 设置 python session flag，默认 `false`
+    python: false
+})
 ```
 
 
@@ -188,37 +189,41 @@ enum DdbType {
 }
 ```
 
-##### 不在快捷类中的类型，比如 DolphinDB 中的 datetime 类型, 可以指定 form 和 type 创建 DdbObj 对象
+##### 没有快捷类的类型，也可以指定 form 和 type 手动创建 DdbObj 对象
 ```ts
+// 通过 DdbDateTime 快捷类创建
+new DdbDateTime(1644573600)
+
+// 等价于手动通过 DdbObj 创建 form = scalar, type = datetime 的对象
 const obj = new DdbObj({
     form: DdbForm.scalar,
     type: DdbType.datetime,
     value: 1644573600,
     length: 0
 })
-```
 
-value 的在 js 中对应类型及取值可以参考 ddb.eval 返回的结果 (见后文 `eval` 方法声明)
 
-```ts
+// value 在 js 中对应类型及取值可以参考 ddb.eval 返回的结果 (见后文 `eval` 方法声明)
 const obj = await ddb.eval('2022.02.11 10:00:00')
 console.log(obj.form === DdbForm.scalar)
 console.log(obj.type === DdbType.datetime)
 console.log(obj.value)
-```
 
-##### 再比如创建一个 set
-```ts
+// 再比如创建一个 set
 // 参考 ddb.eval
 // const obj = await ddb.eval('set([1, 2, 3])')
 // console.log(obj.value)
-
 const obj = new DdbObj({
     form: DdbForm.set,
     type: DdbType.int,
     value: Int32Array.of(1, 2, 3),
     length: 0
 })
+
+// 使用快捷类较为简单
+const obj = new DdbSetInt(
+    new Set([1, 2, 3])
+)
 ```
 
 ##### scalar 形式的 NULL 对象, 对应 DdbObj 的 value 为 JavaScript 中的 null

package/browser.d.ts

@@ -75,11 +75,10 @@ export interface DdbArrayVectorBlock {
     lengths: Uint8Array | Uint16Array | Uint32Array;
     data: DdbVectorValue;
 }
-export declare type DdbValue = null | boolean | number | [number, number] | bigint | string | string[] | Uint8Array | Int16Array | Int32Array | Float32Array | Float64Array | BigInt64Array | Uint8Array[] | DdbObj[] | DdbFunctionDefValue | DdbSymbolExtendedValue | DdbArrayVectorBlock[];
-export declare type DdbVectorValue = string | string[] | Uint8Array | Int16Array | Int32Array | Float32Array | Float64Array | BigInt64Array | Uint8Array[] | DdbObj[] | DdbSymbolExtendedValue | DdbArrayVectorBlock[];
+export declare type DdbValue = null | boolean | number | [number, number] | bigint | string | string[] | Uint8Array | Int8Array | Int16Array | Int32Array | Float32Array | Float64Array | BigInt64Array | Uint8Array[] | DdbObj[] | DdbFunctionDefValue | DdbSymbolExtendedValue | DdbArrayVectorBlock[];
+export declare type DdbVectorValue = string | string[] | Uint8Array | Int8Array | Int16Array | Int32Array | Float32Array | Float64Array | BigInt64Array | Uint8Array[] | DdbObj[] | DdbSymbolExtendedValue | DdbArrayVectorBlock[];
 export declare const nulls: {
-    readonly bool: 128;
-    readonly char: "€";
+    readonly int8: -128;
     readonly int16: -32768;
     readonly int32: -2147483648;
     readonly int64: -9223372036854775808n;
@@ -93,7 +92,9 @@ export declare const timezone_offset: number;
 export declare class DdbObj<T extends DdbValue = DdbValue> {
     static dec: TextDecoder;
     static enc: TextEncoder;
-    /** 维护已解析的 symbol base，比如流数据中后续的 symbol 向量可能只发送一个 base.id, base.size == 0, 依赖之前发送的 symbol base */
+    /** 维护已解析的 symbol base，比如流数据中后续的 symbol 向量可能只发送一个 base.id, base.size == 0, 依赖之前发送的 symbol base ？
+        只是暂存，如果一张表有多个 symbol 列，可能这个 symbol base 会被复用，不同的对象之间 symbol base 一般不复用
+    */
     static symbol_bases: Record<number, string[]>;
     /** little endian (client) */
     static le_client: boolean;
@@ -123,6 +124,8 @@ export declare class DdbObj<T extends DdbValue = DdbValue> {
     datatype?: DdbType;
     /** 实际数据。不同的 DdbForm, DdbType 使用 DdbValue 中不同的类型来表示实际数据 */
     value: T;
+    /** 原始二进制数据 */
+    buffer?: Uint8Array;
     constructor(data: Partial<DdbObj> & {
         form: DdbForm;
         type: DdbType;
@@ -157,7 +160,7 @@ export declare class DdbBool extends DdbObj<boolean> {
     constructor(value: boolean | null);
 }
 export declare class DdbChar extends DdbObj<string> {
-    constructor(value: string | null);
+    constructor(value: string | number | null);
 }
 export declare class DdbInt extends DdbObj<number> {
     constructor(value: number | null);
@@ -189,18 +192,27 @@ export declare class DdbFunction extends DdbObj<DdbFunctionDefValue> {
 export declare class DdbVectorInt extends DdbObj<Int32Array> {
     constructor(ints: (number | null)[] | Int32Array, name?: string);
 }
-export declare class DdbVectorString extends DdbObj<string[]> {
-    constructor(strings: string[], name?: string);
-}
 export declare class DdbVectorDouble extends DdbObj<Float64Array> {
     constructor(doubles: (number | null)[] | Float64Array, name?: string);
 }
+export declare class DdbVectorString extends DdbObj<string[]> {
+    constructor(strings: string[], name?: string);
+}
 export declare class DdbVectorAny extends DdbObj {
     constructor(objs: DdbObj<DdbValue>[], name?: string);
 }
 export declare class DdbVectorSymbol extends DdbObj<DdbSymbolExtendedValue> {
     constructor(strings: string[], name?: string);
 }
+export declare class DdbSetInt extends DdbObj<Int32Array> {
+    constructor(ints: (number | null)[] | Set<number> | Int32Array);
+}
+export declare class DdbSetDouble extends DdbObj<Float64Array> {
+    constructor(doubles: (number | null)[] | Set<number> | Float64Array);
+}
+export declare class DdbSetString extends DdbObj<string[]> {
+    constructor(strings: string[] | Set<string>);
+}
 export declare class DdbTable extends DdbObj<DdbObj[]> {
     constructor(columns: DdbObj[], name?: string);
 }
@@ -251,35 +263,62 @@ export declare class DDB {
     le: boolean;
     /** little endian (client) */
     static le_client: boolean;
+    /** Whether to automatically log in after the connection is established, the default is true */
+    autologin: boolean;
+    /** DolphinDB username */
+    username: string;
+    /** DolphinDB password */
+    password: string;
     /** python session flag (2048) */
     python: boolean;
-    message_hook: (message: Uint8Array) => any;
-    /** print message handler */
-    printer(message: string): void;
+    parse_object: boolean;
+    /** message handler */
+    on_message({ type, data }: DdbMessage, _this: DDB): void;
     /** resolver, rejector, promise of last rpc */
-    presolver(buf: Uint8Array): void;
+    presolver(message: DdbMessage): void;
     prejector(error: Error): void;
-    presult: Promise<Uint8Array>;
+    presult: Promise<DdbMessage>;
     get connected(): boolean;
     /**
         Initialize an instance of DolphinDB Client using the WebSocket URL
         (without establishing an actual network connection)
+        - url?: DolphinDB WebSocket URL. e.g.：`ws://127.0.0.1:8848`, Defaults to the current page URL
+        - options?:
+            - autologin?: Whether to log in automatically after establishing a connection, default `true`
+            - username?: DolphinDB username, default `'admin'`
+            - password?: DolphinDB password, default `'123456'`
+            - python?: set python session flag, default `false`
+        
         @example
         let ddb = new DDB('ws://127.0.0.1:8848')
-        let ddb_secure = new DDB('wss://dolphindb.com')
+        
+        // 使用 HTTPS 加密
+        let ddbsecure = new DDB('wss://dolphindb.com', {
+            autologin: true,
+            username: 'admin',
+            password: '123456',
+            python: false
+        })
     */
-    constructor(url?: string);
-    /** Establish the actual WebSocket connection to the DolphinDB corresponding to the URL */
-    connect({ url, login, username, password, python, }?: {
-        /** By default, the WebSocket URL passed in when the instance is initialized is used */
+    constructor(url?: string, options?: {
+        autologin?: boolean;
+        username?: string;
+        password?: string;
+        python?: boolean;
+    });
+    /** Establish the actual WebSocket connection to the DolphinDB corresponding to the URL
+        - options?:
+            - url?: DolphinDB WebSocket URL. By default, the WebSocket URL passed in when the instance is initialized is used
+            - autologin?: Whether to log in automatically after establishing a connection, default `true`
+            - username?: DolphinDB username, default `'admin'`
+            - password?: DolphinDB password, default `'123456'`
+            - python?: set python session flag, default `false`
+    */
+    connect(options?: {
         url?: string;
-        /** Whether to automatically log in after the connection is established, the default is true */
-        login?: boolean;
-        /** DolphinDB username */
+        autologin?: boolean;
         username?: string;
-        /** DolphinDB password */
         password?: string;
-        /** set python session flag */
         python?: boolean;
     }): Promise<void>;
     get_rpc_options({ urgent, secondary, async: _async, pickle, clear, api, compress, cancellable, priority, parallelism, root_id, limit, }?: {
@@ -311,58 +350,80 @@ export declare class DDB {
         - options:
             - urgent?: 决定 `行为标识` 那一行字符串的取值（只适用于 script 和 function）
             - vars?: type === 'variable' 时必传，variable 指令中待上传的变量名
+            - on_message?:   在该次 rpc 期间设置 message handler, 结束后恢复原有
+            - parse_object?: 在该次 rpc 期间设置 parse_object, 结束后恢复原有，为 false 时返回的 DdbObj 仅含有 buffer 和 le，
+                不做解析，以便后续转发、序列化
     */
-    rpc<T extends DdbObj = DdbObj>(type: 'script' | 'function' | 'variable' | 'connect', { script, func, args, vars, urgent, }: {
+    rpc<T extends DdbObj = DdbObj>(type: 'script' | 'function' | 'variable' | 'connect', { script, func, args, vars, urgent, on_message, parse_object, }: {
         script?: string;
         func?: string;
         args?: (DdbObj | string | boolean)[];
         vars?: string[];
         urgent?: boolean;
+        on_message?: DDB['on_message'];
+        parse_object?: boolean;
     }): Promise<T>;
-    /** eval script through websocket (script command) */
-    eval<T extends DdbObj>(
-    /** 执行的脚本 */
-    script: string, 
-    /** 执行选项 */
-    { urgent }?: {
-        /** 紧急 flag，确保提交的脚本使用 urgent worker 处理，防止被其它作业阻塞 */
+    /** eval script through websocket (script command)
+        - script?: Script to execute
+        - options?: execution options
+            - urgent?: Urgent flag to ensure that submitted scripts are processed by urgent workers to prevent being blocked by other jobs
+            - on_message?: Set the message handler during this rpc, and restore the original after the end
+            - parse_object?: 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, on_message, parse_object, }?: {
         urgent?: boolean;
+        on_message?: DDB['on_message'];
+        parse_object?: boolean;
     }): Promise<T>;
     /** call function through websocket (function command)
-        - func: 函数名
-        - args?: `[ ]` 调用参数 (传入的原生 string 和 boolean 会被自动转换为 DdbObj<string> 和 DdbObj<boolean>)
-        - options?: 调用选项
-            - urgent?: 紧急 flag。使用 urgent worker 执行，防止被其它作业阻塞
-            - node?: 设置结点 alias 时发送到集群中对应的结点执行 (使用 DolphinDB 中的 rpc 方法)
-            - nodes?: 设置多个结点 alias 时发送到集群中对应的多个结点执行 (使用 DolphinDB 中的 pnodeRun 方法)
-            - func_type?: 设置 node 参数时必传，需指定函数类型，其它情况下不传
-            - add_node_alias?: 设置 nodes 参数时选传，其它情况不传
+        - func: function name
+        - args?: `[ ]` Call parameters (the incoming native string and boolean will be automatically converted to DdbObj<string> and DdbObj<boolean>)
+        - options?: call options
+            - urgent?: Emergency flag. Use urgent worker execution to prevent being blocked by other jobs
+            - node?: When the node alias is set, it is sent to the corresponding node in the cluster for execution (using the rpc method in DolphinDB)
+            - nodes?: When setting multiple node aliases, send them to the corresponding multiple nodes in the cluster for execution (using the pnodeRun method in DolphinDB)
+            - func_type?: It must be passed when setting the node parameter, the function type needs to be specified, and it is not passed in other cases
+            - add_node_alias?: Select to pass when setting the nodes parameter, otherwise not pass
+            - on_message?: Set the message handler during this rpc, and restore the original after the end
+            - parse_object?: 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
     */
-    call<T extends DdbObj>(func: string, args?: (DdbObj | string | boolean)[], { urgent, node, nodes, func_type, add_node_alias }?: {
+    call<T extends DdbObj>(func: string, args?: (DdbObj | string | boolean)[], { urgent, node, nodes, func_type, add_node_alias, on_message, parse_object, }?: {
         urgent?: boolean;
         node?: string;
         nodes?: string[];
         func_type?: DdbFunctionType;
         add_node_alias?: boolean;
+        on_message?: DDB['on_message'];
+        parse_object?: boolean;
     }): Promise<T>;
     /** upload variable through websocket (variable command) */
     upload(
     /** Uploaded variables' name */
     vars: string[], 
     /** Uploaded variables' value */
-    args: (DdbObj | string | boolean)[]): Promise<DdbObj<DdbValue>>;
+    args: (DdbObj | string | boolean)[], { on_message, parse_object, }?: {
+        on_message?: DDB['on_message'];
+        parse_object?: boolean;
+    }): Promise<DdbObj<DdbValue>>;
     /** 解析服务端响应报文，返回去掉 header 的 data buf */
-    parse_message(buf: Uint8Array): {
-        type: "message";
-        data: string;
-    } | {
-        type: "object";
-        data: Uint8Array;
-    };
+    parse_message(buf: Uint8Array, parse_object?: boolean): DdbMessage;
     /** 自动转换 js string, boolean 为 DdbObj */
     to_ddbobj(value: DdbObj | string | boolean): DdbObj;
     /** 转换 js 数组为 DdbObj[] */
     to_ddbobjs(values: any[]): DdbObj<DdbValue>[];
 }
+export interface DdbPrintMessage {
+    type: 'print';
+    data: string;
+}
+export interface DdbObjectMessage {
+    type: 'object';
+    data: DdbObj;
+}
+export declare type DdbMessage = DdbPrintMessage | DdbObjectMessage;
 export declare let ddb: DDB;
 export default ddb;