Validation And Defensive Programming - Learning Module

Loading content...

0/246

Assertions vs Validation

Two Tools, Two Purposes

Assertions and validation are frequently confused, sometimes used interchangeably, and often applied incorrectly. This confusion leads to systems that are either brittle (assertions everywhere) or insecure (validation missing where it matters). Understanding the fundamental distinction between these concepts is essential for building robust software.

Validation checks external input—data that enters your system from users, APIs, files, or other systems. Validation failures are expected and represent normal error conditions that must be handled gracefully.

Assertions verify internal invariants—conditions that should always be true if your program logic is correct. Assertion failures indicate bugs in your code, not invalid input.

The Critical Distinction

Never use assertions for validation. Assertions can be disabled in production, leaving your system unprotected. Never use validation for internal invariants—it adds unnecessary overhead and obscures programmer errors. Each tool has its domain; mixing them creates fragile, confusing code.

Understanding Validation

Validation is the process of checking whether external input conforms to expected constraints. Key characteristics of validation:

Invalid input is expected. Users make typos. APIs receive malformed requests. Files get corrupted. Validation failures are normal operations, not exceptional circumstances.

Validation must always run. In development, testing, staging, and production—validation code always executes. It cannot be compiled out or disabled.

Validation produces user-facing errors. When validation fails, the system must communicate what went wrong in terms the caller can understand and act upon.

Validation is part of the contract. Your API promises to validate input and provide meaningful errors. This is behavior clients depend on.

validation-examples.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
// VALIDATION: Checking external input
class UserRegistrationService {
    async register(request: RegistrationRequest): Promise<Result<User, RegistrationError>> {
        // These are validations - external input, expected to fail
        if (!isValidEmail(request.email)) {
            return Result.failure(RegistrationError.invalidEmail(request.email));
        }
        
        if (request.password.length < 8) {
            return Result.failure(RegistrationError.passwordTooShort());
        }
        
        if (await this.userRepo.existsByEmail(request.email)) {
            return Result.failure(RegistrationError.emailAlreadyExists(request.email));
        }
        
        // Validation passed - proceed with registration
        const user = await this.createUser(request);
        return Result.success(user);
    }
}
 
// Validation in Value Objects - enforcing domain constraints
class EmailAddress {
    private constructor(private readonly value: string) {}
    
    static create(value: string): Result<EmailAddress, ValidationError> {
        // Validation: external input must conform to email format
        if (!value || value.trim().length === 0) {
            return Result.failure(ValidationError.required('email'));
        }
        
        if (!EMAIL_REGEX.test(value)) {
            return Result.failure(ValidationError.invalidFormat('email', value));
        }
        
        if (value.length > 254) {
            return Result.failure(ValidationError.tooLong('email', 254));
        }
        
        return Result.success(new EmailAddress(value.toLowerCase()));
    }
    
    toString(): string {
        return this.value;
    }
}

Understanding Assertions

Assertions verify internal invariants—conditions that must be true if the program is correct. Key characteristics:

Assertion failures indicate bugs. If an assertion fails, there's a defect in your code or its assumptions. This is never expected in a correctly functioning system.

Assertions may be disabled. In many languages, assertions can be compiled out for production performance. Your program must be correct without them.

Assertions serve as executable documentation. They communicate programmer intent and invariants to future maintainers.

Assertions fail loudly. When an assertion fails, the program should halt or throw an unrecoverable error. Continuing with violated invariants leads to undefined behavior.

assertion-examples.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
// ASSERTIONS: Verifying internal invariants
class BinarySearchTree<T> {
    insert(value: T): void {
        this.root = this.insertNode(this.root, value);
        
        // Assertion: BST property must hold after insertion
        // If this fails, there's a bug in insertNode()
        console.assert(this.isBinarySearchTree(), 
            'BST invariant violated after insert');
    }
    
    private insertNode(node: TreeNode<T> | null, value: T): TreeNode<T> {
        if (node === null) {
            return new TreeNode(value);
        }
        
        // Assertion: node should never be undefined at this point
        // Our algorithm guarantees this
        console.assert(node !== undefined, 
            'Internal error: node became undefined');
        
        if (this.comparator(value, node.value) < 0) {
            node.left = this.insertNode(node.left, value);
        } else {
            node.right = this.insertNode(node.right, value);
        }
        
        return node;
    }
}
 
