mongoose 9.5.0 → 9.6.0

package/lib/error/messages.js

@@ -30,6 +30,7 @@ msg.DocumentNotFoundError = null;
 msg.general = {};
 msg.general.default = 'Validator failed for path `{PATH}` with value `{VALUE}`';
 msg.general.required = 'Path `{PATH}` is required.';
+msg.general.allowNull = 'Path `{PATH}` does not allow null values.';
 
 msg.Number = {};
 msg.Number.min = 'Path `{PATH}` ({VALUE}) is less than minimum allowed value ({MIN}).';

package/lib/options/schemaTypeOptions.js

@@ -94,6 +94,20 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'cast', opts);
 
 Object.defineProperty(SchemaTypeOptions.prototype, 'required', opts);
 
+/**
+ * Controls whether this path may be set to `null`. By default, Mongoose allows
+ * `null` for non-required paths. Set `allowNull: false` to allow `undefined`
+ * but disallow `null`.
+ *
+ * @api public
+ * @property allowNull
+ * @memberOf SchemaTypeOptions
+ * @type {boolean}
+ * @instance
+ */
+
+Object.defineProperty(SchemaTypeOptions.prototype, 'allowNull', opts);
+
 /**
  * The default value for this path. If a function, Mongoose executes the function
  * and uses the return value as the default.

package/lib/schemaType.js

@@ -200,15 +200,16 @@ SchemaType.prototype._createJSONSchemaTypeDefinition = function _createJSONSchem
     (this.options.required == null ?
       (options?._defaultRequired === true || this.path === '_id') :
       this.options.required && typeof this.options.required !== 'function');
+  const allowNull = this.options.allowNull !== false;
 
   if (useBsonType) {
-    if (isRequired) {
+    if (isRequired || !allowNull) {
       return { bsonType };
     }
     return { bsonType: [bsonType, 'null'] };
   }
 
-  if (isRequired) {
+  if (isRequired || !allowNull) {
     return { type };
   }
   return { type: [type, 'null'] };
@@ -1142,6 +1143,12 @@ SchemaType.prototype.required = function(required, message) {
 
   const _this = this;
   this.isRequired = true;
+  this.originalRequiredValue = required;
+
+  if (typeof this.originalRequiredValue !== 'function' &&
+      (utils.hasUserDefinedProperty(this.options, 'allowNull') || this.allowNullValidator != null)) {
+    throw new MongooseError('Path "' + this.path + '" may not have `allowNull` specified when `required` is true');
+  }
 
   this.requiredValidator = function(v) {
     const cachedRequired = this?.$__?.cachedRequired;
@@ -1166,8 +1173,6 @@ SchemaType.prototype.required = function(required, message) {
 
     return _this.checkRequired(v, this);
   };
-  this.originalRequiredValue = required;
-
   if (typeof required === 'string') {
     message = required;
     required = undefined;
@@ -1183,6 +1188,53 @@ SchemaType.prototype.required = function(required, message) {
   return this;
 };
 
+/**
+ * Adds a validator that disallows `null` for this path without making the path
+ * required. `undefined` values still pass validation.
+ *
+ * #### Example:
+ *
+ *     const schema = new Schema({
+ *       name: { type: String, allowNull: false }
+ *     });
+ *
+ *     new Model({ name: undefined }).validateSync(); // OK
+ *     new Model({ name: null }).validateSync(); // ValidationError
+ *
+ * @param {boolean} allowNull
+ * @return {SchemaType} this
+ * @api public
+ */
+
+SchemaType.prototype.allowNull = function(allowNull) {
+  if (arguments.length > 0 && this.isRequired && typeof this.originalRequiredValue !== 'function') {
+    throw new MongooseError('Path "' + this.path + '" may not have `allowNull` specified when `required` is true');
+  }
+
+  this.validators = this.validators.filter(function(v) {
+    return v.validator !== this.allowNullValidator;
+  }, this);
+
+  if (allowNull !== false) {
+    delete this.options.allowNull;
+    delete this.allowNullValidator;
+    return this;
+  }
+
+  this.options.allowNull = false;
+  this.allowNullValidator = function(v) {
+    return v !== null;
+  };
+
+  this.validators.push({
+    validator: this.allowNullValidator,
+    message: MongooseError.messages.general.allowNull,
+    type: 'allowNull'
+  });
+
+  return this;
+};
+
 /**
  * Set the model that this path refers to. This is the option that [populate](https://mongoosejs.com/docs/populate.html)
  * looks at to determine the foreign collection it should query.
@@ -1802,6 +1854,7 @@ SchemaType.prototype.clone = function() {
   const schematype = new this.constructor(this.path, options, this.instance, this.parentSchema);
   schematype.validators = this.validators.slice();
   if (this.requiredValidator !== undefined) schematype.requiredValidator = this.requiredValidator;
+  if (this.allowNullValidator !== undefined) schematype.allowNullValidator = this.allowNullValidator;
   if (this.defaultValue !== undefined) schematype.defaultValue = this.defaultValue;
   if (this.$immutable !== undefined && this.options.immutable === undefined) {
     schematype.$immutable = this.$immutable;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mongoose",
   "description": "Mongoose MongoDB ODM",
-  "version": "9.5.0",
+  "version": "9.6.0",
   "author": "Guillermo Rauch <guillermo@learnboost.com>",
   "keywords": [
     "mongodb",
@@ -21,7 +21,7 @@
   "license": "MIT",
   "dependencies": {
     "kareem": "3.3.0",
-    "mongodb": "~7.1",
+    "mongodb": "~7.2",
     "mpath": "0.9.0",
     "mquery": "6.0.0",
     "ms": "2.1.3",
@@ -52,7 +52,7 @@
     "markdownlint-cli2": "0.22.0",
     "marked": "17.0.5",
     "mkdirp": "^3.0.1",
-    "mocha": "11.7.5",
+    "mocha": "12.0.0-beta-9.2",
     "moment": "2.30.1",
     "mongodb-client-encryption": "~7.0",
     "mongodb-memory-server": "11.0.1",
@@ -63,7 +63,7 @@
     "tstyche": "^7.0.0",
     "typescript": "5.9.3",
     "typescript-eslint": "^8.31.1",
-    "uuid": "11.1.0"
+    "uuid": "14.0.0"
   },
   "directories": {
     "lib": "./lib/mongoose"

package/types/index.d.ts

@@ -819,12 +819,12 @@ declare module 'mongoose' {
 
   export type ReturnsNewDoc = { new: true } | { returnOriginal: false } | { returnDocument: 'after' };
 
-  type ArrayOperators = { $slice: number | [number, number]; $elemMatch?: never } | { $elemMatch: Record<string, any>; $slice?: never };
+  export type ArrayProjectionOperators = { $slice: number | [number, number]; $elemMatch?: never } | { $elemMatch: Record<string, any>; $slice?: never };
   /**
    * This Type Assigns `Element | undefined` recursively to the `T` type.
    * if it is an array it will do this to the element of the array, if it is an object it will do this for the properties of the object.
    * `Element` is the truthy or falsy values that are going to be used as the value of the projection.(1 | true or 0 | false)
-   * For the elements of the array we will use: `Element | `undefined` | `ArrayOperators`
+   * For the elements of the array we will use: `Element | `undefined` | `ArrayProjectionOperators`
    * @example
    * type CalculatedType = Projector<{ a: string, b: number, c: { d: string }, d: string[] }, true>
    * type CalculatedType = {
@@ -833,11 +833,11 @@ declare module 'mongoose' {
         c?: true | {
             d?: true | undefined;
         } | undefined;
-        d?: true | ArrayOperators | undefined;
+        d?: true | ArrayProjectionOperators | undefined;
     }
   */
