dolphindb 2.0.800 → 2.0.900

package/README.md

@@ -21,7 +21,7 @@ DolphinDB JavaScript API is a JavaScript library that encapsulates the ability t
 https://www.npmjs.com/package/dolphindb
 
 ## Features
-- Communicate with DolphinDB database using WebSocket, exchange data in binary format
+- Use WebSocket to communicate with DolphinDB database, exchange data in binary format, and support real-time push of streaming data
 - 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
@@ -48,10 +48,13 @@ import { DDB } from 'dolphindb'
 // The import method for existing projects using CommonJS modules is const { DDB } = require('dolphindb')
 // Use in browser: import { DDB } form 'dolphindb/browser.js'
 
-// Create a database object and initialize the WebSocket URL
+// Initially connect to an instance of DolphinDB using the WebSocket URL (without establishing an actual network connection)
 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)
+// Encrypt with HTTPS
+// let ddb = new DDB('wss://dolphindb.com')
+
+// Establish a connection to DolphinDB (requires DolphinDB database version at least 1.30.16 or 2.00.4)
 await ddb.connect()
 ```
 
@@ -71,7 +74,10 @@ let ddbsecure = new DDB('wss://dolphindb.com', {
     password: '123456',
     
     // set python session flag, default `false`
-    python: false
+    python: false,
+    
+    // After setting this option, the database connection is only used for streaming data. For details, see `5. Streaming Data`
+    streaming: undefined
 })
 ```
 
