Browse files

new plugin, patch and examples

  • Loading branch information...
1 parent 0dfa066 commit 4fc2a74f9c37957d92197cf660dfd62529cdaf42 @goulash1971 committed Jun 16, 2011
Showing with 298 additions and 11 deletions.
  1. +6 −0 CHANGELOG.md
  2. +57 −6 README.md
  3. +69 −0 examples/basic.js
  4. +48 −0 examples/hooks.js
  5. +28 −2 lib/index.js
  6. +31 −0 lib/patches/dbref.js
  7. +57 −0 lib/plugins/dbrefHooks.js
  8. +2 −2 lib/plugins/resolveDBRefs.js
  9. +0 −1 package.json
View
6 CHANGELOG.md
@@ -1,3 +1,9 @@
+**v0.0.2** (2011-06-16):
+
+ - Added dbrefHooks plugin
+ - Added dbref.fetch monkey patch
+ - Added basic and coercion examples
+
**v0.0.1** (2011-06-06):
- Initial version of the DBRef Plugin for Mongose 1.3.3
View
63 README.md
@@ -4,8 +4,8 @@ mongoose-dbref - Plugin support for DBRef in Mongoose
### Overview
Mongoose-DBRef is an extension for Mongoose that exposes the DBRef type from the the `node-mongodb-native`
-driver as a top level type in the Mongoose ORM and provides some utilities and plugins that allow DBRef instances
-to be dereferenced from the models.
+driver as a top level type in the Mongoose ORM and provides some utilities, plugins and patches that allow
+DBRef instances to be dereferenced from the models.
The extension provides the following types:
@@ -14,6 +14,11 @@ The extension provides the following types:
The extension provides the following plugins:
- `resolveDBRefs` : used to create getter/setter methods that resolve DBRefs
+- `dbrefHooks` : adds hooks to schema and model for DBRefs
+
+The extsion includes the following monkey-patches:
+
+- `dbref.fetch` : used to resolve the dbref against a supplied connection
The extension provides the following utilities:
@@ -24,7 +29,8 @@ The extension provides the following utilities:
npm install mongoose-dbref
### Setup
-To install all of the types, plugins and utilities provided by the extension into a mongoose instance:
+To install all of the types, plugins, patches and utilities provided by the extension into a mongoose
+instance:
var mongoose = require("mongoose");
@@ -42,7 +48,7 @@ To just install the types provided by the extension (either all types or a list
// Create a connection to your database
var db = mongoose.createConnection("mongodb://localhost/sampledb");
- // Access the mongoose-dbref module and install everything
+ // Access the mongoose-dbref module and install types
var dbref = require("mongoose-dbref");
var utils = dbref.loadTypes(mongoose);
@@ -53,9 +59,20 @@ To just install the plugins provided by the extension (either all plugins or lis
// Create a connection to your database
var db = mongoose.createConnection("mongodb://localhost/sampledb");
- // Access the mongoose-dbref module and install everything
+ // Access the mongoose-dbref module and install plugins
var dbref = require("mongoose-dbref");
- var utils = dbref.loadTypes(mongoose);
+ var utils = dbref.installPlugins(mongoose);
+
+To just install the patches provided by the extension (either all patches or list of named patches):
+
+ var mongoose = require("mongoose");
+
+ // Create a connection to your database
+ var db = mongoose.createConnection("mongodb://localhost/sampledb");
+
+ // Access the mongoose-dbref module and install patches
+ var dbref = require("mongoose-dbref");
+ var utils = dbref.installPatches(mongoose);
### Using the types
Once you have loaded the types, or installed the whole extension, you can begin to use them.
@@ -114,6 +131,40 @@ can be used to bypass any cached value.
This plugin can be installed on the mongoose instance or on individual schema, but the "owning"
mongoose instance for the schema must always be specified during the installation.
+#### Plugin: `dbrefHooks`
+The `dbrefHooks` plugin can be used to create *hooks* that on the `model` and `schema` instances that
+map to/from `DBRef` values.
+
+To do this a `_dbref` virtual and a `fetch` static are installed on each `schema` created such that
+the `_dbref` virtual will return the `DBRef` for the `model` instance, and the `fetch` static will
+resolve a supplied `DBRef` and invoke a callback function appropriately.
+
+### Using the patches
+Once you have installed the patches, or installed the whole extension, you can begin to use them.
+
+#### Patch: `dbref.fetch`
+This `fetch` utility patch to the `DBRef` class can be used to resolve a `DBRef` value when supplied with
+a mongoos database connection and a callback function.
+
+ var mongoose = require("mongoose");
+ var db = mongoose.createConnection("mongodb://localhost/sampledb");
+
+ var utils = require("mongoose-dbref").utils;
+
+ var LineItem = db.model('LineItem');
+
+ LineItem.findById("4dee1f473abd4fbc61000001",
+ function(err, doc) {
+ doc.order.fetch(db,
+ function(err, doc) {
+ if (err) throw err;
+ console.log("Order = " + doc);
+ });
+ });
+
+In this example, the `order` of a specific `LineItem` is fetched using the database connection that
+was used to find the `LineItem` instance.
+
### Using the utilities
Once you have installed the utilities, or installed the whole extension, you can begin to use them.
View
69 examples/basic.js
@@ -0,0 +1,69 @@
+var mongoose = require("mongoose");
+
+// Create a connection
+var db = mongoose.createConnection();
+
+// Access the mongoose-dbref module and install everything
+var dbref = require("mongoose-dbref");
+var utils = dbref.install(mongoose);
+
+// Create the schemas
+var Schema = mongoose.Schema;
+var DBRef = mongoose.SchemaTypes.DBRef;
+
+var LineItemSchema = new Schema({
+ order: DBRef,
+ description: String,
+ cost: Number
+});
+
+var OrderSchema = new Schema({
+ poNumber: String,
+ lineItems: [DBRef]
+});
+
+// Create models in the sampledb
+var LineItem = db.model('LineItem', LineItemSchema);
+var Order = db.model('Order', OrderSchema);
+
+
+// Open a connection to the database and do stuff
+db.open("mongodb://localhost/sampledb", function(err) {
+ if (err) throw err;
+
+ // Create an order
+ var order = new Order({poNumber: 'NMH1975'});
+
+ // Save the order and attach the line item to it
+ order.save(function (err) {
+ if (err) throw err;
+
+ // Create line item with reference to order
+ var lineItem = new LineItem({description: 'Jewel', cost: 5000.00});
+ lineItem.order = {"$ref": order.collection.name, "$id": order._id};
+
+ // Save the line item and attach it to the order
+ lineItem.save(function (err) {
+ if (err) throw err;
+ order.lineItems.push({"$ref" : lineItem.collection.name, "$id": lineItem._id});
+
+ // Save the updated order
+ order.save(function (err) {
+ if (err) throw err;
+
+ // All saved so lets show the tree (bottom-up fetch is easier)
+ LineItem.findOne(function (err, doc) {
+ if (err) throw err;
+ utils.fetch(db, doc.order, function (err, doc1) {
+ if (err) throw err;
+ console.log("ORDER:", doc1);
+ console.log("LINE ITEM:", doc);
+ db.close();
+ });
+ });
+ });
+ });
+ });
+});
+
+
View
48 examples/hooks.js
@@ -0,0 +1,48 @@
+var mongoose = require("mongoose");
+
+// Create a connection
+var db = mongoose.createConnection();
+
+// Access the mongoose-dbref module and install everything
+var dbref = require("mongoose-dbref");
+var utils = dbref.install(mongoose);
+
+// Create the schemas
+var Schema = mongoose.Schema;
+var DBRef = mongoose.SchemaTypes.DBRef;
+
+var LineItemSchema = new Schema({
+ order: DBRef,
+ description: String,
+ cost: Number
+});
+
+var OrderSchema = new Schema({
+ poNumber: String,
+ lineItems: [DBRef]
+});
+
+// Create models in the sampledb
+var LineItem = db.model('LineItem', LineItemSchema);
+var Order = db.model('Order', OrderSchema);
+
+// Open a connection to the database and do stuff
+db.open("mongodb://localhost/sampledb", function(err) {
+ if (err) throw err;
+
+ // Create an order
+ var order = new Order({poNumber: 'NMH1975'});
+
+ // Save the order and look at the virtual
+ order.save(function (err) {
+ if (err) throw err;
+ console.log("DBREF:", order._dbref);
+
+ // Now use the static method to fetch
+ Order.fetch(order._dbref, function (err, doc) {
+ if (err) throw err;
+ console.log("FETCHED:", doc);
+ db.close();
+ });
+ });
+});
View
30 lib/index.js
@@ -4,7 +4,7 @@
* Copyright 2011, Stuart Hudson <goulash1971@yahoo.com>
* Released under the terms of the MIT License.
*
- * Version 0.0.1
+ * Version 0.0.2
*/
@@ -65,14 +65,40 @@ exports.installPlugins = installPlugins = function (mongoose) {
}
/**
+ * Installs either the named patches or all available patches in the
+ * {@code lib/patches} source directory
+ *
+ * @param {Mongoose} the active Mongoose instance for installation
+ * @param {Array} (optional) patch filenames
+ * @return the utilities of the extension (see './utils.js')
+ */
+exports.installPatches = installPatches = function (mongoose) {
+ var patches = Array.prototype.slice.call(arguments, 1);
+ if (patches.length) {
+ types.forEach(function (patch) {
+ require("./patches/" + patch).install(mongoose);
+ });
+ } else {
+ var files = require("fs").readdirSync(__dirname + "/patches");
+ files.forEach(function(filename) {
+ var base = filename.slice(0, filename.length-3);
+ require("./patches/" + base).install(mongoose);
+ });
+ }
+ return utils;
+}
+
+/**
* Installation function that will load all of the types and install
- * all of the plugins that are defined for this mongoose extension.
+ * both the plugins and the patches that are defined for this mongoose
+ * extension.
*
* @param {Mongoose} the active Mongoose instance for installation
* @return the utilities of the extension (see './utils.js')
*/
exports.install = function (mongoose) {
loadTypes (mongoose);
installPlugins(mongoose);
+ installPatches(mongoose);
return utils;
}
View
31 lib/patches/dbref.js
@@ -0,0 +1,31 @@
+/**
+ * lib/patches/dbref.js - monkey patches to DBRef type
+ *
+ * Copyright 2011, Stuart Hudson <goulash1971@yahoo.com>
+ * Released under the terms of the MIT License.
+ *
+ * Version 0.0.2
+ */
+var mongoose = require("mongoose");
+
+
+/**
+ * Function that will resolve the DBRef instance using a supplied
+ * database connection
+ *
+ * @param {Connection} a database connection
+ * @param {Function} standard callback '(err, doc)'
+ */
+var dbrefFetch = function (conn, callback) {
+ conn.db.dereference(this, callback);
+};
+
+
+/**
+ * Installer that installs a plugin into the mongoose infrastructure
+ *
+ * @param {Mongoose} the active Mongoose instance for installation
+ */
+exports.install = function (mongoose) {
+ mongoose.Types.DBRef.prototype.fetch = dbrefFetch;
+}
View
57 lib/plugins/dbrefHooks.js
@@ -0,0 +1,57 @@
+/**
+ * lib/plugins/dbrefHooks.js - DBRef Resolver
+ *
+ * Copyright 2011, Stuart Hudson <goulash1971@yahoo.com>
+ * Released under the terms of the MIT License.
+ *
+ * Version 0.0.2
+ */
+var mongoose = require("mongoose");
+
+
+/**
+ * Plugin that will install support (via the schema) that create hooks
+ * on model and schema from DBRefs.
+ *
+ * The '_dbref' virtual returns a DBRef object for the model instance
+ * using the '_id', 'collection' and 'db' properties.
+ *
+ * The 'fetch(dbref,callback,strict)' static performs a dereference
+ * using a supplied DBRef (dbref), active database collection, and the
+ * supplied callback funcion (callback).
+ *
+ * If the optional 'strict' parameter is supplied and is {@code true}
+ * then the namespace of the DBRef must be the same as the schema.
+ *
+ * @param {Object} the schema the plugin is being used against
+ * @param {Object} global options that apply to this plugin
+ */
+exports.dbrefHooks = dbrefHooks = function (schema, options) {
+ if (!('mongoose' in options))
+ throw new Error("'mongoose' option not defined");
+ if (!('DBRef' in options.mongoose.Types))
+ throw new Error("'DBRef' type not installed");
+ var dbref = options.mongoose.SchemaTypes.DBRef;
+ // Virtual to return DBRef
+ schema.virtual("_dbref").get(function () {
+ return dbref.prototype.cast({"$ref": this.collection.name,
+ "$id": this._id, "$db": this.db.db.databaseName});
+ });
+ // Static to perform database dereference
+ schema.static("fetch", function (dbref, callback, strict) {
+ if ((strict) && (dbref.namespace !== this.collection.name))
+ throw new Error("wrong namespace for " + dbref);
+ this.db.db.dereference(dbref, callback);
+ });
+}
+
+
+
+/**
+ * Installer that installs a plugin into the mongoose infrastructure
+ *
+ * @param {Mongoose} the active Mongoose instance for installation
+ */
+exports.install = function (mongoose) {
+ return mongoose.plugin(dbrefHooks, {mongoose: mongoose});
+}
View
4 lib/plugins/resolveDBRefs.js
@@ -1,10 +1,10 @@
/**
- * lib/plugins/resolveDbRefs.js - DBRef Resolver
+ * lib/plugins/resolveDBRefs.js - DBRef Resolver
*
* Copyright 2011, Stuart Hudson <goulash1971@yahoo.com>
* Released under the terms of the MIT License.
*
- * Version 0.0.1
+ * Version 0.0.2
*/
var mongoose = require("mongoose");
View
1 package.json
@@ -1,6 +1,5 @@
{
"name": "mongoose-dbref",
- "private": true,
"description": "Plugin support for DBRef in Mongoose",
"version": "0.0.1",
"author": "Stuart Hudson <goulash1971@yahoo.com>",

0 comments on commit 4fc2a74

Please sign in to comment.