Validator Decorations
Validator Decorations são anotações nativas de validação do tyrus. Elas podem ser anexadas a campos de interface, campos de tipos de objeto e parâmetros de função. O compilador verifica se cada validator existe, mira um tipo compatível e recebe argumentos literais do tipo esperado.
Exemplo
interface UserInput {
@minLength(3)
@maxLength(32)
name: string;
@email()
primaryEmail: string;
@min(18, "The minimum age requirement is 18")
age: u8;
}
const divide = (a: f64, @notEqual(0) b: f64): f64 => a / b;Validators nativos verificam valores literais em tempo de compilação e executam em runtime para valores dinâmicos em parâmetros decorados, literais de objeto e updates de objeto.
Validator Decorations em arquivos .env
O Tyrus aceita Validator Decorations em arquivos .env com ou sem # no início. Use a forma comentada quando outro loader de .env, como o Docker, também ler o arquivo; o Tyrus ainda interpreta a decoração, enquanto os outros loaders veem um comentário.
# @type(u16)
# @port()
PORT=8080Mensagens de erro
Validators nativos permitem sobrescrever a mensagem padrão com uma string literal no último argumento aceito.
interface SignupInput {
@minLength(3)
username: string;
@minLength(8, "password must have at least 8 characters")
password: string;
@email("use a valid company e-mail")
email: string;
}A mesma regra funciona em parâmetros de função decorados.
const divide = (value: f64, @notEqual(0, "division by zero is not allowed") divisor: f64): f64 => {
return value / divisor;
};Prefira mensagens customizadas em fronteiras com usuário
Mensagens padrão são úteis durante o desenvolvimento. Mensagens customizadas são melhores para fronteiras de API, prompts de CLI e falhas de validação que podem aparecer para usuários.
Famílias de Validators
| Família | Exemplos |
|---|---|
| Numéricos | @min, @max, @range, @positive, @negative, @nonNegative, @nonPositive, @multipleOf, @powerOfTwo, @integer, @safeInteger, @port, @statusCode |
| String | @minLength, @maxLength, @length, @notEmpty, @notBlank, @isTrimmed, @isLowercase, @isUppercase, @startsWith, @endsWith, @includes, @regex |
| Formato | @email, @url, @uuid, @ip, @ipv4, @ipv6, @e164, @cep, @cpf, @cnpj |
| Arrays e valores | @minItems, @maxItems, @lengthItems, @notEmptyItems, @unique, @in, @notIn, @equal, @notEqual, @notNull, @optional, @required |
Alvos dos Validators
Um validator numérico é checado na aritmética do tipo que ele decora: um campo i64 é comparado como inteiro e um campo f64 como float. Um número inteiro acima de 2^53 mantém, portanto, seu valor exato, e o veredito de tempo de compilação sempre concorda com o check emitido para o mesmo valor.
@port, @powerOfTwo e @statusCode miram apenas tipos inteiros, porque suas regras não têm leitura sobre um valor fracionário. Uma porta não é 8080.5.
@unique compara elementos por valor, então aceita arrays de números, strings, booleanos, enums, tuplas, tipos de objeto e interfaces nomeadas cujos campos também sejam comparados por valor. Um array de arrays é rejeitado em tempo de compilação: arrays são comparados por endereço, então [[1, 2], [1, 2]] seria reportado como único.
Operação do Validator
Cada família de validators impõe restrições específicas nos valores que ela decora. O compilador verifica valores literais em tempo de compilação e emite checks de runtime para valores dinâmicos. Abaixo estão exemplos para cada família de validators com suas mensagens de erro padrão.
Numéricos
@min
Garante que o valor seja no mínimo o especificado.
@min(value: i8 | i16 | i32 | i64 | u8 | u16 | u32 | u64 | f32 | f64 | f128, message?: string)interface Example {
@min(1)
pageSize: u32;
}
const valid: Example = { pageSize: 5 };error
const invalid: Example = { pageSize: 0 }; error[validator-decorations-failed]: `@min(1)` failed for `pageSize`: value must be greater than or equal to 1
at /src/main.tyr:6:38
const invalid: Example = { pageSize: 0 };
^@max
Garante que o valor seja no máximo o especificado.
@max(value: i8 | i16 | i32 | i64 | u8 | u16 | u32 | u64 | f32 | f64 | f128, message?: string)interface Example {
@max(100)
limit: i32;
}
const valid: Example = { limit: 50 };error
const invalid: Example = { limit: 200 }; error[validator-decorations-failed]: `@max(100)` failed for `limit`: value must be less than or equal to 100
at /src/main.tyr:6:35
const invalid: Example = { limit: 200 };
^^^@range
Garante que o valor esteja dentro do intervalo inclusivo especificado.
@range(min: i8 | i16 | i32 | i64 | u8 | u16 | u32 | u64 | f32 | f64 | f128, max: i8 | i16 | i32 | i64 | u8 | u16 | u32 | u64 | f32 | f64 | f128, message?: string)interface Example {
@range(1, 50)
offset: i32;
}
const valid: Example = { offset: 25 };error
const invalid: Example = { offset: 60 }; error[validator-decorations-failed]: `@range(1, 50)` failed for `offset`: value must be between 1 and 50
at /src/main.tyr:6:36
const invalid: Example = { offset: 60 };
^^@positive
Garante que o valor seja maior que zero.
@positive(message?: string)interface Example {
@positive()
amount: f64;
}
const valid: Example = { amount: 5.0 };error
const invalid: Example = { amount: -5.0 }; error[validator-decorations-failed]: `@positive()` failed for `amount`: value must be positive
at /src/main.tyr:6:36
const invalid: Example = { amount: -5.0 };
^^^^@negative
Garante que o valor seja menor que zero.
@negative(message?: string)interface Example {
@negative()
debt: f64;
}
const valid: Example = { debt: -10.0 };error
const invalid: Example = { debt: 10.0 }; error[validator-decorations-failed]: `@negative()` failed for `debt`: value must be negative
at /src/main.tyr:6:34
const invalid: Example = { debt: 10.0 };
^^^^@nonNegative
Garante que o valor seja zero ou maior.
@nonNegative(message?: string)interface Example {
@nonNegative()
balance: f64;
}
const valid: Example = { balance: 0.0 };error
const invalid: Example = { balance: -1.0 }; error[validator-decorations-failed]: `@nonNegative()` failed for `balance`: value must be non-negative
at /src/main.tyr:6:37
const invalid: Example = { balance: -1.0 };
^^^^@nonPositive
Garante que o valor seja zero ou menor.
@nonPositive(message?: string)interface Example {
@nonPositive()
withdrawal: f64;
}
const valid: Example = { withdrawal: 0.0 };error
const invalid: Example = { withdrawal: 5.0 }; error[validator-decorations-failed]: `@nonPositive()` failed for `withdrawal`: value must be non-positive
at /src/main.tyr:6:40
const invalid: Example = { withdrawal: 5.0 };
^^^@multipleOf
Garante que o valor seja múltiplo do divisor informado.
@multipleOf(value: i8 | i16 | i32 | i64 | u8 | u16 | u32 | u64 | f32 | f64 | f128, message?: string)interface Example {
@multipleOf(5)
quantity: i32;
}
const valid: Example = { quantity: 10 };error
const invalid: Example = { quantity: 7 }; error[validator-decorations-failed]: `@multipleOf(5)` failed for `quantity`: value must be a multiple of 5
at /src/main.tyr:6:38
const invalid: Example = { quantity: 7 };
^@powerOfTwo
Garante que o valor seja uma potência de dois.
@powerOfTwo(message?: string)interface Example {
@powerOfTwo()
bufferSize: u32;
}
const valid: Example = { bufferSize: 8 };error
const invalid: Example = { bufferSize: 3 }; error[validator-decorations-failed]: `@powerOfTwo()` failed for `bufferSize`: value must be a power of two
at /src/main.tyr:6:40
const invalid: Example = { bufferSize: 3 };
^@integer
Garante que um valor de ponto flutuante não tenha parte fracionária.
@integer(message?: string)interface Example {
@integer()
count: f64;
}
const valid: Example = { count: 42.0 };error
const invalid: Example = { count: 3.14 }; error[validator-decorations-failed]: `@integer()` failed for `count`: value must be an integer
at /src/main.tyr:6:35
const invalid: Example = { count: 3.14 };
^^^^@safeInteger
Garante que o valor inteiro esteja dentro do intervalo seguro de ±2⁵³.
@safeInteger(message?: string)interface Example {
@safeInteger()
largeId: f64;
}
const valid: Example = { largeId: 9007199254740992 };error
const invalid: Example = { largeId: 9007199254740993 }; error[E0308]: type mismatch for `largeId`: expected `f64`, found `9007199254740993`
at /src/main.tyr:6:28
const invalid: Example = { largeId: 9007199254740993 };
^^^^^^^
help: change the value or the annotation so their types match; convert numbers explicitly with `value as <type>`@port
Garante que o valor seja uma porta registrada entre 1024 e 49151.
@port(message?: string)interface Example {
@port()
serverPort: u16;
}
const valid: Example = { serverPort: 8080 };error
const invalid: Example = { serverPort: 80 }; error[validator-decorations-failed]: `@port()` failed for `serverPort`: value must be a registered port between 1024 and 49151
at /src/main.tyr:6:40
const invalid: Example = { serverPort: 80 };
^^@statusCode
Garante que o valor seja um código HTTP válido entre 100 e 599.
@statusCode(message?: string)interface Example {
@statusCode()
responseCode: u16;
}
const valid: Example = { responseCode: 200 };error
const invalid: Example = { responseCode: 99 }; error[validator-decorations-failed]: `@statusCode()` failed for `responseCode`: value must be a valid HTTP status code between 100 and 599
at /src/main.tyr:6:42
const invalid: Example = { responseCode: 99 };
^^String
@minLength
Garante que a string contenha ao menos o número especificado de caracteres.
@minLength(value: i64, message?: string)interface Example {
@minLength(3)
username: string;
}
const valid: Example = { username: "abc" };error
const invalid: Example = { username: "ab" }; error[validator-decorations-failed]: `@minLength(3)` failed for `username`: value must contain at least 3 characters
at /src/main.tyr:6:38
const invalid: Example = { username: "ab" };
^^^^@maxLength
Garante que a string contenha no máximo o número especificado de caracteres.
@maxLength(value: i64, message?: string)interface Example {
@maxLength(50)
displayName: string;
}
const valid: Example = { displayName: "A".repeat(10) };error
const invalid: Example = { displayName: "A".repeat(51) }; error[unhandled-throw]: validation of field `displayName` may throw `ValidationError`; catch it or add `throws ValidationError` to the enclosing function
at /src/main.tyr:6:41
const invalid: Example = { displayName: "A".repeat(51) };
^^^^^^^^^^^^^^@length
Garante que a string tenha exatamente o comprimento especificado.
@length(value: i64, message?: string)interface Example {
@length(8)
code: string;
}
const valid: Example = { code: "12345678" };error
const invalid: Example = { code: "1234567" }; error[validator-decorations-failed]: `@length(8)` failed for `code`: value must have exactly 8 characters
at /src/main.tyr:6:34
const invalid: Example = { code: "1234567" };
^^^^^^^^^@notEmpty
Garante que a string não esteja vazia.
@notEmpty(message?: string)interface Example {
@notEmpty()
firstName: string;
}
const valid: Example = { firstName: "John" };error
const invalid: Example = { firstName: "" }; error[validator-decorations-failed]: `@notEmpty()` failed for `firstName`: value must not be empty
at /src/main.tyr:6:39
const invalid: Example = { firstName: "" };
^^@notBlank
Garante que a string contenha ao menos um caractere não-branco.
@notBlank(message?: string)interface Example {
@notBlank()
bio: string;
}
const valid: Example = { bio: "Hello" };error
const invalid: Example = { bio: " " }; error[validator-decorations-failed]: `@notBlank()` failed for `bio`: value must not be blank
at /src/main.tyr:6:33
const invalid: Example = { bio: " " };
^^^^^@isTrimmed
Garante que a string não tenha espaços no início ou no fim.
@isTrimmed(message?: string)interface Example {
@isTrimmed()
title: string;
}
const valid: Example = { title: "no spaces" };error
const invalid: Example = { title: " spaces " }; error[validator-decorations-failed]: `@isTrimmed()` failed for `title`: value must already be trimmed
at /src/main.tyr:6:35
const invalid: Example = { title: " spaces " };
^^^^^^^^^^@isLowercase
Garante que a string contenha apenas caracteres minúsculos.
@isLowercase(message?: string)interface Example {
@isLowercase()
slug: string;
}
const valid: Example = { slug: "valid-slug" };error
const invalid: Example = { slug: "Invalid-Slug" }; error[validator-decorations-failed]: `@isLowercase()` failed for `slug`: value must already be lowercase
at /src/main.tyr:6:34
const invalid: Example = { slug: "Invalid-Slug" };
^^^^^^^^^^^^^^@isUppercase
Garante que a string contenha apenas caracteres maiúsculos.
@isUppercase(message?: string)interface Example {
@isUppercase()
countryCode: string;
}
const valid: Example = { countryCode: "BR" };error
const invalid: Example = { countryCode: "br" }; error[validator-decorations-failed]: `@isUppercase()` failed for `countryCode`: value must already be uppercase
at /src/main.tyr:6:41
const invalid: Example = { countryCode: "br" };
^^^^@startsWith
Garante que a string comece com o prefixo informado.
@startsWith(value: string, message?: string)interface Example {
@startsWith("user_")
userId: string;
}
const valid: Example = { userId: "user_abc" };error
const invalid: Example = { userId: "abc_123" }; error[validator-decorations-failed]: `@startsWith("user_")` failed for `userId`: value must start with "user_"
at /src/main.tyr:6:36
const invalid: Example = { userId: "abc_123" };
^^^^^^^^^@endsWith
Garante que a string termine com o sufixo informado.
@endsWith(value: string, message?: string)interface Example {
@endsWith(".md")
fileName: string;
}
const valid: Example = { fileName: "readme.md" };error
const invalid: Example = { fileName: "readme.txt" }; error[validator-decorations-failed]: `@endsWith(".md")` failed for `fileName`: value must end with ".md"
at /src/main.tyr:6:38
const invalid: Example = { fileName: "readme.txt" };
^^^^^^^^^^^^@includes
Garante que a string contenha a substring informada.
@includes(value: string, message?: string)interface Example {
@includes("@")
handle: string;
}
const valid: Example = { handle: "user@domain" };error
const invalid: Example = { handle: "no-at-sign" }; error[validator-decorations-failed]: `@includes("@")` failed for `handle`: value must include "@"
at /src/main.tyr:6:36
const invalid: Example = { handle: "no-at-sign" };
^^^^^^^^^^^^@regex
Garante que a string corresponda à expressão regular informada.
@regex(value: Regex, message?: string)interface Example {
@regex(/^[a-z]+$/)
alphaName: string;
}
const valid: Example = { alphaName: "hello" };error
const invalid: Example = { alphaName: "user123" }; error[validator-decorations-failed]: `@regex(/^[a-z]+$/)` failed for `alphaName`: value must match /^[a-z]+$/
at /src/main.tyr:6:39
const invalid: Example = { alphaName: "user123" };
^^^^^^^^^Formato
@email
Garante que o valor seja um endereço de e-mail válido.
@email(message?: string)interface Example {
@email()
contactEmail: string;
}
const valid: Example = { contactEmail: "[email protected]" };error
const invalid: Example = { contactEmail: "not-an-email" }; error[validator-decorations-failed]: `@email()` failed for `contactEmail`: value must be a valid e-mail address
at /src/main.tyr:6:42
const invalid: Example = { contactEmail: "not-an-email" };
^^^^^^^^^^^^^^@url
Garante que o valor seja uma URL válida.
@url(message?: string)interface Example {
@url()
website: string;
}
const valid: Example = { website: "https://example.com" };error
const invalid: Example = { website: "not-a-url" }; error[validator-decorations-failed]: `@url()` failed for `website`: value must be a valid URL
at /src/main.tyr:6:37
const invalid: Example = { website: "not-a-url" };
^^^^^^^^^^^@uuid
Garante que o valor seja um UUID válido.
@uuid(message?: string)interface Example {
@uuid()
sessionId: string;
}
const valid: Example = { sessionId: "550e8400-e29b-41d4-a716-446655440000" };error
const invalid: Example = { sessionId: "not-a-uuid" }; error[validator-decorations-failed]: `@uuid()` failed for `sessionId`: value must be a valid UUID
at /src/main.tyr:6:39
const invalid: Example = { sessionId: "not-a-uuid" };
^^^^^^^^^^^^@ip
Garante que o valor seja um endereço IP válido (v4 ou v6).
@ip(message?: string)interface Example {
@ip()
clientIp: string;
}
const valid: Example = { clientIp: "192.168.1.1" };error
const invalid: Example = { clientIp: "999.999.999.999" }; error[validator-decorations-failed]: `@ip()` failed for `clientIp`: value must be a valid IP address
at /src/main.tyr:6:38
const invalid: Example = { clientIp: "999.999.999.999" };
^^^^^^^^^^^^^^^^^@ipv4
Garante que o valor seja um endereço IPv4 válido.
@ipv4(message?: string)interface Example {
@ipv4()
localhost: string;
}
const valid: Example = { localhost: "127.0.0.1" };error
const invalid: Example = { localhost: "999.999.999.999" }; error[validator-decorations-failed]: `@ipv4()` failed for `localhost`: value must be a valid IPv4 address
at /src/main.tyr:6:39
const invalid: Example = { localhost: "999.999.999.999" };
^^^^^^^^^^^^^^^^^@ipv6
Garante que o valor seja um endereço IPv6 válido.
@ipv6(message?: string)interface Example {
@ipv6()
ipv6Host: string;
}
const valid: Example = { ipv6Host: "::1" };error
const invalid: Example = { ipv6Host: "not-ipv6" }; error[validator-decorations-failed]: `@ipv6()` failed for `ipv6Host`: value must be a valid IPv6 address
at /src/main.tyr:6:38
const invalid: Example = { ipv6Host: "not-ipv6" };
^^^^^^^^^^@e164
Garante que o valor seja um número de telefone E.164 válido.
@e164(message?: string)interface Example {
@e164()
phoneNumber: string;
}
const valid: Example = { phoneNumber: "+5511999999999" };error
const invalid: Example = { phoneNumber: "1234567890" }; error[validator-decorations-failed]: `@e164()` failed for `phoneNumber`: value must be a valid E.164 phone number
at /src/main.tyr:6:41
const invalid: Example = { phoneNumber: "1234567890" };
^^^^^^^^^^^^@cep
Garante que o valor seja um CEP brasileiro válido.
@cep(message?: string)interface Example {
@cep()
postalCode: string;
}
const valid: Example = { postalCode: "01310-100" };error
const invalid: Example = { postalCode: "12345" }; error[validator-decorations-failed]: `@cep()` failed for `postalCode`: value must be a valid Brazilian postal code
at /src/main.tyr:6:40
const invalid: Example = { postalCode: "12345" };
^^^^^^^@cpf
Garante que o valor seja um CPF brasileiro válido.
@cpf(message?: string)interface Example {
@cpf()
taxId: string;
}
const valid: Example = { taxId: "529.982.247-25" };error
const invalid: Example = { taxId: "12345678901" }; error[validator-decorations-failed]: `@cpf()` failed for `taxId`: value must be a valid Brazilian CPF
at /src/main.tyr:6:35
const invalid: Example = { taxId: "12345678901" };
^^^^^^^^^^^^^@cnpj
Garante que o valor seja um CNPJ brasileiro válido.
@cnpj(message?: string)interface Example {
@cnpj()
companyTaxId: string;
}
const valid: Example = { companyTaxId: "11.444.777/0001-61" };error
const invalid: Example = { companyTaxId: "12345678901234" }; error[validator-decorations-failed]: `@cnpj()` failed for `companyTaxId`: value must be a valid Brazilian CNPJ
at /src/main.tyr:6:42
const invalid: Example = { companyTaxId: "12345678901234" };
^^^^^^^^^^^^^^^^Array
@minItems
Garante que o array contenha ao menos o número especificado de itens.
@minItems(value: i64, message?: string)interface Example {
@minItems(1)
tags: string[];
}
const valid: Example = { tags: ["hello"] };error
const invalid: Example = { tags: [] }; error[validator-decorations-failed]: `@minItems(1)` failed for `tags`: array must contain at least 1 items
at /src/main.tyr:6:34
const invalid: Example = { tags: [] };
^^@maxItems
Garante que o array contenha no máximo o número especificado de itens.
@maxItems(value: i64, message?: string)interface Example {
@maxItems(10)
selectedIds: i32[];
}
const valid: Example = { selectedIds: [1, 2, 3] };error
const invalid: Example = { selectedIds: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11] }; error[validator-decorations-failed]: `@maxItems(10)` failed for `selectedIds`: array must contain at most 10 items
at /src/main.tyr:6:41
const invalid: Example = { selectedIds: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11] };
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^@lengthItems
Garante que o array tenha exatamente o comprimento especificado.
@lengthItems(value: i64, message?: string)interface Example {
@lengthItems(3)
coordinates: f64[];
}
const valid: Example = { coordinates: [1.0, 2.0, 3.0] };error
const invalid: Example = { coordinates: [1.0, 2.0] }; error[validator-decorations-failed]: `@lengthItems(3)` failed for `coordinates`: array must contain exactly 3 items
at /src/main.tyr:6:41
const invalid: Example = { coordinates: [1.0, 2.0] };
^^^^^^^^^^@notEmptyItems
Garante que o array não esteja vazio.
@notEmptyItems(message?: string)interface Example {
@notEmptyItems()
members: string[];
}
const valid: Example = { members: ["user1"] };error
const invalid: Example = { members: [] }; error[validator-decorations-failed]: `@notEmptyItems()` failed for `members`: array must not be empty
at /src/main.tyr:6:37
const invalid: Example = { members: [] };
^^@unique
Garante que todos os itens do array sejam distintos.
@unique(message?: string)interface Example {
@unique()
permissions: string[];
}
const valid: Example = { permissions: ["read", "write"] };error
const invalid: Example = { permissions: ["read", "write", "read"] }; error[validator-decorations-failed]: `@unique()` failed for `permissions`: array items must be unique
at /src/main.tyr:6:41
const invalid: Example = { permissions: ["read", "write", "read"] };
^^^^^^^^^^^^^^^^^^^^^^^^^Igualdade e pertinência
@equal
Garante que o valor seja igual ao literal informado.
@equal(value: T, message?: string)interface Example {
@equal("active")
status: string;
}
const valid: Example = { status: "active" };error
const invalid: Example = { status: "inactive" }; error[validator-decorations-failed]: `@equal("active")` failed for `status`: value must be equal to "active"
at /src/main.tyr:6:36
const invalid: Example = { status: "inactive" };
^^^^^^^^^^@notEqual
Garante que o valor seja diferente do literal informado.
@notEqual(value: T, message?: string)interface Example {
@notEqual("deleted")
accountType: string;
}
const valid: Example = { accountType: "active" };error
const invalid: Example = { accountType: "deleted" }; error[validator-decorations-failed]: `@notEqual("deleted")` failed for `accountType`: value must be different from "deleted"
at /src/main.tyr:6:41
const invalid: Example = { accountType: "deleted" };
^^^^^^^^^@in
Garante que o valor seja uma das opções especificadas.
@in(value: T[], message?: string)interface Example {
@in(["red", "green", "blue"])
color: string;
}
const valid: Example = { color: "blue" };error
const invalid: Example = { color: "yellow" }; error[validator-decorations-failed]: `@in(["red", "green", "blue"])` failed for `color`: value must be one of ["red", "green", "blue"]
at /src/main.tyr:6:35
const invalid: Example = { color: "yellow" };
^^^^^^^^@notIn
Garante que o valor não seja nenhuma das opções especificadas.
@notIn(value: T[], message?: string)interface Example {
@notIn(["admin", "superadmin"])
role: string;
}
const valid: Example = { role: "user" };error
const invalid: Example = { role: "admin" }; error[validator-decorations-failed]: `@notIn(["admin", "superadmin"])` failed for `role`: value must not be one of ["admin", "superadmin"]
at /src/main.tyr:6:34
const invalid: Example = { role: "admin" };
^^^^^^^Nulidade e presença
@notNull
Garante que um alvo opcional carregue um valor.
@notNull(message?: string)interface Example {
@notNull()
requiredField: string?;
}
const valid: Example = { requiredField: "hello" };error
const invalid: Example = { requiredField: null }; error[unhandled-throw]: validation of field `requiredField` may throw `ValidationError`; catch it or add `throws ValidationError` to the enclosing function
at /src/main.tyr:6:43
const invalid: Example = { requiredField: null };
^^^^
error[validator-decorations-failed]: `@notNull()` failed for `requiredField`: value must not be null
at /src/main.tyr:6:43
const invalid: Example = { requiredField: null };
^^^^
error[E0308]: type mismatch for `requiredField`: expected `string?`, found `null`
at /src/main.tyr:6:28
const invalid: Example = { requiredField: null };
^^^^^^^^^^^^^
help: change the value or the annotation so their types match; convert numbers explicitly with `value as <type>`@optional
Marca um campo ou parâmetro como explicitamente opcional.
@optional(message?: string)interface Example {
@optional()
nickName: string?;
}
const validWithValue: Example = { nickName: "Johnny" };
const validAbsent: Example = {};@required
Garante que o alvo tenha um valor.
@required(message?: string)interface Example {
@required()
mandatoryParam: string;
}
const valid: Example = { mandatoryParam: "present" };error
const invalid: Example = { /* missing mandatoryParam */ }; error[E2741]: property `mandatoryParam` is missing in object literal for type `Example`
at /src/main.tyr:6:7
const invalid: Example = { /* missing mandatoryParam */ };
^^^^^^^A validação é aplicada automaticamente quando objetos tipados são criados ou atualizados e quando funções decoradas são chamadas. O comportamento de schemas de rota pertence ao roadmap HTTP e não faz parte deste mecanismo no nível da linguagem.
Alvos Opcionais
Um validator colocado em um alvo opcional se aplica ao valor que o opcional carrega, então ele só roda quando há um valor presente. Um opcional ausente passa em todos os validators, exceto @notNull e @required, que testam a própria presença e por isso se aplicam ao opcional, não ao valor que ele carrega.
interface Contact {
@email()
email?: string;
}
const acceptAge = (@min(18) age?: i32): void => {
print(age ?? -1); // -1
};
const main = (): void => {
const empty: Contact = {};
print(empty.email ?? "no e-mail"); // "no e-mail"
try {
acceptAge();
} catch (error: ValidationError) {
print(error.issues[0].validator); // "min"
}
};Nem o campo email omitido nem o argumento age omitido falham na validação: não há valor a verificar. Fornecer um valor inválido faz os mesmos validators falharem exatamente como fariam em um alvo obrigatório.
Validação Recuperável em Runtime
Falhas de validação dinâmica lançam ValidationError; elas não encerram a aplicação quando são tratadas. ValidationError.issues está sempre presente e contém pelo menos um ValidationIssue somente de leitura, portanto o mesmo tratamento funciona quando uma regra ou várias regras falham. Uma função decorada declara esse efeito implicitamente. Uma função intermediária deve tratá-lo ou propagá-lo com throws ValidationError, enquanto main deve tratar todo erro alcançável e não pode declarar throws.
O alvo de cada issue é um caminho lógico determinístico. Campos aninhados usam notação de ponto, como profile.address.zipCode, e elementos de array incluem seu índice baseado em zero, como members[0].address.zipCode.
O caminho tem como raiz o valor que a operação valida, e não um tipo mais externo qualquer. Construir um objeto aninhado antes, numa variável própria, torna aquela construção uma operação de validação por si só, então as issues dela têm como raiz aquele objeto: o alvo é zipCode, e não members[0].address.zipCode.
Uma operação de validação coleta todas as regras que falharam antes de lançar: a criação ou atualização de um objeto coleta issues de todos os campos decorados, e uma chamada de função decorada coleta issues de todos os parâmetros decorados. As issues preservam a ordem de declaração e avaliação. Operações separadas lançam valores ValidationError separados e nunca são mescladas.
interface SignupInput {
@minLength(3)
username: string;
@email()
email: string;
}
const readUsername = (): string => "a";
const readEmail = (): string => "invalid";
const buildSignup = (): SignupInput throws ValidationError => {
return {
username: readUsername(),
email: readEmail(),
};
};
const main = (): void => {
try {
const input: SignupInput = buildSignup();
print(input.username); // "a"
} catch (error: ValidationError) {
match (error.issues.length === (1 as usize)) {
(true) => {
const issue = error.issues[0];
print(issue.target); // "username"
print(issue.message); // "must be at least 3 characters"
}
_ => {
for (const issue of error.issues) {
print(issue.target); // field name
print(issue.message); // validation message
}
}
}
}
};ValidationIssue normalmente é inferido quando um item é lido de error.issues; o desenvolvedor não o constrói nem o lança. Passar um issue para um helper somente de leitura não exige escrever &.
Ler e iterar error.issues dentro do catch é o padrão usual. Um move ou retorno direto de error.issues também é seguro: a propriedade acompanha o array retornado em vez de ser liberada com o erro capturado.
const printIssue = (issue: ValidationIssue): void => {
print(issue.validator); // "email"
print(issue.message); // "invalid e-mail"
};
const printValidation = (error: ValidationError): void => {
for (const issue of error.issues) {
printIssue(issue);
}
};A validação de .env tipado é a exceção: uma configuração inicial inválida é fatal porque a aplicação não pode iniciar com um ambiente inválido.
@in e @notIn aceitam um array homogêneo inline ou um array const de nível de módulo que possa ser completamente resolvido em tempo de compilação. O array pode conter membros de enum. Variáveis runtime, bindings let, chamadas de função e valores de API são rejeitados porque os argumentos de decorations são metadados de compilação. Schemas .env tipados continuam usando arrays inline porque arquivos .env não possuem escopo de símbolos ou imports do tyrus.
enum Role: string {
Admin = "admin",
User = "user",
}
const allowedRoles: Role[] = [Role.Admin, Role.User];
const authorize = (@in(allowedRoles) role: Role): void => {
print(role); // Role.Admin or Role.User
};Validators com Regex
interface SlugInput {
@regex(/^[a-z0-9-]+$/)
slug: string;
}@regex usa o tipo nativo Regex. As flags suportadas são i, m, s e x; look-around e backreferences não são suportados intencionalmente.
