dolphindb 0.0.5 → 0.0.6

package/README.md

@@ -28,16 +28,24 @@ https://www.npmjs.com/package/dolphindb
 
 ## Installation
 ```bash
-# Install the latest version of Node.js and browser on the machine
+# 1. Install the latest version of Node.js and browser on the machine
 
-# Install npm packages in your project
+# 2. Create a new project (skip this step if you already have a project)
+mkdir dolphindb-example
+cd dolphindb-example
+npm init --yes
+# Open the package.json file with an editor, add the line "type": "module", below "main": "./index.js",
+# This enables the use of ECMAScript modules, and in the code behind you can use import { DDB } from 'dolphindb' to import npm packages
+
+# 3. Install npm packages in your project
 npm install dolphindb
 ```
 
 ## Usage
 ### 0. Initialize and connect to DolphinDB
 ```ts
-import DDB from 'dolphindb'
+import { DDB } from 'dolphindb'
+// The import method for existing projects using CommonJS modules is const { DDB } = require('dolphindb')
 
 // Create a database object and initialize the WebSocket URL
 let ddb = new DDB('ws://127.0.0.1:8848')
@@ -71,7 +79,8 @@ async connect (
 ```ts
 import { DdbInt } from 'dolphindb'
 
-const result = await ddb.call<DdbInt>('add', [new DdbInt(1), new DdbInt(1)])
+const result = await ddb.call('add', [new DdbInt(1), new DdbInt(1)])
+// TypeScript: const result = await ddb.call<DdbInt>('add', [new DdbInt(1), new DdbInt(1)])
 
 console.log(result.value === 2)  // true
 ```
@@ -178,6 +187,40 @@ 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
+```ts
+const obj = new DdbObj({
+    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
+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
+// 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
+})
+```
+
+
 #### `call` Method Declaration
 ```ts
 async call <T extends DdbObj> (
@@ -211,15 +254,17 @@ async call <T extends DdbObj> (
 ### 2. Execute Script
 #### Example
 ```ts
-import type { DdbLong } from 'dolphindb'
-
-const result = await ddb.eval<DdbLong>(
+const result = await ddb.eval(
     'def foo (a, b) {\n' +
     '    return a + b\n' +
     '}\n' +
     'foo(1l, 1l)\n'
 )
 
+// TypeScript:
+// import type { DdbLong } from 'dolphindb'
+// const result = await ddb.eval<DdbLong>(...)
+
 console.log(result.value === 2n)  // true
 ```
 

package/README.zh.md

@@ -28,16 +28,24 @@ https://www.npmjs.com/package/dolphindb
 
 ## 安装
 ```bash
-# 在机器上安装最新版的 Node.js 及浏览器
+# 1. 在机器上安装最新版的 Node.js 及浏览器
 
-# 在项目中安装 npm 包
+# 2. 创建新项目
+mkdir dolphindb-example
+cd dolphindb-example
+npm init --yes
+# 用编辑器打开 package.json 文件，在 "main": "./index.js", 下面加入一行 "type": "module",
+# 这样能够启用 ECMAScript modules，在后面代码中可以使用 import { DDB } from 'dolphindb' 导入 npm 包
+
+# 3. 在项目中安装 npm 包
 npm install dolphindb
 ```
 
 ## 用法
 ### 0. 初始化并连接到 DolphinDB
 ```ts
-import DDB from 'dolphindb'
+import { DDB } from 'dolphindb'
+// 已有的使用 CommonJS 模块的项目的导入方法为 const { DDB } = require('dolphindb')
 
 // 创建数据库对象，初始化 WebSocket 连接地址
 let ddb = new DDB('ws://127.0.0.1:8848')
@@ -71,7 +79,8 @@ async connect (
 ```ts
 import { DdbInt } from 'dolphindb'
 
-const result = await ddb.call<DdbInt>('add', [new DdbInt(1), new DdbInt(1)])
+const result = await ddb.call('add', [new DdbInt(1), new DdbInt(1)])
+// TypeScript: const result = await ddb.call<DdbInt>('add', [new DdbInt(1), new DdbInt(1)])
 
 console.log(result.value === 2)  // true
 ```
@@ -178,6 +187,40 @@ enum DdbType {
 }
 ```
 
+##### 不在快捷类中的类型，比如 DolphinDB 中的 datetime 类型, 可以指定 form 和 type 创建 DdbObj 对象
+```ts
+const obj = new DdbObj({
+    form: DdbForm.scalar,
+    type: DdbType.datetime,
+    value: 1644573600,
+    length: 0
+})
+```
+
+value 的在 js 中对应类型及取值可以参考 ddb.eval 返回的结果 (见后文 `eval` 方法声明)
+
+```ts
+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
+// 参考 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
+})
+```
+
+
 #### `call` 方法声明
 ```ts
 async call <T extends DdbObj> (
@@ -211,15 +254,17 @@ async call <T extends DdbObj> (
 ### 2. 执行脚本
 #### 例子
 ```ts
-import type { DdbLong } from 'dolphindb'
-
-const result = await ddb.eval<DdbLong>(
+const result = await ddb.eval(
     'def foo (a, b) {\n' +
     '    return a + b\n' +
     '}\n' +
     'foo(1l, 1l)\n'
 )
 
+// TypeScript:
+// import type { DdbLong } from 'dolphindb'
+// const result = await ddb.eval<DdbLong>(...)
+
 console.log(result.value === 2n)  // true
 ```
 

package/browser.d.ts

@@ -136,7 +136,11 @@ export declare class DdbObj<T extends DdbValue = DdbValue> {
     pack(): Uint8Array;
     static pack_vector_body(value: DdbVectorValue, type: DdbType, length: number): ArrayBufferView[];
     toString(): string;
-    to_cols(): any[];
+    to_cols(): {
+        title: string;
+        dataIndex: string;
+        render?: any;
+    }[];
     to_rows<T extends Record<string, any> = Record<string, any>>(): T[];
     to_dict<T = Record<string, any>>(): T;
 }
@@ -190,6 +194,8 @@ export declare class DDB {
     le: boolean;
     /** little endian (client) */
     static le_client: boolean;
+    /** print message handler */
+    printer(message: string): void;
     /** resolver, rejector, promise of last rpc */
     presolver(buf: Uint8Array): void;
     prejector(error: Error): void;
@@ -197,7 +203,7 @@ export declare class DDB {
     constructor(ws_url?: string);
     /** 连接到 DolphinDB Server */
     connect({ ws_url, login, username, password, }?: {
-        /** 默认使用实例初始化时传入的 WebSocket 链接 */
+        /** 默认使用实例初始化时传入的 WebSocket URL */
         ws_url?: string;
         /** 是否在建立连接后自动登录，默认 true */
         login?: boolean;
@@ -253,7 +259,13 @@ export declare class DDB {
     /** 上传的变量值 */
     args: (DdbObj | string | boolean)[]): Promise<DdbObj<DdbValue>>;
     /** 解析服务端响应报文，返回去掉 header 的 data buf */
-    parse_message(buf: Uint8Array): Uint8Array;
+    parse_message(buf: Uint8Array): {
+        type: "message";
+        data: string;
+    } | {
+        type: "object";
+        data: Uint8Array;
+    };
     /** 自动转换 js string, boolean 为 DdbObj */
     to_ddbobj(value: DdbObj | string | boolean): DdbObj;
     /** 转换 js 数组为 DdbObj[] (in place, 会修改原数组) */

package/browser.js

@@ -1032,6 +1032,10 @@ class DDB {
         }
         this.ws_url = ws_url;
     }
+    /** print message handler */
+    printer(message) {
+        console.log(message);
+    }
     /** resolver, rejector, promise of last rpc */
     presolver(buf) { }
     prejector(error) { }
@@ -1062,7 +1066,12 @@ class DDB {
         });
         ws.addEventListener('message', ({ data: buf }) => {
             try {
-                this.presolver(this.parse_message(new Uint8Array(buf)));
+                const { type, data } = this.parse_message(new Uint8Array(buf));
+                if (type === 'message') {
+                    this.printer(data);
+                    return;
+                }
+                this.presolver(data);
             }
             catch (error) {
                 this.prejector(error);
@@ -1142,7 +1151,7 @@ class DDB {
             }
         })());
         const message = (0, utils_browser_1.concat)([
-            this.enc.encode(`API ${this.sid} ${command.length}${urgent ? ` / 1_1_8_8` : ''}\n`),
+            this.enc.encode(`API2 ${this.sid} ${command.length}${urgent ? ` / 1_1_8_8` : ''}\n`),
             command,
             ...args.map((arg) => arg.pack())
         ]);
@@ -1206,6 +1215,14 @@ class DDB {
     }
     /** 解析服务端响应报文，返回去掉 header 的 data buf */
     parse_message(buf) {
+        // MSG\n
+        // <message>\0
+        // 'M'.codePointAt(0).to_hex_str()
+        if (buf[0] === 0x4d && buf[1] === 0x53 && buf[2] === 0x47 && buf[3] === 0x0a)
+            return {
+                type: 'message',
+                data: this.dec.decode(buf.subarray(4))
+            };
         // '1166953221 1 1\n'
         // 'OK\n'
         // '\x04\x00\x02\x00\x00\x00'
@@ -1228,7 +1245,10 @@ class DDB {
         const message = this.dec.decode(buf.subarray(i_ls_1, i_lf_1));
         if (message !== 'OK')
             throw new Error(message);
-        return buf.subarray(i_lf_1 + 1);
+        return {
+            type: 'object',
+            data: buf.subarray(i_lf_1 + 1)
+        };
     }
     /** 自动转换 js string, boolean 为 DdbObj */
     to_ddbobj(value) {