START.md

Getting Started With Kore

Getting started with Kore is very simple. As you know from the Architecture, each Kore node can be started with several options but the minimum startup is just a few lines.

const koredb = require('koredb')
const kore = koredb.node()
...

// Add a new record
kore.addRec('MyList', { a: 'new record' })

// Process incoming records
kore.addProcessor((err, recs, logname) => {...})

To start Kore with the options to save your logs to disk, connect to other nodes, set error handling functions and so on, simply provide an options object with any of the following parameters.

let options = {
    saveTo: <db folder to save logs>,
    connect: <host:port of other node>,
    listen: <port to listen for other nodes>,
    checkReq: <authentication hook fn>,
    authReq: <authentication hook fn>,
    errfn: <your replacement for console.error>,
    migrate: <migration function>,
    whoami: <uuid identifying node>,
}
const kore = koredb.node(options)

All the settings are optional and will depend on the configuration of your network of nodes.

Option	Use
saveTo	If set, persist data here
connect	If set, connect to this node to synchronize
listen	If set, starts a server on this port
checkReq	Authentication hook (see Concepts)
authReq	Authentication hook (see Concepts)
errfn	If set, will send messages here instead to console.error
migrate	Migration function (see Concepts)
whoami	Used as NODEID if set (see Concepts)

If saveTo and connect (or listen) are all not set this node will start and work but not save it's data and not synchronize with other nodes. So all the data will vanish when the node shut's down. This is called a 'hermit' node and is useful for testing and experimentation.

Processing Log Records

As we have seen in the introduction, there are actually two main patterns in log processing:

1. Records are updated by writing a new version of an existing record.
2. Records are updated by a 'command' that updates an existing record or set of records.

Kore supports either or both patterns or you can choose to process the records in the logs entirely on your own.

kore.addProcessor({ filter: { type: 'contact' }, gatheron: 'name' },
    (err, contacts, logname) => {
        // all contact objects merged on name available here
        // called each time they are updated
    }
)

kore.addProcessor({ filter: { type: 'contact' }, gatheron: 'name',
      commands: [ { type: 'rename' }, { type: 'delete' } ] },
    (err, contacts, logname, commandrec) => {
        // Called whenever a matching command found
        // with the current set of contacts.
        // Expects the contacts to be updated with
        // whatever the command is expected to do
        // Finally called with no commandrec when
        // all contact objects merged by name
        // called each time there is an update
    }
)

kore.addProcessor((err, recs, logname) => {
    // All log records available
    // here - no processing done
})

Browsing Your Data

As you gather data it is important and useful to be able to play around and explore with your data. Making ad-hoc queries of your data and trying out various scenarios is often very important.

The good news is that it is very simple to do this in Kore. Simply drop down into the node REPL and load your data and suddenly you have all the power of the entire javascript language at your disposal to slice, dice, and aggregate your data in any way you want.

node
> let kore = require('koredb')
> kore.browse('path/to/data/folder')
> koredata
  { errs: [],
    logs: {
    ...
    }
  }
>

Once you use kore.browse('path/to/data'), the global variable koredata is populated with a snapshot of the logs (and any errors it encountered during loading). From this point onward you can simply use javascript to map, filter, and perform any kind of complex query you can dream of using simple javascript.

And Finally

Now that you know how to use Kore - not too hard was it? - you can finish your tour with an understanding of some slightly advanced concepts.

• Advanced Concepts