Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 417 lines (238 sloc) 10.903 kb
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
1 Mongoose: MongoDB ODM/ORM
2 =========================
a4cd1a0 Nathan White added requirements to readme
nw authored
3
13d957f Aaron Heckmann a -> an
aheckmann authored
4 The goal of Mongoose is to provide an extremely simple interface for MongoDB.
3c71ba2 Nathan White added buffers and currying to models
nw authored
5
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
6 ## Features
ddb4b05 Nathan White readme updates
nw authored
7
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
8 - Reduces the burden of dealing with nested callback from async operations.
9 - Provides a simple yet rich API.
10 - Ability to model your data with custom interfaces.
11 - Allows for complex business logic in an async way (see `Promises`).
12
1506a4f Guillermo Rauch Corrected installation instructions
rauchg authored
13 ## Installation
d2ed12b James Harrison Fisher Added installation instructions, as per new NPM package.
jameshfisher authored
14
1506a4f Guillermo Rauch Corrected installation instructions
rauchg authored
15 ### As a submodule of your project (recommended)
d2ed12b James Harrison Fisher Added installation instructions, as per new NPM package.
jameshfisher authored
16
1506a4f Guillermo Rauch Corrected installation instructions
rauchg authored
17 git submodule add git://github.com/LearnBoost/mongoose.git {path/to/mongoose}
18 git submodule update --init --recursive
19
20 Example paths: `support/mongoose`, `vendor/mongoose`.
21
22 ### Cloning the repository (mainly for making changes to mongoose)
23
24 git clone git://github.com/LearnBoost/mongoose.git --recursive
25 cd mongoose
26
27 ### With npm
d2ed12b James Harrison Fisher Added installation instructions, as per new NPM package.
jameshfisher authored
28
1506a4f Guillermo Rauch Corrected installation instructions
rauchg authored
29 npm install http://github.com/learnboost/mongoose/tree/0.0.2
30
31 ### With Kiwi
d2ed12b James Harrison Fisher Added installation instructions, as per new NPM package.
jameshfisher authored
32
1506a4f Guillermo Rauch Corrected installation instructions
rauchg authored
33 kiwi install mongoose
34
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
35 ## How to use
36
37 ### Setup
38
d2ed12b James Harrison Fisher Added installation instructions, as per new NPM package.
jameshfisher authored
39 Simply require Mongoose:
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
40
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
41 require.paths.unshift('vendor/mongoose');
42 var mongoose = require('mongoose').Mongoose;
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
43
44 ### Defining a model
45
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
46 mongoose.model('User', {
47
48 properties: ['first', 'last', 'age', 'updated_at'],
49
50 cast: {
51 age: Number,
52 'nested.path': String
53 },
54
55 indexes: ['first'],
56
57 setters: {
58 first: function(v){
59 return this.v.capitalize();
60 }
61 },
62
63 getters: {
64 full_name: function(){
65 return this.first + ' ' + this.last
66 }
67 },
68
69 methods: {
70 save: function(fn){
71 this.updated_at = new Date();
72 this.__super__(fn);
73 }
74 },
75
76 static: {
77 findOldPeople: function(){
78 return this.find({age: { '$gt': 70 }});
79 }
80 }
81
82 });
83
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
84 ### Getting a model
85
86 Models are pseudo-classes that depend on an active connection. To connect:
87
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
88 var db = mongoose.connect('mongodb://localhost/db');
89
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
90 To get a model:
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
91
92 var User = db.model('User');
93
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
94 To create a new instance (document)
95
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
96 var u = new User();
97 u.name = 'John';
98 u.save(function(){
99 sys.puts('Saved!');
100 });
101
bcf8da2 Guillermo Rauch More documentation tweaks
rauchg authored
102 To fetch some stuff
103
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
104 User.find({ name: 'john' }).all(function(array){
105
106 });
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
107
5cd7b26 Guillermo Rauch Added js-oo
rauchg authored
108 ### Operating on embedded objects
eef63e3 Guillermo Rauch Added last piece, about EmbeddedObject
rauchg authored
109
110 Embedded objects are hydrated like model instances. Assume a MongoDB document like this stored in a variable `user`
111
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
112 {
113 name: 'John',
114 blogposts: [
115 {
116 title: 'Hi',
117 body: 'Hi there'
118 }
119 ]
120 }
121
eef63e3 Guillermo Rauch Added last piece, about EmbeddedObject
rauchg authored
122 To add a blogpost:
123
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
124 user.blogposts.push({ title: 'New post', body: 'The body' });
125 user.save();
eef63e3 Guillermo Rauch Added last piece, about EmbeddedObject
rauchg authored
126
127 To remove an existing one:
128
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
129 user.blogposts[0] = null;
130 user.save();
eef63e3 Guillermo Rauch Added last piece, about EmbeddedObject
rauchg authored
131
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
132 ## API
133
134 ### mongoose
135
136 #### Methods
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
137
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
138 - **model(name, definition)**
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
139
140 - *definition* determines how the class will be constructed. It's composed of the following keys. All of them are optional:
141
142 - *collection*
143
144 Optionally, the MongoDB collection name. Defaults to the model name in lowercase and plural. Does not need to be created in advance.
145
146 - *properties*
147
148 Defines the properties for how you structure the model.
149
150 To define simple keys:
151
152 properties: [ 'name', 'last' ]
153
154 To define arrays:
155
156 properties: [ 'name', {'tags': []} ]
157
158 To define nested objects:
159
160 properties: [ 'name', {contact: ['email', 'phone', ...]} ]
161
162 To define array of embedded objects:
163
164 properties: [ 'name', {blogposts: [['title', 'body', ...]]} ]
165
166 `_id` is added automatically for all models.
167
168 - *getters*
169
170 Defines getters (can be nested). If the getter matches an existing property, the existing value will be passed as the first argument.
171
172 - *setters*
173
174 Defines setters (can be nested). If the setter matches an existing property, the return value will be set.
175
176 - *cast*
177
178 Defines type casting. By default, all properties beginning with `_` are cast to `ObjectID`. (note: Casting an Array will cast all items in the Array. Currently, Arrays cast when 'save' is called.)
179
180 - *indexes*
181
182 An array of indexes.
183
184 Simple indexes: ['name', 'last']
185
186 Compound indexes: [{ name: 1, last: 1 }, ...]
187
188 Indexes with options: ['simple', [{ name: 1 }, {unique: true}]]
189
190 Notice that the objects that you pass are equivalent to those that you would pass to ensureIndex in MongoDB.
191
192 - *methods*
193
194 Methods that are added to the prototype of the model, or methods that override existing ones. For example `save` (you can call `__super__` to access the parent)
195
196 - *static*
197
198 Static methods that are not instance-dependent (eg: `findByAge()`)
199
89403a0 Nathan White api cleanup and more README docs
nw authored
200 ### Model
ddb4b05 Nathan White readme updates
nw authored
201
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
202 These are methods and properties that all *model instances* already include:
89403a0 Nathan White api cleanup and more README docs
nw authored
203
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
204 #### Properties
89403a0 Nathan White api cleanup and more README docs
nw authored
205
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
206 - **isNew**
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
207
208 Whether the instance exists as a document or the db (*false*), or hasn't been saved down before (*true*)
89403a0 Nathan White api cleanup and more README docs
nw authored
209
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
210 #### Methods
89403a0 Nathan White api cleanup and more README docs
nw authored
211
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
212 Note: if you override any of these by including them in the `methods` object of the model definition, the method is inherited and you can call __super__ to access the parent.
89403a0 Nathan White api cleanup and more README docs
nw authored
213
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
214 - **save(fn)**
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
215
216 Saves down the document and fires the callback.
217
58a6cf1 Guillermo Rauch Added missing method
rauchg authored
218 - **remove(fn)**
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
219
220 Removes the document and fires the callback.
221
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
222 ### Model (static)
89403a0 Nathan White api cleanup and more README docs
nw authored
223
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
224 These are the methods that can be accessed statically, and affect the collection as a whole.
89403a0 Nathan White api cleanup and more README docs
nw authored
225
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
226 - **find(props, subset, hydrate)**
89403a0 Nathan White api cleanup and more README docs
nw authored
227
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
228 Returns an instance of QueryWriter
229
230 - *props*
231
232 Optional, calls the QueryWriter `where` on each key/value. `find({username: 'john'})` is equivalent to:
233
234 model.find().where('username', 'john');
235
236 - *subset*
237
238 Optional, a subset of fields to retrieve. More information on [MongoDB Docs](http://www.mongodb.org/display/DOCS/Advanced+Queries#AdvancedQueries-RetrievingaSubsetofFields)
239
240 - *hydrate*
241
242 Possible values:
243
244 - `true`. Returns a model instance (default)
245 - `null`. Returns a plain object that is augmented to match the missing properties defined in the model.
246 - `false`. Returns the object as it's retrieved from MongoDB.
247
248
249 - **findById(id, fn, hydrate)**
250
251 Returns an instance of QueryWriter
252
253 - *id*
254
255 Document id (hex or string allowed)
256
257 - *fn*
258
259 Optional callback. Called on success.
260
261 - *hydrate*
262
263 Same as above
264
265 - **update(id, doc, fn)**
266
267 Sets/updates *only* the properties of the passed document for the specified object id
268
269 - *id*
270
271 Document id (hex or string allowed)
272
273 - *fn (doc)*
274
275 Optional callback. Called on Success. Doc paramter will contain the hyrdrated document from the DB after the update.
276
277 - *hydrate*
278
279 Same as above
280
281 - **remove(where, fn)**
282
283 Executes the query (and triggers a remove of the matched documents)
284
285 - *where*
286
287 Valid where clause.
288
289 - *fn*
290
291 Optional callback. Called on success.
eef63e3 Guillermo Rauch Added last piece, about EmbeddedObject
rauchg authored
292
293 ### EmbeddedObject
294
295 #### Methods
296
440f320 Nathan White changed EmbeddedObject public method 'delete' => 'remove' (reserved word...
nw authored
297 - **remove**
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
298
299 Marks the embeded object for deletion
300
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
301 ### QueryWriter
89403a0 Nathan White api cleanup and more README docs
nw authored
302
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
303 QueryWriter allows you to construct queries with very simple syntax. All its methods return the `QueryWriter` instance, which means they're chainable.
89403a0 Nathan White api cleanup and more README docs
nw authored
304
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
305 #### Methods
89403a0 Nathan White api cleanup and more README docs
nw authored
306
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
307 ##### Executers
89403a0 Nathan White api cleanup and more README docs
nw authored
308
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
309 These methods execute the query and return a `QueryPromise`.
89403a0 Nathan White api cleanup and more README docs
nw authored
310
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
311 - **exec**
89403a0 Nathan White api cleanup and more README docs
nw authored
312
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
313 Executes the query.
89403a0 Nathan White api cleanup and more README docs
nw authored
314
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
315 - **count**
89403a0 Nathan White api cleanup and more README docs
nw authored
316
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
317 Executes the query (and triggers a count)
89403a0 Nathan White api cleanup and more README docs
nw authored
318
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
319 In addition, for the sake of simplicity, all the promise methods (see "Queueable methods") are mirrored in the QueryWriter and trigger `.exec()`. Then, the following two are equivalent:
89403a0 Nathan White api cleanup and more README docs
nw authored
320
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
321 User.find({username: 'john'}).all(fn)
322
323 and:
324
325 User.find({username: 'john'}).exec().all(fn)
89403a0 Nathan White api cleanup and more README docs
nw authored
326
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
327 ##### Modifiers
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
328
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
329 - **where**
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
330
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
331 - **sort**
89403a0 Nathan White api cleanup and more README docs
nw authored
332
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
333 - **limit**
89403a0 Nathan White api cleanup and more README docs
nw authored
334
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
335 - **skip**
89403a0 Nathan White api cleanup and more README docs
nw authored
336
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
337 - **snapshot**
89403a0 Nathan White api cleanup and more README docs
nw authored
338
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
339 - **group**
89403a0 Nathan White api cleanup and more README docs
nw authored
340
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
341 ### QueryPromise
89403a0 Nathan White api cleanup and more README docs
nw authored
342
13b066e Guillermo Rauch Some more tweaks
rauchg authored
343 A promise is a special object that acts as a `queue` if MongoDB has not resulted the results, and executes the methods you call on it once the results are available.
89403a0 Nathan White api cleanup and more README docs
nw authored
344
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
345 For example
89403a0 Nathan White api cleanup and more README docs
nw authored
346
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
347 User.find({ age: { '$gt': 5 } }).first(function(result){
348 // gets first result
349 }).last(function(result){
350 // gets last result
351 });
89403a0 Nathan White api cleanup and more README docs
nw authored
352
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
353 #### Methods
89403a0 Nathan White api cleanup and more README docs
nw authored
354
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
355 - **stash(fn)**
89403a0 Nathan White api cleanup and more README docs
nw authored
356
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
357 Stashes all the current queued methods, which will be called when `complete` is called. Methods that are queued **after** stash is called will only fire after `complete` is called again.
89403a0 Nathan White api cleanup and more README docs
nw authored
358
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
359 - **complete(result)**
89403a0 Nathan White api cleanup and more README docs
nw authored
360
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
361 Completes the promise. The result parameter is optional. It's either null or an array of documents. (internal use)
89403a0 Nathan White api cleanup and more README docs
nw authored
362
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
363 ##### Queueable Methods
89403a0 Nathan White api cleanup and more README docs
nw authored
364
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
365 You can call all of these in a row, but the callbacks will only trigger when `complete is called`
89403a0 Nathan White api cleanup and more README docs
nw authored
366
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
367 - **all(fn)**
89403a0 Nathan White api cleanup and more README docs
nw authored
368
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
369 Fires with all the results as an array, or an empty array.
89403a0 Nathan White api cleanup and more README docs
nw authored
370
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
371 - **get(fn)**
89403a0 Nathan White api cleanup and more README docs
nw authored
372
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
373 Synonym to `all`
89403a0 Nathan White api cleanup and more README docs
nw authored
374
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
375 - **last(fn)**
89403a0 Nathan White api cleanup and more README docs
nw authored
376
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
377 Fires with the last document or *null*
89403a0 Nathan White api cleanup and more README docs
nw authored
378
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
379 - **first(fn)**
89403a0 Nathan White api cleanup and more README docs
nw authored
380
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
381 Fires with the first document of the resulset or *null* if no documents are returned
89403a0 Nathan White api cleanup and more README docs
nw authored
382
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
383 - **one(fn)**
6fcde18 Nathan White wrappers in place along with an example
nw authored
384
5704f5e Charles Ginzel added description for findById, update and remove model class methods
cginzel authored
385 Synonym to `first`
6fcde18 Nathan White wrappers in place along with an example
nw authored
386
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
387 ## Credits
a4cd1a0 Nathan White added requirements to readme
nw authored
388
89403a0 Nathan White api cleanup and more README docs
nw authored
389 Nathan White <nathan@learnboost.com>
6fcde18 Nathan White wrappers in place along with an example
nw authored
390
5ce2361 Guillermo Rauch Function compilation to make schema initialization 1500% faster
rauchg authored
391 Guillermo Rauch <guillermo@learnboost.com>
392
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
393 ## License
89403a0 Nathan White api cleanup and more README docs
nw authored
394
395 (The MIT License)
396
222e6f4 Guillermo Rauch Definite documentation
rauchg authored
397 Copyright (c) 2010 LearnBoost <dev@learnboost.com>
398
399 Permission is hereby granted, free of charge, to any person obtaining
400 a copy of this software and associated documentation files (the
401 'Software'), to deal in the Software without restriction, including
402 without limitation the rights to use, copy, modify, merge, publish,
403 distribute, sublicense, and/or sell copies of the Software, and to
404 permit persons to whom the Software is furnished to do so, subject to
405 the following conditions:
406
407 The above copyright notice and this permission notice shall be
408 included in all copies or substantial portions of the Software.
409
410 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
411 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
412 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
413 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
414 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
415 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
d2ed12b James Harrison Fisher Added installation instructions, as per new NPM package.
jameshfisher authored
416 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.