Queryable JS

Queryable - A tiny, single file database written in Javascript, that emulates a functional subset of mongodb commands. It works in both browser and server. The database itself is stored as a json string. Unlike mongo there are no collections; a separate db is simply returned by each call to open(). Essentially, queryable facilitates structured querying of an array of objects.

Examples

Some examples of using queryable.js in node.js:

var queryable = require( 'queryable' );

// There are multiple ways to open a db.
// The simplest is to provide a full path to where you want your database file.
var db = queryable.open( "~/code/mydata.db" );

// ..or you can simply name it, which will start an empty db with this name:
var db = queryable.open( "Database_Name" );

// You can load from a json object that is an Array of Objects.
var db = queryable.open( {db_name:"name",data: [{key:val,key2:val2},{key:val},...] } );

// insert any type of key:value pairs you want
db.insert( {key:"keys can be Anything", comment:"fields don't have to match"} );

// Like collections, many independent db can be open at the same time
var db2 = queryable.open( "~/another.db" );

// It handles any value types
db2.insert( {subarray:[1,2,'buckle',{'my':'shoe'}]} );

// find() works like Mongo; RegExp's are fine
var res = db.find( {key:/regex/} );

// SELECT * WHERE (age = 40);
var res = db.find( {age:40} );

// all rows where age is over 40
// supports: $gt, $lt, $gte, $lte, $ne, $exists
var res = db.find( {age: {'$gt':40}} );

// the first 10 rows where age is over 40 and 'name' exists, sorted by name
var res = db.find({age:{$gt:40},name:{'$exists':true}}).sort({name:1}).limit(10);

// find() returns db_result, which has a length property and rows[] array
// as well as chainable methods like: .sort(), .limit(), .skip(), ..
console.log( 'got ' + res.length + ' rows' );


/*
 * a real example - populate from string
 */
// literal data can be a string or an object
var json_string = '[
  {"name":"Cathy"},
  {"name":"Carol","sex":"f"},
  {"name":"John","sex":"m"},
  {"name":"Cornelius","sex":"m"}]';

var queryable = require('queryable');

var db = queryable.open({db_name:"MyDatabase",data:json_string});

// delete a row
db.remove({name:'Cathy'});

// get names that start with 'C'
db.find({name:/^C/}, function(res) {
  console.log( db.db_name + ' contains these names that start with C:' );
  res.rows.forEach(function(x){
    console.log(' ' + x.name);
  });
});

/* outputs:
MyDatabase contains these names that start with C:
 Carol
 Cornelius
*/

Callbacks work now too (finally):

  db.distinct('name',{age:{$lte:35}},function(res) {
    res.rows.forEach(function(row){
      console.log( row.name );
    });
  });

See the 'examples' folder for more examples of usage.

Install

To install using npm:

npm install queryable

To install in your project, appending to your project's package.json:

npm install queryable --save

To install using git:

~$ git clone https://github.com/gmn/queryable.git

Test

To run unit-tests:

npm test

API

The queryable.open() function

There are essentially 3 forms of open(): no args, a single string, a single object. The most concise way to specify what you want is to use a config object, and specify each param individually. Failing that, merely providing a fullpath string, where you want your database to live, is sufficient in most cases.

queryable.open()

• db_name = defaults to 'test.db' in node, 'queryable' in web browser
• db_dir = default is current working directory: (eg. /home/kooldude)
• db_path = concatenation of: (db_dir + db_name) (eg. /home/kooldude/test.db)

queryable.open(string)

• First it tries string as a fullpath; if file is found: db_name, db_dir, and db_path are set.
• If a file isn't found, it tries string as a directory where it will create the database using the default db_name.
• If it isn't a directory or an existing file, string is assumed to be a fullpath where the file will be saved to. db_path, db_dir, and db_name are set from that.

queryable.open(object)

If argument is an object, these configuration variable are looked for in it:

