mongoose: complete and factorize FindAndRemove/Delete/Update Query

2026-08-13 05:20:25 +00:00 · 2019-02-15 19:40:32 +01:00
parent 67c5c58e34
commit b7c3a167ab
2 changed files with 106 additions and 90 deletions
@@ -1722,6 +1722,9 @@ declare module "mongoose" {
   * If later in the query chain a method returns Query<T>, we will need to know type T.
   * So we save this type as the second type parameter in DocumentQuery. Since people have
   * been using Query<T>, we set it as an alias of DocumentQuery.
+   *
+   * Furthermore, Query<T> is used for function that has an option { rawResult: true }.
+   * for instance findOneAndUpdate.
   */
  class Query<T> extends DocumentQuery<T, any> { }
  class DocumentQuery<T, DocType extends Document, QueryHelpers = {}> extends mquery {
@@ -1864,7 +1867,7 @@ declare module "mongoose" {
    equals<T>(val: T): this;

    /** Executes the query */
-    exec(callback?: (err: any, res: T) => void): Promise<T>;
+    exec(callback?: (err: NativeError, res: T) => void): Promise<T>;
    exec(operation: string | Function, callback?: (err: any, res: T) => void): Promise<T>;

    /** Specifies an $exists condition */
@@ -1895,10 +1898,16 @@ declare module "mongoose" {
     * Issues a mongodb findAndModify remove command.
     * Finds a matching document, removes it, passing the found document (if any) to the
     * callback. Executes immediately if callback is passed.
+     *
+     * If mongoose option 'useFindAndModify': set to false it uses native findOneAndUpdate() rather than deprecated findAndModify().
+     * https://mongoosejs.com/docs/api.html#mongoose_Mongoose-set
     */
    findOneAndRemove(callback?: (error: any, doc: DocType | null, result: any) => void): DocumentQuery<DocType | null, DocType> & QueryHelpers;
    findOneAndRemove(conditions: any,
      callback?: (error: any, doc: DocType | null, result: any) => void): DocumentQuery<DocType | null, DocType> & QueryHelpers;
+    findOneAndRemove(conditions: any, options: { rawResult: true } & QueryFindOneAndRemoveOptions,
+      callback?: (error: any, doc: mongodb.FindAndModifyWriteOpResultObject<DocType | null>, result: any) => void)
+        : Query<mongodb.FindAndModifyWriteOpResultObject<DocType | null>> & QueryHelpers;
    findOneAndRemove(conditions: any, options: QueryFindOneAndRemoveOptions,
      callback?: (error: any, doc: DocType | null, result: any) => void): DocumentQuery<DocType | null, DocType> & QueryHelpers;

@@ -1906,6 +1915,9 @@ declare module "mongoose" {
     * Issues a mongodb findAndModify update command.
     * Finds a matching document, updates it according to the update arg, passing any options, and returns
     * the found document (if any) to the callback. The query executes immediately if callback is passed.
+     *
+     * If mongoose option 'useFindAndModify': set to false it uses native findOneAndUpdate() rather than deprecated findAndModify().
+     * https://mongoosejs.com/docs/api.html#mongoose_Mongoose-set
     */
    findOneAndUpdate(callback?: (err: any, doc: DocType | null) => void): DocumentQuery<DocType | null, DocType> & QueryHelpers;
    findOneAndUpdate(update: any,
@@ -1913,8 +1925,15 @@ declare module "mongoose" {
    findOneAndUpdate(query: any, update: any,
      callback?: (err: any, doc: DocType | null, res: any) => void): DocumentQuery<DocType | null, DocType> & QueryHelpers;
    findOneAndUpdate(query: any, update: any,
-      options: { upsert: true, new: true } & QueryFindOneAndUpdateOptions,
-      callback?: (err: any, doc: DocType, res: any) => void): DocumentQuery<DocType | null, DocType> & QueryHelpers;
+      options: { rawResult: true } & { upsert: true } & { new: true } & QueryFindOneAndUpdateOptions,
+      callback?: (err: any, doc: mongodb.FindAndModifyWriteOpResultObject<DocType>, res: any) => void)
+        : Query<mongodb.FindAndModifyWriteOpResultObject<DocType>> & QueryHelpers;
+    findOneAndUpdate(query: any, update: any,
+      options: { upsert: true } & { new: true } & QueryFindOneAndUpdateOptions,
+      callback?: (err: any, doc: DocType, res: any) => void): DocumentQuery<DocType, DocType> & QueryHelpers;
+    findOneAndUpdate(query: any, update: any, options: { rawResult: true } & QueryFindOneAndUpdateOptions,
+      callback?: (err: any, doc: mongodb.FindAndModifyWriteOpResultObject<DocType | null>, res: any) => void)
+        : Query<mongodb.FindAndModifyWriteOpResultObject<DocType | null>> & QueryHelpers;
    findOneAndUpdate(query: any, update: any, options: QueryFindOneAndUpdateOptions,
      callback?: (err: any, doc: DocType | null, res: any) => void): DocumentQuery<DocType | null, DocType> & QueryHelpers;

@@ -2238,12 +2257,21 @@ declare module "mongoose" {
  class mquery { }

  interface QueryFindOneAndRemoveOptions {
-    /** if multiple docs are found by the conditions, sets the sort order to choose which doc to update */
+    /**
+      * if multiple docs are found by the conditions, sets the sort order to choose
+      * which doc to update
+      */
    sort?: any;
    /** puts a time limit on the query - requires mongodb >= 2.6.0 */
    maxTimeMS?: number;
-    /** if true, passes the raw result from the MongoDB driver as the third callback parameter */
+    /** sets the document fields to return */
+    select?: any;
+    /** like select, it determines which fields to return */
+    projection?: any;
+    /** if true, returns the raw result from the MongoDB driver */
    rawResult?: boolean;
+    /** overwrites the schema's strict mode option for this update */
+    strict?: boolean|string;
  }

  interface QueryFindOneAndUpdateOptions extends QueryFindOneAndRemoveOptions {
@@ -2251,8 +2279,6 @@ declare module "mongoose" {
    new?: boolean;
    /** creates the object if it doesn't exist. defaults to false. */
    upsert?: boolean;
-    /** Field selection. Equivalent to .select(fields).findOneAndUpdate() */
-    fields?: any | string;
    /** if true, runs update validators on this command. Update validators validate the update operation against the model's schema. */
    runValidators?: boolean;
    /**
@@ -2270,6 +2296,8 @@ declare module "mongoose" {
     *  Turn on this option to aggregate all the cast errors.
     */
      multipleCastError?: boolean;
+    /** Field selection. Equivalent to .select(fields).findOneAndUpdate() */
+    fields?: any | string;
  }

  interface QueryUpdateOptions extends ModelUpdateOptions {
@@ -2998,17 +3026,21 @@ declare module "mongoose" {
     * findByIdAndRemove(id, ...) is equivalent to findOneAndRemove({ _id: id }, ...).
     * Finds a matching document, removes it, passing the found document (if any) to the callback.
     * Executes immediately if callback is passed, else a Query object is returned.
+     *
+     * If mongoose option 'useFindAndModify': set to false it uses native findOneAndUpdate() rather than deprecated findAndModify().
+     * https://mongoosejs.com/docs/api.html#mongoose_Mongoose-set
+     *
+     * Note: same signatures as findByIdAndDelete
+     *
     * @param id value of _id to query by
     */
    findByIdAndRemove(): DocumentQuery<T | null, T> & QueryHelpers;
    findByIdAndRemove(id: any | number | string,
      callback?: (err: any, res: T | null) => void): DocumentQuery<T | null, T> & QueryHelpers;
-    findByIdAndRemove(id: any | number | string, options: {
-      /** if multiple docs are found by the conditions, sets the sort order to choose which doc to update */
-      sort?: any;
-      /** sets the document fields to return */
-      select?: any;
-    }, callback?: (err: any, res: T | null) => void): DocumentQuery<T | null, T> & QueryHelpers;
+    findByIdAndRemove(id: any | number | string, options: QueryFindOneAndRemoveOptions,
+      callback?: (err: any, res: mongodb.FindAndModifyWriteOpResultObject<T | null>) => void)
+        : Query<mongodb.FindAndModifyWriteOpResultObject<T | null>> & QueryHelpers;
+    findByIdAndRemove(id: any | number | string, options: QueryFindOneAndRemoveOptions, callback?: (err: any, res: T | null) => void): DocumentQuery<T | null, T> & QueryHelpers;


     /**
@@ -3016,31 +3048,44 @@ declare module "mongoose" {
     * findByIdAndDelete(id, ...) is equivalent to findByIdAndDelete({ _id: id }, ...).
     * Finds a matching document, removes it, passing the found document (if any) to the callback.
     * Executes immediately if callback is passed, else a Query object is returned.
+     *
+     * Note: same signatures as findByIdAndRemove
+     *
     * @param id value of _id to query by
     */
-    findByIdAndDelete(): DocumentQuery<T | null, T>;
+    findByIdAndDelete(): DocumentQuery<T | null, T> & QueryHelpers;
    findByIdAndDelete(id: any | number | string,
      callback?: (err: any, res: T | null) => void): DocumentQuery<T | null, T> & QueryHelpers;
-    findByIdAndDelete(id: any | number | string, options: {
-      /** if multiple docs are found by the conditions, sets the sort order to choose which doc to update */
-      sort?: any;
-      /** sets the document fields to return */
-      select?: any;
-    }, callback?: (err: any, res: T | null) => void): DocumentQuery<T | null, T> & QueryHelpers;
+    findByIdAndDelete(id: any | number | string, options: QueryFindOneAndRemoveOptions,
+      callback?: (err: any, res: mongodb.FindAndModifyWriteOpResultObject<T | null>) => void)
+        : Query<mongodb.FindAndModifyWriteOpResultObject<T | null>> & QueryHelpers;
+    findByIdAndDelete(id: any | number | string, options: QueryFindOneAndRemoveOptions, callback?: (err: any, res: T | null) => void): DocumentQuery<T | null, T> & QueryHelpers;

    /**
     * Issues a mongodb findAndModify update command by a document's _id field. findByIdAndUpdate(id, ...)
     * is equivalent to findOneAndUpdate({ _id: id }, ...).
+     *
+     * If mongoose option 'useFindAndModify': set to false it uses native findOneAndUpdate() rather than deprecated findAndModify().
+     * https://mongoosejs.com/docs/api.html#mongoose_Mongoose-set
+     *
     * @param id value of _id to query by
     */
    findByIdAndUpdate(): DocumentQuery<T | null, T> & QueryHelpers;
    findByIdAndUpdate(id: any | number | string, update: any,
      callback?: (err: any, res: T | null) => void): DocumentQuery<T | null, T> & QueryHelpers;
    findByIdAndUpdate(id: any | number | string, update: any,
-      options: { upsert: true, new: true } & ModelFindByIdAndUpdateOptions,
+      options: { rawResult: true } & { upsert: true } & { new: true } & QueryFindOneAndUpdateOptions,
      callback?: (err: any, res: T) => void): DocumentQuery<T, T> & QueryHelpers;
    findByIdAndUpdate(id: any | number | string, update: any,
-      options: ModelFindByIdAndUpdateOptions,
+      options: { upsert: true, new: true } & QueryFindOneAndUpdateOptions,
+      callback?: (err: any, res: mongodb.FindAndModifyWriteOpResultObject<T>) => void)
+        : Query<mongodb.FindAndModifyWriteOpResultObject<T>> & QueryHelpers;
+    findByIdAndUpdate(id: any | number | string, update: any,
+      options: { rawResult : true } & QueryFindOneAndUpdateOptions,
+      callback?: (err: any, res: mongodb.FindAndModifyWriteOpResultObject<T | null>) => void)
+        : Query<mongodb.FindAndModifyWriteOpResultObject<T | null>> & QueryHelpers;
+    findByIdAndUpdate(id: any | number | string, update: any,
+      options: QueryFindOneAndUpdateOptions,
      callback?: (err: any, res: T | null) => void): DocumentQuery<T | null, T> & QueryHelpers;

    /**
@@ -3059,62 +3104,62 @@ declare module "mongoose" {
     * Issue a mongodb findAndModify remove command.
     * Finds a matching document, removes it, passing the found document (if any) to the callback.
     * Executes immediately if callback is passed else a Query object is returned.
+     *
+     * If mongoose option 'useFindAndModify': set to false it uses native findOneAndUpdate() rather than deprecated findAndModify().
+     * https://mongoosejs.com/docs/api.html#mongoose_Mongoose-set
+     *
+     * Note: same signatures as findOneAndDelete
+     *
     */
    findOneAndRemove(): DocumentQuery<T | null, T> & QueryHelpers;
    findOneAndRemove(conditions: any,
      callback?: (err: any, res: T | null) => void): DocumentQuery<T | null, T> & QueryHelpers;
-    findOneAndRemove(conditions: any, options: {
-      /**
-       * if multiple docs are found by the conditions, sets the sort order to choose
-       * which doc to update
-       */
-      sort?: any;
-      /** puts a time limit on the query - requires mongodb >= 2.6.0 */
-      maxTimeMS?: number;
-      /** sets the document fields to return */
-      select?: any;
-    }, callback?: (err: any, res: T | null) => void): DocumentQuery<T | null, T> & QueryHelpers;
+    findOneAndRemove(conditions: any, options: { rawResult: true } & QueryFindOneAndRemoveOptions,
+      callback?: (err: any, doc: mongodb.FindAndModifyWriteOpResultObject<T | null>, res: any) => void)
+        : Query<mongodb.FindAndModifyWriteOpResultObject<T | null>> & QueryHelpers;
+    findOneAndRemove(conditions: any, options: QueryFindOneAndRemoveOptions, callback?: (err: any, res: T | null) => void): DocumentQuery<T | null, T> & QueryHelpers;

    /**
     * Issues a mongodb findOneAndDelete command.
     * Finds a matching document, removes it, passing the found document (if any) to the
     * callback. Executes immediately if callback is passed.
+     *
+     * Note: same signatures as findOneAndRemove
+     *
     */
    findOneAndDelete(): DocumentQuery<T | null, T> & QueryHelpers;
    findOneAndDelete(conditions: any,
      callback?: (err: any, res: T | null) => void): DocumentQuery<T | null, T> & QueryHelpers;
-    findOneAndDelete(conditions: any, options: {
-      /**
-       * if multiple docs are found by the conditions, sets the sort order to choose
-       * which doc to update
-       */
-      sort?: any;
-      /** puts a time limit on the query - requires mongodb >= 2.6.0 */
-      maxTimeMS?: number;
-      /** sets the document fields to return */
-      select?: any;
-      /** like select, it determines which fields to return */
-      projection?: any;
-      /** if true, returns the raw result from the MongoDB driver */
-      rawResult?: boolean;
-      /** overwrites the schema's strict mode option for this update */
-      strict?: boolean|string;
-    }, callback?: (err: any, res: T | null) => void): DocumentQuery<T | null, T> & QueryHelpers;
+    findOneAndDelete(conditions: any, options: { rawResult: true } & QueryFindOneAndRemoveOptions,
+      callback?: (err: any, doc: mongodb.FindAndModifyWriteOpResultObject<T | null>, res: any) => void)
+        : Query<mongodb.FindAndModifyWriteOpResultObject<T | null>> & QueryHelpers;
+    findOneAndDelete(conditions: any, options: QueryFindOneAndRemoveOptions, callback?: (err: any, res: T | null) => void): DocumentQuery<T | null, T> & QueryHelpers;

    /**
     * Issues a mongodb findAndModify update command.
     * Finds a matching document, updates it according to the update arg, passing any options,
     * and returns the found document (if any) to the callback. The query executes immediately
     * if callback is passed else a Query object is returned.
+     *
+    * If mongoose option 'useFindAndModify': set to false it uses native findOneAndUpdate() rather than the deprecated findAndModify().
+    * https://mongoosejs.com/docs/api.html#mongoose_Mongoose-set
     */
    findOneAndUpdate(): DocumentQuery<T | null, T> & QueryHelpers;
    findOneAndUpdate(conditions: any, update: any,
      callback?: (err: any, doc: T | null, res: any) => void): DocumentQuery<T | null, T> & QueryHelpers;
    findOneAndUpdate(conditions: any, update: any,
-      options: { upsert: true, new: true } & ModelFindOneAndUpdateOptions,
+      options: { rawResult : true } & { upsert: true, new: true } & QueryFindOneAndUpdateOptions,
+      callback?: (err: any, doc: mongodb.FindAndModifyWriteOpResultObject<T>, res: any) => void)
+        : Query<mongodb.FindAndModifyWriteOpResultObject<T>> & QueryHelpers;
+    findOneAndUpdate(conditions: any, update: any,
+      options: { upsert: true, new: true } & QueryFindOneAndUpdateOptions,
      callback?: (err: any, doc: T, res: any) => void): DocumentQuery<T, T> & QueryHelpers;
    findOneAndUpdate(conditions: any, update: any,
-      options: ModelFindOneAndUpdateOptions,
+      options: { rawResult: true } & QueryFindOneAndUpdateOptions,
+      callback?: (err: any, doc: mongodb.FindAndModifyWriteOpResultObject<T | null>, res: any) => void)
+        : Query<mongodb.FindAndModifyWriteOpResultObject<T | null>> & QueryHelpers;
+    findOneAndUpdate(conditions: any, update: any,
+      options: QueryFindOneAndUpdateOptions,
      callback?: (err: any, doc: T | null, res: any) => void): DocumentQuery<T | null, T> & QueryHelpers;

    /**
@@ -3308,43 +3353,6 @@ declare module "mongoose" {
    session?: ClientSession | null;
  }

-  interface ModelFindByIdAndUpdateOptions extends ModelOptions {
-    /** true to return the modified document rather than the original. defaults to false */
-    new?: boolean;
-    /** creates the object if it doesn't exist. defaults to false. */
-    upsert?: boolean;
-    /**
-     * if true, runs update validators on this command. Update validators validate the
-     * update operation against the model's schema.
-     */
-    runValidators?: boolean;
-    /**
-     * if this and upsert are true, mongoose will apply the defaults specified in the model's
-     * schema if a new document is created. This option only works on MongoDB >= 2.4 because
-     * it relies on MongoDB's $setOnInsert operator.
-     */
-    setDefaultsOnInsert?: boolean;
-    /** if multiple docs are found by the conditions, sets the sort order to choose which doc to update */
-    sort?: any;
-    /** sets the document fields to return */
-    select?: any;
-    /** if true, passes the raw result from the MongoDB driver as the third callback parameter */
-    rawResult?: boolean;
-    /** overwrites the schema's strict mode option for this update */
-    strict?: boolean;
-    /** The context option lets you set the value of this in update validators to the underlying query. */
-    context?: string;
-  }
-
-  interface ModelFindOneAndUpdateOptions extends ModelFindByIdAndUpdateOptions {
-    /** Field selection. Equivalent to .select(fields).findOneAndUpdate() */
-    fields?: any | string;
-    /** puts a time limit on the query - requires mongodb >= 2.6.0 */
-    maxTimeMS?: number;
-    /** if true, passes the raw result from the MongoDB driver as the third callback parameter */
-    rawResult?: boolean;
-  }
-
  interface ModelPopulateOptions {
    /** space delimited path(s) to populate */
    path: string;
@@ -1021,7 +1021,7 @@ query.findOne(function (err, res) {
 query.findOneAndRemove({name: 'aa'}, {
  rawResult: true
 }, function (err, doc) {
-  doc.execPopulate();
+    doc.lastErrorObject
 }).findOneAndRemove();
 query.findOneAndUpdate({name: 'aa'}, {name: 'bb'}, {

@@ -1911,6 +1911,14 @@ LocModel.findOneAndUpdate().exec().then(function (arg) {
    arg.openingTimes;
  }
 });
+LocModel.findOneAndUpdate(
+    // find a document with that filter
+    {name: "aa"},
+    // document to insert when nothing was found
+    { $set: {name: "bb"} },
+    // options
+    {upsert: true, new: true, runValidators: true,
+        rawResult: true, multipleCastError: true });
 LocModel.geoSearch({}, {
  near: [1, 2],
  maxDistance: 22