Mongoose¶

Mongoose - это ORM (Object Relational Mapping - объектно-реляционное отображение или связывание) для MongoDB. Mongoose предоставляет в распоряжение разработчиков простое основанное на схемах решение для моделирования данных приложения, включающее встроенную проверку типов, валидацию, формирование запросов и хуки, отвечающие за реализацию дополнительной логики обработки запросов.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

const mongoose = require('mongoose');

mongoose.connect('mongodb://localhost:27017/test', {
    useNewUrlParser: true,
    useUnifiedTopology: true,
});

const Cat = mongoose.model('Cat', { name: String });

const kitty = new Cat({ name: 'Cat' });
kitty.save().then(() => console.log('мяу'));

Быстрый старт¶

Установка

1
2
3

yarn add mongoose
# или
npm i mongoose

Подключение к БД

1
2
3
4
5
6
7

const mongoose = require('mongoose');
const { MONGODB_URI } = require('./config.js');

mongoose.connect(MONGODB_URI, {
    useNewUrlParser: true,
    useUnifiedTopology: true,
});

Обработка ошибки и подключения

1
2
3
4
5
6
7
8

const db = mongoose.connection;
db.on(
    'error',
    console.error.bind(console, 'Ошибка подключения: ')
);
db.once('open', () => {
    // Подлючение установлено
});

Создание схемы и модели

1
2
3
4
5
6
7

const { Schema, model } = mongoose;

const catSchema = new Schema({
    name: String,
});

module.exports = model('Cat', catSchema);

Создание объекта

1
2
3

const Cat = require('./Cat.js');

const kitty = new Cat({ name: 'Cat' });

Добавление метода

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

catSchema.methods.speak = function () {
    const greet = this.name
        ? `Меня зовут ${this.name}`
        : `У меня нет имени`;

    console.log(greet);
};

const kitty = new Cat({ name: 'Cat' });
kitty.speak(); // Меня зовут Cat

Сохранение объекта

1
2
3
4

kitty.save((err, cat) => {
    if (err) console.error(err);
    cat.speak();
});

Поиск всех объектов определенной модели

1
2
3
4

Cat.find((err, cats) => {
    if (err) console.error(err);
    console.log(cats);
});

Поиск одного объекта (по имени)

1

Cat.findOne({ name: 'Cat' }, callback);

Для поиска объекта можно использовать регулярное выражение.

Схема¶

Создание схемы

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

const { Schema } = required('mongoose');

const blogSchema = new Schema({
    title: String,
    author: String,
    body: String,
    comments: [
        {
            body: String,
            createdAt: Date,
        },
    ],
    createdAt: {
        type: Date,
        default: Date.now(),
    },
    hidden: Boolean,
    meta: {
        votes: Number,
        favs: Number,
    },
});

Дополнительные поля можно добавлять с помощью метода Schema.add()

1
2
3
4
5
6
7
8
9

const firstSchema = new Schema();
firstSchema.add({
    name: 'string',
    color: 'string',
    price: 'number',
});

const secondSchema = new Schema();
secondSchema.add(firstSchema).add({ year: Number });

По умолчанию Mongoose добавляет к схеме свойство _id (его можно перезаписывать)

1
2
3
4
5
6

const schema = new Schema();
schema.path('_id'); // ObjectId { ... }

const Model = model('Test', schema);
const doc = new Model();
doc._id; // ObjectId { ... }

Кроме методов экземпляра, схема позволяет определять статические функции

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

catSchema.statics.findByName = function (name) {
    return this.find({ name: new RegExp(name, 'i') });
};

// или
catSchema.static('findByName', function (name) {
    return this.find({ name: new RegExp(name, 'i') });
});

const Cat = model('Cat', catSchema);
const cats = await Cat.findByName('Kitty');

Также для определения дополнительного функционала можно использовать утилиты для формирования запроса

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

catSchema.query.byName = function (name) {
    return this.where({ name: new RegExp(name, 'i') });
};

const Cat = model('Cat', catSchema);

Cat.find()
    .byName('Cat')
    .exec((err, cats) => {
        console.log(cats);
    });

Cat.findOne()
    .byName('Cat')
    .exec((err, cat) => {
        console.log(cat);
    });

Mongoose позволяет определять вторичные индексы в Schema на уровне пути или на уровне schema

1
2
3
4
5
6
7

const catSchema = new Schema({
    name: String,
    type: String,
    tags: { type: [String], index: true }, // уровень поля
});

catSchema.index({ name: 1, type: -1 }); // уровень схемы

При запуске приложения для каждого индекса вызывается createIndex(). Индексы полезны для разработки, но в продакшне их лучше не использовать. Отключить индексацию можно с помощью autoIndex: false

1
2
3
4
5

mongoose.connect(MONGODB_URL, { autoIndex: false })
// или
catSchema.set('autoIndex', false)
// или
new Schema({...}, { autoIndex: false })

Схема позволяет создавать виртуальные свойства, которые можно получать и устанавливать, но которые не записываются в БД

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// Схема
const personSchema = new Schema({
    name: {
        first: String,
        last: String,
    },
});

// Модель
const Person = model('Person', personSchema);

// Документ
const john = new Person({
    name: {
        first: 'John',
        last: 'Smith',
    },
});

