yup Télécharger - yup Téléchargement du code source

Ouais

Yup est un générateur de schéma pour l'analyse et la validation des valeurs d'exécution. Définissez un schéma, transformez une valeur pour qu'elle corresponde, affirmez la forme d'une valeur existante, ou les deux. Oui, les schémas sont extrêmement expressifs et permettent de modéliser des validations complexes et interdépendantes ou une transformation de valeur.

Vous consultez des documents pour la v1.0.0 de oui, les documents pré-v1 sont disponibles : ici

Caractéristiques tueuses :

Interface de schéma concise mais expressive, équipée pour modéliser des modèles de données simples à complexes
Prise en charge puissante de TypeScript. Déduire des types statiques à partir du schéma ou garantir que le schéma implémente correctement un type
Prise en charge de la validation asynchrone intégrée. Modélisez aussi bien la validation côté serveur que côté client
Extensible : ajoutez vos propres méthodes et schémas de type sécurisé
De riches détails sur les erreurs facilitent le débogage

Commencer

Les schémas comprennent des actions d'analyse (transformations) ainsi que des assertions (tests) sur la valeur d'entrée. Validez une valeur d’entrée pour l’analyser et exécuter l’ensemble d’assertions configuré. Enchaînez les méthodes pour créer un schéma.

 import { object , string , number , date , InferType } from 'yup' ;

let userSchema = object ( {
  name : string ( ) . required ( ) ,
  age : number ( ) . required ( ) . positive ( ) . integer ( ) ,
  email : string ( ) . email ( ) ,
  website : string ( ) . url ( ) . nullable ( ) ,
  createdOn : date ( ) . default ( ( ) => new Date ( ) ) ,
} ) ;

// parse and assert validity
let user = await userSchema . validate ( await fetchUser ( ) ) ;

type User = InferType < typeof userSchema > ;
/* {
  name: string;
  age: number;
  email?: string | undefined
  website?: string | null | undefined
  createdOn: Date
}*/

Utilisez un schéma pour contraindre ou « convertir » une valeur d’entrée dans le type correct, et éventuellement transformer cette valeur en valeurs plus concrètes et spécifiques, sans faire d’autres affirmations.

 // Attempts to coerce values to the correct type
let parsedUser = userSchema . cast ( {
  name : 'jimmy' ,
  age : '24' ,
  createdOn : '2014-09-23T19:25:25Z' ,
} ) ;
// ✅  { name: 'jimmy', age: 24, createdOn: Date }

Vous savez que votre valeur d'entrée est déjà analysée ? Vous pouvez valider « strictement » une entrée et éviter la surcharge liée à l'exécution de la logique d'analyse.

 //   ValidationError "age is not a number"
let parsedUser = await userSchema . validate (
  {
    name : 'jimmy' ,
    age : '24' ,
  } ,
  { strict : true } ,
) ;

Table des matières

Bases du schéma
- Analyse : transformations
- Validation : Tests
  - Erreurs de personnalisation
- Composition et réutilisation
Intégration TypeScript
- Valeurs par défaut du schéma
- S'assurer qu'un schéma correspond à un type existant
- Extension du schéma intégré avec de nouvelles méthodes
- Configuration dactylographiée
Personnalisation des messages d'erreur
- localisation et i18n
API
- yup
  - reach(schema: Schema, path: string, value?: object, context?: object): Schema
  - addMethod(schemaType: Schema, name: string, method: ()=> Schema): void
  - ref(path: string, options: { contextPrefix: string }): Ref
  - lazy((value: any) => Schema): Lazy
  - ValidationError(errors: string | Array<string>, value: any, path: string)
- Schema
  - Schema.clone(): Schema
  - Schema.label(label: string): Schema
  - Schema.meta(metadata: SchemaMetadata): Schema
  - Schema.describe(options?: ResolveOptions): SchemaDescription
  - Schema.concat(schema: Schema): Schema
  - Schema.validate(value: any, options?: object): Promise<InferType<Schema>, ValidationError>
  - Schema.validateSync(value: any, options?: object): InferType<Schema>
  - Schema.validateAt(path: string, value: any, options?: object): Promise<InferType<Schema>, ValidationError>
  - Schema.validateSyncAt(path: string, value: any, options?: object): InferType<Schema>
  - Schema.isValid(value: any, options?: object): Promise<boolean>
  - Schema.isValidSync(value: any, options?: object): boolean
  - Schema.cast(value: any, options = {}): InferType<Schema>
  - Schema.isType(value: any): value is InferType<Schema>
  - Schema.strict(enabled: boolean = false): Schema
  - Schema.strip(enabled: boolean = true): Schema
  - Schema.withMutation(builder: (current: Schema) => void): void
  - Schema.default(value: any): Schema
  - Schema.getDefault(options?: object): Any
  - Schema.nullable(message?: string | function): Schema
  - Schema.nonNullable(message?: string | function): Schema
  - Schema.defined(): Schema
  - Schema.optional(): Schema
  - Schema.required(message?: string | function): Schema
  - Schema.notRequired(): Schema
  - Schema.typeError(message: string): Schema
  - Schema.oneOf(arrayOfValues: Array<any>, message?: string | function): Schema : equals
  - Schema.notOneOf(arrayOfValues: Array<any>, message?: string | function)
  - Schema.when(keys: string | string[], builder: object | (values: any[], schema) => Schema): Schema
  - Schema.test(name: string, message: string | function | any, test: function): Schema
  - Schema.test(options: object): Schema
  - Schema.transform((currentValue: any, originalValue: any) => any): Schema
- mixte
- chaîne
  - string.required(message?: string | function): Schema
  - string.length(limit: number | Ref, message?: string | function): Schema
  - string.min(limit: number | Ref, message?: string | function): Schema
  - string.max(limit: number | Ref, message?: string | function): Schema
  - string.matches(regex: Regex, message?: string | function): Schema
  - string.matches(regex: Regex, options: { message: string, excludeEmptyString: bool }): Schema
  - string.email(message?: string | function): Schema
  - string.url(message?: string | function): Schema
  - string.uuid(message?: string | function): Schema
  - string.datetime(options?: {message?: string | function, allowOffset?: boolean, precision?: number})
  - string.datetime(message?: string | function)
  - string.ensure(): Schema
  - string.trim(message?: string | function): Schema
  - string.lowercase(message?: string | function): Schema
  - string.uppercase(message?: string | function): Schema
- nombre
  - number.min(limit: number | Ref, message?: string | function): Schema
  - number.max(limit: number | Ref, message?: string | function): Schema
  - number.lessThan(max: number | Ref, message?: string | function): Schema
  - number.moreThan(min: number | Ref, message?: string | function): Schema
  - number.positive(message?: string | function): Schema
  - number.negative(message?: string | function): Schema
  - number.integer(message?: string | function): Schema
  - number.truncate(): Schema
  - number.round(type: 'floor' | 'ceil' | 'trunc' | 'round' = 'round'): Schema
- booléen
- date
  - date.min(limit: Date | string | Ref, message?: string | function): Schema
  - date.max(limit: Date | string | Ref, message?: string | function): Schema
- tableau
  - array.of(type: Schema): this
  - array.json(): this
  - array.length(length: number | Ref, message?: string | function): this
  - array.min(limit: number | Ref, message?: string | function): this
  - array.max(limit: number | Ref, message?: string | function): this
  - array.ensure(): this
  - array.compact(rejector: (value) => boolean): Schema
- tuple
- objet
  - Valeurs par défaut du schéma d'objet
  - object.shape(fields: object, noSortEdges?: Array<[string, string]>): Schema
  - object.json(): this
  - object.concat(schemaB: ObjectSchema): ObjectSchema
  - object.pick(keys: string[]): Schema
  - object.omit(keys: string[]): Schema
  - object.from(fromKey: string, toKey: string, alias: boolean = false): this
  - object.noUnknown(onlyKnownKeys: boolean = true, message?: string | function): Schema
  - object.camelCase(): Schema
  - object.constantCase(): Schema

Bases du schéma

Les définitions de schéma comprennent des « transformations » d'analyse qui manipulent les entrées dans la forme et le type souhaités, et des « tests » qui effectuent des assertions sur les données analysées. Le schéma stocke également un ensemble de « métadonnées », des détails sur le schéma lui-même, qui peuvent être utilisés pour améliorer les messages d'erreur, créer des outils qui consomment dynamiquement le schéma ou sérialiser le schéma dans un autre format.

