feat(NODE-6503): Add Int32 as a SchemaType

docs/guide.md

@@ -80,6 +80,7 @@ The permitted SchemaTypes are:
 * [Decimal128](api/mongoose.html#mongoose_Mongoose-Decimal128)
 * [Map](schematypes.html#maps)
 * [UUID](schematypes.html#uuid)
+* [Int32](schematypes.html#int32)
 
 Read more about [SchemaTypes here](schematypes.html).
 

docs/schematypes.md

@@ -55,6 +55,7 @@ Check out [Mongoose's plugins search](http://plugins.mongoosejs.io) to find plug
 * [Schema](#schemas)
 * [UUID](#uuid)
 * [BigInt](#bigint)
+* [Int32](#int32)
 
 ### Example
 
@@ -68,6 +69,7 @@ const schema = new Schema({
   mixed: Schema.Types.Mixed,
   _someId: Schema.Types.ObjectId,
   decimal: Schema.Types.Decimal128,
+  int32bit: Schema.Types.Int32,
   array: [],
   ofString: [String],
   ofNumber: [Number],
@@ -647,6 +649,44 @@ const question = new Question({ answer: 42n });
 typeof question.answer; // 'bigint'
 ```
 
+### Int32 {#int32}
+
+Mongoose supports 32-bit integers as a SchemaType.
+Int32s are stored as [32-bit integers in MongoDB (BSON type "int")](https://www.mongodb.com/docs/manual/reference/bson-types/).
+
+```javascript
+const studentsSchema = new Schema({
+  id: Int32
+});
+const Student = mongoose.model('Student', schema);
+
+const student = new Student({ id: 1339 });
+typeof student.id; // 'number'
+```
+
+There are several types of values that will be successfully cast to a Number.
+
+```javascript
+new Student({ id: '15' }).id; // 15 as a Int32
+new Student({ id: true }).id; // 1 as a Int32
+new Student({ id: false }).id; // 0 as a Int32
+new Student({ id: { valueOf: () => 83 } }).id; // 83 as a Int32
+new Student({ id: '' }).id; // null as a Int32
+```
+
+If you pass an object with a `valueOf()` function that returns a Number, Mongoose will
+call it and assign the returned value to the path.
+
+The values `null` and `undefined` are not cast.
+
+The following inputs will result will all result in a [CastError](validation.html#cast-errors) once validated, meaning that it will not throw on initialization, only when validated:
+
+* NaN
+* strings that cast to NaN
+* objects that don't have a `valueOf()` function
+* a decimal that must be rounded to be an integer
+* an input that represents a value outside the bounds of an 32-bit integer
+
 ## Getters {#getters}
 
 Getters are like virtuals for paths defined in your schema. For example,

index.js

@@ -46,6 +46,7 @@ module.exports.Decimal128 = mongoose.Decimal128;
 module.exports.Mixed = mongoose.Mixed;
 module.exports.Date = mongoose.Date;
 module.exports.Number = mongoose.Number;
+module.exports.Int32 = mongoose.Int32;
 module.exports.Error = mongoose.Error;
 module.exports.MongooseError = mongoose.MongooseError;
 module.exports.now = mongoose.now;

lib/cast/int32.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const assert = require('assert');
+const BSON = require('bson');
+
+/**
+ * Given a value, cast it to a Int32, or throw an `Error` if the value
+ * cannot be casted. `null` and `undefined` are considered valid.
+ *
+ * @param {Any} value
+ * @return {Number}
+ * @throws {Error} if `value` does not represent an integer, or is outside the bounds of an 32-bit integer.
+ * @api private
+ */
+
+module.exports = function castInt32(val) {
+  if (val == null) {
+    return val;
+  }
+  if (val === '') {
+    return null;
+  }
+
+  let coercedVal;
+  if (val instanceof BSON.Int32 || val instanceof BSON.Double) {
+    coercedVal = val.value;
+  } else if (val instanceof BSON.Long) {
+    coercedVal = val.toNumber();
+  } else {
+    coercedVal = Number(val);
+  }
+
+  const INT32_MAX = 0x7FFFFFFF;
+  const INT32_MIN = -0x80000000;
+
+  if (coercedVal === (coercedVal | 0) &&
+      coercedVal >= INT32_MIN &&
+      coercedVal <= INT32_MAX
+  ) {
+    return coercedVal;
+  }
+  assert.ok(false);
+};

lib/mongoose.js

@@ -987,6 +987,7 @@ Mongoose.prototype.VirtualType = VirtualType;
  * - [ObjectId](https://mongoosejs.com/docs/schematypes.html#objectids)
  * - [Map](https://mongoosejs.com/docs/schematypes.html#maps)
  * - [Subdocument](https://mongoosejs.com/docs/schematypes.html#schemas)
+ * - [Int32](https://mongoosejs.com/docs/schematypes.html#int32)
  *
  * Using this exposed access to the `ObjectId` type, we can construct ids on demand.
  *
@@ -1138,6 +1139,22 @@ Mongoose.prototype.syncIndexes = function(options) {
 
 Mongoose.prototype.Decimal128 = SchemaTypes.Decimal128;
 
+
+/**
+ * The Mongoose Int32 [SchemaType](https://mongoosejs.com/docs/schematypes.html). Used for
+ * declaring paths in your schema that should be 32-bit integers.
+ * Do not use this to create a new Int32 instance, use `mongoose.Types.Int32`
+ * instead.
+ *
+ * #### Example:
+ *
+ *     const vehicleSchema = new Schema({ numTires: mongoose.Int32 });
+ *
+ * @property Int32
+ * @api public
+ */
+Mongoose.prototype.Int32 = SchemaTypes.Int32;
+
 /**
  * The Mongoose Mixed [SchemaType](https://mongoosejs.com/docs/schematypes.html). Used for
  * declaring paths in your schema that Mongoose's change tracking, casting,

lib/schema.js

@@ -2848,6 +2848,7 @@ module.exports = exports = Schema;
  * - [Mixed](https://mongoosejs.com/docs/schematypes.html#mixed)
  * - [UUID](https://mongoosejs.com/docs/schematypes.html#uuid)
  * - [BigInt](https://mongoosejs.com/docs/schematypes.html#bigint)
+ * - [Int32](https://mongoosejs.com/docs/schematypes.html#int32)
  *
  * Using this exposed access to the `Mixed` SchemaType, we can use them in our schema.
  *

lib/schema/bigint.js

@@ -81,12 +81,12 @@ SchemaBigInt.setters = [];
 SchemaBigInt.get = SchemaType.get;
 
 /**
- * Get/set the function used to cast arbitrary values to booleans.
+ * Get/set the function used to cast arbitrary values to bigints.
  *
  * #### Example:
  *
  *     // Make Mongoose cast empty string '' to false.
- *     const original = mongoose.Schema.BigInt.cast();
+ *     const original = mongoose.Schema.Types.BigInt.cast();
  *     mongoose.Schema.BigInt.cast(v => {
  *       if (v === '') {
  *         return false;

lib/schema/index.js

@@ -19,6 +19,7 @@ exports.ObjectId = require('./objectId');
 exports.String = require('./string');
 exports.Subdocument = require('./subdocument');
 exports.UUID = require('./uuid');
+exports.Int32 = require('./int32');
 
 // alias