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, force )

Define a method on the model with the name key. This method can be called by any instances of the model, whether the instances were created before or after the definition of the method.

Note: If a method already exists with such name, an error will be thrown except if you pass force=true.
We still recommand not to overwrite a method since it may be an internal one and can trigger an undefined behavior.

Model.setSchema( schema )

Change the schema.

Note: When you change the schema, the instances previously created do not change. We do not keep a reference of all objects now. We may add an option to do it later.

Model.getSettings( )

Return the settings of the model.

Model.getPrimaryKey( )

Return the primary key of the model.

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

Retrieve one or more documents using their primary keys.

Model.getAll( value or [values], indexName, callback )

Retrieve one or more documents using a secondary index

Model.filter( filterFunction )

Retrieve document based on the filter.

Model.count( )

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

Document

Document.getDocument( )

Internal method

Document.getModel( )

Return the model of the document.

Document.getSettings( )

Return the settings of the document.

Document.definePrivate( name, method )

Define a method accessible through the key name.

The method will be accessible only by the document iself and not any other documents (including those in the same class).

Document.save( callback )

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

Document.merge( newDoc, replace __)

Merge newDoc in the document. If replace is set to true, the document will be replaced.

Note: The new document is checked agains the schema of the model.

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

Run the tests

mocha

Contribute

You are welcome to do a pull request.

TODO

• Write more docs
• Add events methods on Model
• Add more complex queries
• Do not drain the pool when poolMin/poolMax are changed

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.