@depup/bookshelf 1.2.0-depup.0

package/lib/base/eager.js

@@ -0,0 +1,111 @@
+// Eager Base
+// ---------------
+
+// The EagerBase provides a scaffold for handling with eager relation
+// pairing, by queueing the appropriate related method calls with
+// a database specific `eagerFetch` method, which then may utilize
+// `pushModels` for pairing the models depending on the database need.
+
+'use strict';
+
+const _ = require('lodash');
+const Promise = require('bluebird');
+
+function EagerBase(parent, parentResponse, target) {
+  this.parent = parent;
+  this.parentResponse = parentResponse;
+  this.target = target;
+}
+
+_.extend(EagerBase.prototype, {
+  // This helper function is used internally to determine which relations
+  // are necessary for fetching based on the `model.load` or `withRelated` option.
+  fetch: Promise.method(function(options) {
+    const target = this.target;
+    const handled = (this.handled = {});
+    const withRelated = this.prepWithRelated(options.withRelated);
+    const subRelated = {};
+
+    // Internal flag to determine whether to set the ctor(s) on the `Relation` object.
+    target._isEager = true;
+
+    // Eager load each of the `withRelated` relation item, splitting on '.'
+    // which indicates a nested eager load.
+    for (const key in withRelated) {
+      const related = key.split('.');
+      const relationName = related[0];
+
+      // Add additional eager items to an array, to load at the next level in the query.
+      if (related.length > 1) {
+        const relatedObj = {};
+        subRelated[relationName] = subRelated[relationName] || [];
+        relatedObj[related.slice(1).join('.')] = withRelated[key];
+        subRelated[relationName].push(relatedObj);
+      }
+
+      // Only allow one of a certain nested type per-level.
+      if (handled[relationName]) continue;
+
+      if (!_.isFunction(target[relationName])) {
+        throw new Error(relationName + ' is not defined on the model.');
+      }
+
+      const relation = target[relationName]();
+
+      handled[relationName] = relation;
+    }
+
+    // Delete the internal flag from the model.
+    delete target._isEager;
+
+    // Fetch all eager loaded models, loading them onto
+    // an array of pending deferred objects, which will handle
+    // all necessary pairing with parent objects, etc.
+    const pendingDeferred = [];
+    for (const relationName in handled) {
+      pendingDeferred.push(
+        this.eagerFetch(
+          relationName,
+          handled[relationName],
+          _.extend({}, options, {
+            isEager: true,
+            withRelated: subRelated[relationName],
+            _beforeFn: withRelated[relationName] || function() {}
+          })
+        )
+      );
+    }
+
+    // Return a deferred handler for all of the nested object sync
+    // returning the original response when these syncs & pairings are complete.
+    return Promise.all(pendingDeferred).return(this.parentResponse);
+  }),
+
+  // Prep the `withRelated` object, to normalize into an object, where the value
+  // of each key is a function that is called when running the query.
+  prepWithRelated: function(withRelated) {
+    if (!Array.isArray(withRelated)) withRelated = [withRelated];
+    const obj = {};
+    for (let i = 0, l = withRelated.length; i < l; i++) {
+      const related = withRelated[i];
+      if (_.isString(related)) {
+        obj[related] = function() {};
+      } else {
+        _.extend(obj, related);
+      }
+    }
+    return obj;
+  },
+
+  // Pushes each of the incoming models onto a new `related` array,
+  // which is used to correcly pair additional nested relations.
+  pushModels: function pushModels(relationName, handled, response, options) {
+    const models = this.parent;
+    const relatedData = handled.relatedData;
+    const related = _.map(response, (row) => relatedData.createModel(row));
+
+    return relatedData.eagerPair(relationName, related, models, options);
+  }
+});
+
+module.exports = EagerBase;

package/lib/base/events.js

