level-fact-base
v2.0.0
Published
Store immutable "facts" and query them with datalog.
Downloads
28
Maintainers
Readme
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 trueO
- 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