dolphindb 0.0.15 → 2.0.502

package/README.md

@@ -220,6 +220,15 @@ const obj = new DdbObj({
 })
 ```
 
+##### NULL object in the form of scalar, the value corresponding to DdbObj is null in JavaScript
+```ts
+;(await ddb.eval('double()')).value === null
+
+// create NULL object
+new DdbInt(null)
+new DdbDouble(null)
+```
+
 
 #### `call` Method Declaration
 ```ts
@@ -321,18 +330,38 @@ async upload (
 ```
 
 
-### Notes
+### Some Examples
 ```ts
-import { nulls, DdbInt, timestamp2str } from 'dolphindb'
+import { nulls, DdbInt, timestamp2str, DdbVectorSymbol, DdbTable, DdbVectorDouble } from 'dolphindb'
 
-// create DolphinDB null integer value (the smallest 32-bit integer)
-new DdbInt(nulls.int32)
-
-// convert DolphinDB timestamp value to string
+// Format timestamp in DolphinDB as string
 timestamp2str(
     (
-        await ddb.call<DdbObj<bigint>>('now', [false])
+        await ddb.call('now', [false])
+        // TypeScript: await ddb.call<DdbObj<bigint>>('now', [false])
     ).value
 ) === '2022.02.23 17:23:13.494'
+
+// create symbol vector
+new DdbVectorSymbol(['aaa', 'aaa', 'aaa', 'aaa', 'aaa', 'bbb'])
+
+// Create a double vector with NULL values using JavaScript native arrays
+new DdbVectorDouble([0.1, null, 0.3])
+
+// More efficient and memory efficient double vector creation using JavaScript TypedArray
+let av = new Float64Array(3)
+av[0] = 0.1
+av[1] = nulls.double
+av[2] = 0.3
+new DdbVectorDouble(av)
+
+// create DdbTable
+new DdbTable(
+    [
+        new DdbVectorDouble([0.1, 0.2, null], 'col0'),
+        new DdbVectorSymbol(['a', 'b', 'c'], 'col1')
+    ],
+    'mytable'
+)
 ```
 

package/README.zh.md

@@ -221,6 +221,15 @@ const obj = new DdbObj({
 })
 ```
 
+##### scalar 形式的 NULL 对象, 对应 DdbObj 的 value 为 JavaScript 中的 null
+```ts
+;(await ddb.eval('double()')).value === null
+
+// 创建 NULL 对象
+new DdbInt(null)
+new DdbDouble(null)
+```
+
 
 #### `call` 方法声明
 ```ts
@@ -322,17 +331,37 @@ async upload (
 ```
 
 
-### Notes
+### 一些例子
 ```ts
-import { nulls, DdbInt, timestamp2str } from 'dolphindb'
-
-// 创建 DolphinDB 空值 (最小的 32-bit 整数)
-new DdbInt(nulls.int32)
+import { nulls, DdbInt, timestamp2str, DdbVectorSymbol, DdbTable, DdbVectorDouble } from 'dolphindb'
 
 // 将 DolphinDB 中的 timestamp 格式化为 string
 timestamp2str(
     (
-        await ddb.call<DdbObj<bigint>>('now', [false])
+        await ddb.call('now', [false])
+        // TypeScript: await ddb.call<DdbObj<bigint>>('now', [false])
     ).value
 ) === '2022.02.23 17:23:13.494'
+
+// 创建 symbol vector
+new DdbVectorSymbol(['aaa', 'aaa', 'aaa', 'aaa', 'aaa', 'bbb'])
+
+// 使用 JavaScript 原生数组创建含有 NULL 值的 double vector
+new DdbVectorDouble([0.1, null, 0.3])
+
+// 使用 JavaScript TypedArray 更加高效且节约内存的创建 double vector
+let av = new Float64Array(3)
+av[0] = 0.1
+av[1] = nulls.double
+av[2] = 0.3
+new DdbVectorDouble(av)
+
+// 创建 DdbTable
+new DdbTable(
+    [
+        new DdbVectorDouble([0.1, 0.2, null], 'col0'),
+        new DdbVectorSymbol(['a', 'b', 'c'], 'col1')
+    ],
+    'mytable'
+)
 ```

package/browser.d.ts

@@ -78,10 +78,15 @@ export interface DdbArrayVectorBlock {
 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 bool: 128;
     readonly char: "€";
     readonly int16: -32768;
     readonly int32: -2147483648;
     readonly int64: -9223372036854775808n;
+    readonly float32: -3.4028234663852886e+38;
+    /** -Number.MAX_VALUE */
+    readonly double: number;
+    readonly bytes16: Uint8Array;
 };
 export declare const timezone_offset: number;
 /** 可以表示所有 DolphinDB 数据库中的数据类型 */
@@ -149,49 +154,55 @@ export declare class DdbVoid extends DdbObj<undefined> {
     constructor();
 }
 export declare class DdbBool extends DdbObj<boolean> {
-    constructor(value: boolean);
+    constructor(value: boolean | null);
 }
 export declare class DdbChar extends DdbObj<string> {
-    constructor(value: string);
+    constructor(value: string | null);
 }
 export declare class DdbInt extends DdbObj<number> {
-    constructor(value: number);
+    constructor(value: number | null);
 }
 export declare class DdbString extends DdbObj<string> {
     constructor(value: string);
 }
 export declare class DdbLong extends DdbObj<bigint> {
-    constructor(value: bigint);
+    constructor(value: bigint | null);
 }
 export declare class DdbDouble extends DdbObj<number> {
-    constructor(value: number);
+    constructor(value: number | null);
 }
 export declare class DdbDateTime extends DdbObj<number> {
-    constructor(value: number);
+    constructor(value: number | null);
 }
 export declare class DdbTimeStamp extends DdbObj<bigint> {
-    constructor(value: bigint);
+    constructor(value: bigint | null);
 }
 export declare class DdbNanoTimeStamp extends DdbObj<bigint> {
-    constructor(value: bigint);
+    constructor(value: bigint | null);
+}
+export declare class DdbPair extends DdbObj<Int32Array> {
+    constructor(l: number | null, r?: number | null);
+}
+export declare class DdbFunction extends DdbObj<DdbFunctionDefValue> {
+    constructor(name: string, type: DdbFunctionType);
 }
 export declare class DdbVectorInt extends DdbObj<Int32Array> {
-    constructor(value: number[], name?: string);
+    constructor(ints: (number | null)[] | Int32Array, name?: string);
 }
 export declare class DdbVectorString extends DdbObj<string[]> {
-    constructor(value: string[], name?: string);
+    constructor(strings: string[], name?: string);
 }
 export declare class DdbVectorDouble extends DdbObj<Float64Array> {
-    constructor(value: number[], name?: string);
+    constructor(doubles: (number | null)[] | Float64Array, name?: string);
 }
 export declare class DdbVectorAny extends DdbObj {
-    constructor(value: DdbObj<DdbValue>[], name?: string);
+    constructor(objs: DdbObj<DdbValue>[], name?: string);
 }
-export declare class DdbPair extends DdbObj<Int32Array> {
-    constructor(l: number, r?: number);
+export declare class DdbVectorSymbol extends DdbObj<DdbSymbolExtendedValue> {
+    constructor(strings: string[], name?: string);
 }
-export declare class DdbFunction extends DdbObj<DdbFunctionDefValue> {
-    constructor(name: string, type: DdbFunctionType);
+export declare class DdbTable extends DdbObj<DdbObj[]> {
+    constructor(columns: DdbObj[], name?: string);
 }
 export declare function date2str(date: number, format?: string): string;
 export declare function datetime2str(datetime: number, format?: string): string;
@@ -249,6 +260,7 @@ export declare class DDB {
     presolver(buf: Uint8Array): void;
     prejector(error: Error): void;
     presult: Promise<Uint8Array>;
+    get connected(): boolean;
     /**
         Initialize an instance of DolphinDB Client using the WebSocket URL
         (without establishing an actual network connection)
@@ -349,7 +361,7 @@ export declare class DDB {
     };
     /** 自动转换 js string, boolean 为 DdbObj */
     to_ddbobj(value: DdbObj | string | boolean): DdbObj;
-    /** 转换 js 数组为 DdbObj[] (in place, 会修改原数组) */
+    /** 转换 js 数组为 DdbObj[] */
     to_ddbobjs(values: any[]): DdbObj<DdbValue>[];
 }
 export declare let ddb: DDB;

package/browser.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ddb = exports.DDB = exports.str2nanotimestamp = exports.nanotimestamp2str = exports.str2timestamp = exports.timestamp2str = exports.datetime2str = exports.date2str = exports.DdbFunction = exports.DdbPair = exports.DdbVectorAny = exports.DdbVectorDouble = exports.DdbVectorString = exports.DdbVectorInt = exports.DdbNanoTimeStamp = exports.DdbTimeStamp = exports.DdbDateTime = exports.DdbDouble = exports.DdbLong = exports.DdbString = exports.DdbInt = exports.DdbChar = exports.DdbBool = exports.DdbVoid = exports.DdbObj = exports.timezone_offset = exports.nulls = exports.DdbFunctionType = exports.DdbType = exports.DdbForm = void 0;
+exports.ddb = exports.DDB = exports.str2nanotimestamp = exports.nanotimestamp2str = exports.str2timestamp = exports.timestamp2str = exports.datetime2str = exports.date2str = exports.DdbTable = exports.DdbVectorSymbol = exports.DdbVectorAny = exports.DdbVectorDouble = exports.DdbVectorString = exports.DdbVectorInt = exports.DdbFunction = exports.DdbPair = exports.DdbNanoTimeStamp = exports.DdbTimeStamp = exports.DdbDateTime = exports.DdbDouble = exports.DdbLong = exports.DdbString = exports.DdbInt = exports.DdbChar = exports.DdbBool = exports.DdbVoid = exports.DdbObj = exports.timezone_offset = exports.nulls = exports.DdbFunctionType = exports.DdbType = exports.DdbForm = void 0;
 const tslib_1 = require("tslib");
 const dayjs_1 = tslib_1.__importDefault(require("dayjs"));
 const customParseFormat_js_1 = tslib_1.__importDefault(require("dayjs/plugin/customParseFormat.js"));
@@ -72,10 +72,15 @@ var DdbFunctionType;
     DdbFunctionType[DdbFunctionType["JitPartialFunc"] = 8] = "JitPartialFunc";
 })(DdbFunctionType = exports.DdbFunctionType || (exports.DdbFunctionType = {}));
 exports.nulls = {
+    bool: 0x80,
     char: '\x80',
     int16: -32768,
     int32: -2147483648,
-    int64: -0x8000000000000000n, // -922_3372_0368_5477_5808
+    int64: -0x8000000000000000n,
+    float32: -3.4028234663852886e+38,
+    /** -Number.MAX_VALUE */
+    double: -Number.MAX_VALUE,
+    bytes16: Uint8Array.from(new Array(16).fill(0))
 };
 exports.timezone_offset = 1000 * 60 * new Date().getTimezoneOffset();
 /** 可以表示所有 DolphinDB 数据库中的数据类型 */
@@ -92,7 +97,7 @@ class DdbObj {
                 form: DdbForm.scalar,
                 type: DdbType.void,
                 length: 0,
-                value: undefined
+                value: null
             });
         const type = buf[0];
         const form = buf[1];
