Документ

Выбрасывает ошибку, если заданный путь не заполнен

Пример:

const doc = await Model.findOne().populate('author');

doc.$assertPopulated('author'); // does not throw
doc.$assertPopulated('other path'); // throws an error

// Manually populate and assert in one call. The following does
// `doc.$set({ likes })` before asserting.
doc.$assertPopulated('likes', { likes });

Возвращает копию этого документа с глубокой копией _doc и $__.

Хэш, содержащий текущие ошибки валидации $errors.

Получить все дочерние документы (по алгоритму обхода в ширину)

Получает все заполненные документы, связанные с этим документом.

Не запускать валидацию для этого пути или сохранять изменения в этом пути.

Пример:

doc.foo = null;
doc.$ignore('foo');
doc.save(); // changes to foo will not be persisted and validators won't be run

Увеличивает числовое значение в path на заданное значение. При вызове save() для этого документа, Mongoose отправит $inc, а не $set.

Пример:

const schema = new Schema({ counter: Number });
const Test = db.model('Test', schema);

const doc = await Test.create({ counter: 0 });
doc.$inc('counter', 2);
await doc.save(); // Sends a `{ $inc: { counter: 2 } }` to MongoDB
doc.counter; // 2

doc.counter += 2;
await doc.save(); // Sends a `{ $set: { counter: 2 } }` to MongoDB

Псевдоним для .init

Проверяет, установлен ли путь по умолчанию.

Пример:

MyModel = mongoose.model('test', { name: { type: String, default: 'Val '} });
const m = new MyModel();
m.$isDefault('name'); // true

Геттер/сеттер, определяет, был ли документ удален.

Пример:

const product = await product.remove();
product.$isDeleted(); // true
product.remove(); // no-op, doesn't send anything to the db

product.$isDeleted(false);
product.$isDeleted(); // false
product.remove(); // will execute a remove against the db

Возвращает true, если заданный путь имеет значение null или содержит только пустые объекты. Полезно для определения, будет ли этот дочерний документ удален параметром minimize option.

Пример:

const schema = new Schema({ nested: { foo: String } });
const Model = mongoose.model('Test', schema);
const doc = new Model({});
doc.$isEmpty('nested'); // true
doc.nested.$isEmpty(); // true

doc.nested.foo = 'bar';
doc.$isEmpty('nested'); // false
doc.nested.$isEmpty(); // false

Псевдоним .isModified

Флаг булевого типа, указывающий, является ли документ новым. Если вы создаёте документ с помощью new, этот документ будет считаться "новым". $isNew — это способ, которым Mongoose определяет, нужно ли использовать insertOne() для создания нового документа или updateOne() для обновления существующего.

Пример:

const user = new User({ name: 'John Smith' });
user.$isNew; // true

await user.save(); // Sends an `insertOne` to MongoDB

С другой стороны, если вы загружаете существующий документ из базы данных с помощью findOne() или другой операции запроса, $isNew будет false.

Пример:

const user = await User.findOne({ name: 'John Smith' });
user.$isNew; // false

Mongoose устанавливает $isNew в false сразу после успешного выполнения save(). Это означает, что Mongoose устанавливает $isNew в false **до** выполнения хуков post('save'). В хуках post('save'), $isNew будет false, если save() завершился успешно.

Пример:

userSchema.post('save', function() {
  this.$isNew; // false
});
await User.create({ name: 'John Smith' });

Для дочерних документов $isNew имеет значение true, если у родительского документа установлено значение $isNew или если вы создали новый дочерний документ.

Пример:

// Assume `Group` has a document array `users`
const group = await Group.findOne();
group.users[0].$isNew; // false

group.users.push({ name: 'John Smith' });
group.users[1].$isNew; // true

Пустой объект, который вы можете использовать для хранения свойств в документе. Это полезно для передачи данных в middleware без конфликтов с внутренними компонентами Mongoose.

Пример:

