expresser

<!DOCTYPE html> <html> <head> <title>database.coffee</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <link rel="stylesheet" media="all" href="public/stylesheets/normalize.css" /> <link rel="stylesheet" media="all" href="docco.css" /> </head> <body> <div class="container"> <div class="page"> <div class="header"> <h1>database.coffee</h1> <div class="toc"> <h3>Table of Contents</h3> <ol> <li> <a class="source" href="index.html"> index.coffee </a> </li> <li> <a class="source" href="app.html"> app.coffee </a> </li> <li> <a class="source" href="cron.html"> cron.coffee </a> </li> <li> <a class="source" href="database.html"> database.coffee </a> </li> <li> <a class="source" href="downloader.html"> downloader.coffee </a> </li> <li> <a class="source" href="events.html"> events.coffee </a> </li> <li> <a class="source" href="firewall.html"> firewall.coffee </a> </li> <li> <a class="source" href="imaging.html"> imaging.coffee </a> </li> <li> <a class="source" href="logger.html"> logger.coffee </a> </li> <li> <a class="source" href="mailer.html"> mailer.coffee </a> </li> <li> <a class="source" href="settings.html"> settings.coffee </a> </li> <li> <a class="source" href="sockets.html"> sockets.coffee </a> </li> <li> <a class="source" href="utils.html"> utils.coffee </a> </li> </ol> </div> </div> <h2 id="expresser-database">EXPRESSER DATABASE</h2> Handles MongoDB database transactions using the <code>mongoskin</code> module. It supports a very simple failover mechanism where you can specify a “backup” connection string to which the module will connect in case the main database is down. If you prefer tp access Mongo directly, you can use the <code>db</code> property, for example: expresser.database.db.collection(“mycollection”).findAndModify(args…).  <div class='highlight'><pre>class Database lodash = require "lodash" logger = require "./logger.coffee" settings = require "./settings.coffee" mongo = require "mongoskin"</pre></div> @property [Object] Database object (using mongoskin), will be set during <code>init</code>. <div class='highlight'><pre> db: null</pre></div> <h2 id="init">INIT</h2> Init the databse module and test the connection straight away. @param [Object] options Database init options. <div class='highlight'><pre> init: (options) => if settings.database.connString? and settings.database.connString isnt "" @setDb settings.database.connString, settings.database.options else logger.debug "Database.init", "No connection string set.", "Database module won't work."</pre></div> <h2 id="crud-implementation">CRUD IMPLEMENTATION</h2> Get data from the database. A <code>collection</code> and <code>callback</code> must be specified. The <code>filter</code> is optional. Please note that if <code>filter</code> has an _id or id field, or if it’s a plain string or number, it will be used to return documents by ID. Otherwise it’s used as keys-values object for filtering. @param [String] collection The collection name. @param [String, Object] filter Optional, if a string or number, assume it’s the document ID. Otherwise assume keys-values filter. @param [Object] options Options to be passed to the query. @option options [Integer] limit Limits the resultset to X documents. @param [Method] callback Callback (err, result) when operation has finished. <div class='highlight'><pre> get: (collection, filter, options, callback) => if not callback? if lodash.isFunction options callback = options options = null else if lodash.isFunction filter callback = filter filter = null</pre></div> Callback is mandatory! <div class='highlight'><pre> if not callback? if settings.logger.autoLogErrors logger.error "Database.get", "No callback specified. Abort!", collection, filter throw new Error "Database.get: a callback (last argument) must be specified."</pre></div> No DB set? Throw exception. <div class='highlight'><pre> if not @db? if settings.logger.autoLogErrors logger.error "Database.get", "The db is null or was not initialized. Abort!", collection, filter return callback "Database.insert: the db was not initialized, please check database settings and call its 'init' method."</pre></div> Create the DB callback helper. <div class='highlight'><pre> dbCallback = (err, result) => if callback? result = @normalizeId result if settings.database.normalizeId callback err, result</pre></div> Set collection object. <div class='highlight'><pre> dbCollection = @db.collection collection</pre></div> Parse ID depending on <code>filter</code>. <div class='highlight'><pre> if filter? if filter._id? id = filter._id else if filter.id? and settings.database.normalizeId id = filter.id else t = typeof filter id = filter if t is "string" or t is "integer"</pre></div> Get <code>limit</code> option. <div class='highlight'><pre> if options?.limit? limit = options.limit else limit = 0</pre></div> Find documents depending on <code>filter</code> and <code>options</code>. If id is set, use the shorter findById. <div class='highlight'><pre> if id? dbCollection.findById id, dbCallback</pre></div> Create a params object for the find method. <div class='highlight'><pre> else if filter? findParams = {$query: filter} findParams["$orderby"] = options.orderBy if options?.orderBy? if limit > 0 dbCollection.find(findParams).limit(limit).toArray dbCallback else dbCollection.find(findParams).toArray dbCallback</pre></div> Search everything! <div class='highlight'><pre> else if limit > 0 dbCollection.find({}).limit(limit).toArray dbCallback else dbCollection.find({}).toArray dbCallback if filter? filterLog = filter filterLog.password = "***" if filterLog.password? filterLog.passwordHash = "***" if filterLog.passwordHash? logger.debug "Database.get", collection, filterLog, options else logger.debug "Database.get", collection, "No filter.", options</pre></div> Add new documents to the database. The <code>options</code> parameter is optional. @param [String] collection The collection name. @param [Object] obj Document or array of documents to be added. @param [Method] callback Callback (err, result) when operation has finished. <div class='highlight'><pre> insert: (collection, obj, callback) => if not obj? if settings.logger.autoLogErrors logger.error "Database.insert", "No object specified. Abort!", collection if callback? callback "Database.insert: no object (second argument) was specified." return false</pre></div> No DB set? Throw exception. <div class='highlight'><pre> if not @db? if settings.logger.autoLogErrors logger.error "Database.insert", "The db is null or was not initialized. Abort!", collection if callback? callback "Database.insert: the db was not initialized, please check database settings and call its 'init' method." return false</pre></div> Create the DB callback helper. <div class='highlight'><pre> dbCallback = (err, result) => if callback? result = @normalizeId(result) if settings.database.normalizeId callback err, result</pre></div> Set collection object. <div class='highlight'><pre> dbCollection = @db.collection collection</pre></div> Execute insert! <div class='highlight'><pre> dbCollection.insert obj, dbCallback logger.debug "Database.insert", collection</pre></div> Update existing documents on the database. The <code>options</code> parameter is optional. @param [String] collection The collection name. @param [Object] obj Document or data to be updated. @param [Object] options Optional, options to control and filter the insert behaviour. @option options [Object] filter Defines the query filter. If not specified, will try using the ID of the passed object. @option options [Boolean] patch Default is false, if true replace only the specific properties of documents instead of the whole data, using $set. @option options [Boolean] upsert Default is false, if true it will create documents if none was found. @param [Method] callback Callback (err, result) when operation has finished. <div class='highlight'><pre> update: (collection, obj, options, callback) => if not callback? and lodash.isFunction options callback = options options = {}</pre></div> Object or filter is mandatory. <div class='highlight'><pre> if not obj? if settings.logger.autoLogErrors logger.error "Database.update", "No object specified. Abort!", collection if callback? callback "Database.update: no object (second argument) was specified." return false</pre></div> No DB set? Throw exception. <div class='highlight'><pre> if not @db? if settings.logger.autoLogErrors logger.error "Database.update", "The db is null or was not initialized. Abort!", collection if callback? callback "Database.update: the db was not initialized, please check database settings and call its 'init' method." return false</pre></div> Create the DB callback helper. <div class='highlight'><pre> dbCallback = (err, result) => if callback? result = @normalizeId(result) if settings.database.normalizeId callback err, result</pre></div> Set collection object. <div class='highlight'><pre> dbCollection = @db.collection collection</pre></div> Make sure the ID is converted to ObjectID. <div class='highlight'><pre> if obj._id? id = mongo.ObjectID.createFromHexString obj._id.toString() else if obj.id? and settings.database.normalizeId id = mongo.ObjectID.createFromHexString obj.id.toString()</pre></div> Make sure options is valid. <div class='highlight'><pre> options = {} if not options?</pre></div> If a <code>filter</code> option was set, use it as the query filter otherwise use the “_id” property. <div class='highlight'><pre> if options.filter? filter = options.filter else filter = {"_id": id}</pre></div> If options patch is set, replace specified document properties only instead of replacing the whole document. <div class='highlight'><pre> if options.patch docData = {$set: obj} else docData = obj</pre></div> Set default options. <div class='highlight'><pre> options = lodash.defaults options, {"new": true, "insert": false}</pre></div> Execute update! <div class='highlight'><pre> dbCollection.update filter, docData, options, dbCallback if id? logger.debug "Database.update", collection, options, "ID: #{id}" else logger.debug "Database.update", collection, options, "New document."</pre></div> DEPRECATED! Alias for <code>update</code>, will be removed soon. <div class='highlight'><pre> set: => console.warn "Database.set", "Method is deprecated, use .insert or .update instead!" @update.apply this, arguments</pre></div> Delete an object from the database. The <code>obj</code> argument can be either the document itself, or its integer/string ID. @param [String] collection The collection name. @param [String, Object] filter If a string or number, assume it’s the document ID. Otherwise assume the document itself. @param [Method] callback Callback (err, result) when operation has finished. <div class='highlight'><pre> remove: (collection, filter, callback) => if not callback? and lodash.isFunction options callback = options options = {}</pre></div> Filter is mandatory. <div class='highlight'><pre> if not filter? if settings.logger.autoLogErrors logger.error "Database.remove", "No filter specified. Abort!", collection if callback? callback "Database.remove: no filter (second argument) was specified." return false</pre></div> No DB set? Throw exception. <div class='highlight'><pre> if not @db? if settings.logger.autoLogErrors logger.error "Database.remove", "The db is null or was not initialized. Abort!", collection if callback? callback "Database.remove: the db was not initialized, please check database settings and call its 'init' method." return false</pre></div> Check it the <code>obj</code> is the model itself, or only the ID string / number. <div class='highlight'><pre> if filter._id? id = filter._id else if filter.id and settings.database.normalizeId id = filter.id else t = typeof filter id = filter if t is "string" or t is "integer"</pre></div> Create the DB callback helper. <div class='highlight'><pre> dbCallback = (err, result) => if callback? result = @normalizeId(result) if settings.database.normalizeId callback err, result</pre></div> Set collection object and remove specified object from the database. <div class='highlight'><pre> dbCollection = @db.collection collection</pre></div> Remove object by ID or filter. <div class='highlight'><pre> if id? and id isnt "" dbCollection.removeById id, dbCallback else dbCollection.remove filter, dbCallback logger.debug "Database.remove", collection, filter</pre></div> Alias for <code>remove</code>. <div class='highlight'><pre> del: => @remove.apply this, arguments</pre></div> Count documents from the database. A <code>collection</code> must be specified. If no <code>filter</code> is not passed then count all documents. @param [String] collection The collection name. @param [Object] filter Optional, keys-values filter of documents to be counted. @param [Method] callback Callback (err, result) when operation has finished. <div class='highlight'><pre> count: (collection, filter, callback) => if not callback? and lodash.isFunction filter callback = filter filter = {}</pre></div> Callback is mandatory! <div class='highlight'><pre> if not callback? if settings.logger.autoLogErrors logger.error "Database.count", "No callback specified. Abort!", collection, filter throw new Error "Database.count: a callback (last argument) must be specified."</pre></div> Create the DB callback helper. <div class='highlight'><pre> dbCallback = (err, result) => if callback? logger.debug "Database.count", collection, filter, "Result #{result}" callback err, result</pre></div> MongoDB has a built-in count so use it. <div class='highlight'><pre> dbCollection = @db.collection collection dbCollection.count filter, dbCallback</pre></div> <h2 id="helper-methods">HELPER METHODS</h2> Helper to transform MongoDB document “_id” to “id”. @param [Object] result The document or result to be normalized. @return [Object] Returns the normalized document. <div class='highlight'><pre> normalizeId: (result) => return if not result? isArray = lodash.isArray result or lodash.isArguments result</pre></div> Check if result is a collection / array or a single document. <div class='highlight'><pre> if isArray for obj in result if obj["_id"]? obj["id"] = obj["_id"].toString() delete obj["_id"] else if result["_id"]? result["id"] = result["_id"].toString() delete result["_id"] return result</pre></div> Helper to set the current DB object. Can be called externally but ideally you should control the connection string by updating your app settings.json file. @param [Object] connString The connection string, for example user:password@hostname/dbname. @param [Object] options Additional options to be passed when creating the DB connection object. <div class='highlight'><pre> setDb: (connString, options) => @db = mongo.db connString, options</pre></div> Safe logging, strip username and password. <div class='highlight'><pre> sep = connString.indexOf "@" connStringSafe = connString connStringSafe = connStringSafe.substring sep if sep > 0 logger.debug "Database.setDb", connStringSafe, options</pre></div> <h2 id="singleton-implementation-">Singleton implementation.</h2> <div class='highlight'><pre>Database.getInstance = -> @instance = new Database() if not @instance? return @instance module.exports = exports = Database.getInstance()</pre></div> <div class="fleur">h</div> </div> </div> </body> </html>