Schematype

Конструктор SchemaType. Не следует создавать экземпляры SchemaType напрямую. Mongoose автоматически преобразует ваши пути схемы в SchemaTypes.

Пример:

const schema = new Schema({ name: String });
schema.path('name') instanceof SchemaType; // true

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

Пример:

// Disallow `null` for numbers, and don't try to cast any values to
// numbers, so even strings like '123' will cause a CastError.
mongoose.Number.cast(function(v) {
  assert.ok(v === undefined || typeof v === 'number');
  return v;
});

Установить и получить функцию checkRequired Переопределить функцию, используемую валидатором required для проверки, проходит ли значение проверку required. Переопределите её в отдельном SchemaType.

Пример:

// Use this to allow empty strings to pass the `required` validator
mongoose.Schema.Types.String.checkRequired(v => typeof v === 'string');

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

Пример:

// Make all numbers round down
mongoose.Number.get(function(v) { return Math.floor(v); });

Функция, которую Mongoose вызывает для преобразования произвольных значений в данный SchemaType.

Получить/установить функцию, используемую для преобразования произвольных значений в данный экземпляр schematype. Переопределяет SchemaType.cast().

Пример:

// Disallow `null` for numbers, and don't try to cast any values to
// numbers, so even strings like '123' will cause a CastError.
const number = new mongoose.Number('mypath', {});
number.cast(function(v) {
  assert.ok(v === undefined || typeof v === 'number');
  return v;
});

Устанавливает значение по умолчанию для данного SchemaType.

Пример:

