Forem: Aishwarya B R

Event Sourcing: The Record Statement You Never Throw Away

Aishwarya B R — Thu, 12 Mar 2026 13:31:56 +0000

Your bank doesn't show you just your current balance. It shows you every deposit, every withdrawal, every transfer — in order, forever. Not because storage is cheap, but because the history IS the data.

Now imagine your bank deleted all transactions and just stored "Current Balance: $500." When a dispute occurs, how do you prove what happened? You can't. The journey is gone.

That's what traditional databases do to your application state. Every UPDATE overwrites the past. Every DELETE erases it permanently.

Event Sourcing says: stop throwing away the journey.

The Way Memory Actually Works

You can't change the past. But you can replay it.

That's event sourcing. Your application's history works exactly like memory and documentation combined:

Memory = immutable. What happened, happened. You append new experiences; you don't rewrite old ones.
Documentation = replayable.

What Event Sourcing IS

Store every state change as an immutable event. Never update. Never delete. Rebuild current state by replaying all events.

Traditional approach:

Patient record: medication = "Y", dosage = 100mg

(Everything before this moment: gone)

Event Sourcing approach:

Event 1 - PrescriptionAdded
{ medication: "X", dosage: 50mg, doctor: "Smith" }

Event 2 - PrescriptionChanged
{ medication: "Y", dosage: 100mg, doctor: "Jones", reason: "allergy to X" }

Current state = replay events = medication "Y", 100mg

The events are the source of truth. The current state is derived from them.

What Event Sourcing is NOT

❌ Audit logging — Audit logs are secondary. Event sourcing IS the primary storage.

❌ Event-driven architecture — Related, but different. You can have one without the other.

❌ Time travel / undo — You can rebuild past states. You cannot retroactively change events.

❌ Simple to implement — This is significant complexity. Choose deliberately.

When NOT to Use Event Sourcing

❌ Simple CRUD applications — If your app is forms-to-database with no history requirements, this is genuine overkill.

❌ High write volume, low read value — IoT sensor data writing 10,000 events/second where you only care about current readings.

❌ Strong immediate consistency required — Projections are eventually consistent. Use an append-only ledger with double-entry bookkeeping instead.

❌ No team familiarity — The learning curve is real. Budget time for it.

The test: If you can't name at least two concrete scenarios where replaying your event history would save you — in debugging, compliance, or feature development — you probably don't need it yet.

The Real-World Pain: Healthcare Records

Current Architecture (Traditional)

A patient record system stores only the latest state:

┌──────────────────────────┐
│ Patient Table            │
│                          │
│ id:         12345        │
│ medication: "Y"          │  ← Previous value: gone
│ dosage:     100mg        │  ← Previous value: gone
│ updated_at: 10:00 AM     │  ← When it changed, not why
└──────────────────────────┘

The damage:

Regulatory violation — HIPAA requires a complete audit trail
Legal liability — no proof of original prescription
Patient safety risk — no way to track the chain of medication decisions
No debugging capability — the system shows "Y" but you don't know how it got there

The Refactoring Journey

Attempt 1: Add `updated_at` Timestamps (15%)

ALTER TABLE patients ADD COLUMN updated_at TIMESTAMP;

What it does: You know when the record last changed.

What it still can't tell you:

What the value was before the change
Who made the change, or why
Any change before the last one

One UPDATE wipes all timestamp context. You have a clock but no history.

Attempt 2: Audit Log Table (25%)

CREATE TABLE audit_log (
  change_id   SERIAL PRIMARY KEY,
  table_name  TEXT,
  field_name  TEXT,
  old_value   TEXT,
  new_value   TEXT,
  changed_by  UUID,
  changed_at  TIMESTAMP
);

What it does: Separate table captures every field-level change.

What it still can't tell you:

The audit log is secondary — not the source of truth
Easy to forget logging in some code paths
You can't rebuild current state from audit entries alone

The audit log is a receipt printer, not a ledger.

Attempt 3: Versioned Records (50%)

CREATE TABLE patient_history (
  version     INT,
  patient_id  UUID,
  medication  TEXT,
  dosage      TEXT,
  active      BOOLEAN,
  created_at  TIMESTAMP
);
-- Never UPDATE. Only INSERT new versions.

What it does: Full history preserved. Never overwrites.

What it still can't tell you:

Stores full snapshots — if one field changes, you copy the entire record
No semantic meaning: was this a prescription change or a data correction?
Version conflicts in distributed systems

You have history, but it's dumb history.

Attempt 4: Event Log + Projections (75%)

const events = [
  {
    type: "PrescriptionAdded",
    data: { medication: "X", dosage: "50mg", doctor: "Smith" }
  },
  {
    type: "PrescriptionChanged",
    data: { medication: "Y", dosage: "100mg", doctor: "Jones", reason: "allergy to X" }
  }
];

function rebuildPatientState(events) {
  return events.reduce((state, event) => {
    switch (event.type) {
      case "PrescriptionAdded":
        return { ...state, medication: event.data.medication, dosage: event.data.dosage };
      case "PrescriptionChanged":
        return { ...state, medication: event.data.medication, dosage: event.data.dosage };
      default:
        return state;
    }
  }, {});
}

