README.md

datascript-mori

Wrapper for datascript interplay with mori

Why?

Datascript is greatful project - an immutable in-memory database and Datalog query engine in Clojure and ClojureScript. It is very useful for managing very big and complex application state in frontend application.

Datascript is written in ClojureScript. Also Datascript designed for using from ClojureScript, but it has JS dedicated API. However usage Datascript from JS has problems:

• functions for quering - q, pull, pull_many, index_range etc. - convert result of query into JS data structures(Array, Object). JS data structures is mutable data strutures with very bad API. Also when you use mutable data structures in React app, you can not use "pure render" optimisations. See more cases for immutability. datascript-mori open access for all Datascript API and some helpers.
• Datascript includes ClojureScript Runtime. It is very big amount of code includes extensive set of immutable data structures. However it is useless without mori. But when you're importing mori and Datascript, the size of your application will grow twice(because mori and Datascript are two separate packages for Javascript). datascript-mori join their codebase.

Setup

• (Recommended) Install from NPM

npm install datascript-mori

• Download latest release

Usage

• (Recommended) Using EcmaScript 2015 modules:

import {
    datascript, // This is contain datascript object
    mori,       // This is contain mori object
    helpers     // This is contain helpers for conversions from CLJS
} from 'datascript-mori';

const {
    core, // This is pure DataScript CLJS API without any conversions
    js    // This is DataScript JS API
} = datascript;

• Using CommonJS modules:

var datascript_mori = require('datascript-mori');

var mori = datascript_mori.mori;
var datascript_js = datascript_mori.datascript.js;
var datascript_core = datascript_mori.datascript.core;
var helpers = datascript_mori.helpers;

• (Not recommended) Using tag <script> in Browser:

<script src="datascript-mori.js">
   var mori = datascript_mori.mori;
   var datascript_js = datascript_mori.datascript.js;
   var datascript_core = datascript_mori.datascript.core;
   var helpers = datascript_mori.helpers;
</script>

API Overview

• datascript_mori.datascript.core - is a CLJS DataScript API. All functions accept CLJS data structures and return back CLJS data structures(i.e mori values). All names of these functions converts("munging") with symbols allowed in JS for function name. See mapping list.
• datascript_mori.datascript.js - is a JS DataScript API
• mori - is a mori object
• helpers - is a helpers functions for convert JS data structures to CLJS data structures and CLJS data structures to JS data structures. Also helpers contains functions for parsing Datalog queries - parse_query and parse_pull.

Examples

• combineJsAndCljsApi.spec.js - this example demonstrated how to combine JS API with CLJS call d.q() to get mori values
• onlyCljsApiUsage.spec.js - this example demonstrated how to use only CLJS API without any conversion(only mori.parse for parsing EDN string)

Roadmap

• Investigate Posh and include to datascript-mori support tx-pattern

Related projects

• Babel-plugin-datascript - Plugin for precompile static DataScript query to Mori structs and check them during compilation.
• Rx-DataScript - RxJS wrapper for DataScript.