feat(schema): add collectionOptions option to schemas

docs/guide.md

@@ -526,6 +526,7 @@ Valid options:
 - [skipVersioning](#skipVersioning)
 - [timestamps](#timestamps)
 - [storeSubdocValidationError](#storeSubdocValidationError)
+- [collectionOptions](#collectionOptions)
 - [methods](#methods)
 - [query](#query-helpers)
 
@@ -1399,6 +1400,30 @@ const Parent = mongoose.model('Parent', parentSchema);
 new Parent({ child: {} }).validateSync().errors;
 ```
 
+<h2 id="collectionOptions">
+  <a href="#collectionOptions">
+    option: collectionOptions
+  </a>
+</h2>
+
+Options like [`collation`](#collation) and [`capped`](#capped) affect the options Mongoose passes to MongoDB when creating a new collection.
+Mongoose schemas support most [MongoDB `createCollection()` options](https://www.mongodb.com/docs/manual/reference/method/db.createCollection/), but not all.
+You can use the `collectionOptions` option to set any `createCollection()` options; Mongoose will use `collectionOptions` as the default values when calling `createCollection()` for your schema.
+
+```javascript
+const schema = new Schema({ name: String }, {
+  autoCreate: false,
+  collectionOptions: {
+    capped: true,
+    max: 1000
+  }
+});
+const Test = mongoose.model('Test', schema);
+
+// Equivalent to `createCollection({ capped: true, max: 1000 })`
+await Test.createCollection();
+```
+
 <h2 id="es6-classes"><a href="#es6-classes">With ES6 Classes</a></h2>
 
 Schemas have a [`loadClass()` method](api/schema.html#schema_Schema-loadClass)

lib/model.js

@@ -1370,6 +1370,14 @@ Model.createCollection = async function createCollection(options) {
     throw new MongooseError('Model.createCollection() no longer accepts a callback');
   }
 
+  const collectionOptions = this &&
+    this.schema &&
+    this.schema.options &&
+    this.schema.options.collectionOptions;
+  if (collectionOptions != null) {
+    options = Object.assign({}, collectionOptions, options);
+  }
+
   const schemaCollation = this &&
     this.schema &&
     this.schema.options &&

lib/schema.js

@@ -80,6 +80,7 @@ let id = 0;
  * - [timestamps](https://mongoosejs.com/docs/guide.html#timestamps): object or boolean - defaults to `false`. If true, Mongoose adds `createdAt` and `updatedAt` properties to your schema and manages those properties for you.
  * - [pluginTags](https://mongoosejs.com/docs/guide.html#pluginTags): array of strings - defaults to `undefined`. If set and plugin called with `tags` option, will only apply that plugin to schemas with a matching tag.
  * - [virtuals](https://mongoosejs.com/docs/tutorials/virtuals.html#virtuals-via-schema-options): object - virtuals to define, alias for [`.virtual`](https://mongoosejs.com/docs/api/schema.html#Schema.prototype.virtual())
+ * - [collectionOptions]: object with options passed to [`createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection/) when calling `Model.createCollection()` or `autoCreate` set to true.
  *
  * #### Options for Nested Schemas:
  *

test/model.test.js

@@ -7028,6 +7028,19 @@ describe('Model', function() {
       assert(bypass);
     });
   });
+
+  it('respects schema-level `collectionOptions` for setting options to createCollection()', async function() {
+    const testSchema = new Schema({
+      name: String
+    }, { collectionOptions: { capped: true, size: 1024 } });
+    const TestModel = db.model('Test', testSchema);
+    await TestModel.init();
+    await TestModel.collection.drop();
+    await TestModel.createCollection();
+
+    const isCapped = await TestModel.collection.isCapped();
+    assert.ok(isCapped);
+  });
 });
 
 

types/schemaoptions.d.ts

@@ -49,6 +49,9 @@ declare module 'mongoose' {
     /** Sets a default collation for every query and aggregation. */
     collation?: mongodb.CollationOptions;
 
+    /** Arbitrary options passed to `createCollection()` */
+    collectionOptions?: mongodb.CreateCollectionOptions;
+
     /** The timeseries option to use when creating the model's collection. */
     timeseries?: mongodb.TimeSeriesCollectionOptions;