mapql
v0.0.10
Published
A MongoDB inspired ES6 Map() query langauge.
Downloads
74
Maintainers
Readme
MapQL (WIP)
A MongoDB inspired ES6 Map() query language. -
This is a WIP; do NOT use in production yet! See TODO for more information.
Testing
Node:
You can test with node.js via npm test
.
Browser:
For local browser testing with karma run npm run-script local
or karma start tests/local.karma.js
to run tests with PhantomJS and/or any browsers you have access to.
Sauce Labs:
See karma-sauce-launcher and sauce.karma.js.
# See more about Open Source testing at https://saucelabs.com/open-source
$ export SAUCE_USERNAME=***** # Your Sauce Labs username.
$ export SAUCE_ACCESS_KEY=***** # Your Sauce Labs access key.
$ karma start tests/sauce.karma.js # npm run-script sauce
Browser Support
ES6 supported browsers:
<!-- MapQL() WITHOUT chain() support (es6)-->
<script src="./dist/MapQL.es6.js"></script>
<!-- MapQL() WITH chain() support (es6) -->
<script src="./dist/MapQL.es6.chainable.js"></script>
ES5 (babel transpiled):
<!-- MapQL() WITHOUT chain() support-->
<script src="./dist/MapQL.es5.js"></script>
<!-- MapQL() WITH chain() support (es6) -->
<script src="./dist/MapQL.es5.chainable.js"></script>
You can use unpkg to retrieve dist files.
#find(<Query>)
Search the MapQL()
with the supplied query operators. The result is a Cursor
with matching Document
objects. Entries that have an Object
as the value can be searched with dot notation
fields.
Dot notation
#find({ '<Field>.<Field>.<Field>': { <Query Operators> } });
Example:
// Cursor [ Document { _id: 'foo', value: { bar: { baz: 1 } } } ]
{Instance}.find({ 'bar.baz': { $eq: 1 } });
#findAsync(<Query Operators>)
The Promise
based version of #find()
. More information to come.
Cursor
The Cursor
class is an extended Array
containing Document
objects found with find()
, providing sort()
and limit()
methods along with the rest of the Array methods. Please note that calling limit()
BEFORE sort()
will limit the number of documents BEFORE sorting and vise versa.
#sort(<Sort>)
-- Returns results ordered according to a sort specification.
Specifies the order in which the query returns matching documents. Specify in the sort parameter the field or fields to sort by and a value of 1
or -1
to specify an ascending or descending sort respectively.
#limit(<Limit>)
-- Constrains the size of a cursor's result set.
Use the limit() method on a cursor to specify the maximum number of documents the cursor will return.
Document
The Document
class is an extended Object
containing the MapQL()
entry within Cursor
. The Document
consits of an _id
(entry key
) and a value
(entry value
).
// Cursor [ Document { _id: 'Foo', value: 'Bar' } ]
{Instance}.set('Foo', 'Bar')
Implemented Query Operators
Comparison
$eq -- Matches values that are equal to a specified value.
The $eq
operator matches documents where the value of a field equals (==
) the specified value. This is also the default find()
operator.
<value> OR { <field>: { $eq: <value> } }
The following examples query against MapQL
with the following documents:
{Instance}.set('foo1', 'bar');
{Instance}.set('foo2', { bar: 'baz' });
{Instance}.set('bar', 'foo3');
The following example queries the MapQL
instance to select all documents where the value equals { bar: 'baz' }
or bar
. If a Document
is added to the Cursor
by it's key value, Symbol(bykey)
will be true in the Document
.
// Cursor [ Document { _id: 'foo2', value: { bar: 'baz' } } ]
{Instance}.find({ bar: { $eq: 'baz' } });
// Cursor [ Document { _id: 'foo1', value: 'bar' } ]
{Instance}.find({ $eq: 'bar' });
/*
Cursor [
Document { _id: 'bar', value: 'foo3', [Symbol(bykey)]: true },
Document { _id: 'foo1', value: 'bar', [Symbol(bykey)]: false },
]
*/
{Instance}.find('bar');
$gt -- Matches values that are greater than a specified value.
The $gt
operator selects those documents where the value is greater than (>
) the specified value.
$gte -- Matches values that are greater than or equal to a specified value.
The $gte
operator selects the documents where the value of the field is greater than or equal to (>=
) the specified value.
$lt -- Matches values that are less than a specified value.
The $lt
operator selects the documents where the value of the field is less than (<
) the specified value.
$lte -- Matches values that are less than or equal to a specified value.
The $lte
operator selects the documents where the value of the field is less than or equal to (<=
) the specified value.
$ne -- Matches all values that are not equal to a specified value.
The $ne
operator selects the documents where the value of the field is not equal (!=
) to the specified value. This includes documents that do not contain the field.
$in -- Matches any of the values specified in an array.
The $in
operator selects the documents where the value of a field equals any value in the specified Array
.
$nin -- Matches none of the values specified in an array.
The $nin
operator selects the documents where the field value is not in the specified Array
or the field does not exist.
Logical
$or -- Joins query clauses with a logical OR returns all documents that match the conditions of either clause.
The $or
operator performs a logical OR operation on an Array
of two or more expressions
and selects the documents that satisfy at least one of the expressions
.
$and -- Joins query clauses with a logical AND returns all documents that match the conditions of both clauses.
The $and
operator performs a logical AND operation on an Array
of two or more expressions (e.g. expression1
, expression2
, etc.) and selects the documents that satisfy all the expressions in the Array
.
Element
$exists -- Matches documents that have the specified field.
When boolean
is true
, $exists
matches the documents that contain the field, including documents where the field value is null
. If boolean
is false
, the query returns only the documents that do not contain the field.
$type -- Selects documents if a field is of the specified type.
The $type
operator selects the documents where the value of the field is an instance of the specified data type. Querying by data type is useful when dealing with highly unstructured data where data types are not predictable.
Evaluation
$regex -- Selects documents where values match a specified regular expression.
Provides regular expression capabilities for pattern matching strings in queries. MapQL()
uses JavaScript regular expressions (RegExp).
$where -- Matches documents that satisfy a JavaScript expression.
Use the $where
operator to pass a JavaScript function to the query system. The $where
provides greater flexibility, but requires that the MapQL()
processes the function for each document. Reference the document in the function using either this
or as the first function argument
.
Array
$size -- Selects documents if the array field is a specified size.
The $size
operator matches any Array
with the number of elements specified by the argument.
Implemented Update Operators
Fields
$set -- Sets the value of a field in a document.
The $set
operator sets or replaces the value of a field with the specified value.
$inc -- Increments the value of the field by the specified amount.
The $inc operator increments a field by a specified value.
$mul -- Multiplies the value of the field by the specified amount.
Multiply the value of a field by a number.
$unset -- Removes the specified field from a document.
The $unset operator deletes a particular field.
Array
$pop -- Removes the first or last item of an array.
The $pop
operator removes the first or last element of an Array
. Pass $pop
a value of -1
to remove the first element of an Array
and 1
to remove the last element in an Array
.
Import/Export
Please note that importing and exporting data is highly experimental. This feature currently exports as json, so certain keys or references may not be supported.
As well, due to the way Symbol()
works, it's impossible to export any key/value pairs from Objects if the key is a Symbol. Any input on how to improve import/export
of Map()
would be greatly appreciated. Please see #5 for further information.
Current (known) supported data types:
- Primitives
- Boolean, Null, Undefined, Number, String, Symbol, Object
- Extended support
- Array, Function, Date, Map, Set, Buffer/Uint8Array, RegExp, NaN
- Experimental support
Buffer and Uint8Array are similar enough that browsers will attempt to convert a Buffer into a Uint8Array if the Buffer constructor is unavailable. In the unlikely event that nether are available, import() will then attempt to convert it to a normal Array with Array.from(). Typed arrays are tested with ArrayBuffer.isView(), this is an experimental (under tested) feature of MapQL. See TypedArray for more information about typed arrays.