Predictable Behavior — The Principle of Least… | OneNoughtOne

0/86

System Design (HLD)Principle of Least Astonishment

The Principle of Least Astonishment (POLA)

LevelIntermediate

Duration60 mins

TopicPrinciple of Least Astonishment

2 / 4

Predictable Behavior

The Architecture of Trust

When developers work with code they trust, they move fast. They don't second-guess method calls. They don't write defensive null checks around every operation. They don't add logging statements to verify that things happened. They simply write what they mean and trust the system to do what it says. Predictable behavior is the foundation of this trust. It's not enough for code to do the right thing—it must do the right thing consistently, reliably, and in a way developers can anticipate . This page examines the concrete properties and patterns that make behavior predictable. These aren't abstract ideals; they're practical engineering techniques that, when applied systematically, transform code from mysterious to reliable.

What You Will Learn

By the end of this page, you will understand five key properties of predictable behavior: determinism, idempotency, explicit state, clear contracts, and consistent error handling. You'll learn patterns for achieving each and understand why these properties reduce bugs, simplify debugging, and accelerate development.

Determinism: Same Inputs, Same Outputs

Deterministic behavior is the most fundamental form of predictability. A deterministic function always produces the same output given the same input. No randomness, no hidden state, no dependency on external systems that might behave differently. A function f is deterministic if for all inputs x, f(x) always returns the same value. Determinism is the gold standard of predictability because it makes code: Testable — Run the same test 1000 times; get the same result Debuggable — Reproduce issues by replaying inputs Cacheable — Same inputs mean cached results are valid Parallelizable — No hidden dependencies between calls

Pure Functions

Deterministic functions with no side effects are called pure functions . They're the most predictable code possible: call them anywhere, anytime, any number of times, and the only effect is the return value. Functional programming builds entire systems from pure functions for exactly this reason.

Sources of Non-Determinism: Understanding what breaks determinism helps you avoid or isolate it: Random Number Generation — Obvious, but subtle when libraries use randomness internally (shuffling algorithms, UUID generation, hash seed randomization). Current Time/Date — Date.now(), LocalDateTime.now(), or any time-dependent logic. Tests that pass at 11:59 PM and fail at 12:01 AM are a symptom. External System Dependencies — Network calls, database queries, file system reads. The external system might return different data or fail entirely. Mutable Shared State — If multiple threads or processes share mutable state, the order of operations affects results. This is the domain of race conditions. Hash Map Iteration Order — In many languages, hash map iteration order is not guaranteed. Code that depends on order is non-deterministic across runs. Floating Point Accumulation — Different orderings of floating-point operations can produce different results due to rounding. (a + b) + c may not equal a + (b + c) .

non-deterministic.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// ❌ Non-Deterministic
function generateReport(orders: Order[]) {
  const timestamp = new Date();
  const randomId = Math.random();
  
  return {
    id: randomId,
    generatedAt: timestamp,
    summary: summarize(orders),
    // Different every time!
  };
}
 
function summarize(orders: Order[]) {
  // Depends on iteration order
  const byStatus = new Map();
  for (const order of orders) {
    const current = byStatus.get(order.status);
    byStatus.set(order.status, (current ?? 0) + 1);
  }
  // Map iteration order may vary!
  return [...byStatus.entries()];
}

deterministic.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// ✅ Deterministic
function generateReport(
  orders: Order[],
  clock: Clock,      // Injected
  idGenerator: IdGen // Injected
) {
  return {
    id: idGenerator.next(),
    generatedAt: clock.now(),
    summary: summarize(orders),
  };
}
 
function summarize(orders: Order[]) {
  const byStatus = new Map();
  for (const order of orders) {
    const current = byStatus.get(order.status);
    byStatus.set(order.status, (current ?? 0) + 1);
  }
  // Explicitly sort for consistent order
  return [...byStatus.entries()]
    .sort(([a], [b]) => a.localeCompare(b));
}

Dependency Injection for Determinism

The key pattern for achieving determinism is dependency injection . Instead of calling Date.now() directly, accept a Clock parameter. Instead of using Math.random(), accept a RandomSource . In tests, inject deterministic implementations. In production, inject real ones. This separates the logic from its non-deterministic dependencies.

Idempotency: Safe to Repeat

Idempotent operations produce the same result whether executed once or multiple times. This is crucial for distributed systems, retry logic, and anywhere operations might be duplicated. An operation f is idempotent if f(f(x)) = f(x) for all x . Or more simply: doing it twice is the same as doing it once. Why Idempotency Matters: In the real world, things fail. Networks drop packets. Services time out. Clients retry. If your operations aren't idempotent, retries can cause catastrophic problems: Charge a customer's credit card twice Send duplicate emails Create duplicate records Apply discounts multiple times