-  type Projector<T, Element> = T extends Array<infer U>
-    ? Projector<U, Element> | ArrayOperators
+  export type Projector<T, Element> = T extends Array<infer U>
+    ? Projector<U, Element> | ArrayProjectionOperators
     : T extends TreatAsPrimitives
       ? Element
       : T extends Record<string, any>

package/types/inferrawdoctype.d.ts

@@ -3,7 +3,8 @@ import {
   PathEnumOrString,
   OptionalPaths,
   RequiredPaths,
-  IsPathRequired
+  IsPathRequired,
+  PathAllowsNull
 } from './inferschematype';
 import { Binary, UUID } from 'mongodb';
 
@@ -24,7 +25,9 @@ declare module 'mongoose' {
     OptionalPaths<SchemaDefinition, TSchemaOptions['typeKey']>)
     ]: IsPathRequired<SchemaDefinition[K], TSchemaOptions['typeKey']> extends true
       ? ObtainRawDocumentPathType<SchemaDefinition[K], TSchemaOptions['typeKey'], TTransformOptions>
-      : ObtainRawDocumentPathType<SchemaDefinition[K], TSchemaOptions['typeKey'], TTransformOptions> | null;
+      : PathAllowsNull<SchemaDefinition[K]> extends true
+        ? ObtainRawDocumentPathType<SchemaDefinition[K], TSchemaOptions['typeKey'], TTransformOptions> | null
+        : ObtainRawDocumentPathType<SchemaDefinition[K], TSchemaOptions['typeKey'], TTransformOptions>;
   }, TSchemaOptions>;
 
   export type InferRawDocType<

