Yup: Schema Builder for Runtime Validation

WHY IT EXISTS: Runtime data is untrusted. APIs return strings where numbers are expected, users submit empty fields, and configuration files drift out of shape. Static types catch none of this because they evaporate at compile time. Yup was built to close that gap by giving JavaScript a declarative, chainable way to enforce structure, coerce types, and produce rich errors at runtime.

THE MENTAL MODEL: Think of a Yup schema as a customs checkpoint for your data. Every field passes through two lanes: a parsing lane that cleans and converts the input, and an assertion lane that runs tests against the cleaned value. You describe the rules once, and Yup handles both the transformation and the interrogation. TypeScript types can then be inferred from that same description, so the contract you enforce at runtime is the contract you see in the editor.

HOW IT WORKS: You import builders like object, string, and number, then chain methods to compose constraints. Methods like required, email, positive, and integer are assertions that throw ValidationError when they fail. Methods like default and cast are transforms that mutate the value before or instead of testing it. Calling validate runs both transforms and assertions, while calling cast only runs transforms. Passing strict true to validate skips coercion entirely and rejects mismatched types immediately.

WHEN TO USE IT: Reach for Yup when you need shared validation between client and server, when you want TypeScript types derived from runtime rules rather than duplicated by hand, or when you need async validation such as checking a username against a database. It is especially useful when you face complex, interdependent validations where the rules for one field change based on another value.

WHEN NOT TO USE IT: Avoid Yup for purely compile-time type checking; it adds bundle size and runtime overhead that TypeScript alone handles for free. Do not use it when you only need simple, one-off checks where a handful of if statements is cleaner than importing a schema builder. If your environment is extremely sensitive to package size, a lighter alternative may be preferable.

ONE CANONICAL EXAMPLE: A user registration form needs a name string, a positive integer age, an optional email, and a creation date that defaults to now. The schema chains string with required, number with required positive integer, string with email, and date with a default of new Date. Feeding an object with name jimmy, age 24 as a string, and createdOn as an ISO string into cast produces a number age and a Date object because the strings are coerced. Running the same object through validate would also assert that the email format is valid and that no required fields are missing.