feat(model): add insertOne() function to insert a single doc

lib/model.js

@@ -2774,6 +2774,49 @@ Model.create = async function create(doc, options) {
   return res;
 };
 
+/**
+ * Shortcut for saving one document to the database.
+ * `MyModel.insertOne(obj, options)` is almost equivalent to `new MyModel(obj).save(options)`.
+ * The difference is that `insertOne()` checks if `obj` is already a document, and checks for discriminators.
+ *
+ * This function triggers the following middleware.
+ *
+ * - `save()`
+ *
+ * #### Example:
+ *
+ *     // Insert one new `Character` document
+ *     await Character.insertOne({ name: 'Jean-Luc Picard' });
+ *
+ *     // Create a new character within a transaction.
+ *     await Character.insertOne({ name: 'Jean-Luc Picard' }, { session });
+ *
+ * @param {Object|Document} docs Document to insert, as a POJO or Mongoose document
+ * @param {Object} [options] Options passed down to `save()`.
+ * @return {Promise}
+ * @api public
+ */
+
+Model.insertOne = async function insertOne(doc, options) {
+  _checkContext(this, 'insertOne');
+
+  const discriminatorKey = this.schema.options.discriminatorKey;
+  const Model = this.discriminators && doc[discriminatorKey] != null ?
+    this.discriminators[doc[discriminatorKey]] || getDiscriminatorByValue(this.discriminators, doc[discriminatorKey]) :
+    this;
+  if (Model == null) {
+    throw new MongooseError(
+      `Discriminator "${doc[discriminatorKey]}" not found for model "${this.modelName}"`
+    );
+  }
+  let toSave = doc;
+  if (!(toSave instanceof Model)) {
+    toSave = new Model(toSave);
+  }
+
+  return await toSave.$save(options);
+};
+
 /**
  * _Requires a replica set running MongoDB >= 3.6.0._ Watches the
  * underlying collection for changes using

test/model.test.js

@@ -8461,6 +8461,37 @@ describe('Model', function() {
       assert.deepStrictEqual(toDrop, []);
     });
   });
+
+  describe('insertOne() (gh-14843)', function() {
+    it('should insert a new document', async function() {
+      const userSchema = new Schema({
+        name: String
+      });
+      const User = db.model('User', userSchema);
+
+      const res = await User.insertOne({ name: 'John' });
+      assert.ok(res instanceof User);
+
+      const doc = await User.findOne({ _id: res._id });
+      assert.equal(doc.name, 'John');
+    });
+
+    it('should support validateBeforeSave: false option', async function() {
+      const userSchema = new Schema({
+        name: {
+          type: String,
+          required: true
+        }
+      });
+      const User = db.model('User', userSchema);
+
+      const res = await User.insertOne({}, { validateBeforeSave: false });
+      assert.ok(res instanceof User);
+
+      const doc = await User.findOne({ _id: res._id });
+      assert.equal(doc.name, undefined);
+    });
+  });
 });
 
 

test/types/models.test.ts

@@ -988,3 +988,13 @@ async function gh14802() {
   const conn2 = mongoose.createConnection('mongodb://127.0.0.1:27017/mongoose_test');
   Model.useConnection(conn2);
 }
+
+async function gh14843() {
+  const schema = new mongoose.Schema({
+    name: String
+  });
+  const Model = model('Test', schema);
+
+  const doc = await Model.insertOne({ name: 'taco' });
+  expectType<ReturnType<(typeof Model)['hydrate']>>(doc);
+}

types/models.d.ts

@@ -576,6 +576,8 @@ declare module 'mongoose' {
       Array<MergeType<THydratedDocumentType, Omit<DocContents, '_id'>>>
     >;
 
+    insertOne<DocContents = AnyKeys<TRawDocType>>(doc: DocContents | TRawDocType, options?: SaveOptions): Promise<THydratedDocumentType>;
+
     /**
      * List all [Atlas search indexes](https://www.mongodb.com/docs/atlas/atlas-search/create-index/) on this model's collection.
      * This function only works when connected to MongoDB Atlas.