mongodb-expressions/README.md

MongoDB expressions for fire.js

#mongodb-expressions
[![Build Status](https://secure.travis-ci.org/firebaseco/mongodb-expressions.png)](http://travis-ci.org/firebaseco/mongodb-expressions)

The official [MongoDB](http://www.mongodb.org) expressions for [fire.js](https://github.com/firejs/fire)
***

## @Mongo.Insert

Inserts a document in a MongoDB collection given in the hint. Returns the same document with the generated _id.

### Example

This example inserts a contact document into the contacts collection:
    
	{
		"@Mongo.Insert(contacts)": {
			email: "johan@firebase.co"
			firstName: "Johan",
			lastName: "Hernandez"
		}
	}
	
### Possible errors and solutions

#### Mongo.Insert requires a hint with the name of the collection
When you call Mongo.Insert you need to provide the name of the collection you want to insert to.

#### Mongo.Insert can only insert one document at the time
The input is an array, you can't insert arrays. It must be an object.

#### Mongo.Insert can not insert null documents
The input is null. You can't insert null into a collection.

#### Mongo.Insert can only insert object documents
The input is anything but an object. Numbers, Functions, Strings can not be inserted directly into a collection.

## @Mongo.Find

Retrieve documents from a collection given in the hint. Returns an array of matched documents by the criteria. If the input is null or @undefined or you don't provide a condition it will retrieve all the documents in the collection.

Mongo.Find accepts an input with the following attributes:

    
	{
		"conditions": <object, optional>,
		"fields": <array, optional>,
		"sort": <object, optional>,
		"limit": <Number, optional>,
		"skip": <Number, optional>
	}
    

### Input Attributes

#### conditions

An object with all the conditions to be used as criteria. [More info about MongoDB Queries](http://www.mongodb.org/display/DOCS/Advanced+Queries).

#### fields

An array with all the fields names to include in the results. It supports [dot notation](http://www.mongodb.org/display/DOCS/Dot+Notation+%28Reaching+into+Objects%29) so you can specify the embedded documents fields too.

#### sort

An object with all the sorting options. More info [here](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%7B%7Bsort%28%29%7D%7D) and [here](http://www.mongodb.org/display/DOCS/Querying#Querying-Sorting)

#### limit

It specifies a maximum number of results to return. [More info](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%7B%7Blimit%28%29%7D%7D).

#### skip

It specifies at which object the database should begin returning results
[More info](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%7B%7Bskip%28%29%7D%7D)

### Possible errors and solutions

#### Mongo.Find requires a hint with the name of the collection
When you call Mongo.Find you need to provide the name of the collection you want to query from.

#### Mongo.Find can not currently work with including and excluding fields
When you call Mongo.Find you can't use includingFields and excludingFields options at the same time, you can either use one of them or none of them. 

#### Mongo.Find input must be an object
#### Mongo.Find fields must be an array, @undefined or null
#### Mongo.Find conditions must be an object, @undefined or null
#### Mongo.Find sort must be an object, @undefined or null
#### Mongo.Find options must be an object, @undefined or null

## @Mongo.FindOne

Retrieve a single document from a collection given in the hint matched by criteria. If no document can be matched with by the criteria it will return null. If the input is null or @undefined or you don't provide a condition it will retrieve the first document in the collection.

Mongo.FindOne accepts an input with the following attributes:

    
	{
		"conditions": <object, optional>,
		"fields": <array, optional>,
		"sort": <object, optional>,
		"skip": <Number, optional>
	}
    

### Input Attributes

#### conditions

An object with all the conditions to be used as criteria. [More info about MongoDB Queries](http://www.mongodb.org/display/DOCS/Advanced+Queries).

#### fields

An array with all the fields names to include in the results. It supports [dot notation](http://www.mongodb.org/display/DOCS/Dot+Notation+%28Reaching+into+Objects%29) so you can specify the embedded documents fields too.

#### sort

An object with all the sorting options. More info [here](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%7B%7Bsort%28%29%7D%7D) and [here](http://www.mongodb.org/display/DOCS/Querying#Querying-Sorting)

#### skip

It specifies at which object the database should begin returning results
[More info](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-%7B%7Bskip%28%29%7D%7D)

### Possible errors and solutions

Same errors and solutions than @Mongo.Find


## @Mongo.Update

Updates documents from a collection given in the hint. Returns the count of affected rows. All updates are strict and will return either an error if they fail or the count of update rows if succeeded.

Mongo.Update accepts an input with the following attributes:
    
	{
		"conditions": <object>,
		"changes": <object>,
		"options": <object, optional>,
	}
    
### Input Attributes

#### conditions

An object with all the conditions to be used as criteria. [More info about MongoDB Queries](http://www.mongodb.org/display/DOCS/Advanced+Queries).

#### changes

An object with all the changes to perform. [More info about MongoDB udpates](http://www.mongodb.org/display/DOCS/Updating)

#### options

It specifies the options to use when updating. The more common options are multi and upsert.

##### multi

When set to true all matching documents are updated, not just the first.

##### upsert

When set to true Atomically inserts the document if no documents matched.


### Possible errors and solutions

#### Mongo.Update requires a hint with the name of the collection
When you call Mongo.Update you need to provide the name of the collection you want to update.

#### Mongo.Update input must be an object
#### Mongo.Update changes must be an object
#### Mongo.Update options must be an object, @undefined or null


## @Mongo.Remove

Remove documents from a collection given in the hint. Returns the count of affected rows. All updates are strict and will return either an error if they fail or the count of removed rows if succeeded.

Mongo.Remove accepts an input with a single attribute:
    
	{
		"conditions": <object>
	}
    
### Input Attributes

#### conditions

An object with all the conditions to be used as criteria when removing the documents. [More info about MongoDB Queries](http://www.mongodb.org/display/DOCS/Advanced+Queries).


### Possible errors and solutions

#### Mongo.Remove requires a hint with the name of the collection
When you call Mongo.Remove you need to provide the name of the collection you want to remove documents from.

#### Mongo.Remove input must be an object
#### Mongo.Remove conditions must be an object

## @Mongo.DropDatabase

Drops the current database.

### Testing Goodies

`mongodb-expressions` will automatically execute `@Mongo.DropDatabase` when the runtime is loaded in `NODE_ENV` `test`.

### Cloning the Repository

    git clone https://github.com/firebaseco/mongodb-expressions.git

### Tests

    make

### Contributors

* Johan (author). Email: *johan@firebase.co*

## License

Copyright (c) 2011 Firebase.co - [http://www.firebase.co](http://www.firebase.co)

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 NON-INFRINGEMENT. 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.