// Виртуальное свойство для получения и записи полного имени
personSchema
    .virtual('fullName')
    .get(function () {
        return `${this.name.first} ${this.name.last}`;
    })
    .set(function (str) {
        [this.name.first, this.name.last] = str.split(' ');
    });

john.fullName; // John Smith
john.fullName = 'Jane Air';
john.fullName; // Jane Air

Настройки¶

Настройки схемы могут передаваться в виде объекта в конструктор или в виде пары ключ/значение в метод set()

1
2
3
4

new Schema({...}, options)

const schema = new Schema({...})
schema.set(option, value)

• autoIndex: bool - определяет создание индексов (по умолчанию true)
• autoCreate: bool - определяет создание коллекций (по умолчанию false)
• bufferCommands: bool и bufferTimaoutMs: num - определяет, должны ли команды буферизоваться (по умолчанию true), и в течение какого времени (по умолчанию отсутствует)
• capped: num - позволяет создавать закрытые коллекции ({ capped: 1024 }, 1024 - размер в байтах)
• collection: str - определяет название коллекции (по умолчанию используется название модели)
• id: bool - позволяет отключать получение _id через виртуальный геттер id
• _id: bool - позволяет отключать создание _id
• minimize: bool - определяет удаление пустых объектов (по умолчанию true). Для определения пустого объекта используется утилита $isEmpty - doc.$isEmpty(fieldName)
• strict: bool - определяет, должны ли значения, передаваемые в конструктор модели и отсутствующие в схеме, сохраняться в БД (по умолчанию true, значит, не должны)
• typeKey: str - позволяет определять ключ типа (по умолчанию type)
• validateBeforeSave: bool - позволяет отключать валидацию объектов перед их сохранением в БД (по умолчанию true)
• collation: obj - определяет порядок разрешения коллизий, например, при совпадении двух объектов ({collation: { locale: 'en_US', strength: 1 }} - совпадающие ключи/значения на латинице будут игнорироваться)
• timestamps: bool | obj - позволяет добавлять к схеме поля createdAt и updatedAt с типом Date. Данным полям можно присваивать другие названия - { timestamps: { createdAt: 'created_at' } }. По умолчанию для создания даты используется new Date(). Это можно изменить - { timestamps: { currentTime: () => ~~(Date.now() / 1000) } }

Метод loadClass() позволяет создавать схемы из классов:

• методы класса становятся методами Mongoose
• статические методы класса становятся статическими методами Mongoose
• геттеры и сеттеры становятся виртуальными методами Mongoose

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

class MyClass {
    myMethod() {
        return 42;
    }
    static myStatic() {
        return 24;
    }
    get myVirtual() {
        return 31;
    }
}

const schema = new Schema();
schema.loadClass(MyClass);

console.log(schema.methods); // { myMethod: ... }
console.log(schema.statics); // { myStatic: ... }
console.log(schema.virtuals); // { myVirtual: ... }

SchemaTypes¶

Что такое SchemaType?¶

Схема представляет собой объект конфигурации для модели. SchemaType - это объект конфигурации для определенного свойства модели. SchemaType определяет тип, геттеры, сеттеры и валидаторы свойства.

Доступные SchemaTypes (типы)

• String
• Number
• Date
• Buffer
• Boolean
• Mixed
• ObjectId
• Array
• Decimal128
• Map

Пример¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

const schema = new Schema({
    name: String,
    binary: Buffer,
    livilng: Boolean,
    updated: {
        type: Date,
        default: Date.now,
    },
    age: {
        type: Number,
        min: 18,
        max: 65,
    },
    mixed: Schema.Types.Mixed,
    _someId: Schema.Types.ObjectId,
    decimal: Schema.Types.Decimal128,
    array: [],
    ofString: [String],
    ofNumber: [Number],
    ofDates: [Date],
    ofBuffer: [Buffer],
    ofBoolean: [Boolean],
    ofMixed: [Schema.Types.Mixed],
    ofObjectId: [Schema.Types.ObjectId],
    ofArrays: [[]],
    ofArrayOfNumber: [[Number]],
    nested: {
        stuff: {
            type: String,
            lowercase: true,
            trim: true,
        },
    },
    map: Map,
    mapOfString: {
        type: Map,
        of: String,
    },
});

Существует три способа определения типа

1
2
3
4
5
6
7
8

// 1
name: String;
// 2
name: 'String' | 'string';
// 3
name: {
    type: String;
}

type¶

Для определения свойства с названием type необходимо сделать следующее

1
2
3
4
5
6
7

new Schema({
    asset: {
        // !
        type: { type: String },
        ticker: String,
    },
});

Настройки¶

При определении типа схемы с помощью объекта можно определять дополнительные настройки.

Общие¶

• required: bool - определяет, является ли поле обязательным
• default: any | fn - значение поля по умолчанию
• validate: fn - функция-валидатор
• get: fn - кастомный геттер
• set: fn - кастомный сеттер
• alias: str - алиас, синоним, виртуальный геттер/сеттер
• immutable: bool - определяет, является ли поле иммутабельным (неизменяемым)
• transform: fn - функция, вызываемая при выполнении Document.toJSON(), включая JSON.stringify()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

const numberSchema = new Schema({
    intOnly: {
        type: Number,
        get: (v) => Math.round(v),
        set: (v) => Math.round(v),
        alias: 'i',
    },
});

const Number = model('Number', numberSchema);

