Home Reference Source Repository


A JavaScript client for GoshawkDB that works in node or the browser.

Dev only links:

Notes for getting Started

Run a GoshawkDB server with the config found in example/env. See the goshawkdb documentation.

When running in the browser, you currently need to import the certificates for your user. You can test that you've done this correctly by going to https://localhost:7895/ws. If it's working, it will say 'GoshawkDB Server version dev. Websocket available at /ws'.

To see the web example

npm run start

And navigate to http://localhost:8080/example/

The specific example code assumes that your database has a root object with two references to other objects.

To see the node example

node example/node-example.js


In Node

Import the GoshawkDB client

npm install --save goshawkdb

When running in node, I suggest the following in your code:

// Doesn't log at debug level as it's pretty noisy.  I'll need a proper logging solution soon...
global.console.debug = () => {}
// global.console.debug = global.console.log

// Make console.log of objects use colours.  Pretty
if (process.stdout.isTTY) {
    require('util').inspect.defaultOptions.colors = true

Get a goshawkdb reference and open a connection:

const goshawkdb = require('goshawkdb')

// These will need to be for a user that your goshawkdb configuration allows.
// Check the .pem file you created for that user.
const connectionOptions = {
    rejectUnauthorized: false,
    cert: `-----BEGIN CERTIFICATE-----
    key: `-----BEGIN EC PRIVATE KEY-----

goshawkdb.connect("wss://localhost:7895/ws", connectionOptions).then((connection) => {

    // this is where your goshawkdb code goes


In the browser

The configuration of keys and certificates must be done in whatever way your browser and operating system support.

Check that it has worked by navigating to https://localhost:7895/. If it's working, it will say 'GoshawkDB Server version dev. Websocket available at /ws'.

Include the client:

<script type="text/javascript" src="goshawkdb.browser.js"></script>

The file goshawkdb.browser.js is located in the dist subfolder of this module. It is regenerated on an npm build.

Now include your code, e.g.

goshawksb.connect("wss://localhost:7895/ws").then((connection) => {

    // this is where your goshawkdb code goes


Connection API

A connection allows you to submit transactions. Only one transaction is ever active at a time, calling transact while another transaction is active will cause your new transaction to be queued.

const promiseOfSomething = connection.transact((txn) => {

    // transaction code

    return something

Transaction API

NOTE: code submitted to .transact may be run by the system multiple times. Avoid making side effecting changes from inside a transaction. The goshawksb library uses exceptions to stop execution when there is a cache miss and it needs to request values from the server. If you use try catch around transaction methods and you want this behaviour to work, you will need to rethrow any exceptions with a name of TransactionRetryNeeded that you inadvertantly catch.

Inside a transaction you can access references to the configured root objects:

const rootRef = txn.roots['myRoot']

You can read the value and references of an object via a reference to that object.

const {value, refs} = txn.read(rootRef)

Values are ArrayBuffers while refs is an array of Reference ojects.

To write to an object you call txn.write. This example code loads the first reference from the root object (assuming it refers to some object), then sets the value and adds a reference back to the root object.

const otherObjRef = refs[0]
const otherRefs = txn.read(otherObjRef).refs
txn.write(otherObjRef, Buffer.from("hello"), otherRefs.concat(rootRef))

Values can be buffers (in node), typed arrays or arraybuffers.

You can create an object too with

const newRef = txn.create(Buffer.from("thing"), [])

If you want to be notified when something changes, you can create a transaction that reads the values you're interested in and then calls txn.retry(). This will cause the transaction to stop processing until the values change, at which point the transaction will be run again.

If you want to check that references point to the same object, you can do this with if (ref.sameReferent(otherRef)).