From a55d3882752fc488c7d75711b1851db1ff149a61 Mon Sep 17 00:00:00 2001 From: Valeri Karpov Date: Sat, 2 Jul 2022 19:05:39 -0400 Subject: [PATCH] docs: add Buffer, Decimal128, Map to docs Fix #11971 --- docs/source/api.js | 5 ++- lib/types/buffer.js | 54 +++++++++++++++---------------- lib/types/decimal128.js | 6 ++-- lib/types/map.js | 70 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 103 insertions(+), 32 deletions(-) diff --git a/docs/source/api.js b/docs/source/api.js index 9fd275e0406..e1325c76c1e 100644 --- a/docs/source/api.js +++ b/docs/source/api.js @@ -33,7 +33,10 @@ const files = [ 'lib/options/SchemaStringOptions.js', 'lib/types/DocumentArray/methods/index.js', 'lib/types/subdocument.js', - 'lib/types/ArraySubdocument.js' + 'lib/types/ArraySubdocument.js', + 'lib/types/buffer.js', + 'lib/types/decimal128.js', + 'lib/types/map.js' ]; module.exports = { diff --git a/lib/types/buffer.js b/lib/types/buffer.js index 941bf91878c..ca3787cc6f0 100644 --- a/lib/types/buffer.js +++ b/lib/types/buffer.js @@ -70,7 +70,7 @@ MongooseBuffer.mixin = { * * @api private * @property _subtype - * @receiver MongooseBuffer + * @memberOf MongooseBuffer */ _subtype: undefined, @@ -80,7 +80,7 @@ MongooseBuffer.mixin = { * * @api private * @method _markModified - * @receiver MongooseBuffer + * @memberOf MongooseBuffer */ _markModified: function() { @@ -97,7 +97,7 @@ MongooseBuffer.mixin = { * * @api public * @method write - * @receiver MongooseBuffer + * @memberOf MongooseBuffer */ write: function() { @@ -120,7 +120,7 @@ MongooseBuffer.mixin = { * @return {Number} The number of bytes copied. * @param {Buffer} target * @method copy - * @receiver MongooseBuffer + * @memberOf MongooseBuffer */ copy: function(target) { @@ -161,24 +161,22 @@ MongooseBuffer.mixin = { /** * Converts this buffer to its Binary type representation. * - * ####SubTypes: - * - * const bson = require('bson') - * bson.BSON_BINARY_SUBTYPE_DEFAULT - * bson.BSON_BINARY_SUBTYPE_FUNCTION - * bson.BSON_BINARY_SUBTYPE_BYTE_ARRAY - * bson.BSON_BINARY_SUBTYPE_UUID - * bson.BSON_BINARY_SUBTYPE_MD5 - * bson.BSON_BINARY_SUBTYPE_USER_DEFINED - * - * doc.buffer.toObject(bson.BSON_BINARY_SUBTYPE_USER_DEFINED); + * #### SubTypes: + * const bson = require('bson') + * bson.BSON_BINARY_SUBTYPE_DEFAULT + * bson.BSON_BINARY_SUBTYPE_FUNCTION + * bson.BSON_BINARY_SUBTYPE_BYTE_ARRAY + * bson.BSON_BINARY_SUBTYPE_UUID + * bson.BSON_BINARY_SUBTYPE_MD5 + * bson.BSON_BINARY_SUBTYPE_USER_DEFINED + * doc.buffer.toObject(bson.BSON_BINARY_SUBTYPE_USER_DEFINED); * * @see https://bsonspec.org/#/specification * @param {Hex} [subtype] * @return {Binary} * @api public * @method toObject - * @receiver MongooseBuffer + * @memberOf MongooseBuffer */ MongooseBuffer.mixin.toObject = function(options) { @@ -196,7 +194,7 @@ MongooseBuffer.mixin.$toObject = MongooseBuffer.mixin.toObject; * @return {Binary} * @api public * @method toBSON - * @receiver MongooseBuffer + * @memberOf MongooseBuffer */ MongooseBuffer.mixin.toBSON = function() { @@ -209,7 +207,7 @@ MongooseBuffer.mixin.toBSON = function() { * @param {Buffer} other * @return {Boolean} * @method equals - * @receiver MongooseBuffer + * @memberOf MongooseBuffer */ MongooseBuffer.mixin.equals = function(other) { @@ -233,23 +231,23 @@ MongooseBuffer.mixin.equals = function(other) { /** * Sets the subtype option and marks the buffer modified. * - * ####SubTypes: + * #### SubTypes: * - * const bson = require('bson') - * bson.BSON_BINARY_SUBTYPE_DEFAULT - * bson.BSON_BINARY_SUBTYPE_FUNCTION - * bson.BSON_BINARY_SUBTYPE_BYTE_ARRAY - * bson.BSON_BINARY_SUBTYPE_UUID - * bson.BSON_BINARY_SUBTYPE_MD5 - * bson.BSON_BINARY_SUBTYPE_USER_DEFINED + * const bson = require('bson') + * bson.BSON_BINARY_SUBTYPE_DEFAULT + * bson.BSON_BINARY_SUBTYPE_FUNCTION + * bson.BSON_BINARY_SUBTYPE_BYTE_ARRAY + * bson.BSON_BINARY_SUBTYPE_UUID + * bson.BSON_BINARY_SUBTYPE_MD5 + * bson.BSON_BINARY_SUBTYPE_USER_DEFINED * - * doc.buffer.subtype(bson.BSON_BINARY_SUBTYPE_UUID); + * doc.buffer.subtype(bson.BSON_BINARY_SUBTYPE_UUID); * * @see https://bsonspec.org/#/specification * @param {Hex} subtype * @api public * @method subtype - * @receiver MongooseBuffer + * @memberOf MongooseBuffer */ MongooseBuffer.mixin.subtype = function(subtype) { diff --git a/lib/types/decimal128.js b/lib/types/decimal128.js index 1ac89650b0f..b4459329ad9 100644 --- a/lib/types/decimal128.js +++ b/lib/types/decimal128.js @@ -1,11 +1,11 @@ /** - * ObjectId type constructor + * Decimal128 type constructor * * #### Example * - * const id = new mongoose.Types.ObjectId; + * const id = new mongoose.Types.Decimal128('3.1415'); * - * @constructor ObjectId + * @constructor Decimal128 */ 'use strict'; diff --git a/lib/types/map.js b/lib/types/map.js index 486c03f4e7f..1cfc98d8f9a 100644 --- a/lib/types/map.js +++ b/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 Map + * @instance + */ + Object.defineProperty(MongooseMap.prototype, '$isMongooseMap', { enumerable: false, writable: false,