const doc = new Number();
doc.intOnly = 2.001;
doc.intOnly; // 2
doc.i; // 2
doc.i = 3.002;
doc.intOnly; // 3
doc.i; // 3

Индексы¶

• index: bool
• unique: bool - определяет, должны ли индексы быть уникальными
• sparse: bool - определяет, должны ли индексы создаваться только для индексируемых полей

Строка¶

• lowercase: bool
• uppercase: bool
• trim: bool
• match: RegExp - валидатор в виде регулярного выражения
• enum: arr - валидатор, проверяющий, совпадает ли строка с каким-либо элементом массива
• minLength: num
• maxLength: num
• populate: obj - дефолтные настройки популяции (извлечения данных, заполнения данными)

Число¶

• min: num
• max: num
• enum: arr
• populate: obj

Дата¶

• min: Date
• max: Date

ObjectId¶

• populate: obj

Особенности использования некоторых типов¶

Даты¶

При изменении даты, например, с помощью метода setMonth(), ее необходимо пометить с помощью markModified(), иначе, изменения не будут сохранены

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const schema = new Schema('date', { dueDate: Date });
schema.findOne((err, doc) => {
    doc.dueDate.setMonth(3);
    // это не сработает
    doc.save();

    // надо делать так
    doc.markModified('dueDate');
    doc.save();
});

Mixed (смешанный тип)¶

Mongoose не осуществляет проверку смешанных типов

1
2
3
4

new Schema({ any: {} });
new Schema({ any: Object });
new Schema({ any: Schema.Types.Mixed });
new Schema({ any: mongoose.Mixed });

При изменении значений смешанного типа, их, как и даты, необходимо помечать с помощью markModified.

ObjectId¶

ObjectId - это специальный тип, обычно используемый для уникальных идентификаторов

1

const carSchema = new Schema({ driver: mongoose.ObjectId });

ObjectId - это класс, а сами ObjectIds - это объекты, которые, обычно, представлены в виде строки. При преобразовании ObjectId с помощью метода toString(), мы получаем 24-значную шестнадцатиричную строку

1
2
3
4

const Car = model('Car', carSchema);

const car = new Car();
car.driver.toString(); // 5e1a0651741b255ddda996c4

Map¶

MongooseMap - это подкласс JS-класса Map. Ключи карт должны быть строками

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

const userSchema = new Schema({
    socialMediaHandles: {
        type: Map,
        of: String,
    },
});

const User = model('User', userSchema);
const user = new User({
    socialMediaHandles: {},
});

Для получения и установки значений следует использовать get() и set()

1
2
3
4
5
6
7

user.socialMediaHandles.set('github', 'username');
// или
user.set('socialMediaHandles.github', 'username');

user.socialMediaHandles.get('github'); // username
// или
user.get('socialMediaHandles.github'); // username

Для популяции элементов в карту используется синтаксис $*

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

const userSchema = new Schema({
    socialMediaHandles: {
        type: Map,
        of: new Schema({
            handle: String,
            oauth: {
                type: ObjectId,
                ref: 'OAuth',
            },
        }),
    },
});
const User = model('User', userSchema);
// заполняем свойство `oauth` данными пользователя
const user = await User.findOne().populate(
    'socialMediaHandles.$*.oauth'
);

Геттеры¶

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

const root = 'https://examplce.com/avatars';

const userSchema = new Schema({
    name: String,
    avatar: {
        type: String,
        get: (v) => `${root}/${v}`,
    },
});

const User = model('User', userSchema);

const user = new User({ name: 'John', avatar: 'john.png' });
user.avatar; // https://examplce.com/avatars/john.png

Схема¶

В качестве типов полей схемы можно использовать другие схемы

1
2
3
4
5
6
7
8

const subSchema = new Schema({});

const schema = new Schema({
    data: {
        type: subSchema,
        default: {},
    },
});

Подключение¶

Для подключения к MongoDB используется метод mongoose.connect()

1
2
3
4

mongoose.connect(MONGODB_URL, {
    useNewUrlParser: true,
    useUnifiedTopology: true,
});

Данный метод принимает строку с адресом БД и объект с настройками.

Буферизация¶

За счет буферизации Mongoose позволяет использовать модели, не дожидаясь подключения к БД. Отключить буферизацию можно с помощью bufferCommands: false. Отключить ожидание создания коллекций можно с помощью autoCreate: false

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const schema = new Schema(
    {
        name: String,
    },
    {
        capped: { size: 1024 },
        bufferCommands: false,
        autoCreate: false,
    }
);

Обработка ошибок¶

Существует 2 класса ошибок, возникающих при подключении к БД:

• Ошибка при первоначальном подключении. При провале подключения Mongoose отправляет событие error и промис, возвращаемый connect(), отклоняется. При этом, Mongoose не пытается выполнить повторное подключение
• Ошибка после установки начального соединения. В этом случае Mongoose пытается выполнить повторное подключение

Для обработки первого класса ошибок используется catch() или try/catch

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

mongoose
    .connect(uri, options)
    .catch((err) => handleError(err));

// или
try {
    await mongoose.connect(uri, options);
} catch (err) {
    handleError(err);
}

Для обработки второго класса ошибок нужно прослушивать соответствующее событие

1
2
3

mongoose.connection.on('error', (err) => {
    handleError(err);
});

Настройки¶

