dolphindb 0.0.4 → 0.0.7

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
 ```
 
@@ -275,3 +320,19 @@ async upload (
 ): Promise<void>
 ```
 
+
+### Notes
+```ts
+import { nulls, DdbInt, timestamp2str } from 'dolphindb'
+
+// create DolphinDB null integer value (the smallest 32-bit integer)
+new DdbInt(nulls.int32)
+
+// convert DolphinDB timestamp value to string
+timestamp2str(
+    (
+        await ddb.call<DdbObj<bigint>>('now', [false])
+    ).value
+) === '2022.02.23 17:23:13.494'
+```
+

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
 ```
 
@@ -275,3 +320,18 @@ async upload (
 ): Promise<void>
 ```
 
+
+### Notes
+```ts
+import { nulls, DdbInt, timestamp2str } from 'dolphindb'
+
+// 创建 DolphinDB 空值 (最小的 32-bit 整数)
+new DdbInt(nulls.int32)
+
+// 将 DolphinDB 中的 timestamp 格式化为 string
+timestamp2str(
+    (
+        await ddb.call<DdbObj<bigint>>('now', [false])
+    ).value
+) === '2022.02.23 17:23:13.494'
+```

package/browser.d.ts

@@ -66,16 +66,24 @@ export interface DdbFunctionDefValue {
 export interface DdbSymbolExtendedValue {
     base_id: number;
     base: string[];
-    value: Uint32Array;
+    data: Uint32Array;
 }
-export declare type DdbValue = null | boolean | number | [number, number] | bigint | string | string[] | Uint8Array | Int16Array | Int32Array | Float32Array | Float64Array | BigInt64Array | Uint8Array[] | DdbObj[] | DdbFunctionDefValue | DdbSymbolExtendedValue;
-export declare type DdbVectorValue = string | string[] | Uint8Array | Int16Array | Int32Array | Float32Array | Float64Array | BigInt64Array | Uint8Array[] | DdbObj[] | DdbSymbolExtendedValue;
+export interface DdbArrayVectorBlock {
+    unit: 1 | 2 | 4;
+    rows: number;
+    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 const nulls: {
     readonly char: "€";
     readonly int16: -32768;
     readonly int32: -2147483648;
     readonly int64: -9223372036854775808n;
 };
+export declare const timezone_offset: number;
+/** 可以表示所有 DolphinDB 数据库中的数据类型 */
 export declare class DdbObj<T extends DdbValue = DdbValue> {
     static dec: TextDecoder;
     static enc: TextEncoder;
@@ -128,8 +136,16 @@ 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;
+}
+export declare class DdbVoid extends DdbObj<undefined> {
+    constructor();
 }
 export declare class DdbBool extends DdbObj<boolean> {
     constructor(value: boolean);
@@ -164,42 +180,84 @@ export declare class DdbPair extends DdbObj<Int32Array> {
 export declare class DdbFunction extends DdbObj<DdbFunctionDefValue> {
     constructor(name: string, type: DdbFunctionType);
 }
+export declare function date2str(date: number): string;
+export declare function timestamp2str(timestamp: bigint): string;
 export declare class DDB {
     /** 当前的 session id (http 或 tcp) */
     sid: string;
     /** utf-8 text decoder */
     dec: TextDecoder;
     enc: TextEncoder;
-    ws_url: string;
-    ws: WebSocket;
+    /** DolphinDB WebSocket URL
+        e.g. `ws://127.0.0.1:8848/`, `wss://dolphindb.com`
+    */
+    url: string;
+    websocket: WebSocket;
     /** little endian (server) */
     le: boolean;
     /** little endian (client) */
     static le_client: boolean;
+    /** python session flag (2048) */
+    python: boolean;
+    message_hook: (message: Uint8Array) => any;
+    /** print message handler */
+    printer(message: string): void;
     /** resolver, rejector, promise of last rpc */
     presolver(buf: Uint8Array): void;
     prejector(error: Error): void;
     presult: Promise<Uint8Array>;
-    constructor(ws_url?: string);
-    /** 连接到 DolphinDB Server */
-    connect({ ws_url, login, username, password, }?: {
-        /** 默认使用实例初始化时传入的 WebSocket 链接地址 */
-        ws_url?: string;
-        /** 是否在建立连接后自动登录，默认 true */
+    /**
+        Initialize an instance of DolphinDB Client using the WebSocket URL
+        (without establishing an actual network connection)
+        @example
+        let ddb = new DDB('ws://127.0.0.1:8848')
+        let ddb_secure = new DDB('wss://dolphindb.com')
+    */
+    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 */
+        url?: string;
+        /** Whether to automatically log in after the connection is established, the default is true */
         login?: boolean;
-        /** DolphinDB 登录用户名 */
+        /** DolphinDB username */
         username?: string;
-        /** DolphinDB 登录密码 */
+        /** 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, }?: {
+        urgent?: boolean;
+        /** API 提交的任务, secondary 必须为 false */
+        secondary?: boolean;
+        /** 是否异步任务（不返回结果） */
+        async?: boolean;
+        /** 让服务端以 pickle 协议返回数据 */
+        pickle?: boolean;
+        /** 本次任务完成后 clear session memory */
+        clear?: boolean;
+        /** 是否为 api client */
+        api?: boolean;
+        compress?: boolean;
+        /** 任务是否可以取消 */
+        cancellable?: boolean;
+        priority?: number;
+        /** `8` 0 ~ 64, 指定本任务并行度 */
+        parallelism?: number;
+        /** 根任务编号，内部使用，API中固定为空 */
+        root_id?: string;
+        /** 指定分块返回的块大小 */
+        limit?: boolean;
+    }): string;
     disconnect(): void;
-    /** rpc through websocket (function command)
+    /** rpc through websocket (function/script/variable command)
         - type: API 类型: 'script' | 'function' | 'variable'
         - options:
             - urgent?: 决定 `行为标识` 那一行字符串的取值（只适用于 script 和 function）
             - vars?: type === 'variable' 时必传，variable 指令中待上传的变量名
     */
-    rpc<T extends DdbObj = DdbObj>(type: 'script' | 'function' | 'variable', { script, func, args, vars, urgent, }: {
+    rpc<T extends DdbObj = DdbObj>(type: 'script' | 'function' | 'variable' | 'connect', { script, func, args, vars, urgent, }: {
         script?: string;
         func?: string;
         args?: (DdbObj | string | boolean)[];
@@ -212,14 +270,14 @@ export declare class DDB {
     script: string, 
     /** 执行选项 */
     { urgent }?: {
-        /** 紧急 flag，使用 urgent worker 处理，防止被其它作业阻塞 */
+        /** 紧急 flag，确保提交的脚本使用 urgent worker 处理，防止被其它作业阻塞 */
         urgent?: boolean;
     }): Promise<T>;
     /** call function through websocket (function command)
         - func: 函数名
         - args?: `[ ]` 调用参数 (传入的原生 string 和 boolean 会被自动转换为 DdbObj<string> 和 DdbObj<boolean>)
         - options?: 调用选项
-            - urgent?: 紧急 flag，使用 urgent worker 处理，防止被其它作业阻塞
+            - urgent?: 紧急 flag。使用 urgent worker 执行，防止被其它作业阻塞
             - node?: 设置结点 alias 时发送到集群中对应的结点执行 (使用 DolphinDB 中的 rpc 方法)
             - nodes?: 设置多个结点 alias 时发送到集群中对应的多个结点执行 (使用 DolphinDB 中的 pnodeRun 方法)
             - func_type?: 设置 node 参数时必传，需指定函数类型，其它情况下不传
@@ -234,12 +292,18 @@ export declare class DDB {
     }): Promise<T>;
     /** upload variable through websocket (variable command) */
     upload(
-    /** 上传的变量名 */
+    /** Uploaded variables' name */
     vars: string[], 
-    /** 上传的变量值 */
+    /** Uploaded variables' value */
     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, 会修改原数组) */