Update documentation of fetch methods

lib/base/model.js

@@ -947,7 +947,7 @@ _.each(modelMethods, function(method) {
  *       throw new Error('Email and password are both required')
  *
  *     return new this({email: email.toLowerCase()})
- *       .fetch({require: true})
+ *       .fetch()
  *       .tap(function(customer) {
  *         if (!compare(password, customer.get('password'))
  *           throw new Error('Invalid password')

lib/collection.js

@@ -96,16 +96,16 @@ const BookshelfCollection = (module.exports = CollectionBase.extend(
 
     /**
      * 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
+     * resetting the collection when they arrive. If you do not wish to trigger
+     * an error if the fetched collection is empty, pass `{require: false}` 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.*
+     * 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
@@ -116,8 +116,9 @@ const BookshelfCollection = (module.exports = CollectionBase.extend(
      *
      * @fires Collection#fetched
      * @throws {Collection.EmptyError}
-     *   Upon a sucessful query resulting in no records returned. Only fired if `require: true` is
-     *   passed as an option.
+     *   Thrown if no records are found. You can pass the `require: false` option
+     *   to override this behavior or set it at the model level for all fetch
+     *   operations with the {@link Model#requireFetch} option.
      * @param {Object=} options
      * @param {Boolean} [options.require=true]
      *   Whether or not to throw a {@link Collection.EmptyError} if no records are found.
@@ -228,7 +229,7 @@ const BookshelfCollection = (module.exports = CollectionBase.extend(
      * @param {Object=}  options
      * @param {Boolean} [options.require=true]
      *   Rejects the returned Promise with a {@link Model.NotFoundError} if no records can be
-     *   fetched from the databse.
+     *   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.
@@ -495,8 +496,9 @@ const BookshelfCollection = (module.exports = CollectionBase.extend(
        * @class Collection.EmptyError
        * @description
        *   Thrown when no records are found by {@link Collection#fetch fetch},
-       *   {@link Model#fetchAll}, or {@link Model.fetchAll} when called with
-       *   the `{require: true}` option.
+       *   {@link Model#fetchAll}, {@link Model#fetchPage} or
+       *   {@link Model.fetchAll} by default. This behavior can be overrided with
+       *   the {@link Model#requireFetch} option.
        */
       child.EmptyError = createError(this.EmptyError);
     }

lib/errors.js

@@ -20,17 +20,16 @@ function ModelNotResolvedError() {
 }
 
 module.exports = {
-  // Thrown when the model is not found and {require: true} is passed in the fetch options
+  // Thrown when a model is not found.
   NotFoundError: createError('NotFoundError'),
 
-  // Thrown when the collection is empty and {require: true} is passed in model.fetchAll or
-  // collection.fetch
+  // Thrown when the collection is empty upon fetching it.
   EmptyError: createError('EmptyError'),
 
-  // Thrown when an update affects no rows and {require: true} is passed in model.save.
+  // Thrown when an update affects no rows
   NoRowsUpdatedError: createError('NoRowsUpdatedError'),
 
-  // Thrown when a delete affects no rows and {require: true} is passed in model.destroy.
+  // Thrown when a delete affects no rows.
   NoRowsDeletedError: createError('NoRowsDeletedError'),
 
   ModelNotResolvedError

lib/model.js

@@ -585,7 +585,7 @@ const BookshelfModel = ModelBase.extend(
      *   options that can be specified.
      * @param {boolean} [options.require=true]
      *   Rejects the returned Promise with a {@link Collection.EmptyError} if no records can be
-     *   fetched from the databse.
+     *   fetched from the database.
      * @param {number} [options.pageSize]
      *   How many models to include in each page, defaulting to 10 if not specified. Used only together with the `page`
      *   option.
@@ -785,24 +785,26 @@ const BookshelfModel = ModelBase.extend(
     /**
      * Fetches a collection of {@link Model models} from the database, using any
      * query parameters currently set on the model to form a select query. Returns
-     * a Promise, which will resolve with the fetched collection. If you wish to
-     * trigger an error if no models are found, pass `{require: true}` as one of
-     * the options.
+     * a Promise, which will resolve with the fetched collection. If there are no
+     * results it will trigger a {@link Collection.EmptyError}. If you wish to
+     * return an empty collection if no models are found, pass the
+     * `require: false` option. You can override this behavior at the model level
+     * for all fetch calls with the {@link Model#requireFetch} option.
      *
-     * If you need to constrain the query performed by fetch, you can call the
-     * {@link Model#query query} method before calling fetch.
+     * If you need to constrain the results, you can call the {@link Model#query query}
+     * or {@link Model#where where} methods before calling this method.
      *
      * @method Model#fetchAll
      * @param {Object} [options] Set of options to modify the request.
      * @param {Boolean} [options.require=true]
-     *   Rejects the returned Promise with a {@link Collection.EmptyError} if no records can be
-     *   fetched from the databse.
+     *   Whether or not to reject with a {@link Collection.EmptyError} if no records can be
+     *   fetched from the database.
      * @param {Transaction} [options.transacting] Optionally run the query in a transaction.
      * @fires Model#fetching:collection
      * @fires Model#fetched:collection
      * @throws {Collection.EmptyError}
      *   This error is used to reject the Promise in the event of an empty response from the
-     *   database if the `require: true` option is used.
+     *   database.
      * @returns {Promise} A Promise resolving to the fetched {@link Collection collection}.
      */
     fetchAll(options) {
@@ -1459,30 +1461,26 @@ const BookshelfModel = ModelBase.extend(
   {
     extended(child) {
       /**
-       * @class Model.NotFoundError
-       * @description
+       * Thrown when no records are found by {@link Model#fetch fetch} or
+       * {@link Model#refresh} unless called with the `{require: false}` option.
        *
-       *   Thrown when no records are found by {@link Model#fetch fetch} or
-       *   {@link Model#refresh} when called with the
-       *   `{require: true}` option.
+       * @class Model.NotFoundError
        */
       child.NotFoundError = createError(this.NotFoundError);
 
       /**
-       * @class Model.NoRowsUpdatedError
-       * @description
+       * Thrown when no records are saved by {@link Model#save save}
+       * unless called with the `{require: false}` option.
        *
-       *   Thrown when no records are saved by {@link Model#save save}
-       *   unless called with the `{require: false}` option.
+       * @class Model.NoRowsUpdatedError
        */
       child.NoRowsUpdatedError = createError(this.NoRowsUpdatedError);
 
       /**
-       * @class Model.NoRowsDeletedError
-       * @description
+       * Thrown when no record is deleted by {@link Model#destroy destroy}
+       * unless called with the `{require: false}` option.
        *
-       *   Thrown when no record is deleted by {@link Model#destroy destroy}
-       *   if called with the `{require: true}` option.
+       * @class Model.NoRowsDeletedError
        */
       child.NoRowsDeletedError = createError(this.NoRowsDeletedError);
     },

lib/relation.js

@@ -934,9 +934,7 @@ const PivotHelpers = {
 
     return joinModel
       .set(fks)
-      .fetch({
-        require: true
-      })
+      .fetch()
       .then(function(instance) {
         if (method === 'delete') {
           return instance.destroy(options);

tutorials/models.md

@@ -27,7 +27,7 @@ const Customer = bookshelf.model('Customer', {
   // Static class properties and methods
   login: Promise.method((email, password) => {
     return new this({email})
-      .fetch({require: true})
+      .fetch()
       .tap((customer) => {
         return bcrypt.compareAsync(password, customer.get('password'))
           .then((valid) => {