Afin d'être aussi flexible que possible, yup permet d'exécuter à la fois l'analyse et les assertions séparément pour répondre à des besoins spécifiques.

Analyse : transformations

Chaque type intégré implémente une analyse de type de base, ce qui s'avère pratique lors de l'analyse de données sérialisées, telles que JSON. De plus, les types implémentent des transformations spécifiques au type qui peuvent être activées.

 let num = number ( ) . cast ( '1' ) ; // 1

let obj = object ( {
  firstName : string ( ) . lowercase ( ) . trim ( ) ,
} )
  . json ( )
  . camelCase ( )
  . cast ( '{"first_name": "jAnE "}' ) ; // { firstName: 'jane' }

Des transformations personnalisées peuvent être ajoutées

 let reversedString = string ( )
  . transform ( ( currentValue ) => currentValue . split ( '' ) . reverse ( ) . join ( '' ) )
  . cast ( 'dlrow olleh' ) ; // "hello world"

Les transformations forment un « pipeline », dans lequel la valeur d'une transformation précédente est redirigée vers la suivante. Lorsqu'une valeur d'entrée undefined yup appliquera le schéma par défaut s'il est configuré.

Attention! Il n'est pas garanti que les valeurs soient des types valides dans les fonctions de transformation. Les transformations précédentes ont peut-être échoué. Par exemple, une transformation numérique peut recevoir la valeur d'entrée, NaN ou un nombre.

Validation : Tests

Oui, le schéma exécute des "tests" sur les valeurs d'entrée. Les tests affirment que les entrées sont conformes à certains critères. Les tests sont distincts des transformations, dans le sens où ils ne modifient ni n'altèrent l'entrée (ou son type) et sont généralement réservés aux vérifications difficiles, voire impossibles, à représenter dans les types statiques.

 string ( )
  . min ( 3 , 'must be at least 3 characters long' )
  . email ( 'must be a valid email' )
  . validate ( 'no' ) ; // ValidationError

Comme pour les transformations, les tests peuvent être personnalisés à la volée

 let jamesSchema = string ( ) . test (
  'is-james' ,
  ( d ) => ` ${ d . path } is not James` ,
  ( value ) => value == null || value === 'James' ,
) ;

jamesSchema . validateSync ( 'James' ) ; // "James"

jamesSchema . validateSync ( 'Jane' ) ; // ValidationError "this is not James"

Attention : contrairement aux transformations, value dans un test personnalisé est garantie d'être du type correct (dans ce cas, une chaîne facultative). Il peut toujours être undefined ou null selon votre schéma. Dans ces cas, vous souhaiterez peut-être renvoyer true pour les valeurs absentes, à moins que votre transformation ne fasse des assertions liées à la présence. L'option de test skipAbsent le fera pour vous si elle est définie.

Erreurs de personnalisation

Dans le cas le plus simple, une fonction de test renvoie true ou false selon que le contrôle a réussi. En cas d'échec d'un test, yup lancera une ValidationError avec votre message (ou le message par défaut) pour ce test. ValidationErrors contient également de nombreuses autres métadonnées sur le test, notamment son nom, les arguments (le cas échéant) avec lesquels il a été appelé et le chemin d'accès au champ défaillant dans le cas d'une validation imbriquée.

Des messages d'erreur peuvent également être générés à la volée pour personnaliser la manière dont le schéma échoue.

 let order = object ( {
  no : number ( ) . required ( ) ,
  sku : string ( ) . test ( {
    name : 'is-sku' ,
    skipAbsent : true ,
    test ( value , ctx ) {
      if ( ! value . startsWith ( 's-' ) ) {
        return ctx . createError ( { message : 'SKU missing correct prefix' } )
      }
      if ( ! value . endsWith ( '-42a' ) ) {
        return ctx . createError ( { message : 'SKU missing correct suffix' } )
      }
      if ( value . length < 10 ) {
        return ctx . createError ( { message : 'SKU is not the right length' } )
      }
      return true
    }
  } )
} )

order . validate ( { no : 1234 , sku : 's-1a45-14a' } )

Composition et réutilisation

Les schémas sont immuables, chaque appel de méthode renvoie un nouvel objet de schéma. Réutilisez-les et faites-les circuler sans craindre de muter une autre instance.

 let optionalString = string ( ) . optional ( ) ;

let definedString = optionalString . defined ( ) ;

let value = undefined ;
optionalString . isValid ( value ) ; // true
definedString . isValid ( value ) ; // false

Intégration TypeScript

Oui, le schéma produit des interfaces TypeScript statiques. Utilisez InferType pour extraire cette interface :

 import * as yup from 'yup' ;

let personSchema = yup . object ( {
  firstName : yup . string ( ) . defined ( ) ,
  nickName : yup . string ( ) . default ( '' ) . nullable ( ) ,
  sex : yup
    . mixed ( )
    . oneOf ( [ 'male' , 'female' , 'other' ] as const )
    . defined ( ) ,
  email : yup . string ( ) . nullable ( ) . email ( ) ,
  birthDate : yup . date ( ) . nullable ( ) . min ( new Date ( 1900 , 0 , 1 ) ) ,
} ) ;

interface Person extends yup . InferType < typeof personSchema > {
  // using interface instead of type generally gives nicer editor feedback
}

Valeurs par défaut du schéma

La valeur par défaut d'un schéma est utilisée lorsque le casting produit une valeur de sortie undefined . Pour cette raison, la définition d'une valeur par défaut affecte le type de sortie du schéma, le marquant essentiellement comme « défini () ».

 import { string } from 'yup' ;

let value : string = string ( ) . default ( 'hi' ) . validate ( undefined ) ;

// vs

let value : string | undefined = string ( ) . validate ( undefined ) ;

S'assurer qu'un schéma correspond à un type existant

Dans certains cas, un type TypeScript existe déjà et vous souhaitez vous assurer que votre schéma produit un type compatible :

 import { object , number , string , ObjectSchema } from 'yup' ;

interface Person {
  name : string ;
  age ?: number ;
  sex : 'male' | 'female' | 'other' | null ;
}

// will raise a compile-time type error if the schema does not produce a valid Person
let schema : ObjectSchema < Person > = object ( {
  name : string ( ) . defined ( ) ,
  age : number ( ) . optional ( ) ,
  sex : string < 'male' | 'female' | 'other' > ( ) . nullable ( ) . defined ( ) ,
} ) ;

//  errors:
// "Type 'number | undefined' is not assignable to type 'string'."
let badSchema : ObjectSchema < Person > = object ( {
  name : number ( ) ,
} ) ;

Extension du schéma intégré avec de nouvelles méthodes

Vous pouvez utiliser le comportement de fusion d'interface de TypeScript pour étendre les types de schéma si nécessaire. Les extensions de type doivent être placées dans un fichier de définition de type "ambiant" tel que votre globals.d.ts . N'oubliez pas d'étendre réellement le type yup dans votre code d'application !

Attention! la fusion ne fonctionne que si la définition du type est exactement la même, y compris les génériques. Consultez le code source yup pour chaque type pour vous assurer que vous le définissez correctement

 // globals.d.ts
declare module 'yup' {
  interface StringSchema < TType , TContext , TDefault , TFlags > {
    append ( appendStr : string ) : this ;
  }
}

// app.ts
import { addMethod , string } from 'yup' ;

addMethod ( string , 'append' , function append ( appendStr : string ) {
  return this . transform ( ( value ) => ` ${ value } ${ appendStr } ` ) ;
} ) ;

string ( ) . append ( '~~~~' ) . cast ( 'hi' ) ; // 'hi~~~~'

Configuration dactylographiée

L’option du compilateur strictNullChecks doit être activée pour que l’inférence de type fonctionne.

Nous recommandons également de définir strictFunctionTypes sur false , pour des types fonctionnellement meilleurs. Oui, cela réduit la solidité globale, mais TypeScript désactive déjà cette vérification pour les méthodes et les constructeurs (note de la documentation TS) :

Lors du développement de cette fonctionnalité, nous avons découvert un grand nombre de hiérarchies de classes intrinsèquement dangereuses, dont certaines dans le DOM. Pour cette raison, le paramètre s'applique uniquement aux fonctions écrites dans la syntaxe de fonction, et non à celles écrites dans la syntaxe de méthode :

