dolphindb 2.0.801 → 2.0.901

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;
@@ -432,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;
@@ -444,8 +439,10 @@ 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: 40;
+export declare const winsize: 100000;
 export declare class ConnectionError extends Error {
     ddb: DDB;
     constructor(ddb: DDB);
@@ -614,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;
@@ -631,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;