schema.pre('save', function() {
  // Mongoose will set `isNew` to `false` if `save()` succeeds
  this.$locals.wasNew = this.isNew;
});

schema.post('save', function() {
  // Prints true if `isNew` was set before `save()`
  console.log(this.$locals.wasNew);
});

Помечает путь как валидный, удаляя существующие ошибки валидации.

Строка, содержащая текущую операцию, которую Mongoose выполняет над этим документом. Может быть null, 'save', 'validate', или 'remove'.

Пример:

const doc = new Model({ name: 'test' });
doc.$op; // null

const promise = doc.save();
doc.$op; // 'save'

await promise;
doc.$op; // null

Псевдоним для parent(). Если этот документ является дочерним или заполненным документом, возвращает родительский документ. В противном случае возвращает undefined.

Псевдоним .populated.

Геттер/сеттер для сессии, связанной с этим документом. Используется для автоматического установки session, если вы save() документ, полученный из запроса с связанной сессией.

Пример:

const session = MyModel.startSession();
const doc = await MyModel.findOne().session(session);
doc.$session() === session; // true
doc.$session(null);
doc.$session() === null; // true

Если это документ верхнего уровня, установка сессии распространяется на все дочерние документы.

Псевдоним для set(), используется во избежание конфликтов

Геттер/сеттер, определяющий, будет ли применяться опция timestamps по умолчанию для этого документа при использовании save() и bulkSave().

Пример:

const TestModel = mongoose.model('Test', new Schema({ name: String }, { timestamps: true }));
const doc = new TestModel({ name: 'John Smith' });

doc.$timestamps(); // true

doc.$timestamps(false);
await doc.save(); // Does **not** apply timestamps

Псевдоним .validate

Установите это свойство, чтобы добавить дополнительные фильтры запросов при сохранении этого документа, когда isNew равно false.

Пример:

// Make sure `save()` never updates a soft deleted document.
schema.pre('save', function() {
  this.$where = { isDeleted: false };
});

Принимает заполненное поле и возвращает его в незаполненное состояние.

Пример:

Model.findOne().populate('author').exec(function (err, doc) {
  console.log(doc.author.name); // Dr.Seuss
  console.log(doc.depopulate('author'));
  console.log(doc.author); // '5144cf8050f071d979c118a7'
})

Если путь не был указан, все заполненные поля возвращаются в незаполненное состояние.

Возвращает список путей, которые были непосредственно изменены. Прямой изменённый путь — это путь, который вы явно установили, будь то через doc.foo = 'bar', Object.assign(doc, { foo: 'bar' }), или doc.set('foo', 'bar').

Путь a может быть в modifiedPaths(), но не в directModifiedPaths(), потому что дочерний элемент a был изменён напрямую.

Пример:

const schema = new Schema({ foo: String, nested: { bar: String } });
const Model = mongoose.model('Test', schema);
await Model.create({ foo: 'original', nested: { bar: 'original' } });

const doc = await Model.findOne();
doc.nested.bar = 'modified';
doc.directModifiedPaths(); // ['nested.bar']
doc.modifiedPaths(); // ['nested', 'nested.bar']

Возвращает true, если этот документ равен другому документу.

Документы считаются равными, если у них совпадают _idы, если у обоих документов нет _id, в этом случае эта функция использует deepEqual().

Хэш, содержащий текущие ошибки валидации.

Возвращает значение пути.

Пример:

// path
doc.get('age') // 47

// dynamic casting to a string
doc.get('age', String) // "47"

Возвращает изменения, произошедшие в документе в формате, который будет отправлен в MongoDB.

Пример:

const userSchema = new Schema({
  name: String,
  age: Number,
  country: String
});
const User = mongoose.model('User', userSchema);
const user = await User.create({
  name: 'Hafez',
  age: 25,
  country: 'Egypt'
});

// returns an empty object, no changes happened yet
user.getChanges(); // { }

