#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": , "fields": , "sort": , "limit": , "skip": } ### 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": , "fields": , "sort": , "skip": } ### 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": , "changes": , "options": , } ### 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": } ### 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.