// Assertion in state machine - enforcing valid transitions
class OrderStateMachine {
    private state: OrderState = OrderState.Created;
    
    ship(): void {
        // Assertion: This method should only be called when state allows shipping
        // The caller is responsible for checking canShip() first
        console.assert(
            this.state === OrderState.Confirmed,
            `Bug: ship() called in invalid state: ${this.state}`
        );
        
        this.state = OrderState.Shipped;
        this.emitEvent(new OrderShippedEvent(this.orderId));
    }
    
    // Public method for callers to check before calling ship()
    canShip(): boolean {
        return this.state === OrderState.Confirmed;
    }
}
 
// Custom assertion function with rich diagnostics
function assert(condition: boolean, message: string, context?: object): asserts condition {
    if (!condition) {
        const error = new AssertionError(message);
        if (context) {
            console.error('Assertion context:', context);
        }
        console.error(error.stack);
        throw error;
    }
}
 
// Usage
function divideArrayIntoChunks<T>(array: T[], chunkSize: number): T[][] {
    // Assertion: chunk size comes from our algorithm, not user input
    assert(chunkSize > 0, 'chunkSize must be positive', { chunkSize, arrayLength: array.length });
    
    const chunks: T[][] = [];
    for (let i = 0; i < array.length; i += chunkSize) {
        chunks.push(array.slice(i, i + chunkSize));
    }
    
    // Post-condition assertion: verify our algorithm produced correct output
    assert(
        chunks.flat().length === array.length,
        'Chunking lost elements',
        { original: array.length, chunked: chunks.flat().length }
    );
    
    return chunks;
}

The Decision Framework

When deciding between assertion and validation, ask these questions:

Assertion vs Validation Decision Matrix
Question	Validation	Assertion
Where does the data come from?	External sources (users, APIs, files)	Internal computation, trusted code
Is failure expected?	Yes, regularly	No, indicates a bug
What action on failure?	Graceful error response	Halt or crash
Who is responsible for correct data?	The caller/external system	Your own code
Can it be disabled?	Never	Potentially in production
What does failure message target?	User/API client	Developer debugging

Use Validation When

•Data comes from outside your code
•User input from forms, APIs, etc.
•Configuration files or environment
•External service responses
•Data that could reasonably be invalid

Use Assertions When

•Verifying algorithm correctness
•Checking post-conditions after computation
•Enforcing class invariants
•Documenting impossible cases
•Detecting unreachable code paths

Common Antipatterns

Misusing assertions and validation creates subtle but dangerous problems.

antipatterns.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
// ❌ ANTIPATTERN 1: Using assertions for validation
// DANGEROUS: Assertions may be disabled in production!
function processPayment(amount: number, cardNumber: string): void {
    // If assertions are disabled, this check disappears
    console.assert(amount > 0, 'Amount must be positive');
    console.assert(cardNumber.length === 16, 'Invalid card number');
    
    // Attacker could submit amount: -1000 (credit instead of charge)
    chargeCard(cardNumber, amount);
}
 
// ✅ CORRECT: Use validation for external input
function processPaymentSafe(amount: number, cardNumber: string): Result<Payment, PaymentError> {
    if (amount <= 0) {
        return Result.failure(PaymentError.invalidAmount(amount));
    }
    if (!isValidCardNumber(cardNumber)) {
        return Result.failure(PaymentError.invalidCardNumber());
    }
    return chargeCard(cardNumber, amount);
}
 
// ❌ ANTIPATTERN 2: Using validation for internal invariants
// WASTEFUL: Adds overhead to check conditions that should always be true
class Stack<T> {
    private items: T[] = [];
    
    pop(): T | null {
        // Validation where assertion belongs - size() is internal state
        if (this.items.length === 0) {
            // This validation runs every time, even when we know stack isn't empty
            return null;
        }
        return this.items.pop()!;
    }
}
 