• bufferCommands: bool - позволяет отключать буферизацию
• user: str / pass: str - имя пользователя и пароль для аутентификации
• autoIndex: bool - позволяет отключать автоматическую индексацию
• dbName: str - название БД для подключения

Важные

• useNewUrlParser: bool - true означает использование нового MongoDB-парсера для разбора строки подключения (должно быть включено во избежание предупреждений)
• useCreateIndex: bool - true означает использование createIndex() вместо ensureIndex() для создания индексов (должно быть включено при индексации)
• useFindAndModify: bool - false означает использование нативного findOneAndUpdate() вместо findAndModify()
• useUnifiedTopology: bool - true означает использование нового движка MongoDB для управления подключением (должно быть включено во избежание предупреждений)
• poolSize: num - максимальное количество сокетов для данного подключения
• socketTimeoutMS: num - время, по истечении которого неактивный сокет отключается от БД
• family: 4 | 6 - версия IP для подключения
• authSource: str - БД, используемая при аутентификации с помощью user и pass

Колбек¶

Функция connect() также принимает колбек, возвращающий промис

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

mongoose.connect(uri, options, (err) => {
  if (err) // обработка ошибки
  // успех
})

// или
mongoose.connect(uri, options).then(
  () => { /* обработка ошибки */ },
  err => { /* успех */ }
)

События, возникающие при подключении¶

• connecting - начало подключения
• connected - успешное подключение
• open - эквивалент connected
• disconnecting - приложение вызвало Connection.close() для отключения от БД
• disconnected - потеря подключения
• close - возникает после выполнения Connection.close()
• reconnected - успешное повторное подключение
• error - ошибка подключения
• fullsetup - возникает при подключении к набору реплик (replica set), когда выполнено подключение к основной реплике и одной из вторичных
• all - возникает при подключении к набору реплик, когда выполнено подключение ко всем серверам
• reconnectedFailed - провал всех reconnectTries (попыток выполнения повторного подключения)

Подключение к набору реплик¶

1
2
3
4
5
6
7
8

mongoose.connect(
    'mongodb://<username>:<password>@host1.com:27017,host2.com:27017,host3.com:27017/testdb'
);

// к одному узлу
mongoose.connect(
    'mongodb://host1.com:port1/?replicaSet=rsName'
);

Подключение к нескольким БД¶

Подключение к нескольким БД выполняется с помощью метода createConnection(). Существует два паттерна для выполнения такого подключения:

• Экспорт подключения и регистрация моделей для подключения в одном файле

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// connections/fast.js
const mongoose = require('mongoose');

const conn = mongoose.createConnection(
    process.env.MONGO_URI
);
conn.model('User', require('../schemas/user'));

module.exports = conn;

// connections/slow.js
const mongoose = require('mongoose');

const conn = mongoose.createConnection(
    process.env.MONGO_URI
);
conn.model('User', require('../schemas/user'));
conn.model('PageView', require('../schemas/pageView'));

module.exports = conn;

• Регистрация подключений с функцией внедрения зависимостей

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

const mongoose = require('mongoose');

module.exports = function connFactory() {
    const conn = mongoose.createConnection(
        process.env.MONGO_URI
    );

    conn.model('User', require('../schemas/user'));
    conn.model('PageView', require('../schemas/pageView'));

    return conn;
};

Модель¶

Модели - это конструкторы, компилируемые из определений Schema. Экземпляр модели называется документом. Модели отвечают за создание и получение документов из БД.

Компиляция модели¶

При вызове mongoose.model() происходит компиляция модели

1
2
3
4
5

const schema = new Schema({
    name: 'string',
    age: 'number',
});
const User = model('User', schema);

Первый аргумент - название коллекции. В данном случае будет создана коллекция users.

Обратите внимание: функция model() создает копию schema. Убедитесь, что перед вызовом model() полностью настроили schema (включая определение хуков).

Создание и сохранение документа¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

const User = model('User', userSchema);

const user = new User({ name: 'John', age: 30 });
user.save((err) => {
    if (err) return handleError(err);
    console.log(user);
});

// или
User.create({ name: 'John', age: 30 }, (err, user) => {
    if (err) return handleError(err);
    console.log(user);
});

// или для создания нескольких документов
User.insertMany(
    [
        {
            name: 'John',
            age: 30,
        },
        {
            name: 'Jane',
            age: 20,
        },
    ],
    (err) => {}
);

Получение документов¶

Для получения документов из БД используются методы find(), findById(), findOne(), where() и др.

1
2
3
4

User.find({ name: 'John' })
    .where('createdAt')
    .gt(oneYearAgo)
    .exec(callback);

Удаление документов¶

Для удаления документов используются методы deleteOne(), deleteMany() и др.

1

User.deleteOne({ name: 'John' }, (err) => {});

Обновление документов¶

Для обновления документов используется метод updateOne() и др.

1
2
3
4
5
6
7
8
9

User.updateOne(
    { name: 'John' },
    { name: 'Bob' },
    (err, res) => {
        // Обновляется как минимум один документ
        // `res.modifiedCount` содержит количество обновленных документов
        // Обновленные документы не возвращаются
    }
);

Если мы хотим обновить один документ и вернуть его, то следует использовать findOneAndUpdate().

Поток изменений¶

Поток изменений позволяет регистрировать добавление/удаление и обновление документов

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