@@ -0,0 +1,129 @@
+// Events
+// ---------------
+
+'use strict';
+
+const Promise = require('bluebird');
+const events = require('events');
+const _ = require('lodash');
+const EventEmitter = events.EventEmitter;
+const eventNames = (text) => text.split(/\s+/);
+
+/**
+ * @class Events
+ * @description
+ * Base Event class inherited by {@link Model} and {@link Collection}. It's not
+ * meant to be used directly, and is only displayed here for completeness.
+ */
+class Events extends EventEmitter {
+  /**
+   * Registers an event listener. The callback will be invoked whenever the event is fired. The event string may also be
+   * a space-delimited list of several event names.
+   *
+   * @method Events#on
+   * @param {string} nameOrNames The name or space separated names of events to register a callback for.
+   * @param {function} callback That callback to invoke whenever the event is fired.
+   * @return {mixed} The object where this is called on is returned to allow chaining this method call.
+   */
+  on(nameOrNames, callback) {
+    eventNames(nameOrNames).forEach((name) => {
+      super.on(name, callback);
+    });
+    return this;
+  }
+
+  /**
+   * @method Events#off
+   * @description
+   * Remove a previously-bound callback event listener from an object. If no
+   * event name is specified, callbacks for all events will be removed.
+   *
+   * @param {string} nameOrNames
+   *   The name of the event or space separated list of events to stop listening
+   *   to.
+   * @param {function} callback That callback to remove.
+   */
+  off(nameOrNames, callback) {
+    if (nameOrNames == null) {
+      return this.removeAllListeners();
+    }
+
+    eventNames(nameOrNames).forEach((name) => {
+      if (callback === undefined) {
+        return this.removeAllListeners(name);
+      }
+      return this.removeListener(name, callback);
+    });
+    return this;
+  }
+
+  /**
+   * @method Events#trigger
+   * @description
+   * Trigger callbacks for the given event, or space-delimited list of events.
+   * Subsequent arguments to `trigger` will be passed along to the event
+   * callback.
+   *
+   * @param {string} nameOrNames
+   *   The name of the event to trigger. Also accepts a space separated list of
+   *   event names.
+   * @param {...mixed} [args]
+   *   Extra arguments to pass to the event listener callback function.
+   */
+  trigger(nameOrNames) {
+    eventNames(nameOrNames).forEach((name) => {
+      this.emit.apply(this, [name].concat(Array.from(arguments)));
+    });
+    return this;
+  }
+
+  /**
+   * A promise version of {@link Events#trigger}, returning a promise which
+   * resolves with all return values from triggered event handlers. If any of the
+   * event handlers throw an `Error` or return a rejected promise, the promise
+   * will be rejected. Used internally on the {@link Model#event:creating "creating"},
+   * {@link Model#event:updating "updating"}, {@link Model#event:saving "saving"}, and
+   * {@link Model@event:destroying "destroying"} events, and can be helpful when needing
+   * async event handlers (e.g. for validations).
+   *
+   * @method Events#triggerThen
+   * @param {string} name
+   *   The event name or a whitespace-separated list of event names to be triggered.
+   * @param {...mixed} [args] Arguments to be passed to any registered event handlers.
+   * @returns {Promise}
+   *   A promise resolving to the return values of any triggered handlers.
+   */
+  triggerThen(nameOrNames) {
+    const names = eventNames(nameOrNames);
+    const listeners = _.flatMap(names, (name) => this.listeners(name));
+    const args = Array.from(arguments);
+
+    return Promise.mapSeries(listeners, (listener) => listener.apply(this, args.slice(1)));
+  }
+
+  /**
+   * @method Events#once
+   * @description
+   * Just like {@link Events#on}, but causes the bound callback to fire only
+   * once before being removed. Handy for saying "the next time that X happens,
+   * do this". When multiple events are passed in using the space separated
+   * syntax, the event will fire once for every event you passed in, not once
+   * for a combination of all events.
+   *
+   * @param {string} nameOrNames
+   *   The name of the event or space separated list of events to register a
+   *   callback for.
+   * @param {function} callback
+   *   That callback to invoke only once when the event is fired.
+   */
+  once(name, callback) {
+    const wrapped = _.once(function() {
+      this.off(name, wrapped);
+      return callback.apply(this, arguments);
+    });
+    wrapped._callback = callback;
+    return this.on(name, wrapped);
+  }
+}
+
+module.exports = Events;