Votre kilométrage variera, mais nous avons constaté que cette vérification n'empêche pas de nombreux bugs réels, tout en augmentant la quantité de conversion de type explicite et onéreuse dans les applications.

Personnalisation des messages d'erreur

Les messages d'erreur par défaut peuvent être personnalisés lorsqu'aucun message n'est fourni avec un test de validation. Si un message manque dans le dictionnaire personnalisé, le message d'erreur sera par défaut celui de Yup.

 import { setLocale } from 'yup' ;

setLocale ( {
  mixed : {
    default : 'Não é válido' ,
  } ,
  number : {
    min : 'Deve ser maior que ${min}' ,
  } ,
} ) ;

// now use Yup schemas AFTER you defined your custom dictionary
let schema = yup . object ( ) . shape ( {
  name : yup . string ( ) ,
  age : yup . number ( ) . min ( 18 ) ,
} ) ;

try {
  await schema . validate ( { name : 'jimmy' , age : 11 } ) ;
} catch ( err ) {
  err . name ; // => 'ValidationError'
  err . errors ; // => ['Deve ser maior que 18']
}

localisation et i18n

Si vous avez besoin d’une assistance multilingue, vous avez ce qu’il vous faut. La fonction setLocale accepte des fonctions qui peuvent être utilisées pour générer des objets d'erreur avec des clés et des valeurs de traduction. Ceux-ci peuvent être introduits dans votre bibliothèque i18n préférée.

 import { setLocale } from 'yup' ;

setLocale ( {
  // use constant translation keys for messages without values
  mixed : {
    default : 'field_invalid' ,
  } ,
  // use functions to generate an error object that includes the value from the schema
  number : {
    min : ( { min } ) => ( { key : 'field_too_short' , values : { min } } ) ,
    max : ( { max } ) => ( { key : 'field_too_big' , values : { max } } ) ,
  } ,
} ) ;

// ...

let schema = yup . object ( ) . shape ( {
  name : yup . string ( ) ,
  age : yup . number ( ) . min ( 18 ) ,
} ) ;

try {
  await schema . validate ( { name : 'jimmy' , age : 11 } ) ;
} catch ( err ) {
  messages = err . errors . map ( ( err ) => i18next . t ( err . key ) ) ;
}

API

`yup`

L'exportation du module.

 // core schema
import {
  mixed ,
  string ,
  number ,
  boolean ,
  bool ,
  date ,
  object ,
  array ,
  ref ,
  lazy ,
} from 'yup' ;

// Classes
import {
  Schema ,
  MixedSchema ,
  StringSchema ,
  NumberSchema ,
  BooleanSchema ,
  DateSchema ,
  ArraySchema ,
  ObjectSchema ,
} from 'yup' ;

// Types
import type { InferType , ISchema , AnySchema , AnyObjectSchema } from 'yup' ;

`reach(schema: Schema, path: string, value?: object, context?: object): Schema`

Pour les schémas imbriqués, reach récupérera un schéma interne basé sur le chemin fourni.

Pour les schémas imbriqués qui doivent être résolus dynamiquement, vous pouvez fournir une value et éventuellement un objet context .

 import { reach } from 'yup' ;

let schema = object ( {
  nested : object ( {
    arr : array ( object ( { num : number ( ) . max ( 4 ) } ) ) ,
  } ) ,
} ) ;

reach ( schema , 'nested.arr.num' ) ;
reach ( schema , 'nested.arr[].num' ) ;
reach ( schema , 'nested.arr[1].num' ) ;
reach ( schema , 'nested["arr"][1].num' ) ;

`addMethod(schemaType: Schema, name: string, method: ()=> Schema): void`

Ajoute une nouvelle méthode aux types de schéma principaux. Une méthode plus conviviale pour schemaType.prototype[name] = method .

 import { addMethod , date } from 'yup' ;

addMethod ( date , 'format' , function format ( formats , parseStrict ) {
  return this . transform ( ( value , originalValue , ctx ) => {
    if ( ctx . isType ( value ) ) return value ;

    value = Moment ( originalValue , formats , parseStrict ) ;

    return value . isValid ( ) ? value . toDate ( ) : new Date ( '' ) ;
  } ) ;
} ) ;

Si vous souhaitez ajouter une méthode à TOUS les types de schéma, étendez la classe de base abstraite : Schema

 import { addMethod , Schema } from 'yup' ;

addMethod ( Schema , 'myMethod' , ... )

`ref(path: string, options: { contextPrefix: string }): Ref`

Crée une référence à un autre champ frère ou descendant frère. Les références sont résolues au moment de la validation/diffusion et prises en charge lorsque cela est spécifié. Les références sont évaluées dans le bon ordre afin que la valeur de la référence soit résolue avant le champ utilisant la référence (attention aux dépendances circulaires !).

 import { ref , object , string } from 'yup' ;

let schema = object ( {
  baz : ref ( 'foo.bar' ) ,
  foo : object ( {
    bar : string ( ) ,
  } ) ,
  x : ref ( '$x' ) ,
} ) ;

schema . cast ( { foo : { bar : 'boom' } } , { context : { x : 5 } } ) ;
// => { baz: 'boom',  x: 5, foo: { bar: 'boom' } }

`lazy((value: any) => Schema): Lazy`

Crée un schéma qui est évalué au moment de la validation/diffusion. Utile pour créer un schéma récursif comme des arbres, pour des champs et des tableaux polymorphes.

PRUDENCE! Lors de la définition du schéma d'objet récursif parent-enfant, vous souhaitez réinitialiser le default() à null sur l'enfant, sinon l'objet s'imbriquera à l'infini lorsque vous le lancerez !

 let node = object ( {
  id : number ( ) ,
  child : yup . lazy ( ( ) => node . default ( undefined ) ) ,
} ) ;

let renderable = yup . lazy ( ( value ) => {
  switch ( typeof value ) {
    case 'number' :
      return number ( ) ;
    case 'string' :
      return string ( ) ;
    default :
      return mixed ( ) ;
  }
} ) ;

let renderables = array ( ) . of ( renderable ) ;

`ValidationError(errors: string | Array<string>, value: any, path: string)`

Lancé en cas d'échec des validations, avec les propriétés suivantes

name : "ValidationError"
type : le type de test spécifique ou le "nom" du test qui a échoué.
value : La valeur du champ qui a été testée ;
params ? : les entrées de test, telles que la valeur maximale, l'expression régulière, etc. ;
path : une chaîne indiquant où l'erreur a été générée. path est vide au niveau racine.
errors : tableau de messages d'erreur
inner : dans le cas d'erreurs globales, inner est un tableau de ValidationErrors lancé plus tôt dans la chaîne de validation. Lorsque l'option abortEarly est false , c'est ici que vous pouvez inspecter chaque erreur générée. Alternativement, errors auront tous les messages de chaque erreur interne.

`Schema`

Schema est la classe de base abstraite dont héritent tous les types de schéma. Il fournit un certain nombre de méthodes et de propriétés de base à tous les autres types de schéma.

Remarque : sauf si vous créez un type de schéma personnalisé, Schema ne doit jamais être utilisé directement. Pour les types inconnus/tous, utilisez mixed()

`Schema.clone(): Schema`

Crée une copie complète du schéma. Clone est utilisé en interne pour renvoyer un nouveau schéma à chaque changement d'état du schéma.

`Schema.label(label: string): Schema`

Remplace le nom de clé utilisé dans les messages d'erreur.

`Schema.meta(metadata: SchemaMetadata): Schema`

S'ajoute à un objet de métadonnées, utile pour stocker des données avec un schéma, qui n'appartient pas à l'objet de diffusion lui-même.

Une interface SchemaMetadata personnalisée peut être définie en fusionnant avec l'interface CustomSchemaMetadata . Commencez par créer un fichier yup.d.ts dans votre package et créez l'interface CustomSchemaMetadata souhaitée :

 // yup.d.ts
import 'yup' ;

declare module 'yup' {
  // Define your desired `SchemaMetadata` interface by merging the
  // `CustomSchemaMetadata` interface.
  export interface CustomSchemaMetadata {
    placeholderText ?: string ;
    tooltipText ?: string ;
    // …
  }
}