const run = async () => {
    const userSchema = new Schema({
        name: String,
    });
    const User = model('User', userSchema);

    // Создаем поток изменений
    // При обновлении БД отправляется (emitted) событие `change`
    User.watch().on('change', (data) =>
        console.log(new Date(), data)
    );

    console.log(new Date(), 'Создание документа');
    await User.create({ name: 'John Smith' });
    console.log(new Date(), 'Документ успешно создан');
};

Документ¶

Документы - это экземпляры моделей. Документ и модель - разные классы Mongoose. Класс модели является подклассом класса документа. При использовании конструктора модели создается новый документ.

Извлечение документа¶

1

const doc = await Model.findOne();

Обновление документа с помощью save()¶

Документы можно изменять с помощью обычного присвоения - Mongoose автоматически преобразует его в оператор обновления MongoDB

1
2
3
4

doc.name = 'foo';

// `Mongoose` отправляет `updateOne({ _id: doc._id }, { $set: { name: 'foo' } })` в `MongoDB`
await doc.save();

Метод save() возвращает промис, который при успешном завершении операции возвращает сохраненный документ

1
2
3

doc.save().then((savedDoc) => {
    savedDoc === doc; // true
});

При отсутствии документа с указанным _id, выбрасывается исключение DocumentNotFoundError.

Обновление документа с помощью запросов¶

Если нам не хватает save(), то можно создать собственное обновление

1
2

// Обновляем все документы в коллекции `users`
await User.updateMany({}, { $set: { name: 'John' } });

Обратите внимание, что update(), updateMany(), findOneAndUpdate() и др. не запускают посредников save().

Валидация¶

Документы подвергаются кастингу и валидации перед сохранением. Кастинг представляет собой проверку типа, а валидация - проверку дополнительных настроек (например, min для типа Number). Внутренне Mongoose вызывает метод документа validate() перед сохранением

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

const userSchema = new Schema({
    name: String,
    age: { type: Number, min: 18 },
});
const User = model('User', userSchema);

const user = new User({ name: 'John', age: 'many' });
// Кастинг типа `Number` провален для значения `many` поля `age`
await user.validate();

const user2 = new User((name: 'Jane'), (age: 17));
// Значение поля `age` (17) меньше минимально допустимого значения (18)

Перезапись¶

Существует два способа перезаписи документов (замены всех ключей документа). Первый способ - функции Document.overwrite() и save()

1
2
3
4
5

const user = await User.findOne({ _id });

// Устанавливаем `name` и удаляем остальные свойства
user.overwrite({ name: 'John' });
await doc.save();

Второй способ - метод Model.replaceOne()

1

await User.replaceOne({ _id }, { name: 'John' });

Субдокумент (документ в документе)¶

Субдокументы - это документы, встроенные в другие документы. В Mongoose это означает, что одни схемы могут быть вложены в другие.

1
2
3
4
5
6
7
8

const childSchema = new Schema({ name: String });

const parentSchema = new Schema({
    // массив субдокументов
    children: [childSchema],
    // единичный вложенный субдокумент
    child: childSchema,
});

Что такое субдокументы?¶

Субдокументы похожи на обычные документы. Вложенные схемы могут иметь посредников, кастомную логику валидации, виртуальные свойства и т.д. Главное отличие субдокументов состоит в том, что они не сохраняются индивидуально, они сохраняются вместе с родительским документом.

1
2
3
4
5
6
7
8
9

const Parent = model('Parent', parentSchema);
const parent = new Parent({
    children: [{ name: 'John' }, { name: 'Jane' }],
});
parent.children[0].name = 'Bob';

// `parent.children[0].save()` запустит посредников
// но не сохранит документ. Для этого нужно сохранить его предка
parent.save();

Вызов save() предка запускает выполнение save() всех потоков. То же самое справедливо для validate().

Дочерние посредники pre('save') и pre('validate') выполняются до родительского pre('save'), но после родительского pre('validate')

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// числа 1-4 будут выведены по порядку
const childSchema = new Schema({ name: String });

childSchema.pre('validate', (next) => {
    console.log(2);
    next();
});

childSchema.pre('save', (next) => {
    console.log(3);
    next();
});

const parentSchema = new Schema({
    child: childSchema,
});

parentSchema.pre('validate', (next) => {
    console.log(1);
    next();
});

parentSchema.pre('save', (next) => {
    console.log(4);
    next();
});

Субдокументы и вложенные пути¶

Вложенные пути немного отличаются от субдокументов. В приведенном ниже примере у нас имеется две схемы: одна с субдокументом child, другая с вложенным путем child

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

// Субдокумент
const subdocSchema = new Schema({
    child: new Schema({
        name: String,
        age: Number,
    }),
});
const Subdoc = model('Subdoc', subdocSchema);

// Вложенный путь
const nestedSchema = new Schema({
    child: {
        name: String,
        age: Number,
    },
});
const Nested = model('Nested', nestedSchema);

Отличия:

• экземпляры Nested никогда не имеют child === undefined. Мы может определять подсвойства child даже при отсутствии самого child. Но экземпляры Subdoc могут иметь child === undefined

1
2
3
4
5
6
7
8

const doc1 = new Subdoc({});
doc1.child === undefined; // true
doc1.child.name = 'test'; // TypeError: cannot read property...

