Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

README updates

  • Loading branch information...
commit dfe0c083854ccbd1a252215ba15f40c14af2e98d 1 parent 064e699
@goulash1971 goulash1971 authored
Showing with 141 additions and 3 deletions.
  1. +137 −3 README.md
  2. +4 −0 lib/index.js
View
140 README.md
@@ -3,12 +3,146 @@ mongoose-dbref - Plugin support for DBRef in Mongoose
### Overview
-Mongoose-DBRef is a plugin for Mongoose that exposes the DBRef type from the the `node-mongodb-native`
-driver as a top level type in teh Mongoose ORM.
+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.
+
+The extension provides the following types:
+
+- 'DBRef' : this is the schema type that can be used for database references
+
+The extension provides the following plugins:
+
+- 'resolveDBRefs' : used to create getter/setter methods that resolve DBRefs
+
+The extension provides the following utilities:
+
+- 'fetch' : fetches the object referenced by a DBRef value
+
### Installation
npm install mongoose-dbref
### Setup
+To install all of the types, plugins and utilities provided by the extension into a mongoose instance:
+ var mongoose = require("mongoose");
+
+ // Create a connection to your database
+ var db = mongoose.createConnection("mongodb://localhost/sampledb");
+
+ // Access the mongoose-dbref module and install everything
+ var dbref = require("mongoose-dbref");
+ var utils = dbref.install(mongoose);
+
+To just install the types provided by the extension (either all types or a list of named types):
+ var mongoose = require("mongoose");
+
+ // Create a connection to your database
+ var db = mongoose.createConnection("mongodb://localhost/sampledb");
+
+ // Access the mongoose-dbref module and install everything
+ var dbref = require("mongoose-dbref");
+ var utils = dbref.loadTypes(mongoose);
+
+To just install the plugins provided by the extension (either all plugins or list of named plugins):
+ var mongoose = require("mongoose");
+
+ // Create a connection to your database
+ var db = mongoose.createConnection("mongodb://localhost/sampledb");
+
+ // Access the mongoose-dbref module and install everything
+ var dbref = require("mongoose-dbref");
+ var utils = dbref.loadTypes(mongoose);
+
+### Using the types
+Once you have loaded the types, or installed the whole extension, you can begin to use them.
+
+#### 'DBRef'
+The 'DBRef' type is a top-level schema type that can be used to identfied a field as holding
+a MongoDb database reference. You use the type as you would any other standard type.
+ var DBRef = mongoose.SchemaTypes.DBRef;
+
+ var LineItemSchema = new Schema({
+ order: DBRef,
+ description: String,
+ cost: Number
+ });
+
+ var OrderSchema = new Schema({
+ poNumber: String,
+ lineItems: [DBRef]
+ });
+
+This will create two schema - 'OrderSchema' that has a field ('lineItems') which can hold
+multiple references, and 'LineItemSchema' that has a field 'order' with a single reference.
+
+All of the 'standard' options ('required', 'index' etc) can be applied to these fields.
+
+### Using the plugins
+Once you have installed the plugins, or installed the whole extension, you can begin to use them.
+
+#### 'resolveDBRefs'
+The 'resolveDBRefs' plugin can be used to be used to automatically install *getter* and *setter*
+methods for fields where a 'resolve' option has been set.
+
+These methods will map DBRef values to/from objects via the database connection of the owning
+model.
+
+For example:
+ var LineItemSchema = new Schema({
+ order: {type: DBRef, resolve: true},
+ description: String,
+ cost: Number
+ });
+
+This will create two methods:
+- `getOrder(callback)` - this will asynchronously resolve the DBRef value in the `order` field
+- `setOrder(value)` - this will cast the `value` (a model) to a DBRef value
+
+In addition if the 'cache' option is set, then the object resolved from teh DBRef value will be
+cached in a cache property ('$order' for the 'order' field) and the getter method signature
+will be changed to 'getOrder(callback, force)'. The additional, optional, parameter 'force'
+can be used to by pass any cached value.
+
+This plugin can be installed on a mongoose instance or on individual schema, but the "owning"
+mongoose instance for the schema must always be specified.
+
+### Using the utilities
+Once you have installed the utilities, or installed the whole extension, you can begin to use them.
+
+#### 'utils.fetch'
+This utility function can be used to resolve a given 'DBRef' value when supplied with a mongoose
+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) {
+ utils.fetch(db, doc.order,
+ 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.
+
+### Contributors
+- [Stuart Hudson](https://github.com/goulash1971)
+
+### License
+MIT License
+
+### Acknowledgements
+- Brian Noguchi for the 'mongoose-types' extension that was used as a template for this extension
+
+---
+### Author
+Stuart Hudson
-## Using the DBRef type
+
View
4 lib/index.js
@@ -21,6 +21,7 @@ exports.utils = utils = require("./utils");
*
* @param {Mongoose} the active Mongoose instance for installation
* @param {Array} (optional) type filenames
+ * @return the utilities of the extension (see './utils.js')
*/
exports.loadTypes = loadTypes = function (mongoose) {
var types = Array.prototype.slice.call(arguments, 1);
@@ -35,6 +36,7 @@ exports.loadTypes = loadTypes = function (mongoose) {
require("./types/" + base).loadType(mongoose);
});
}
+ return utils;
};
@@ -44,6 +46,7 @@ exports.loadTypes = loadTypes = function (mongoose) {
*
* @param {Mongoose} the active Mongoose instance for installation
* @param {Array} (optional) plugin filenames
+ * @return the utilities of the extension (see './utils.js')
*/
exports.installPlugins = installPlugins = function (mongoose) {
var plugins = Array.prototype.slice.call(arguments, 1);
@@ -58,6 +61,7 @@ exports.installPlugins = installPlugins = function (mongoose) {
require("./plugins/" + base).install(mongoose);
});
}
+ return utils;
}
/**
Please sign in to comment.
Something went wrong with that request. Please try again.