@@ -336,7 +342,7 @@ async upload (
 ```
 
 
-### Some Examples
+### 4. Some Examples
 ```ts
 import { nulls, DdbInt, timestamp2str, DdbVectorSymbol, DdbTable, DdbVectorDouble } from 'dolphindb'
 
@@ -371,3 +377,72 @@ new DdbTable(
 )
 ```
 
+### 5. Streaming Data
+```ts
+// New Streaming Data Connection Configuration
+let sddb = new DDB('ws://192.168.0.43:8800', {
+    autologin: true,
+    username: 'admin',
+    password: '123456',
+    streaming: {
+        table: 'Streaming table name to subscribe to',
+        
+        // Streaming data processing callback, the type of message is StreamingData
+        handler (message) {
+            console.log(message)
+        }
+    }
+})
+
+// Establish connection
+await sddb.connect()
+```
+
+The streaming data received after the connection is established will be used as the message parameter of the handler. The type of the message is StreamingData, as follows:
+
+```ts
+export interface StreamingParams {
+    table: string
+    action?: string
+    
+    handler (message: StreamingData): any
+}
+
+export interface StreamingData extends StreamingParams {
+    /**
+        The time the server sent the message (nano seconds since epoch)  
+        std::chrono::system_clock::now().time_since_epoch() / std::chrono::nanoseconds(1)
+    */
+    time: bigint
+    
+    /** message id */
+    id: bigint
+    
+    colnames: string[]
+    
+    /** Subscription topic, which is the name of a subscription.
+        It is a string consisting of the alias of the node where the subscription table is located, the stream data table name, and the subscription task name (if actionName is specified), separated by `/`
+    */
+    topic: string
+    
+    /** Streaming data, the type is any vector, each element of which corresponds to a column (without name) of the subscribed table, and the content in the column (DdbObj<DdbVectorValue>) is the new data value */
+    data: DdbObj<DdbVectorObj[]>
+    
+    /** Number of new streaming data rows */
+    rows: number
+    
+    window: {
+        /** The establishment of the connection starts offset = 0, and gradually increases as the window moves */
+        offset: number
+        
+        /** sum of segment.row in segments */
+        rows: number
+        
+        /** An array of data received each time */
+        segments: DdbObj<DdbVectorObj[]>[]
+    }
+    
+    /** After successfully subscribed, if the subsequently pushed message is parsed incorrectly, the error will be set and the handler will be called. */
+    error?: Error
+}
+```

package/README.zh.md

@@ -21,7 +21,7 @@ DolphinDB JavaScript API 是一个 JavaScript 库，封装了操作 DolphinDB
 https://www.npmjs.com/package/dolphindb
 
 ## 特性
-- 使用 WebSocket 与 DolphinDB 数据库通信，用二进制格式进行数据交换
+- 使用 WebSocket 与 DolphinDB 数据库通信，用二进制格式进行数据交换，支持流数据实时推送
 - 支持在浏览器环境和 Node.js 环境中运行
 - 使用了 JavaScript 中的 Int32Array 等 TypedArray 处理二进制数据，性能较高
 - 单次调用支持最大 2 GB 数据的序列化上传，下载数据量不受限制
@@ -48,19 +48,19 @@ import { DDB } from 'dolphindb'
 // 已有的使用 CommonJS 模块的项目的导入方法为 const { DDB } = require('dolphindb')
 // 在浏览器中使用: import { DDB } form 'dolphindb/browser.js'
 
-// 创建数据库对象，初始化 WebSocket 连接地址
+// 使用 WebSocket URL 初始化连接到 DolphinDB 的实例（不建立实际的网络连接）
 let ddb = new DDB('ws://127.0.0.1:8848')
 
-// 建立到 DolphinDB 的 WebSocket 连接（要求 DolphinDB 数据库版本不低于 1.30.16 或 2.00.4）
+// 使用 HTTPS 加密
+// let ddb = new DDB('wss://dolphindb.com')
+
+// 建立到 DolphinDB 的连接（要求 DolphinDB 数据库版本不低于 1.30.16 或 2.00.4）
 await ddb.connect()
 ```
 
 #### DDB 选项
 ```ts
-let ddb = new DDB('ws://127.0.0.1:8848')
-
-// 使用 HTTPS 加密
-let ddbsecure = new DDB('wss://dolphindb.com', {
+let ddb = new DDB('ws://127.0.0.1:8848', {
     // 是否在建立连接后自动登录，默认 `true`
     autologin: true,
     
@@ -71,7 +71,10 @@ let ddbsecure = new DDB('wss://dolphindb.com', {
     password: '123456',
     
     // 设置 python session flag，默认 `false`
-    python: false
+    python: false,
+    
+    // 设置该选项后，该数据库连接只用于流数据，详细用法见后文 `5. 流数据`
+    streaming: undefined
 })
 ```
 
@@ -336,7 +339,7 @@ async upload (
 ```
 
 
-### 一些例子
+### 4. 一些例子
 ```ts
 import { nulls, DdbInt, timestamp2str, DdbVectorSymbol, DdbTable, DdbVectorDouble } from 'dolphindb'
 
@@ -370,3 +373,74 @@ new DdbTable(
     'mytable'
 )
 ```
+
+
+### 5. 流数据
+```ts
+// 新建流数据连接配置
+let sddb = new DDB('ws://192.168.0.43:8800', {
+    autologin: true,
+    username: 'admin',
+    password: '123456',
+    streaming: {
+        table: '要订阅的流表名称',
+        
+        // 流数据处理回调, message 的类型是 StreamingData
+        handler (message) {
+            console.log(message)
+        }
+    }
+})
+
+// 建立连接
+await sddb.connect()
+```
+
+连接建立后接收到的流数据会作为 message 参数调用 handler, message 的类型是 StreamingData, 如下:
+
+```ts
+export interface StreamingParams {
+    table: string
+    action?: string
+    
+    handler (message: StreamingData): any
+}
+
+export interface StreamingData extends StreamingParams {
+    /**
+        server 发送消息的时间 (nano seconds since epoch)  
+        std::chrono::system_clock::now().time_since_epoch() / std::chrono::nanoseconds(1)
+    */
+    time: bigint
+    
+    /** message id */
+    id: bigint
+    
+    colnames: string[]
+    
+    /** 订阅主题，即一个订阅的名称。
+        它是一个字符串，由订阅表所在节点的别名、流数据表名称和订阅任务名称（如果指定了 actionName）组合而成，使用 `/` 分隔
+    */
+    topic: string
+    
+    /** 流数据，类型是 any vector, 其中的每一个元素对应被订阅表的一个列 (没有 name)，列 (DdbObj<DdbVectorValue>) 中的内容是新增的数据值 */
+    data: DdbObj<DdbVectorObj[]>
+    
+    /** 新增的流数据行数 */
+    rows: number
+    
+    window: {
+        /** 建立连接开始 offset = 0, 随着 window 的移动逐渐增加 */
+        offset: number
+        
+        /** segments 中 segment.row 的总和 */
+        rows: number
+        
+        /** 每次接收到的 data 组成的数组 */
+        segments: DdbObj<DdbVectorObj[]>[]
+    }
+    
+    /** 成功订阅后，后续推送过来的 message 解析错误，则会设置 error 并调用 handler */
+    error?: Error
+}
+```

package/browser.d.ts

@@ -124,12 +124,15 @@ export interface DdbArrayVectorBlock {
     lengths: Uint8Array | Uint16Array | Uint32Array;
     data: Int8Array | Int16Array | Int32Array | Float32Array | Float64Array | BigInt64Array;
 }
+export type DdbArrayVectorValue = DdbArrayVectorBlock[] & /* decimal32, decimal64 会有这个属性 */ {
+    scale?: number;
+};
 export interface DdbMatrixValue {
     rows: DdbVectorObj;
     cols: DdbVectorObj;
     data: DdbVectorValue;
 }
-export declare type DdbDictValue = [DdbVectorObj, DdbVectorObj];
+export type DdbDictValue = [DdbVectorObj, DdbVectorObj];
 export declare enum DdbChartType {
     area = 0,
     bar = 1,
@@ -164,24 +167,24 @@ export interface DdbChartValue {
     };
     data: DdbMatrixObj;
 }
-export declare type DdbScalarValue = null | boolean | number | bigint | string | Uint8Array | // uuid, ipaddr, int128, blob
+export type DdbScalarValue = null | boolean | number | bigint | string | Uint8Array | // uuid, ipaddr, int128, blob
 [
     number,
     number
 ] | // complex, point
 DdbFunctionDefValue | DdbDurationValue | DdbDecimal32Value | DdbDecimal64Value;
-export declare type DdbVectorValue = Uint8Array | Int8Array | Int16Array | Int32Array | Float32Array | Float64Array | BigInt64Array | string[] | // string[]
+export type DdbVectorValue = Uint8Array | Int8Array | Int16Array | Int32Array | Float32Array | Float64Array | BigInt64Array | string[] | // string[]
 Uint8Array[] | // blob
 DdbObj[] | // any
-DdbSymbolExtendedValue | DdbArrayVectorBlock[] | DdbDecimal32VectorValue | DdbDecimal64VectorValue;
-export declare type DdbValue = DdbScalarValue | DdbVectorValue | DdbMatrixValue | DdbDictValue | DdbChartValue;
-export declare type DdbVectorObj = DdbObj<DdbVectorValue>;
-export declare type DdbVectorAnyObj = DdbObj<DdbObj[]>;
-export declare type DdbVectorStringObj = DdbObj<string[]>;
-export declare type DdbTableObj = DdbObj<DdbVectorObj[]>;
-export declare type DdbDictObj = DdbObj<[DdbVectorObj, DdbVectorObj]>;
-export declare type DdbMatrixObj = DdbObj<DdbMatrixValue>;
-export declare type DdbChartObj = DdbObj<DdbChartValue>;
+DdbSymbolExtendedValue | DdbArrayVectorValue | DdbDecimal32VectorValue | DdbDecimal64VectorValue;
+export type DdbValue = DdbScalarValue | DdbVectorValue | DdbMatrixValue | DdbDictValue | DdbChartValue;
+export type DdbVectorObj = DdbObj<DdbVectorValue>;
+export type DdbVectorAnyObj = DdbObj<DdbObj[]>;
+export type DdbVectorStringObj = DdbObj<string[]>;
+export type DdbTableObj = DdbObj<DdbVectorObj[]>;
+export type DdbDictObj = DdbObj<[DdbVectorObj, DdbVectorObj]>;
+export type DdbMatrixObj = DdbObj<DdbMatrixValue>;
+export type DdbChartObj = DdbObj<DdbChartValue>;
 export declare const nulls: {
     readonly int8: -128;
     readonly int16: -32768;
@@ -192,14 +195,6 @@ export declare const nulls: {
     readonly double: number;
     readonly bytes16: Uint8Array;
 };
-export declare const timezone_offset: number;
-export declare enum StreamingStatusCode {
-    ok = 0,
-    connection_existed = 1,
-    not_leader = 2,
-    other = 3,
-    error = 4
-}
 /** 可以表示所有 DolphinDB 数据库中的数据类型 */
 export declare class DdbObj<TValue extends DdbValue = DdbValue> {
     static dec: TextDecoder;
@@ -262,7 +257,7 @@ export declare class DdbObj<TValue extends DdbValue = DdbValue> {
     to_cols(): {
         title: string;
         dataIndex: string;
-        render?: any;
+        render: (value: any) => string;
     }[];
     to_rows<T extends Record<string, any> = Record<string, any>>(): T[];
     /** Automatically convert dict<string, any> to js object (Record<string, any>)
@@ -283,10 +278,14 @@ export interface InspectOptions {
     colors?: boolean;
     /** decimal places */
     decimals?: number;
+    /** `false` 决定 null 值如何返回. nullstr ? 'null' : '' */
+    nullstr?: boolean;
+    /** `false` 决定 string, symbol, char 类型是否加引号 */
+    quote?: boolean;
 }
 /** Formats a single element (value) as a string according to DdbType, null returns a 'null' string */
 export declare function format(type: DdbType, value: DdbValue, le: boolean, options?: InspectOptions): string;
-/** formatted vector, the index-th item in the collection is a string, a null value returns a 'null' string */
+/** formatted vector, the index-th item in the collection is a string */
 export declare function formati(obj: DdbVectorObj, index: number, options?: InspectOptions): string;
 export declare class DdbVoid extends DdbObj<undefined> {
     constructor();
@@ -428,10 +427,10 @@ export interface StreamingData extends StreamingParams {
         It is a string consisting of the alias of the node where the subscription table is located, the stream data table name, and the subscription task name (if actionName is specified), separated by `/`
     */
     topic: string;
-    /** The schema of the flow table, the type is table, there is no data in the column vector (rows === 0), only the column name and type */
-    schema: DdbTableObj;
     /** Stream data, the type is any vector, each element of which corresponds to a column (without name) of the subscribed table, and the content in the column (DdbObj<DdbVectorValue>) is the new data value */
     data: DdbObj<DdbVectorObj[]>;
+    /** Number of new streaming data rows */
+    rows: number;
     window: {
         /** The establishment of the connection starts offset = 0, and gradually increases as the window moves */
         offset: number;
@@ -440,8 +439,14 @@ export interface StreamingData extends StreamingParams {
         /** An array of data received each time */
         segments: DdbObj<DdbVectorObj[]>[];
     };
+    /** After successfully subscribed, if the subsequently pushed message is parsed incorrectly, the error will be set and the handler will be called. */
+    error?: Error;
+}
+export declare const winsize: 100000;
+export declare class ConnectionError extends Error {
+    ddb: DDB;
+    constructor(ddb: DDB);
 }
-export declare const winsize: 40;
 export declare class DDB {
     /** 当前的 session id (http 或 tcp) */
     sid: string;
@@ -508,23 +513,10 @@ export declare class DDB {
         streaming?: StreamingParams;
     });
     private on_message;
-    /** Establish the actual WebSocket connection to the DolphinDB corresponding to the URL
-        - options?:
-            - url?: DolphinDB WebSocket URL. By default, the WebSocket URL passed in when the instance is initialized is used
-            - autologin?: Whether to log in automatically after establishing a connection, default `true`
-            - username?: DolphinDB username, default `'admin'`
-            - password?: DolphinDB password, default `'123456'`
-            - python?: set python session flag, default `false`
-            - streaming?: When this option is set, the WebSocket connection is only used for streaming data
-    */
-    connect({ url, autologin, username, password, python, streaming }?: {
-        url?: string;
-        autologin?: boolean;
-        username?: string;
-        password?: string;
-        python?: boolean;
-        streaming?: StreamingParams;
-    }): Promise<void>;
+    /** Establish a actual websocket connection to the DolphindB corresponding to the URL
+        After calling, it will ensure that it has been connected to the database (ensure that websocket.ReadyState is open), otherwise an error will be reported
+        this.autologin automatically log in when it is true */
+    connect(): Promise<void>;
     get_rpc_options({ urgent, secondary, async: _async, pickle, clear, api, compress, cancellable, priority, parallelism, root_id, limit, }?: {
         urgent?: boolean;
         /** API 提交的任务, secondary 必须为 false */
@@ -550,6 +542,7 @@ export declare class DDB {
     }): string;
     disconnect(): void;
     /** rpc through websocket (function/script/variable command)
+        When the DDB is not connected, the call will be automatically connected. When the connection is disconnected, the call will throw the Connectionerror
         - type: API 类型: 'script' | 'function' | 'variable'
         - options:
             - urgent?: 决定 `行为标识` 那一行字符串的取值（只适用于 script 和 function）
@@ -618,7 +611,7 @@ export declare class DDB {
     /** 解析服务端响应报文，返回去掉 header 的 data buf */
     parse_message(buf: Uint8Array, parse_object?: boolean): DdbMessage;
     /** Internal stream subscription method */
-    subscribe(): Promise<DdbTableObj>;
+    subscribe(): Promise<StreamingData>;
 }
 export interface DdbMessageListener {
     (message: DdbMessage, _this: DDB): any;
@@ -635,5 +628,5 @@ export interface DdbErrorMessage {
     type: 'error';
     data: Error;
 }
-export declare type DdbMessage = DdbPrintMessage | DdbObjectMessage | DdbErrorMessage;
+export type DdbMessage = DdbPrintMessage | DdbObjectMessage | DdbErrorMessage;
 export declare let ddb: DDB;