dolphindb 0.0.1 → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 DolphinDB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,277 @@
+# DolphinDB JavaScript API
+
+<p align='center'>
+    <img src='./ddb.svg' alt='DolphinDB' width='256'>
+</p>
+
+<p align='center'>
+    <a href='https://www.npmjs.com/package/dolphindb' target='_blank'>
+        <img alt='npm version' src='https://img.shields.io/npm/v/dolphindb.svg?style=flat-square&color=brightgreen' />
+    </a>
+    <a href='https://www.npmjs.com/package/dolphindb' target='_blank'>
+        <img alt='npm downloads' src='https://img.shields.io/npm/dt/dolphindb?style=flat-square&color=brightgreen' />
+    </a>
+</p>
+
+## [中文](./README.md) | English
+
+## Overview
+DolphinDB JavaScript API is a JavaScript library that encapsulates the ability to operate the DolphinDB database, such as: connecting to the database, executing scripts, calling functions, uploading variables, etc.
+
+https://www.npmjs.com/package/dolphindb
+
+## Features
+- Communicate with DolphinDB database using WebSocket, exchange data in binary format
+- Support running in browser environment and Node.js environment
+- Use TypedArray such as Int32Array in JavaScript to process binary data, with high performance
+- A single call supports serialized upload of up to 2GB of data, and the amount of downloaded data is not limited
+
+## Installation
+```bash
+# Install the latest version of Node.js and browser on the machine
+
+# Install npm packages in your project
+npm install dolphindb
+```
+
+## Usage
+### 0. Initialize and connect to DolphinDB
+```ts
+import DDB from 'dolphindb'
+
+// Create a database object and initialize the WebSocket URL
+let ddb = new DDB('ws://127.0.0.1:8848')
+
+// Establish a WebSocket connection to DolphinDB (requires DolphinDB database version at least 1.30.16 or 2.00.4)
+await ddb.connect()
+```
+
+#### Connect Method Declaration
+```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>
+```
+
+
+### 1. Call Functions
+#### Example
+```ts
+import { DdbInt } from 'dolphindb'
+
+const result = await ddb.call<DdbInt>('add', [new DdbInt(1), new DdbInt(1)])
+
+console.log(result.value === 2)  // true
+```
+
+#### The DolphinDB JavaScript API uses DdbObj objects to represent data types in DolphinDB
+In the above example, two parameters 1 (corresponding to the int type in DolphinDB) are uploaded to the DolphinDB database as parameters of the add function, then the result of the function call is received.
+
+`<DdbInt>` is used by TypeScript to infer the type of the return value
+
+- result is a `DdbInt`, which is also a `DdbObj<number>`
+- result.form is a `DdbForm.scalar`
+- result.type is a `DdbType.int`
+- result.value is native `number` in JavaScript (the value range and precision of int can be accurately represented by JavaScript number)
+
+```ts
+/** Can represent all data types in DolphinDB databases */
+class DdbObj <T extends DdbValue = DdbValue> {
+    /** is it little endian */
+    le: boolean
+    
+    /** data form https://www.dolphindb.cn/cn/help/DataTypesandStructures/DataForms/index.html */
+    form: DdbForm
+    
+    /** data type  https://www.dolphindb.cn/cn/help/DataTypesandStructures/DataTypes/index.html */
+    type: DdbType
+    
+    /** consumed length in buf parsed */
+    length: number
+    
+    /** table name / column name */
+    name?: string
+    
+    /**
+        Lowest dimension
+        - vector: rows = n, cols = 1
+        - pair:   rows = 2, cols = 1
+        - matrix: rows = n, cols = m
+        - set:    the same as vector
+        - dict:   include keys, values vector
+        - table:  the same as matrix
+    */
+    rows?: number
+    
+    /** 2nd dimension */
+    cols?: number
+    
+    /** the type of the value in matrix (only matrix has this field) */
+    datatype?: DdbType
+    
+    /** the actual data. Different DdbForm, DdbType use different types in DdbValue to represent actual data */
+    value: T
+    
+    constructor (data: Partial<DdbObj> & { form: DdbForm, type: DdbType, length: number }) {
+        Object.assign(this, data)
+    }
+}
+
+class DdbInt extends DdbObj<number> {
+    constructor (value: number) {
+        super({
+            form: DdbForm.scalar,
+            type: DdbType.int,
+            length: 4,
+            value
+        })
+    }
+}
+
+// ... There are also many utility classes, such as DdbString, DdbLong, DdbDouble, DdbVectorDouble, DdbVectorAny, etc.
+
+type DdbValue = 
+    null | boolean | number | [number, number] | bigint | string | string[] | 
+    Uint8Array | Int16Array | Int32Array | Float32Array | Float64Array | BigInt64Array | Uint8Array[] | 
+    DdbObj[] | DdbFunctionDefValue | DdbSymbolExtendedValue
+    
+
+enum DdbForm {
+    scalar = 0,
+    vector = 1,
+    pair = 2,
+    matrix = 3,
+    set = 4,
+    dict = 5,
+    table = 6,
+    chart = 7,
+    chunk = 8,
+}
+
+
+enum DdbType {
+    void = 0,
+    bool = 1,
+    char = 2,
+    short = 3,
+    int = 4,
+    long = 5,
+    // ...
+    timestamp = 12,
+    // ...
+    double = 16,
+    symbol = 17,
+    string = 18,
+    // ...
+}
+```
+
+#### `call` Method Declaration
+```ts
+async call <T extends DdbObj> (
+    /** function name */
+    func: string,
+    
+    /** function arguments (The incoming native string and boolean will be automatically converted to DdbObj<string> and DdbObj<boolean>) */
+    args?: (DdbObj | string | boolean)[] = [ ],
+    
+    /** calling options */
+    options?: {
+        /** Urgent flag. Use urgent worker to execute to prevent being blocked by other jobs */
+        urgent?: boolean
+        
+        /** When the node alias is set, the function is sent to the corresponding node in the cluster for execution (using the rpc method in DolphinDB) */
+        node?: string
+        
+        /** When setting multiple node aliases, send them to the corresponding multiple nodes in the cluster for execution (using the pnodeRun method in DolphinDB) */
+        nodes?: string[]
+        
+        /** It must be passed when setting the node parameter, the function type needs to be specified, and it is not passed in other cases */
+        func_type?: DdbFunctionType
+        
+        /** It may be  passed when setting the nodes parameter, otherwise may not be passed */
+        add_node_alias?: boolean
+    } = { }
+): Promise<T>
+```
+
+
+### 2. Execute Script
+#### Example
+```ts
+import type { DdbLong } from 'dolphindb'
+
+const result = await ddb.eval<DdbLong>(
+    'def foo (a, b) {\n' +
+    '    return a + b\n' +
+    '}\n' +
+    'foo(1l, 1l)\n'
+)
+
+console.log(result.value === 2n)  // true
+```
+
+In the above example, a script is uploaded through a string to the DolphinDB database for execution, and the execution result of the last statement `foo(1l, 1l)` is received.
+
+`<DdbLong>` is used by TypeScript to infer the type of the return value
+
+- result is a `DdbLong`, which is also a `DdbObj<bigint>`
+- result.form is `DdbForm.scalar`
+- result.type is `DdbType.long`
+- result.value is the native `bigint` in JavaScript (the precision of long cannot be accurately represented by JavaScript number, but it can be represented by bigint)
+
+As long as the WebSocket connection is not disconnected, the custom function `foo` will always exist in the subsequent session and can be reused, for example, you can use `await ddb.call<DdbInt>('foo', [new DdbInt(1), new DdbInt(1)])` to call this custom function
+
+#### `eval` Method Declaration
+```ts
+async eval <T extends DdbObj> (
+    /** the script to execute */
+    script: string,
+    
+    /** calling options */
+    options: {
+        /** Urgent flag. Use urgent worker to execute to prevent being blocked by other jobs */
+        urgent?: boolean
+    } = { }
+): Promise<T>
+```
+
+
+### 3. Upload Variables
+#### Example
+```ts
+import { DdbVectorDouble } from 'dolphindb'
+
+let a = new Array(10000)
+a.fill(1.0)
+
+ddb.upload(['bar1', 'bar2'], [new DdbVectorDouble(a), new DdbVectorDouble(a)])
+```
+
+In the above example, two variables `bar1`, `bar2` are uploaded, and the variable value is a double vector of length 10000
+
+As long as the WebSocket connection is not disconnected, the variables `bar1`, `bar2` will always exist in the subsequent session and can be reused
+
+#### `upload` Method Declaration
+```ts
+async upload (
+    /** variable names */
+    vars: string[],
+    
+    /** variable values */
+    args: (DdbObj | string | boolean)[]
+): Promise<void>
+```
+

