Validator Decorations
Validator Decorations son anotaciones nativas de validación de tyrus. Pueden adjuntarse a campos de interface, campos de tipos de objeto y parámetros de función. El compilador verifica que cada validator exista, apunte a un tipo compatible y reciba argumentos literales del tipo esperado.
Ejemplo
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;Los validators integrados verifican valores literales en tiempo de compilación y se ejecutan en runtime para valores dinámicos en parámetros decorados, literales de objeto y updates de objeto.
Validator Decorations en archivos .env
Tyrus acepta Validator Decorations en archivos .env con o sin # al inicio. Usa la forma comentada cuando otro loader de .env, como Docker, también lea el archivo; Tyrus sigue interpretando la decoración, mientras los demás loaders ven un comentario.
# @type(u16)
# @port()
PORT=8080Mensajes de error
Los validators integrados permiten reemplazar el mensaje predeterminado con un literal string como último argumento aceptado.
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;
}La misma regla funciona en parámetros de función decorados.
const divide = (value: f64, @notEqual(0, "division by zero is not allowed") divisor: f64): f64 => {
return value / divisor;
};Prefiere mensajes customizados en fronteras con usuario
Los mensajes default son útiles durante el desarrollo. Los mensajes customizados son mejores para fronteras de API, prompts de CLI y fallas de validación que pueden aparecer para usuarios.
Familias de Validators
| Familia | Ejemplos |
|---|---|
| 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 y valores | @minItems, @maxItems, @lengthItems, @notEmptyItems, @unique, @in, @notIn, @equal, @notEqual, @notNull, @optional, @required |
Objetivos de los Validators
Un validator numérico se comprueba en la aritmética del tipo que decora: un campo i64 se compara como entero y un campo f64 como float. Un número entero por encima de 2^53 conserva, por lo tanto, su valor exacto, y el veredicto en tiempo de compilación siempre coincide con la comprobación emitida para el mismo valor.
@port, @powerOfTwo y @statusCode apuntan solo a tipos enteros, porque sus reglas no tienen lectura sobre un valor fraccionario. Un puerto no es 8080.5.
@unique compara elementos por valor, así que acepta arrays de números, strings, booleanos, enums, tuplas, tipos de objeto e interfaces nombradas cuyos campos también se comparen por valor. Un array de arrays se rechaza en tiempo de compilación: los arrays se comparan por dirección, así que [[1, 2], [1, 2]] sería reportado como único.
Operación del Validator
Cada familia de validators impone restricciones específicas en los valores que decora. El compilador verifica valores literales en tiempo de compilación y emite comprobaciones de runtime para valores dinámicos. A continuación hay ejemplos para cada familia de validators con sus mensajes de error predeterminados.
Numéricos
@min
Garantiza que el valor sea como mínimo el 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
Garantiza que el valor sea como máximo el 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
Garantiza que el valor esté dentro del rango 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
Garantiza que el valor sea mayor que cero.
@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
Garantiza que el valor sea menor que cero.
@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
Garantiza que el valor sea cero o mayor.
@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
Garantiza que el valor sea cero o 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
Garantiza que el valor sea múltiplo del divisor indicado.
@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
Garantiza que el valor sea una potencia de dos.
@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
Garantiza que un valor de punto flotante no tenga parte fraccionaria.
@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
Garantiza que el valor entero esté dentro del rango 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
Garantiza que el valor sea un puerto registrado entre 1024 y 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
Garantiza que el valor sea un código HTTP válido entre 100 y 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
Garantiza que la cadena contenga al menos el 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
Garantiza que la cadena contenga como máximo el 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
Garantiza que la cadena tenga exactamente la longitud especificada.
@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
Garantiza que la cadena no esté vacía.
@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
Garantiza que la cadena contenga al menos un carácter no blanco.
@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
Garantiza que la cadena no tenga espacios al inicio o al final.
@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
Garantiza que la cadena contenga solo caracteres en minúscula.
@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
Garantiza que la cadena contenga solo caracteres en mayúscula.
@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
Garantiza que la cadena comience con el prefijo indicado.
@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
Garantiza que la cadena termine con el sufijo indicado.
@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
Garantiza que la cadena contenga la subcadena indicada.
@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
Garantiza que la cadena coincida con la expresión regular indicada.
@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
Garantiza que el valor sea una dirección de e-mail válida.
@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
Garantiza que el valor sea una 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
Garantiza que el valor sea un 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
Garantiza que el valor sea una dirección IP válida (v4 o 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
Garantiza que el valor sea una dirección IPv4 válida.
@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
Garantiza que el valor sea una dirección IPv6 válida.
@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
Garantiza que el valor sea un número de teléfono 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
Garantiza que el valor sea un CEP brasileño 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
Garantiza que el valor sea un CPF brasileño 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
Garantiza que el valor sea un CNPJ brasileño 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
Garantiza que el array contenga al menos el número especificado de elementos.
@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
Garantiza que el array contenga como máximo el número especificado de elementos.
@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
Garantiza que el array tenga exactamente la longitud especificada.
@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
Garantiza que el array no esté vacío.
@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
Garantiza que todos los elementos del array sean 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"] };
^^^^^^^^^^^^^^^^^^^^^^^^^Igualdad y pertenencia
@equal
Garantiza que el valor sea igual al literal indicado.
@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
Garantiza que el valor sea diferente del literal indicado.
@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
Garantiza que el valor sea una de las opciones 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
Garantiza que el valor no sea ninguna de las opciones 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" };
^^^^^^^Anulabilidad y presencia
@notNull
Garantiza que un objetivo opcional tenga un 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 un campo o parámetro como explícitamente opcional.
@optional(message?: string)interface Example {
@optional()
nickName: string?;
}
const validWithValue: Example = { nickName: "Johnny" };
const validAbsent: Example = {};@required
Garantiza que el objetivo tenga un 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 */ };
^^^^^^^La validación se aplica automáticamente cuando se crean o actualizan objetos tipados y cuando se llaman funciones decoradas. El comportamiento de schemas de ruta pertenece al roadmap HTTP y no forma parte de este mecanismo a nivel de lenguaje.
Objetivos Opcionales
Un validator colocado en un objetivo opcional se aplica al valor que el opcional lleva, así que solo se ejecuta cuando hay un valor presente. Un opcional ausente pasa todos los validators, excepto @notNull y @required, que comprueban la presencia misma y por eso se aplican al opcional y no al valor que lleva.
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"
}
};Ni el campo email omitido ni el argumento age omitido fallan la validación: no hay valor que comprobar. Suministrar un valor inválido hace que los mismos validators fallen exactamente como lo harían en un objetivo obligatorio.
Validación Recuperable en Runtime
Las fallas de validación dinámica lanzan ValidationError; no terminan la aplicación cuando son tratadas. ValidationError.issues siempre está presente y contiene al menos un ValidationIssue de solo lectura, por lo que el mismo tratamiento funciona cuando falla una regla o varias reglas. Una función decorada declara este efecto implícitamente. Una función intermedia debe tratarlo o propagarlo con throws ValidationError, mientras que main debe tratar todos los errores alcanzables y no puede declarar throws.
El destino de cada issue es una ruta lógica determinista. Los campos anidados usan notación de punto, como profile.address.zipCode, y los elementos de array incluyen su índice basado en cero, como members[0].address.zipCode.
La ruta tiene como raíz el valor que la operación valida, y no un tipo más externo cualquiera. Construir un objeto anidado antes, en su propia variable, convierte esa construcción en una operación de validación por sí misma, así que sus issues tienen como raíz ese objeto: el destino es zipCode, y no members[0].address.zipCode.
Una operación de validación recopila todas las reglas que fallaron antes de lanzar: la creación o actualización de un objeto recopila issues de todos los campos decorados, y una llamada de función decorada recopila issues de todos los parámetros decorados. Las issues preservan el orden de declaración y evaluación. Operaciones separadas lanzan valores ValidationError separados y nunca se combinan.
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 se infiere cuando se lee un elemento de error.issues; el desarrollador no lo construye ni lo lanza. Pasar un issue a un helper de solo lectura no requiere escribir &.
Leer e iterar error.issues dentro del catch es el patrón habitual. Un move o retorno directo de error.issues también es seguro: la propiedad acompaña al array retornado en lugar de liberarse con el error 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);
}
};La validación de .env tipado es la excepción: una configuración inicial inválida es fatal porque la aplicación no puede iniciar con un entorno inválido.
@in y @notIn aceptan un array homogéneo inline o un array const de nivel de módulo que pueda resolverse completamente en tiempo de compilación. El array puede contener miembros de enum. Variables runtime, bindings let, llamadas de función y valores de API son rechazados porque los argumentos de decorations son metadatos de compilación. Los schemas .env tipados continúan usando arrays inline porque los archivos .env no tienen scope de símbolos ni imports de 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 con Regex
interface SlugInput {
@regex(/^[a-z0-9-]+$/)
slug: string;
}@regex usa el tipo nativo Regex. Las flags soportadas son i, m, s y x; look-around y backreferences no son soportados intencionalmente.
