@depup/bookshelf 1.2.0-depup.0

package/lib/collection.js

@@ -0,0 +1,545 @@
+const _ = require('lodash');
+const Sync = require('./sync');
+const Helpers = require('./helpers');
+const EagerRelation = require('./eager');
+const Errors = require('./errors');
+const CollectionBase = require('./base/collection');
+const Promise = require('bluebird');
+const createError = require('create-error');
+
+/**
+ * When creating a {@link Collection}, you may choose to pass in the initial array of
+ * {@link Model models}. The collection's {@link Collection#comparator comparator} may be included
+ * as an option. Passing `false` as the comparator option will prevent sorting. If you define an
+ * {@link Collection#initialize initialize} function, it will be invoked when the collection is
+ * created.
+ *
+ * If you would like to customize the Collection used by your models when calling
+ * {@link Model#fetchAll} or {@link Model#fetchPage} you can use the following process:
+ *
+ *     const Test = bookshelf.model('Test', {
+ *       tableName: 'test'
+ *     }, {
+ *       collection(...args) {
+ *         return new Tests(...args)
+ *       }
+ *     })
+ *     const Tests = bookshelf.collection('Tests', {
+ *       get model() {
+ *         return Test
+ *       },
+ *       initialize () {
+ *         this.constructor.__super__.initialize.apply(this, arguments)
+ *         // Collection will emit fetching event as expected even on eager queries.
+ *         this.on('fetching', () => {})
+ *       },
+ *       doStuff() {
+ *         // This method will be available in the results collection returned
+ *         // by Test.fetchAll() and Test.fetchPage()
+ *       }
+ *     })
+ *
+ * @example
+ * const TabSet = bookshelf.collection('TabSet', {
+ *   model: Tab
+ * })
+ * const tabs = new TabSet([tab1, tab2, tab3])
+ *
+ * @class Collection
+ * @extends CollectionBase
+ * @classdesc
+ *   Collections are ordered sets of models returned from the database, from a
+ *   {@link Model#fetchAll fetchAll} call.
+ * @param {(Model[])=} models Initial array of models.
+ * @param {Object=} options
+ * @param {Boolean} [options.comparator=false]
+ *   {@link Collection#comparator Comparator} for collection, or `false` to disable sorting.
+ */
+const BookshelfCollection = (module.exports = CollectionBase.extend(
+  /** @lends Collection.prototype */
+  {
+    /**
+     * Used to define relationships where a {@link Model#hasMany hasMany} or
+     * {@link Model#belongsToMany belongsToMany} relation passes "through" an `Interim` model. This
+     * is exactly like the equivalent {@link Model#through model method} except that it applies to
+     * the collections that the above mentioned relation methods return instead of individual
+     * models.
+     *
+     * A good example of where this would be useful is if a book {@link Model#hasMany hasMany}
+     * paragraphs *through* chapters. See the example above for how this can be used.
+     *
+     * @example
+     * const Chapter = bookshelf.model('Chapter', {
+     *   tableName: 'chapters',
+     *   paragraphs() {
+     *     return this.hasMany(Paragraph)
+     *   }
+     * })
+     *
+     * const Paragraph = bookshelf.model('Paragraph', {
+     *   tableName: 'paragraphs',
+     *   chapter() {
+     *     return this.belongsTo(Chapter)
+     *   }
+     * })
+     *
+     * const Book = bookshelf.model('Book', {
+     *   tableName: 'books',
+
+     *   // Find all paragraphs associated with this book, by
+     *   // passing through the "Chapter" model.
+     *   paragraphs() {
+     *     return this.hasMany(Paragraph).through(Chapter)
+     *   }
+     * })
+     *
+     * @param {Model} Interim Pivot model.
+     * @param {string} [throughForeignKey]
+     *   Foreign key in this collection's model. This is the model that the `hasMany` or
+     *   `belongsToMany` relations return. By default, the `foreignKey` is assumed to be the
+     *   singular form of the `Target` model's tableName, followed by `_id` /
+     *   `_{{{@link Model#idAttribute idAttribute}}}`.
+     * @param {string} [otherKey]
+     *   Foreign key in the `Interim` model. By default, the `otherKey` is assumed to be the
+     *   singular form of this model's tableName, followed by `_id` /
+     *   `_{{{@link Model#idAttribute idAttribute}}}`.
+     * @param {string} [throughForeignKeyTarget]
+     *   Column in this collection's model which `throughForeignKey` references, if other than the
+     *   default of the model's `id` / `{@link Model#idAttribute idAttribute}`.
+     * @param {string} [otherKeyTarget]
+     *   Column in the `Interim` model which `otherKey` references, if other than `id` /
+     *   `{@link Model#idAttribute idAttribute}`.
+     * @returns {Collection} The related but empty collection.
+     */
+    through: function(Interim, throughForeignKey, otherKey, throughForeignKeyTarget, otherKeyTarget) {
+      return this.relatedData.through(this, Interim, {
+        throughForeignKey,
+        otherKey,
+        throughForeignKeyTarget,
+        otherKeyTarget
+      });
+    },
+
+    /**
+     * Fetch the default set of models for this collection from the database,
+     * resetting the collection when they arrive. If you wish to trigger an
+     * error if the fetched collection is empty, pass `{require: true}` as one
+     * of the options to the {@link Collection#fetch fetch} call. A {@link
+     * Collection#fetched "fetched"} event will be fired when records are
+     * successfully retrieved. If you need to constrain the query performed by
+     * `fetch`, you can call the {@link Collection#query query} method before
+     * calling `fetch`.
+     *
+     * If you'd like to only fetch specific columns, you may specify a `columns`
+     * property in the options for the `fetch` call.
+     *
+     * The `withRelated` option may be specified to fetch the models of the
+     * collection, eager loading any specified {@link Relation relations} named on
+     * the model. A single property, or an array of properties can be specified as
+     * a value for the `withRelated` property. The results of these relation
+     * queries will be loaded into a relations property on the respective models,
+     * may be retrieved with the {@link Model#related related} method.
+     *
+     * @fires Collection#fetched
+     * @throws {Collection.EmptyError} Thrown if no records are found.
+     * @param {Object=} options
+     * @param {Boolean} [options.require=false]
+     *   Whether or not to throw a {@link Collection.EmptyError} if no records are found.
+     *   You can pass the `require: true` option to override this behavior.
+     * @param {string|string[]} [options.withRelated=[]]
+     *   A relation, or list of relations, to be eager loaded as part of the `fetch` operation.
+     * @param {boolean} [options.debug=false]
+     *   Whether to enable debugging mode or not. When enabled will show information about the
+     *   queries being run.
+     * @returns {Promise<Collection>}
+     */
+    fetch: Promise.method(function(options) {
+      options = options ? _.clone(options) : {};
+      return (
+        this.sync(options)
+          .select()
+          .bind(this)
+          .tap(function(response) {
+            if (!response || response.length === 0) {
+              throw new this.constructor.EmptyError('EmptyResponse');
+            }
+          })
+
+          // Now, load all of the data onto the collection as necessary.
+          .tap(function(response) {
+            return this._handleResponse(response, options);
+          })
+
+          // If the "withRelated" is specified, we also need to eager load all of the
+          // data on the collection, as a side-effect, before we ultimately jump into the
+          // next step of the collection. Since the `columns` are only relevant to the current
+          // level, ensure those are omitted from the options.
+          .tap(function(response) {
+            if (options.withRelated) {
+              return this._handleEager(response, _.omit(options, 'columns'));
+            }
+          })
+          .tap(function(response) {
+            /**
+             * @event Collection#fetched
+             * @tutorial events
+             *
+             * @description
+             * Fired after a `fetch` operation. A promise may be returned from the
+             * event handler for async behaviour.
+             *
+             * @param {Collection} collection The collection performing the {@link Collection#fetch}.
+             * @param {Object} response Knex query response.
+             * @param {Object} options Options object passed to {@link Collection#fetch fetch}.
+             * @returns {Promise}
+             */
+            return this.triggerThen('fetched', this, response, options);
+          })
+          .catch(this.constructor.EmptyError, function(err) {
+            if (options.require) throw err;
+            this.reset([], {silent: true});
+          })
+          .return(this)
+      );
+    }),
+
+    fetchPage(options) {
+      if (!options) options = {};
+      return Helpers.fetchPage.call(this, options);
+    },
+
+    /**
+     * Get the number of records in the collection's table.
+     *
+     * @example
+     * // select count(*) from shareholders where company_id = 1 and share &gt; 0.1;
+     * new Company({id: 1})
+     *   .shareholders()
+     *   .where('share', '>', '0.1')
+     *   .count()
+     *   .then((count) => {
+     *     assert(count === 3)
+     *   })
+     *
+     * @since 0.8.2
+     * @see Model#count
+     * @param {string} [column='*']
+     *   Specify a column to count. Rows with `null` values in this column will be excluded.
+     * @param {Object} [options] Hash of options.
+     * @returns {Promise<number|string>}
+     */
+    count: Promise.method(function(column, options) {
+      if (!_.isString(column)) {
+        options = column;
+        column = undefined;
+      }
+      if (options) options = _.clone(options);
+      return this.sync(options).count(column);
+    }),
+
+    /**
+     * Fetch and return a single {@link Model model} from the collection,
+     * maintaining any {@link Relation relation} data from the collection, and
+     * any {@link Collection#query query} parameters that have already been passed
+     * to the collection. Especially helpful on relations, where you would only
+     * like to return a single model from the associated collection.
+     *
+     * @example
+     * // select * from authors where site_id = 1 and id = 2 limit 1;
+     * new Site({id:1})
+     *   .authors()
+     *   .query({where: {id: 2}})
+     *   .fetchOne()
+     *   .then(function(model) {
+     *     // ...
+     *   });
+     *
+     * @param {Object=}  options
+     * @param {Boolean} [options.require=true]
+     *   Whether or not to reject the returned Promise with a {@link Model.NotFoundError} if no
+     *   records can be fetched from the database.
+     * @param {(string|string[])} [options.columns='*']
+     *   Limit the number of columns fetched.
+     * @param {Transaction} [options.transacting] Optionally run the query in a transaction.
+     * @param {string} [options.lock]
+     *  Type of row-level lock to use. Valid options are `forShare` and
+     *  `forUpdate`. This only works in conjunction with the `transacting`
+     *  option, and requires a database that supports it.
+     * @param {boolean} [options.debug=false]
+     *   Whether to enable debugging mode or not. When enabled will show information about the
+     *   queries being run.
+     * @throws {Model.NotFoundError}
+     * @returns {Promise<Model|null>}
+     *  A promise resolving to the fetched {@link Model} or `null` if none exists and the
+     *  `require: false` option is passed or {@link Model#requireFetch requireFetch} is set to
+     *  `false`.
+     */
+    fetchOne: Promise.method(function(options) {
+      const model = new this.model();
+      model._knex = this.query().clone();
+      this.resetQuery();
+      if (this.relatedData) model.relatedData = this.relatedData;
+      return model.fetch(options);
+    }),
+
+    /**
+     * This method is used to eager load relations onto a Collection, in a similar way that the
+     * `withRelated` property works on {@link Collection#fetch fetch}. Nested eager loads can be
+     * specified by separating the nested relations with `.`.
+     *
+     * @param {string|string[]} relations The relation, or relations, to be loaded.
+     * @param {Object} [options] Hash of options.
+     * @param {Transaction} [options.transacting]
+     * @param {string} [options.lock]
+     *   Type of row-level lock to use. Valid options are `forShare` and `forUpdate`. This only
+     *   works in conjunction with the `transacting` option, and requires a database that supports
+     *   it.
+     * @param {boolean} [options.debug=false]
+     *   Whether to enable debugging mode or not. When enabled will show information about the
+     *   queries being run.
+     * @returns {Promise<Collection>} A promise resolving to this {@link Collection collection}.
+     */
+    load: Promise.method(function(relations, options) {
+      if (!Array.isArray(relations)) relations = [relations];
+      options = _.assignIn({}, options, {
+        shallow: true,
+        withRelated: relations
+      });
+      return new EagerRelation(this.models, this.toJSON(options), new this.model()).fetch(options).return(this);
+    }),
+
+    /**
+     * Convenience method to create a new {@link Model model} instance within a
+     * collection. Equivalent to instantiating a model with a hash of {@link
+     * Model#attributes attributes}, {@link Model#save saving} the model to the
+     * database then adding the model to the collection.
+     *
+     * When used on a relation, `create` will automatically set foreign key
+     * attributes before persisting the `Model`.
+     *
+     * @example
+     * const { courses, ...attributes } = req.body;
+     *
+     * Student.forge(attributes).save().tap(student =>
+     *   Promise.map(courses, course => student.related('courses').create(course))
+     * ).then(student =>
+     *   res.status(200).send(student)
+     * ).catch(error =>
+     *   res.status(500).send(error.message)
+     * );
+     *
+     * @param {Object} model A set of attributes to be set on the new model.
+     * @param {Object} [options]
+     * @param {Transaction} [options.transacting]
+     * @param {boolean} [options.debug=false]
+     *   Whether to enable debugging mode or not. When enabled will show information about the
+     *   queries being run.
+     * @returns {Promise<Model>} A promise resolving with the new {@link Model model}.
+     */
+    create: Promise.method(function(model, options) {
+      options = options != null ? _.clone(options) : {};
+      const relatedData = this.relatedData;
+      model = this._prepareModel(model, options);
+
+      // If we've already added things on the query chain, these are likely intended for the model.
+      if (this._knex) {
+        model._knex = this._knex;
+        this.resetQuery();
+      }
+      return Helpers.saveConstraints(model, relatedData)
+        .save(null, options)
+        .bind(this)
+        .then(function() {
+          if (relatedData && relatedData.type === 'belongsToMany') {
+            return this.attach(model, _.omit(options, 'query'));
+          }
+        })
+        .then(function() {
+          this.add(model, options);
+        })
+        .return(model);
+    }),
+
+    /**
+     * Used to reset the internal state of the current query builder instance. This method is called
+     * internally each time a database action is completed by {@link Sync}.
+     *
+     * @private
+     * @returns {Collection} Self, this method is chainable.
+     */
+    resetQuery: function() {
+      this._knex = null;
+      return this;
+    },
+
+    /**
+     * This method is used to tap into the underlying Knex query builder instance for the current
+     * collection.
+     *
+     * If called with no arguments, it will return the query builder directly, otherwise it will
+     * call the specified `method` on the query builder, applying any additional arguments from the
+     * `collection.query` call.
+     *
+     * If the `method` argument is a function, it will be called with the Knex query builder as the
+     * context and the first argument.
+     *
+     * @see {@link http://knexjs.org/#Builder Knex `QueryBuilder`}
+     * @example
+     * let qb = collection.query();
+     *     qb.where({id: 1}).select().then(function(resp) {
+     *       // ...
+     *     });
+     *
+     * collection.query(function(qb) {
+     *   qb.where('id', '>', 5).andWhere('first_name', '=', 'Test');
+     * }).fetch()
+     *   .then(function(collection) {
+     *     // ...
+     *   });
+     *
+     * collection
+     *   .query('where', 'other_id', '=', '5')
+     *   .fetch()
+     *   .then(function(collection) {
+     *     // ...
+     *   });
+     *
+     * @param {function|Object|...string=} arguments The query method.
+     * @returns {Collection|QueryBuilder}
+     *   This collection or, if called with no arguments, the underlying query builder.
+     */
+    query: function() {
+      return Helpers.query(this, Array.from(arguments));
+    },
+
+    /**
+     * This is used as convenience for the most common {@link Collection#query query} method:
+     * adding a `WHERE` clause to the builder. Any additional knex methods may be accessed using
+     * {@link Collection#query query}.
+     *
+     * Accepts either `key, value` syntax, or a hash of attributes to constrain the results.
+     *
+     * @example
+     * collection
+     *   .where('favorite_color', '<>', 'green')
+     *   .fetch()
+     *   .then(results => {
+     *     // ...
+     *   })
+     *
+     * // or
+     *
+     * collection
+     *   .where('favorite_color', 'red')
+     *   .fetch()
+     *   .then(results => {
+     *     // ...
+     *   })
+     *
+     * collection
+     *   .where({favorite_color: 'red', shoe_size: 12})
+     *   .fetch()
+     *   .then(results => {
+     *     // ...
+     *   })
+     *
+     * @see Collection#query
+     * @param {Object|...string} conditions
+     *   Either `key, [operator], value` syntax, or a hash of attributes to match. Note that these
+     *   must be formatted as they are in the database, not how they are stored after
+     *   {@link Model#parse}.
+     * @returns {Collection} Self, this method is chainable.
+     */
+    where() {
+      return this.query.apply(this, ['where'].concat(Array.from(arguments)));
+    },
+
+    /**
+     * Specifies the column to sort on and sort order.
+     *
+     * The order parameter is optional, and defaults to 'ASC'. You may
+     * also specify 'DESC' order by prepending a hyphen to the sort column
+     * name. `orderBy("date", 'DESC')` is the same as `orderBy("-date")`.
+     *
+     * Unless specified using dot notation (i.e., "table.column"), the default
+     * table will be the table name of the model `orderBy` was called on.
+     *
+     * @since 0.9.3
+     * @example
+     * Cars.forge().orderBy('color', 'ASC').fetch()
+     *    .then(function (rows) { // ...
+     *
+     * @param {string} column Column to sort on.
+     * @param {string} order Ascending (`'ASC'`) or descending (`'DESC'`) order.
+     */
+    orderBy() {
+      return Helpers.orderBy.apply(null, [this].concat(Array.from(arguments)));
+    },
+
+    /**
+     * Creates and returns a new `Bookshelf.Sync` instance.
+     *
+     * @private
+     */
+    sync: function(options) {
+      return new Sync(this, options);
+    },
+
+    /* Ensure that QueryBuilder is copied on clone. */
+    clone() {
+      const cloned = BookshelfCollection.__super__.clone.apply(this, arguments);
+      if (this._knex != null) {
+        cloned._knex = cloned._builder(this._knex.clone());
+      }
+      return cloned;
+    },
+
+    /**
+     * Handles the response data for the collection, returning from the collection's `fetch` call.
+     *
+     * @private
+     */
+    _handleResponse: function(response, options) {
+      const relatedData = this.relatedData;
+
+      this.set(response, {
+        merge: options.merge,
+        remove: options.remove,
+        silent: true,
+        parse: true
+      }).invokeMap(function() {
+        this.formatTimestamps();
+        this._reset();
+        this._previousAttributes = _.cloneDeep(this.attributes);
+      });
+
+      if (relatedData && relatedData.isJoined()) {
+        relatedData.parsePivot(this.models);
+      }
+    },
+
+    /**
+     * Handle the related data loading on the collection.
+     *
+     * @private
+     */
+    _handleEager: function(response, options) {
+      return new EagerRelation(this.models, response, new this.model()).fetch(options);
+    }
+  },
+  /** @lends Collection */
+  {
+    extended: function(child) {
+      /**
+       * @class Collection.EmptyError
+       * @description
+       *   Thrown by default when no records are found by {@link Collection#fetch fetch} or
+       *   {@link Collection#fetchOne}. This behavior can be overrided with the
+       *   {@link Model#requireFetch} option.
+       */
+      child.EmptyError = createError(this.EmptyError);
+    }
+  }
+));
+
+BookshelfCollection.EmptyError = Errors.EmptyError;

