mongoose 6.4.2 → 6.4.5

package/lib/types/map.js

@@ -42,6 +42,14 @@ class MongooseMap extends Map {
     super.set(key, value);
   }
 
+  /**
+   * Overwrites native Map's `get()` function to support Mongoose getters.
+   *
+   * @api public
+   * @method get
+   * @memberOf Map
+   */
+
   get(key, options) {
     if (isBsonType(key, 'ObjectID')) {
       key = key.toString();
@@ -54,6 +62,20 @@ class MongooseMap extends Map {
     return this.$__schemaType.applyGetters(super.get(key), this.$__parent);
   }
 
+  /**
+   * Overwrites native Map's `set()` function to support setters, `populate()`,
+   * and change tracking. Note that Mongoose maps _only_ support strings and
+   * ObjectIds as keys.
+   *
+   * #### Example:
+   *     doc.myMap.set('test', 42); // works
+   *     doc.myMap.set({ obj: 42 }, 42); // Throws "Mongoose maps only support string keys"
+   *
+   * @api public
+   * @method set
+   * @memberOf Map
+   */
+
   set(key, value) {
     if (isBsonType(key, 'ObjectID')) {
       key = key.toString();
@@ -108,6 +130,14 @@ class MongooseMap extends Map {
     }
   }
 
+  /**
+   * Overwrites native Map's `clear()` function to support change tracking.
+   *
+   * @api public
+   * @method clear
+   * @memberOf Map
+   */
+
   clear() {
     super.clear();
     const parent = this.$__parent;
@@ -116,6 +146,14 @@ class MongooseMap extends Map {
     }
   }
 
+  /**
+   * Overwrites native Map's `delete()` function to support change tracking.
+   *
+   * @api public
+   * @method delete
+   * @memberOf Map
+   */
+
   delete(key) {
     if (isBsonType(key, 'ObjectID')) {
       key = key.toString();
@@ -125,6 +163,14 @@ class MongooseMap extends Map {
     super.delete(key);
   }
 
+  /**
+   * Converts this map to a native JavaScript Map so the MongoDB driver can serialize it.
+   *
+   * @api public
+   * @method toBSON
+   * @memberOf Map
+   */
+
   toBSON() {
     return new Map(this);
   }
@@ -146,6 +192,21 @@ class MongooseMap extends Map {
     return this.constructor.prototype.toObject.apply(this, arguments);
   }
 
+  /**
+   * Converts this map to a native JavaScript Map for `JSON.stringify()`. Set
+   * the `flattenMaps` option to convert this map to a POJO instead.
+   *
+   * #### Example:
+   *     doc.myMap.toJSON() instanceof Map; // true
+   *     doc.myMap.toJSON({ flattenMaps: true }) instanceof Map; // false
+   *
+   * @api public
+   * @method toJSON
+   * @param {Object} [options]
+   * @param {Boolean} [options.flattenMaps=false] set to `true` to convert the map to a POJO rather than a native JavaScript map
+   * @memberOf Map
+   */
+
   toJSON(options) {
     if (typeof (options && options.flattenMaps) === 'boolean' ? options.flattenMaps : true) {
       const ret = {};
@@ -209,6 +270,15 @@ Object.defineProperty(MongooseMap.prototype, '$__schemaType', {
   configurable: false
 });
 
+/**
+ * Set to `true` for all Mongoose map instances
+ *
+ * @api public
+ * @property $isMongooseMap
+ * @memberOf MongooseMap
+ * @instance
+ */
+
 Object.defineProperty(MongooseMap.prototype, '$isMongooseMap', {
   enumerable: false,
   writable: false,

package/lib/types/objectid.js

@@ -1,7 +1,7 @@
 /**
  * ObjectId type constructor
  *
- * #### Example
+ * #### Example:
  *
  *     const id = new mongoose.Types.ObjectId;
  *

package/lib/types/subdocument.js

@@ -188,7 +188,7 @@ Subdocument.prototype.isModified = function(paths, modifiedPaths) {
  * @param {String} path the field to mark as valid
  * @api private
  * @method $markValid
- * @receiver Subdocument
+ * @memberOf Subdocument
  */
 
 Subdocument.prototype.$markValid = function(path) {

package/lib/virtualtype.js

@@ -75,7 +75,7 @@ VirtualType.prototype.clone = function() {
  * Mongoose calls the getter function with the below 3 parameters.
  *
  * - `value`: the value returned by the previous getter. If there is only one getter, `value` will be `undefined`.
- * - `virtual`: the virtual object you called `.get()` on
+ * - `virtual`: the virtual object you called `.get()` on.
  * - `doc`: the document this virtual is attached to. Equivalent to `this`.
  *
  * #### Example:
@@ -85,7 +85,7 @@ VirtualType.prototype.clone = function() {
  *       return this.name.first + ' ' + this.name.last;
  *     });
  *
- * @param {Function(Any, VirtualType, Document)} fn
+ * @param {function} fn
  * @return {VirtualType} this
  * @api public
  */
@@ -100,8 +100,8 @@ VirtualType.prototype.get = function(fn) {
  *
  * Mongoose calls the setter function with the below 3 parameters.
  *
- * - `value`: the value being set
- * - `virtual`: the virtual object you're calling `.set()` on
+ * - `value`: the value being set.
+ * - `virtual`: the virtual object you're calling `.set()` on.
  * - `doc`: the document this virtual is attached to. Equivalent to `this`.
  *
  * #### Example:
@@ -120,7 +120,7 @@ VirtualType.prototype.get = function(fn) {
  *     doc.name.first; // 'Jean-Luc'
  *     doc.name.last; // 'Picard'
  *
- * @param {Function(Any, VirtualType, Document)} fn
+ * @param {function} fn
  * @return {VirtualType} this
  * @api public
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mongoose",
   "description": "Mongoose MongoDB ODM",
-  "version": "6.4.2",
+  "version": "6.4.5",
   "author": "Guillermo Rauch <guillermo@learnboost.com>",
   "keywords": [
     "mongodb",
@@ -28,9 +28,9 @@
     "sift": "16.0.0"
   },
   "devDependencies": {
-    "@babel/core": "7.18.2",
-    "@typescript-eslint/eslint-plugin": "5.27.0",
-    "@typescript-eslint/parser": "5.27.0",
+    "@babel/core": "7.18.6",
+    "@typescript-eslint/eslint-plugin": "5.30.3",
+    "@typescript-eslint/parser": "5.30.3",
     "acquit": "1.2.1",
     "acquit-ignore": "0.2.0",
     "acquit-require": "0.1.1",
@@ -40,19 +40,19 @@
     "benchmark": "2.1.4",
     "bluebird": "3.7.2",
     "buffer": "^5.6.0",
-    "cheerio": "1.0.0-rc.11",
+    "cheerio": "1.0.0-rc.12",
     "crypto-browserify": "3.12.0",
-    "dox": "0.3.1",
-    "eslint": "8.16.0",
+    "dox": "0.9.1",
+    "eslint": "8.19.0",
     "eslint-plugin-mocha-no-only": "1.1.1",
     "highlight.js": "11.5.1",
     "lodash.isequal": "4.5.0",
     "lodash.isequalwith": "4.4.0",
-    "marked": "4.0.16",
+    "marked": "4.0.17",
     "mkdirp": "^1.0.4",
     "mocha": "10.0.0",
     "moment": "2.x",
-    "mongodb-memory-server": "8.6.0",
+    "mongodb-memory-server": "8.7.2",
     "ncp": "^2.0.0",
     "nyc": "15.1.0",
     "pug": "3.0.2",
@@ -60,11 +60,11 @@
     "serve-handler": "6.1.3",
     "sinon": "14.0.0",
     "stream-browserify": "3.0.0",
-    "ts-benchmark": "^1.0.2",
+    "ts-benchmark": "^1.1.5",
     "tsd": "0.20.0",
-    "typescript": "4.7.2",
+    "typescript": "4.7.4",
     "uuid": "8.3.2",
-    "webpack": "5.72.1"
+    "webpack": "5.73.0"
   },
   "directories": {
     "lib": "./lib/mongoose"
@@ -98,8 +98,8 @@
     "test-tsd": "node ./test/types/check-types-filename && tsd",
     "tdd": "mocha ./test/*.test.js --inspect --watch --recursive --watch-files ./**/*.{js,ts}",
     "test-coverage": "nyc --reporter=html --reporter=text npm test",
-    "ts-benchmark": "ts-benchmark -p ./benchmarks/typescript/simple -f 17 18 29 32",
-    "ts-benchmark-watch": "ts-benchmark -p ./benchmarks/typescript/simple -w ./types -i -s -f 17 18 29 32 -b master"
+    "ts-benchmark": "ts-benchmark -p ./benchmarks/typescript/simple -f 17/100000 18 29 32",
+    "ts-benchmark-watch": "ts-benchmark -p ./benchmarks/typescript/simple -w ./types -i -s -f 17/100000 18 29 32 -b master"
   },
   "main": "./index.js",
   "types": "./types/index.d.ts",
@@ -145,4 +145,4 @@
       "target": "ES2017"
     }
   }
-}
+}

package/types/expressions.d.ts

@@ -32,7 +32,7 @@ declare module 'mongoose' {
        *
        * @see https://docs.mongodb.com/manual/reference/operator/aggregation/add/#mongodb-expression-exp.-add
        */
-      $add: (NumberExpression | DateExpression)[];
+      $add: Expression[];
     }
 
     export interface Ceil {
@@ -1043,7 +1043,7 @@ declare module 'mongoose' {
        *
        * @see https://docs.mongodb.com/manual/reference/operator/aggregation/cond/#mongodb-expression-exp.-cond
        */
-      $cond: { if: BooleanExpression, then: AnyExpression, else: AnyExpression } | [BooleanExpression, AnyExpression, AnyExpression];
+      $cond: { if: Expression, then: AnyExpression, else: AnyExpression } | [BooleanExpression, AnyExpression, AnyExpression];
     }
 
     export interface IfNull {
@@ -1067,13 +1067,13 @@ declare module 'mongoose' {
          * - $case
          * - $then
          */
-        $branches: { $case: Expression, then: Expression }[];
+        branches: { case: Expression, then: Expression }[];
         /**
          * The path to take if no branch case expression evaluates to true.
          *
          * Although optional, if default is unspecified and no branch case evaluates to true, $switch returns an error.
          */
-        $default: Expression;
+        default: Expression;
       };
     }
 
@@ -1104,7 +1104,7 @@ declare module 'mongoose' {
        * @version 3.2
        * @see https://docs.mongodb.com/manual/reference/operator/aggregation/concatArrays/#mongodb-expression-exp.-concatArrays
        */
-      $concatArrays: ArrayExpression[];
+      $concatArrays: Expression[];
     }
 
     export interface Filter {
@@ -1957,7 +1957,7 @@ declare module 'mongoose' {
        * @version 5.0
        * @see https://docs.mongodb.com/manual/reference/operator/aggregation/addToSet/#mongodb-expression-exp.-addToSet
        */
-      $addToSet: ArrayExpression;
+      $addToSet: Expression | Record<string, Expression>;
     }
 
     export interface Avg {
@@ -1967,7 +1967,7 @@ declare module 'mongoose' {
        * @version 5.0
        * @see https://docs.mongodb.com/manual/reference/operator/aggregation/avg/#mongodb-expression-exp.-avg
        */
-      $avg: ArrayExpression;
+      $avg: Expression;
     }
 
     export interface Count {
@@ -2316,6 +2316,21 @@ declare module 'mongoose' {
       $toObjectId: Expression;
     }
 
+    export interface Top {
+      $top: {
+        sortBy: AnyObject,
+        output: Expression
+      };
+    }
+
+    export interface TopN {
+      $topN: {
+        n: Expression,
+        sortBy: AnyObject,
+        output: Expression
+      };
+    }
+
     export interface ToString {
       /**
        * Converts a value to a string. If the value cannot be converted to a string, $toString errors. If the value is
@@ -2406,7 +2421,10 @@ declare module 'mongoose' {
     TypeExpressionOperator |
     AccumulatorOperator |
     VariableExpressionOperator |
-    WindowOperator;
+    WindowOperator |
+    Expression.Top |
+    Expression.TopN |
+    any;
 
   export type NullExpression = null;
 
@@ -2430,7 +2448,8 @@ declare module 'mongoose' {
     BinaryExpression |
     FunctionExpression |
     ObjectIdExpression |
-    ConditionalExpressionOperator;
+    ConditionalExpressionOperator |
+    any;
 
   export type ObjectIdExpression =
     TypeExpressionOperatorReturningObjectId;
@@ -2478,7 +2497,8 @@ declare module 'mongoose' {
     DataSizeOperatorReturningNumber |
     CustomAggregationExpressionOperatorReturningAny |
     TypeExpressionOperatorReturningNumber |
-    DateExpression;
+    DateExpression |
+    DateExpressionOperatorReturningNumber;
 
   export type ObjectExpression =
     Path |

package/types/index.d.ts

@@ -109,9 +109,7 @@ declare module 'mongoose' {
   }
 
   export type Require_id<T> = T extends { _id?: infer U }
-    ? U extends any
-      ? (T & { _id: Types.ObjectId })
-      : T & Required<{ _id: U }>
+    ? IfAny<U, T & { _id: Types.ObjectId }, T & Required<{ _id: U }>>
     : T & { _id: Types.ObjectId };
 
   export type RequireOnlyTypedId<T> = T extends { _id?: infer U; }
@@ -227,6 +225,7 @@ declare module 'mongoose' {
     obj: SchemaDefinition<SchemaDefinitionType<EnforcedDocType>>;
 
     /** Gets/sets schema paths. */
+    path<pathGeneric extends keyof EnforcedDocType>(path: pathGeneric): SchemaType<EnforcedDocType[pathGeneric]>;
     path<ResultType extends SchemaType = SchemaType>(path: string): ResultType;
     path(path: string, constructor: any): this;
 
@@ -438,6 +437,10 @@ declare module 'mongoose' {
 
   export type SortOrder = -1 | 1 | 'asc' | 'ascending' | 'desc' | 'descending';
 
+  type Mutable<T> = {
+    -readonly [K in keyof T]: T[K];
+  };
+
   type _UpdateQuery<TSchema> = {
     /** @see https://docs.mongodb.com/manual/reference/operator/update-field/ */
     $currentDate?: AnyKeys<TSchema> & AnyObject;
@@ -451,10 +454,10 @@ declare module 'mongoose' {
     $unset?: AnyKeys<TSchema> & AnyObject;
 
     /** @see https://docs.mongodb.com/manual/reference/operator/update-array/ */
-    $addToSet?: mongodb.SetFields<TSchema>;
+    $addToSet?: Mutable<mongodb.SetFields<TSchema>>;
     $pop?: AnyKeys<TSchema> & AnyObject;
-    $pull?: mongodb.PullOperator<TSchema>;
-    $push?: mongodb.PushOperator<TSchema>;
+    $pull?: Mutable<mongodb.PullOperator<TSchema>>;
+    $push?: Mutable<mongodb.PushOperator<TSchema>>;
     $pullAll?: mongodb.PullAllOperator<TSchema>;
 
     /** @see https://docs.mongodb.com/manual/reference/operator/update-bitwise/ */
@@ -538,7 +541,7 @@ declare module 'mongoose' {
   export type SchemaDefinitionType<T> = T extends Document ? Omit<T, Exclude<keyof Document, '_id' | 'id' | '__v'>> : T;
 
   // Helpers to simplify checks
-  type IfAny<IFTYPE, THENTYPE> = 0 extends (1 & IFTYPE) ? THENTYPE : IFTYPE;
+  type IfAny<IFTYPE, THENTYPE, ELSETYPE = IFTYPE> = 0 extends (1 & IFTYPE) ? THENTYPE : ELSETYPE;
   type IfUnknown<IFTYPE, THENTYPE> = unknown extends IFTYPE ? THENTYPE : IFTYPE;
 
   // tests for these two types are located in test/types/lean.test.ts

package/types/indexes.d.ts

@@ -51,8 +51,8 @@ declare module 'mongoose' {
      * the model's schema except the `_id` index, and build any indexes that
      * are in your schema but not in MongoDB.
      */
-    syncIndexes(options: mongodb.CreateIndexesOptions | null, callback: Callback<Array<string>>): void;
-    syncIndexes(options?: mongodb.CreateIndexesOptions): Promise<Array<string>>;
+    syncIndexes(options: SyncIndexesOptions | null, callback: Callback<Array<string>>): void;
+    syncIndexes(options?: SyncIndexesOptions): Promise<Array<string>>;
   }
 
   interface IndexesDiff {

package/types/inferschematype.d.ts

@@ -1,4 +1,18 @@
-import { Schema, InferSchemaType, SchemaType, SchemaTypeOptions, TypeKeyBaseType, Types, NumberSchemaDefinition, StringSchemaDefinition, BooleanSchemaDefinition, DateSchemaDefinition } from 'mongoose';
+import {
+  Schema,
+  InferSchemaType,
+  SchemaType,
+  SchemaTypeOptions,
+  TypeKeyBaseType,
+  Types,
+  NumberSchemaDefinition,
+  StringSchemaDefinition,
+  BooleanSchemaDefinition,
+  DateSchemaDefinition,
+  ObtainDocumentType,
+  DefaultTypeKey,
+  ObjectIdSchemaDefinition
+} from 'mongoose';
 
 declare module 'mongoose' {
   /**
@@ -75,9 +89,9 @@ type IsPathRequired<P, TypeKey extends TypeKeyBaseType> =
       ? P extends { default: undefined }
         ? false
         : true
-      : P extends (Record<TypeKey, NumberSchemaDefinition | StringSchemaDefinition | BooleanSchemaDefinition | DateSchemaDefinition>)
-        ? P extends { default: ResolvePathType<P[TypeKey]> }
-          ? true
+      : P extends (Record<TypeKey, any>)
+        ? P extends { default: any }
+          ? IfEquals<P['default'], undefined, false, true>
           : false
         : false;
 
@@ -138,7 +152,8 @@ type ObtainDocumentPathType<PathValueType, TypeKey extends TypeKeyBaseType> = Pa
   ? InferSchemaType<PathValueType>
   : ResolvePathType<
   PathValueType extends PathWithTypePropertyBaseType<TypeKey> ? PathValueType[TypeKey] : PathValueType,
-  PathValueType extends PathWithTypePropertyBaseType<TypeKey> ? Omit<PathValueType, TypeKey> : {}
+  PathValueType extends PathWithTypePropertyBaseType<TypeKey> ? Omit<PathValueType, TypeKey> : {},
+  TypeKey
   >;
 
 /**
@@ -151,17 +166,18 @@ type PathEnumOrString<T extends SchemaTypeOptions<string>['enum']> = T extends (
  * @summary Resolve path type by returning the corresponding type.
  * @param {PathValueType} PathValueType Document definition path type.
  * @param {Options} Options Document definition path options except path type.
- * @returns Number, "Number" or "number" will be resolved to string type.
+ * @param {TypeKey} TypeKey A generic of literal string type."Refers to the property used for path type definition".
+ * @returns Number, "Number" or "number" will be resolved to number type.
  */
-type ResolvePathType<PathValueType, Options extends SchemaTypeOptions<PathValueType> = {}> =
+type ResolvePathType<PathValueType, Options extends SchemaTypeOptions<PathValueType> = {}, TypeKey extends TypeKeyBaseType = DefaultTypeKey> =
   PathValueType extends Schema ? InferSchemaType<PathValueType> :
-    PathValueType extends (infer Item)[] ? IfEquals<Item, never, any, ResolvePathType<Item>>[] :
+    PathValueType extends (infer Item)[] ? IfEquals<Item, never, any[], Item extends Schema ? Types.DocumentArray<ResolvePathType<Item>> : ResolvePathType<Item>[]> :
       PathValueType extends StringSchemaDefinition ? PathEnumOrString<Options['enum']> :
         PathValueType extends NumberSchemaDefinition ? number :
           PathValueType extends DateSchemaDefinition ? Date :
             PathValueType extends typeof Buffer | 'buffer' | 'Buffer' | typeof Schema.Types.Buffer ? Buffer :
               PathValueType extends BooleanSchemaDefinition ? boolean :
-                PathValueType extends 'objectId' | 'ObjectId' | typeof Schema.Types.ObjectId ? Types.ObjectId :
+                PathValueType extends ObjectIdSchemaDefinition ? Types.ObjectId :
                   PathValueType extends 'decimal128' | 'Decimal128' | typeof Schema.Types.Decimal128 ? Types.Decimal128 :
                     PathValueType extends MapConstructor ? Map<string, ResolvePathType<Options['of']>> :
                       PathValueType extends ArrayConstructor ? any[] :
@@ -169,5 +185,5 @@ type ResolvePathType<PathValueType, Options extends SchemaTypeOptions<PathValueT
                           IfEquals<PathValueType, ObjectConstructor> extends true ? any:
                             IfEquals<PathValueType, {}> extends true ? any:
                               PathValueType extends typeof SchemaType ? PathValueType['prototype'] :
-                                PathValueType extends {} ? PathValueType :
+                                PathValueType extends Record<string, any> ? ObtainDocumentType<PathValueType, any, TypeKey> :
                                   unknown;

package/types/models.d.ts

@@ -106,7 +106,7 @@ declare module 'mongoose' {
     checkKeys?: boolean;
     j?: boolean;
     safe?: boolean | WriteConcern;
-    timestamps?: boolean;
+    timestamps?: boolean | QueryTimestampsConfig;
     validateBeforeSave?: boolean;
     validateModifiedOnly?: boolean;
     w?: number | string;
@@ -351,6 +351,7 @@ declare module 'mongoose' {
     findOneAndRemove<ResultDoc = HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>(filter?: FilterQuery<T>, options?: QueryOptions<T> | null, callback?: (err: CallbackError, doc: ResultDoc | null, res: any) => void): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, T>;
 
     /** Creates a `findOneAndReplace` query: atomically finds the given document and replaces it with `replacement`. */
+    findOneAndReplace<ResultDoc = HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>(filter: FilterQuery<T>, replacement: T | AnyObject, options: QueryOptions<T> & { rawResult: true }, callback?: (err: CallbackError, doc: any, res: any) => void): QueryWithHelpers<ModifyResult<ResultDoc>, ResultDoc, TQueryHelpers, T>;
     findOneAndReplace<ResultDoc = HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>(filter: FilterQuery<T>, replacement: T | AnyObject, options: QueryOptions<T> & { upsert: true } & ReturnsNewDoc, callback?: (err: CallbackError, doc: ResultDoc, res: any) => void): QueryWithHelpers<ResultDoc, ResultDoc, TQueryHelpers, T>;
     findOneAndReplace<ResultDoc = HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>(filter?: FilterQuery<T>, replacement?: T | AnyObject, options?: QueryOptions<T> | null, callback?: (err: CallbackError, doc: ResultDoc | null, res: any) => void): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, T>;
 

package/types/pipelinestage.d.ts

@@ -212,7 +212,7 @@ declare module 'mongoose' {
 
     export interface Set {
       /** [`$set` reference](https://docs.mongodb.com/manual/reference/operator/aggregation/set/) */
-      $set: Record<string, AnyExpression>
+      $set: Record<string, AnyExpression | any>
     }
 
     export interface SetWindowFields {

package/types/query.d.ts

@@ -90,6 +90,11 @@ declare module 'mongoose' {
     [key: string]: any;
   };
 
+  interface QueryTimestampsConfig {
+    createdAt?: boolean;
+    updatedAt?: boolean;
+  }
+
   interface QueryOptions<DocType = unknown> extends
     PopulateOption,
     SessionOption {
@@ -157,7 +162,7 @@ declare module 'mongoose' {
      * skip timestamps for this update. Note that this allows you to overwrite
      * timestamps. Does nothing if schema-level timestamps are not set.
      */
-    timestamps?: boolean;
+    timestamps?: boolean | QueryTimestampsConfig;
     upsert?: boolean;
     writeConcern?: mongodb.WriteConcern;