datascript-query-builder
Datascript query builder
Query Builder based on FeatherJS query syntax
This syntax is inspired by MongoDB query syntax
Design
This Query builder consists of the following:
- QueryBuilder
- Datoms
- Entity
- Pull
- Query
- Result
Datoms
is used to access entity data directly (via index). We use it to find all ids for a given Entity class. Entity
is used to access entity data directly. Pull
can use the Pull one and Pull many APIs to retrieve specific Entity attribute data for one or more entities (by Id).
Query
is a general purpose query, used for finding Entity data that match specific criteria/constraints (ie. predicates etc.).
The QueryBuilder
is a facade to all the different query variants.
entities(params)
byId(params)
query(params, options)
Result
is used to pre-process a query result from datascript/datomic DB.
A result is typically in the form: [['kris', 32]]
or [['name', 'kris', 'age', 32]]
however, we would often like it in JSON map form, like {name: 'kris', 'age': 32}
.
Result
is aimed to facilitate this enrichment and also pagination (limiting window/size of results returned) and sorting.
Usage
In package.json
"dqb": "datascript-query-builder"
Alternatively clone this repo and npm link
it locally when "hacking".
API usage:
; // first 10 entities older than 32 years, sorted by namevar query = age: $gt: 32 $limit: 10 $sort: name: 1; // Create Datalog, ie Datascript/Datomic query from FeatherJS query Object// Search :person entities only...var result = 'person' query; // prepare result using special pagination params ($limit, ...)return result;
More usage examples
var qb = 'person' options;
The Datascript Query builder was initially built for use in feathers-datascript, a FeathersJS compatible DB driver/adapter.
Query :person entities matching criteria
// Query person entities matching criteriavar q1 = age: $gt: 32 'last-name': 'Johnson';var datalogQuery = qb;var result = connd;
Pull :person entity 27
// Pull :person entity 27var personPull = qb;var params = $skip: 20 $limit: 20;var data = connd;
Fetch all :person entities via index
// Fetch all :person entities via index// See: http://augustl.com/blog/2013/datomic_direct_index_lookup/var datomsQuery = qb;var entities = connd;
Get entity by lookup ref
// Get entity by lookup ref: emailvar lookupRef = qb;var person = connd;
Development/Contribution
This is still early alpha. Please help out ;)
Write the code in src
. Run npm run build
to compile the source into a distributable format.
Put unit tests in test/unit
. The npm test
command runs the tests using Node.
npm Scripts
npm test
- Lint the library and tests, then run the unit testsnpm run lint
- Lint the source and unit testsnpm run watch
- Continuously run the unit tests as you make changes to the source and test files themselvesnpm run test-browser
- Build the library for use with the browser spec runner. Changes to the source will cause the runner to automatically refresh.npm run build
- Lint then build the librarynpm run coverage
- Generate a coverage report
Browser Tests
The browser spec runner
can be opened in a browser to run your tests. For it to work, you must first run npm run test-browser
. This
will set up a watch task that will automatically refresh the tests when your scripts, or the tests, change.