goshawkdb
A JavaScript client for GoshawkDB that works in node or the browser.
Dev only links:
- Doc
- Explorer
- Script tag:
<script type="text/javascript" src="https://rawgit.com/goshawkdb/js-client/master/dist/goshawkdb.browser.js"></script>
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
Setup
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...globalconsole {}// global.console.debug = global.console.log // Make console.log of objects use colours. Prettyif processstdoutisTTY inspectdefaultOptionscolors = true
Get a goshawkdb
reference and open a connection:
const 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-----MIIBszCCAVmgAwIBAgIIUHgu22HZLJkwCgYIKoZIzj0EAwIwOjESMBAGA1UEChMJR29zaGF3a0RCMSQwIgYDVQQDExtDbHVzdGVyIENBIFJvb3QgQ2VydGlmaWNhdGUwIBcNMTYxMjE5MTEwMTE4WhgPMjIxNjEyMTkxMTAxMThaMBQxEjAQBgNVBAoTCUdvc2hhd2tEQjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABEBLPJry7JgUU4UFyycUho0Lut+/eHgo5pBrXP0gsdC52DX3A+dETyRSmilagFrnxxdEUFxEHVF/dMmX4liv14GjbTBrMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDAjAMBgNVHRMBAf8EAjAAMBkGA1UdDgQSBBCbGXFg2f4Hu4302AGGnOs+MBsGA1UdIwQUMBKAEI4ItnwgV5AGs2bJdVP5os4wCgYIKoZIzj0EAwIDSAAwRQIhANBON8j48On2jd/+sCzxhdFur/tJqc0CyKQIFXy3zgGmAiBr0VBtKK+OGBxA/QSlqGZGed+udOQ0qHYikBqGTwQfvQ==-----END CERTIFICATE-----` key: `-----BEGIN EC PRIVATE KEY-----MHcCAQEEIF3aJdsPnKsMxpPPa2RFx0R4oFGF4gXYHLsuL62v6L7+oAoGCCqGSM49AwEHoUQDQgAEQEs8mvLsmBRThQXLJxSGjQu63794eCjmkGtc/SCx0LnYNfcD50RPJFKaKVqAWufHF0RQXEQdUX90yZfiWK/XgQ==-----END EC PRIVATE KEY-----` goshawkdb
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:
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
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
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 = txnroots'myRoot'
You can read the value and references of an object via a reference to that object.
const value refs = txn
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 = refs0const otherRefs = txnrefstxn
Values can be buffers (in node), typed arrays or arraybuffers.
You can create an object too with
const newRef = txn
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))
.