`Schema.describe(options?: ResolveOptions): SchemaDescription`

Collecte les détails du schéma (comme les méta, les étiquettes et les tests actifs) dans un objet de description sérialisable.

 let schema = object ( {
  name : string ( ) . required ( ) ,
} ) ;

let description = schema . describe ( ) ;

Pour les schémas avec des composants dynamiques (références, paresseux ou conditions), la description nécessite plus de contexte pour renvoyer avec précision la description du schéma. Dans ces cas, proposez options

 import { ref , object , string , boolean } from 'yup' ;

let schema = object ( {
  isBig : boolean ( ) ,
  count : number ( ) . when ( 'isBig' , {
    is : true ,
    then : ( schema ) => schema . min ( 5 ) ,
    otherwise : ( schema ) => schema . min ( 0 ) ,
  } ) ,
} ) ;

schema . describe ( { value : { isBig : true } } ) ;

Et ci-dessous se trouvent les types de description, qui diffèrent un peu selon le type de schéma.

 interface SchemaDescription {
  type : string ;
  label ?: string ;
  meta : object | undefined ;
  oneOf : unknown [ ] ;
  notOneOf : unknown [ ] ;
  default ?: unknown ;
  nullable : boolean ;
  optional : boolean ;
  tests : Array < { name ?: string ; params : ExtraParams | undefined } > ;

  // Present on object schema descriptions
  fields : Record < string , SchemaFieldDescription > ;

  // Present on array schema descriptions
  innerType ?: SchemaFieldDescription ;
}

type SchemaFieldDescription =
  | SchemaDescription
  | SchemaRefDescription
  | SchemaLazyDescription ;

interface SchemaRefDescription {
  type : 'ref' ;
  key : string ;
}

interface SchemaLazyDescription {
  type : string ;
  label ?: string ;
  meta : object | undefined ;
}

`Schema.concat(schema: Schema): Schema`

Crée une nouvelle instance du schéma en combinant deux schémas. Seuls les schémas du même type peuvent être concaténés. concat n'est pas une fonction de "fusion" dans le sens où tous les paramètres du schéma fourni remplacent ceux de la base, y compris le type, la présence et la nullité.

 mixed < string > ( ) . defined ( ) . concat ( mixed < number > ( ) . nullable ( ) ) ;

// produces the equivalent to:

mixed < number > ( ) . defined ( ) . nullable ( ) ;

`Schema.validate(value: any, options?: object): Promise<InferType<Schema>, ValidationError>`

Renvoie les analyses et valide une valeur d'entrée, en renvoyant la valeur analysée ou en lançant une erreur. Cette méthode est asynchrone et renvoie un objet Promise, qui est rempli avec la valeur ou rejeté avec une ValidationError .

 value = await schema . validate ( { name : 'jimmy' , age : 24 } ) ;

Fournissez options pour contrôler plus spécifiquement le comportement de validate .

 interface Options {
  // when true, parsing is skipped and the input is validated "as-is"
  strict: boolean = false ;
  // Throw on the first error or collect and return all
  abortEarly: boolean = true ;
  // Remove unspecified keys from objects
  stripUnknown: boolean = false ;
  // when `false` validations will be performed shallowly
  recursive: boolean = true ;
  // External values that can be provided to validations and conditionals
  context ?: object ;
}

`Schema.validateSync(value: any, options?: object): InferType<Schema>`

Exécute les validations de manière synchrone si possible et renvoie la valeur résultante, ou renvoie une ValidationError. Accepte toutes les mêmes options que validate .

La validation synchrone ne fonctionne que s'il n'y a pas de tests asynchrones configurés, par exemple des tests qui renvoient une promesse. Par exemple, cela fonctionnera :

 let schema = number ( ) . test (
  'is-42' ,
  "this isn't the number i want" ,
  ( value ) => value != 42 ,
) ;

schema . validateSync ( 23 ) ; // throws ValidationError

cependant, ce ne sera pas :

 let schema = number ( ) . test ( 'is-42' , "this isn't the number i want" , ( value ) =>
  Promise . resolve ( value != 42 ) ,
) ;

schema . validateSync ( 42 ) ; // throws Error

`Schema.validateAt(path: string, value: any, options?: object): Promise<InferType<Schema>, ValidationError>`

Validez un chemin profondément imbriqué dans le schéma. Semblable au fonctionnement reach , mais utilise le schéma résultant comme sujet de validation.

Note! La value ici est la valeur racine relative au schéma de départ, et non la valeur au chemin imbriqué.

 let schema = object ( {
  foo : array ( ) . of (
    object ( {
      loose : boolean ( ) ,
      bar : string ( ) . when ( 'loose' , {
        is : true ,
        otherwise : ( schema ) => schema . strict ( ) ,
      } ) ,
    } ) ,
  ) ,
} ) ;

let rootValue = {
  foo : [ { bar : 1 } , { bar : 1 , loose : true } ] ,
} ;

await schema . validateAt ( 'foo[0].bar' , rootValue ) ; // => ValidationError: must be a string

await schema . validateAt ( 'foo[1].bar' , rootValue ) ; // => '1'

`Schema.validateSyncAt(path: string, value: any, options?: object): InferType<Schema>`

Identique à validateAt mais synchrone.

`Schema.isValid(value: any, options?: object): Promise<boolean>`

Renvoie true lorsque la valeur transmise correspond au schéma. isValid est asynchrone et renvoie un objet Promise.

Prend les mêmes options que validate() .

`Schema.isValidSync(value: any, options?: object): boolean`

Renvoie true de manière synchrone lorsque la valeur transmise correspond au schéma.

Prend les mêmes options que validateSync() et présente les mêmes mises en garde concernant les tests asynchrones.

`Schema.cast(value: any, options = {}): InferType<Schema>`

Tente de contraindre la valeur transmise à une valeur qui correspond au schéma. Par exemple : '5' sera converti en 5 lors de l'utilisation du type number() . Les conversions échouées renvoient généralement null , mais peuvent également renvoyer des résultats tels que NaN et des chaînes inattendues.

Fournissez options pour contrôler plus spécifiquement le comportement de validate .

 interface CastOptions < TContext extends { } > {
  // Remove undefined properties from objects
  stripUnknown : boolean = false ;

  // Throws a TypeError if casting doesn't produce a valid type
  // note that the TS return type is inaccurate when this is `false`, use with caution
  assert ?: boolean = true ;

  // External values that used to resolve conditions and references
  context ?: TContext ;
}

`Schema.isType(value: any): value is InferType<Schema>`

Exécute une vérification de type par rapport à la value transmise. Il renvoie vrai si cela correspond, il ne convertit pas la valeur. Lorsque nullable() est défini, null est considéré comme une valeur valide du type. Vous devez utiliser isType pour toutes les vérifications de type de schéma.

`Schema.strict(enabled: boolean = false): Schema`

Définit l'option strict sur true . Les schémas stricts évitent les tentatives de coercition et de transformation, validant la valeur « telle quelle ».

`Schema.strip(enabled: boolean = true): Schema`

Marque un schéma à supprimer d’un objet de sortie. Fonctionne uniquement comme un schéma imbriqué.

 let schema = object ( {
  useThis : number ( ) ,
  notThis : string ( ) . strip ( ) ,
} ) ;

schema . cast ( { notThis : 'foo' , useThis : 4 } ) ; // => { useThis: 4 }

Les schémas avec strip activé ont un type déduit never , ce qui leur permet d'être supprimés du type global :

 let schema = object ( {
  useThis : number ( ) ,
  notThis : string ( ) . strip ( ) ,
} ) ;

InferType < typeof schema > ; /*
{
   useThis?: number | undefined
}
*/

`Schema.withMutation(builder: (current: Schema) => void): void`

Tout d’abord, la citation de Rich Hickey légalement requise :

Si un arbre tombe dans la forêt, est-ce qu'il fait un bruit ?
Si une fonction pure mute certaines données locales afin de produire une valeur de retour immuable, est-ce que ça va ?