• db_name If none supplied, it either takes one from db_path or defaults to 'queryable' or 'test.db' in the browser or in node respectively.
• db_path The fullpath where the database lives. Irrelevant in the browser. The database file is written to db_path everytime save() is called, and read from it in open() if an existing file is discovered at the location.
• db_dir Defaults to current working directory if db_path or db_dir are not supplied.
• use_gzip Can manually specify file is of type gzip. This is useful for files lacking the '.gz' extension. Note: currently gzbz must be present for this to work.
• data If this is set, the database can be populated outright by an argument to data. data can be string or json. It must be in the form of an Array of Zero or More Objects of Any Kind.

Full List of Commands

Supported Methods

object	command	status	comment/example
queryable			the return of require('queryable')
	open();	implemented	returns db_object
	useGzip(boolean);	implemented	force use of gzip. Useful for gzipped files lacking '.gz' extension; defaults to false
db_object			the return of queryable.open()
	save()	implemented	writes to current system (either file-system or browser)
	insert(vals_obj)	implemented	inserts vals_obj onto end of table; if vals_obj is an array, will treat contents as array of objects and insert each, one at a time
	update(match, newval)	implemented	finds rows that match match and set to newval
	find(match, callback)	implemented	returns db_result unless callback is present, then db_result passed to it
	distinct(string,clause)	implemented	finds all rows, eliminates duplicate values of certain key. db.distinct('name') or db.distinct('name',{age:{$lt:35}})
	remove()	implemented	db.remove( {name:/[A-Z](.*)/} )
	get_json()	implemented	returns json string of entire db
	print(fmt)	implemented	spits out tabular json to stdout
	now()	implemented	returns Date().toISOString of the present moment; useful for date fields
	toDate(arg)	implemented	returns new Date(arg)
	count()	implemented	returns table length
db_result
	sort()	implemented
	limit(integer)	implemented	limits the result set to integer results
	skip(integer)	implemented	shaves off the first integer rows of the result set
	count()	implemented	returns length of result set
	getArray()	implemented
	get_json()	implemented
	print(fmt)	implemented	debug print to stdout

Query Operators

Name	Status	comment/example
$gt	implemented	db.find( {a:{$gt:5}} );
$gte	implemented	db.find( {a:{$gte:100}} );
$in	implemented	db.find( {a:{$in[3,5,7]}} );
$lt	implemented
$lte	implemented
$ne	implemented	Matches all values that are not equal to the value specified in the query db.find( {a:{$ne:2},b{$ne:3}} ); // select * from table where (a != 2) && (b != 3)
$nin	not impl
$or	implemented	db.find( {$or:[{n:1},{y:{$gte:3}}]} ) //return all results where (n == 1) or (y >= 3)
$and	not impl
$not	not impl
$nor	not impl
$exists	implemented	db.find( {name: {$exists:true} } ) // return all results where the name field exists
$type	not impl
$mod	no plans
$regex	no plans
$text	no plans
$where	no plans

Update Operators

Name	Status	comment/example
$inc	not impl	Increments the value of the field by the specified amount.
$mul	not impl	Multiplies the value of the field by the specified amount.
$rename	not impl	Renames a field.
$setOnInsert	not impl	Sets the value of a field upon document creation during an upsert. Has no effect on update operations that modify existing documents.
$set	implemented	Sets the value of a field in an existing document.
$unset	not impl	Removes the specified field from an existing document.
$min	not impl	Only updates if the existing field value is less than the specified value.
$max	not impl	Only updates if the existing field value is greater than the specified value.
$currentDate	kindof impl	Use db.now() instead for now

In the Works

1. Better documentation (still working on it); Website (not quite yet).

2. Feature Roadmap: which features will be implemented next, roughly in order.

• better documentation for open()
• callbacks
• [] .findOne()
• [] better documentation for update()
• [] $nin
• [] $and, $not, $nor
• [] $inc, $mul
• [] $unset
• [] $rename
• [] update().limit()
• [] remove().limit()
• [] $min, $max
• [] $currentDate (db.now() already accomplishes this, though could alias it to $currentDate)
• [] queryable.min.js
• [] cleanup

3. Sample projects built on queryable demonstrating features and functionality.

• Simple Browser Example (sourceode here)
• Arcane Vocabulary Tutor

License

(The MIT License)

Copyright 2014 Greg Naughton. All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contact

Mail: greg AT naughton DOT org for questions, comments, bugs