Big update!Announcing Socket for GitHub 1.0. Learn more
Log in


Package Overview
File Explorer

Advanced tools


Simple database function


Version published
Weekly downloads
decreased by-88.24%

Weekly downloads



dolphin-database JavaScript API


npm version npm downloads

English | 中文


dolphin-database JavaScript API is a JavaScript library that encapsulates the ability to operate the dolphin-database database, such as: connecting to the database, executing scripts, calling functions, uploading variables, etc.


  • Communicate with dolphin-database database using WebSocket, exchange data in binary format
  • 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


# 1. Install the latest version of Node.js and browser on the machine # 2. Create a new project (skip this step if you already have a project) mkdir dolphin-database-example cd dolphin-database-example npm init --yes # Open the package.json file with an editor, add the line "type": "module", below "main": "./index.js", # This enables the use of ECMAScript modules, and in the code behind you can use import { DDB } from 'dolphin-database' to import npm packages # 3. Install npm packages in your project npm install dolphin-database


0. Initialize and connect to dolphin-database

import { DDB } from 'dolphin-database' // The import method for existing projects using CommonJS modules is const { DDB } = require('dolphin-database') // Use in browser: import { DDB } form 'dolphin-database/browser.js' // Create a database object and initialize the WebSocket URL let ddb = new DDB('ws://') // Establish a WebSocket connection to dolphin-database (requires dolphin-database database version at least 1.30.16 or 2.00.4) await ddb.connect()
DDB options
let ddb = new DDB('ws://') // Encrypt with HTTPS let ddbsecure = new DDB('wss://', { // Whether to log in automatically after establishing a connection, default `true` autologin: true, // dolphin-database username, default `'admin'` username: 'admin', // dolphin-database password, default `'123456'` password: '123456', // set python session flag, default `false` python: false })

1. Call Functions

import { DdbInt } from 'dolphin-database' const result = await'add', [new DdbInt(1), new DdbInt(1)]) // TypeScript: const result = await<DdbInt>('add', [new DdbInt(1), new DdbInt(1)]) console.log(result.value === 2) // true
The dolphin-database JavaScript API uses DdbObj objects to represent data types in dolphin-database

In the above example, two parameters 1 (corresponding to the int type in dolphin-database) are uploaded to the dolphin-database database as parameters of the add function, then the result of the function call is received.

<DdbInt> is used by TypeScript to infer the type of the return value

  • result is a DdbInt, which is also a DdbObj<number>
  • result.form is a DdbForm.scalar
  • result.type is a
  • result.value is native number in JavaScript (the value range and precision of int can be accurately represented by JavaScript number)