withMutation vous permet de muter le schéma sur place, au lieu du comportement par défaut qui est cloné avant chaque modification. Généralement, cela n'est pas nécessaire puisque la grande majorité des modifications de schéma se produisent lors de la déclaration initiale et ne se produisent qu'une seule fois au cours de la durée de vie du schéma. Les performances ne sont donc pas un problème. Cependant, certaines mutations se produisent au moment de la conversion/validation (comme un schéma conditionnel utilisant when() ) ou lors de l'instanciation d'un objet de schéma.

 object ( )
  . shape ( { key : string ( ) } )
  . withMutation ( ( schema ) => {
    return arrayOfObjectTests . forEach ( ( test ) => {
      schema . test ( test ) ;
    } ) ;
  } ) ;

`Schema.default(value: any): Schema`

Définit une valeur par défaut à utiliser lorsque la valeur n'est undefined . Les valeurs par défaut sont créées après l'exécution des transformations, mais avant les validations, pour garantir que des valeurs par défaut sûres sont spécifiées. La valeur par défaut sera clonée à chaque utilisation, ce qui peut entraîner une dégradation des performances des objets et des tableaux. Pour éviter cette surcharge, vous pouvez également transmettre une fonction qui renvoie une nouvelle valeur par défaut. Notez que null est considéré comme une valeur distincte non vide.

 yup . string . default ( 'nothing' ) ;

yup . object . default ( { number : 5 } ) ; // object will be cloned every time a default is needed

yup . object . default ( ( ) => ( { number : 5 } ) ) ; // this is cheaper

yup . date . default ( ( ) => new Date ( ) ) ; // also helpful for defaults that change over time

`Schema.getDefault(options?: object): Any`

Récupère une valeur par défaut précédemment définie. getDefault résoudra toutes les conditions susceptibles de modifier la valeur par défaut. Transmettez éventuellement options avec context (pour plus d'informations sur context voir Schema.validate ).

`Schema.nullable(message?: string | function): Schema`

Indique que null est une valeur valide pour le schéma. Sans nullable() null est traité comme un type différent et échouera aux vérifications Schema.isType() .

 let schema = number ( ) . nullable ( ) ;

schema . cast ( null ) ; // null

InferType < typeof schema > ; // number | null

`Schema.nonNullable(message?: string | function): Schema`

Le contraire de nullable supprime null des valeurs de type valides pour le schéma. Les schémas ne sont pas nullables par défaut .

 let schema = number ( ) . nonNullable ( ) ;

schema . cast ( null ) ; // TypeError

InferType < typeof schema > ; // number

`Schema.defined(): Schema`

Exiger une valeur pour le schéma. Toutes les valeurs de champ, à l'exception undefined répondent à cette exigence.

 let schema = string ( ) . defined ( ) ;

schema . cast ( undefined ) ; // TypeError

InferType < typeof schema > ; // string

`Schema.optional(): Schema`

L'opposé de defined() autorise des valeurs undefined pour le type donné.

 let schema = string ( ) . optional ( ) ;

schema . cast ( undefined ) ; // undefined

InferType < typeof schema > ; // string | undefined

`Schema.required(message?: string | function): Schema`

Marquez le schéma comme requis, ce qui n'autorisera pas undefined ou null comme valeur. required annule les effets de l'appel de optional() et nullable()

Attention! string().required ) fonctionne un peu différemment et empêche en outre les valeurs de chaîne vides ( '' ) lorsque cela est nécessaire.

`Schema.notRequired(): Schema`

Marquez le schéma comme non requis. Il s'agit d'un raccourci pour schema.nullable().optional() ;

`Schema.typeError(message: string): Schema`

Définissez un message d'erreur pour les vérifications de type ayant échoué. L'interpolation ${value} et ${type} peut être utilisée dans l'argument message .

`Schema.oneOf(arrayOfValues: Array<any>, message?: string | function): Schema` : `equals`

Autoriser uniquement les valeurs d'un ensemble de valeurs. Les valeurs ajoutées sont supprimées de toutes les valeurs notOneOf si elles sont présentes. L'interpolation ${values} peut être utilisée dans l'argument message . Si une ou plusieurs références sont fournies, l'interpolation ${resolved} peut être utilisée dans l'argument du message pour obtenir les valeurs résolues qui ont été vérifiées au moment de la validation.

Notez undefined ne fait pas échouer ce validateur, même si undefined n'est pas inclus dans arrayOfValues . Si vous ne souhaitez pas que undefined soit une valeur valide, vous pouvez utiliser Schema.required .

 let schema = yup . mixed ( ) . oneOf ( [ 'jimmy' , 42 ] ) ;

await schema . isValid ( 42 ) ; // => true
await schema . isValid ( 'jimmy' ) ; // => true
await schema . isValid ( new Date ( ) ) ; // => false

`Schema.notOneOf(arrayOfValues: Array<any>, message?: string | function)`

Interdire les valeurs d’un ensemble de valeurs. Les valeurs ajoutées sont supprimées des valeurs oneOf si elles sont présentes. L'interpolation ${values} peut être utilisée dans l'argument message . Si une ou plusieurs références sont fournies, l'interpolation ${resolved} peut être utilisée dans l'argument du message pour obtenir les valeurs résolues qui ont été vérifiées au moment de la validation.

 let schema = yup . mixed ( ) . notOneOf ( [ 'jimmy' , 42 ] ) ;

await schema . isValid ( 42 ) ; // => false
await schema . isValid ( new Date ( ) ) ; // => true

`Schema.when(keys: string | string[], builder: object | (values: any[], schema) => Schema): Schema`

Ajustez le schéma en fonction des champs d'un frère ou d'un enfant frère ou sœur. Vous pouvez fournir un objet littéral où la clé is une valeur ou une fonction de correspondance, then fournir le vrai schéma et/ou otherwise pour la condition d'échec.

is conditions sont strictement comparées ( === ) si vous souhaitez utiliser une forme différente d'égalité, vous pouvez fournir une fonction comme : is: (value) => value == true .

Vous pouvez également préfixer les propriétés avec $ pour spécifier une propriété qui dépend du context transmis par validate() ou cast à la place de la valeur d'entrée.

when les conditions s’additionnent.

then et otherwise sont des fonctions spécifiées (schema: Schema) => Schema .

 let schema = object ( {
  isBig : boolean ( ) ,
  count : number ( )
    . when ( 'isBig' , {
      is : true , // alternatively: (val) => val == true
      then : ( schema ) => schema . min ( 5 ) ,
      otherwise : ( schema ) => schema . min ( 0 ) ,
    } )
    . when ( '$other' , ( [ other ] , schema ) =>
      other === 4 ? schema . max ( 6 ) : schema ,
    ) ,
} ) ;

await schema . validate ( value , { context : { other : 4 } } ) ;

Vous pouvez également spécifier plusieurs clés dépendantes, auquel cas chaque valeur sera répartie en tant qu'argument.

 let schema = object ( {
  isSpecial : boolean ( ) ,
  isBig : boolean ( ) ,
  count : number ( ) . when ( [ 'isBig' , 'isSpecial' ] , {
    is : true , // alternatively: (isBig, isSpecial) => isBig && isSpecial
    then : ( schema ) => schema . min ( 5 ) ,
    otherwise : ( schema ) => schema . min ( 0 ) ,
  } ) ,
} ) ;

await schema . validate ( {
  isBig : true ,
  isSpecial : true ,
  count : 10 ,
} ) ;

Vous pouvez également fournir une fonction qui renvoie un schéma, appelé avec un tableau de valeurs pour chaque clé fournie dans le schéma actuel.

 let schema = yup . object ( {
  isBig : yup . boolean ( ) ,
  count : yup . number ( ) . when ( 'isBig' , ( [ isBig ] , schema ) => {
    return isBig ? schema . min ( 5 ) : schema . min ( 0 ) ;
  } ) ,
} ) ;

await schema . validate ( { isBig : false , count : 4 } ) ;

`Schema.test(name: string, message: string | function | any, test: function): Schema`

Ajoute une fonction de test à la chaîne de validation. Les tests sont exécutés après la conversion d'un objet. De nombreux types intègrent des tests, mais vous pouvez facilement en créer des personnalisés. Afin de permettre des validations personnalisées asynchrones, tous (ou aucun) tests sont exécutés de manière asynchrone. Une conséquence de ceci est que l’ordre d’exécution des tests ne peut pas être garanti.

Tous les tests doivent fournir un name , un message d'erreur et une fonction de validation qui doit renvoyer true lorsque la value actuelle est valide et false ou une ValidationError dans le cas contraire. Pour effectuer un test asynchrone, renvoyez une promesse qui résout true ou false ou une ValidationError .

Pour l'argument message , vous pouvez fournir une chaîne qui interpolera certaines valeurs si elle est spécifiée à l'aide de la syntaxe ${param} . Par défaut, tous les messages de test reçoivent une valeur path qui est précieuse dans les schémas imbriqués.

La fonction test est appelée avec la value actuelle . Pour des validations plus avancées, vous pouvez utiliser la signature alternative pour fournir plus d'options (voir ci-dessous) :

 let jimmySchema = string ( ) . test (
  'is-jimmy' ,
  '${path} is not Jimmy' ,
  ( value , context ) => value === 'jimmy' ,
) ;

// or make it async by returning a promise
let asyncJimmySchema = string ( )
  . label ( 'First name' )
  . test (
    'is-jimmy' ,
    ( { label } ) => ` ${ label } is not Jimmy` , // a message can also be a function
    async ( value , testContext ) =>
      ( await fetch ( '/is-jimmy/' + value ) ) . responseText === 'true' ,
  ) ;

await schema . isValid ( 'jimmy' ) ; // => true
await schema . isValid ( 'john' ) ; // => false

Les fonctions de test sont appelées avec une valeur de contexte spéciale, comme deuxième argument, qui expose des métadonnées et des fonctions utiles. Pour les fonctions non fléchées, le contexte de test est également défini comme la fonction this . Attention, si vous y accédez via this cela ne fonctionnera pas en fonction flèche.

testContext.path : le chemin de chaîne de la validation en cours
testContext.schema : l'objet de schéma résolu sur lequel le test est exécuté.
testContext.options : l'objet options avec lequel validate() ou isValid() a été appelé
testContext.parent : dans le cas d'un schéma imbriqué, c'est la valeur de l'objet parent
testContext.originalValue : la valeur d'origine testée
testContext.createError(Object: { path: String, message: String, params: Object }) : crée et renvoie une erreur de validation. Utile pour définir dynamiquement le path , params ou, plus probablement, le message d'erreur. Si l'une ou l'autre option est omise, elle utilisera le chemin actuel ou le message par défaut.

`Schema.test(options: object): Schema`

test(..) signature. options est un objet contenant certaines des options suivantes :

 Options = {
  // unique name identifying the test
  name : string ;
  // test function, determines schema validity
  test: ( value : any ) => boolean ;
  // the validation error message
  message: string ;
  // values passed to message for interpolation
  params: ? object ;
  // mark the test as exclusive, meaning only one test of the same name can be active at once
  exclusive: boolean = false ;
}

Dans le cas du mélange de tests exclusifs et non exclusifs, la logique suivante est utilisée. Si un test non exclusif est ajouté à un schéma avec un test exclusif du même nom, le test exclusif est supprimé et d'autres tests du même nom seront empilés.

Si un test exclusif est ajouté à un schéma avec des tests non exclusifs du même nom, les tests précédents sont supprimés et les autres tests du même nom se remplaceront.

 let max = 64 ;
let schema = yup . string ( ) . test ( {
  name : 'max' ,
  exclusive : true ,
  params : { max } ,
  message : '${path} must be less than ${max} characters' ,
  test : ( value ) => value == null || value . length <= max ,
} ) ;

`Schema.transform((currentValue: any, originalValue: any) => any): Schema`

Ajoute une transformation à la chaîne de transformation. Les transformations sont au cœur du processus de conversion, les transformations par défaut pour chaque type contraignent les valeurs au type spécifique (comme vérifié par isType() ). les transformations sont exécutées avant les validations et appliquées uniquement lorsque le schéma n'est pas marqué comme strict (valeur par défaut). Certains types ont intégré des transformations.

Les transformations sont utiles pour modifier arbitrairement la façon dont l'objet est converti, cependant, vous devez faire attention à ne pas muter la valeur transmise. Les transformations sont exécutées séquentiellement afin que chaque value représente l'état actuel de la distribution, vous pouvez utiliser le paramètre originalValue si vous devez travailler sur la valeur initiale brute.

 let schema = string ( ) . transform ( ( value , originalValue ) => {
  return this . isType ( value ) && value !== null ? value . toUpperCase ( ) : value ;
} ) ;

schema . cast ( 'jimmy' ) ; // => 'JIMMY'

Chaque type gérera la coercition de base des valeurs vers le type qui vous convient, mais vous souhaiterez peut-être parfois ajuster ou affiner le comportement par défaut. Par exemple, si vous souhaitez utiliser une stratégie d'analyse de date différente de celle par défaut, vous pouvez le faire avec une transformation.

 module . exports = function ( formats = 'MMM dd, yyyy' ) {
  return date ( ) . transform ( ( value , originalValue , context ) => {
    // check to see if the previous transform already parsed the date
    if ( context . isType ( value ) ) return value ;

    // the default coercion failed so let's try it with Moment.js instead
    value = Moment ( originalValue , formats ) ;

    // if it's valid return the date object, otherwise return an `InvalidDate`
    return value . isValid ( ) ? value . toDate ( ) : new Date ( '' ) ;
  } ) ;
} ;

mixte

Crée un schéma qui correspond à tous les types, ou uniquement à ceux que vous configurez. Hérite du Schema . Les types mixtes extends {} par défaut au lieu de any ou unknown . En effet, dans TypeScript {} signifie tout ce qui n'est pas null ou undefined et qui est traité distinctement.

 import { mixed , InferType } from 'yup' ;

let schema = mixed ( ) . nullable ( ) ;

schema . validateSync ( 'string' ) ; // 'string';

schema . validateSync ( 1 ) ; // 1;

schema . validateSync ( new Date ( ) ) ; // Date;

InferType < typeof schema > ; // {} | undefined

InferType < typeof schema . nullable ( ) . defined ( ) > ; // {} | null

Les types personnalisés peuvent être implémentés en passant une fonction check de type. Cela réduira également le type TypeScript pour le schéma.

 import { mixed , InferType } from 'yup' ;

let objectIdSchema = yup
  . mixed ( ( input ) : input is ObjectId => input instanceof ObjectId )
  . transform ( ( value : any , input , ctx ) => {
    if ( ctx . isType ( value ) ) return value ;
    return new ObjectId ( value ) ;
  } ) ;

await objectIdSchema . validate ( ObjectId ( '507f1f77bcf86cd799439011' ) ) ; // ObjectId("507f1f77bcf86cd799439011")

await objectIdSchema . validate ( '507f1f77bcf86cd799439011' ) ; // ObjectId("507f1f77bcf86cd799439011")

InferType < typeof objectIdSchema > ; // ObjectId

chaîne

Définissez un schéma de chaîne. Hérite du Schema .

 let schema = yup . string ( ) ;

await schema . isValid ( 'hello' ) ; // => true

Par défaut, la logique cast de string consiste à appeler toString sur la valeur si elle existe.

les valeurs vides ne sont pas contraintes (utilisez ensure() pour contraindre les valeurs vides à des chaînes vides).

Les conversions échouées renvoient la valeur d’entrée.

`string.required(message?: string | function): Schema`

Identique au schéma mixed() requis, sauf que les chaînes vides sont également considérées comme des valeurs « manquantes ».

`string.length(limit: number | Ref, message?: string | function): Schema`

Définissez une longueur requise pour la valeur de chaîne. L'interpolation ${length} peut être utilisée dans l'argument message

`string.min(limit: number | Ref, message?: string | function): Schema`

Définissez une limite de longueur minimale pour la valeur de chaîne. L'interpolation ${min} peut être utilisée dans l'argument message

`string.max(limit: number | Ref, message?: string | function): Schema`

Définissez une limite de longueur maximale pour la valeur de chaîne. L'interpolation ${max} peut être utilisée dans l'argument message

`string.matches(regex: Regex, message?: string | function): Schema`

Fournissez une regex arbitraire pour faire correspondre la valeur.

 let schema = string ( ) . matches ( / (hi|bye) / ) ;

await schema . isValid ( 'hi' ) ; // => true
await schema . isValid ( 'nope' ) ; // => false

`string.matches(regex: Regex, options: { message: string, excludeEmptyString: bool }): Schema`