package/types/inferschematype.d.ts

@@ -47,7 +47,9 @@ declare module 'mongoose' {
           TSchemaOptions['typeKey']
         > extends true ?
           ObtainDocumentPathType<DocDefinition[K], TSchemaOptions['typeKey']>
-        : ObtainDocumentPathType<DocDefinition[K], TSchemaOptions['typeKey']> | null;
+        : PathAllowsNull<DocDefinition[K]> extends true ?
+          ObtainDocumentPathType<DocDefinition[K], TSchemaOptions['typeKey']> | null
+        : ObtainDocumentPathType<DocDefinition[K], TSchemaOptions['typeKey']>;
       };
 
   /**
@@ -222,6 +224,12 @@ type OptionalPaths<T, TypeKey extends string = DefaultTypeKey> = Pick<
   OptionalPathKeys<T, TypeKey>
 >;
 
+/**
+ * @summary Checks if a document path allows `null` values.
+ * @param {P} P Document path.
+ */
+export type PathAllowsNull<P> = P extends { allowNull: false } ? false : true;
+
 /**
  * @summary Allows users to optionally choose their own type for a schema field for stronger typing.
  */

package/types/query.d.ts

@@ -1,13 +1,13 @@
 declare module 'mongoose' {
   import mongodb = require('mongodb');
 
-  type StringQueryTypeCasting = string | RegExp;
+  type StringQueryTypeCasting<T> = string extends T ? string | RegExp : T | RegExp;
   type ObjectIdQueryTypeCasting = Types.ObjectId | string;
   type DateQueryTypeCasting = string | number | NativeDate;
   type UUIDQueryTypeCasting = Types.UUID | string;
   type BufferQueryCasting = Buffer | mongodb.Binary | number[] | string | { $binary: string | mongodb.Binary };
   type QueryTypeCasting<T> = T extends string
-    ? StringQueryTypeCasting
+    ? StringQueryTypeCasting<T>
     : T extends Types.ObjectId
       ? ObjectIdQueryTypeCasting
       : T extends Types.UUID

package/types/schematypes.d.ts

@@ -104,6 +104,13 @@ declare module 'mongoose' {
       | [boolean, string]
       | [(this: THydratedDocumentType) => boolean, string];
 
+    /**
+     * Controls whether this path may be set to `null`. By default, Mongoose allows
+     * `null` for non-required paths. Set `allowNull: false` to allow `undefined`
+     * but disallow `null`.
+     */
+    allowNull?: boolean;
+
     /**
      * The default value for this path. If a function, Mongoose executes the function
      * and uses the return value as the default.
@@ -355,6 +362,9 @@ declare module 'mongoose' {
      */
     required(required: boolean, message?: string): this;
 
+    /** Adds or removes a validator that disallows `null` without making this path required. */
+    allowNull(allowNull: boolean): this;
+
     /** If the SchemaType is a subdocument or document array, this is the schema of that subdocument */
     schema?: Schema<any>;