package/lib/constants.js

@@ -0,0 +1,2 @@
+exports.PIVOT_PREFIX = '_pivot_';
+exports.DEFAULT_TIMESTAMP_KEYS = ['created_at', 'updated_at'];

package/lib/eager.js

@@ -0,0 +1,122 @@
+// EagerRelation
+// ---------------
+'use strict';
+
+const _ = require('lodash');
+const Helpers = require('./helpers');
+const Promise = require('bluebird');
+const EagerBase = require('./base/eager');
+const getAttributeUnique = (models, attribute) => _.uniq(_.map(models, (m) => m.get(attribute)));
+
+// An `EagerRelation` object temporarily stores the models from an eager load,
+// and handles matching eager loaded objects with their parent(s). The
+// `tempModel` is only used to retrieve the value of the relation method, to
+// know the constraints for the eager query.
+class EagerRelation extends EagerBase {
+  // Handles an eager loaded fetch, passing the name of the item we're fetching
+  // for, and any options needed for the current fetch.
+  eagerFetch(relationName, handled, options) {
+    const relatedData = handled.relatedData;
+
+    // skip eager loading for rows where the foreign key isn't set
+    if (relatedData.parentFk === null) return;
+
+    if (relatedData.type === 'morphTo') {
+      return this.morphToFetch(relationName, relatedData, options);
+    }
+
+    return handled
+      .sync(Object.assign({}, options, {parentResponse: this.parentResponse}))
+      .select()
+      .tap((response) => this._eagerLoadHelper(response, relationName, handled, _.omit(options, 'parentResponse')));
+  }
+
+  // Special handler for the eager loaded morph-to relations, this handles the
+  // fact that there are several potential models that we need to be fetching
+  // against.  pairing them up onto a single response for the eager loading.
+  morphToFetch(relationName, relatedData, options) {
+    const columnNames = relatedData.columnNames || [];
+    const morphName = relatedData.morphName;
+    const typeColumn = columnNames[0] === undefined ? `${morphName}_type` : columnNames[0];
+    const idColumn = columnNames[1] === undefined ? `${morphName}_id` : columnNames[1];
+
+    const parentsByType = _.groupBy(this.parent, (model) => {
+      const type = model.get(typeColumn);
+
+      if (!type)
+        throw new Error("The target polymorphic model could not be determined because it's missing the type attribute");
+
+      return type;
+    });
+    const TargetByType = _.mapValues(parentsByType, (parents, type) =>
+      Helpers.morphCandidate(relatedData.candidates, type)
+    );
+
+    return Promise.all(
+      _.map(parentsByType, (parents, type) => {
+        const Target = TargetByType[type];
+        const idAttribute = _.result(Target.prototype, 'idAttribute');
+        const ids = getAttributeUnique(parents, idColumn);
+
+        // Remove `query` from options to not send the same query to all candidates
+        return Target.query('whereIn', idAttribute, ids)
+          .sync(_.assign({}, options, {query: undefined}))
+          .select()
+          .tap((response) => {
+            const clone = relatedData.instance('morphTo', Target, {
+              morphName,
+              columnNames,
+              morphValue: type
+            });
+            return this._eagerLoadHelper(response, relationName, {relatedData: clone}, options);
+          });
+      })
+    ).then(_.flatten);
+  }
+
+  // Handles the eager load for both the `morphTo` and regular cases.
+  _eagerLoadHelper(response, relationName, handled, options) {
+    const relatedData = handled.relatedData;
+    const isEmptyHasOne = response.length === 0 && relatedData.type === 'hasOne';
+    const relatedModels = isEmptyHasOne ? [] : this.pushModels(relationName, handled, response, options);
+
+    return Promise.try(() => {
+      // If there is a response, fetch additional nested eager relations, if any.
+      if (response.length > 0 && options.withRelated) {
+        const relatedModel = relatedData.createModel();
+
+        // If this is a `morphTo` relation, we need to do additional processing
+        // to ensure we don't try to load any relations that don't look to exist.
+        if (relatedData.type === 'morphTo') {
+          const withRelated = this._filterRelated(relatedModel, options);
+          if (withRelated.length === 0) return;
+          options = _.extend({}, options, {withRelated: withRelated});
+        }
+
+        return new EagerRelation(relatedModels, response, relatedModel).fetch(options).return(response);
+      }
+    }).tap(() => {
+      return Promise.map(relatedModels, (model) => model.triggerThen('fetched', model, model.attributes, options));
+    });
+  }
+
+  // Filters the `withRelated` on a `morphTo` relation, to ensure that only valid
+  // relations are attempted for loading.
+  _filterRelated(relatedModel, options) {
+    // By this point, all withRelated should be turned into a hash, so it should
+    // be fairly simple to process by splitting on the dots.
+    return _.reduce(
+      options.withRelated,
+      function(memo, val) {
+        for (const key in val) {
+          const seg = key.split('.')[0];
+          if (_.isFunction(relatedModel[seg])) memo.push(val);
+        }
+        return memo;
+      },
+      []
+    );
+  }
+}
+
+module.exports = EagerRelation;