Обработка отсутствующих полей

Когда поле отсутствует в запросе (его значение undefined или null), Express-Cargo должен знать, что делать. Это поведение управляется двумя декораторами:

• @Default(value) — подставляет запасное значение.
• @Optional() — позволяет полю оставаться пустым без ошибки «required».

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

Если у поля нет ни одного из этих декораторов и значение отсутствует, привязка завершается ошибкой валидации <field> is required.

@Default(value: T)

Декоратор @Default присваивает значение по умолчанию свойству класса, когда запрос не предоставляет его.

• value: Значение по умолчанию для присвоения, если поле отсутствует в запросе.

class Request {
    @Body()
    @Default(1)
    price!: number;
}

Когда применяется значение по умолчанию

Значение по умолчанию применяется только когда входящее значение равно undefined или null (то есть поле отсутствует в запросе). Любое другое значение из запроса сохраняется как есть.

Это означает, что falsy-значения, такие как 0, '' и false, рассматриваются как реальный ввод и не вызывают значение по умолчанию:

class Request {
    @Body()
    @Default(10)
    quantity!: number
}

Входящее quantity	Привязанное значение
отсутствует / undefined	10 (применено по умолчанию)
null	10 (применено по умолчанию)
0	0 (сохранено)
5	5 (сохранено)

@Optional()

Декоратор @Optional помечает поле как необязательное, позволяя опустить его или установить в undefined/null без вызова ошибки «required». Когда поле отсутствует, оно остаётся null, а правила валидации для него пропускаются.

class Request {
    @Body()
    @Min(0)
    @Optional()
    discount?: number
}

Здесь отсутствующее discount привязывается к null, а правило @Min(0) пропускается. Если discount предоставлено, оно валидируется обычным образом.

Выбор между @Default и @Optional

	Поле отсутствует	Поле предоставлено
@Default(value)	привязано к value	значение сохранено и валидировано
@Optional()	привязано к null	значение сохранено и валидировано
ни одного	ошибка <field> is required	значение сохранено и валидировано

Выбирайте одну стратегию на поле:

class Request {
    // ❌ Недопустимо: поле может использовать только одну стратегию отсутствующего значения
    @Body()
    @Default(1)
    @Optional()
    price!: number
}