Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

api cleanup and more README docs

  • Loading branch information...
commit 89403a05c89c8edc358b28ca4552ed4dcca195b5 1 parent 4f9308b
Nathan White nw authored
Showing with 268 additions and 80 deletions.
  1. +268 −76 README.md
  2. +0 −4 lib/storage.js
344 README.md
View
@@ -3,11 +3,11 @@ Mongoose: MongoDB utility library with ODM-like functionality
The goal of Mongoose is to provide a extremely simple interface for MongoDB.
-Goals
------
+Features
+---------
- Reduce the burden of dealing with nested callback from async operations.
- Provide a simple yet rich API.
-- Still have easy access to the database/collection.
+- Still have easy access to the native database/collection.
- Ability to model your data with custom interfaces.
Quick Start
@@ -37,95 +37,240 @@ With Mongoose:
Collection.find({}).each(function(doc){
// do something
});
-
-Mongoose buffers the connection to the database providing an easier to use API. Mongoose also adds some neat chaining features to allow for a more expressive and easier way of dealing with your data.
+
+Modeling Data with Mongoose:
-Query Promises
--------------
+
-Mongoose implements the promise pattern for queries. This assures the developer that execution happens in proper order.
- var promise = Collection.find();
- promise.gt({age : 20}).lt({age : 25}).limit(10); // promise commands are chainable.
+Documentation
+--------------
+
+### Mongoose
+
+Methods:
+
+- *configure(options)*
+ - connections
+ - activeStore
+ (str) Specify an activeStore within connections.
+ - activeStoreEnabled
+ (bool) default true. Allows for implicit binding of Models to Stores.
-Currently the Mongoose QueryPromise API is lazy. A query action is not performed until an 'action' method has been assigned.
+- *load(resource)*
+ Loads a file, if resource is a directory loads all files in directory.
+
+- *connect(uri)*
+ [format](http://www.mongodb.org/display/DOCS/Connections). If activeStoreEnabled, activeStore will be set to this connection.
+ returns Storage
-- Actions (each,count,first,one,get,execute,exec,run)
+- *get(model,[store])*
+ returns a model that uses the Storage. If store is not passed, activeStore is then attempted.
-In the case of 'each','first','one','get' they take two arguments. A callback, and an option to hydrate. It is important to note that all callbacks operate within the scope of the QueryPromise.
+- *noSchema(collection,[store])*
+ same as get but doesn't require a Model definition, binds directly to a collection.
-QueryPromises provide the following helper methods in addition to the query 'sugar' methods.
+- *close()*
+ closes all Storage connections.
-- result - sets a result value for the promise
-- partial - sets a partial result for a promise, handy for result sets using .each()
-- error - define an error
-- then - code you want to execute after the promise has been made. It takes 2 parameters. The first is your callback, second is an optional in case of errors.
+### Storage
-An example using each
+Properties:
- promise.each(function(doc){
- // do something
- this.partial(doc.title);
- }).then(function(titles){
- // titles is an array of the doc titles
- });
+- *loaded*
+ (bool) if connection established with Mongo.
+
+Methods:
+
+- *static(model)
+ Binds a model to the current Storage object.
-QueryPromise query helper methods.
+
+### Model
-**sort**,**limit**,**skip**,**hint**,**timeout**,**snapshot**,**explain**,
-**where**,**in**,**nin**,**ne**,**gt**,**gte**,**lt**,**lte**, **min**,**max**,**mod**,**all**,**size**,**exists**,**type**,**not**
-**inc**,**set**,**unset**,**push**,**pushAll**,**addToSet**,**pop**,**pull**,**pullAll**
+Properties:
+
+- *loaded*
+
+- *collectionName*
+
+- *store*
+
+- *collection*
+
+Methods:
+
+- *find()*
+
+- *update()*
+
+- *insert()*
+
+- *count()*
+
+- *distinct()*
+
+- *mapReduce()*
+
+- *remove()*
+
+- *save()*
+
+- *drop()*
+
+- *close()*
+
+- *halt()*
+
+- *clear()*
+
+- *resume()*
+
+### QueryPromise
+
+Properties:
+
+- *completed*
+
+Methods (Promise):
+
+- *result()*
+
+- *partial()*
+
+- *error()*
+
+- *then(func,errorCallback)*
+
+Methods (Query Actions):
+
+- *each(fn,hydrate)*
+
+- *first(fn,hydrate)*
+
+- *execute(fn)*
+
+- *run(fn)*
+
+Method (Query Sugar):
+
+- *sort()*
+
+- *limit()*
+
+- *skip()*
+
+- *hint()*
+
+- *timeout()*
+
+- *snapshot()*
+
+- *explain()*
+
+- *where()*
+
+- *in()*
+
+- *nin()*
+
+- *ne()*
+- *gt()*
+
+- *gte()*
+
+- *lt()*
+
+- *lte()*
+
+- *min()*
+
+- *max()*
+
+- *mod()*
+
+- *add()*
+
+- *size()*
+
+- *exists()*
+
+- *type()*
+
+- *not()*
+
+- *inc()*
+
+- *set()*
+
+- *unset()*
+
+- *push()*
+
+- *pushAll()*
+
+- *addToSet()*
+
+- *pop()*
+
+- *pull()*
+
+- *pullAll()*
+
+
+
+Mongoose buffers the connection to the database providing an easier to use API. Mongoose also adds some neat chaining features to allow for a more expressive and easier way of dealing with your data.
Models
-------
Mongoose allows you to define models for your data. Models provide an interface to your data.
- Model.define('User',{
-
- collection : 'test_user', // (optional) if not present uses the model name instead.
-
- // defines your data structure
- types: {
- _id : Object, // if not defined, Mongoose automatically defines for you.
- username: String,
- first : String,
- last : String,
- bio: {
- age: Number
- }
- },
-
- indexes : [
- 'username',
- 'bio.age',
- [['first'],['last']] // compound key indexes
- ],
-
- static : {}, // adds methods onto the Model.
- methods : {}, // adds methods to Model instances.
-
- setters: { // custom setters
- first: function(v){
- return v.toUpperCase();
- }
- },
-
- getters: { // custom getters
- username: function(v){
- return v.toUpperCase();
+ Model.define('User',{
+
+ collection : 'test_user', // (optional) if not present uses the model name instead.
+
+ // defines your data structure
+ types: {
+ _id : Object, // if not defined, Mongoose automatically defines for you.
+ username: String,
+ first : String,
+ last : String,
+ bio: {
+ age: Number
+ }
},
- legalDrinkingAge : function(){
- return (this.bio.age >= 21) ? true : false;
- },
+ indexes : [
+ 'username',
+ 'bio.age',
+ [['first'],['last']] // compound key indexes
+ ],
+
+ static : {}, // adds methods onto the Model.
+ methods : {}, // adds methods to Model instances.
- first_last : function(){ // custom getter that merges two getters together.
- return this.first + ' ' + this.last;
+ setters: { // custom setters
+ first: function(v){
+ return v.toUpperCase();
+ }
+ },
+
+ getters: { // custom getters
+ username: function(v){
+ return v.toUpperCase();
+ },
+
+ legalDrinkingAge : function(){
+ return (this.bio.age >= 21) ? true : false;
+ },
+
+ first_last : function(){ // custom getter that merges two getters together.
+ return this.first + ' ' + this.last;
+ }
}
- }
- });
+ });
All sections of a Mongoose Model definition allow nesting of arbitrary level. This allows for namespaces for methods within your model.
@@ -137,6 +282,8 @@ Once a model is defined. Your ready to use it with Mongoose.
user = new User({username : 'test', first : 'me', last : 'why', bio : { age : 100 }}); // create a new document.
user.save(); //save
+ user.first_last // returns 'ME why'
+ user.legalDrinkingAge // true
User.find()
@@ -171,6 +318,43 @@ In addition Mongoose has a featured we refer to as 'activeStore' This allows for
If 'activeStore' is not defined, it will be defined as soon as you connect(uri). If you want to disable this feature in the configuration object add 'activeStoreEnabled : false'.
+Query Promises
+-------------
+
+Mongoose implements the promise pattern for queries. This assures the developer that execution happens in proper order.
+
+ var promise = Collection.find();
+ promise.gt({age : 20}).lt({age : 25}).limit(10); // promise commands are chainable.
+
+Currently the Mongoose QueryPromise API is lazy. A query action is not performed until an 'action' method has been assigned.
+
+- Actions (each,count,first,one,get,execute,exec,run)
+
+In the case of 'each','first','one','get' they take two arguments. A callback, and an option to hydrate. It is important to note that all callbacks operate within the scope of the QueryPromise.
+
+QueryPromises provide the following helper methods in addition to the query 'sugar' methods.
+
+- result - sets a result value for the promise
+- partial - sets a partial result for a promise, handy for result sets using .each()
+- error - define an error
+- then - code you want to execute after the promise has been made. It takes 2 parameters. The first is your callback, second is an optional in case of errors.
+
+An example using each
+
+ promise.each(function(doc){
+ // do something
+ this.partial(doc.title);
+ }).then(function(titles){
+ // titles is an array of the doc titles
+ });
+
+QueryPromise query helper methods.
+
+**sort**,**limit**,**skip**,**hint**,**timeout**,**snapshot**,**explain**,
+**where**,**in**,**nin**,**ne**,**gt**,**gte**,**lt**,**lte**, **min**,**max**,**mod**,**all**,**size**,**exists**,**type**,**not**
+**inc**,**set**,**unset**,**push**,**pushAll**,**addToSet**,**pop**,**pull**,**pullAll**
+
+
Plugins
-------
@@ -178,9 +362,8 @@ Mongoose supports a plugin architecture. This allows you to add dynamic mixins t
More to be announced soon.
-
-Example
--------
+Documentation
+-------------
Requirements
@@ -191,8 +374,7 @@ Requirements
Credits
--------
-- Node, MongoDB, and node-mongodb-native without these none of this would have been possible.
-- Some ideas and inspiration from Ming
+Nathan White <nathan@learnboost.com>
Future
------
@@ -202,5 +384,15 @@ Future
- Ability to define foreign keys
- Add Inheritance to Models.
-Revisions
----------
+License
+-------
+
+(The MIT License)
+
+Copyright (c) 2010 LearnBoost <dev@learnboost.com>
+
+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.
4 lib/storage.js
View
@@ -85,10 +85,6 @@ var mongo = require('./support/mongodb/lib/mongodb/'),
noSchema : function(collection){
return Model.load(collection, this, {noSchema : true});
},
-
- bindModel : function(model,dirpath){
- return Model.load(model, this, {dir : dirpath || process.env['MONGOOSE_MODELS_DIR'] || (process.env['PWD']+'/models') });
- },
collection : function(){ return this._cmd('collection',Array.prototype.slice.call(arguments,0)); },
close : function(){ return this._cmd('close', Array.prototype.slice.call(arguments,0)); },
Please sign in to comment.
Something went wrong with that request. Please try again.