thinky

Thinky

JavaScript ORM for RethinkDB.
Note: Alpha release

Quick start

Install:

npm install thinky

Use

var thinky = require('thinky');
thinky.init({});

// Create a model
var Cat = thinky.createModel('Cat', {name: String}); 

// Create custom methods
Cat.define('hello', function() { console.log("Hello, I'm "+this.name) });

// Create a new object
kitty = new Cat({name: 'Kitty'});
kitty.hello(); // Log "Hello, I'm Kitty
kitty.save(function(err, result) {
    if (err) throw err;
    console.log("Kitty has been saved in the database");
})

Docs

Note: Work in progress.

Thinky

Thinky.init( options )

options (object): object with the fields

• host: RethinkDB host (default "localhost")
• port: RethinkDB port for client (default to 28015)
• db: default database (default to "test")
• poolMax: The maximum number of connections in the pool (default to 10)
• poolMin: The minimum number of connections in the pool (default to 1)
• enforce: represents if the schemas should be enforced or not. Its value can be:
  • an object with the 3 fields:
    • missing -- throw on missing fields -- default to false
    • extra -- throw if extra fields are provided -- default to false
    • type -- throw if the type is not the one expected -- default to true
  • a boolean that set all 3 parameters to the same value

Thinky.getOptions()

Returns all the options previously set.

Thinky.getOption( optionName )

Returns the value for optionName. Possible values:

• host: RethinkDB host
• port: RethinkDB port for client
• db: default database
• poolMax: The maximum number of connections in the pool
• poolMin: The minimum number of connections in the pool
• enforce: Boolean that represent if the schemas should be enforced or not

Thinky.setOptions( options )

Overwrite the options defined in options.

The argument options is an object that can have the following fields

• host: RethinkDB host (default "localhost")
• port: RethinkDB port for client (default to 28015)
• db: default database (default to "test")
• poolMax: The maximum number of connections in the pool (default to 10)
• poolMin: The minimum number of connections in the pool (default to 1)
• enforce: represents if the schemas should be enforced or not. Its value can be:
  • an object with the 3 fields:
    • missing -- throw on missing fields -- default to false
    • extra -- throw if extra fields are provided -- default to false
    • type -- throw if the type is not the one expected -- default to true
  • a boolean that set all 3 parameters to the same value

Setting a value to null will delete the value and the default value will be used.

Note: Changing the host/port/poolMax/poolMin will create a new pool (the previous one will be drained).
This behavior will be fixed when generic pool will be able to resize the pool at will (or when I'll fork it)

Thinky.disconnect()

Close all the connections.

Thinky.createModel( name, schema, settings )

Create a new model

• name: name of the model
• schema: An object which fields can map to the following value
  • String
  • Number
  • Boolean
  • Array with one type (like [String], [Number], [{name: String, age: Number}]
  • Object that contains a valid schema
  • {_type: String, enforce: { missing: boolean, type: boolean, extra: boolean}, default: value/function }
  • {_type: Number, enforce: { missing: boolean, type: boolean, extra: boolean}, default: value/function }
  • {_type: Boolean, enforce: { missing: <boolean_, type: boolean, extra: boolean}, default: value/function }
  • {_type: Array, schema: schema, enforce: { missing: boolean, type: boolean, extra: boolean}, default: value/function }
  • {_type: Object, schama: schema, enforce: { missing: boolean, type: boolean, extra: boolean}, default: value/function }
• settings (object): settings for the model
  • enforce: represents if the schemas should be enforced or not. Its value can be:
    • an object with the 3 fields:
      • missing -- throw on missing fields -- default to false
      • extra -- throw if extra fields are provided -- default to false
      • type -- throw if the type is not the one expected -- default to true
    • a boolean that set all 3 parameters to the same value

Note 1: the fields enforce and default are optional.
Note 2: the value of enforce is the lower one (thinky -> model -> field).
Note 3: if enforce is provided as an object, the three fields missing/extra/type have to be defined. This limitation will be lifted when more important issues will be solved.
Note 4: you currently cannot have a field named _type in your model. This limitation will be removed at some point.

Examples of valid schema:

{ name: String }
{ name: { _type: String } }
{ name: { _type: String, default: "Unknown name" } }
{ age: { _type: Number, default: function() { return Math.random()*100 } } }
{ name: {_type: String, enforce: { missing: false, extra: false, type: true } }, age: { _type: Number, enforce: { missing: false, extra: false, type: true } }
{ user: { name: String, age: Number }}
{ comments: [ {author: String, comment: String} ] }
{ comments: {_type: Array, schema: {author: String, comment: String} } }

Note: The settings to set a minimum/maximum of elements in an array is on the roadmap.

Model

Model.compile( name, schema, settings, thinky )

Internal method

Model.createBasedOnSchema( result, doc, originalDoc, enforce, prefix, schema )

Internal method

Model.checkType( result, doc, originalDoc, schema, key, type, typeOf, prefix, enforce )

Internal method

Model.define( key, method )

Define a method on the model that can be called by any instances of the model.

Model.setSchema( schema )

Change the schema -- Not tested (I think)

Model.getSettings( )

Return the settings of the model.

Model.getDocument( )

Return the document.

Model.getPrimaryKey( )

Return the primary key

Model.save( callback, overwrite )

Save the object in the database. Thinky will call insert or update depending on whether how the object was created.

overwrite: not implemented yet

Model.get( id or [ids], callback )

Retrieve one or more documents

Model.filter( filterFunction )

Retrieve document based on the filter.

Model.count( )

Return the number of element in the table of your model.

Model.mapReduce( filterFunction )

Not yet implemented

Document

Document.getDocument( )

Internal method?

Document.getModel( )

Return the model of the document.

Document.getSettings( )

Document.define( name, method )

Document.replace( newDoc ) Not implemented yet

All method of EventEmitter are available on Document. They do not pollute the document itself.

Internals

When you create a new object from a model, the object has the following chain of prototypes object -> DocumentObject -> Document -> model

Run the tests

mocha

Contribute

You are welcome to do a pull request.

TODO

• Write the docs
• Add more complex queries
• Update pool when poolMax/poolMin changes

About

Author: Michel Tu -- [e-mail] -- www.justonepixel.com

License

Copyright (c) 2013 Michel Tu [e-mail]

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.