const doc2 = new Nested({});
doc2.child === undefined; // false
console.log(doc2.child); // MongooseDocument { undefined }
doc2.child.name = 'test'; // работает

• метод Document.set() выполняет объединение для вложенных путей и перезапись для субдокументов

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

const doc1 = new Subdoc({
    child: {
        name: 'John',
        age: 30,
    },
});
doc1.set({
    child: {
        age: 20,
    },
});
doc1.child; // { age: 20 }

const doc2 = new Nested({
    child: {
        name: 'John',
        age: 30,
    },
});
doc2.set({
    child: {
        age: 20,
    },
});
doc2.set({
    child: {
        age: 20,
    },
});
doc2.child; // { name: 'John', age: 20 }

Значения субдокументов по умолчанию¶

Пути субдокументов имеют значение undefined (к ним не применяются настройки default) до тех пор, пока им не будет присвоено ненулевое значение

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

const subdocSchema = new Schema({
    child: new Schema({
        name: String,
        age: {
            type: Number,
            default: 18,
        },
    }),
});
const Subdoc = model('Subdoc', subdocSchema);

// настройка `default` поля `age` не будет иметь эффекта, поскольку значением `child` является `undefined`
const doc = new Subdoc();
doc.child; // undefined

Получение субдокумента¶

Для поиска субдокумента по его _id (устанавливается по умолчанию) используется специальный метод id()

1

const subdoc = parent.children.id(_id);

Добавление субдокументов в массив¶

Такие методы как push(), unshift(), addToSet() и др. осуществляют прозрачный кастинг передаваемых аргументов

1
2
3
4
5
6
7
8
9

const Parent = model('Parent', parentSchema);
const parent = new Parent();

parent.children.push({ name: 'John' });
const subdoc = parent.children[0];
console.log(subdoc); // { _id: '...', name: 'John' }
subdoc.isNew; // true

parent.save();

Для того, чтобы создать документ без его добавления в массив, следует использовать метод create()

1

const subdoc = parent.children.create({ name: 'Jane' });

Удаление субдокументов¶

У каждого субдокумента есть метод remove(). Для массива субдокументов данный метод эквивалентен вызову pull(). Для единичного субдокумента он эквивалентен установке значения субдокумента в null

1
2
3
4
5
6
7

// эквивалент `parent.children.pull(_id)`
parent.children.id(_id).remove();

// эквивалент `parent.child = null`
parent.child.remove();

parent.save();

Получение предка субдокумента¶

Для получения непосредственного предка субдокумента используется функция parent(), а для получения предка верхнего уровня (для глубоко вложенных субдокументов) - функция ownerDocument().

Альтернативный синтаксис¶

При создании схемы с помощью массива объектов, Mongoose автоматически преобразует объекты в схемы

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

const parentSchema = new Schema({
    children: [
        {
            name: String,
        },
    ],
});
// эквивалент
const parentSchema = new Schema({
    children: [
        new Schema({
            name: String,
        }),
    ],
});

Обратите внимание, что в случае единичного объекта, вместо схемы создается вложенных путь. Для того, чтобы сообщить Mongoose о необходимости создания схемы для единичного объекта, следует использовать настройку typePojoToMixed: false

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const schema = new Schema(
    {
        nested: {
            // `new Schema({ prop: String })`
            type: { prop: String },
            required: true,
        },
    },
    { typePojoToMixed: false }
);

Запрос¶

Модель предоставляет несколько статических вспомогательных функций. Каждая функция возвращает объект Query

• Model.deleteMany()
• Model.deleteOne()
• Model.find()
• Model.findById()
• Model.findByIdAndDelete()
• Model.findByIdAndRemove()
• Model.findByIdAndUpdate()
• Model.findOne()
• Model.findOneAndDelete()
• Model.findOneAndRemove()
• Model.findOneAndReplace()
• Model.findOneAndUpdate()
• Model.replaceOne()
• Model.updateMany()
• Model.updateOne()

Запрос может выполняться двумя способами:

• с помощью колбека - запрос выполняется асинхронно и результат передается в колбек
• с помощью метода then() запроса, что позволяет использовать его как промис

Выполнение запроса¶

При выполнении запроса с помощью callback, запрос может быть определен в виде JSON документа

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

const User = model('User', userSchema);

// Ищем пользователей, фамилия которых совпадает с `Smith`, выбираем поля `name` и `occupation`
User.findOne(
    { 'name.last': 'Smith' },
    'name occupation',
    (err, user) => {
        if (err) return handleError(err);
        console.log(user);
    }
);

Запрос выполняется, его результат передается в callback. Сигнатура колбеков всегда такая: callback(error, result). При возникновении ошибки, параметр error содержит объект ошибки, а result является нулевым. При успешном выполнении запроса error является нулевым, а result заполняется (populate) данными из результата запроса.

result зависит от операции: для findOne() - это потенциально ненулевой единичный документ, для find() - список документов, для count() - количество документов, для update() - количество обновленных документов и т.д.

Пример без колбека

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// Ищем пользователей, фамилия которых совпадает с `Smith`
const query = User.findOne({ 'name.last', 'Smith' })

// выбираем поля `name` и `occupation`
query.select('name occupation')

// выполняем запрос
query.exec((err, user) => {
  if (err) return handleError(err)
  console.log(user)
})

