immudb-node

immudb-node

Official immudb client for nodejs.

Contents

• Introduction
• Prerequisites
• Installation
• Supported Versions
• Quickstart
• Step by step guide
  • Creating a Client
  • User sessions
  • Creating a database
  • Setting the active database
  • Traditional read and write
  • Verified or Safe read and write
  • Multi-key read and write
  • Closing the client
• Contributing

Introduction

immudb-node implements a grpc immudb client. A minimalist API is exposed for applications while cryptographic verifications and state update protocol implementation are fully implemented by this client. Latest validated immudb state may be kept in the local filesystem when initialising the client with the rootPath option. Please read immudb research paper for details on how immutability is ensured by immudb.

Prerequisites

immudb-node assumes an already running immudb server. Running immudb is quite simple, please refer to the following link for downloading and running it: https://docs.immudb.io/quickstart.html

Installation

Just include immudb-node as a dependency in your project:

const ImmudbClient = require('immudb-node')

Supported Versions

immudb-node supports the latest immudb release.

Quickstart

Check out some examples

Testing

Create a .env file based on a .env.example in the project root and replace the /path/to/immudb/ with your local path to immudb.

You can use either of the following commands to check that all the unit tests pass:

• npm run test: automatically download the latest immudb release, run it and then run tests
• npm run test:dev: connect to an already running immudb on the host:port from the .env file on your machine and then run tests

Step by step guide

Creating a Client

The following code snippets shows how to create a client.

Using default configuration:

const config = {
  address: '127.0.0.1:3322',
  rootPath: '.',
}

ImmudbClient(config, (err, cl) => {
  if (err) {
    return console.log(err)
  }

  // Interact with the client.
})

User sessions

Use login and logout methods to initiate and terminate user sessions:

try {
  await cl.login({ username: 'usr1', password: 'pwd1' })

  // Interact with immudb using logged user.

  await cl.logout()
} catch (err) {
  console.log(err)
}

Or with callbacks

cl.login({ username: 'usr1', password: 'pwd1' }, (err, res) => {
  if (err) {
    return console.log(err)
  }

  // Interact with immudb using logged user.

  cl.logout(null, (err, res) => {
    if (err) {
      return console.log(err)
    })
    // Logged out.
})

Creating a database

Creating a new database is quite simple:

cl.createDatabase('db1')

Setting the active database

Specify the active database with:

cl.useDatabase('db1')

Traditional read and write

immudb provides read and write operations that behave as a traditional key-value store i.e. no cryptographic verification is done. These operations may be used when validating can be postponed:

let res = await cl.set({ key: 'key1', value: 'value1' })
console.log(res.index)

res = await cl.get({ key: 'key1' })
console.log(res.key, res.value, res.index)

Verified or Safe read and write

immudb provides built-in cryptographic verification for any entry. The client implements the mathematical validations while the application uses as a traditional read or write operation:

try {
  let res = await cl.verifiedSet({ key: 'key1', value: 'value1' })
  console.log(res.index)

  res = await cl.verifiedGet({ key: 'key1' })
  console.log(res.key, res.value, res.index)
} catch (err) {
  if (err.clientErr == cl.proofErr) {
    // Proof does not verify.
  }
  console.log(err)
}

Multi-key read and write

Transactional multi-key read and write operations are supported by immudb and immudb-node.

Atomic multi-key write (all entries are persisted or none):

  req = {
    keys: [{
      key: 'key1',
      value: 'value1'
    },{
      key: 'key2',
      value: 'value2'
    }]
  }
  res = await cl.setAll(req)

Atomic multi-key read (all entries are retrieved or none):

    req = {
      keys: [{
        key: 'key1',
      },{
        key: 'key2',
      }],
    }
    res = await cl.getAll(req)

Closing the client

To programatically close the connection with immudb server use the shutdown operation:

cl.shutdown()

Note: after shutdown, a new client needs to be created to establish a new connection.

Contributing

We welcome contributions. Feel free to join the team!

To report bugs or get help, use GitHub's issues.