README.md

level-fact-base

Store immutable "facts" in level and query them with datalog.

level-fact-base is inspired by Datomic. Also check out datascript.

Why "Facts"??

A fact is something that happened.

• E - Entity - an id that represents an entity i.e. "user10"
• A - Attribute - the attribute the fact is about i.e. "email"
• V - Value - the attribute value i.e. "some@email"
• T - Transaction - when this fact became true
• O - Assertion/Retraction - whether the fact was asserted or retracted

The power of facts

Using a fact based information model inherently provide these 3 benefits.

1 - Flexible data model

When you write data you don't need to think much about how it will be queried later. You simply assert attributes about an entity. Facts are not tightly coupled with structure.

2 - Built in, queryable history and auditing

Most databases only remember the last thing that was true. For example:

 - April 1 -
user10 : Set email to "old@email"

 - April 6 -
user10 : Set email to "new@email"

 - April 18 -
You    : What is user10's email address?
aDumbDB: "new@email"

You    : What was user10's email on April 3?
aDumbDB: "new@email"

But what you really want is this:

You     : What is user10's email address?
FactBase: "new@email", on April 6 it was set by user10

You     : What was user10's email on April 3?
FactBase: "old@email", on April 1 it was set by user10, but on April 6 it was changed to "new@email" by user10

3 - Easy to query with performant joins

Fact base joins are implicit, it simply matches binding variables and unions results. The database is fully indexed for you so you don't need to worry about primary keys or indexes.

For example in SQL:

SELECT
  c.id,
  c.text
FROM
  users u
  JOIN comment c ON c.userId = u.id
WHERE
  u.email = 'my@email'

The fact datalog equivalent:

[
  ['?uid', 'user_email'    , 'my@email'],
  ['?cid', 'comment_userId', '?uid'    ],
  ['?cid', 'comment_text'  , '?text'   ]
]
// implicitly joined on ?uid and ?cid

API

var Transactor = require('level-fact-base')

var db = new Level('db', {
  keyEncoding: require('charwise'),// or bytewise, or any codec for sorted arrays of flat json values
  valueEncoding: 'json'
})

// define a schema for attributes
// like datomic schema is stored and versioned inside the database
var schema = {
  user_name: {type: 'String'},
  user_email: {type: 'String'},
  comment_userId: {type: 'EntityID'}
  comment_text: {type: 'String'}
  // ...
}

var tr = Transactor(db, schema)

// like levelup, every asynchronous function either takes a callback or returns a promise
// i.e. a callback
tr.snap(function(err, fb){ ... })
// or return a Promise
var fb = await tr.snap()

Checkout example/index.js for a more complete example.

tr = Transactor(db, initSchema, nextId = randomUUID)

Initialize the fact-base and return a transactor (tr for short)

• db is any thing that exposes a levelup api.
• initSchema the current expected schema for the transactor to use. As part of starting up the transactor it will sync up the schema to match what you pass it.
• nextId a function to generate unique string ids. Defaults to crypto.randomUUID

tr.snap() -> fb

Asynchronously get the current snapshot of the database.

tr.asOf(txn) -> fb

Asynchronously get a given txn version of the database.

tr.transact(entities) -> fb

Assert facts and get the resulting new version of the database.

transact([
  {
    $e: '101', // the entity id
    email: 'my@email',
    name: 'bob',
    // This expands to:
    // ['101', 'email', 'my@email']
    // ['101', 'name' , 'bob'     ]
  }
], function(err, fb){
  // fb is the new fb version
})

// or
fb = await transact([..])

fb.q(tuples, binding, select) -> results

The main entry point for performing datalog queries. Anything that starts with '?' is a binding variable.

fb.q([[ '?uid', 'user_email'    , '?email' ],
      [ '?cid', 'comment_userId', '?uid'   ],
      [ '?cid', 'comment_text'  , '?text'  ]

      { email: 'my@email' }, // map of bindings i.e. bind ?email to 'my@email'

      [ 'cid', 'text' ], // select which result bindings we care about

      function(err, results){
        // results are
        // [
        //   {cid: '123', text: 'some comment about the post...'},
        //   {cid: '321', text: 'annother comment'},
        //   ...
        // ]
      })

// or
results = await fb.q([..], {..}, [..])

You may also pass filter functions as the values in a binding map. Bound functions should return a boolean and filter out facts that evalutate falsy.

function hasExclamation (text) {
  return text.includes('!')
}

fb.q([[ '?cid', 'comment_userId', '?uid'   ],
      [ '?cid', 'comment_text'  , '?text'  ]

      { text: hasExclamation }, // match comments on text value

      [ 'cid', 'text' ], // select which result bindings we care about

      function(err, results){
        // results are
        // [
        //   {cid: '456', text: 'wow!'},
        //   {cid: '654', text: 'super!'},
        //   ...
        // ]
      })

For more examples see test.js.

NOTE: To help prevent injection attacks, use bindings to pass in untrusted data so it's properly escaped.

fb.get($e) -> entity

A sugar function that simply gets all attributes an entity.

fb.get('101', function(err, user){

  // user is {$e: '101', name: 'bob', email: 'my@email'}

})

// or
user = await fb.get('101')

License

MIT