В приведенном примере переменная query имеет тип Query. Query позволяет формировать запрос двумя способами

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// Документ JSON
User.find({
    'name.last': 'Smith',
    // gt - greater than, больше чем; lt - less than, меньше чем
    age: { $gt: 17, $lt: 66 },
    // in - один из вариантов
    likes: { $in: ['playing guitar', 'swimming'] },
})
    .limit(10)
    .sort({ occupation: -1 })
    .select({ name: 1, occupation: 1 })
    .exec(callback);

// Строитель (builder) запроса
User.find({ 'name.last': 'Smith' })
    .where('age')
    .gt(17)
    .lt(66)
    .where('likes')
    .in(['playing guitar', 'swimming'])
    .limit(10)
    .sort('-occupation')
    .select('name occupation')
    .exec(callback);

Запросы не являются промисами¶

Несмотря на то, что у запросов есть метод then(), это всего лишь соглашение, они не являются промисами. В отличие от промисов, вызов then() запроса может привести к его многократному выполнению.

В приведенном ниже примере updateMany() вызывается 3 раза

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const q = Model.updateMany({}, { completed: true }, () => {
    console.log('Первое обновление');
});

q.then(() => {
    console.log('Второе обновление');
});
q.then(() => {
    console.log('Третье обновление');
});

Смешивание колбеков и промисов может привести к дублированию операций.

Валидация¶

Для валидации характерно следующее:

• Она определяется в SchemaType (при определении схемы)
• Валидация - это посредник (middleware). Mongoose регистрирует ее как хук pre('save') для каждой схемы
• Автоматическую валидацию, выполняемую перед сохранением документа, можно отключить с помощью настройки validateBeforeSave: false
• Валидаторы можно запускать вручную с помощью doc.validate(callback) или doc.validateSync()
• Помечать поля как невалидные можно с помощью doc.invalidate(...)
• Валидаторы не запускаются для неопределенных значений, кроме валидатора required
• Валидаторы выполняются асинхронно и рекурсивно: при вызове Model.save() также выполняется валидация субдокументов. При возникновении ошибки, ее получает колбек Model.save()
• Можно создавать собственные валидаторы

Встроенные валидаторы¶

Mongoose предоставляет несколько встроенных валидаторов:

• Все SchemaTypes имеют встроенный валидатор required (поле является обязательным для заполнения)
• Числа имеют валидаторы min и max
• Строки имеют валидаторы enum, match, minLength и maxLength

Значением валидатора является либо соответствующий примитив - условие, которому должно удовлетворять значение поля, либо массив, где первым элементом является примитив, а вторым - сообщение об ошибке

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

const breakfastSchema = new Schema({
    eggs: {
        type: Number,
        min: [3, 'Слишком мало яиц'],
        max: 6,
    },
    bacon: {
        type: Number,
        required: [true, 'Без бекона?'],
    },
    drink: {
        type: String,
        enum: ['Кофе', 'Чай'],
        required: function () {
            return this.bacon >= 2;
        },
    },
});
const Breakfast = model('Breakfast', breakfastSchema);

const badBreakfast = new Breakfast({
    eggs: 2,
    bacon: 2,
    drink: 'Молоко',
});
let error = badBreakfast.validateSync();
error.errors['eggs'].message; // Слишком мало яиц
error.errors['drink'].message; // `Молоко` is not a valid enum value for path `drink`

badBreakfast.drink = null;
error = badBreakfast.validateSync();
error.errors['drink'].message; // Path `drink` is required

badBreakfast.bacon = null;
error = badBreakfast.validateSync();
error.errors['bacon'].message; // Без бекона?

Обратите внимание, что настройка unique не является валидатором. Это утилита для генерации уникальных индексов

1
2
3
4
5
6

const uniqueUsernameSchema = new Schema({
    username: {
        type: String,
        unique: true,
    },
});

Кастомные валидаторы¶

Кастомные валидаторы определяются следующим образом:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

const userSchema = new Schema({
    phone: {
        type: String,
        validate: {
            validator: (v) => /+7\d{10}/.test(v),
            message: (props) =>
                `${props.value} не является валидным номером сотового телефона!`,
        },
        required: [
            true,
            'Номер телефона является обязательным',
        ],
    },
});

const User = model('User', userSchema);
const user = new User();

user.phone = '3214256';
let error = user.validateSync();
error.errors['phone'].message; // `3214256` не является валидным номером сотового телефона!

user.phone = '';
error = user.validateSync();
error.errors['phone'].message; // Номер телефона является обязательным

Асинхронные кастомные валидаторы¶

Также существует два способа определения асинхронных кастомных валидаторов:

• с помощью Promise.reject()
• с помощью Promise.resolve(false)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

const userSchema = new Schema({
    name: {
        type: String,
        validate: () => Promise.reject(new Error('Упс!')),
    },
    email: {
        type: String,
        validate: {
            validator: () => Promise.resolve(false),
            message: 'Валидация email провалилась',
        },
    },
});

Ошибки валидации¶

Если при выполнении валидации возникли ошибки, возвращается объект errors, каждое значение которого представляет собой объект ValidatorError (unique возвращает DuplicateKeyError). Объект ValidatorError содержит свойства kind, path, value и message. Он также может содержать свойство reason. Если в валидаторе было выброшено исключение, данное свойство будет содержать это исключение.

Ошибки кастинга¶