/** Can represent all data types in dolphin-database databases */ class DdbObj <T extends DdbValue = DdbValue> { /** is it little endian */ le: boolean /** data form */ form: DdbForm /** data type */ type: DdbType /** consumed length in buf parsed */ length: number /** table name / column name */ name?: string /** Lowest dimension - vector: rows = n, cols = 1 - pair: rows = 2, cols = 1 - matrix: rows = n, cols = m - set: the same as vector - dict: include keys, values vector - table: the same as matrix */ rows?: number /** 2nd dimension */ cols?: number /** the actual data. Different DdbForm, DdbType use different types in DdbValue to represent actual data */ value: T /** raw binary data, only top-level objects generated by parse_message when parse_object is false have this attribute */ buffer?: Uint8Array constructor (data: Partial<DdbObj> & { form: DdbForm, type: DdbType, length: number }) { Object.assign(this, data) } } class DdbInt extends DdbObj<number> { constructor (value: number) { super({ form: DdbForm.scalar, type:, length: 4, value }) } } // ... There are also many utility classes, such as DdbString, DdbLong, DdbDouble, DdbVectorDouble, DdbVectorAny, etc. type DdbValue = null | boolean | number | [number, number] | bigint | string | string[] | Uint8Array | Int16Array | Int32Array | Float32Array | Float64Array | BigInt64Array | Uint8Array[] | DdbObj[] | DdbFunctionDefValue | DdbSymbolExtendedValue enum DdbForm { scalar = 0, vector = 1, pair = 2, matrix = 3, set = 4, dict = 5, table = 6, chart = 7, chunk = 8, } enum DdbType { void = 0, bool = 1, char = 2, short = 3, int = 4, long = 5, // ... timestamp = 12, // ... double = 16, symbol = 17, string = 18, // ... }
If there is no shortcut class, you can also specify form and type to manually create a DdbObj object
// Created by the DdbDateTime shortcut class new DdbDateTime(1644573600) // Equivalent to manually creating an object of form = scalar, type = datetime through DdbObj const obj = new DdbObj({ form: DdbForm.scalar, type: DdbType.datetime, value: 1644573600, length: 0 }) // The corresponding type and value of value in js can refer to the result returned by ddb.eval (see the `eval` method declaration below) const obj = await ddb.eval('2022.02.11 10:00:00') console.log(obj.form === DdbForm.scalar) console.log(obj.type === DdbType.datetime) console.log(obj.value) // Another example is to create a set // refer to ddb.eval // const obj = await ddb.eval('set([1, 2, 3])') // console.log(obj.value) const obj = new DdbObj({ form: DdbForm.set, type:, value: Int32Array.of(1, 2, 3), length: 0 }) // It's easier to use shortcut classes const obj = new DdbSetInt( new Set([1, 2, 3]) )
NULL object in the form of scalar, the value corresponding to DdbObj is null in JavaScript
;(await ddb.eval('double()')).value === null // create NULL object new DdbInt(null) new DdbDouble(null)
call Method Declaration
async call <T extends DdbObj> ( /** function name */ func: string, /** function arguments (The incoming native string and boolean will be automatically converted to DdbObj<string> and DdbObj<boolean>) */ args?: (DdbObj | string | boolean)[] = [ ], /** calling options */ options?: { /** Urgent flag. Use urgent worker to execute to prevent being blocked by other jobs */ urgent?: boolean /** When the node alias is set, the function is sent to the corresponding node in the cluster for execution (using the rpc method in dolphin-database) */ node?: string /** When setting multiple node aliases, send them to the corresponding multiple nodes in the cluster for execution (using the pnodeRun method in dolphin-database) */ nodes?: string[] /** It must be passed when setting the node parameter, the function type needs to be specified, and it is not passed in other cases */ func_type?: DdbFunctionType /** It may be passed when setting the nodes parameter, otherwise may not be passed */ add_node_alias?: boolean } = { } ): Promise<T>

2. Execute Script

const result = await ddb.eval( 'def foo (a, b) {\n' + ' return a + b\n' + '}\n' + 'foo(1l, 1l)\n' ) // TypeScript: // import type { DdbLong } from 'dolphin-database' // const result = await ddb.eval<DdbLong>(...) console.log(result.value === 2n) // true

In the above example, a script is uploaded through a string to the dolphin-database database for execution, and the execution result of the last statement foo(1l, 1l) is received.

<DdbLong> is used by TypeScript to infer the type of the return value

  • result is a DdbLong, which is also a DdbObj<bigint>
  • result.form is DdbForm.scalar
  • result.type is DdbType.long
  • result.value is the native bigint in JavaScript (the precision of long cannot be accurately represented by JavaScript number, but it can be represented by bigint)

As long as the WebSocket connection is not disconnected, the custom function foo will always exist in the subsequent session and can be reused, for example, you can use await<DdbInt>('foo', [new DdbInt(1), new DdbInt(1)]) to call this custom function

eval Method Declaration
async eval <T extends DdbObj> ( /** the script to execute */ script: string, /** calling options */ options: { /** Urgent flag. Use urgent worker to execute to prevent being blocked by other jobs */ urgent?: boolean } = { } ): Promise<T>

3. Upload Variables

import { DdbVectorDouble } from 'dolphin-database' let a = new Array(10000) a.fill(1.0) ddb.upload(['bar1', 'bar2'], [new DdbVectorDouble(a), new DdbVectorDouble(a)])

In the above example, two variables bar1, bar2 are uploaded, and the variable value is a double vector of length 10000

As long as the WebSocket connection is not disconnected, the variables bar1, bar2 will always exist in the subsequent session and can be reused

upload Method Declaration
async upload ( /** variable names */ vars: string[], /** variable values */ args: (DdbObj | string | boolean)[] ): Promise<void>

Some Examples

import { nulls, DdbInt, timestamp2str, DdbVectorSymbol, DdbTable, DdbVectorDouble } from 'dolphin-database' // Format timestamp in dolphin-database as string timestamp2str( ( await'now', [false]) // TypeScript: await<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' )


What is dolphin-database?

security holding package

Is dolphin-database popular?

The npm package dolphin-database receives a total of 2 weekly downloads. As such, dolphin-database popularity was classified as not popular.

Is dolphin-database well maintained?

We found that dolphin-database demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.It has 0 open source maintainers collaborating on the project.

Last updated on 29 Jul 2022


Subscribe to our newsletter

Get open source security insights delivered straight into your inbox. Be the first to learn about new features and product updates.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc