Skip to content

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 ​

tyrus
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.

dotenv
# @type(u16)
# @port()
PORT=8080

Mensajes de error ​

Los validators integrados permiten reemplazar el mensaje predeterminado con un literal string como último argumento aceptado.

tyrus
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.

tyrus
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 ​

FamiliaEjemplos
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.

Firma@min(value: i8 | i16 | i32 | i64 | u8 | u16 | u32 | u64 | f32 | f64 | f128, message?: string)
tyrus
interface Example {
    @min(1)
    pageSize: u32;
}

const valid: Example = { pageSize: 5 };

error

tyrus
const invalid: Example = { pageSize: 0 }; 
text
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.

Firma@max(value: i8 | i16 | i32 | i64 | u8 | u16 | u32 | u64 | f32 | f64 | f128, message?: string)
tyrus
interface Example {
    @max(100)
    limit: i32;
}

const valid: Example = { limit: 50 };

error

tyrus
const invalid: Example = { limit: 200 }; 
text
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.

Firma@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)
tyrus
interface Example {
    @range(1, 50)
    offset: i32;
}

const valid: Example = { offset: 25 };

error

tyrus
const invalid: Example = { offset: 60 }; 
text
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.

Firma@positive(message?: string)
tyrus
interface Example {
    @positive()
    amount: f64;
}

const valid: Example = { amount: 5.0 };

error

tyrus
const invalid: Example = { amount: -5.0 }; 
text
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.

Firma@negative(message?: string)
tyrus
interface Example {
    @negative()
    debt: f64;
}

const valid: Example = { debt: -10.0 };

error

tyrus
const invalid: Example = { debt: 10.0 }; 
text
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.

Firma@nonNegative(message?: string)
tyrus
interface Example {
    @nonNegative()
    balance: f64;
}

const valid: Example = { balance: 0.0 };

error

tyrus
const invalid: Example = { balance: -1.0 }; 
text
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.

Firma@nonPositive(message?: string)
tyrus
interface Example {
    @nonPositive()
    withdrawal: f64;
}

const valid: Example = { withdrawal: 0.0 };

error

tyrus
const invalid: Example = { withdrawal: 5.0 }; 
text
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.

Firma@multipleOf(value: i8 | i16 | i32 | i64 | u8 | u16 | u32 | u64 | f32 | f64 | f128, message?: string)
tyrus
interface Example {
    @multipleOf(5)
    quantity: i32;
}

const valid: Example = { quantity: 10 };

error

tyrus
const invalid: Example = { quantity: 7 }; 
text
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.

Firma@powerOfTwo(message?: string)
tyrus
interface Example {
    @powerOfTwo()
    bufferSize: u32;
}

const valid: Example = { bufferSize: 8 };

error

tyrus
const invalid: Example = { bufferSize: 3 }; 
text
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.

Firma@integer(message?: string)
tyrus
interface Example {
    @integer()
    count: f64;
}

const valid: Example = { count: 42.0 };

error

tyrus
const invalid: Example = { count: 3.14 }; 
text
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⁵³.

Firma@safeInteger(message?: string)
tyrus
interface Example {
    @safeInteger()
    largeId: f64;
}

const valid: Example = { largeId: 9007199254740992 };

error

tyrus
const invalid: Example = { largeId: 9007199254740993 }; 
text
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.

Firma@port(message?: string)
tyrus
interface Example {
    @port()
    serverPort: u16;
}

const valid: Example = { serverPort: 8080 };

error

tyrus
const invalid: Example = { serverPort: 80 }; 
text
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.

Firma@statusCode(message?: string)
tyrus
interface Example {
    @statusCode()
    responseCode: u16;
}

const valid: Example = { responseCode: 200 };

error

tyrus
const invalid: Example = { responseCode: 99 }; 
text
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.

Firma@minLength(value: i64, message?: string)
tyrus
interface Example {
    @minLength(3)
    username: string;
}

const valid: Example = { username: "abc" };

error

tyrus
const invalid: Example = { username: "ab" }; 
text
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.

Firma@maxLength(value: i64, message?: string)
tyrus
interface Example {
    @maxLength(50)
    displayName: string;
}

const valid: Example = { displayName: "A".repeat(10) };

error

tyrus
const invalid: Example = { displayName: "A".repeat(51) }; 
text
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.

Firma@length(value: i64, message?: string)
tyrus
interface Example {
    @length(8)
    code: string;
}

const valid: Example = { code: "12345678" };

error

tyrus
const invalid: Example = { code: "1234567" }; 
text
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.

Firma@notEmpty(message?: string)
tyrus
interface Example {
    @notEmpty()
    firstName: string;
}

const valid: Example = { firstName: "John" };

error

tyrus
const invalid: Example = { firstName: "" }; 
text
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.

Firma@notBlank(message?: string)
tyrus
interface Example {
    @notBlank()
    bio: string;
}

const valid: Example = { bio: "Hello" };

error

tyrus
const invalid: Example = { bio: "   " }; 
text
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.

Firma@isTrimmed(message?: string)
tyrus
interface Example {
    @isTrimmed()
    title: string;
}

const valid: Example = { title: "no spaces" };

error

tyrus
const invalid: Example = { title: " spaces " }; 
text
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.

Firma@isLowercase(message?: string)
tyrus
interface Example {
    @isLowercase()
    slug: string;
}

const valid: Example = { slug: "valid-slug" };

error

tyrus
const invalid: Example = { slug: "Invalid-Slug" }; 
text
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.

Firma@isUppercase(message?: string)
tyrus
interface Example {
    @isUppercase()
    countryCode: string;
}

const valid: Example = { countryCode: "BR" };

error

tyrus
const invalid: Example = { countryCode: "br" }; 
text
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.

Firma@startsWith(value: string, message?: string)
tyrus
interface Example {
    @startsWith("user_")
    userId: string;
}

const valid: Example = { userId: "user_abc" };

error

tyrus
const invalid: Example = { userId: "abc_123" }; 
text
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.

Firma@endsWith(value: string, message?: string)
tyrus
interface Example {
    @endsWith(".md")
    fileName: string;
}

const valid: Example = { fileName: "readme.md" };

error

tyrus
const invalid: Example = { fileName: "readme.txt" }; 
text
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.

Firma@includes(value: string, message?: string)
tyrus
interface Example {
    @includes("@")
    handle: string;
}

const valid: Example = { handle: "user@domain" };

error

tyrus
const invalid: Example = { handle: "no-at-sign" }; 
text
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.

Firma@regex(value: Regex, message?: string)
tyrus
interface Example {
    @regex(/^[a-z]+$/)
    alphaName: string;
}

const valid: Example = { alphaName: "hello" };

error

tyrus
const invalid: Example = { alphaName: "user123" }; 
text
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.

Firma@email(message?: string)
tyrus
interface Example {
    @email()
    contactEmail: string;
}

const valid: Example = { contactEmail: "[email protected]" };

error

tyrus
const invalid: Example = { contactEmail: "not-an-email" }; 
text
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.

Firma@url(message?: string)
tyrus
interface Example {
    @url()
    website: string;
}

const valid: Example = { website: "https://example.com" };

error

tyrus
const invalid: Example = { website: "not-a-url" }; 
text
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.

Firma@uuid(message?: string)
tyrus
interface Example {
    @uuid()
    sessionId: string;
}

const valid: Example = { sessionId: "550e8400-e29b-41d4-a716-446655440000" };

error

tyrus
const invalid: Example = { sessionId: "not-a-uuid" }; 
text
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).

Firma@ip(message?: string)
tyrus
interface Example {
    @ip()
    clientIp: string;
}

const valid: Example = { clientIp: "192.168.1.1" };

error

tyrus
const invalid: Example = { clientIp: "999.999.999.999" }; 
text
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.

Firma@ipv4(message?: string)
tyrus
interface Example {
    @ipv4()
    localhost: string;
}

const valid: Example = { localhost: "127.0.0.1" };

error

tyrus
const invalid: Example = { localhost: "999.999.999.999" }; 
text
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.

Firma@ipv6(message?: string)
tyrus
interface Example {
    @ipv6()
    ipv6Host: string;
}

const valid: Example = { ipv6Host: "::1" };

error

tyrus
const invalid: Example = { ipv6Host: "not-ipv6" }; 
text
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.