// ✅ CORRECT: API provides checking, implementation uses assertions
class StackCorrect<T> {
    private items: T[] = [];
    
    isEmpty(): boolean {
        return this.items.length === 0;
    }
    
    pop(): T {
        // Caller is responsible for checking isEmpty() first
        // Assertion catches bugs where callers forget to check
        console.assert(!this.isEmpty(), 'pop() called on empty stack');
        return this.items.pop()!;
    }
    
    // Or provide safe alternative that uses validation
    tryPop(): T | null {
        if (this.isEmpty()) return null;
        return this.items.pop()!;
    }
}
 
// ❌ ANTIPATTERN 3: Silent assertion (assertion with side effects or recovery)
function badAssertion(data: Data): void {
    if (!isValid(data)) {
        console.log('Warning: invalid data, using default');
        data = getDefaultData(); // Silently "recovering" from invariant violation
    }
    process(data);
}
 
// ✅ CORRECT: Assertions should fail loudly
function correctAssertion(data: Data): void {
    assert(isValid(data), 'Internal error: received invalid data');
    process(data);
}

Security Implications

Using assertions for input validation is a security vulnerability. When assertions are disabled in production (common for performance), all those 'checks' vanish. Attackers can then submit malicious input that bypasses your non-existent validation.

Assertions in Production Systems

Whether to keep assertions enabled in production is a nuanced decision. There are two schools of thought:

Disable in Production: Traditional approach. Assertions are development aids, removed for production performance. This assumes thorough testing catches all bugs. Risk: bugs slip through, assertions can't catch them in production.

Keep Enabled (Fail-Fast): Modern approach. Assertion failures in production are better than undefined behavior from violated invariants. A crash with clear diagnostics beats silent data corruption. This aligns with the fail-fast principle we'll explore next.

production-assertions.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
// Production-safe assertion that never gets disabled
// but has configurable behavior
class ProductionAssert {
    static invariant(
        condition: boolean,
        message: string,
        context?: Record<string, unknown>
    ): asserts condition {
        if (!condition) {
            const error = new InvariantViolationError(message, context);
            
            // Always log - this is a bug, we need visibility
            logger.error('Invariant violation', {
                message,
                context,
                stack: error.stack,
            });
            
            // Alert monitoring systems
            metrics.increment('invariant_violations', { message });
            
            // In production, we might choose to:
            // Option A: Throw (fail-fast) - recommended for critical paths
            // Option B: Report to error tracking and attempt recovery
            
            if (config.isProduction && config.gracefulDegradation) {
                // Report but don't crash - use for non-critical paths
                errorTracking.captureException(error);
            } else {
                throw error;
            }
        }
    }
}
 
// Usage
function calculateDiscount(order: Order, rules: DiscountRule[]): Money {
    // This should never happen if our rule engine is correct
    ProductionAssert.invariant(
        rules.length > 0,
        'Discount calculation invoked with no rules',
        { orderId: order.id, ruleCount: rules.length }
    );
    
    const discount = rules.reduce(
        (sum, rule) => sum.add(rule.apply(order)),
        Money.zero()
    );
    
    // Post-condition: discount cannot exceed order total
    ProductionAssert.invariant(
        discount.isLessThanOrEqual(order.total),
        'Discount exceeds order total',
        { discount: discount.toString(), total: order.total.toString() }
    );
    
    return discount;
}

Summary: Assertions vs Validation

Key Takeaways

•Validation is for external input — It checks data from users, APIs, and external systems. Failures are expected and handled gracefully.
•Assertions are for internal invariants — They verify your code's correctness. Failures indicate bugs and should crash loudly.
•Never use assertions for security — Assertions may be disabled in production. Security-critical checks must use validation.
•Assertions serve as documentation — They communicate invariants and programmer intent to maintainers.
•Consider keeping assertions in production — Fail-fast with diagnostics beats silent corruption from violated invariants.

Page Complete

You now understand the crucial distinction between assertions and validation, and when to apply each. Next, we'll explore the fail-fast principle—a foundational philosophy that guides how systems should respond when things go wrong.