@noggin/elastic-noggin-sdk

Elastic Noggin SDK

The Elastic Noggin SDK provides libraries to interact with Elastic Noggin Server - the technical platform underneath Noggin 2.0.

Getting started

The main usage is through the EnSrv class where you can read, write, query, and start processes on Elastic Noggin Server. Most methods return RxJS Observables which can be converted to a promise if you prefer.

For all the examples below you will need something like the following boilerplate to construct the EnSrv class.

import { EnSrv, EnoFactory } from '@noggin/elastic-noggin-sdk';

const SESSION_TOKEN = 'your-session-token';
const ENSRV_URL = 'your-regional-ensrv-end-point';
const NAMESPACE = 'your-system-namespace';

const enSrv = new EnSrv({
  enSrvUrl: ENSRV_URL,
  sessionToken: SESSION_TOKEN,
  namespace: NAMESPACE
});

Concepts and terminology

We've written down some of the concepts you're going to need to understand when working with Elastic Noggin Server and this SDK.

Elastic Noggin Objects (ENOs)

Elastic Noggin Server is essentially a feature rich distributed graph database. Everything is stored in the database as an immutable Elastic Noggin Object (ENO).

TIPs and SIDs

Each ENO has a Source-Id (SID) which acts as the unique primary key of the object-version. The SID is a SHA-256 of the contents of the object. An ENO includes a reference to it's previous version (known as the parent) meaning that the SID is actually a hash-chain.

A TIP on an ENO is the SID of the first version of that ENO. We use the TIP to refer to the object generally - without referring to a specific version.

Most of the time the TIPs will see will be SHA-256 hashes, but sometimes they will look like a human readable string. These are called "well-known-tips" and are hardcoded in Noggin's applications.

Type definitions

The ENO's meta data includes a reference to the type definition which the field data conforms to. The type definition is also an ENO, so you can just read it like any other ENO.

Branches

Branches in Elastic Noggin Server are kind of like branches in git. When you write an ENO you can write it to a branch. The main branch which the Noggin 2.0 application runs off of is "master". Everything else is just a branch off of that. Most of the time you should just use the master branch.

Some branches are validating and some are not. A validating branch means that all the ENOs in it were valid when they were persisted. The master branch for example is a validating branch. A non-validating branch means that the ENOs in it might not be valid. This is helpful as a staging area where you might have drafts etc. An invalid ENO must still be syntactically valid, but doesn't meet the type definition field constraints.

Like git, when you're happy with your branch you can "merge" it in to master. The merge is not atomic.

Reading an object

This is a simple example of reading an object from Elastic Noggin Server.

enSrv.read('my-example-object-tip').subscribe(
  eno => {
    console.log('Read object:', eno);
  },
  err => {
    console.err('Couldn\'t read object:', err);
  }
);

Creating an object

This is an example of creating and writing an object to Elastic Noggin Server. This SDK has an ENO factory class to make it easier.

const enoFactory = new EnoFactory('your-type-tip', 'your-security-policy-tip');
enoFactory.setField('your-field-tip', 'your-field-values-string-array');
const eno = enoFactory.makeEno();

enSrv.write(eno).subscribe(
  eno => {
    console.log('Wrote object:', eno);
  },
  err => {
    console.err('Couldn\'t write object:', err);
  }
);

Updating an object

This is an example of creating and writing an object to Elastic Noggin Server. First you need to retrieve the original object, then patch it, then write it.

enSrv.read('your-object-tip').pipe(
  switchMap(originalEno => {
    const enoFactory = new EnoFactory();
    enoFactory.setProtoToPatch(originalEno);
    enoFactory.setField('your-field-tip', 'your-new-field-values-string-array');
    const patchedEno = enoFactory.makeEno();
    return enSrv.write(patchedEno);
  })
).subscribe(
  patchedEno => {
    console.log('Wrote object:', patchedEno);
  },
  err => {
    console.err('Couldn\'t write object:', err);
  }
);

Deleting an object

This is an example of creating and writing an object to Elastic Noggin Server. This SDK has an ENO factory class to make it easier. ENO's are immutable, so deleting an object is actually just creating a new version of it which is marked as deleted.

enSrv.read('your-object-tip').pipe(
  switchMap(originalEno => {
    const enoFactory = new EnoFactory();
    enoFactory.setProtoToPatch(originalEno);
    enoFactory.setDeleted(true);
    const deletedEno = enoFactory.makeEno();
    return enSrv.write(deletedEno);
  })
).subscribe(
  deletedEno => {
    console.log('Deleted object:', deletedEno);
  },
  err => {
    console.err('Couldn\'t delete object:', err);
  }
);