Une signature alternative pour string.matches avec un objet options. excludeEmptyString , lorsqu'il est vrai, court-circuite le test d'expression régulière lorsque la valeur est une chaîne vide, ce qui permet d'éviter plus facilement de ne rien correspondre sans compliquer l'expression régulière.

 let schema = string ( ) . matches ( / (hi|bye) / , { excludeEmptyString : true } ) ;

await schema . isValid ( '' ) ; // => true

`string.email(message?: string | function): Schema`

Valide la valeur en tant qu'adresse e-mail en utilisant la même expression régulière définie par la spécification HTML.

ATTENTION : La validation des adresses e-mail est presque impossible avec un seul code. Différents clients et serveurs acceptent différentes choses et beaucoup divergent des différentes spécifications définissant les e-mails « valides ». Le SEUL véritable moyen de valider une adresse e-mail est de lui envoyer un e-mail de vérification et de vérifier que l'utilisateur l'a bien reçu. Dans cet esprit, yup choisit une expression régulière relativement simple qui ne couvre pas tous les cas, mais s'aligne sur le comportement de validation des entrées du navigateur, car les formulaires HTML sont un cas d'utilisation courant pour yup.

Si vous avez des besoins plus spécifiques, veuillez remplacer la méthode email par votre propre logique ou regex :

 yup . addMethod ( yup . string , 'email' , function validateEmail ( message ) {
  return this . matches ( myEmailRegex , {
    message ,
    name : 'email' ,
    excludeEmptyString : true ,
  } ) ;
} ) ;

`string.url(message?: string | function): Schema`

Valide la valeur en tant qu'URL valide via une expression régulière.

`string.uuid(message?: string | function): Schema`

Valide la valeur en tant qu'UUID valide via une expression régulière.

`string.datetime(options?: {message?: string | function, allowOffset?: boolean, precision?: number})`

Valide la valeur en tant que datetime ISO via une regex. La valeur par défaut est la validation UTC ; les décalages de fuseau horaire ne sont pas autorisés (voir options.allowOffset ).

Contrairement à .date() , datetime ne convertira pas la chaîne en objet Date . datetime offre également une plus grande personnalisation du format requis de la chaîne datetime que date .

options.allowOffset : Autoriser un décalage de fuseau horaire. False nécessite le fuseau horaire UTC « Z ». (par défaut : false) options.precision : Exige une certaine précision inférieure à la seconde sur la date. (par défaut : null -- toute (ou aucune) précision inférieure à la seconde)

`string.datetime(message?: string | function)`

Une signature alternative pour string.datetime qui peut être utilisée lorsque vous n'avez pas besoin de transmettre des options autres que message .

`string.ensure(): Schema`

Transforme les valeurs undefined et null en une chaîne vide tout en définissant la default sur une chaîne vide.

`string.trim(message?: string | function): Schema`

Transforme les valeurs de chaîne en supprimant les espaces de début et de fin. Si strict() est défini, cela validera uniquement que la valeur est réduite.

`string.lowercase(message?: string | function): Schema`

Transforme la valeur de la chaîne en minuscules. Si strict() est défini, cela validera uniquement que la valeur est en minuscules.

`string.uppercase(message?: string | function): Schema`

Transforme la valeur de la chaîne en majuscule. Si strict() est défini, cela validera uniquement que la valeur est en majuscule.

nombre

Définir un schéma numérique. Hérite du Schema .

 let schema = yup . number ( ) ;

await schema . isValid ( 10 ) ; // => true

La logique cast par défaut du number est : parseFloat .

Les lancers échoués renvoient NaN .

`number.min(limit: number | Ref, message?: string | function): Schema`

Définissez la valeur minimale autorisée. L'interpolation ${min} peut être utilisée dans l'argument message .

`number.max(limit: number | Ref, message?: string | function): Schema`

Définissez la valeur maximale autorisée. L'interpolation ${max} peut être utilisée dans l'argument message .

`number.lessThan(max: number | Ref, message?: string | function): Schema`

La valeur doit être inférieure à max . L'interpolation ${less} peut être utilisée dans l'argument message .

`number.moreThan(min: number | Ref, message?: string | function): Schema`

La valeur doit être strictement supérieure à min . L'interpolation ${more} peut être utilisée dans l'argument message .

`number.positive(message?: string | function): Schema`

La valeur doit être un nombre positif.

`number.negative(message?: string | function): Schema`

La valeur doit être un nombre négatif.

`number.integer(message?: string | function): Schema`

Valide qu'un nombre est un entier.

`number.truncate(): Schema`

Transformation qui contraint la valeur à un nombre entier en supprimant les chiffres à droite du point décimal.

`number.round(type: 'floor' | 'ceil' | 'trunc' | 'round' = 'round'): Schema`

Ajuste la valeur via la méthode Math spécifiée (par défaut « arrondi »).

booléen

Définissez un schéma booléen. Hérite du Schema .

 let schema = yup . boolean ( ) ;

await schema . isValid ( true ) ; // => true

date

Définissez un schéma Date. Par défaut, les chaînes de date ISO seront analysées correctement. Pour des options d'analyse plus robustes, consultez les types de schéma d'extension à la fin du fichier Lisez-moi. Hérite du Schema .

 let schema = yup . date ( ) ;

await schema . isValid ( new Date ( ) ) ; // => true

La logique cast par défaut de date consiste à transmettre la valeur au constructeur Date . À défaut, il tentera d'analyser la date en tant que chaîne de date ISO.

Si vous souhaitez que les chaînes ISO ne soient pas converties en objet Date , utilisez plutôt .datetime() .

Les conversions échouées renvoient une date non valide.

`date.min(limit: Date | string | Ref, message?: string | function): Schema`

Définissez la date minimale autorisée. Lorsqu'une chaîne est fournie, elle tentera d'abord d'effectuer une conversion en date et d'utiliser le résultat comme limite.

`date.max(limit: Date | string | Ref, message?: string | function): Schema`

Définissez la date maximale autorisée. Lorsqu'une chaîne est fournie, elle tentera d'abord d'être convertie en une date et d'utiliser le résultat comme limite.

tableau

Définissez un schéma de tableau. Les tableaux peuvent être saisis ou non. Lors de la spécification du type d'élément, cast et isValid s'appliqueront également aux éléments. Les options transmises à isValid sont également transmises aux schémas enfants.

Hérite du Schema .

 let schema = yup . array ( ) . of ( yup . number ( ) . min ( 2 ) ) ;

await schema . isValid ( [ 2 , 3 ] ) ; // => true
await schema . isValid ( [ 1 , - 24 ] ) ; // => false

schema . cast ( [ '2' , '3' ] ) ; // => [2, 3]

Vous pouvez également transmettre un schéma de sous-type au constructeur de tableau pour plus de commodité.

 array ( ) . of ( yup . number ( ) ) ;
// or
array ( yup . number ( ) ) ;

Les tableaux n'ont pas de comportement de conversion par défaut.

`array.of(type: Schema): this`

Spécifiez le schéma des éléments du tableau. of() est facultatif et lorsqu'il est omis, le schéma du tableau ne validera pas son contenu.

`array.json(): this`

Essayez d'analyser les valeurs de chaîne d'entrée au format JSON à l'aide de JSON.parse .

`array.length(length: number | Ref, message?: string | function): this`

Définissez une exigence de longueur spécifique pour le tableau. L'interpolation ${length} peut être utilisée dans l'argument message .

`array.min(limit: number | Ref, message?: string | function): this`

Définissez une limite de longueur minimale pour le tableau. L'interpolation ${min} peut être utilisée dans l'argument message .

`array.max(limit: number | Ref, message?: string | function): this`

Définissez une limite de longueur maximale pour le tableau. L'interpolation ${max} peut être utilisée dans l'argument message .

`array.ensure(): this`

Garantit que la valeur est un tableau, en définissant la valeur par défaut sur [] et en transformant également les valeurs null et undefined en un tableau vide. Toute valeur non vide et non-tableau sera enveloppée dans un tableau.

 array ( ) . ensure ( ) . cast ( null ) ; // => []
array ( ) . ensure ( ) . cast ( 1 ) ; // => [1]
array ( ) . ensure ( ) . cast ( [ 1 ] ) ; // => [1]

`array.compact(rejector: (value) => boolean): Schema`

Supprime les valeurs fausses du tableau. Fournir une fonction de rejet vous permet de spécifier vous-même les critères de rejet.

 array ( ) . compact ( ) . cast ( [ '' , 1 , 0 , 4 , false , null ] ) ; // => [1, 4]

