JavaScript API

1.1. 在机器上安装最新版的 Node.js 及浏览器。

• windows: https://nodejs.org/en/download/prebuilt-installer/current
• linux: https://github.com/nodesource/distributions?tab=readme-ov-file#debian-and-ubuntu-based-distributions

1.2. （可选）使用以下命令创建新项目。如果已有项目，可跳过此步。

mkdir dolphindb-example
cd dolphindb-example
npm init --yes

1.3. 用编辑器打开 package.json 文件，在 "main": "./index.js" 下方加入一行 "type": "module", 这样能够启用 ECMAScript modules，在后面代码中可以使用 import { DDB } from 'dolphindb' 导入 npm 包。

1.4. 在项目中安装 npm 包。

npm install dolphindb

// 2.1 在浏览器环境中用下面的方法导入
import { DDB } from 'dolphindb/browser.js'

// 2.1 在 Node.js 环境中用下面的方法导入
// import { DDB } from 'dolphindb'
// 已有的使用 CommonJS 模块的项目的导入方法为 const { DDB } = await import('dolphindb')

// 2.2 使用 WebSocket URL 初始化连接到 DolphinDB 的实例（不建立实际的网络连接）
let ddb = new DDB('ws://127.0.0.1:8848')

// 使用 HTTPS 加密
// let ddb = new DDB('wss://dolphindb.com')

// 2.3 建立到 DolphinDB 的连接（要求 DolphinDB 数据库版本不低于 1.30.16 或 2.00.4）
await ddb.connect()

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 推断返回值的类型

/** 调用 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>

import { DdbInt } from 'dolphindb'

const result = await ddb.call('add', [new DdbInt(1), new DdbInt(1)])
// TypeScript: const result = await ddb.call<DdbInt>('add', [new DdbInt(1), new DdbInt(1)])

console.log(result.value === 2)  // true

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>

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.invoke<number>('foo', [1, 1]) 调用这个自定义函数

/** 执行 dolphindb 脚本，返回 js 原生对象或值（调用 DdbObj.data() 后的结果）*/
async execute <TResult = any> (
    /** 执行的脚本 */
    script: string, 
    
    /** 执行选项 */
    options?: {
        /** 紧急 flag，确保提交的脚本使用 urgent worker 处理，防止被其它作业阻塞 */
        urgent?: boolean
        /** listener?: 处理本次 rpc 期间的消息 (DdbMessage) */
        listener?: DdbMessageListener
    }
): Promise<TResult>

const result = await ddb.eval(
    'def foo (a, b) {\n' +
    '    return a + b\n' +
    '}\n' +
    'foo(1l, 1l)\n'
)

// TypeScript:
// import type { DdbLong } from 'dolphindb'
// const result = await ddb.eval<DdbLong>(...)

console.log(result.value === 2n)  // true

上面例子中，通过字符串上传了一段脚本到 DolphinDB 数据库执行，并接收最后一条语句 foo(1l, 1l) 执行结果 result

<DdbLong> 用于 TypeScript 推断返回值的类型

• result 是一个 DdbLong，也是 DdbObj<bigint>
• result.form 是 DdbForm.scalar
• result.type 是 DdbType.long
• result.value 是 JavaScript 中原生的 bigint (long 的精度不能用 JavaScript 的 number 准确表示，但可以用 bigint 表示)

/** 执行 dolphindb 脚本，返回 DdbObj 对象）*/
async eval <T extends DdbObj> (
    /** 执行的脚本 */
    script: string,
    
    /** 执行选项 */
    options: {
        /** 紧急 flag，确保提交的脚本使用 urgent worker 处理，防止被其它作业阻塞 */
        urgent?: boolean
    } = { }
): Promise<T>