dolphindb 0.0.1

package/README.md

@@ -0,0 +1,273 @@
+# 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>
+
+## 简介
+DolphinDB JavaScript API 封装了操作 DolphinDB 数据库的能力，如：连接数据库、执行脚本、调用函数、上传变量等
+
+## 特性
+- 使用 WebSocket 与 DolphinDB 数据库通信，用二进制格式进行数据交换
+- 支持在浏览器环境和 Node.js 环境中运行
+- 使用了 JavaScript 中的 Int32Array 等 TypedArray 处理二进制数据，性能较高
+- 单次调用支持最大 2 GB 数据的序列化上传，下载数据量不受限制
+
+## 安装
+```bash
+# 在机器上安装最新版的 Node.js 及浏览器
+
+# 在项目中安装 npm 包
+npm install dolphindb
+```
+
+## 用法
+### 0. 初始化并连接到 DolphinDB
+```ts
+import DDB from 'dolphindb'
+
+// 初始化 WebSocket 连接地址
+let ddb = new DDB('ws://127.0.0.1:8848')
+
+// 建立到 DolphinDB 的 WebSocket 连接
+await ddb.connect()
+```
+
+#### connect 方法声明
+```ts
+async connect (
+    options?: {
+        /** 默认使用实例初始化时传入的 WebSocket 链接地址 */
+        ws_url?: string
+        
+        /** 是否在建立连接后自动登录，默认 true */
+        login?: boolean
+        
+        /** DolphinDB 登录用户名 */
+        username?: string
+        
+        /** DolphinDB 登录密码 */
+        password?: string
+    } = { }
+): Promise<void>
+```
+
+
+### 1. 调用函数
+#### 例子
+```ts
+import { DdbInt } from 'dolphindb'
+
+const result = await ddb.call<DdbInt>('add', [new DdbInt(1), new DdbInt(1)])
+
+console.log(result.value === 2)  // true
+```
+
+#### DolphinDB JavaScript API 用 DdbObj 对象来表示 DolphinDB 中的数据类型
+上面例子中，上传了两个参数 1 (对应 DolphinDB 中的 int 类型) 到 DolphinDB 数据库，作为 add 函数的参数，并接收函数调用的结果 result
+
+`<DdbInt>` 用于 TypeScript 推断返回值的类型
+
+- result 是一个 `DdbInt`，也是 `DdbObj<number>`
+- result.form 是 `DdbForm.scalar`
+- result.type 是 `DdbType.int`
+- result.value 是 JavaScript 中原生的 `number` (int 的取值范围及精度可以用 JavaScript 的 number 准确表示)
+
+```ts
+/** 可以表示所有 DolphinDB 数据库中的数据 */
+class DdbObj <T extends DdbValue = DdbValue> {
+    /** 是否为小端 (little endian) */
+    le: boolean
+    
+    /** 数据形式 https://www.dolphindb.cn/cn/help/DataTypesandStructures/DataForms/index.html */
+    form: DdbForm
+    
+    /** 数据类型 https://www.dolphindb.cn/cn/help/DataTypesandStructures/DataTypes/index.html */
+    type: DdbType
+    
+    /** 占用 parse 时传入的 buf 的长度 */
+    length: number
+    
+    /** table name / column name */
+    name?: string
+    
+    /**
+        最低维、第 1 维
+        - vector: rows = n, cols = 1
+        - pair:   rows = 2, cols = 1
+        - matrix: rows = n, cols = m
+        - set:    同 vector
+        - dict:   包含 keys, values 向量
+        - table:  同 matrix
+    */
+    rows?: number
+    
+    /** 第 2 维 */
+    cols?: number
+    
+    /** matrix 中值的类型，仅 matrix 才有 */
+    datatype?: DdbType
+    
+    /** 实际数据。不同的 DdbForm, DdbType 使用 DdbValue 中不同的类型来表示实际数据 */
+    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
+        })
+    }
+}
+
+// ... 还有很多快捷类，如 DdbString, DdbLong, DdbDouble, DdbVectorDouble, DdbVectorAny 等
+
+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 方法声明
+```ts
+async call <T extends DdbObj> (
+    /** 函数名 */
+    func: string,
+    
+    /** 调用参数 (传入的原生 string 和 boolean 会被自动转换为 DdbObj<string> 和 DdbObj<boolean>) */
+    args?: (DdbObj | string | boolean)[] = [ ],
+    
+    /** 调用选项 */
+    options?: {
+        /** 紧急 flag，使用 urgent worker 处理，防止被其它作业阻塞 */
+        urgent?: boolean
+        
+        /** 设置结点 alias 时发送到集群中对应的结点执行 (使用 DolphinDB 中的 rpc 方法) */
+        node?: string
+        
+        /** 设置多个结点 alias 时发送到集群中对应的多个结点执行 (使用 DolphinDB 中的 pnodeRun 方法) */
+        nodes?: string[]
+        
+        /** 设置 node 参数时必传，需指定函数类型，其它情况下不传 */
+        func_type?: DdbFunctionType
+        
+        /** 设置 nodes 参数时选传，其它情况不传 */
+        add_node_alias?: boolean
+    } = { }
+): Promise<T>
+```
+
+
+### 2. 执行脚本
+#### 例子
+```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
+```
+
+上面例子中，通过字符串上传了一段脚本到 DolphinDB 数据库执行，并接收最后一条语句 `foo(1l, 1l)` 执行结果 result
+
+`<DdbInt>` 用于 TypeScript 推断返回值的类型
+
+- result 是一个 `DdbLong`，也是 `DdbObj<bigint>`
+- result.form 是 `DdbForm.scalar`
+- result.type 是 `DdbType.long`
+- result.value 是 JavaScript 中原生的 `bigint` (long 的精度不能用 JavaScript 的 number 准确表示，但可以用 bigint 表示)
+
+只要 WebSocket 连接不断开，在后续的会话中 `foo` 这个自定义函数会一直存在，可复用，比如后续通过 `await ddb.call<DdbInt>('foo', [new DdbInt(1), new DdbInt(1)])` 调用这个自定义函数
+
+#### eval 方法声明
+```ts
+async eval <T extends DdbObj> (
+    /** 执行的脚本 */
+    script: string,
+    
+    /** 执行选项 */
+    options: {
+        /** 紧急 flag，使用 urgent worker 处理，防止被其它作业阻塞 */
+        urgent?: boolean
+    } = { }
+): Promise<T>
+```
+
+
+### 3. 上传变量
+#### 例子
+```ts
+import { DdbVectorDouble } from 'dolphindb'
+
+let a = new Array(10000)
+a.fill(1.0)
+
+ddb.upload(['bar1', 'bar2'], [new DdbVectorDouble(a), new DdbVectorDouble(a)])
+```
+
+上面的例子中，上传了 `bar1`, `bar2` 两个变量，变量值是长度为 10000 的 double 向量
+
+只要 WebSocket 连接不断开，在后续的会话中 `bar1`, `bar2` 这些变量会一直存在，可复用
+
+#### upload 方法声明
+```ts
+async upload (
+    /** 上传的变量名 */
+    vars: string[],
+    
+    /** 上传的变量值 */
+    args: (DdbObj | string | boolean)[]
+): Promise<void>
+```
+

package/browser.d.ts

@@ -0,0 +1,249 @@
+import 'xshell/prototype.browser';
+export declare enum DdbForm {
+    scalar = 0,
+    vector = 1,
+    pair = 2,
+    matrix = 3,
+    set = 4,
+    dict = 5,
+    table = 6,
+    chart = 7,
+    chunk = 8
+}
+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,
+    compress = 26,
+    dict = 27,
+    datehour = 28,
+    ipaddr = 30,
+    int128 = 31,
+    blob = 32,
+    complex = 34,
+    point = 35,
+    duration = 36,
+    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 interface DdbFunctionDefValue {
+    type: DdbFunctionType;
+    name: string;
+}
+export interface DdbSymbolExtendedValue {
+    base_id: number;
+    base: string[];
+    value: 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 declare const nulls: {
+    readonly char: "€";
+    readonly int16: -32768;
+    readonly int32: -2147483648;
+    readonly int64: -9223372036854775808n;
+};
+export declare class DdbObj<T extends DdbValue = DdbValue> {
+    static dec: TextDecoder;
+    static enc: TextEncoder;
+    /** 维护已解析的 symbol base，比如流数据中后续的 symbol 向量可能只发送一个 base.id, base.size == 0, 依赖之前发送的 symbol base */
+    static symbol_bases: Record<number, string[]>;
+    /** little endian (client) */
+    static le_client: boolean;
+    /** 是否为小端 (little endian) */
+    le: boolean;
+    /** 数据形式 https://www.dolphindb.cn/cn/help/DataTypesandStructures/DataForms/index.html */
+    form: DdbForm;
+    /** 数据类型 https://www.dolphindb.cn/cn/help/DataTypesandStructures/DataTypes/index.html */
+    type: DdbType;
+    /** 占用 parse 时传入的 buf 的长度 */
+    length: number;
+    /** table name / column name */
+    name?: string;
+    /**
+        最低维、第 1 维
+        - vector: rows = n, cols = 1
+        - pair:   rows = 2, cols = 1
+        - matrix: rows = n, cols = m
+        - set:    同 vector
+        - dict:   包含 keys, values 向量
+        - table:  同 matrix
+    */
+    rows?: number;
+    /** 第 2 维 */
+    cols?: number;
+    /** matrix 中值的类型，仅 matrix 才有 */
+    datatype?: DdbType;
+    /** 实际数据。不同的 DdbForm, DdbType 使用 DdbValue 中不同的类型来表示实际数据 */
+    value: T;
+    constructor(data: Partial<DdbObj> & {
+        form: DdbForm;
+        type: DdbType;
+        length: number;
+    });
+    static parse(buf: Uint8Array, le: boolean): DdbObj<DdbValue>;
+    static parse_scalar(buf: Uint8Array, le: boolean, type: DdbType): [number, DdbValue];
+    /** parse: rows, cols, items
+        返回的 ddbobj.length 不包括 vector 的 type 和 form
+    */
+    static parse_vector(buf: Uint8Array, le: boolean, type: DdbType): DdbObj;
+    /** 有可能没有字节对齐，不能直接使用原有 message 的 arraybuffer, 统一复制出来，让原有 arraybuffer 被回收掉比较好 */
+    static parse_vector_items(buf: Uint8Array, le: boolean, type: DdbType, length: number): [
+        number,
+        DdbVectorValue
+    ];
+    pack(): Uint8Array;
+    static pack_vector_body(value: DdbVectorValue, type: DdbType, length: number): ArrayBufferView[];
+    toString(): string;
+    to_cols(): any[];
+    to_rows<T extends Record<string, any> = Record<string, any>>(): T[];
+}
+export declare class DdbBool extends DdbObj<boolean> {
+    constructor(value: boolean);
+}
+export declare class DdbInt extends DdbObj<number> {
+    constructor(value: number);
+}
+export declare class DdbString extends DdbObj<string> {
+    constructor(value: string);
+}
+export declare class DdbLong extends DdbObj<bigint> {
+    constructor(value: bigint);
+}
+export declare class DdbDouble extends DdbObj<number> {
+    constructor(value: number);
+}
+export declare class DdbVectorInt extends DdbObj<Int32Array> {
+    constructor(value: number[]);
+}
+export declare class DdbVectorString extends DdbObj<string[]> {
+    constructor(value: string[]);
+}
+export declare class DdbVectorDouble extends DdbObj<Float64Array> {
+    constructor(value: number[]);
+}
+export declare class DdbVectorAny extends DdbObj {
+    constructor(value: DdbObj<DdbValue>[]);
+}
+export declare class DdbPair extends DdbObj<Int32Array> {
+    constructor(l: number, r?: number);
+}
+export declare class DdbFunction extends DdbObj<DdbFunctionDefValue> {
+    constructor(name: string, type: DdbFunctionType);
+}
+export declare class DDB {
+    /** 当前的 session id (http 或 tcp) */
+    sid: string;
+    /** utf-8 text decoder */
+    dec: TextDecoder;
+    enc: TextEncoder;
+    ws_url: string;
+    ws: WebSocket;
+    /** little endian (server) */
+    le: boolean;
+    /** little endian (client) */
+    static le_client: boolean;
+    /** 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 */
+        login?: boolean;
+        /** DolphinDB 登录用户名 */
+        username?: string;
+        /** DolphinDB 登录密码 */
+        password?: string;
+    }): Promise<void>;
+    disconnect(): void;
+    /** rpc through websocket (function 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, }: {
+        script?: string;
+        func?: string;
+        args?: (DdbObj | string | boolean)[];
+        vars?: string[];
+        urgent?: boolean;
+    }): Promise<T>;
+    /** eval script through websocket (script command) */
+    eval<T extends DdbObj>(
+    /** 执行的脚本 */
+    script: string, 
+    /** 执行选项 */
+    { urgent }?: {
+        /** 紧急 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 处理，防止被其它作业阻塞
+            - node?: 设置结点 alias 时发送到集群中对应的结点执行 (使用 DolphinDB 中的 rpc 方法)
+            - nodes?: 设置多个结点 alias 时发送到集群中对应的多个结点执行 (使用 DolphinDB 中的 pnodeRun 方法)
+            - func_type?: 设置 node 参数时必传，需指定函数类型，其它情况下不传
+            - add_node_alias?: 设置 nodes 参数时选传，其它情况不传
+    */
+    call<T extends DdbObj>(func: string, args?: (DdbObj | string | boolean)[], { urgent, node, nodes, func_type, add_node_alias }?: {
+        urgent?: boolean;
+        node?: string;
+        nodes?: string[];
+        func_type?: DdbFunctionType;
+        add_node_alias?: boolean;
+    }): Promise<T>;
+    /** upload variable through websocket (variable command) */
+    upload(
+    /** 上传的变量名 */
+    vars: string[], 
+    /** 上传的变量值 */
+    args: (DdbObj | string | boolean)[]): Promise<DdbObj<DdbValue>>;
+    /** 解析服务端响应报文，返回去掉 header 的 data buf */
+    parse_message(buf: Uint8Array): Uint8Array;
+    /** 自动转换 js string, boolean 为 DdbObj */
+    to_ddbobj(value: DdbObj | string | boolean): DdbObj;
+    /** 转换 js 数组为 DdbObj[] (in place, 会修改原数组) */
+    to_ddbobjs(values: any[]): DdbObj<DdbValue>[];
+}
+export declare let ddb: DDB;
+export default ddb;