array ( )
  . compact ( function ( v ) {
    return v == null ;
  } )
  . cast ( [ '' , 1 , 0 , 4 , false , null ] ) ; // => ['', 1, 0, 4, false]

tuple

Les tuples sont des tableaux de longueur fixe dans lesquels chaque élément a un type distinct.

Hérite du Schema .

 import { tuple , string , number , InferType } from 'yup' ;

let schema = tuple ( [
  string ( ) . label ( 'name' ) ,
  number ( ) . label ( 'age' ) . positive ( ) . integer ( ) ,
] ) ;

await schema . validate ( [ 'James' , 3 ] ) ; // ['James', 3]

await schema . validate ( [ 'James' , - 24 ] ) ; // => ValidationError: age must be a positive number

InferType < typeof schema > // [string, number] | undefined

les tuples n'ont pas de comportement de conversion par défaut.

objet

Définissez un schéma d'objet. Les options transmises à isValid sont également transmises aux schémas enfants. Hérite du Schema .

 yup . object ( {
  name : string ( ) . required ( ) ,
  age : number ( ) . required ( ) . positive ( ) . integer ( ) ,
  email : string ( ) . email ( ) ,
  website : string ( ) . url ( ) ,
} ) ;

Le schéma d'objet n'a aucune transformation par défaut appliquée.

Valeurs par défaut du schéma d'objet

Le schéma d'objet est livré avec une valeur par défaut déjà définie, qui "construit" la forme de l'objet et définit les valeurs par défaut des champs :

 let schema = object ( {
  name : string ( ) . default ( '' ) ,
} ) ;

schema . default ( ) ; // -> { name: '' }

Cela peut être un peu surprenant, mais est généralement utile car cela permet à un schéma volumineux et imbriqué de créer des valeurs par défaut qui remplissent la forme entière et pas seulement l'objet racine. Il y a un piège ! cependant. Pour les schémas d'objets imbriqués qui sont facultatifs mais qui incluent des champs non facultatifs, cela peut échouer de manière inattendue :

 let schema = object ( {
  id : string ( ) . required ( ) ,
  names : object ( {
    first : string ( ) . required ( ) ,
  } ) ,
} ) ;

schema . isValid ( { id : 1 } ) ; // false! names.first is required

En effet, oui, convertit l'objet d'entrée avant d'exécuter la validation, ce qui produira :

{ id: '1', names: { first: undefined }}

Pendant la phase de validation, names existent et sont validés, trouvant names.first manquants. Si vous souhaitez éviter ce comportement, effectuez l'une des opérations suivantes :

Définissez la valeur par défaut imbriquée sur non défini : names.default(undefined)
marquez-le comme nullable et par défaut sur null : names.nullable().default(null)

`object.shape(fields: object, noSortEdges?: Array<[string, string]>): Schema`

Définissez les clés de l'objet et les schémas de ces clés.

Notez que vous pouvez chaîner la méthode shape , qui agit comme Object.assign .

 object ( {
  a : string ( ) ,
  b : number ( ) ,
} ) . shape ( {
  b : string ( ) ,
  c : number ( ) ,
} ) ;

serait exactement la même chose que :

 object ( {
  a : string ( ) ,
  b : string ( ) ,
  c : number ( ) ,
} ) ;

`object.json(): this`

Essayez d'analyser les valeurs de chaîne d'entrée au format JSON à l'aide de JSON.parse .

`object.concat(schemaB: ObjectSchema): ObjectSchema`

Crée un schéma d'objet, en appliquant tous les paramètres et champs du schemaB à la base, produisant ainsi un nouveau schéma. La forme de l'objet est fusionnée superficiellement avec les champs communs du schemaB qui ont priorité sur les champs de base.

`object.pick(keys: string[]): Schema`

Créez un nouveau schéma à partir d'un sous-ensemble des champs d'origine.

 let person = object ( {
  age : number ( ) . default ( 30 ) . required ( ) ,
  name : string ( ) . default ( 'pat' ) . required ( ) ,
  color : string ( ) . default ( 'red' ) . required ( ) ,
} ) ;

let nameAndAge = person . pick ( [ 'name' , 'age' ] ) ;
nameAndAge . getDefault ( ) ; // => { age: 30, name: 'pat'}

`object.omit(keys: string[]): Schema`

Créez un nouveau schéma avec les champs omis.

 let person = object ( {
  age : number ( ) . default ( 30 ) . required ( ) ,
  name : string ( ) . default ( 'pat' ) . required ( ) ,
  color : string ( ) . default ( 'red' ) . required ( ) ,
} ) ;

let nameAndAge = person . omit ( [ 'color' ] ) ;
nameAndAge . getDefault ( ) ; // => { age: 30, name: 'pat'}

`object.from(fromKey: string, toKey: string, alias: boolean = false): this`

Transforme la clé spécifiée en une nouvelle clé. Si alias est true , l'ancienne clé sera conservée.

 let schema = object ( {
  myProp : mixed ( ) ,
  Other : mixed ( ) ,
} )
  . from ( 'prop' , 'myProp' )
  . from ( 'other' , 'Other' , true ) ;

schema . cast ( { prop : 5 , other : 6 } ) ; // => { myProp: 5, other: 6, Other: 6 }

`object.noUnknown(onlyKnownKeys: boolean = true, message?: string | function): Schema`

Vérifiez que la valeur de l'objet contient uniquement les clés spécifiées dans shape , transmettez false comme premier argument pour désactiver la vérification. Restreindre les clés à connues active également l'option stripUnknown , lorsqu'elle n'est pas en mode strict.

`object.camelCase(): Schema`

Transforme toutes les clés d'objet en camelCase

`object.constantCase(): Schema`

Transforme toutes les clés d'objet en CONSTANT_CASE.

Développer

yup

Ouais

Commencer

Table des matières

Bases du schéma

Analyse : transformations

Validation : Tests

Erreurs de personnalisation

Composition et réutilisation

Intégration TypeScript

Valeurs par défaut du schéma

S'assurer qu'un schéma correspond à un type existant

Extension du schéma intégré avec de nouvelles méthodes

Configuration dactylographiée

Personnalisation des messages d'erreur

localisation et i18n

API

yup

reach(schema: Schema, path: string, value?: object, context?: object): Schema

addMethod(schemaType: Schema, name: string, method: ()=> Schema): void

ref(path: string, options: { contextPrefix: string }): Ref

lazy((value: any) => Schema): Lazy

ValidationError(errors: string | Array<string>, value: any, path: string)

Schema

Schema.clone(): Schema

Schema.label(label: string): Schema

Schema.meta(metadata: SchemaMetadata): Schema

Schema.describe(options?: ResolveOptions): SchemaDescription

Schema.concat(schema: Schema): Schema

Schema.validate(value: any, options?: object): Promise<InferType<Schema>, ValidationError>

Schema.validateSync(value: any, options?: object): InferType<Schema>

Schema.validateAt(path: string, value: any, options?: object): Promise<InferType<Schema>, ValidationError>

Schema.validateSyncAt(path: string, value: any, options?: object): InferType<Schema>

Schema.isValid(value: any, options?: object): Promise<boolean>

Schema.isValidSync(value: any, options?: object): boolean

Schema.cast(value: any, options = {}): InferType<Schema>

Schema.isType(value: any): value is InferType<Schema>

Schema.strict(enabled: boolean = false): Schema

Schema.strip(enabled: boolean = true): Schema

Schema.withMutation(builder: (current: Schema) => void): void

Schema.default(value: any): Schema

Schema.getDefault(options?: object): Any

Schema.nullable(message?: string | function): Schema

Schema.nonNullable(message?: string | function): Schema

Schema.defined(): Schema

Schema.optional(): Schema

Schema.required(message?: string | function): Schema

Schema.notRequired(): Schema

Schema.typeError(message: string): Schema

Schema.oneOf(arrayOfValues: Array<any>, message?: string | function): Schema : equals

Schema.notOneOf(arrayOfValues: Array<any>, message?: string | function)

Schema.when(keys: string | string[], builder: object | (values: any[], schema) => Schema): Schema

Schema.test(name: string, message: string | function | any, test: function): Schema

Schema.test(options: object): Schema

Schema.transform((currentValue: any, originalValue: any) => any): Schema