## Why Type-Safe Validators Matter in Modern Applications Most form validation failures in production stem from a disconnect between what developers assume about data structure and what actually arrives at runtime. Teams write validators that accept `any`, return boolean values without context, and chain logic that TypeScript cannot verify. The result: runtime errors that type checking should have prevented. Type-safe validators solve this by making validation rules part of your type system. When a validator runs, TypeScript knows exactly what shape the data takes if validation succeeds. This matters because form validation sits at the boundary between user input and application logic—the exact place where type safety delivers maximum value. The distinction is critical. A validator that returns `boolean` tells you nothing about the validated data's shape. A validator that narrows types through predicates gives you compile-time guarantees about what operations are safe downstream. This difference eliminates entire categories of bugs before code reaches production. ## Building a Generic Validator Type System The foundation of type-safe validation is a result type that captures both success and failure states with their associated data. Developers need a structure that TypeScript can narrow discriminately. ```typescript type ValidationResult = | { success: true; data: T } | { success: false; errors: ValidationError[] }; interface ValidationError { field: string; message: string; code: string; } type Validator = ( value: TInput ) => ValidationResult; ``` This type system makes validation results explicit. When `success` is `true`, TypeScript knows `data` exists with type `TOutput`. When `success` is `false`, TypeScript knows `errors` exists. The generic parameters allow validators to transform input types—a string validator can output a branded type or a more specific union. The validator function signature separates input and output types deliberately. Most validators preserve the input type, but transforming validators (parsing numbers from strings, normalizing data) need different input and output types. This flexibility matters in real applications where validation often includes coercion. ```mermaid %% alt: Type-safe validator architecture with discriminated union results flowchart TD A[Input: unknown] --> B{Validator Function} B --> C[ValidationResult] C --> D{success: true} C --> E{success: false} D --> F[data: TOutput] E --> G[errors: ValidationError[]] F --> H[Type Narrowed
Safe Operations] G --> I[Error Handling
User Feedback] ``` The diagram shows how validators narrow types through discriminated unions. Once code checks the `success` property, TypeScript automatically narrows to the correct branch. This pattern eliminates the need for type assertions and makes error handling explicit. ![TypeScript validator type system](https://emzvxuokuqzdkmyrzfut.supabase.co/storage/v1/object/public/blog/posts/typescript-form-validators-custom/content-1.jpg) ## Creating Reusable Field Validators with Type Guards Field validators need to be composable and reusable across forms. The pattern that scales best combines type predicates with the result type system. ```typescript function createStringValidator( minLength?: number, maxLength?: number ): Validator { return (value: unknown): ValidationResult => { if (typeof value !== 'string') { return { success: false, errors: [{ field: 'value', message: 'Must be a string', code: 'INVALID_TYPE' }] }; } const errors: ValidationError[] = []; if (minLength !== undefined && value.length < minLength) { errors.push({ field: 'value', message: `Must be at least ${minLength} characters`, code: 'MIN_LENGTH' }); } if (maxLength !== undefined && value.length > maxLength) { errors.push({ field: 'value', message: `Must be no more than ${maxLength} characters`, code: 'MAX_LENGTH' }); } if (errors.length > 0) { return { success: false, errors }; } return { success: true, data: value }; }; } // Email validator that outputs a branded type type Email = string & { readonly __brand: 'Email' }; function emailValidator(value: unknown): ValidationResult { const stringResult = createStringValidator()(value); if (!stringResult.success) { return stringResult; } const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; if (!emailPattern.test(stringResult.data)) { return { success: false, errors: [{ field: 'value', message: 'Must be a valid email address', code: 'INVALID_EMAIL' }] }; } return { success: true, data: stringResult.data as Email }; } ``` This approach creates validators that TypeScript can track through the type system. The `createStringValidator` factory takes unknown input and outputs a validated string. The email validator builds on this foundation and narrows further to a branded type. Branded types prevent accidentally passing regular strings where emails are required. The implication here is that type safety compounds as validators compose. Each layer adds more specific guarantees without losing the validation context from previous layers. ## Composing Validators: Chain and Combine Patterns Complex forms require combining multiple validation rules. The pattern that maintains type safety is explicit composition through combinators. ```typescript function chain( first: Validator, second: Validator ): Validator { return (value: T): ValidationResult => { const firstResult = first(value); if (!firstResult.success) { return firstResult; } return second(firstResult.data); }; } function combine( ...validators: Validator[] ): Validator { return (value: T): ValidationResult => { const allErrors: ValidationError[] = []; for (const validator of validators) { const result = validator(value); if (!result.success) { allErrors.push(...result.errors); } } if (allErrors.length > 0) { return { success: false, errors: allErrors }; } return { success: true, data: value }; }; } // Usage: chain transforms types sequentially const parseAndValidateAge = chain( createStringValidator(), (str): ValidationResult => { const num = parseInt(str, 10); if (isNaN(num)) { return { success: false, errors: [{ field: 'age', message: 'Must be a valid number', code: 'INVALID_NUMBER' }] }; } if (num < 0 || num > 120) { return { success: false, errors: [{ field: 'age', message: 'Must be between 0 and 120', code: 'OUT_OF_RANGE' }] }; } return { success: true, data: num }; } ); ``` The `chain` combinator passes successful results through a pipeline, transforming types at each step. The `combine` combinator runs all validators and collects errors, useful when multiple independent rules apply to the same field. TypeScript tracks the type transformations through the entire chain. ## Type-Safe Error Handling and Messages Validation errors need structure that supports internationalization and detailed feedback. The error type system should make it impossible to create malformed error messages. ```typescript const ErrorCodes = { REQUIRED: 'REQUIRED', INVALID_TYPE: 'INVALID_TYPE', MIN_LENGTH: 'MIN_LENGTH', MAX_LENGTH: 'MAX_LENGTH', INVALID_EMAIL: 'INVALID_EMAIL', OUT_OF_RANGE: 'OUT_OF_RANGE' } as const; type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes]; interface TypedValidationError { field: string; code: ErrorCode; params?: Record; } type ErrorMessages = Record) => string>; const defaultMessages: ErrorMessages = { REQUIRED: () => 'This field is required', INVALID_TYPE: (params) => `Expected ${params?.expected || 'valid type'}`, MIN_LENGTH: (params) => `Must be at least ${params?.min} characters`, MAX_LENGTH: (params) => `Must be no more than ${params?.max} characters`, INVALID_EMAIL: () => 'Must be a valid email address', OUT_OF_RANGE: (params) => `Must be between ${params?.min} and ${params?.max}` }; function formatError(error: TypedValidationError, messages = defaultMessages): string { const formatter = messages[error.code]; return formatter(error.params); } ``` This structure separates error codes from messages, making internationalization straightforward. The `params` object allows dynamic values in error messages while maintaining type safety. Teams can replace `defaultMessages` with localized versions without changing validation logic. ![Type-safe error handling in validators](https://emzvxuokuqzdkmyrzfut.supabase.co/storage/v1/object/public/blog/posts/typescript-form-validators-custom/content-2.jpg) ## Custom vs Library Validators: When to Build Your Own The decision between custom validators and libraries like Zod or Yup depends on specific application needs and team constraints. ```mermaid %% alt: Comparison of custom validators vs library-based validation approaches flowchart LR subgraph CustomValidators["Custom Validators"] A1[Full Type Control] --> A2[Zero Dependencies] A2 --> A3[Explicit Logic] A3 --> A4[Bundle Size: Minimal] end subgraph LibraryValidators["Library Validators"] B1[Rich Feature Set] --> B2[Community Support] B2 --> B3[Tested Patterns] B3 --> B4[Bundle Size: 10-50KB] end A4 --> C{Decision Point} B4 --> C C --> D[Use Custom:
Specific needs,
performance critical] C --> E[Use Library:
Complex schemas,
rapid development] ``` Custom validators make sense when applications need precise control over validation logic, minimal bundle size matters, or validation rules are domain-specific and stable. The patterns shown earlier provide full type safety with zero runtime dependencies. Teams that understand their validation requirements and rarely change them benefit from this approach. Library validators excel when schemas change frequently, applications need complex nested validation, or teams want battle-tested patterns. Libraries handle edge cases that custom code might miss. The tradeoff is bundle size and learning curve. In other words, libraries pay upfront cost for long-term flexibility. The failure mode here is adopting a library for simple validation that custom code handles better, or building custom validators for complex scenarios where libraries prevent bugs. Match the tool to the complexity. ## Advanced Patterns: Async Validators and Cross-Field Validation Production applications often need validators that check against external systems or compare multiple fields. These patterns extend the base validator type system. ```typescript type AsyncValidator = ( value: TInput ) => Promise>; function createAsyncEmailValidator( checkAvailability: (email: string) => Promise ): AsyncValidator { return async (value: unknown): Promise> => { const emailResult = emailValidator(value); if (!emailResult.success) { return emailResult; } const isAvailable = await checkAvailability(emailResult.data); if (!isAvailable) { return { success: false, errors: [{ field: 'email', message: 'Email address is already registered', code: 'EMAIL_TAKEN' }] }; } return emailResult; }; } // Cross-field validation for password confirmation interface PasswordFields { password: string; confirmPassword: string; } function passwordMatchValidator( fields: PasswordFields ): ValidationResult { if (fields.password !== fields.confirmPassword) { return { success: false, errors: [{ field: 'confirmPassword', message: 'Passwords must match', code: 'PASSWORD_MISMATCH' }] }; } return { success: true, data: fields }; } ``` Async validators maintain the same type safety as synchronous ones. The key difference is returning `Promise>` instead of `ValidationResult`. TypeScript tracks the async nature through the entire validation chain. Cross-field validators take multiple fields as input and validate relationships between them. This pattern keeps validation logic centralized rather than scattered across form components. The type system ensures all required fields exist before validation runs. ## Integration and Real-World Implementation Real applications need validators integrated into form state management. The pattern that maintains type safety throughout is a typed form schema. ```typescript interface RegistrationForm { username: string; email: Email; age: number; password: string; confirmPassword: string; } type FormValidators = { [K in keyof T]?: Validator; }; const registrationValidators: FormValidators = { username: chain( createStringValidator(3, 20), (str): ValidationResult => { if (!/^[a-zA-Z0-9_]+$/.test(str)) { return { success: false, errors: [{ field: 'username', message: 'Only letters, numbers, and underscores allowed', code: 'INVALID_FORMAT' }] }; } return { success: true, data: str }; } ), email: emailValidator, age: parseAndValidateAge }; function validateForm>( data: Record, validators: FormValidators ): ValidationResult { const errors: ValidationError[] = []; const validated: Partial = {}; for (const [field, validator] of Object.entries(validators)) { if (!validator) continue; const result = validator(data[field]); if (!result.success) { errors.push(...result.errors.map(err => ({ ...err, field }))); } else { validated[field as keyof T] = result.data; } } if (errors.length > 0) { return { success: false, errors }; } return { success: true, data: validated as T }; } ``` This integration pattern validates entire forms while maintaining field-level type safety. The `FormValidators` type maps each form field to its validator, ensuring validators output the correct types for each field. TypeScript verifies that all required fields have validators and that validator output types match form field types. The `validateForm` function processes all fields, collects errors, and returns a fully typed result. When validation succeeds, teams know the data matches the form schema exactly. This eliminates the type assertions and runtime checks that plague untyped validation. That covers the essential patterns for building type-safe form validators in TypeScript. Apply these in production and the difference will be immediate—fewer runtime errors, better developer experience, and validation logic that scales with application complexity.

Posts tagged “Forms”

Build Type-Safe Form Validators in TypeScript