user.country = undefined;
user.age = 26;

user.getChanges(); // { $set: { age: 26 }, { $unset: { country: 1 } } }

await user.save();

user.getChanges(); // { }

Изменение объекта, который getChanges() возвращает, не влияет на состояние отслеживания изменений документа. Даже если вы delete user.getChanges().$set, Mongoose всё равно отправит $set на сервер.

Строковое представление _id этого документа.

Примечание:

Этот геттер по умолчанию присутствует во всех документах. Геттер можно отключить, установив id параметр своего Schema в ложь во время создания.

new Schema({ name: String }, { id: false });

Инициализирует документ без установщиков или помечания чего-либо изменённым.

Вызывается внутренне после того, как документ возвращён из mongodb. Обычно вам не нужно вызывать эту функцию самостоятельно.

Эта функция запускает init средства промежуточного ПО. Обратите внимание, что init хуки являются синхронными.

Помощник для console.log

Помечает путь как невалидный, вызывая сбой валидации.

Аргумент errorMsg станет сообщением ValidationError.

Аргумент value (если передан) будет доступен через свойство ValidationError.value.

doc.invalidate('size', 'must be less than 20', 14);

doc.validate(function (err) {
  console.log(err)
  // prints
  { message: 'Validation failed',
    name: 'ValidationError',
    errors:
     { size:
        { message: 'must be less than 20',
          name: 'ValidatorError',
          path: 'size',
          type: 'user defined',
          value: 14 } } }
})

Возвращает true, если path был напрямую установлен и изменён, иначе false.

Пример:

doc.set('documents.0.title', 'changed');
doc.isDirectModified('documents.0.title') // true
doc.isDirectModified('documents') // false

Проверяет, был ли path явно выбран. Если проекции нет, всегда возвращает true.

Пример:

Thing.findOne().select('nested.name').exec(function (err, doc) {
   doc.isDirectSelected('nested.name') // true
   doc.isDirectSelected('nested.otherName') // false
   doc.isDirectSelected('nested')  // false
})

Проверяет, находится ли path в состоянии init, то есть он был установлен Document#init() и не изменялся с тех пор.

Возвращает true, если любой из заданных путей изменён, иначе false. Если аргументов нет, возвращает true , если какой-либо путь в этом документе изменён.

Если path задан, проверяет, был ли путь или любой полный путь, содержащий path в качестве части цепочки путей, изменён.

Пример:

doc.set('documents.0.title', 'changed');
doc.isModified()                      // true
doc.isModified('documents')           // true
doc.isModified('documents.0.title')   // true
doc.isModified('documents otherProp') // true
doc.isDirectModified('documents')     // false

Устаревший псевдоним для $isNew.

Проверяет, был ли path выбран в исходном запросе, который инициализировал этот документ.

Пример:

const doc = await Thing.findOne().select('name');
doc.isSelected('name') // true
doc.isSelected('age')  // false

Помечает путь как содержащий изменения, которые нужно записать в базу данных.

Очень полезно при использовании типов Mixed.

Пример:

doc.mixed.type = 'changed';
doc.markModified('mixed.type');
doc.save() // changes to mixed.type are now persisted

Возвращает список путей, которые были изменены.

Перезапишите все значения в этом документе значениями obj, за исключением неизменяемых свойств. Ведёт себя аналогично set(), за исключением того, что сбрасывает все свойства, которые не присутствуют в obj.

Если этот документ является поддокументом или заполненным документом, возвращает родительский документ. Возвращает исходный документ, если родительского документа нет.

Заполняет пути существующего документа.

Пример:

// Given a document, `populate()` lets you pull in referenced docs
await doc.populate([
  'stories',
  { path: 'fans', sort: { name: -1 } }
]);
doc.populated('stories'); // Array of ObjectIds
doc.stories[0].title; // 'Casino Royale'
doc.populated('fans'); // Array of ObjectIds

