bookshelf/lib/collection.js

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;