Array

MongooseArray.prototype.$pop()

Pops the array atomically at most one time per document save().

NOTE:

Calling this mulitple times on an array before saving sends the same command as calling it once. This update is implemented using the MongoDB $pop method which enforces this restriction.

doc.array = [1,2,3];
 const popped = doc.array.$pop();
 console.log(popped); // 3
 console.log(doc.array); // [1,2]
 // no affect
 popped = doc.array.$pop();
 console.log(doc.array); // [1,2]
 doc.save(function (err) {
   if (err) return handleError(err);
   // we saved, now $pop works again
   popped = doc.array.$pop();
   console.log(popped); // 2
   console.log(doc.array); // [1]
 })

MongooseArray.prototype.$shift()

Atomically shifts the array at most one time per document save().

NOTE:

Calling this multiple times on an array before saving sends the same command as calling it once. This update is implemented using the MongoDB $pop method which enforces this restriction.

doc.array = [1,2,3];
 const shifted = doc.array.$shift();
 console.log(shifted); // 1
 console.log(doc.array); // [2,3]
 // no affect
 shifted = doc.array.$shift();
 console.log(doc.array); // [2,3]
 doc.save(function (err) {
   if (err) return handleError(err);
   // we saved, now $shift works again
   shifted = doc.array.$shift();
   console.log(shifted ); // 2
   console.log(doc.array); // [3]
 })

MongooseArray.prototype.addToSet()

Parameters

• [args…] «any»

Returns:

• «Array» the values that were added

Adds values to the array if not already present.

Example:

console.log(doc.array) // [2,3,4]
const added = doc.array.addToSet(4,5);
console.log(doc.array) // [2,3,4,5]
console.log(added)     // [5]

MongooseArray.prototype.includes()

Parameters

• obj «Object» the item to check

Returns:

• «Boolean»

Return whether or not the obj is included in the array.

MongooseArray.prototype.indexOf()

Parameters

• obj «Object» the item to look for

Returns:

• «Number»

Return the index of obj or -1 if not found.

MongooseArray.prototype.inspect()

Helper for console.log

MongooseArray.prototype.nonAtomicPush()

Parameters

• [args…] «any»

Pushes items to the array non-atomically.

NOTE:

marks the entire array as modified, which if saved, will store it as a $set operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it.

MongooseArray.prototype.pop()

Wraps Array#pop with proper change tracking.

Note:

marks the entire array as modified which will pass the entire thing to $set potentially overwritting any changes that happen between when you retrieved the object and when you save it.

MongooseArray.prototype.pull()

Parameters

• [args…] «any»

Pulls items from the array atomically. Equality is determined by casting the provided value to an embedded document and comparing using the Document.equals() function.

Examples:

doc.array.pull(ObjectId)
doc.array.pull({ _id: 'someId' })
doc.array.pull(36)
doc.array.pull('tag 1', 'tag 2')

To remove a document from a subdocument array we may pass an object with a matching _id.

doc.subdocs.push({ _id: 4815162342 })
doc.subdocs.pull({ _id: 4815162342 }) // removed

Or we may passing the _id directly and let mongoose take care of it.

doc.subdocs.push({ _id: 4815162342 })
doc.subdocs.pull(4815162342); // works

The first pull call will result in a atomic operation on the database, if pull is called repeatedly without saving the document, a $set operation is used on the complete array instead, overwriting possible changes that happened on the database in the meantime.

MongooseArray.prototype.push()

Parameters

• [args…] «Object»

Wraps Array#push with proper change tracking.

Example:

const schema = Schema({ nums: [Number] });
const Model = mongoose.model('Test', schema);
const doc = await Model.create({ nums: [3, 4] });
doc.nums.push(5); // Add 5 to the end of the array
await doc.save();
// You can also pass an object with `$each` as the
// first parameter to use MongoDB's `$position`
doc.nums.push({
  $each: [1, 2],
  $position: 0
});
doc.nums; // [1, 2, 3, 4, 5]

MongooseArray.prototype.remove()

Alias of pull

MongooseArray.prototype.set()

Returns:

• «Array» this

Sets the casted val at index i and marks the array modified.

Example:

// given documents based on the following
const Doc = mongoose.model('Doc', new Schema({ array: [Number] }));
const doc = new Doc({ array: [2,3,4] })
console.log(doc.array) // [2,3,4]
doc.array.set(1,"5");
console.log(doc.array); // [2,5,4] // properly cast to number
doc.save() // the change is saved
// VS not using array#set
doc.array[1] = "5";
console.log(doc.array); // [2,"5",4] // no casting
doc.save() // change is not saved

MongooseArray.prototype.shift()

Wraps Array#shift with proper change tracking.

Example:

doc.array = [2,3];
const res = doc.array.shift();
console.log(res) // 2
console.log(doc.array) // [3]

Note:

marks the entire array as modified, which if saved, will store it as a $set operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it.

MongooseArray.prototype.sort()

Wraps Array#sort with proper change tracking.

NOTE:

marks the entire array as modified, which if saved, will store it as a $set operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it.

MongooseArray.prototype.splice()

Wraps Array#splice with proper change tracking and casting.

Note:

marks the entire array as modified, which if saved, will store it as a $set operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it.

MongooseArray.prototype.toObject()

Parameters

• options «Object»

Returns:

• «Array»

Returns a native js Array.

MongooseArray.prototype.unshift()

Wraps Array#unshift with proper change tracking.

Note:

marks the entire array as modified, which if saved, will store it as a $set operation, potentially overwriting any changes that happen between when you retrieved the object and when you save it.