What it does: Events carry meaning. History is semantic, not just snapshots.

What breaks at scale:

1 million events per patient = slow rebuild on every read
No snapshots — must replay from event 1 every time
Can't run SQL queries against events directly

You have the right idea but it collapses under production load.

Attempt 5: Production-Ready Event Sourcing (100%)

The complete solution: immutable event store + snapshots + projections + CQRS separation.

┌──────────────────┐
│ Command Handler  │  (Write: AddPrescription)
└────────┬─────────┘
         │
         ▼
┌─────────────────────────────┐
│ Event Store                 │
│ (Immutable, append-only)    │
│                             │
│ PrescriptionAdded           │
│ PrescriptionChanged         │
│ DosageAdjusted              │
│ AllergyRecorded             │
└──────────────┬──────────────┘
               │
               ├──► Projection 1: Current Patient State   (read model)
               ├──► Projection 2: Medication History View (read model)
               └──► Projection 3: Compliance Audit Report (read model)

Event Store Schema:

CREATE TABLE events (
  event_id        UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  aggregate_id    TEXT NOT NULL,         -- "patient-12345"
  aggregate_type  TEXT NOT NULL,         -- "Patient"
  event_type      TEXT NOT NULL,         -- "PrescriptionChanged"
  event_data      JSONB NOT NULL,        -- { medication, dosage, doctor, reason }
  metadata        JSONB NOT NULL,        -- { user_id, ip, timestamp, causation_id }
  version         INT NOT NULL,          -- optimistic concurrency control
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- Append-only: no UPDATE, no DELETE ever touches this table

Snapshot Table:

CREATE TABLE snapshots (
  aggregate_id  TEXT PRIMARY KEY,
  version       INT NOT NULL,   -- event version at snapshot time
  state         JSONB NOT NULL, -- full reconstructed state
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

Snapshots: The Cache That Fixes Replay Performance

Replaying 600 events is fast. Replaying 600,000 is not.

Think of snapshots as a manually managed materialized view — a checkpoint that says "here's the known-good state at version N, don't bother replaying anything before this."

Rule of thumb: create a snapshot every N events (common values: 50, 100, 500 — tune to your read latency requirements).

Event Versioning: When Your Schema Evolves

// Version 1 (old)
{ type: "PrescriptionAdded", version: 1, data: { medication, dosage } }

// Version 2 (new)
{ type: "PrescriptionAdded", version: 2, data: { medication, dosage, prescriber_license } }

// Upcaster — converts old events to new schema at read time
function upcastPrescriptionAdded(event) {
  if (event.version === 1) {
    return {
      ...event,
      version: 2,
      data: {
        ...event.data,
        prescriber_license: lookupLicense(event.metadata.user_id)
      }
    };
  }
  return event;
}

All application code works with version 2. Old events are transparently upgraded at read time. No migrations. No data loss.

Indexing: Write Fast, Query Smart

Keep the Event Store Lean

The event store is not a query surface. It's a ledger. You only need two indexes:

-- Fetch and replay a single aggregate's history
CREATE INDEX idx_events_aggregate ON events (aggregate_id, version);

-- Stream all events in order (for projection rebuilds)
CREATE INDEX idx_events_created ON events (created_at);

That's it. No index on event_type. No index on event_data fields.

If you find yourself writing WHERE event_data->>'medication' = 'Y' against the event store — stop. That's a projection's job.

The Write Path: Intentionally Simple

One row. One append. No joins. No cascading index updates.

Compare to a traditional schema under heavy writes:

Write to patients table:
→ Update 3 indexes on patients
→ Write to audit_log table
→ Update 2 indexes on audit_log
→ Update foreign key indexes

Event sourcing flips this:

Writes are cheap. Reads are someone else's problem — specifically, the projection's problem.

Projections: Where All the Indexing Lives

Event Store (lean, 2 indexes)
├──► Current Patient State Projection
│      Index: patient_id
│      Index: (medication, dosage)
├──► Medication History Projection
│      Index: (patient_id, changed_at)
└──► Compliance Audit Projection
       Index: (changed_by, changed_at)
       Index: event_type

Adding a new reporting requirement? Add a new projection. The event store never changes.

Debugging with Event Sourcing

Patient 12345 is showing the wrong medication. Here's your workflow:

-- 1. Query the event store
SELECT * FROM events WHERE aggregate_id = 'patient-12345' ORDER BY version;

-- 2. Replay events in sequence — see exact state at each step
-- 3. Identify which event caused the incorrect state
-- 4. Check metadata: who triggered it, from which IP, at what time
-- 5. Fix the projection logic and replay to verify
-- 6. Deploy — no data migration needed

Quick Reference

Concept	What it does
Event Store	Immutable, append-only log of everything that happened
Aggregate	The entity whose state you're rebuilding (e.g. Patient)
Projection	A read model derived by replaying events
Snapshot	A checkpoint to avoid replaying from event 1 every time
Upcaster	Converts old event schemas to new ones at read time
CQRS	Separates the write path (commands) from the read path (queries)

Next: CQRS — because storing every event is only half the solution. Reading them efficiently is the other half.

Building scalable systems? I write about architecture patterns and clean code.
Follow me on LinkedIn | Twitter | GitHub

Caching Patterns That Scale

Aishwarya B R — Tue, 17 Feb 2026 17:52:39 +0000

You're writing a research paper. Every time you need a fact, you walk to the library (10 minutes away), search for the book (20 minutes), read the page (5 minutes), return the book, walk home (10 minutes).

For 20 facts, that's 15 hours of walking and searching.

Or: First trip, photocopy the relevant pages. Keep them on your desk. Look up facts instantly. One trip, 45 minutes total.

That's caching. Stop making the same expensive trip repeatedly.

Core idea: Trade memory for speed.

The Real-World Pain

You're building a social media feed. Users refresh constantly. Right now:

12.7 seconds per feed load
Database melts down at 10K concurrent users
Paying $50K/month for oversized instances
Database connections pool out (max 100)
Database CPU hits 100%

The platform grinds to a halt.

The Refactoring Journey

You can't keep hitting the database for every request. Here's how most teams evolve their caching strategy.

Attempt 1: Cache Everything With Fixed TTL (25%)

The idea: Just cache it all. Redis is fast. Problem solved, right?

feed = cache.get("user:123:feed")
if (!feed) {
  feed = database.query(...)
  cache.set("user:123:feed", feed, ttl=300)  // 5 minutes
}
return feed

What happens: It works! Data refreshes. Memory stays bounded. But then you notice something odd. Every 5 minutes, database load spikes to 100%. All cache entries expire at once. It's like a dam breaking every 5 minutes.

Also, user profiles (which barely change) get the same 5-minute TTL as rapidly updating feeds. Wasteful.

✅ Achieved	❌ Still Pending
Basic caching works	No invalidation strategy
Reduced initial DB load	Thundering herd (all expire together)
Faster repeated requests	No granular control
Data eventually refreshes	Cache hit rate drops on mass expiry
Memory stays bounded
Automatic cleanup

Attempt 2: Smart Caching with Invalidation (50%)

The evolution: Different TTLs for different data. Cache-aside pattern. Write-through when needed. Event-driven invalidation.

// Read with cache-aside
feed = cache.get(key)
if (!feed) {
  feed = database.query(...)
  cache.set(key, feed, ttl=30)  // Short TTL for feeds
}

// Write-through for critical data
database.update(userId, data)
cache.set(`user:${userId}`, data)  // Update cache immediately
eventBus.publish("UserUpdated", userId)  // Notify dependents

// Event handler invalidates related caches
onUserUpdated((userId) => {
  cache.delete(`user:${userId}:feed`)
  // Invalidate followers' feeds too
  followers = getFollowers(userId)
  followers.forEach(f => cache.delete(`user:${f}:feed`))
})

What happens: Much better! Fresh data after updates. But edge cases emerge.

✅ Achieved	❌ Still Pending
Fresh data after updates	Race conditions (write during read)
Granular TTL control	No thundering herd prevention
Event-driven invalidation	Cold start hammers DB
Write-through for consistency	Single point of failure

Attempt 3: Thundering Herd Prevention (75%)

The breakthrough: The database dies when popular cache keys expire simultaneously. 10,000 requests hit the database at once. You need to ensure only ONE request fetches from the database while others wait.

Key innovations:

Distributed locks: Only one request refreshes expired data
Probabilistic early expiration: Stagger refreshes before TTL expires

What happens: Traffic spike at noon. Your most popular user's feed (1M followers) expires from cache. 50,000 requests arrive in the next second. Without protection, that's 50,000 database queries. Instant death.

Impact:

Without protection: 10,000 concurrent requests = 10,000 DB queries = database death
With distributed lock: 10,000 concurrent requests = 1 DB query = smooth sailing
With probabilistic refresh: Refreshes spread over 30 seconds = no expiration spike

✅ Achieved	❌ Still Pending
Thundering herd eliminated	Cold start still painful
Smooth cache refresh	No failure handling
Database protected during spikes	Single-layer cache
Staggered expirations

Attempt 4: Production-Ready Caching (100%) ✨

The final form: Everything from Attempt 3, plus multi-layer caching, intelligent warming, circuit breakers, and graceful degradation.

Full implementation code

Architecture:

Request → L1 (memory, 1ms) → L2 (Redis, 7ms) → Database (200ms)
                                ↓ (if down)
                            Fallback to DB

Key additions:

Multi-layer caching:

L1 (in-memory): 100ms TTL, prevents Redis hammering during traffic spikes
L2 (Redis): 5min TTL, shared across all servers
L3 (Database): Source of truth

Cache warming on startup

What happens: L1 cache hits return in 1ms. L2 hits in 7ms. Database queries only happen for cache misses or cold data. No thundering herd. Redis failures degrade gracefully to database. App restarts are smooth. You scale to 100K concurrent users without breaking a sweat.

Real-world latency:

Request Type	Latency	What Happened
L1 hit (same server)	1ms	Read from Node.js memory
L2 hit (Redis)	7ms	Network + Redis lookup
Database miss	207ms	Full query + cache populate

Impact: 80% L1 hit rate + 15% L2 hit rate = 95% of requests under 10ms. Only 5% hit database.

✅ Production Ready:

Multi-layer caching (L1: memory, L2: Redis, L3: DB)
Cache warming on startup with parallel batch processing
Thundering herd prevention (distributed locks)
Probabilistic refresh (stagger expirations)
Circuit breaker for Redis failures
Graceful degradation (fallback to DB)
Lock safety (TTL prevents deadlocks)
Proper error handling
Monitoring & alerting

Sizing Your Cache

The 80/20 Rule (Pareto Principle): 20% of your data gets 80% of the traffic.

You have 10 million users. Do you cache all feeds? No. Cache the active users.

Real example calculation:

Total users: 10,000,000
Active daily users: 2,000,000 (20%)
Active hourly users: 500,000 (5%)

Average feed size: 50 posts × 500 bytes = 25 KB
Cache budget: 16 GB (Redis instance size)

Option 1: Cache all users
10M × 25 KB = 250 GB ❌ (exceeds budget by 15x)

Option 2: Cache active hourly users
500K × 25 KB = 12.5 GB ✅ (fits with room to spare)

Hit rate: 95% (active users cached)
Miss rate: 5% (inactive users hit DB directly)

L1 vs L2 sizing:

Layer	Size	TTL	Purpose
L1 (memory)	100 MB	100ms	Prevent Redis hammering during traffic spikes
L2 (Redis)	16-64 GB	5-30min	Main cache layer, shared across servers
L3 (Database)	Unlimited	Forever	Source of truth

Rule of thumb: L1 should hold ~1000 of your hottest items. L2 should hold 10-20% of your dataset.

Cache Invalidation Strategies

Strategy	Example	When to Use
TTL-based	Profiles (5min), Posts (30s), Static (24hr)	Different data change frequencies
Event-based	User updates profile → publish event → delete cache	Immediate consistency needed
Dependency-based	New post → invalidate author + all 1000 followers	Complex relationships
Tag-based	`cache.invalidateByTag('user')` invalidates all user-related keys	Bulk invalidation
Probabilistic	Refresh randomly before expiration	Prevent thundering herd

Key Patterns Compared

Pattern	Use When	Consistency	What You Trade
Cache-Aside	Default for most reads	Eventual	Simple but cold cache penalty
Write-Through	Need strong consistency	Strong	2× write latency
Write-Behind	High write volume	Eventual	Risk of data loss if cache fails

When NOT to Cache

Don't Cache	Why
Financial transactions	Always read from source of truth. Stale balance = wrong charge.
Real-time stock prices	Price changes every second. Cache = misleading data.
Passwords / PII	Security risk. Always fetch from secure storage.
Rarely accessed data	Cache memory wasted. Cost > benefit.
User permissions/auth	Stale permissions = security hole. Cache for max 30s if needed.
Audit logs	Legal requirement for immutability. No caching.
Shopping cart totals	Needs transactional consistency. Cache items, not totals.

Redis Cluster: Scaling Beyond Single Instance

When you hit 100K+ concurrent users, single-instance Redis becomes the bottleneck. Redis Cluster distributes data across multiple nodes for horizontal scaling.

When You Need Clustering

Single Instance Limits:

Memory: ~64GB per instance (AWS/GCP limits)
Throughput: ~100K ops/sec
Network: ~1-2 Gbps

Signs you need clustering:

Redis memory usage >70% and growing
CPU consistently >60%
Network bandwidth saturating
Single point of failure unacceptable

How Redis Cluster Works

// Redis uses CRC16 hash slot algorithm
hash_slot = CRC16(key) % 16384

// Keys are distributed across nodes
Node 1: slots 0-5460
Node 2: slots 5461-10922
Node 3: slots 10923-16383

Critical: Hash Tags for Multi-Key Operations

// ❌ Keys go to different nodes - MULTI/EXEC fails
redis.mget('user:123:feed', 'user:123:profile')

// ✅ Use hash tags {} to force same slot
redis.mget('user:{123}:feed', 'user:{123}:profile')
// Both keys hash on "123", guaranteed same node

More on this in Part 2

Monitoring: What to Track

Metric	Target	Alert If	Why	Check in Redis CLI
Cache hit rate	>80%	<70%	Cache not effective	INFO stats
Memory usage	<80%	>90%	Running out of RAM	INFO memory
L1 latency	<1ms	>5ms	Memory pressure or GC issues	N/A (app-level)
L2 latency	<5ms	>20ms	Redis overloaded or network issues	--latency
Eviction rate	<100/sec	>1000/sec	Cache too small for working set	INFO stats
Miss rate	<20%	>30%	Ineffective caching strategy	INFO stats
DB query time	<50ms	>200ms	Database struggling	N/A (DB-level)

The Bottom Line

Production caching is about resilience and observability, not just performance.

Challenge	Solution
Single point of failure	Redis Cluster with replicas
Cache goes down	Circuit breakers, fallback to DB
Mystery slowness	Comprehensive monitoring + debug toolkit
Traffic spikes	Multi-layer cache + distributed locks
Can't reproduce bugs	Metric dashboards + structured logging

Start simple. Evolve deliberately. Your database will thank you.

Building scalable systems? I write about architecture patterns and clean code. Follow me on Linkedin | Twitter | Medium | GitHub

TypeScript: Stop Writing JavaScript With Extra Steps

Aishwarya B R — Mon, 16 Feb 2026 21:02:16 +0000

Production is down. You're staring at Cannot read property 'email' of undefined for the 47th time this quarter. The user object was supposed to have an email. The API docs said it would have an email. Your colleague who left six months ago definitely said it would have an email.

But it doesn't. And now you're debugging a codebase where any appears 847 times and every function accepts "whatever, man" as a valid argument.

Welcome to JavaScript Hell. TypeScript is the exit door, if you use it right.

What TypeScript IS

TypeScript is a static type system that catches bugs at compile time. It's JavaScript with guardrails that:

Tells you when you're accessing properties that don't exist
Autocompletes your objects because it knows what's in them
Documents your code through types (no more // user object, has stuff comments)
Refactors fearlessly because the compiler yells before users do

Think of it as spell-check for your logic. Red squiggles before you hit send.

What TypeScript is NOT

❌ A runtime safety net
Types disappear after compilation. TypeScript won't save you from bad API responses at runtime.
❌ A performance booster
It compiles to JavaScript. Same speed, same output.
❌ An excuse to over-engineer
type NestedGenericFactoryBuilderStrategy<T extends AbstractBase<K>, K> is not a flex.
❌ Just "JavaScript with types"
Used properly, it changes how you design code, not just how you annotate it.

Everything You Need to Learn TypeScript

You don't need a 40-hour course. You need:

Cheatsheets for the syntax stuff like types, interfaces, classes, control flow.
The handbook to get oriented.
A solid grasp of tsconfig.json before you touch anything. Half the time "TypeScript isn't working" actually means "I don't understand what strict: true does." Save yourself the existential crisis.

Practice (muscle memory)

Pick a small project like a CLI tool, a utility library, an API client and type it strictly. You'll learn more from one strict: true project than ten tutorials.

The rest of this post? It's the thinking part, how to evolve from "TypeScript that compiles" to "TypeScript that protects"

The Refactoring Journey: From `any` to Type Safety

Let's fix a real function: fetching and displaying a user.

async function getUser(id: any): Promise<any> {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}

const user = await getUser(123);
console.log(user.emial); // typo? TypeScript: LGTM 👍

Problems: Zero type safety. any in, any out.

25% Basic Interface

interface User {
  id: number;
  name: string;
  email: string;
}

async function getUser(id: number): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  return res.json(); // ⚠️ lying to TypeScript
}

const user = await getUser(123);
console.log(user.emial); // ✅ Error: Property 'emial' does not exist

What it does: Catches typos. Autocomplete works. Your IDE is useful now.

Problems: You're promising the API returns a User, but APIs lie. No runtime validation.

50% Optional Properties & Null Handling

interface User {
  id: number;
  name: string;
  email?: string;        // might not exist
  avatar?: string | null; // might be null
}

async function getUser(id: number): Promise<User | null> {
  const res = await fetch(`/api/users/${id}`);
  if (!res.ok) return null;
  return res.json();
}

const user = await getUser(123);
if (user) {
  console.log(user.email?.toUpperCase()); // safe chaining
}

What it does: Models reality. Things can be missing or null. Forces you to handle edge cases.

Problems: Still trusting res.json() blindly. No validation that the response actually matches User.

75% Discriminated Unions for API States

interface User {
  id: number;
  name: string;
  email?: string;
}

type ApiResult<T> =
  | { status: "loading" }
  | { status: "error"; message: string }
  | { status: "success"; data: T };

async function getUser(id: number): Promise<ApiResult<User>> {
  try {
    const res = await fetch(`/api/users/${id}`);
    if (!res.ok) {
      return { status: "error", message: `HTTP ${res.status}` };
    }
    const data = await res.json();
    return { status: "success", data };
  } catch (e) {
    return { status: "error", message: "Network failed" };
  }
}

const result = await getUser(123);

switch (result.status) {
  case "loading":
    showSpinner();
    break;
  case "error":
    showError(result.message); // TS knows `message` exists here
    break;
  case "success":
    showUser(result.data);     // TS knows `data` is User here
    break;
}

What it does: Models all possible states. TypeScript narrows types in each branch. Impossible to access data when status is "error".

Problems: Still no runtime guarantee that data matches User. If the API changes, you'll find out in production.

100% Runtime Validation with Type Guards

interface User {
  id: number;
  name: string;
  email?: string;
}

// Type guard: validates at runtime, narrows at compile time
function isUser(obj: unknown): obj is User {
  return (
    typeof obj === "object" &&
    obj !== null &&
    "id" in obj &&
    typeof (obj as User).id === "number" &&
    "name" in obj &&
    typeof (obj as User).name === "string"
  );
}

type ApiResult<T> =
  | { status: "error"; message: string }
  | { status: "success"; data: T };

async function getUser(id: number): Promise<ApiResult<User>> {
  try {
    const res = await fetch(`/api/users/${id}`);
    if (!res.ok) {
      return { status: "error", message: `HTTP ${res.status}` };
    }
    const json: unknown = await res.json(); // don't trust it

    if (!isUser(json)) {
      return { status: "error", message: "Invalid user data" };
    }

    return { status: "success", data: json }; // TS knows it's User
  } catch {
    return { status: "error", message: "Network failed" };
  }
}

What it does:

Treats API response as unknown (honest)
Validates at runtime with a type guard
TypeScript narrows to User after validation passes
Catches API contract changes before they hit users

Production-ready. For complex schemas, use libraries like Zod or Valibot instead of hand-written guards.

The Current Landscape

Framework	Conventional Choice	Why
Next.js / React	Zod, Valibot	Functional style, tree-shakeable, no decorators needed
NestJS	class-validator + class-transformer	Decorator-based, integrates with NestJS pipes/DTOs natively

Interface vs Type vs Class: The Decision Tree

TL;DR:

Interface → Object shapes, public APIs, extending
Type → Unions, intersections, tuples, mapped types
Class → Runtime instances, private state, instanceof

Quick Reference

Question	🚩 Red Flag	✅ Benefit
"What type is this?"	`any` everywhere	Explicit interfaces
"Can this be null?"	Unchecked `.property` access	Optional chaining + null checks
"What can this function return?"	`Promise<any>`	Union types for all states
"Is this API response safe?"	Casting `as User`	Runtime validation + type guards
"What properties does this have?"	`console.log` to find out	Autocomplete knows
"Will this refactor break things?"	"Deploy and pray"	Compiler errors before merge

When NOT to Use (Full) TypeScript

🚫 Over-typing everything Don't create interfaces for objects used once. Inline types work: function greet(user: { name: string }) {}
🚫 Complex generics for simple problems If your type definition is longer than the function, reconsider.
🚫 Typing third-party API responses you don't control Use runtime validation instead of lying with interfaces.
🚫 100% type coverage as a goal Some any or unknown is fine at boundaries. Perfect is the enemy of shipped.

TypeScript Cursor Rules & AI Guidance

.cursorrules (or rules in cursor settings)

# TypeScript Rules

- Never use `any`. Use `unknown` and narrow with type guards
- Treat all external data as `unknown`, validate with Zod
- Use discriminated unions for state (loading/error/success)
- Prefer Result pattern over thrown exceptions
- `strict: true` always

Example AI Prompt

Write a TypeScript function to fetch users from `/api/users`.

Requirements:
- Use Zod for response validation
- Return a discriminated union: `{ status: "error"; message: string } | { status: "success"; data: User[] }`
- Handle network errors and validation failures separately
- Infer the User type from the Zod schema

The Bottom Line

TypeScript isn't about adding colons and angle brackets to your code. It's about making illegal states unrepresentable.

Start here: Enable strict mode. Model your API responses honestly. Use unions for state. Validate at boundaries.

Stop writing types. Start designing with types.

SOLID Principles: From Chaos to Clean Code

Aishwarya B R — Tue, 27 Jan 2026 18:11:26 +0000

The God Class Problem

SOLID principles aren't about memorizing definitions or using fancy keywords. They're about writing code that doesn't make you want to cry when you revisit it six months later.

In today's age of "vibe coding" where AI generates hundreds of lines in seconds, we're out of excuses. We have the tools to write clean, testable code—we just need to prompt AI correctly. SOLID isn't optional anymore; it's the difference between shipping fast AND maintaining sanity.

Think of SOLID as five common-sense rules:

Single Responsibility: One class, one job
Open/Closed: Add features without breaking existing code
Liskov Substitution: Swap implementations without things exploding
Interface Segregation: Small, focused contracts
Dependency Inversion: Depend on abstractions, not concrete implementations

The Problem: A Real-World Nightmare

Here's a typical e-commerce order processor that violates every SOLID principle:

class OrderProcessor {
  constructor() {
    this.orders = [];
  }

  processOrder(customerData, items, paymentType, shippingAddress) {
    // Validates customer
    if (!customerData.name || !customerData.email) {
      throw new Error("Invalid customer");
    }

    // Calculates total
    let total = 0;
    for (let item of items) {
      total += item.price * item.quantity;
    }

    // Applies discount
    if (customerData.isPremium) {
      total *= 0.9;
    }

    // Processes payment
    if (paymentType === "credit") {
      console.log("Processing credit card...");
    } else if (paymentType === "paypal") {
      console.log("Processing PayPal...");
    } else if (paymentType === "bitcoin") {
      console.log("Processing Bitcoin...");
    }

    // Calculates shipping
    let shippingCost = 0;
    if (shippingAddress.country === "US") shippingCost = 10;
    else if (shippingAddress.country === "CA") shippingCost = 15;
    else shippingCost = 25;

    // Sends email
    console.log("Sending email to: " + customerData.email);

    // Saves to database
    this.orders.push({ customerData, items, total });

    // Generates invoice
    console.log("=== INVOICE ===");
    console.log("Total: $" + (total + shippingCost));
  }
}

What's Wrong?

This class isn't just a God Class—it's the entire pantheon. It's doing validation, calculation, payment processing, shipping, emails, database operations, and invoice generation. Want to add Apple Pay? Touch this monolith. Want to test payments? Good luck mocking everything else.

Requirements always change. Usually at 4 PM on Friday. Right before a demo.

The reality: A "2-hour feature" becomes 6 hours because changing one thing breaks three others.

The Refactoring Journey

Attempt 1: Extract Methods (15% there)

class OrderProcessor {
  processOrder(data) {
    this.validateCustomer(data.customer);
    const total = this.calculateTotal(data.items);
    this.processPayment(total, data.paymentType);
  }

  validateCustomer(customer) { /* ... */ }
  calculateTotal(items) { /* ... */ }
  processPayment(total, type) { /* ... */ }
}

Problem: Still one giant class. Can't test parts independently. Just organized chaos.

Attempt 2: Separate Classes (30% there)

class CustomerValidator {
  validate(customer) { /* ... */ }
}

class PaymentProcessor {
  process(amount, type) {
    if (type === "credit") { /* ... */ }
    else if (type === "paypal") { /* ... */ }
  }
}

Problem: PaymentProcessor still has that if-else chain. Adding new payment types means modifying this class.

Attempt 3: Abstractions! (85% there)

abstract class Payment {
  abstract processPayment(total: number): void;
}

class CreditPayment extends Payment {
  processPayment(total: number): void {
    console.log(`Processing credit card: $${total}`);
    if (total > 10000) throw new Error("Limit exceeded");
  }
}

class PayPalPayment extends Payment {
  processPayment(total: number): void {
    console.log(`Processing PayPal: $${total}`);
  }
}

Win: Each payment type is its own class. Want to add Apple Pay? Create ApplePayPayment without touching existing code.

Apply the same pattern to shipping, discounts, and notifications:

abstract class ShippingCalculator {
  abstract calculateShippingCost(address: Address): number;
}

abstract class DiscountStrategy {
  abstract applyDiscount(total: number): number;
}

abstract class NotificationService {
  abstract sendNotification(message: string): void;
}

The Final Solution

Here's the refactored architecture:

// Core abstractions
abstract class Payment {
  abstract processPayment(total: number): void;
}

abstract class ShippingCalculator {
  abstract calculateShippingCost(address: Address): number;
}

abstract class DiscountStrategy {
  abstract applyDiscount(total: number): number;
}

// Concrete implementations
class CreditPayment extends Payment {
  processPayment(total: number): void {
    console.log(`Processing credit card: $${total}`);
  }
}

class USShipping extends ShippingCalculator {
  calculateShippingCost(address: Address): number {
    return 10;
  }
}

class PremiumDiscount extends DiscountStrategy {
  applyDiscount(total: number): number {
    return total * 0.9;
  }
}

// The orchestrator (simplified)
class OrderProcessor {
  constructor(
    private validator: CustomerValidator,
    private calculator: OrderCalculator,
    private repository: OrderRepository,
    private invoiceGenerator: InvoiceGenerator
  ) {}

  processOrder(
    customerData: Customer,
    items: Item[],
    shippingAddress: Address,
    payment: Payment,
    shipping: ShippingCalculator,
    discount: DiscountStrategy,
    notification: NotificationService
  ): void {
    this.validator.validate(customerData);
    const subtotal = this.calculator.calculateTotal(items);
    const total = discount.applyDiscount(subtotal);
    const shippingCost = shipping.calculateShippingCost(shippingAddress);

    payment.processPayment(total + shippingCost);
    this.invoiceGenerator.generate(customerData, items, total, shippingCost);
    notification.sendNotification("Order confirmed!");
    this.repository.save({ customerData, items, total });
  }
}

See the complete working solution with all implementations, tests, and examples:
👉 GitHub Repository

When NOT to Use SOLID

Don't over-engineer small projects:

Prototypes/MVPs: Ship fast, refactor later
Simple CRUD apps: Sometimes a God Class is fine for 3 endpoints
Scripts/utilities: A 50-line script doesn't need dependency injection

Start simple. Refactor when you feel pain (tests are hard, changes break things, adding features takes too long).

Quick Reference

Principle	Question	Red Flag	Quick Fix
SRP	Does this class have one reason to change?	Multiple responsibilities	Extract separate classes
OCP	Can I add features without modifying code?	Long if-else chains	Use strategy pattern or polymorphism
LSP	Can I swap implementations safely?	No abstractions	Define interfaces/base classes
ISP	Am I forced to depend on unused methods?	Fat interfaces	Split into smaller, focused interfaces
DIP	Do I depend on abstractions?	Direct instantiation	Inject dependencies

Using AI to Write SOLID Code

AI can generate clean code—you just need to prompt it correctly. Here's how:

The Prompt

You are a senior software engineer who follows SOLID principles strictly.

When writing code:
- Each class should have ONE responsibility
- Use abstractions (interfaces/abstract classes) instead of concrete implementations
- Apply dependency injection via constructors
- Use strategy pattern for conditional logic (no long if-else chains)
- Keep classes small and focused

For the following requirement, provide:
1. Interface/abstract class definitions
2. Concrete implementations
3. A simple orchestrator class
4. Usage example

Requirement: [YOUR REQUIREMENT HERE]

Enforcing SOLID in Cursor/Windsurf

Create a .cursorrules or .windsurfrules file in your project root:

# Code Style Rules

## Architecture Principles
- Follow SOLID principles strictly
- Each class must have a single responsibility
- Use dependency injection via constructor
- Depend on abstractions, not concrete classes
- No God Classes - break down into focused classes

## Code Patterns
- Replace if-else chains with strategy pattern
- Use factory pattern for object creation
- Apply polymorphism over conditionals
- Keep methods under 20 lines
- Keep classes under 200 lines

## Testing Requirements
- All business logic must be testable
- Use dependency injection to enable mocking
- Write unit tests for each class independently

## Red Flags to Avoid
- Classes with 5+ methods doing unrelated things
- Methods with 3+ levels of nesting
- Direct instantiation of dependencies (use DI)
- Long parameter lists (>4 parameters suggests poor design)

In Cursor/Windsurf, reference this during prompts:

@.cursorrules Refactor this code following our SOLID principles

The AI will now automatically apply these constraints. No more excuses for messy code.

Key Takeaways

Before SOLID: One massive class doing everything. Adding Apple Pay means touching payment, validation, and database code.

After SOLID:

Want Apple Pay? Create ApplePayPayment class. Done.
Want SMS notifications? Create SMSNotification class. Done.
Want to test payments? Mock just the Payment interface. Done.

The goal isn't perfect architecture—it's code that adapts to change without breaking everything else.

Building an AI SaaS with clean architecture? I write about scalable patterns and practical refactoring. Follow me on Dev.to| GitHub

Forem: Aishwarya B R

Event Sourcing: The Record Statement You Never Throw Away

The Way Memory Actually Works

What Event Sourcing IS

What Event Sourcing is NOT

When NOT to Use Event Sourcing

The Real-World Pain: Healthcare Records

Current Architecture (Traditional)

The Refactoring Journey

Attempt 1: Add updated_at Timestamps (15%)

Attempt 2: Audit Log Table (25%)

Attempt 3: Versioned Records (50%)

Attempt 4: Event Log + Projections (75%)

Attempt 5: Production-Ready Event Sourcing (100%)

Snapshots: The Cache That Fixes Replay Performance

Event Versioning: When Your Schema Evolves

Indexing: Write Fast, Query Smart

Keep the Event Store Lean

The Write Path: Intentionally Simple

Projections: Where All the Indexing Lives

Debugging with Event Sourcing

Quick Reference

Caching Patterns That Scale

The Real-World Pain

The Refactoring Journey

Attempt 1: Cache Everything With Fixed TTL (25%)

Attempt 2: Smart Caching with Invalidation (50%)

Attempt 3: Thundering Herd Prevention (75%)

Attempt 4: Production-Ready Caching (100%) ✨

Sizing Your Cache

Cache Invalidation Strategies

Key Patterns Compared

When NOT to Cache

Redis Cluster: Scaling Beyond Single Instance

Monitoring: What to Track

The Bottom Line

TypeScript: Stop Writing JavaScript With Extra Steps

What TypeScript IS

What TypeScript is NOT

Everything You Need to Learn TypeScript

Practice (muscle memory)

The Refactoring Journey: From any to Type Safety

25% Basic Interface

50% Optional Properties & Null Handling

75% Discriminated Unions for API States

100% Runtime Validation with Type Guards

The Current Landscape

Interface vs Type vs Class: The Decision Tree

Quick Reference

When NOT to Use (Full) TypeScript

TypeScript Cursor Rules & AI Guidance

Example AI Prompt

The Bottom Line

SOLID Principles: From Chaos to Clean Code

The God Class Problem

The Problem: A Real-World Nightmare

What's Wrong?

The Refactoring Journey

Attempt 1: Extract Methods (15% there)

Attempt 2: Separate Classes (30% there)

Attempt 3: Abstractions! (85% there)

The Final Solution

When NOT to Use SOLID

Quick Reference

Using AI to Write SOLID Code

The Prompt

Enforcing SOLID in Cursor/Windsurf

Key Takeaways

Attempt 1: Add `updated_at` Timestamps (15%)

The Refactoring Journey: From `any` to Type Safety