Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 263 lines (178 sloc) 9.381 kB
ec4a54f @goulash1971 README.md added
goulash1971 authored
1 mongoose-dbref - Plugin support for DBRef in Mongoose
2 ==============
3
4 ### Overview
5
dfe0c08 @goulash1971 README updates
goulash1971 authored
6 Mongoose-DBRef is an extension for Mongoose that exposes the DBRef type from the the `node-mongodb-native`
4fc2a74 @goulash1971 new plugin, patch and examples
goulash1971 authored
7 driver as a top level type in the Mongoose ORM and provides some utilities, plugins and patches that allow
8 DBRef instances to be dereferenced from the models.
dfe0c08 @goulash1971 README updates
goulash1971 authored
9
b583f4f @goulash1971 README updated
goulash1971 authored
10 #### Extension contents
8865f40 @goulash1971 README updated
goulash1971 authored
11
dfe0c08 @goulash1971 README updates
goulash1971 authored
12 The extension provides the following types:
13
969a33c @goulash1971 README restyles
goulash1971 authored
14 - `DBRef` : this is the schema type that can be used for database references
dfe0c08 @goulash1971 README updates
goulash1971 authored
15
16 The extension provides the following plugins:
17
969a33c @goulash1971 README restyles
goulash1971 authored
18 - `resolveDBRefs` : used to create getter/setter methods that resolve DBRefs
4fc2a74 @goulash1971 new plugin, patch and examples
goulash1971 authored
19 - `dbrefHooks` : adds hooks to schema and model for DBRefs
20
bb8aa8a @goulash1971 README updated
goulash1971 authored
21 The extension includes the following monkey-patches:
4fc2a74 @goulash1971 new plugin, patch and examples
goulash1971 authored
22
23 - `dbref.fetch` : used to resolve the dbref against a supplied connection
dfe0c08 @goulash1971 README updates
goulash1971 authored
24
25 The extension provides the following utilities:
26
969a33c @goulash1971 README restyles
goulash1971 authored
27 - `fetch` : fetches the object referenced by a DBRef value
dfe0c08 @goulash1971 README updates
goulash1971 authored
28
ec4a54f @goulash1971 README.md added
goulash1971 authored
29 ### Installation
30 npm install mongoose-dbref
31
32 ### Setup
bb8aa8a @goulash1971 README updated
goulash1971 authored
33 To install all of the types, plugins, patches and utilities provided by the extension into a Mongoose
4fc2a74 @goulash1971 new plugin, patch and examples
goulash1971 authored
34 instance:
2f80a33 @goulash1971 README restyles
goulash1971 authored
35
969a33c @goulash1971 README restyles
goulash1971 authored
36 var mongoose = require("mongoose");
37
38 // Create a connection to your database
39 var db = mongoose.createConnection("mongodb://localhost/sampledb");
40
41 // Access the mongoose-dbref module and install everything
42 var dbref = require("mongoose-dbref");
ca7a622 @goulash1971 README and installer
goulash1971 authored
43 var utils = dbref.utils
44
45 // Install the types, plugins and monkey patches
46 var loaded = dbref.install(mongoose);
47
48 The `loaded` value returned contains 2 properties:
49
50 - `loaded.types` : the join types that were loaded
51 - `loaded.plugins` : the extension plugins that were loaded
dfe0c08 @goulash1971 README updates
goulash1971 authored
52
0af5159 @goulash1971 README updated
goulash1971 authored
53 If you want to control what is installed, you can either install types/plugins/patches separately (see below)
54 or pass in a second argument to the `install` function.
55
56 If this second argument is a `Function` then it will be used as a filter when installing the types, plugins and
57 patches. If it is an `Object` then the `types` property (either a filter `Function` or list of type names) is used
58 when loading the types, the `plugins` property (either a filter `Function` or list of plugin names) is used when
59 installing the plugins and the `patches` property (either a filter `Function` or list of patch names) is used when
60 installing the patches.
61
62 #### Loading Types Only
63
64 To just install the types provided by the extension:
2f80a33 @goulash1971 README restyles
goulash1971 authored
65
969a33c @goulash1971 README restyles
goulash1971 authored
66 var mongoose = require("mongoose");
dfe0c08 @goulash1971 README updates
goulash1971 authored
67
969a33c @goulash1971 README restyles
goulash1971 authored
68 // Create a connection to your database
69 var db = mongoose.createConnection("mongodb://localhost/sampledb");
dfe0c08 @goulash1971 README updates
goulash1971 authored
70
ca7a622 @goulash1971 README and installer
goulash1971 authored
71 // Access the mongoose-dbref module
969a33c @goulash1971 README restyles
goulash1971 authored
72 var dbref = require("mongoose-dbref");
ca7a622 @goulash1971 README and installer
goulash1971 authored
73 var utils = dbref.utils
74
75 // Install the plugins
76 var loaded = dbref.loadTypes(mongoose);
77
78 The `loaded` value returned contains the types that were loaded, keyed by the name of each type
79 loaded.
dfe0c08 @goulash1971 README updates
goulash1971 authored
80
0af5159 @goulash1971 README updated
goulash1971 authored
81 If you just want to load a specific list of types, or want to filter the types loaded then use one
82 of the following signatures with the `loadTypes()` function:
83
e6307de @goulash1971 README updated
goulash1971 authored
84 - `loadTypes(mongoose, 'dbref')` : just loads the `dbref` type
0af5159 @goulash1971 README updated
goulash1971 authored
85 - `loadTypes(mongoose, function(type) { return type.slice(1,2) === 'db'; })` : loads types starting with `db`
86
87 #### Installing Plugins Only
88
89 To just install the plugins provided by the extension:
2f80a33 @goulash1971 README restyles
goulash1971 authored
90
969a33c @goulash1971 README restyles
goulash1971 authored
91 var mongoose = require("mongoose");
92
93 // Create a connection to your database
94 var db = mongoose.createConnection("mongodb://localhost/sampledb");
95
ca7a622 @goulash1971 README and installer
goulash1971 authored
96 // Access the mongoose-dbref module
969a33c @goulash1971 README restyles
goulash1971 authored
97 var dbref = require("mongoose-dbref");
ca7a622 @goulash1971 README and installer
goulash1971 authored
98 var utils = dbref.utils
99
100 // Install the plugins
101 var loaded = dbref.installPlugins(mongoose);
102
103 The `loaded` value returned contains the plugins that were loaded, keyed by the name of each plugin
104 loaded.
4fc2a74 @goulash1971 new plugin, patch and examples
goulash1971 authored
105
0af5159 @goulash1971 README updated
goulash1971 authored
106 If you just want to install a specific list of plugins, or want to filter the plugins loaded then use one
107 of the following signatures with the `installPlugins()` function:
108
e6307de @goulash1971 README updated
goulash1971 authored
109 - `installPlugins(mongoose, 'resolveDBRefs')` : just install the `resolveDBRef` plugin
0af5159 @goulash1971 README updated
goulash1971 authored
110 - `installPlugins(mongoose, function(plugin) { return plugin.slice(1,2) === 'db'; })` : installs plugins starting with `db`
111
112 #### Installing Patches Only
113
114 To just install the patches provided by the extension (all patches, named named patches or filtered patches):
4fc2a74 @goulash1971 new plugin, patch and examples
goulash1971 authored
115
116 var mongoose = require("mongoose");
117
118 // Create a connection to your database
119 var db = mongoose.createConnection("mongodb://localhost/sampledb");
120
ca7a622 @goulash1971 README and installer
goulash1971 authored
121 // Access the mongoose-dbref module and the utilities
4fc2a74 @goulash1971 new plugin, patch and examples
goulash1971 authored
122 var dbref = require("mongoose-dbref");
ca7a622 @goulash1971 README and installer
goulash1971 authored
123 var utils = dbref.utils;
124
125 // Install the monkey patches
126 dbref.installPatches(mongoose);
dfe0c08 @goulash1971 README updates
goulash1971 authored
127
0af5159 @goulash1971 README updated
goulash1971 authored
128 If you just want to install a specific list of patches, or want to filter the patches loaded then use one
129 of the following signatures with the `installPatches()` function:
130
e6307de @goulash1971 README updated
goulash1971 authored
131 - `installPatches(mongoose, 'fetch')` : just install the `fetch` patch
0af5159 @goulash1971 README updated
goulash1971 authored
132 - `installPatches(mongoose, function(patch) { return patch.slice(1,2) === 'db'; })` : installs patch starting with `db`
133
dfe0c08 @goulash1971 README updates
goulash1971 authored
134 ### Using the types
135 Once you have loaded the types, or installed the whole extension, you can begin to use them.
136
05790bf @goulash1971 README restyles
goulash1971 authored
137 #### Type: `DBRef`
969a33c @goulash1971 README restyles
goulash1971 authored
138 The `DBRef` type is a top-level schema type that can be used to identfied a field as holding
dfe0c08 @goulash1971 README updates
goulash1971 authored
139 a MongoDb database reference. You use the type as you would any other standard type.
2f80a33 @goulash1971 README restyles
goulash1971 authored
140
dfe0c08 @goulash1971 README updates
goulash1971 authored
141 var DBRef = mongoose.SchemaTypes.DBRef;
142
143 var LineItemSchema = new Schema({
144 order: DBRef,
145 description: String,
146 cost: Number
147 });
969a33c @goulash1971 README restyles
goulash1971 authored
148
dfe0c08 @goulash1971 README updates
goulash1971 authored
149 var OrderSchema = new Schema({
150 poNumber: String,
151 lineItems: [DBRef]
152 });
153
969a33c @goulash1971 README restyles
goulash1971 authored
154 This will create two schema - `OrderSchema` that has a field (`lineItems`) which can hold
b882f9a @goulash1971 README restyles
goulash1971 authored
155 multiple references, and `LineItemSchema` that has a field `order` with a single reference.
dfe0c08 @goulash1971 README updates
goulash1971 authored
156
b882f9a @goulash1971 README restyles
goulash1971 authored
157 All of the *standard* options (`required`, `index` etc) can be applied to these fields.
dfe0c08 @goulash1971 README updates
goulash1971 authored
158
159 ### Using the plugins
160 Once you have installed the plugins, or installed the whole extension, you can begin to use them.
161
05790bf @goulash1971 README restyles
goulash1971 authored
162 #### Plugin: `resolveDBRefs`
969a33c @goulash1971 README restyles
goulash1971 authored
163 The `resolveDBRefs` plugin can be used to be used to automatically install *getter* and *setter*
b882f9a @goulash1971 README restyles
goulash1971 authored
164 methods for fields where a `resolve` option has been set.
dfe0c08 @goulash1971 README updates
goulash1971 authored
165
166 These methods will map DBRef values to/from objects via the database connection of the owning
167 model.
168
169 For example:
2f80a33 @goulash1971 README restyles
goulash1971 authored
170
dfe0c08 @goulash1971 README updates
goulash1971 authored
171 var LineItemSchema = new Schema({
172 order: {type: DBRef, resolve: true},
173 description: String,
174 cost: Number
175 });
176
177 This will create two methods:
5c0767e @goulash1971 README restyles
goulash1971 authored
178
0dfa066 @goulash1971 README restyles
goulash1971 authored
179 - `getOrder(callback)` - this will asynchronously resolve the `DBRef` value in the `order` field
5c0767e @goulash1971 README restyles
goulash1971 authored
180
0dfa066 @goulash1971 README restyles
goulash1971 authored
181 - `setOrder(value)` - this will cast the `value` (a model) to a `DBRef` value that is set in the `order` field
dfe0c08 @goulash1971 README updates
goulash1971 authored
182
5c0767e @goulash1971 README restyles
goulash1971 authored
183 In addition if the `cache` option is set, then the object resolved from teh `DBRef` value will be
969a33c @goulash1971 README restyles
goulash1971 authored
184 cached in a cache property (`$order` for the `order` field) and the getter method signature
b882f9a @goulash1971 README restyles
goulash1971 authored
185 will be changed to `getOrder(callback, force)`. The additional, optional, parameter `force`
5c0767e @goulash1971 README restyles
goulash1971 authored
186 can be used to bypass any cached value.
dfe0c08 @goulash1971 README updates
goulash1971 authored
187
b882f9a @goulash1971 README restyles
goulash1971 authored
188 This plugin can be installed on the mongoose instance or on individual schema, but the "owning"
189 mongoose instance for the schema must always be specified during the installation.
dfe0c08 @goulash1971 README updates
goulash1971 authored
190
4fc2a74 @goulash1971 new plugin, patch and examples
goulash1971 authored
191 #### Plugin: `dbrefHooks`
192 The `dbrefHooks` plugin can be used to create *hooks* that on the `model` and `schema` instances that
193 map to/from `DBRef` values.
194
195 To do this a `_dbref` virtual and a `fetch` static are installed on each `schema` created such that
196 the `_dbref` virtual will return the `DBRef` for the `model` instance, and the `fetch` static will
197 resolve a supplied `DBRef` and invoke a callback function appropriately.
198
199 ### Using the patches
200 Once you have installed the patches, or installed the whole extension, you can begin to use them.
201
202 #### Patch: `dbref.fetch`
bb8aa8a @goulash1971 README updated
goulash1971 authored
203 This `fetch` monkey patch to the `DBRef` class can be used to resolve a `DBRef` value when supplied with
4fc2a74 @goulash1971 new plugin, patch and examples
goulash1971 authored
204 a mongoos database connection and a callback function.
205
206 var mongoose = require("mongoose");
207 var db = mongoose.createConnection("mongodb://localhost/sampledb");
208
209 var utils = require("mongoose-dbref").utils;
210
211 var LineItem = db.model('LineItem');
212
213 LineItem.findById("4dee1f473abd4fbc61000001",
214 function(err, doc) {
215 doc.order.fetch(db,
216 function(err, doc) {
217 if (err) throw err;
218 console.log("Order = " + doc);
219 });
220 });
221
222 In this example, the `order` of a specific `LineItem` is fetched using the database connection that
223 was used to find the `LineItem` instance.
224
dfe0c08 @goulash1971 README updates
goulash1971 authored
225 ### Using the utilities
226 Once you have installed the utilities, or installed the whole extension, you can begin to use them.
227
7ccb21e @goulash1971 README restyles
goulash1971 authored
228 #### Utility: `fetch`
229 This `fetch` utility function can be used to resolve a given `DBRef` value when supplied with a mongoose
dfe0c08 @goulash1971 README updates
goulash1971 authored
230 database connection and a callback function.
5931a51 @goulash1971 README restyles
goulash1971 authored
231
969a33c @goulash1971 README restyles
goulash1971 authored
232 var mongoose = require("mongoose");
dfe0c08 @goulash1971 README updates
goulash1971 authored
233 var db = mongoose.createConnection("mongodb://localhost/sampledb");
969a33c @goulash1971 README restyles
goulash1971 authored
234
235 var utils = require("mongoose-dbref").utils;
236
dfe0c08 @goulash1971 README updates
goulash1971 authored
237 var LineItem = db.model('LineItem');
969a33c @goulash1971 README restyles
goulash1971 authored
238
dfe0c08 @goulash1971 README updates
goulash1971 authored
239 LineItem.findById("4dee1f473abd4fbc61000001",
240 function(err, doc) {
241 utils.fetch(db, doc.order,
242 function(err, doc) {
243 if (err) throw err;
244 console.log("Order = " + doc);
245 });
246 });
247
b882f9a @goulash1971 README restyles
goulash1971 authored
248 In this example, the `order` of a specific `LineItem` is fetched using the database connection that
249 was used to find the `LineItem` instance.
dfe0c08 @goulash1971 README updates
goulash1971 authored
250
251 ### Contributors
252 - [Stuart Hudson](https://github.com/goulash1971)
253
254 ### License
255 MIT License
256
257 ### Acknowledgements
05790bf @goulash1971 README restyles
goulash1971 authored
258 - [Brian Noguchi](https://github.com/bnoguchi) for the 'mongoose-types' extension that was used as a template for this extension
dfe0c08 @goulash1971 README updates
goulash1971 authored
259
260 ---
261 ### Author
262 Stuart Hudson
Something went wrong with that request. Please try again.