ONQL Node.js Driver

Official Node.js client for the ONQL database server.

Installation

From npm

npm install onql-client

From GitHub (latest main)

npm install github:ONQL/onqlclient-node

Pinned to a release tag

npm install "github:ONQL/onqlclient-node#v1.0.0"

Quick Start

const{ ONQLClient }=require('onql-client');(async()=>{constclient=awaitONQLClient.create({host: 'localhost',port: 5656});// Insert a single recordawaitclient.insert('mydb','users',{id: 'u1',name: 'John',age: 30});// Read via ONQL expressionconstadults=awaitclient.onql('mydb.users[age>18]');console.log(adults);// Update using a queryawaitclient.update('mydb','users',{age: 31},client.build('mydb.users[id=$1].id','u1'));// ...or using explicit idsawaitclient.delete('mydb','users','',{ids: ['u1']});awaitclient.close();})();

API Reference

ONQLClient.create(options)

Creates and returns a connected client instance.

Parameter	Type	Default	Description
options.host	string	"localhost"	Server hostname
options.port	number	5656	Server port
options.defaultTimeout	number	10	Default request timeout in seconds

client.sendRequest(keyword, payload, timeout?)

Sends a raw request frame and waits for the response.

client.close()

Closes the connection.

Direct ORM-style API

On top of raw sendRequest, the client exposes convenience methods for the common insert / update / delete / onql operations. Each one builds the standard payload envelope for you and unwraps the {error, data} response — throwing on a non-empty error, returning the decoded data otherwise.

db is passed explicitly to insert / update / delete. onql takes a fully-qualified ONQL expression (which already includes the db name), so no separate db argument is needed.

query arguments are ONQL expression strings, e.g. 'mydb.users[id="u1"].id' or 'mydb.orders[status="pending"]'. Use client.build(template, ...values) to substitute $1, $2, ... — strings get double-quoted, numbers/booleans are inlined verbatim.

await client.insert(db, table, data)

Insert a single record.

Parameter	Type	Description
db	string	Database name
table	string	Target table
data	object	A single record object (not an array)

awaitclient.insert('mydb','users',{id: 'u1',name: 'John',age: 30});

await client.update(db, table, data, query, opts?)

Update records matching query (or the explicit opts.ids).

Parameter	Type	Default	Description
db	string	—	Database name
table	string	—	Target table
data	object	—	Fields to update
query	string	—	ONQL query expression (e.g. mydb.users[id="u1"].id). Pass "" when using opts.ids.
opts.protopass	string	"default"	Proto-pass profile
opts.ids	string[]	[]	Explicit record IDs (alternative to query)

// Via ONQL queryawaitclient.update('mydb','users',{age: 31},client.build('mydb.users[id=$1].id','u1'));// Via explicit idsawaitclient.update('mydb','users',{age: 31},'',{ids: ['u1']});// With custom proto-passawaitclient.update('mydb','users',{active: false},client.build('mydb.users[id=$1].id','u1'),{protopass: 'admin'});

await client.delete(db, table, query, opts?)

Delete records matching query (or the explicit opts.ids). Same options as update.

awaitclient.delete('mydb','users',client.build('mydb.users[id=$1].id','u1'));awaitclient.delete('mydb','users','',{ids: ['u1']});

await client.onql(query, opts?)

Run a raw ONQL query. The server's {error, data} envelope is unwrapped.

Parameter	Type	Default	Description
query	string	—	ONQL expression (e.g. mydb.users[active="yes"])
opts.protopass	string	"default"	Proto-pass profile
opts.ctxkey	string	""	Context key
opts.ctxvalues	string[]	[]	Context values

constrows=awaitclient.onql('mydb.users[age>18]');// With $-placeholder interpolation:constbyName=awaitclient.onql(client.build('mydb.users[name=$1]','John'));

client.build(query, ...values)

Replace $1, $2, … placeholders with values. Strings are automatically double-quoted; numbers and booleans are inlined verbatim.

constq=client.build('mydb.users[name=$1 and age>$2]','John',18);// -> 'mydb.users[name="John" and age>18]'constrows=awaitclient.onql(q);

Protocol

The client communicates over TCP using a delimiter-based message format:

<request_id>\x1E<keyword>\x1E<payload>\x04

• \x1E — field delimiter
• \x04 — end-of-message marker

License

MIT