@@ -241,13 +246,18 @@ class DdbObj {
         switch (type) {
             case DdbType.void:
                 return [1, null];
-            case DdbType.bool:
-                return [1, Boolean(buf[0])];
-            case DdbType.char:
-                return [1, String.fromCharCode(buf[0])];
+            case DdbType.bool: {
+                const value = buf[0];
+                return [1, value === exports.nulls.bool ? null : Boolean(value)];
+            }
+            case DdbType.char: {
+                const value = String.fromCharCode(buf[0]);
+                return [1, value === exports.nulls.char ? null : value];
+            }
             case DdbType.short: {
                 const dv = new DataView(buf.buffer, buf.byteOffset);
-                return [2, dv.getInt16(0, le)];
+                const value = dv.getInt16(0, le);
+                return [2, value === exports.nulls.int16 ? null : value];
             }
             case DdbType.int:
             // datetime
@@ -259,15 +269,18 @@ class DdbObj {
             case DdbType.datetime:
             case DdbType.datehour: {
                 const dv = new DataView(buf.buffer, buf.byteOffset);
-                return [4, dv.getInt32(0, le)];
+                const value = dv.getInt32(0, le);
+                return [4, value === exports.nulls.int32 ? null : value];
             }
             case DdbType.float: {
                 const dv = new DataView(buf.buffer, buf.byteOffset);
-                return [4, dv.getFloat32(0, le)];
+                const value = dv.getFloat32(0, le);
+                return [4, value === exports.nulls.float32 ? null : value];
             }
             case DdbType.double: {
                 const dv = new DataView(buf.buffer, buf.byteOffset);
-                return [8, dv.getFloat64(0, le)];
+                const value = dv.getFloat64(0, le);
+                return [8, value === exports.nulls.double ? null : value];
             }
             case DdbType.long:
             // timestamp
@@ -275,7 +288,8 @@ class DdbObj {
             case DdbType.nanotime:
             case DdbType.nanotimestamp: {
                 const dv = new DataView(buf.buffer, buf.byteOffset);
-                return [8, dv.getBigInt64(0, le)];
+                const value = dv.getBigInt64(0, le);
+                return [8, value === exports.nulls.int64 ? null : value];
             }
             case DdbType.string:
             case DdbType.symbol:
@@ -576,11 +590,26 @@ class DdbObj {
                         case DdbType.void:
                             return [Uint8Array.of(1)];
                         case DdbType.bool:
-                            return [Uint8Array.of(Number(value))];
+                            return [
+                                Uint8Array.of(value === null ?
+                                    exports.nulls.bool
+                                    :
+                                        Number(value))
+                            ];
                         case DdbType.char:
-                            return [Uint8Array.of(value.charCodeAt(0))];
+                            return [
+                                Uint8Array.of((value === null ?
+                                    exports.nulls.char
+                                    :
+                                        value).charCodeAt(0))
+                            ];
                         case DdbType.short:
-                            return [Int16Array.of(value)];
+                            return [
+                                Int16Array.of(value === null ?
+                                    exports.nulls.int16
+                                    :
+                                        value)
+                            ];
                         case DdbType.int:
                         // datetime
                         case DdbType.date:
@@ -590,17 +619,37 @@ class DdbObj {
                         case DdbType.second:
                         case DdbType.datetime:
                         case DdbType.datehour:
-                            return [Int32Array.of(value)];
+                            return [
+                                Int32Array.of(value === null ?
+                                    exports.nulls.int32
+                                    :
+                                        value)
+                            ];
                         case DdbType.float:
-                            return [Float32Array.of(value)];
+                            return [
+                                Float32Array.of(value === null ?
+                                    exports.nulls.float32
+                                    :
+                                        value)
+                            ];
                         case DdbType.double:
-                            return [Float64Array.of(value)];
+                            return [
+                                Float64Array.of(value === null ?
+                                    exports.nulls.double
+                                    :
+                                        value)
+                            ];
                         case DdbType.long:
                         // timestamp
                         case DdbType.timestamp:
                         case DdbType.nanotime:
                         case DdbType.nanotimestamp:
-                            return [BigInt64Array.of(this.value)];
+                            return [
+                                BigInt64Array.of(value === null ?
+                                    exports.nulls.int64
+                                    :
+                                        value)
+                            ];
                         case DdbType.string:
                         case DdbType.symbol:
                         case DdbType.code:
@@ -660,15 +709,12 @@ class DdbObj {
                 case DdbForm.table:
                     return [
                         Uint32Array.of(this.rows, this.cols),
-                        DdbObj.enc.encode(this.name),
+                        DdbObj.enc.encode(this.name || ''),
+                        // column names
                         Uint8Array.of(0),
-                        ...DdbObj.pack_vector_body(this.value.map(col => col.name), DdbType.string, this.cols),
-                        ...(() => {
-                            let cols = new Array(this.cols);
-                            for (let i = 0; i < cols.length; i++)
-                                cols[i] = this.value[i].pack();
-                            return cols;
-                        })()
+                        ...DdbObj.pack_vector_body(this.value.map((col, i) => col.name || `col${i}`), DdbType.string, this.cols),
+                        // column vectors
+                        ...this.value.map(col => col.pack())
                     ];
                 case DdbForm.dict:
                     return [
@@ -764,7 +810,7 @@ class DdbObj {
             case DdbType.symbol_extended: {
                 const { base_id, base, data } = value;
                 return [
-                    Uint32Array.of(base_id, base.length),
+                    Uint32Array.of(base_id || 0, base.length),
                     ...this.pack_vector_body(base, DdbType.string, base.length),
                     data
                 ];
@@ -879,6 +925,7 @@ class DdbVoid extends DdbObj {
             form: DdbForm.scalar,
             type: DdbType.void,
             length: 0,
+            value: null,
         });
     }
 }
@@ -911,7 +958,7 @@ class DdbInt extends DdbObj {
             form: DdbForm.scalar,
             type: DdbType.int,
             length: 4,
-            value
+            value,
         });
     }
 }
@@ -982,86 +1029,143 @@ class DdbNanoTimeStamp extends DdbObj {
     }
 }
 exports.DdbNanoTimeStamp = DdbNanoTimeStamp;
+class DdbPair extends DdbObj {
+    constructor(l, r = null) {
+        super({
+            form: DdbForm.pair,
+            type: DdbType.int,
+            length: 0,
+            rows: 2,
+            cols: 1,
+            value: Int32Array.of(l === null ? exports.nulls.int32 : l, r === null ? exports.nulls.int32 : r)
+        });
+    }
+}
+exports.DdbPair = DdbPair;
+class DdbFunction extends DdbObj {
+    constructor(name, type) {
+        super({
+            form: DdbForm.scalar,
+            type: DdbType.functiondef,
+            length: 0,
+            value: { type, name }
+        });
+    }
+}
+exports.DdbFunction = DdbFunction;
 class DdbVectorInt extends DdbObj {
-    constructor(value, name) {
+    constructor(ints, name) {
         super({
             form: DdbForm.vector,
             type: DdbType.int,
             length: 0,
-            rows: value.length,
+            rows: ints.length,
             cols: 1,
-            value: Int32Array.from(value),
+            value: ints instanceof Int32Array ?
+                ints
+                :
+                    Int32Array.from(ints, v => v === null ?
+                        exports.nulls.int32
+                        :
+                            v),
             name,
         });
     }
 }
 exports.DdbVectorInt = DdbVectorInt;
 class DdbVectorString extends DdbObj {
-    constructor(value, name) {
+    constructor(strings, name) {
         super({
             form: DdbForm.vector,
             type: DdbType.string,
             length: 0,
-            rows: value.length,
+            rows: strings.length,
             cols: 1,
-            value,
+            value: strings,
             name,
         });
     }
 }
 exports.DdbVectorString = DdbVectorString;
 class DdbVectorDouble extends DdbObj {
-    constructor(value, name) {
+    constructor(doubles, name) {
         super({
             form: DdbForm.vector,
             type: DdbType.double,
             length: 0,
-            rows: value.length,
+            rows: doubles.length,
             cols: 1,
-            value: Float64Array.from(value),
+            value: doubles instanceof Float64Array ?
+                doubles
+                :
+                    Float64Array.from(doubles, v => v === null ?
+                        exports.nulls.double
+                        :
+                            v),
             name,
         });
     }
 }
 exports.DdbVectorDouble = DdbVectorDouble;
 class DdbVectorAny extends DdbObj {
-    constructor(value, name) {
+    constructor(objs, name) {
         super({
             form: DdbForm.vector,
             type: DdbType.any,
             length: 0,
-            rows: value.length,
+            rows: objs.length,
             cols: 1,
-            value,
+            value: objs,
             name,
         });
     }
 }
 exports.DdbVectorAny = DdbVectorAny;
-class DdbPair extends DdbObj {
-    constructor(l, r = -2147483648) {
+class DdbVectorSymbol extends DdbObj {
+    constructor(strings, name) {
+        let map = new Map([
+            ['', 0]
+        ]);
+        let data = new Uint32Array(strings.length);
+        for (let i = 0; i < strings.length; i++) {
+            const x = strings[i];
+            let index = map.get(x);
+            if (index === undefined) {
+                index = map.size;
+                map.set(x, index);
+            }
+            data[i] = index;
+        }
         super({
-            form: DdbForm.pair,
-            type: DdbType.int,
+            form: DdbForm.vector,
+            type: DdbType.symbol_extended,
             length: 0,
-            rows: 2,
+            rows: strings.length,
             cols: 1,
-            value: Int32Array.of(l, r)
+            value: {
+                base: [...map.keys()],
+                base_id: null,
+                data,
+            },
+            name
         });
     }
 }
-exports.DdbPair = DdbPair;
-class DdbFunction extends DdbObj {
-    constructor(name, type) {
+exports.DdbVectorSymbol = DdbVectorSymbol;
+class DdbTable extends DdbObj {
+    constructor(columns, name = '') {
         super({
-            form: DdbForm.scalar,
-            type: DdbType.functiondef,
+            form: DdbForm.table,
+            type: DdbType.void,
             length: 0,
-            value: { type, name }
+            rows: columns[0].rows,
+            cols: columns.length,
+            name,
+            value: columns,
         });
     }
 }
-exports.DdbFunction = DdbFunction;
+exports.DdbTable = DdbTable;
 function date2str(date, format = 'YYYY.MM.DD') {
     return date === exports.nulls.int32 ?
         ''
@@ -1187,12 +1291,14 @@ class DDB {
     /** resolver, rejector, promise of last rpc */
     presolver(buf) { }
     prejector(error) { }
+    get connected() {
+        return this.websocket?.readyState === WebSocket.OPEN;
+    }
     /** Establish the actual WebSocket connection to the DolphinDB corresponding to the URL */
     async connect({ url = this.url, login = true, username = 'admin', password = '123456', python = false, } = {}) {
         this.url = url;
         this.python = python;
-        if (this.websocket?.readyState === WebSocket.OPEN)
-            this.disconnect();
+        this.disconnect();
         let websocket = new WebSocket(url, python ? ['python'] : []);
         // https://stackoverflow.com/questions/11821096/what-is-the-difference-between-an-arraybuffer-and-a-blob/39951543
         websocket.binaryType = 'arraybuffer';
@@ -1283,7 +1389,11 @@ class DDB {
         return `/ ${options.join('_')}`;
     }
     disconnect() {
-        this.websocket?.close(1000);
+        if (this.connected)
+            this.websocket.close(1000);
+        this.presolver = buf => { };
+        this.prejector = error => { };
+        this.presult = Promise.resolve(null);
     }
     /** rpc through websocket (function/script/variable command)
         - type: API 类型: 'script' | 'function' | 'variable'
@@ -1294,7 +1404,7 @@ class DDB {
     async rpc(type, { script, func, args = [], vars = [], urgent, }) {
         if (!this.websocket)
             await this.connect();
-        if (this.websocket.readyState !== WebSocket.OPEN)
+        if (!this.connected)
             throw new Error(`${this.url} is already disconnected`);
         // 临界区：保证多个 rpc 并发时形成 promise 链
         // ddb 世界观：需要等待上一个 rpc 结果从 server 返回之后才能发起下一个调用  
@@ -1317,7 +1427,7 @@ class DDB {
         // 临界区结束，只有一个 rpc 请求可以写 WebSocket
         if (urgent && type !== 'script' && type !== 'function')
             throw new Error('urgent 只适用于 script 和 funciton');
-        this.to_ddbobjs(args);
+        args = this.to_ddbobjs(args);
         const command = this.enc.encode((() => {
             switch (type) {
                 case 'function':
@@ -1459,11 +1569,9 @@ class DDB {
                 throw new Error(`不能自动转换 ${type} 至 DdbObj`);
         }
     }
-    /** 转换 js 数组为 DdbObj[] (in place, 会修改原数组) */
+    /** 转换 js 数组为 DdbObj[] */
     to_ddbobjs(values) {
-        for (let i = 0; i < values.length; i++)
-            values[i] = this.to_ddbobj(values[i]);
-        return values;
+        return values.map(value => this.to_ddbobj(value));
     }
 }
 exports.DDB = DDB;