package/README.md

@@ -13,8 +13,12 @@
     </a>
 </p>
 
+## 中文 | [English](./README.en.md)
+
 ## 简介
-DolphinDB JavaScript API 封装了操作 DolphinDB 数据库的能力，如：连接数据库、执行脚本、调用函数、上传变量等
+DolphinDB JavaScript API 是一个 JavaScript 库，封装了操作 DolphinDB 数据库的能力，如：连接数据库、执行脚本、调用函数、上传变量等
+
+https://www.npmjs.com/package/dolphindb
 
 ## 特性
 - 使用 WebSocket 与 DolphinDB 数据库通信，用二进制格式进行数据交换
@@ -35,10 +39,10 @@ npm install dolphindb
 ```ts
 import DDB from 'dolphindb'
 
-// 初始化 WebSocket 连接地址
+// 创建数据库对象，初始化 WebSocket 连接地址
 let ddb = new DDB('ws://127.0.0.1:8848')
 
-// 建立到 DolphinDB 的 WebSocket 连接
+// 建立到 DolphinDB 的 WebSocket 连接（要求 DolphinDB 数据库版本不低于 1.30.16 或 2.00.4）
 await ddb.connect()
 ```
 
@@ -46,7 +50,7 @@ await ddb.connect()
 ```ts
 async connect (
     options?: {
-        /** 默认使用实例初始化时传入的 WebSocket 链接地址 */
+        /** 默认使用实例初始化时传入的 WebSocket 链接 */
         ws_url?: string
         
         /** 是否在建立连接后自动登录，默认 true */
@@ -83,7 +87,7 @@ console.log(result.value === 2)  // true
 - result.value 是 JavaScript 中原生的 `number` (int 的取值范围及精度可以用 JavaScript 的 number 准确表示)
 
 ```ts