Firma@e164(message?: string)
tyrus
interface Example {
    @e164()
    phoneNumber: string;
}

const valid: Example = { phoneNumber: "+5511999999999" };

error

tyrus
const invalid: Example = { phoneNumber: "1234567890" }; 
text
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.

Firma@cep(message?: string)
tyrus
interface Example {
    @cep()
    postalCode: string;
}

const valid: Example = { postalCode: "01310-100" };

error

tyrus
const invalid: Example = { postalCode: "12345" }; 
text
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.

Firma@cpf(message?: string)
tyrus
interface Example {
    @cpf()
    taxId: string;
}

const valid: Example = { taxId: "529.982.247-25" };

error

tyrus
const invalid: Example = { taxId: "12345678901" }; 
text
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.

Firma@cnpj(message?: string)
tyrus
interface Example {
    @cnpj()
    companyTaxId: string;
}

const valid: Example = { companyTaxId: "11.444.777/0001-61" };

error

tyrus
const invalid: Example = { companyTaxId: "12345678901234" }; 
text
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.

Firma@minItems(value: i64, message?: string)
tyrus
interface Example {
    @minItems(1)
    tags: string[];
}

const valid: Example = { tags: ["hello"] };

error

tyrus
const invalid: Example = { tags: [] }; 
text
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.

Firma@maxItems(value: i64, message?: string)
tyrus
interface Example {
    @maxItems(10)
    selectedIds: i32[];
}

const valid: Example = { selectedIds: [1, 2, 3] };

error

tyrus
const invalid: Example = { selectedIds: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11] }; 
text
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.

Firma@lengthItems(value: i64, message?: string)
tyrus
interface Example {
    @lengthItems(3)
    coordinates: f64[];
}

const valid: Example = { coordinates: [1.0, 2.0, 3.0] };

error

tyrus
const invalid: Example = { coordinates: [1.0, 2.0] }; 
text
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.

Firma@notEmptyItems(message?: string)
tyrus
interface Example {
    @notEmptyItems()
    members: string[];
}

const valid: Example = { members: ["user1"] };

error

tyrus
const invalid: Example = { members: [] }; 
text
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.

Firma@unique(message?: string)
tyrus
interface Example {
    @unique()
    permissions: string[];
}

const valid: Example = { permissions: ["read", "write"] };

error

tyrus
const invalid: Example = { permissions: ["read", "write", "read"] }; 
text
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.

Firma@equal(value: T, message?: string)
tyrus
interface Example {
    @equal("active")
    status: string;
}

const valid: Example = { status: "active" };

error

tyrus
const invalid: Example = { status: "inactive" }; 
text
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.

Firma@notEqual(value: T, message?: string)
tyrus
interface Example {
    @notEqual("deleted")
    accountType: string;
}

const valid: Example = { accountType: "active" };

error

tyrus
const invalid: Example = { accountType: "deleted" }; 
text
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.

Firma@in(value: T[], message?: string)
tyrus
interface Example {
    @in(["red", "green", "blue"])
    color: string;
}

const valid: Example = { color: "blue" };

error

tyrus
const invalid: Example = { color: "yellow" }; 
text
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.

Firma@notIn(value: T[], message?: string)
tyrus
interface Example {
    @notIn(["admin", "superadmin"])
    role: string;
}

const valid: Example = { role: "user" };

error

tyrus
const invalid: Example = { role: "admin" }; 
text
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.

Firma@notNull(message?: string)
tyrus
interface Example {
    @notNull()
    requiredField: string?;
}

const valid: Example = { requiredField: "hello" };

error

tyrus
const invalid: Example = { requiredField: null }; 
text
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.

Firma@optional(message?: string)
tyrus
interface Example {
    @optional()
    nickName: string?;
}

const validWithValue: Example = { nickName: "Johnny" };
const validAbsent: Example = {};

@required ​

Garantiza que el objetivo tenga un valor.

Firma@required(message?: string)
tyrus
interface Example {
    @required()
    mandatoryParam: string;
}

const valid: Example = { mandatoryParam: "present" };

error

tyrus
const invalid: Example = { /* missing mandatoryParam */ }; 
text
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.

tyrus
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.

tyrus
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.

tyrus
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.

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 ​

tyrus
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.