Idempotency in HTTP Methods
Method	Idempotent?	Reasoning
GET	Yes	Reading doesn't change state; can read repeatedly
PUT	Yes	Setting to a specific value is always the same value
DELETE	Yes	Deleting what's already deleted is still deleted
POST	No	Creates new resource; calling twice creates two resources
PATCH	Depends	Relative changes (increment) aren't; absolute (set to X) are

Patterns for Achieving Idempotency: 1. Idempotency Keys For non-naturally-idempotent operations, use client-generated unique keys. The server stores processed keys and returns cached results for duplicates. async function processPayment(request: PaymentRequest) { const existing = await db.payments.findByIdempotencyKey(request.idempotencyKey); if (existing) { return existing.result; // Return cached result } const result = await chargeCard(request); await db.payments.save({ idempotencyKey: request.idempotencyKey, result, }); return result; } 2. Absolute Rather Than Relative Updates // ❌ Not idempotent: incrementing twice increases by 2 await db.user.update({ balance: { increment: 100 } }); // ✅ Idempotent: setting to specific value is always that value const newBalance = currentBalance + 100; await db.user.update({ balance: newBalance }); 3. Conditional Operations // ❌ Not idempotent: always sets await db.user.update({ status: 'active' }); // ✅ Idempotent: only sets if condition met await db.user.updateWhere( { status: 'pending' }, // Only if currently pending { status: 'active' } );

The Retry Trap

Non-idempotent operations with automatic retries are a disaster waiting to happen. If your HTTP client retries failed POST requests, and your server doesn't handle duplicates, you will create duplicate data. Either make operations idempotent or disable retries—never assume the network is reliable.

Explicit State: No Hidden Surprises

One of the most common sources of unpredictable behavior is hidden state —state that affects behavior but isn't visible to the caller. When state is implicit, developers must know about it to use the system correctly. When it's explicit, the code enforces correct usage. The Problem with Implicit State: Consider a connection pool that implicitly tracks whether connections are 'in use':

implicit-state.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// ❌ Implicit state: caller must remember to release
class ConnectionPool {
  private connections: Connection[] = [];
  private inUse: Set<Connection> = new Set();
  
  acquire(): Connection {
    const conn = this.connections.find(c => !this.inUse.has(c));
    if (!conn) throw new Error('Pool exhausted');
    this.inUse.add(conn);
    return conn;  // Caller must remember to release!
  }
  
  release(conn: Connection): void {
    this.inUse.delete(conn);
  }
}
 
// Calling code - easy to forget release!
const conn = pool.acquire();
const result = await conn.query(sql);
// Forgot pool.release(conn) - connection leaked!

Making State Explicit: Explicit state makes constraints visible and enforceable. Here are patterns for explicitness:

explicit-state.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// ✅ Explicit state: structure enforces correct usage
class ConnectionPool {
  async withConnection<T>(fn: (conn: Connection) => Promise<T>): Promise<T> {
    const conn = await this.acquire();
    try {
      return await fn(conn);
    } finally {
      this.release(conn);  // Automatic release!
    }
  }
}
 
// Calling code - impossible to forget release
await pool.withConnection(async (conn) => {
  return await conn.query(sql);
});  // Connection released automatically
 
// ✅ Alternative: RAII with Symbol.dispose (TypeScript 5.2+)
async function doWork() {
  using conn = await pool.acquire();  // Disposed at scope end
  return await conn.query(sql);
}

Patterns for Explicit State

•Required Parameters — If state is needed, require it as a parameter. Don't rely on implicit initialization.
•State Machines — Model valid states and transitions explicitly. Invalid transitions become compilation errors or clear runtime errors.
•RAII / Using Statements — Tie resource lifecycle to scope. Acquisition and release happen together.
•Factory Functions — Return fully-initialized objects. Don't allow partially-constructed objects to exist.
•Immutable Transitions — Instead of mutating state, return new objects representing the new state.
•Builder Pattern — Accumulate configuration explicitly, then validate and build atomically.

Type-Driven Explicit State

Use your type system to make invalid states unrepresentable. If a 'Submitted' order must have a submission timestamp, ensure the Submitted type includes that timestamp. The type system then prevents creating submitted orders without timestamps—no documentation or discipline required.

Clear Contracts: Promises You Can Count On

A contract defines what a piece of code promises to do and what it requires in return. Clear contracts make behavior predictable because developers know exactly what to expect. The Components of a Contract: Preconditions — What must be true before calling. If violated, the caller has made an error. Postconditions — What will be true after calling. This is the caller's guarantee. Invariants — What remains constant throughout. These must hold before and after every public operation.

contracts.ts
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
/**
 * Transfers funds between accounts.
 * 
 * @precondition fromAccount and toAccount are valid, active accounts
 * @precondition amount > 0
 * @precondition fromAccount.balance >= amount
 * @precondition fromAccount !== toAccount
 * 
 * @postcondition fromAccount.balance decreased by amount
 * @postcondition toAccount.balance increased by amount
 * @postcondition transfer is recorded in audit log
 * @postcondition no other account balances changed
 * 
 * @throws InsufficientFundsError if balance < amount (despite precondition)
 * @throws AccountFrozenError if either account becomes frozen during transfer
 */
function transfer(fromAccount: Account, toAccount: Account, amount: Money): void {
  // Validate preconditions at runtime for safety
  if (amount.value <= 0) {
    throw new InvalidArgumentError('Amount must be positive');
  }
  if (fromAccount.id === toAccount.id) {
    throw new InvalidArgumentError('Cannot transfer to same account');
  }
  if (!fromAccount.isActive || !toAccount.isActive) {
    throw new AccountInactiveError();
  }
  
  // Invariant: total money in system remains constant
  const totalBefore = fromAccount.balance.add(toAccount.balance);
  
  try {
    fromAccount.debit(amount);
    toAccount.credit(amount);
  } finally {
    // Verify invariant maintained
    const totalAfter = fromAccount.balance.add(toAccount.balance);
    assert(totalBefore.equals(totalAfter), 'Money invariant violated');
  }
  
  auditLog.record(new TransferEvent(fromAccount, toAccount, amount));
}

Levels of Contract Enforcement: Documentation-Only Contracts (Weakest) Contracts stated in comments/docs only Relies on developers reading and following Violations discovered at runtime or never Runtime-Checked Contracts (Moderate) Assert/validate preconditions at start Check postconditions before return Violations become clear errors Type-Enforced Contracts (Strongest) Use types to make violations impossible Invalid calls don't compile Zero runtime overhead for checking

Weak Contract

•// @param age - must be positive
•function setAge(age: number) { ... }
•
•setAge(-5) // Compiles! Fails at ???

Strong Contract

•type PositiveNumber = number & { readonly brand: unique symbol }
•function setAge(age: PositiveNumber) { ... }
•
•setAge(-5) // Compile error!

Design by Contract

The idea of contracts as first-class design elements comes from Bertrand Meyer's 'Design by Contract' methodology. Languages like Eiffel have built-in contract support. In other languages, you can use assertion libraries, type brands, or runtime validation libraries to achieve similar benefits.

Consistent Error Handling

Few things destroy predictability faster than inconsistent error handling. When some methods throw, others return null, and still others return Result objects, developers never know what to expect. The Error Handling Spectrum:

Approach	Signal	When to Use
Exceptions	Throw	Truly exceptional conditions; caller can't reasonably prevent
Null/Undefined	Return null	Expected absence; 'not found' scenarios
Result Types	Return Result<T, E>	Recoverable failures; domain errors
Error Callbacks	Invoke callback	Async operations (older style)
Status Codes	Return code	APIs, system interfaces

The Key Principle: Choose One, Apply Everywhere Consistency matters more than which approach you choose. If your codebase uses Result types, use them everywhere. If it uses exceptions for recoverable errors, use exceptions everywhere. Mixing approaches creates confusion. Patterns for Consistent Error Handling:

error-handling.ts
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
// ✅ Pattern: Result Types for Domain Errors
type Result<T, E> = 
  | { success: true; value: T }
  | { success: false; error: E };
 
class UserService {
  findById(id: UserId): Result<User, 'not_found' | 'database_error'> {
    // Consistent: always returns Result, never throws
  }
  
  create(data: CreateUserData): Result<User, 'validation_error' | 'duplicate_email'> {
    // Same pattern: Result for all domain operations
  }
  
  delete(id: UserId): Result<void, 'not_found' | 'has_dependencies'> {
    // Even for void, use Result for consistency
  }
}
 
// Calling code knows exactly what to expect
const result = userService.findById(userId);
if (result.success) {
  console.log(result.value.name);
} else {
  // TypeScript knows error is 'not_found' | 'database_error'
  switch (result.error) {
    case 'not_found': return showNotFoundPage();
    case 'database_error': return showErrorPage();
  }
}

Error Handling Consistency Checklist

•Document the approach — State explicitly which approach the codebase uses and when
•Use types to enforce — If using Result types, make the return type explicit; callers can't ignore it
•Handle at appropriate level — Don't catch and re-throw repeatedly; handle once at the right layer
•Preserve information — Include context, causes, and actionable messages in errors
•Fail fast for bugs — Programmer errors (null pointers, out-of-bounds) should crash immediately, not return error codes
•Distinguish expected vs unexpected — 'User not found' is expected; 'database connection lost' is unexpected

The Silent Failure Trap

The worst form of inconsistency is silent failure—when operations fail but don't signal it at all. Returning null when something went wrong (not when absence is expected), catching and ignoring exceptions, or setting a boolean flag that no one checks. These create impossible-to-debug systems where errors propagate silently until they surface far from the cause.

Stability and Backward Compatibility

Predictability extends across time. Code that behaves one way today and differently tomorrow is surprising, even if both behaviors are individually correct. Stability means behavior remains consistent across versions. Semantic Versioning and Behavior: Semantic versioning (SemVer) is built on this principle: Patch (1.0.X) — Bug fixes only; behavior unchanged for correct usage Minor (1.X.0) — New features; existing behavior unchanged Major (X.0.0) — Breaking changes; behavior may change The implicit promise: if you depend on version 1.2.3, upgrading to 1.2.4 or 1.3.0 won't break your code. Only 2.0.0 might.

Patterns for Stable Evolution: 1. Deprecation Before Removal /** @deprecated Use specificSearch() instead. Will be removed in v3.0. */ function search(query: string): Result[] { console.warn('search() is deprecated; use specificSearch()'); return specificSearch({ query, limit: 100 }); } 2. Feature Flags for Gradual Migration function processOrder(order: Order) { if (featureFlags.useNewOrderFlow) { return newOrderProcessor.process(order); } return legacyOrderProcessor.process(order); } 3. Versioned APIs // Old clients continue working; new clients use v2 app.post('/api/v1/users', v1UserController.create); app.post('/api/v2/users', v2UserController.create); 4. Extension Points for Future Needs interface Config { required: string; optional?: string; // Reserved for future use; allows adding fields without version bump [key: string]: unknown; }

Hyrum's Law

"With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody." —Hyrum Wright. This means even 'undefined behavior' becomes a de facto contract. Be very careful about what your code does, even incidentally.

Testing for Predictability

Predictability should be verified, not assumed. Specific testing techniques help ensure behavior remains predictable:

Testing Techniques for Predictability

•Determinism Tests — Run the same test multiple times; verify identical results. Use test runners that randomize test order to expose hidden state dependencies.
•Idempotency Tests — Call the same operation multiple times; verify the result is identical to calling once. Test with 2, 3, and large numbers of repetitions.
•Contract Tests — Verify preconditions, postconditions, and invariants. Use property-based testing to generate many inputs and verify contracts hold.
•Chaos Engineering — Inject failures (network errors, timeouts, disk failures) and verify the system still behaves predictably.
•Regression Tests — Capture current behavior; verify it doesn't change unexpectedly. Snapshot testing is useful here.
•Boundary Tests — Test at edges: empty inputs, maximum values, null values. Edge cases often reveal unexpected behavior.

predictability-tests.ts
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
describe('TransferService', () => {
  // Determinism test
  it('produces same result with same inputs', () => {
    const result1 = service.calculate(input);
    const result2 = service.calculate(input);
    expect(result1).toEqual(result2);
  });
  
  // Idempotency test
  it('is idempotent for status updates', async () => {
    await service.markComplete(orderId);
    const afterFirst = await service.getOrder(orderId);
    
    await service.markComplete(orderId);
    const afterSecond = await service.getOrder(orderId);
    
    expect(afterFirst).toEqual(afterSecond);
  });
  
  // Contract test
  it('maintains money invariant during transfer', async () => {
    const totalBefore = accountA.balance + accountB.balance;
    
    await service.transfer(accountA, accountB, amount);
    
    const totalAfter = accountA.balance + accountB.balance;
    expect(totalAfter).toEqual(totalBefore);
  });
  
  // Property-based contract test
  it('never leaves system in invalid state', () => {
    fc.assert(fc.property(
      fc.array(fc.oneof(
        fc.record({ type: fc.constant('deposit'), amount: fc.nat() }),
        fc.record({ type: fc.constant('withdraw'), amount: fc.nat() }),
      )),
      (operations) => {
        applyOperations(account, operations);
        return account.balance >= 0;  // Invariant: balance never negative
      }
    ));
  });
});

System Design (HLD)Principle of Least Astonishment

The Principle of Least Astonishment (POLA)

LevelIntermediate

Duration60 mins

TopicPrinciple of Least Astonishment

2 / 4

Predictable Behavior

The Architecture of Trust

When developers work with code they trust, they move fast. They don't second-guess method calls. They don't write defensive null checks around every operation. They don't add logging statements to verify that things happened. They simply write what they mean and trust the system to do what it says. Predictable behavior is the foundation of this trust. It's not enough for code to do the right thing—it must do the right thing consistently, reliably, and in a way developers can anticipate . This page examines the concrete properties and patterns that make behavior predictable. These aren't abstract ideals; they're practical engineering techniques that, when applied systematically, transform code from mysterious to reliable.

What You Will Learn

By the end of this page, you will understand five key properties of predictable behavior: determinism, idempotency, explicit state, clear contracts, and consistent error handling. You'll learn patterns for achieving each and understand why these properties reduce bugs, simplify debugging, and accelerate development.

Determinism: Same Inputs, Same Outputs

Deterministic behavior is the most fundamental form of predictability. A deterministic function always produces the same output given the same input. No randomness, no hidden state, no dependency on external systems that might behave differently. A function f is deterministic if for all inputs x, f(x) always returns the same value. Determinism is the gold standard of predictability because it makes code: Testable — Run the same test 1000 times; get the same result Debuggable — Reproduce issues by replaying inputs Cacheable — Same inputs mean cached results are valid Parallelizable — No hidden dependencies between calls

Pure Functions

Deterministic functions with no side effects are called pure functions . They're the most predictable code possible: call them anywhere, anytime, any number of times, and the only effect is the return value. Functional programming builds entire systems from pure functions for exactly this reason.

Sources of Non-Determinism: Understanding what breaks determinism helps you avoid or isolate it: Random Number Generation — Obvious, but subtle when libraries use randomness internally (shuffling algorithms, UUID generation, hash seed randomization). Current Time/Date — Date.now(), LocalDateTime.now(), or any time-dependent logic. Tests that pass at 11:59 PM and fail at 12:01 AM are a symptom. External System Dependencies — Network calls, database queries, file system reads. The external system might return different data or fail entirely. Mutable Shared State — If multiple threads or processes share mutable state, the order of operations affects results. This is the domain of race conditions. Hash Map Iteration Order — In many languages, hash map iteration order is not guaranteed. Code that depends on order is non-deterministic across runs. Floating Point Accumulation — Different orderings of floating-point operations can produce different results due to rounding. (a + b) + c may not equal a + (b + c) .

non-deterministic.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// ❌ Non-Deterministic
function generateReport(orders: Order[]) {
  const timestamp = new Date();
  const randomId = Math.random();
  
  return {
    id: randomId,
    generatedAt: timestamp,
    summary: summarize(orders),
    // Different every time!
  };
}
 
function summarize(orders: Order[]) {
  // Depends on iteration order
  const byStatus = new Map();
  for (const order of orders) {
    const current = byStatus.get(order.status);
    byStatus.set(order.status, (current ?? 0) + 1);
  }
  // Map iteration order may vary!
  return [...byStatus.entries()];
}

deterministic.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// ✅ Deterministic
function generateReport(
  orders: Order[],
  clock: Clock,      // Injected
  idGenerator: IdGen // Injected
) {
  return {
    id: idGenerator.next(),
    generatedAt: clock.now(),
    summary: summarize(orders),
  };
}
 
function summarize(orders: Order[]) {
  const byStatus = new Map();
  for (const order of orders) {
    const current = byStatus.get(order.status);
    byStatus.set(order.status, (current ?? 0) + 1);
  }
  // Explicitly sort for consistent order
  return [...byStatus.entries()]
    .sort(([a], [b]) => a.localeCompare(b));
}

Dependency Injection for Determinism

The key pattern for achieving determinism is dependency injection . Instead of calling Date.now() directly, accept a Clock parameter. Instead of using Math.random(), accept a RandomSource . In tests, inject deterministic implementations. In production, inject real ones. This separates the logic from its non-deterministic dependencies.

Idempotency: Safe to Repeat

Idempotent operations produce the same result whether executed once or multiple times. This is crucial for distributed systems, retry logic, and anywhere operations might be duplicated. An operation f is idempotent if f(f(x)) = f(x) for all x . Or more simply: doing it twice is the same as doing it once. Why Idempotency Matters: In the real world, things fail. Networks drop packets. Services time out. Clients retry. If your operations aren't idempotent, retries can cause catastrophic problems: Charge a customer's credit card twice Send duplicate emails Create duplicate records Apply discounts multiple times

Idempotency in HTTP Methods
Method	Idempotent?	Reasoning
GET	Yes	Reading doesn't change state; can read repeatedly
PUT	Yes	Setting to a specific value is always the same value
DELETE	Yes	Deleting what's already deleted is still deleted
POST	No	Creates new resource; calling twice creates two resources
PATCH	Depends	Relative changes (increment) aren't; absolute (set to X) are

Patterns for Achieving Idempotency: 1. Idempotency Keys For non-naturally-idempotent operations, use client-generated unique keys. The server stores processed keys and returns cached results for duplicates. async function processPayment(request: PaymentRequest) { const existing = await db.payments.findByIdempotencyKey(request.idempotencyKey); if (existing) { return existing.result; // Return cached result } const result = await chargeCard(request); await db.payments.save({ idempotencyKey: request.idempotencyKey, result, }); return result; } 2. Absolute Rather Than Relative Updates // ❌ Not idempotent: incrementing twice increases by 2 await db.user.update({ balance: { increment: 100 } }); // ✅ Idempotent: setting to specific value is always that value const newBalance = currentBalance + 100; await db.user.update({ balance: newBalance }); 3. Conditional Operations // ❌ Not idempotent: always sets await db.user.update({ status: 'active' }); // ✅ Idempotent: only sets if condition met await db.user.updateWhere( { status: 'pending' }, // Only if currently pending { status: 'active' } );

The Retry Trap

Non-idempotent operations with automatic retries are a disaster waiting to happen. If your HTTP client retries failed POST requests, and your server doesn't handle duplicates, you will create duplicate data. Either make operations idempotent or disable retries—never assume the network is reliable.

Explicit State: No Hidden Surprises

One of the most common sources of unpredictable behavior is hidden state —state that affects behavior but isn't visible to the caller. When state is implicit, developers must know about it to use the system correctly. When it's explicit, the code enforces correct usage. The Problem with Implicit State: Consider a connection pool that implicitly tracks whether connections are 'in use':

implicit-state.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// ❌ Implicit state: caller must remember to release
class ConnectionPool {
  private connections: Connection[] = [];
  private inUse: Set<Connection> = new Set();
  
  acquire(): Connection {
    const conn = this.connections.find(c => !this.inUse.has(c));
    if (!conn) throw new Error('Pool exhausted');
    this.inUse.add(conn);
    return conn;  // Caller must remember to release!
  }
  
  release(conn: Connection): void {
    this.inUse.delete(conn);
  }
}
 
// Calling code - easy to forget release!
const conn = pool.acquire();
const result = await conn.query(sql);
// Forgot pool.release(conn) - connection leaked!

Making State Explicit: Explicit state makes constraints visible and enforceable. Here are patterns for explicitness:

explicit-state.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// ✅ Explicit state: structure enforces correct usage
class ConnectionPool {
  async withConnection<T>(fn: (conn: Connection) => Promise<T>): Promise<T> {
    const conn = await this.acquire();
    try {
      return await fn(conn);
    } finally {
      this.release(conn);  // Automatic release!
    }
  }
}
 
// Calling code - impossible to forget release
await pool.withConnection(async (conn) => {
  return await conn.query(sql);
});  // Connection released automatically
 
// ✅ Alternative: RAII with Symbol.dispose (TypeScript 5.2+)
async function doWork() {
  using conn = await pool.acquire();  // Disposed at scope end
  return await conn.query(sql);
}

Patterns for Explicit State

•Required Parameters — If state is needed, require it as a parameter. Don't rely on implicit initialization.
•State Machines — Model valid states and transitions explicitly. Invalid transitions become compilation errors or clear runtime errors.
•RAII / Using Statements — Tie resource lifecycle to scope. Acquisition and release happen together.
•Factory Functions — Return fully-initialized objects. Don't allow partially-constructed objects to exist.
•Immutable Transitions — Instead of mutating state, return new objects representing the new state.
•Builder Pattern — Accumulate configuration explicitly, then validate and build atomically.

Type-Driven Explicit State

Use your type system to make invalid states unrepresentable. If a 'Submitted' order must have a submission timestamp, ensure the Submitted type includes that timestamp. The type system then prevents creating submitted orders without timestamps—no documentation or discipline required.

Clear Contracts: Promises You Can Count On

A contract defines what a piece of code promises to do and what it requires in return. Clear contracts make behavior predictable because developers know exactly what to expect. The Components of a Contract: Preconditions — What must be true before calling. If violated, the caller has made an error. Postconditions — What will be true after calling. This is the caller's guarantee. Invariants — What remains constant throughout. These must hold before and after every public operation.

contracts.ts
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
/**
 * Transfers funds between accounts.
 * 
 * @precondition fromAccount and toAccount are valid, active accounts
 * @precondition amount > 0
 * @precondition fromAccount.balance >= amount
 * @precondition fromAccount !== toAccount
 * 
 * @postcondition fromAccount.balance decreased by amount
 * @postcondition toAccount.balance increased by amount
 * @postcondition transfer is recorded in audit log
 * @postcondition no other account balances changed
 * 
 * @throws InsufficientFundsError if balance < amount (despite precondition)
 * @throws AccountFrozenError if either account becomes frozen during transfer
 */
function transfer(fromAccount: Account, toAccount: Account, amount: Money): void {
  // Validate preconditions at runtime for safety
  if (amount.value <= 0) {
    throw new InvalidArgumentError('Amount must be positive');
  }
  if (fromAccount.id === toAccount.id) {
    throw new InvalidArgumentError('Cannot transfer to same account');
  }
  if (!fromAccount.isActive || !toAccount.isActive) {
    throw new AccountInactiveError();
  }
  
  // Invariant: total money in system remains constant
  const totalBefore = fromAccount.balance.add(toAccount.balance);
  
  try {
    fromAccount.debit(amount);
    toAccount.credit(amount);
  } finally {
    // Verify invariant maintained
    const totalAfter = fromAccount.balance.add(toAccount.balance);
    assert(totalBefore.equals(totalAfter), 'Money invariant violated');
  }
  
  auditLog.record(new TransferEvent(fromAccount, toAccount, amount));
}

Levels of Contract Enforcement: Documentation-Only Contracts (Weakest) Contracts stated in comments/docs only Relies on developers reading and following Violations discovered at runtime or never Runtime-Checked Contracts (Moderate) Assert/validate preconditions at start Check postconditions before return Violations become clear errors Type-Enforced Contracts (Strongest) Use types to make violations impossible Invalid calls don't compile Zero runtime overhead for checking

Weak Contract

•// @param age - must be positive
•function setAge(age: number) { ... }
•
•setAge(-5) // Compiles! Fails at ???

Strong Contract

•type PositiveNumber = number & { readonly brand: unique symbol }
•function setAge(age: PositiveNumber) { ... }
•
•setAge(-5) // Compile error!

Design by Contract

The idea of contracts as first-class design elements comes from Bertrand Meyer's 'Design by Contract' methodology. Languages like Eiffel have built-in contract support. In other languages, you can use assertion libraries, type brands, or runtime validation libraries to achieve similar benefits.

Consistent Error Handling

Few things destroy predictability faster than inconsistent error handling. When some methods throw, others return null, and still others return Result objects, developers never know what to expect. The Error Handling Spectrum:

Approach	Signal	When to Use
Exceptions	Throw	Truly exceptional conditions; caller can't reasonably prevent
Null/Undefined	Return null	Expected absence; 'not found' scenarios
Result Types	Return Result<T, E>	Recoverable failures; domain errors
Error Callbacks	Invoke callback	Async operations (older style)
Status Codes	Return code	APIs, system interfaces

The Key Principle: Choose One, Apply Everywhere Consistency matters more than which approach you choose. If your codebase uses Result types, use them everywhere. If it uses exceptions for recoverable errors, use exceptions everywhere. Mixing approaches creates confusion. Patterns for Consistent Error Handling:

error-handling.ts
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
// ✅ Pattern: Result Types for Domain Errors
type Result<T, E> = 
  | { success: true; value: T }
  | { success: false; error: E };
 
class UserService {
  findById(id: UserId): Result<User, 'not_found' | 'database_error'> {
    // Consistent: always returns Result, never throws
  }
  
  create(data: CreateUserData): Result<User, 'validation_error' | 'duplicate_email'> {
    // Same pattern: Result for all domain operations
  }
  
  delete(id: UserId): Result<void, 'not_found' | 'has_dependencies'> {
    // Even for void, use Result for consistency
  }
}
 
// Calling code knows exactly what to expect
const result = userService.findById(userId);
if (result.success) {
  console.log(result.value.name);
} else {
  // TypeScript knows error is 'not_found' | 'database_error'
  switch (result.error) {
    case 'not_found': return showNotFoundPage();
    case 'database_error': return showErrorPage();
  }
}

Error Handling Consistency Checklist

•Document the approach — State explicitly which approach the codebase uses and when
•Use types to enforce — If using Result types, make the return type explicit; callers can't ignore it
•Handle at appropriate level — Don't catch and re-throw repeatedly; handle once at the right layer
•Preserve information — Include context, causes, and actionable messages in errors
•Fail fast for bugs — Programmer errors (null pointers, out-of-bounds) should crash immediately, not return error codes
•Distinguish expected vs unexpected — 'User not found' is expected; 'database connection lost' is unexpected

The Silent Failure Trap

The worst form of inconsistency is silent failure—when operations fail but don't signal it at all. Returning null when something went wrong (not when absence is expected), catching and ignoring exceptions, or setting a boolean flag that no one checks. These create impossible-to-debug systems where errors propagate silently until they surface far from the cause.

Stability and Backward Compatibility

Predictability extends across time. Code that behaves one way today and differently tomorrow is surprising, even if both behaviors are individually correct. Stability means behavior remains consistent across versions. Semantic Versioning and Behavior: Semantic versioning (SemVer) is built on this principle: Patch (1.0.X) — Bug fixes only; behavior unchanged for correct usage Minor (1.X.0) — New features; existing behavior unchanged Major (X.0.0) — Breaking changes; behavior may change The implicit promise: if you depend on version 1.2.3, upgrading to 1.2.4 or 1.3.0 won't break your code. Only 2.0.0 might.

Patterns for Stable Evolution: 1. Deprecation Before Removal /** @deprecated Use specificSearch() instead. Will be removed in v3.0. */ function search(query: string): Result[] { console.warn('search() is deprecated; use specificSearch()'); return specificSearch({ query, limit: 100 }); } 2. Feature Flags for Gradual Migration function processOrder(order: Order) { if (featureFlags.useNewOrderFlow) { return newOrderProcessor.process(order); } return legacyOrderProcessor.process(order); } 3. Versioned APIs // Old clients continue working; new clients use v2 app.post('/api/v1/users', v1UserController.create); app.post('/api/v2/users', v2UserController.create); 4. Extension Points for Future Needs interface Config { required: string; optional?: string; // Reserved for future use; allows adding fields without version bump [key: string]: unknown; }

Hyrum's Law

"With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody." —Hyrum Wright. This means even 'undefined behavior' becomes a de facto contract. Be very careful about what your code does, even incidentally.

Testing for Predictability

Predictability should be verified, not assumed. Specific testing techniques help ensure behavior remains predictable:

Testing Techniques for Predictability

•Determinism Tests — Run the same test multiple times; verify identical results. Use test runners that randomize test order to expose hidden state dependencies.
•Idempotency Tests — Call the same operation multiple times; verify the result is identical to calling once. Test with 2, 3, and large numbers of repetitions.
•Contract Tests — Verify preconditions, postconditions, and invariants. Use property-based testing to generate many inputs and verify contracts hold.
•Chaos Engineering — Inject failures (network errors, timeouts, disk failures) and verify the system still behaves predictably.
•Regression Tests — Capture current behavior; verify it doesn't change unexpectedly. Snapshot testing is useful here.
•Boundary Tests — Test at edges: empty inputs, maximum values, null values. Edge cases often reveal unexpected behavior.

predictability-tests.ts
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
describe('TransferService', () => {
  // Determinism test
  it('produces same result with same inputs', () => {
    const result1 = service.calculate(input);
    const result2 = service.calculate(input);
    expect(result1).toEqual(result2);
  });
  
  // Idempotency test
  it('is idempotent for status updates', async () => {
    await service.markComplete(orderId);
    const afterFirst = await service.getOrder(orderId);
    
    await service.markComplete(orderId);
    const afterSecond = await service.getOrder(orderId);
    
    expect(afterFirst).toEqual(afterSecond);
  });
  
  // Contract test
  it('maintains money invariant during transfer', async () => {
    const totalBefore = accountA.balance + accountB.balance;
    
    await service.transfer(accountA, accountB, amount);
    
    const totalAfter = accountA.balance + accountB.balance;
    expect(totalAfter).toEqual(totalBefore);
  });
  
  // Property-based contract test
  it('never leaves system in invalid state', () => {
    fc.assert(fc.property(
      fc.array(fc.oneof(
        fc.record({ type: fc.constant('deposit'), amount: fc.nat() }),
        fc.record({ type: fc.constant('withdraw'), amount: fc.nat() }),
      )),
      (operations) => {
        applyOperations(account, operations);
        return account.balance >= 0;  // Invariant: balance never negative
      }
    ));
  });
});

Predictable Behavior

The Architecture of Trust

Determinism: Same Inputs, Same Outputs

Idempotency: Safe to Repeat

Explicit State: No Hidden Surprises

Clear Contracts: Promises You Can Count On

Consistent Error Handling

Stability and Backward Compatibility

Testing for Predictability

There’s more to understand.

Predictable Behavior

The Architecture of Trust

Determinism: Same Inputs, Same Outputs

Idempotency: Safe to Repeat

Explicit State: No Hidden Surprises

Clear Contracts: Promises You Can Count On

Consistent Error Handling

Stability and Backward Compatibility

Testing for Predictability

There’s more to understand.