// If the referenced doc has been deleted, `populate()` will
// remove that entry from the array.
await Story.delete({ title: 'Casino Royale' });
await doc.populate('stories'); // Empty array

// You can also pass additional query options to `populate()`,
// like projections:
await doc.populate('fans', '-email');
doc.fans[0].email // undefined because of 2nd param `select`

Получает _id(ы), используемые во время заполнения указанного path.

Пример:

const doc = await Model.findOne().populate('author');

console.log(doc.author.name); // Dr.Seuss
console.log(doc.populated('author')); // '5144cf8050f071d979c118a7'

Если путь не был заполнен, возвращает undefined.

Отправляет команду replaceOne с этим документом _id в качестве селектора запроса.

Допустимые опции:

• также как и в Model.replaceOne

Сохраняет этот документ, вставляя новый документ в базу данных, если document.isNew равно true, или отправляет операцию updateOne только с изменениями в базе данных, не заменяя весь документ в последнем случае.

Пример:

product.sold = Date.now();
product = await product.save();

Если сохранение прошло успешно, возвращаемый промис будет выполнен с сохранённым документом.

Пример:

const newProduct = await product.save();
newProduct === product; // true

Схема документа.

Устанавливает значение пути или нескольких путей. Псевдоним для .$set.

Пример:

// path, value
doc.set(path, value)

// object
doc.set({
    path  : value
  , path2 : {
       path  : value
    }
})

// on-the-fly cast to number
doc.set(path, value, Number)

// on-the-fly cast to string
doc.set(path, value, String)

// changing strict mode behavior
doc.set(path, value, { strict: false });

Значение, возвращаемое этим методом, используется в вызовах JSON.stringify(doc).

Этот метод принимает те же параметры, что и Document#toObject. Чтобы применить эти параметры по умолчанию ко всем документам вашей схемы, установите параметр схемы toJSON в то же значение.

schema.set('toJSON', { virtuals: true });

Существует одно различие между toJSON() и toObject() параметрами. При вызове toJSON(), параметр flattenMaps по умолчанию равен true, потому что JSON.stringify() по умолчанию не преобразует карты в объекты. При вызове toObject(), параметр flattenMaps по умолчанию равен false.

См. параметры схемы для получения дополнительной информации о настройке параметров toJSON по умолчанию.

Преобразует этот документ в обычный JavaScript-объект (POJO).

Буферы преобразуются в экземпляры mongodb.Binary для правильного хранения.

Геттеры/Виртуальные свойства

Пример применения только геттеров путей

doc.toObject({ getters: true, virtuals: false })

Пример применения только виртуальных геттеров

doc.toObject({ virtuals: true })

Пример применения геттеров путей и виртуальных свойств

doc.toObject({ getters: true })

Чтобы применить эти параметры по умолчанию ко всем документам вашей схемы, установите параметр схемы toObject в то же значение.

schema.set('toObject', { virtuals: true })

Преобразование:

Возможно, нам потребуется выполнить преобразование результирующего объекта на основе некоторых критериев, например, удалить какую-либо конфиденциальную информацию или вернуть пользовательский объект. В этом случае мы задаём необязательную функцию transform.

Функции преобразования принимают три аргумента

function (doc, ret, options) {}

• doc Документ mongoose, который преобразуется
• ret Представление простого объекта, который был преобразован
• options Параметры, используемые (либо параметры схемы, либо параметры, переданные непосредственно)

Пример:

// specify the transform schema option
if (!schema.options.toObject) schema.options.toObject = {};
schema.options.toObject.transform = function (doc, ret, options) {
  // remove the _id of every document before returning the result
  delete ret._id;
  return ret;
}

// without the transformation in the schema
doc.toObject(); // { _id: 'anId', name: 'Wreck-it Ralph' }

// with the transformation
doc.toObject(); // { name: 'Wreck-it Ralph' }

