dolphindb 3.0.21 → 3.0.22

package/README.zh.md

@@ -49,7 +49,7 @@ https://www.npmjs.com/package/dolphindb
             await ddb.connect()
             
             console.log(
-                await ddb.eval('1 + 1')
+                await ddb.execute('1 + 1')
             )
         </script>
     </body>
@@ -127,7 +127,54 @@ let ddb = new DDB('ws://127.0.0.1:8848', {
 
 
 ### 调用函数
-#### 例子
+#### `invoke` 方法
+##### `invoke` 方法代码示例
+```ts
+const result = await ddb.invoke('add', [1, 1])
+// TypeScript: const result = await ddb.invoke<number>('add', [1, 1])
+
+console.log(result === 2)  // true
+```
+
+上面例子中，上传了两个参数 1 (对应 DolphinDB 中的 int 类型) 到 DolphinDB 数据库，作为 add 函数的参数，并接收函数调用的结果 result
+
+`<number>` 用于 TypeScript 推断返回值的类型
+
+##### `invoke` 方法声明
+```ts
+/** 调用 dolphindb 函数，传入 js 原生数组作为参数，返回 js 原生对象或值（调用 DdbObj.data() 后的结果）*/
+async invoke <TResult = any> (
+    /** 函数名 */
+    func: string, 
+    
+    /** `[ ]` 调用参数，可以是 js 原生数组 */
+    args?: any[], 
+    
+    /** 调用选项 */
+    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
+        
+        /** 处理本次 rpc 期间的消息 (DdbMessage) */
+        listener?: DdbMessageListener
+    } = { }
+): Promise<TResult>
+```
+
+#### `call` 方法
+##### `call` 方法代码示例
 ```ts
 import { DdbInt } from 'dolphindb'
 
@@ -137,7 +184,7 @@ const result = await ddb.call('add', [new DdbInt(1), new DdbInt(1)])
 console.log(result.value === 2)  // true
 ```
 
-##### 用 DdbObj 对象来表示 DolphinDB 中的数据类型
+###### 用 DdbObj 对象来表示 DolphinDB 中的数据类型
 
 上面例子中，上传了两个参数 1 (对应 DolphinDB 中的 int 类型) 到 DolphinDB 数据库，作为 add 函数的参数，并接收函数调用的结果 result
 
@@ -244,7 +291,7 @@ enum DdbType {
 }
 ```
 
-##### 无快捷类的类型
+###### 无快捷类的类型
 
 对于没有快捷类的类型，可指定 form 和 type 手动创建 DdbObj 对象
 
@@ -284,7 +331,7 @@ const obj = new DdbSetInt(
 )
 ```
 
-#### scalar 形式的 NULL 对象
+###### scalar 形式的 NULL 对象
 
 scalar 形式的 NULL 对象，其对应 DdbObj 的 value 为 JavaScript 中的 null：
 
@@ -296,8 +343,7 @@ new DdbInt(null)
 new DdbDouble(null)
 ```
 
-
-#### `call` 方法声明
+##### `call` 方法声明
 ```ts
 async call <T extends DdbObj> (
     /** 函数名 */
@@ -326,9 +372,50 @@ async call <T extends DdbObj> (
 ): Promise<T>
 ```
 
-
 ### 执行脚本
-#### 例子
+#### `execute` 方法
+##### `execute` 方法代码示例
+```ts
+const result = await ddb.execute(
+    'def foo (a, b) {\n' +
+    '    return a + b\n' +
+    '}\n' +
+    'foo(1l, 1l)\n'
+)
+
+// TypeScript:
+// const result = await ddb.execute<bigint>(...)
+
+console.log(result.value === 2n)  // true
+```
+
+上面例子中，通过字符串上传了一段脚本到 DolphinDB 数据库执行，并接收最后一条语句 `foo(1l, 1l)` 执行结果 result
+
+`<bigint>` 用于 TypeScript 推断返回值的类型
+
+- result 是一个 `bigint`
+
+只要 WebSocket 连接不断开，在后续的会话中 `foo` 这个自定义函数会一直存在，可复用，比如后续通过 `await ddb.call<DdbInt>('foo', [new DdbInt(1), new DdbInt(1)])` 调用这个自定义函数
+
+##### `execute` 方法声明
+```ts
+/** 执行 dolphindb 脚本，返回 js 原生对象或值（调用 DdbObj.data() 后的结果）*/
+async execute <TResult = any> (
+    /** 执行的脚本 */
+    script: string, 
+    
+    /** 执行选项 */
+    options?: {
+        /** 紧急 flag，确保提交的脚本使用 urgent worker 处理，防止被其它作业阻塞 */
+        urgent?: boolean
+        /** listener?: 处理本次 rpc 期间的消息 (DdbMessage) */
+        listener?: DdbMessageListener
+    }
+): Promise<TResult>
+```
+
+#### `eval` 方法
+##### `eval` 方法代码示例
 ```ts
 const result = await ddb.eval(
     'def foo (a, b) {\n' +
@@ -353,10 +440,9 @@ console.log(result.value === 2n)  // true
 - 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` 方法声明
+##### `eval` 方法声明
 ```ts
+/** 执行 dolphindb 脚本，返回 DdbObj 对象）*/
 async eval <T extends DdbObj> (
     /** 执行的脚本 */
     script: string,
@@ -369,7 +455,6 @@ async eval <T extends DdbObj> (
 ): Promise<T>
 ```
 
-
 ### 上传变量
 #### 例子
 ```ts

package/browser.js

@@ -1876,9 +1876,7 @@ export function converts(type, value, rows, le) {
             case DdbType.decimal64:
             case DdbType.decimal128: {
                 const { scale, data } = value;
-                // todo: 用 Array.prototype.map.call 时对 BigInt128Array 这个代理对象无效？为什么只能通过下标访问？
-                return seq(rows, i => {
-                    const x = data[i];
+                return Array.prototype.map.call(data, (x) => {
                     if (is_decimal_null_value(type, x))
                         return '';
                     const s = String(x < 0 ? -x : x).padStart(scale, '0');
@@ -3206,6 +3204,14 @@ export class BigInt128Array {
                     return true;
                 }
                 return Reflect.set(target, key, value);
+            },
+            has(target, key) {
+                if (typeof key === 'string') {
+                    const index = Number(key);
+                    if (Number.isInteger(index) && index >= 0 && index < target.length)
+                        return true;
+                }
+                return Reflect.has(target, key);
             }
         });
     }