W3cubDocs

/Mongoose

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];

 var 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];

 var 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
Returns:
  • «Array» the values that were added

Adds values to the array if not already present.

Example:

console.log(doc.array) // [2,3,4]
var 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

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

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

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
var Doc = mongoose.model('Doc', new Schema({ array: [Number] }));

var 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];
var 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 overwritting any changes that happen between when you retrieved the object and when you save it.

© 2010 LearnBoost
Licensed under the MIT License.
https://mongoosejs.com/docs/api/array.html