С помощью преобразований мы можем сделать гораздо больше, чем удалить свойства. Мы можем даже вернуть полностью новые настроенные объекты:

if (!schema.options.toObject) schema.options.toObject = {};
schema.options.toObject.transform = function (doc, ret, options) {
  return { movie: ret.name }
}

// without the transformation in the schema
doc.toObject(); // { _id: 'anId', name: 'Wreck-it Ralph' }

// with the transformation
doc.toObject(); // { movie: 'Wreck-it Ralph' }

Примечание: если функция преобразования возвращает undefined, возвращаемое значение будет проигнорировано.

Преобразования также могут быть применены непосредственно, переопределяя любое преобразование, заданное в параметрах:

function xform (doc, ret, options) {
  return { inline: ret.name, custom: true }
}

// pass the transform as an inline option
doc.toObject({ transform: xform }); // { inline: 'Wreck-it Ralph', custom: true }

Если вы хотите пропустить преобразования, используйте transform: false:

schema.options.toObject.hide = '_id';
schema.options.toObject.transform = function (doc, ret, options) {
  if (options.hide) {
    options.hide.split(' ').forEach(function (prop) {
      delete ret[prop];
    });
  }
  return ret;
}

const doc = new Doc({ _id: 'anId', secret: 47, name: 'Wreck-it Ralph' });
doc.toObject();                                        // { secret: 47, name: 'Wreck-it Ralph' }
doc.toObject({ hide: 'secret _id', transform: false });// { _id: 'anId', secret: 47, name: 'Wreck-it Ralph' }
doc.toObject({ hide: 'secret _id', transform: true }); // { name: 'Wreck-it Ralph' }

Если вы передаёте преобразование в параметрах toObject(), Mongoose применит преобразование к вложенным документам в дополнение к документу верхнего уровня. Аналогично, transform: false пропускает преобразования для всех вложенных документов. Обратите внимание, что это поведение отличается для преобразований, определённых в схеме: если вы определите преобразование в schema.options.toObject.transform, это преобразование не будет применено к вложенным документам.

const memberSchema = new Schema({ name: String, email: String });
const groupSchema = new Schema({ members: [memberSchema], name: String, email });
const Group = mongoose.model('Group', groupSchema);

const doc = new Group({
  name: 'Engineering',
  email: 'dev@mongoosejs.io',
  members: [{ name: 'Val', email: 'val@mongoosejs.io' }]
});

// Removes `email` from both top-level document **and** array elements
// { name: 'Engineering', members: [{ name: 'Val' }] }
doc.toObject({ transform: (doc, ret) => { delete ret.email; return ret; } });

Преобразования, как и все эти параметры, также доступны для toJSON. См. этот справочник по JSON.stringify(), чтобы узнать, почему toJSON() и toObject() — это отдельные функции.

См. параметры схемы для получения дополнительной информации.

Во время сохранения никакие пользовательские параметры не применяются к документу перед отправкой в базу данных.

Утилита для console.log

Очищает состояние модификации указанного пути.

Пример:

doc.foo = 'bar';
doc.unmarkModified('foo');
doc.save(); // changes to foo will not be persisted

Отправляет команду updateOne с этим документом _id в качестве селектора запроса.

Пример:

weirdCar.updateOne({$inc: {wheels:1}}, { w: 1 }, callback);

Допустимые параметры:

• аналогично Model.updateOne

Выполняет зарегистрированные правила валидации для этого документа.

Примечание:

Этот метод вызывается pre сохранения, и если правило валидации нарушено, сохранение прерывается, и ошибка выбрасывается.

Пример:

await doc.validate({ validateModifiedOnly: false, pathsToSkip: ['name', 'email']});

Выполняет зарегистрированные правила валидации (пропуская асинхронные валидаторы) для этого документа.

Примечание:

Этот метод полезен, если вам нужна синхронная валидация.

Пример:

const err = doc.validateSync();
if (err) {
  handleError(err);
} else {
  // validation passed
}