calypso

A common query interface for data stores, featuring a SQL-like query language.

calypso

  • Use a SQL-like query language over any queryable data store.
  • Automatically map query results to models.
  • Protect against SQL injection with prepared statements.
  • Create your own driver for your favorite database or web service!

npm install calypso

You'll also need a driver. Available drivers:

  • MongoDB: https://github.com/kevinswiber/calypso-mongodb
  • Usergrid: https://github.com/kevinswiber/calypso-usergrid
  • LevelDB/LevelUP: https://github.com/kevinswiber/calypso-level
  • Memory: https://github.com/kevinswiber/calypso-memory
var calypso = require('calypso');
var Query = calypso.Query;
var UsergridDriver = require('calypso-usergrid');
 
var engine = calypso.configure({
  driver: UsergridDriver.create({
    orgName: 'kevinswiber',
    appName: 'sandbox'
  })
});
 
engine.build(function(errconnection) {
  var session = connection.createSession();
 
  var query = Query.of('books')
    .ql('select title, author as writer where author=@author')
    .params({ author: 'Stephen Hawking' });
 
  session.find(query, function(errbooks) {
    console.log(books);
  });
});
 
// Output: 
// [ { title: 'A Brief History of Time', writer: 'Stephen Hawking' } ] 
 

Takes a collection name or a constructor function that has been mapped. (See: Mappings)

Returns a Query instance.

Accepts Calypso Query Language as a string.

var query = Query.of('books')
  .ql('where title contains "breakfast"');

Add parameters to prepared statements. Parameters will be properly escaped to prevent SQL injection attacks.

var query = Query.of('books')
  .ql('where title contains @term')
  .params({ term: 'breakfast' });

Constructor functions can be assigned mappings. Calypso will automatically instantiate the object when receiving query results. Here's a quick Getting Started guide.

1. Require dependencies.

var calypso = require('calypso');
var Query = calypso.Query;
var UsergridDriver = require('usergrid-calypso');

2. Set up a constructor function that assigns properties to instances.

var Book = function() {
  this.title = null;
  this.writer = null;
};

3. Set up a mapping for the constructor.

var mapping = function(config) {
  config
    .of(Book)
    .at('books')
    .map('title')
    .map('writer', { to: 'author' })
};

Notice we're mapping Book#writer to the data store's author property.

4. Configure a new Calypso engine.

var engine = calypso.configure({
  driver: UsergridDriver.create({
    orgName: 'kevinswiber',
    appName: 'sandbox'
  }),
  mappings: [mapping]
});

5. Query based on the JavaScript properties.

engine.build(function(errconnection) {
  var session = connection.createSession();
 
  var query = Query.of(Book)
    .ql('where writer=@writer')
    .params({ writer: 'Stephen Hawking' });
 
  session.find(query, function(errbooks) {
    console.log(books);
  });
});

Output: [ { title: 'A Brief History of Time', writer: 'Stephen Hawking' } ]

Sessions are created by drivers. See the Usergrid Driver for more information: https://github.com/kevinswiber/calypso-usergrid

This method returns an array of results. It takes a query object and a callback in the form of function(err, results).

The query passed to this method is without fields or filters.

Example:

session.get(Query.of(Book), 1234, function(errbook) {
  console.log(book);
});

A repository can be used instead of sessions. They provide similar functionality to sessions, except they are tied to a particular constructor.

Example:

var calypso = require('calypso');
var Query = calypso.Query;
var RepositoryFactory = calypso.RepositoryFactory;
var UsergridDriver = require('calypso-usergrid');
 
var Book = function() {
  this.title = null;
  this.writer = null;
};
 
var bookMapping = function(config) {
  config
    .of(Book)
    .at('books')
    .map('title')
    .map('writer', { to: 'author' })
};
 
var engine = calypso.configure({
  driver: UsergridDriver.create({
    orgName: 'kevinswiber',
    appName: 'sandbox'
  }),
  mappings: [bookMapping]
});
 
engine.build(function(errconnection) {
  var session = connection.createSession();
 
  var factory = RepositoryFactory.create(session);
 
  var bookRepository = factory.of(Book);
 
  var id = 'd4d66224-f54e-11e2-9033-b1911fc0a0cc';
 
  bookRepository.get(id, function(errbook) {
    console.log(book);
  });
});
 

Output: [ { title: 'A Brief History of Time', writer: 'Stephen Hawking' } ]

The Calypso Query Language (CaQL) has support for field selection, field aliases, filters, and ordering.

See the full specification here: Calypso Query Language Specification

MIT