-/** 可以表示所有 DolphinDB 数据库中的数据 */
+/** 可以表示所有 DolphinDB 数据库中的数据类型 */
 class DdbObj <T extends DdbValue = DdbValue> {
     /** 是否为小端 (little endian) */
     le: boolean
@@ -174,7 +178,7 @@ enum DdbType {
 }
 ```
 
-#### call 方法声明
+#### `call` 方法声明
 ```ts
 async call <T extends DdbObj> (
     /** 函数名 */
@@ -185,7 +189,7 @@ async call <T extends DdbObj> (
     
     /** 调用选项 */
     options?: {
-        /** 紧急 flag，使用 urgent worker 处理，防止被其它作业阻塞 */
+        /** 紧急 flag。使用 urgent worker 执行，防止被其它作业阻塞 */
         urgent?: boolean
         
         /** 设置结点 alias 时发送到集群中对应的结点执行 (使用 DolphinDB 中的 rpc 方法) */
@@ -221,7 +225,7 @@ console.log(result.value === 2n)  // true
 
 上面例子中，通过字符串上传了一段脚本到 DolphinDB 数据库执行，并接收最后一条语句 `foo(1l, 1l)` 执行结果 result
 
-`<DdbInt>` 用于 TypeScript 推断返回值的类型
+`<DdbLong>` 用于 TypeScript 推断返回值的类型
 
 - result 是一个 `DdbLong`，也是 `DdbObj<bigint>`
 - result.form 是 `DdbForm.scalar`
@@ -230,7 +234,7 @@ console.log(result.value === 2n)  // true
 
 只要 WebSocket 连接不断开，在后续的会话中 `foo` 这个自定义函数会一直存在，可复用，比如后续通过 `await ddb.call<DdbInt>('foo', [new DdbInt(1), new DdbInt(1)])` 调用这个自定义函数
 
-#### eval 方法声明
+#### `eval` 方法声明
 ```ts
 async eval <T extends DdbObj> (
     /** 执行的脚本 */
@@ -238,7 +242,7 @@ async eval <T extends DdbObj> (
     
     /** 执行选项 */
     options: {
-        /** 紧急 flag，使用 urgent worker 处理，防止被其它作业阻塞 */
+        /** 紧急 flag，确保提交的脚本使用 urgent worker 处理，防止被其它作业阻塞 */
         urgent?: boolean
     } = { }
 ): Promise<T>
@@ -260,7 +264,7 @@ ddb.upload(['bar1', 'bar2'], [new DdbVectorDouble(a), new DdbVectorDouble(a)])
 
 只要 WebSocket 连接不断开，在后续的会话中 `bar1`, `bar2` 这些变量会一直存在，可复用
 
-#### upload 方法声明
+#### `upload` 方法声明
 ```ts
 async upload (
     /** 上传的变量名 */

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "dolphindb",
     "description": "DolphinDB JavaScript API",
-    "version": "0.0.1",
+    "version": "0.0.2",
     "type": "commonjs",
     "main": "./index.js",
     "browser": "./browser.js",