const schema = new Schema({ n: { type: Number, default: 10 })
const M = db.model('M', schema)
const m = new M;
console.log(m.n) // 10

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

Пример:

// values are cast:
const schema = new Schema({ aNumber: { type: Number, default: 4.815162342 }})
const M = db.model('M', schema)
const m = new M;
console.log(m.aNumber) // 4.815162342

// default unique objects for Mixed types:
const schema = new Schema({ mixed: Schema.Types.Mixed });
schema.path('mixed').default(function () {
  return {};
});

// if we don't use a function to return object literals for Mixed defaults,
// each document will receive a reference to the same object literal creating
// a "shared" object instance:
const schema = new Schema({ mixed: Schema.Types.Mixed });
schema.path('mixed').default({});
const M = db.model('M', schema);
const m1 = new M;
m1.mixed.added = 1;
console.log(m1.mixed); // { added: 1 }
const m2 = new M;
console.log(m2.mixed); // { added: 1 }

Выполняет валидацию value с использованием валидаторов, объявленных для данного SchemaType.

Добавляет геттер к этому типу schematype.

Пример:

function dob (val) {
  if (!val) return val;
  return (val.getMonth() + 1) + "/" + val.getDate() + "/" + val.getFullYear();
}

// defining within the schema
const s = new Schema({ born: { type: Date, get: dob })

// or by retreiving its SchemaType
const s = new Schema({ born: Date })
s.path('born').get(dob)

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

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

function obfuscate (cc) {
  return '****-****-****-' + cc.slice(cc.length-4, cc.length);
}

const AccountSchema = new Schema({
  creditCardNumber: { type: String, get: obfuscate }
});

const Account = db.model('Account', AccountSchema);

Account.findById(id, function (err, found) {
  console.log(found.creditCardNumber); // '****-****-****-1234'
});

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

function inspector (val, priorValue, schematype) {
  if (schematype.options.required) {
    return schematype.path + ' is required';
  } else {
    return schematype.path + ' is not';
  }
}

const VirusSchema = new Schema({
  name: { type: String, required: true, get: inspector },
  taxonomy: { type: String, get: inspector }
})

const Virus = db.model('Virus', VirusSchema);

Virus.findById(id, function (err, virus) {
  console.log(virus.name);     // name is required
  console.log(virus.taxonomy); // taxonomy is not
})

Определяет этот путь как неизменяемый. Mongoose запрещает изменение неизменяемых путей, если у родительского документа нет isNew: true.

Пример:

const schema = new Schema({
  name: { type: String, immutable: true },
  age: Number
});
const Model = mongoose.model('Test', schema);

await Model.create({ name: 'test' });
const doc = await Model.findOne();

doc.isNew; // false
doc.name = 'new name';
doc.name; // 'test', because `name` is immutable

Mongoose также предотвращает изменение неизменяемых свойств с помощью updateOne() и updateMany() в зависимости от режима strict.

Пример:

// Mongoose will strip out the `name` update, because `name` is immutable
Model.updateOne({}, { $set: { name: 'test2' }, $inc: { age: 1 } });

// If `strict` is set to 'throw', Mongoose will throw an error if you
// update `name`
const err = await Model.updateOne({}, { name: 'test2' }, { strict: 'throw' }).
  then(() => null, err => err);
err.name; // StrictModeError

// If `strict` is `false`, Mongoose allows updating `name` even though
// the property is immutable.
Model.updateOne({}, { name: 'test2' }, { strict: false });

Объявляет параметры индекса для данного schematype.

Пример:

const s = new Schema({ name: { type: String, index: true })
const s = new Schema({ name: { type: String, index: -1 })
const s = new Schema({ loc: { type: [Number], index: 'hashed' })
const s = new Schema({ loc: { type: [Number], index: '2d', sparse: true })
const s = new Schema({ loc: { type: [Number], index: { type: '2dsphere', sparse: true }})
const s = new Schema({ date: { type: Date, index: { unique: true, expires: '1d' }})
s.path('my.path').index(true);
s.path('my.date').index({ expires: 60 });
s.path('my.path').index({ unique: true, sparse: true });

Примечание:

Индексы создаются в фоновом режиме по умолчанию. Если background установлено в false, MongoDB не будет выполнять никакие операции чтения/записи, которые вы отправляете, до завершения построения индекса. Укажите background: false для переопределения значения по умолчанию Mongoose.

Истина, если у данного SchemaType есть валидатор required. Ложь в противном случае.

Пример:

const schema = new Schema({ name: { type: String, required: true } });
schema.path('name').isRequired; // true

schema.path('name').required(false);
schema.path('name').isRequired; // false

Путь к этому SchemaType в схеме.

Пример:

const schema = new Schema({ name: String });
schema.path('name').path; // 'name'

Устанавливает модель, к которой относится этот путь. Это опция, на которую populate смотрит, чтобы определить внешнюю коллекцию, которую она должна запросить.

Пример:

const userSchema = new Schema({ name: String });
const User = mongoose.model('User', userSchema);

const postSchema = new Schema({ user: mongoose.ObjectId });
postSchema.path('user').ref('User'); // Can set ref to a model name
postSchema.path('user').ref(User); // Or a model class
postSchema.path('user').ref(() => 'User'); // Or a function that returns the model name
postSchema.path('user').ref(() => User); // Or a function that returns the model class

// Or you can just declare the `ref` inline in your schema
const postSchema2 = new Schema({
  user: { type: mongoose.ObjectId, ref: User }
});

Добавляет обязательный валидатор в этот SchemaType. Валидатор добавляется в начало массива validators этого SchemaType с помощью unshift().

Пример:

const s = new Schema({ born: { type: Date, required: true })

// or with custom error message

const s = new Schema({ born: { type: Date, required: '{PATH} is required!' })

// or with a function

const s = new Schema({
  userId: ObjectId,
  username: {
    type: String,
    required: function() { return this.userId != null; }
  }
})

// or with a function and a custom message
const s = new Schema({
  userId: ObjectId,
  username: {
    type: String,
    required: [
      function() { return this.userId != null; },
      'username is required if id is specified'
    ]
  }
})

// or through the path API

s.path('name').required(true);

// with custom error messaging

s.path('name').required(true, 'grrr :( ');

// or make a path conditionally required based on a function
const isOver18 = function() { return this.age >= 18; };
s.path('voterRegistrationId').required(isOver18);

Обязательный валидатор использует функцию checkRequired SchemaType, чтобы определить, удовлетворяет ли данное значение обязательный валидатор. По умолчанию значение удовлетворяет обязательный валидатор, если val != null (то есть, если значение не null и не undefined). Однако большинство встроенных типов схем Mongoose переопределяют функцию checkRequired по умолчанию:

Устанавливает поведение по умолчанию для этого пути.

Устанавливается в select() , если этот путь всегда должен включаться в результаты, и в false , если он по умолчанию должен быть исключён. Это значение может быть переопределено на уровне запроса.

Пример:

T = db.model('T', new Schema({ x: { type: String, select: true }}));
T.find(..); // field x will always be selected ..
// .. unless overridden;
T.find().select('-x').exec(callback);

Добавляет установщик для этого типа схемы.

Пример:

function capitalize (val) {
  if (typeof val !== 'string') val = '';
  return val.charAt(0).toUpperCase() + val.substring(1);
}

// defining within the schema
const s = new Schema({ name: { type: String, set: capitalize }});

// or with the SchemaType
const s = new Schema({ name: String })
s.path('name').set(capitalize);

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

Предположим, вы реализуете регистрацию пользователей для веб-сайта. Пользователи предоставляют адрес электронной почты и пароль, которые сохраняются в MongoDB. Адрес электронной почты — это строка, которую вы захотите привести к нижнему регистру, чтобы избежать наличия более одной учетной записи по одному адресу электронной почты — например, в противном случае, avenue@q.com может быть зарегистрирован для 2 учетных записей через avenue@q.com и AvEnUe@Q.CoM.

Вы можете легко установить нормализацию адресов электронной почты к нижнему регистру с помощью установщика Mongoose.

function toLower(v) {
  return v.toLowerCase();
}

const UserSchema = new Schema({
  email: { type: String, set: toLower }
});

const User = db.model('User', UserSchema);

const user = new User({email: 'AVENUE@Q.COM'});
console.log(user.email); // 'avenue@q.com'

// or
const user = new User();
user.email = 'Avenue@Q.com';
console.log(user.email); // 'avenue@q.com'
User.updateOne({ _id: _id }, { $set: { email: 'AVENUE@Q.COM' } }); // update to 'avenue@q.com'

Как видно выше, установщики позволяют преобразовывать данные перед их сохранением в MongoDB или перед выполнением запроса.

ПРИМЕЧАНИЕ: мы также могли бы просто использовать встроенный параметр SchemaType lowercase: true вместо определения собственной функции.

new Schema({ email: { type: String, lowercase: true }})

Установщики также получают второй аргумент — тип схемы, для которого был определен установщик. Это позволяет настроить поведение в зависимости от параметров, передаваемых в схему.

function inspector (val, priorValue, schematype) {
  if (schematype.options.required) {
    return schematype.path + ' is required';
  } else {
    return val;
  }
}

const VirusSchema = new Schema({
  name: { type: String, required: true, set: inspector },
  taxonomy: { type: String, set: inspector }
})

const Virus = db.model('Virus', VirusSchema);
const v = new Virus({ name: 'Parvoviridae', taxonomy: 'Parvovirinae' });

console.log(v.name);     // name is required
console.log(v.taxonomy); // Parvovirinae

Вы также можете использовать установщики для изменения других свойств документа. Если вы устанавливаете свойство name в документе, установщик будет выполняться со значением this в качестве документа. Будьте осторожны, в Mongoose 5 установщики также будут выполняться при запросе по name со значением this в качестве запроса.

const nameSchema = new Schema({ name: String, keywords: [String] });
nameSchema.path('name').set(function(v) {
  // Need to check if `this` is a document, because in mongoose 5
  // setters will also run on queries, in which case `this` will be a
  // mongoose query object.
  if (this instanceof Document && v != null) {
    this.keywords = v.split(' ');
  }
  return v;
});

Объявляет разреженный индекс.

Пример:

const s = new Schema({ name: { type: String, sparse: true } });
s.path('name').index({ sparse: true });

Объявляет индекс полнотекстового поиска.

Пример:

 const s = new Schema({ name : { type: String, text : true } })
 s.path('name').index({ text : true });

Определяет пользовательскую функцию преобразования этого пути при преобразовании документа в JSON.

Mongoose вызывает эту функцию с одним параметром: текущим value пути. Затем Mongoose использует возвращаемое значение в выходных данных JSON.

Пример:

const schema = new Schema({
  date: { type: Date, transform: v => v.getFullYear() }
});
const Model = mongoose.model('Test', schema);

await Model.create({ date: new Date('2016-06-01') });
const doc = await Model.findOne();

doc.date instanceof Date; // true

doc.toJSON().date; // 2016 as a number
JSON.stringify(doc); // '{"_id":...,"date":2016}'

Объявляет уникальный индекс.

Пример:

const s = new Schema({ name: { type: String, unique: true } });
s.path('name').index({ unique: true });

ПРИМЕЧАНИЕ: нарушение ограничения возвращает ошибку E11000 от MongoDB при сохранении, а не ошибку валидации Mongoose.

Добавляет валидатор(ы) для этого пути документа.

Валидаторы всегда получают значение для валидации в качестве первого аргумента и должны возвращать Boolean. Возвращение false или вызов ошибки означает неудачную валидацию.

Аргумент сообщения об ошибке необязателен. Если он не передан, будет использоваться шаблон сообщения об ошибке по умолчанию .

Пример:

// make sure every value is equal to "something"
function validator (val) {
  return val === 'something';
}
new Schema({ name: { type: String, validate: validator }});

// with a custom error message

const custom = [validator, 'Uh oh, {PATH} does not equal "something".']
new Schema({ name: { type: String, validate: custom }});

// adding many validators at a time

const many = [
    { validator: validator, message: 'uh oh' }
  , { validator: anotherValidator, message: 'failed' }
]
new Schema({ name: { type: String, validate: many }});

// or utilizing SchemaType methods directly:

const schema = new Schema({ name: 'string' });
schema.path('name').validate(validator, 'validation of `{PATH}` failed with value `{VALUE}`');

Шаблоны сообщений об ошибках:

Ниже приведен список поддерживаемых ключевых слов шаблона:

• PATH: путь схемы, где возникает ошибка.
• VALUE: значение, назначенное PATH, вызывающее ошибку.
• KIND: свойство валидации, вызвавшее ошибку, например, required.
• REASON: объект ошибки, вызвавший эту ошибку, если таковой был.

Если встроенная система шаблонов сообщений об ошибках Mongoose недостаточна, Mongoose поддерживает установку свойства message в функцию.

schema.path('name').validate({
  validator: function(v) { return v.length > 5; },
  // `errors['name']` will be "name must have length 5, got 'foo'"
  message: function(props) {
    return `${props.path} must have length 5, got '${props.value}'`;
  }
});

Чтобы обойти сообщения об ошибках Mongoose и просто скопировать сообщение об ошибке, которое сгенерировал валидатор, сделайте следующее:

schema.path('name').validate({
  validator: function() { throw new Error('Oops!'); },
  // `errors['name']` will be "Oops!"
  message: function(props) { return props.reason.message; }
});

Асинхронная валидация:

Mongoose поддерживает валидаторы, которые возвращают промис. Валидатор, возвращающий промис, называется асинхронным валидатором. Асинхронные валидаторы выполняются параллельно, и validate() будет ждать, пока все асинхронные валидаторы завершат работу.

schema.path('name').validate({
  validator: function (value) {
    return new Promise(function (resolve, reject) {
      resolve(false); // validation failed
    });
  }
});

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

Валидация происходит pre('save') или всякий раз, когда вы вручную выполняете document#validate.

Если валидация завершается неудачно во время pre('save') и не был передан обратный вызов для получения ошибки, событие error будет излучаться в ассоциированной базе данных ваших моделей connection, передавая вместе с ним объект ошибки валидации.

const conn = mongoose.createConnection(..);
conn.on('error', handleError);

const Product = conn.model('Product', yourSchema);
const dvd = new Product(..);
dvd.save(); // emits error on the `conn` above

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

// registering an error listener on the Model lets us handle errors more locally
Product.on('error', handleError);

Валидаторы, которые Mongoose должен выполнить для валидации свойств в пути этого SchemaType.

Пример:

const schema = new Schema({ name: { type: String, required: true } });
schema.path('name').validators.length; // 1, the `required` validator

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

Пример:

// Make all strings be trimmed by default
mongoose.SchemaTypes.String.set('trim', true);