Перед запуском валидаторов Mongoose выполняет проверку значений на соответствие типам. Данный процесс называется кастингом (casting). При провале кастинга, объект error.errors будет содержать объект CastError. Кастинг выполняется перед валидацией, при провале кастинга валидация не выполняется.

Валидатор required для вложенных объектов¶

Для того, чтобы сделать вложенный объект обязательным, следует определить его в виде схемы

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

// Будет выброшено исключение, поскольку `name` не является самостоятельным путем
let userSchema = new Schema({
    name: {
        first: String,
        last: String,
    },
    required: true,
});

const nameSchema = new Schema({
    first: String,
    last: String,
});

// так будет работать
userSchema = new Schema({
    name: {
        type: nameSchema,
        required: true,
    },
});

Валидаторы обновления¶

Mongoose также поддерживает валидацию для операций update(), updateOne(), updateMany() и findOneAndUpdate(). По умолчанию такая валидацию отключена. Для того, чтобы ее включить, следует установить настройку runValidators в значение true

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

const toySchema = new Schema({
  color: {
    type: String,
    validate: (v) => /red|green|blue/i.test(v), 'Недопустимый цвет'
  },
  name: String
})

const Toy = model('Toy', toySchema)

const opts = { runValidators: true }
Toy.updateOne({}, { color: 'не цвет' }, opts, (err) => {
  console.error(err) // Недопустимый цвет
})

Обратите внимание: валидаторы обновления имеют некоторые особенности, связанные с потерей контекста (this), успешной валидацией несуществующих путей и возможностью их использования только в некоторых операциях.

Посредники¶

Посредники (промежуточное программное обеспечение, промежуточный слой, middlewares), которые тажке называются пре и пост хуками, являются функциями, перехватывающими выполнение асинхронных функций. Посредники определяются на уровне схемы и часто используются для создания плагинов.

Типы посредников¶

Mongoose предоставляет 4 типа посредников: посредники документа, посредники модели, посредники агрегации и посредники запроса. В посредниках документов this указывает на документ. Такие посредники поддерживаются для следующих функций документа:

• validate
• save
• remove
• updateOne
• deleteOne
• init (хуки init являются синхронными)

В посредниках запросов this указывает на запрос. Такие посредники поддерживаются для следующих функций моделей и запросов:

• count
• deleteMany
• deleteOne
• find
• findOne
• findOneAndDelete
• findOneAndRemove
• findOneAndUpdate
• remove
• update
• updateOne
• updateMany

Посредники агрегации выполняются при вызове call() на агрегируемом объекте. В таких посредниках this указывает на объект агрегации

• aggregate

В посредниках модели this указывает на модель. Поддерживаются следующие посредники модели:

• insertMany

Обратите внимание: при определении schema.pre('remove') автоматически регистрируется посредник для doc.remove(). Для того, чтобы посредник выполнялся при вызове Query.remove(), следует указать schema.pre('remove', { query: true, document: false }, fn).

Обратите внимание: в отличие от schema.pre('remove'), Mongoose по умолчанию автоматически регистрирует посредников для Query.updateOne() и Query.deleteOne(). Это означает, что doc.updateOne() и Model.updateOne() запускают хуки updateOne, но this указывает на запрос, а не на документ. Для регистрации updateOne или deleteOne в качестве посредников документа следует указать schema.pre('updateOne', { document: true, query: false }).

Обратите внимание: функция create() запускает хуки save().

Pre¶

Предварительные посредники выполняются один за другим, когда каждый посредник вызывает next()

1
2
3
4
5

const schema = new Schema(...)
schema.pre('save', (next) => {
  // ...
  next()
})

Вместо next() можно использовать функцию, возвращающую промис, или async/await

1
2
3
4
5
6
7
8
9

schema.pre('save', () =>
    doStuff().then(() => doMoreStuff())
);

// или
schema.pre('save', async () => {
    await doStuff();
    await doMoreStuff();
});

Обратите внимание: вызов next() не останавливает выполнение функции.

Случаи использования¶

Посредники могут использоваться для атомизации логики модели. Другие варианты:

• сложная валидация
• удаление зависимых документов (удаление постов пользователя при удалении самого пользователя)
• асинхронные настройки по умолчанию
• выполнение асинхронных задач

Ошибки в предварительных хуках¶

При возникновении ошибки в хуке, другие хуки или соответствующая функция не выполняются. Вместо этого, ошибка передается в колбек, а возвращенный промис отклоняется. Существует несколько способов обработки таких ошибок:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

schema.pre('save', (next) => {
    const err = new Error('Что-то пошло не так');
    // При вызове `next()` с аргументом, предполагается, что данный аргумент
    // является ошибкой
    next(err);
});

schema.pre(
    'save',
    () =>
        // Также можно вернуть отклоненный промис
        new Promise((res, rej) => {
            reject(new Error('Что-то пошло не так'));
        })
);

schema.pre('save', () => {
    // или выбросить синхронное исключение,
    throw new Error('Что-то пошло не так');
});

schema.pre('save', async () => {
    await Promise.resolve();
    // или выбросить исключение в асинхронной функции
    throw new Error('Что-то пошло не так');
});

// Позже

// Изменения не будут сохранены в БД, поскольку в предварительном хуке возникает ошибка
doc.save((err) => {
    console.error(err); // Что-то пошло не так
});