Forem: Ali nazari

Bulletproof Your Node.js Applications with Resilia

Ali nazari — Mon, 05 Jan 2026 14:52:35 +0000

Ali nazari

Dec 28 '25

Bulletproof Your Node.js Applications with Resilia: A Lightweight Resilience Stack

#webdev #programming #node #javascript

Comments 1

4 min read

Supercharge Your Node.js Application with Hedge-Fetch: Eliminating Tail Latency with Speculative Execution

Ali nazari — Mon, 05 Jan 2026 14:52:03 +0000

In modern distributed systems, a frustrating paradox often emerges:

while your average response times are excellent, a small percentage of users experience inexplicably slow requests. This is tail latency—the dreaded P95 and P99 latencies that tarnish user experience and complicate SLA adherence.

While individual services may be fast, the compounding effect of variability across dozens of microservices or database calls means someone always gets the short straw.

Traditional solutions like static timeouts are blunt instruments.

Set them too low, and you increase error rates; set them too high, and you lose the battle against the tail.

The breakthrough came from Google's seminal research, "The Tail at Scale", which proposed a clever strategy:

speculative request hedging. Instead of waiting passively, you fire a redundant request to a different replica after a calculated delay, racing the two and taking the winner.

Today, we're bringing this production-grade resilience pattern directly to the Node.js ecosystem with hedge-fetch, an open-source library that implements adaptive, intelligent request hedging to automatically cut your P95 tail latency.

The Theory: From Google's Paper to Your Codebase

Google's paper identified that in large-scale systems, latency variability is inevitable.

A single slow request can be caused by garbage collection on a virtual machine, a noisy neighbor consuming shared resources, a transient network hiccup, or a queue delay.

Their solution was elegant: if a request is taking longer than the typical (e.g., 95th percentile) latency for that operation, it's statistically likely to be a "tail" request.

At that point, issuing a second, "hedged" request to another server replica often results in a faster completion. The key is to trigger this hedge intelligently—not too early (wasting resources), not too late (losing the benefit).

Hedge-fetch is a practical implementation of this theory, designed not for Google's internal C++ infrastructure, but for the everyday Node.js and TypeScript developer using the standard fetch API.

Core Architecture: How Hedge-Fetch Works Under the Hood

At its heart, hedge-fetch is a high-performance wrapper around the Fetch API.

You replace your standard fetch call with hedge.fetch(), and the library manages the complexity. Let's dissect its core mechanisms.

1. The Adaptive P95 Hedge Trigger

Unlike naive implementations that use a fixed timeout (e.g., "hedge after 200ms"), hedge-fetch employs a dynamic, self-learning algorithm.

Its LatencyTracker maintains a rolling window of recent request durations for each distinct operation (identified by a configurable key).

import { HedgedContext, LocalTokenBucket, LatencyTracker } from 'hedge-fetch';

const tracker = new LatencyTracker();
const hedge = new HedgedContext(new LocalTokenBucket(10), tracker);

// The tracker continuously updates P95 latency for this endpoint
const response = await hedge.fetch('https://api.example.com/data');

When a new request is made, the library checks its progress against the current 95th percentile (P95) latency for that endpoint.

If the primary request hasn't responded by the P95 mark, it's flagged as a tail candidate, and the speculative hedge request is dispatched.

This ensures your hedging strategy adapts to the real performance of your backend services.

2. Safe and Idempotent Hedging

Blindly duplicating requests is dangerous, particularly for non-idempotent operations like POST. Hedge-fetch builds in safety:

Safe by Default: Only GET, HEAD, and OPTIONS requests are hedged automatically.
Explicit Consent for POST: To hedge a POST request, you must explicitly set forceHedge: true in the options.
Automatic Idempotency Keys: When hedging unsafe methods, hedge-fetch can automatically generate and attach a unique Idempotency-Key header (UUID). This allows your backend to recognize and deduplicate the parallel requests, preventing double charges or duplicate database entries.

// Hedging a POST request safely
const orderResponse = await hedge.fetch('https://api.example.com/orders', {
  method: 'POST',
  body: orderData,
  forceHedge: true // Explicitly opt-in
  // The library can automatically add an `Idempotency-Key` header
});

3. Resource Management and Zero Leakage

A common fear with speculative requests is resource leakage—dangling connections that waste sockets and memory.

Hedge-fetch uses the modern AbortSignal.any() API to guarantee zero leakage. As soon as one request (primary or hedge) returns a successful response, a combined abort signal immediately terminates all other outstanding requests.

Furthermore, to prevent a thundering herd of hedge requests during a backend slowdown from becoming a self-inflicted DDoS attack, hedge-fetch uses a token bucket rate limiter.

// Start with a 10% hedging budget
const hedge = new HedgedContext(new LocalTokenBucket(10), tracker);

// Or, implement a distributed bucket for a cluster
import { Redis } from 'ioredis';
class RedisBucket implements IHedgeBucket {
  constructor(private redis: Redis) {}
  async canHedge() {
    const tokens = await this.redis.decr('hedge_tokens');
    return tokens >= 0;
  }
}
const globalHedge = new HedgedContext(new RedisBucket(redisClient), tracker);

You can start with a local LocalTokenBucket, which allows, for example, a 10% overhead from hedging. For coordinated fleets of servers, you can plug in a RedisBucket (or any IHedgeBucket implementation) to share a global hedging budget across your entire cluster.

4. Observability and Debugging

You can't improve what you can't measure. Hedge-fetch provides deep visibility into its operations through response metadata and lifecycle hooks.

const response = await hedge.fetch('https://api.example.com/data', {
  onHedge: () => console.log('Hedging triggered!'),
  onPrimaryWin: (ms) => console.log(`Primary won in ${ms}ms`),
  onSpeculativeWin: (ms) => console.log(`Hedge won in ${ms}ms!`),
});

// Check if the response came from the hedge request
if (response.isHedged) {
  console.log('Tail latency was successfully mitigated!');
  metrics.increment('hedge_wins');
}

Putting It All Together: A Real-World Scenario

Imagine an e-commerce page that calls a product info service, a recommendations service, and an inventory service.

The recommendations service has a P95 latency of 85ms but suffers from occasional 1500ms+ tails due to cache misses.

Without hedging, 1 in 20 page loads is slow, dragging down the entire user experience.

With a static 100ms hedging timeout, you'd see improvement but would also double your call volume to that service 5% of the time, regardless of its health.

With hedge-fetch, the behavior is optimized:

The LatencyTracker learns the 85ms P95 for the recommendations endpoint.
For 19 out of 20 requests that finish before 85ms, nothing changes—no extra load.
For the 1 "tail" request that is still pending at 85ms, a hedge request is fired to a different replica.
The faster of the two responses wins (often the hedge, returning in ~90ms), and the loser is aborted.
The user gets their page in ~90ms instead of 1500ms, and the token bucket ensures this hedging doesn't exceed your defined budget across all servers.

Getting Started and Joining the Community

Implementing this cutting-edge resilience pattern is now trivial.

npm install hedge-fetch

We've built hedge-fetch for the Node.js community because everyone deserves production-resilient applications without needing to build and maintain complex infrastructure code.

This project is open source (MIT licensed) and thrives on contributions, ideas, and real-world battle testing.

Ready to banish tail latency from your applications?

Star the GitHub repository to show your support and stay updated.
Install the package: npm install hedge-fetch
Dive into the code, open issues for feature requests, or submit pull requests. Whether it's new bucket implementations, advanced hedging algorithms, or better observability integrations, your input is welcome.

Stop letting the tail wag the dog. Take control of your latency with hedge-fetch.

💡 Have questions? Drop them in the comments!

Why setTimeout Returns an Object in Node.js (and Why setInterval Can Break Your App)

Ali nazari — Sat, 03 Jan 2026 21:52:47 +0000

At first glance, JavaScript timers look simple: setTimeout and setInterval schedule work for later.

But once you move from the browser to Node.js, a subtle difference appears—setTimeout no longer returns a number, it returns an object.

This difference is not cosmetic, nor is it a TypeScript quirk. It reflects a deep design choice in Node.js around process lifecycle management, server reliability, and graceful shutdowns.

This post explains, in depth, why Node.js timers return objects, how ref() and unref() work, and why setInterval is significantly more dangerous than setTimeout in backend systems.

Browser Timers vs Node.js Timers

In browsers, timers are part of the Web APIs. Calling setTimeout returns a numeric identifier:

const id = setTimeout(fn, 1000);

That number is merely a lookup key. The browser maintains an internal timer table and uses the number to cancel the timer if needed.

The browser itself is already running a UI event loop, so timers have no influence over whether the environment stays alive.

Node.js operates under very different constraints.

Node.js Is a Process That Must Decide When to Exit

Node.js typically runs as a server or CLI process. Unlike a browser, it must continuously answer a critical question:

“Is there any work left that requires me to stay alive?”

To answer that, Node tracks active resources:

open servers
open sockets
file descriptors
timers

If no active resources remain, Node exits.

This is the key reason Node timers are not just numbers.

Why `setTimeout` Returns an Object in Node.js

In Node.js, setTimeout returns a timer handle object (commonly typed as NodeJS.Timeout). This object represents a real, registered resource in the event loop.

Because it is an object, it can:

participate in lifecycle tracking
influence whether the process stays alive
expose methods that change that behavior

A numeric ID cannot do any of that.

The Meaning of `ref()` and `unref()`

Default behavior: timers are “ref’d”

By default, every timer created with setTimeout or setInterval is ref’d.

Conceptually, this means:

“This timer is important. Do not let the process exit until it is done.”

This is why the following code keeps Node alive for 10 seconds:

setTimeout(() => {
  console.log("done");
}, 10_000);

Calling ref() explicitly is unnecessary because this behavior is already the default.

`unref()`: making a timer optional

Calling unref() changes the timer’s role:

const t = setTimeout(task, 10_000);
t.unref();

Now the timer says:

“If I am the only thing left, do not wait for me.”

If all other resources are gone, Node will exit immediately, and the timer may never fire. This is intentional and extremely useful for background or best-effort work.

`ref()`: undoing `unref()`

The ref() method exists solely to reverse unref():

t.ref();

You typically only call ref() in:

libraries
reusable infrastructure code
situations where timer importance changes dynamically

In normal application code, calling ref() manually is almost always unnecessary.

Why `setInterval` Is Riskier Than `setTimeout`

The core difference is simple but critical:

setTimeout runs once and cleans itself up
setInterval runs forever unless explicitly stopped

Lifecycle implications

A setTimeout:

registers a timer
fires once
unregisters itself
stops keeping the process alive

A setInterval:

registers a timer
fires repeatedly
never unregisters itself
keeps the process alive indefinitely

If you forget about a setTimeout, the problem ends on its own.
If you forget about a setInterval, the process may never exit.

The Silent Production Bug

This code looks harmless:

setInterval(() => {
  collectMetrics();
}, 60_000);

But during shutdown:

HTTP servers close
database connections close
all real work is done

Yet the process hangs.

Why? Because the interval is still ref’d and still alive.

Unless you:

clearInterval(interval);

or:

interval.unref();

Node has no reason to exit.

Overlapping Execution: Another `setInterval` Hazard

setInterval does not care whether the previous execution finished:

setInterval(async () => {
  await slowTask(); // takes 10s
}, 5_000);

This leads to overlapping executions, which can cause:

race conditions
unbounded concurrency
memory growth
database overload

Why Recursive `setTimeout` Is Safer

A common and safer pattern is:

async function loop() {
  await slowTask();
  setTimeout(loop, 5_000);
}

loop();

This guarantees:

no overlap
predictable pacing
natural cleanup
safer shutdown behavior

This pattern aligns better with Node’s lifecycle model.

Best Practices Summary

Node timers return objects because they are real event-loop resources
Timers are ref()’d by default
Use unref() for background or best-effort tasks
Avoid setInterval unless you fully control its lifecycle
Prefer recursive setTimeout for repeated async work
Always think about shutdown behavior in server code

💡 Have questions? Drop them in the comments!

Bulletproof Your Node.js Applications with Resilia: A Lightweight Resilience Stack

Ali nazari — Sun, 28 Dec 2025 19:40:50 +0000

Building distributed systems in Node.js often feels like walking a tightrope.

One slow database query or a flickering third-party API can cascade into a complete system outage. While there are heavy frameworks out there to handle these issues, sometimes you just want a clean, simple tool that stays out of your way.

Enter Resilia.

I created Resilia to solve a specific problem: adding professional-grade resilience patterns to TypeScript applications without the bloat.

It is a zero-dependency, decorator-based library that wraps your critical methods in a protective layer of stability.

If you are tired of writing repetitive try-catch-retry logic or manually managing concurrency limits, this tool is for you.

The Problem: Fragile Architectures

In a microservices environment, failures are not a matter of "if," but "when." Network packets get lost, services get overloaded, and databases time out.

Without a proper resilience strategy, a single failing component can exhaust your thread pool or connection limit, bringing your entire application to a halt.

To prevent this, you typically need three things:

Circuit Breakers to stop calling a failing service.
Retries to handle temporary blips.
Bulkheads to limit how many requests run in parallel.

Wiring these up manually for every function is tedious and error-prone. Resilia automates this entire stack.

Meet Resilia

Resilia is designed around the "Matryoshka" security model—a three-layered approach to protecting your code execution. It uses TypeScript decorators to apply these layers declaratively.

You do not need to wrap your code in callbacks or complex configuration objects. You simply tag your method, and Resilia handles the rest.

Layer 1: The Circuit Breaker

This is your outer defense. It acts like a safety switch in your electrical panel. If a service starts failing consistently (for example, exceeding a 50% error rate), the circuit "trips" and opens.

When open, Resilia immediately rejects new requests without even trying to execute the underlying function. This prevents your system from wasting resources on a dead service and gives the failing subsystem time to recover.

After a set sleep window, it allows a single test request through (Half-Open state) to check if health has been restored.

Layer 2: Intelligent Retries

Middle-layer protection handles transient errors—those one-off network glitches that vanish if you just try again. However, blind retries can lead to a "thundering herd" problem where your retries D-DoS your own server.

Resilia uses an Exponential Backoff strategy with Jitter. It waits longer between each attempt and adds a bit of randomness to the timing.

This ensures that if multiple clients fail at once, they do not all hit the server again at the exact same millisecond.

Layer 3: The Bulkhead

The inner layer is about resource isolation. It limits the number of concurrent executions for a specific method. If you have a heavy reporting query, you can restrict it to 5 simultaneous runs.

Additional requests queue up until a slot opens. This guarantees that one slow feature never hogs all your server's CPU or memory.

How to Use It

The best part of Resilia is the developer experience. It requires minimal setup.

First, install the package:

npm install resilia reflect-metadata

Then, use the @Resilient decorator on any class method:

import { Resilient } from 'resilia';

class PaymentService {
  @Resilient({
    concurrency: 5,        // Max 5 simultaneous requests
    queue: 10,             // Max 10 waiting in line
    maxRetries: 3,         // Try 3 times before failing
    errorThreshold: 0.5,   // Trip circuit if >50% fail
    sleepWindowMs: 30000   // Rest for 30s when tripped
  })
  async processTransaction(id: string) {
    // Your critical business logic here
    return await db.payments.create({ id });
  }
}

That is it. Your processTransaction method is now protected by a circuit breaker, a bulkhead, and a smart retry mechanism.

Observability Built-In

You cannot improve what you cannot measure. Resilia is built with observability in mind. Every component is an event emitter, allowing you to hook into state changes and metrics in real-time.

You can listen for circuit state changes (like going from Closed to Open) or track when the bulkhead queue rejects a request. This makes it trivial to integrate with monitoring tools like Prometheus or Grafana.

import { resilienceRegistry } from 'resilia';

// Monitor your application health
resilienceRegistry.forEach(({ breaker, bulkhead }, key) => {
    breaker.on('state:changed', (event) => {
        console.log(`Circuit ${key} changed state to ${event.to}`);
    });
});

Why Resilia?

Zero Dependencies: It keeps your node_modules light and your security footprint small.
Performance: It is lightweight and designed to add negligible overhead to your calls.
TypeScript Native: It leverages decorators for a clean, modern syntax.

Support the Project

I built Resilia to make robust Node.js development accessible to everyone. If you find this tool useful or if the code helps you learn more about resilience patterns, please consider supporting the project.

Check out the code and give it a Star on GitHub:

https://github.com/Silent-Watcher/resilia

Your stars help others discover the tool and motivate me to keep adding features like rate limiting and advanced timeout strategies.

💡 Have questions? Drop them in the comments!

Implementing a Circuit Breaker in Node.js

Ali nazari — Tue, 23 Dec 2025 17:26:13 +0000

A circuit breaker prevents an application from repeatedly invoking an operation that is likely to fail (for example, a downstream service or external API).

Instead of continually waiting for timeouts and consuming resources, the circuit breaker trips after a measured failure threshold and begins rejecting requests immediately; after a cooldown it allows a small number of test requests (half-open) to check recovery.

This prevents cascading failures, reduces wasted concurrency and latency, and gives operators a clear signal when a downstream service is unhealthy.

The provided implementation encodes a classical three-state circuit breaker and a time-based sliding window implemented as short duration buckets:

States: Closed (normal), Open (reject requests), HalfOpen (allow test requests). (Enum CircuitState.)
Metrics:

buckets: HealthBucket[] — each bucket counts successes and failures and has a timestamp. The code creates 1s buckets and keeps a rolling window (30s) of buckets; it computes error rate across the window. This is a time-based sliding window implementation.

Config: threshold (error rate), minRequests (minimum calls before evaluation), sleepWindowMs (how long to stay Open), and lastTripTime. (Constructor defaults: 50% threshold, 10 minRequests, 30s sleep window.)

Walkthrough

Key fields and constructor:

private state: CircuitState = CircuitState.Closed
private buckets: HealthBucket[] = []

constructor(
  private threshold: number = 0.5,
  private minRequests: number = 10,
  private sleepWindowMs: number = 30000,
  private lastTripTime: number = 0
) { super(); }

Meaning:

state holds the current breaker state.

buckets holds recent 1-second buckets with { successes, failures, timestamp }.

threshold and minRequests control sensitivity: only when the count of requests exceeds minRequests will the breaker evaluate whether failures / total > threshold.

The minRequests guard avoids tripping on tiny sample sizes (this is a common parameter in mature libraries like Resilience4j).

sleepWindowMs is the cooldown used to move Open -> HalfOpen for a trial.

`execute` method

public async execute<T>(task: () => Promise<T>): Promise<T> {
  this.updateState();

  if (this.state === CircuitState.Open) {
    throw new Error("Circuit is OPEN: Request rejected to protect the system.");
  }

  try {
    const result = await task();
    this.record(true);
    return result;
  } catch (error) {
    this.record(false);
    throw error;
  }
}

State refresh: updateState() is called at the start to transition Open -> HalfOpen if the sleep window has elapsed. This ensures the breaker can try recovery attempts.
Fail-fast: If the circuit is Open, the method immediately throws — the service caller receives an immediate failure and the protected call is not made.

This implements the "fast fail" behavior.

Instrumentation: On success or failure, record(...) is invoked to update metrics and (possibly) change state.

Note: the implementation records after the underlying promise completes. That is the correct semantic: success/failure must reflect the outcome of the protected operation.

Edge concerns

In HalfOpen, execute still allows a request through (because state is not Open), but the implementation relies on record to decide whether to Close or Open again.

There is no throttling or token bucket—every request during HalfOpen becomes a single trial.

Production breakers normally restrict trial attempts to a small number to avoid hammering the recovering system. See suggested improvements below.

`record` method

Relevant excerpt (paraphrased):

it gets the active bucket, increments successes or failures, checks thresholds, and handles HalfOpen special-case logic (if success -> close and clear buckets; if fail -> open and set lastTripTime).

public record(success: boolean) {
        const bucket = this.getActiveBucket();

        if (this.state === CircuitState.HalfOpen) {
            if (success) {
                this.state = CircuitState.Closed;
                this.buckets = [];
                console.log("Circuit is CLOSED System recovered!");
            } else {
                this.state = CircuitState.Open;
                this.lastTripTime = Date.now(); // Reset the clock for a new rest period
                console.warn("Test failed. Circuit back to OPEN.");
            }
            this.emit('state:changed', {
                from: CircuitState.HalfOpen,
                to: CircuitState[this.state],
                timestamp: Date.now()
            })
            return;
        }

        if (success) {
            bucket.successes++;
        } else {
            bucket.failures++
        }

        this.checkThreshold();
    }

Behavioral details:

Handling HalfOpen: If the state is HalfOpen, the first recorded success immediately transitions to Closed and clears recorded buckets — effectively "we recovered".

A single failure during HalfOpen sets state back to Open and restarts the cooldown.

This is a simple and valid policy, but it's aggressive: one success immediately restores traffic.

Depending on your risk profile you may prefer: require N consecutive successes to close, or allow a limited number of trial calls and evaluate a small sample.

Recording in Closed: For normal operation, record increments counters in the active bucket and calls checkThreshold() to decide whether to trip.

Potential race conditions

Multiple concurrent calls to record mutate buckets and state.

Node’s single-threaded model reduces classical race conditions, but asynchronous interleaving still allows inconsistent reads and writes across multiple execute invocations.

For high-concurrency scenarios, consider light synchronization (e.g., atomic updates via a short critical section) or single-threaded eventing for metric updates.

`checkThreshold` method

Algorithm:

If not Closed, return (only evaluate while Closed).
Sum successes and failures across buckets.
If totalRequest > minRequests, compute errorRate = failures / totalRequest.
If errorRate > threshold, call trip().

   private checkThreshold() {
        if (this.state !== CircuitState.Closed) return;

        const totals = this.buckets.reduce((acc, b) => ({

            s: acc.s + b.successes,
            f: acc.f + b.failures

        }), { s: 0, f: 0 })

        const totalRequest = totals.s + totals.f;

        if (totalRequest > this.minRequests) {
            const errorRate = totals.f / totalRequest
            if (errorRate > this.threshold) {
                this.trip();
            }
        }
    }

`getActiveBucket` method - sliding window logic

Key behavior:

Each call uses now = Date.now().
Buckets are 1s (bucketDurationMs = 1000).
If existing last bucket is still within its 1s window, that bucket is reused; otherwise a new bucket is pushed.
The buckets array is then filtered to retain only buckets within the rolling window (hardcoded windowSizeMs = 30000 — 30s), i.e., now - windowSizeMs < b.timestamp.

This is a standard time-based sliding window implemented with fixed-size time buckets. It’s readable and efficient for moderate throughput. Key choices to review:

bucketDurationMs controls granularity — smaller yields more precise temporal resolution but more buckets.
windowSizeMs controls the complete window over which you compute error rate (here hardcoded 30s; could be parameterized).

    private getActiveBucket(): HealthBucket {
        const now = Date.now();

        const bucketDurationMs = 1000;

        const lastBucket = this.buckets[this.buckets.length - 1];

        if (lastBucket && now < lastBucket.timestamp + bucketDurationMs) {
            return lastBucket;
        }

        const newBucket: HealthBucket = { failures: 0, successes: 0, timestamp: now }
        this.buckets.push(newBucket);

        const windowSizeMs = 30000;
        this.buckets = this.buckets.filter(b => now - windowSizeMs < b.timestamp)

        return newBucket

    }

The function both returns the active bucket and prunes stale buckets; that keeps memory bounded.

time-based bucketed sliding windows are a common approach used in circuit breaker implementations and routers.

`trip` method

Behavior:

Save oldState.
Set state = Open, set lastTripTime = Date.now().
Emit state:changed with { from, to, timestamp }.
Log a warning.

  private trip() {
        const oldState = this.state;
        this.state = CircuitState.Open;
        this.lastTripTime = Date.now();
        console.warn("Circuit Breaker TRIP! State is now OPEN.");
        this.emit('state:changed', {
            from: oldState,
            to: CircuitState.Open,
            timestamp: Date.now()
        })
    }

This is straightforward. Emitting an event gives you a hook for metrics, alerts or side effects (for example, increase a Prometheus counter, or trigger alerting in SRE workflows).

The class extends EventEmitter expressly for this reason.

`updateState()` method - `Open -> HalfOpen` transition

Logic:

If state === Open and (Date.now() - lastTripTime) > sleepWindowMs, transition to HalfOpen, emit state:changed, and log.

This implements the cooldown:

after sleepWindowMs elapses, try again. In HalfOpen, the class expects the next real request(s) to determine whether to close or open again (via record).

the whole picture

import EventEmitter from "node:events";

enum CircuitState {
    Open,
    Closed,
    HalfOpen
}

interface HealthBucket {
    successes: number;
    failures: number;
    timestamp: number; // To know when this bucket expires
}


export class CircuitBreaker extends EventEmitter {
    private state: CircuitState = CircuitState.Closed
    private buckets: HealthBucket[] = []


    constructor(
        private threshold: number = 0.5, // 50% failure rate
        private minRequests: number = 10,
        private sleepWindowMs: number = 30000, // 30s to stay Open
        private lastTripTime: number = 0
    ) {
        super();
    }


    public async execute<T>(task: () => Promise<T>): Promise<T> {
        this.updateState();

        if (this.state === CircuitState.Open) {
            throw new Error("Circuit is OPEN: Request rejected to protect the system.");
        }

        try {
            const result = await task();
            this.record(true);
            return result;
        } catch (error) {
            this.record(false);
            throw error;
        }
    }

    public record(success: boolean) {
        const bucket = this.getActiveBucket();

        if (this.state === CircuitState.HalfOpen) {
            if (success) {
                this.state = CircuitState.Closed;
                this.buckets = [];
                console.log("Circuit is CLOSED System recovered!");
            } else {
                this.state = CircuitState.Open;
                this.lastTripTime = Date.now(); // Reset the clock for a new rest period
                console.warn("Test failed. Circuit back to OPEN.");
            }
            this.emit('state:changed', {
                from: CircuitState.HalfOpen,
                to: CircuitState[this.state],
                timestamp: Date.now()
            })
            return;
        }

        if (success) {
            bucket.successes++;
        } else {
            bucket.failures++
        }

        this.checkThreshold();
    }

    // to check if the request is allowed
    public isOpen(): boolean {
        return this.state === CircuitState.Open;
    }

    private getActiveBucket(): HealthBucket {
        const now = Date.now();

        const bucketDurationMs = 1000;

        const lastBucket = this.buckets[this.buckets.length - 1];

        if (lastBucket && now < lastBucket.timestamp + bucketDurationMs) {
            return lastBucket;
        }

        const newBucket: HealthBucket = { failures: 0, successes: 0, timestamp: now }
        this.buckets.push(newBucket);

        const windowSizeMs = 30000;
        this.buckets = this.buckets.filter(b => now - windowSizeMs < b.timestamp)

        return newBucket

    }

    private checkThreshold() {
        if (this.state !== CircuitState.Closed) return;

        const totals = this.buckets.reduce((acc, b) => ({

            s: acc.s + b.successes,
            f: acc.f + b.failures

        }), { s: 0, f: 0 })

        const totalRequest = totals.s + totals.f;

        if (totalRequest > this.minRequests) {
            const errorRate = totals.f / totalRequest
            if (errorRate > this.threshold) {
                this.trip();
            }
        }
    }

    private trip() {
        const oldState = this.state;
        this.state = CircuitState.Open;
        this.lastTripTime = Date.now();
        console.warn("Circuit Breaker TRIP! State is now OPEN.");
        this.emit('state:changed', {
            from: oldState,
            to: CircuitState.Open,
            timestamp: Date.now()
        })
    }

    private updateState() {
        const oldState = this.state;
        if (this.state === CircuitState.Open && Date.now() - this.lastTripTime > this.sleepWindowMs) {
            this.state = CircuitState.HalfOpen
            console.log("Circuit is HALF-OPEN. Testing the waters...");
            this.emit('state:changed', {
                from: oldState,
                to: CircuitState.HalfOpen,
                timestamp: Date.now()
            })
        }

    }
}

How to use this class

Small usage example (consumer side):

const breaker = new CircuitBreaker();

breaker.on('state:changed', info => {
  console.log('breaker', info);
});

async function callRemote() {
  return breaker.execute(async () => {
    // call the downstream API, e.g. fetch/axios
    return await fetchSomeApi();
  });
}

Because execute throws immediately when the breaker is Open, callers should handle that and optionally provide fallbacks.

For example, return cached results or degrade features rather than retrying aggressively.

💡 Have questions? Drop them in the comments!

Implementing the Bulkhead Pattern in Node.js

Ali nazari — Tue, 16 Dec 2025 11:41:09 +0000

Implementing the Bulkhead Pattern in Node.js

Introduction to System Resilience

In a distributed system or a microservices architecture, a single failing component can cause a ripple effect that brings down an entire application.

This is often seen when a database or downstream service becomes slow. Incoming requests continue to stack up, consuming memory and CPU cycles until the Node.js event loop is exhausted.

The Bulkhead pattern is a structural design used to isolate critical resources.

By limiting the number of concurrent operations allowed to reach a specific resource (like a database), we ensure that a spike in traffic or a slowdown in the database does not consume all available server resources.

The Core Mechanism: Semaphores

A semaphore is the synchronization primitive used to implement a Bulkhead. Unlike a Mutex, which allows only one task to proceed at a time, a semaphore allows a defined number of concurrent tasks (N).

In a Node.js context, we use a semaphore to manage:

Counter: Tracks how many asynchronous operations are currently in progress.
Queue: Stores the "resolve" functions of Promises for tasks that arrived after the concurrency limit was reached.
Wait (P) / Signal (V): Operations that respectively request a slot or release a slot.

Step-by-Step Implementation

1. Defining the Bulkhead Class

The class requires a concurrencyLimit to define the maximum simultaneous operations and a queueLimit to prevent memory exhaustion from an infinite waiting line.

class Bulkhead {
  constructor(concurrencyLimit, queueLimit = 100) {
    this.concurrencyLimit = concurrencyLimit;
    this.queueLimit = queueLimit;
    this.activeCount = 0;
    this.queue = [];
  }

  async run(task) {
    // Admission Control and Wait Logic
    if (this.activeCount >= this.concurrencyLimit) {
      if (this.queue.length >= this.queueLimit) {
        throw new Error("Bulkhead capacity exceeded: Server Busy");
      }

      await new Promise((resolve) => {
        this.queue.push(resolve);
      });
    }

    this.activeCount++;

    try {
      // Execution of the asynchronous task
      return await task();
    } finally {
      // Release Logic
      this.activeCount--;
      if (this.queue.length > 0) {
        const nextInLine = this.queue.shift();
        nextInLine();
      }
    }
  }
}

2. Protecting the Database Layer

Using Mongoose or any other ORM, the database call is wrapped in the run method. This ensures that even if 1,000 requests hit the API endpoint simultaneously, only a controlled number actually hit the database.

const dbBulkhead = new Bulkhead(5, 10);

app.get('/data', async (req, res) => {
  try {
    const result = await dbBulkhead.run(() => User.find().lean());
    res.json(result);
  } catch (error) {
    res.status(503).json({ message: error.message });
  }
});

Key Technical Takeaways

Fail-Fast (Admission Control): By checking the queue.length, we reject requests immediately (HTTP 503) rather than letting them hang and consume RAM.
Error Isolation: The finally block is critical. It ensures that if a database query fails or throws an exception, the activeCount is still decremented, allowing the next task in the queue to proceed.
Resource Management: In microservices, the concurrency limit should be calculated as Total DB Connections / Number of Service Instances.

💡 Have questions? Drop them in the comments!

Why Custom JavaScript Errors Create Messy Stack Traces and How Error.captureStackTrace Fixes Them

Ali nazari — Fri, 05 Dec 2025 16:12:42 +0000

When building robust JavaScript applications, error handling is not just about catching exceptions—it's about creating meaningful, debuggable error experiences.

While many developers extend the native Error class, few understand the critical piece of code that makes custom errors truly professional: Error.captureStackTrace

This powerful, V8-specific method transforms your error handling from functional to exceptional, providing clean, actionable stack traces that streamline debugging.

The Problem with Basic Custom Errors

Let's start with a common pattern for creating custom errors:

class DatabaseError extends Error {
  constructor(message) {
    super(message);
    this.name = 'DatabaseError';
  }
}

// When thrown, the stack trace includes unwanted frames:
// DatabaseError: Connection failed
//     at new DatabaseError (file.js:3:5)  <-- Unnecessary noise
//     at connectToDatabase (file.js:10:9) <-- Actual error origin
//     at main (file.js:15:3)

The issue is clear:

the stack trace includes the error constructor itself, adding noise that obscures the actual error source.

This becomes particularly problematic in complex applications where errors might be instantiated deep within helper functions or libraries.

Understanding Error.captureStackTrace

Error.captureStackTrace is a V8 engine API (available in Node.js and Chrome) that programmatically captures the current call stack. Its signature is straightforward:

Error.captureStackTrace(targetObject, constructorOpt)

// Typical usage in custom error classes:
Error.captureStackTrace(this, this.constructor);

targetObject: The object (typically an error instance) to attach the stack trace to
constructorOpt: Optional constructor function whose frames should be omitted from the stack trace

How it works:

When called, Error.captureStackTrace captures the current JavaScript call stack.
It attaches this stack trace to the targetObject as a .stack property.
The constructorOpt parameter tells V8: "When generating the stack trace, start from the frame that called this constructor, and omit all frames from this constructor upward."
By passing this.constructor, we're saying: "Start the stack trace from wherever new MyError() was called, not from inside the MyError constructor itself."

Visualizing the stack manipulation:

Original call stack:                          After captureStackTrace:
1. SomeFunction()                             1. SomeFunction()
2. AnotherFunction()                          2. AnotherFunction()
3. new MyError() <-- constructor called       3. new MyError() <-- Omitted!
4. MyError constructor logic                  4. (Hidden from stack trace)
5. Error.captureStackTrace()                  5. (Hidden from stack trace)

Implementing Professional Custom Errors

Here's the complete pattern for production-ready custom errors:

class ApplicationError extends Error {
  constructor(message, options = {}) {
    super(message);

    // Set the error name to the class name
    this.name = this.constructor.name;

    // Additional error properties
    this.timestamp = new Date().toISOString();
    this.code = options.code || 'INTERNAL_ERROR';
    this.details = options.details || {};

    // Capture the stack trace, excluding this constructor
    if (Error.captureStackTrace) {
      Error.captureStackTrace(this, this.constructor);
    } else {
      // Fallback for non-V8 environments
      this.stack = (new Error()).stack;
    }
  }

  toJSON() {
    return {
      name: this.name,
      message: this.message,
      code: this.code,
      timestamp: this.timestamp,
      stack: process.env.NODE_ENV === 'development' ? this.stack : undefined
    };
  }
}

super(message): Always call the parent constructor first. This establishes the error inheritance chain properly.
this.name = this.constructor.name: Dynamic naming ensures if you refactor the class name, the error name updates automatically. This is better than hardcoding 'ApplicationError'.
this.timestamp: Crucial for debugging distributed systems where errors might be logged at different times.
this.code: Error codes (like 'VALIDATION_ERROR', 'AUTH_ERROR') allow programmatic error handling without parsing error messages.
Error.captureStackTrace check: Essential for cross-environment compatibility since not all JavaScript engines support this method.
toJSON() method: Provides consistent error serialization. The conditional stack trace prevents exposing internal implementation details in production.

Real-World Use Cases

Database Layer Errors

Here's how to implement a database-specific error with contextual information:

class DatabaseError extends ApplicationError {
  constructor(message, query, originalError) {
    // Call parent with enhanced message and error code
    super(message, { code: 'DATABASE_ERROR' });

    // Store the original SQL query that failed
    // This is invaluable for debugging SQL issues
    this.query = query;

    // Store the underlying database driver error
    // This preserves the original error chain
    this.originalError = originalError;

    // Provide helpful suggestions for common issues
    this.suggestion = 'Check your connection string and database permissions';

    // Add query metadata for performance debugging
    this.queryMetrics = {
      timestamp: new Date().toISOString(),
      estimatedRows: null, // Could be populated if available
      executionPlan: null  // Could store query plan if available
    };
  }

  // Override toJSON to include database-specific fields
  toJSON() {
    const baseJson = super.toJSON();
    return {
      ...baseJson,
      query: this.maskSensitiveData(this.query), // Security: mask sensitive data
      suggestion: this.suggestion,
      originalError: this.originalError?.message
    };
  }

  // Helper method to mask sensitive data in queries
  maskSensitiveData(query) {
    // Simple example: mask password values in SQL
    return query.replace(/password\s*=\s*'[^']*'/gi, "password = '***'");
  }
}

async function queryUser(userId) {
  try {
    // Simulated database operation
    const sql = `SELECT * FROM users WHERE id = ${userId} AND password = 'secret'`;

    // This might fail for various reasons
    throw new Error('Connection timeout: database server not responding');

  } catch (dbErr) {
    // Wrap the original database error with our custom error
    throw new DatabaseError(
      `Failed to fetch user ${userId} from database`,
      sql, // Pass the actual SQL for debugging
      dbErr // Preserve the original error
    );
  }
}

Key aspects of this implementation:

Error chaining: Preserves the original database driver error, maintaining the full error context.
Sensitive data masking: Protects sensitive information when logging or serializing errors.
Contextual metadata: Includes query information that helps database administrators debug issues.
Actionable suggestions: Provides guidance for common resolution steps.

API Validation Errors

For API development, validation errors need to provide structured information about what failed:

class ValidationError extends ApplicationError {
  constructor(field, value, constraints) {
    // Create a human-readable message
    const message = `Validation failed for field "${field}" with value "${value}"`;

    // Call parent with validation-specific code
    super(message, { code: 'VALIDATION_ERROR' });

    // Store validation context
    this.field = field;
    this.value = typeof value === 'string' && value.length > 50 
      ? value.substring(0, 47) + '...' // Truncate long values
      : value;
    this.constraints = constraints; // e.g., { required: true, minLength: 5 }
    this.statusCode = 422; // HTTP 422 Unprocessable Entity

    // Add path for nested validations (e.g., 'user.address.city')
    this.path = field;

    // Add validation type for client-side handling
    this.type = this.determineValidationType(constraints);
  }

  determineValidationType(constraints) {
    if (constraints.required) return 'required';
    if (constraints.pattern) return 'pattern';
    if (constraints.min || constraints.max) return 'range';
    if (constraints.minLength || constraints.maxLength) return 'length';
    return 'custom';
  }

  // Format error for API response
  toAPIResponse() {
    return {
      error: {
        message: this.message,
        code: this.code,
        field: this.field,
        constraints: this.constraints,
        type: this.type
      }
    };
  }
}

// Usage in an Express.js middleware
function validateEmail(email) {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

  if (!email) {
    throw new ValidationError('email', email, {
      required: true,
      message: 'Email is required'
    });
  }

  if (!emailRegex.test(email)) {
    throw new ValidationError('email', email, {
      pattern: 'Must be a valid email address',
      example: 'user@example.com',
      message: 'Invalid email format'
    });
  }

  if (email.length > 254) {
    throw new ValidationError('email', email, {
      maxLength: 254,
      message: 'Email must be less than 255 characters'
    });
  }
}

Why this structure is effective:

Structured constraints: Each validation rule is explicitly defined, making it easy for frontend clients to display specific error messages.
Value truncation: Long values are truncated in error messages to prevent log flooding.
HTTP status codes: Integration with web frameworks is seamless because the error knows its appropriate HTTP status.
Type categorization: Categorizing validation types helps clients apply consistent error styling.

Advanced Patterns

Error Factory Functions

Sometimes you need to create errors from utility functions while maintaining clean stack traces. Factory functions are perfect for this:

function createValidationError(field, message, constraints = {}) {
  // Create a base error
  const error = new Error(message);

  // Set standard properties
  error.name = 'ValidationError';
  error.field = field;
  error.code = 'VALIDATION_ERROR';
  error.constraints = constraints;
  error.timestamp = new Date().toISOString();

  // The key insight: remove the factory function from stack trace
  if (Error.captureStackTrace) {
    // Note: We pass the factory function itself as constructorOpt
    // This removes createValidationError from the stack
    Error.captureStackTrace(error, createValidationError);
  }

  return error;
}

// Compare stack traces:
function processForm(data) {
  if (!data.username) {
    // Option 1: Direct instantiation
    const error1 = new ValidationError('username', 'Username is required');
    console.log('Direct instantiation:', error1.stack.split('\n')[1]);

    // Option 2: Factory function
    const error2 = createValidationError('username', 'Username is required');
    console.log('Factory function:', error2.stack.split('\n')[1]);
  }
}

// Output might look like:
// Direct instantiation:     at new ValidationError (errors.js:10:15)
// Factory function:         at processForm (app.js:25:20)  <-- Cleaner!

Benefits of factory functions:

Consistent error creation: Ensures all validation errors have the same structure.
Cleaner stack traces: The factory function itself is omitted, pointing directly to where the error condition was detected.
Reduced boilerplate: Encapsulates common error setup logic.
Flexibility: Can include additional logic like validation rule checking, sanitization, or logging.

Hierarchical Error Systems

For large applications, consider implementing a hierarchical error system that categorizes errors by domain:

// Base error with common functionality
class BaseError extends Error {
  constructor(message, options = {}) {
    super(message);

    // Automatic name assignment
    this.name = this.constructor.name;

    // Common properties for all errors
    this.statusCode = options.statusCode || 500;
    this.isOperational = options.isOperational !== false; // Distinguishes programmer errors
    this.timestamp = new Date().toISOString();
    this.context = options.context || {};

    // Capture stack trace
    if (Error.captureStackTrace) {
      Error.captureStackTrace(this, this.constructor);
    }

    // Generate unique error ID for tracking
    this.errorId = this.generateErrorId();
  }

  generateErrorId() {
    // Generate a unique ID for error correlation
    return `err_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
  }

  // Log the error with context
  log(logger) {
    logger.error({
      errorId: this.errorId,
      name: this.name,
      message: this.message,
      statusCode: this.statusCode,
      timestamp: this.timestamp,
      stack: this.stack,
      context: this.context
    });
  }
}

// Client errors (4xx)
class ClientError extends BaseError {
  constructor(message, options = {}) {
    // Default to 400 Bad Request for client errors
    super(message, { 
      ...options, 
      statusCode: options.statusCode || 400,
      isOperational: true // Client errors are usually operational
    });
  }
}

// Server errors (5xx)
class ServerError extends BaseError {
  constructor(message, options = {}) {
    // Default to 500 Internal Server Error
    super(message, { 
      ...options, 
      statusCode: options.statusCode || 500,
      isOperational: options.isOperational !== undefined ? options.isOperational : true
    });
  }
}

// Domain-specific errors
class NotFoundError extends ClientError {
  constructor(resource, identifier, options = {}) {
    const message = `${resource} with ID ${identifier} not found`;
    super(message, {
      statusCode: 404,
      ...options,
      context: {
        ...options.context,
        resource,
        identifier,
        suggestion: `Check that the ${resource} exists and you have access`
      }
    });
  }
}

class AuthenticationError extends ClientError {
  constructor(message = 'Authentication required', options = {}) {
    super(message, {
      statusCode: 401,
      ...options,
      context: {
        ...options.context,
        suggestion: 'Check your credentials or login again'
      }
    });
  }
}

class DatabaseError extends ServerError {
  constructor(message, query, originalError, options = {}) {
    super(message, {
      code: 'DATABASE_ERROR',
      ...options,
      context: {
        ...options.context,
        query,
        originalError: originalError?.message,
        database: process.env.DB_NAME || 'unknown',
        suggestion: 'Check database connection and permissions'
      }
    });

    this.query = query;
    this.originalError = originalError;
  }
}

Hierarchy benefits:

Categorization: Clear separation between client errors (user's fault) and server errors (system's fault).
HTTP integration: Each error knows its appropriate HTTP status code.
Operational vs programmer errors: Distinguishes expected errors (like validation failures) from bugs.
Context inheritance: Each level can add context appropriate to its domain.

Performance Considerations

While Error.captureStackTrace adds minimal overhead, consider these optimizations for high-performance applications:

class OptimizedError extends Error {
  constructor(message, options = {}) {
    super(message);
    this.name = this.constructor.name;

    // Lazy stack trace generation
    // Only capture stack when accessed
    this._stack = null;
    this._stackCaptured = false;

    // Store options for lazy processing
    this._options = options;
    this._code = options.code;
    this._details = options.details;
  }

  // Override stack getter
  get stack() {
    if (!this._stackCaptured) {
      if (Error.captureStackTrace) {
        const target = {};
        Error.captureStackTrace(target, this.constructor);
        this._stack = `${this.name}: ${this.message}\n${target.stack}`;
      } else {
        this._stack = super.stack;
      }
      this._stackCaptured = true;
    }
    return this._stack;
  }

  set stack(value) {
    this._stack = value;
    this._stackCaptured = true;
  }

  // Lazy property initialization
  get code() {
    if (this._code === undefined) {
      this._code = this._options.code || 'ERROR';
    }
    return this._code;
  }

  get details() {
    if (this._details === undefined) {
      this._details = this._options.details || {};
    }
    return this._details;
  }

  // Performance optimization: batch property access
  hydrate() {
    // Force initialization of all lazy properties
    const _ = this.code;
    const __ = this.details;
    const ___ = this.stack;
    return this;
  }
}

// Usage in performance-critical code
function processBatch(items) {
  const errors = [];

  for (const item of items) {
    try {
      validateItem(item);
    } catch (err) {
      if (err instanceof OptimizedError) {
        // Defer stack trace generation until needed
        errors.push(err);
      } else {
        // For non-optimized errors, capture immediately
        errors.push(new OptimizedError(err.message, { 
          code: 'VALIDATION_ERROR',
          details: { item }
        }));
      }
    }
  }

  // Only hydrate errors if we need to process them
  if (errors.length > 0) {
    return errors.map(err => err.hydrate());
  }

  return null;
}

Performance optimization techniques:

Lazy stack generation: Only capture stack traces when they're actually accessed.
Lazy property initialization: Defer processing of options until properties are accessed.
Batched hydration: Provide a method to initialize all properties at once when needed.
Selective error creation: Only create full error objects when necessary.

Integration with Logging Systems

Custom errors shine when integrated with structured logging systems. Here's a comprehensive example:

class LoggableError extends ApplicationError {
  constructor(message, options = {}) {
    super(message, options);

    // Additional logging metadata
    this.requestId = options.requestId || this.generateRequestId();
    this.sessionId = options.sessionId;
    this.userId = options.userId;
    this.component = options.component || 'unknown';
    this.severity = this.determineSeverity(options.severity);

    // Performance metrics
    this.metrics = {
      memoryUsage: process.memoryUsage(),
      uptime: process.uptime(),
      timestamp: this.timestamp
    };
  }

  generateRequestId() {
    // Generate a correlation ID for distributed tracing
    return `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
  }

  determineSeverity(severity) {
    // Map error codes to severity levels
    const severityMap = {
      'VALIDATION_ERROR': 'warning',
      'AUTH_ERROR': 'warning',
      'DATABASE_ERROR': 'error',
      'NETWORK_ERROR': 'error',
      'INTERNAL_ERROR': 'critical'
    };

    return severity || severityMap[this.code] || 'error';
  }

  getLogEntry() {
    // Structured log entry following best practices
    return {
      // Standard fields
      level: this.severity,
      timestamp: this.timestamp,
      message: this.message,

      // Error-specific fields
      error: {
        name: this.name,
        code: this.code,
        stack: this.stack,
        details: this.details
      },

      // Context fields
      context: {
        requestId: this.requestId,
        sessionId: this.sessionId,
        userId: this.userId,
        component: this.component,
        environment: process.env.NODE_ENV || 'development'
      },

      // Performance metrics
      metrics: this.metrics,

      // Correlation for distributed systems
      correlation: {
        traceId: this.requestId,
        spanId: this.generateSpanId()
      }
    };
  }

  generateSpanId() {
    // Generate a span ID for distributed tracing
    return `span_${Math.random().toString(36).substr(2, 9)}`;
  }
}

// Express.js integration example
app.use((err, req, res, next) => {
  // Create a loggable error if it isn't already
  const loggableError = err instanceof LoggableError 
    ? err 
    : new LoggableError(err.message, {
        code: 'UNKNOWN_ERROR',
        requestId: req.id,
        userId: req.user?.id,
        component: 'express-middleware',
        originalError: err
      });

  // Log with structured logging
  logger.error(loggableError.getLogEntry());

  // Determine appropriate HTTP response
  const statusCode = err.statusCode || 500;
  const shouldExposeDetails = process.env.NODE_ENV === 'development';

  // Send response to client
  res.status(statusCode).json({
    error: {
      message: err.message,
      code: err.code,
      requestId: loggableError.requestId,
      ...(shouldExposeDetails && { 
        stack: err.stack,
        details: err.details 
      })
    }
  });
});

Mastering Error.captureStackTrace and custom error classes elevates your error handling from basic to professional.

By implementing clean, actionable stack traces and structured error information, you significantly reduce debugging time and improve application maintainability.

💡 Have questions? Drop them in the comments!

Preventing Accidental Interchangeability in TypeScript — Branding & the Unique Property Pattern

Ali nazari — Tue, 25 Nov 2025 09:20:24 +0000

TypeScript’s structural type system is convenient and flexible: two types are compatible when their shapes match.

That convenience can become a problem when you want different domain concepts (e.g. UserId vs ProductId) to be treated as distinct even though both are plain strings or numbers.

This post explains two effective patterns for making types nominal-like in TypeScript: branding (tagged types) and the unique property pattern (using unique symbol).

You’ll get practical code, runtime-friendly factories and guards, and guidance about trade-offs and pitfalls.

Problem: structural typing → accidental interchangeability

Example of the problem:

type UserId = string;
type ProductId = string;

function getUser(id: UserId) { /* ... */ }

const pid: ProductId = "p-123";
getUser(pid); // allowed — but this is probably a bug

Because UserId and ProductId are both string, TypeScript treats them as identical.

We need a way to make these types distinct at the type level, without adding runtime overhead or complex class wrappers.

Overview of solutions

Branding (dummy property / intersection) — add a compile-time-only phantom property (commonly __brand) to make the type shape unique. Requires an explicit construction or as cast.
Unique property pattern (unique symbol) — use a unique symbol as a property key to guarantee uniqueness across modules and third-party code.
Runtime-safe factories and type guards — create values and validate them at runtime to avoid as-driven unsafety.
Use wrappers (classes/objects) if you need runtime identity/behaviour.

Simple branding (the classic trick)

A generic Brand utility makes it easy:

type Brand<K, T> = K & { __brand: T };

// Domain-specific tagged types:
type UserId = Brand<string, "UserId">;
type ProductId = Brand<string, "ProductId">;

UserId and ProductId are now structurally different because of the __brand property. You cannot assign one to the other without an explicit cast.

Creating branded values

function makeUserId(s: string): UserId {
  return s as UserId; // only here do we assert; caller must use factory
}

const uid = makeUserId("u-42");
const pid = "p-42" as ProductId;

getUser(uid);       // ok
getUser(pid);       // error (ProductId not assignable to UserId)

Notes:

The __brand field is purely a compile-time trick — it does not exist at runtime.
Any as cast can subvert the safety; prefer factories or validators.

Unique symbol branding (safer)

Using a unique symbol gives stronger guarantees and prevents collisions:

declare const userIdBrand: unique symbol;

type UserId = string & { readonly [userIdBrand]: true };

This pattern ensures the key is truly unique, so other code cannot accidentally create an identical-looking brand. It’s more robust when publishing libraries or when multiple modules are involved.

Example with factory:

declare const userIdBrand: unique symbol;

type UserId = string & { readonly [userIdBrand]: true };

function makeUserId(s: string): UserId {
  return s as UserId;
}

Because userIdBrand is a unique symbol, the only place that exact property key exists is where it is declared; other code cannot recreate it accidentally.

Runtime factories and type guards (recommended)

Branding alone is compile-time. If you want runtime validation (recommended for input coming from network / user), combine brands with factories and guards.

Factory + Guard example

// branding
type UserId = Brand<string, "UserId">;

function makeUserId(s: string): UserId {
  if (!/^u-\d+$/.test(s)) throw new Error("invalid user id");
  return s as UserId;
}

function isUserId(x: unknown): x is UserId {
  return typeof x === "string" && /^u-\d+$/.test(x);
}

// usage
const raw = getFromNetwork();
if (isUserId(raw)) {
  // raw is now narrowed to UserId
  useUserId(raw);
} else {
  // handle invalid input
}

This pattern enforces domain constraints at runtime and gives you genuine safety when data crosses boundaries.

Branded types with generic utilities

A reusable Brand helper:

type Brand<K, T extends string> = K & { readonly __brand: T };

// make factory creator
function brandFactory<K, T extends string>(tag: T) {
  return {
    of(value: K) { return value as Brand<K, T>; },
  };
}

const UserIdFactory = brandFactory<string, "UserId">("UserId");
type UserId = Brand<string, "UserId">;

const id = UserIdFactory.of("u-1");

This is flexible for many domain IDs. But remember: these branded types are still erased at runtime.

Branded types in unions, generics, collections

Branding usually composes well with arrays, generics and unions:

type OrderId = Brand<string, "OrderId">;
type Id = UserId | OrderId;

function useId(id: Id) {
  // structural checks and discriminants still behave as expected
}

const arr: UserId[] = [UserIdFactory.of("u-1"), UserIdFactory.of("u-2")];

Caveat: when using mapping types or serialization helpers, be aware that the brand does not exist at runtime and will be lost on JSON round-trip.

Serialization and JSON

Because brands are compile-time-only, JSON conversions strip the brand. Always re-validate or re-construct branded values from parsed JSON:

// from server:
const parsed = JSON.parse(payload);
const uid = makeUserId(parsed.id); // re-validate and brand

Never assume a raw string from external input is a properly-branded value.

Best practices

Provide small factory functions (makeX) and type guards (isX) for each branded type.
Validate inputs at the boundary (HTTP handlers, file parsers) and convert raw data into branded values immediately.
Prefer unique symbol for widely-distributed libraries or when collisions might occur.
For internal codebases, a simple Brand<K, "Name"> plus disciplined factories is usually sufficient.
Document the expected runtime shape and provide examples for consumers.

💡 Have questions? Drop them in the comments!

Nested query strings in depth — a complete technical guide

Ali nazari — Fri, 21 Nov 2025 23:49:41 +0000

This guide explains everything you need to know about nested query strings (e.g. ?filter[where][name]=John&filter[where][age][lt]=30), the relevant standards and RFCs, how browsers/servers treat them, how to handle them safely and efficiently in Node.js/Express, and practical tips, traps and code you can drop into a real app.

TL;DR (if you want the short map)

a[b][c]=x is conventionally parsed into { a: { b: { c: "x" } } } by parsers that support bracket notation (e.g. qs).
The canonical spec for URIs is RFC 3986; form encoding and application/x-www-form-urlencoded behavior is defined by the WHATWG URL standard / HTML form specs (and legacy RFCs). Percent-encoding rules are different in these specs — encode reserved characters when in doubt.
In Node/Express you can parse nested queries with qs (Express "extended" parser uses qs) or use native URLSearchParams / querystring for simpler cases. Know qs options (depth, parameterLimit, plainObjects, allowPrototypes, arrayLimit) and harden them.
Security: prototype pollution (historical qs advisories), NoSQL injection, parameter-explosion DoS. Validate, whitelist, and sanitize before using parsed objects in DB queries.

What does `?filter[where][name]=John&filter[where][age][lt]=30` mean?

That query string is using bracket notation to express a nested object. A parser that understands bracket syntax (like qs) will produce:

{
  filter: {
    where: {
      name: "John",
      age: { lt: "30" } // note: values are strings by default
    }
  }
}

Key implications:

Bracket syntax is not special to HTTP itself — it's a convention used by many web frameworks and client libraries. The parsing behavior depends on the parser used by the server or client.
Values are strings unless you coerce them (e.g.Number(), schema validators).
Equivalent bracket forms can represent arrays (e.g. a[]=x&a[]=y → a: ["x","y"]) or indexed arrays (a[0]=x&a[1]=y). Use parser options to control these behaviors.

Standards and specs you should know

RFC 3986 — URI generic syntax

RFC 3986 is the canonical definition of URIs (scheme, authority, path, query, fragment) and how characters are percent-encoded in URIs.

The query component is defined but many practical details (like HTML form encoding) are specified elsewhere. If you care about what characters must or may be percent-encoded in a URI, read RFC 3986.

WHATWG URL Standard / HTML form encoding

The WHATWG URL Standard (and HTML form submission rules) describe application/x-www-form-urlencoded semantics, including space encoding as + vs %20, how form submits are encoded and how browsers typically encode form/query values.

For practical interoperability and building URLs programmatically, follow WHATWG's rules

Practical rule: percent-encode reserved characters (including [ and ]) when constructing URLs programmatically unless you know all clients tolerate raw brackets.

Many libraries (qs.stringify()) will encode correctly for you.

Parsers available in Node / Browser: behavior and differences

Native browser `URLSearchParams`

Modern and standardized, available in browsers and Node (globalThis / url.URLSearchParams).
Good for simple key=value pairs and handling repeated keys. It does not produce nested objects from bracket notation — keys are kept as strings ("filter[where][name]") unless you post-process them.
Use when query structure is flat or you control client and server and prefer explicit parsing. (Works for most single-value needs.)

Node querystring (legacy)

Node historically offered querystring.parse which treats keys literally (no nested object parsing from brackets).

Node marks querystring as legacy in favor of URLSearchParams.

Use only if you need its exact behavior or for legacy code.

`qs` (de facto standard for nested parsing)

qs supports bracket notation, creating nested objects and arrays, configurable depth, arrayLimit, parameterLimit, and more.

Widely used in Express (via "extended" parser) and many frameworks.
npm

qs.stringify() will properly encode keys (percent-encoding) and generate query strings that qs.parse() will invert, which makes client/server symbiosis easy.

Express and `app.set('query parser', ...)`

app.set('query parser', 'simple') — uses Node's simple parser (literal keys, no nesting).

app.set('query parser', 'extended') — uses qs style parsing (nested objects). This is the option you want if you expect a[b][c] semantics.

You can also pass a custom function to that setting to call qs.parse() with custom options or implement your own parser.

Note: set this early in your app initialization (before other middleware) — changing it later can be ineffective.

const qs = require('qs');
app.set('query parser', (str) => qs.parse(str, { ignoreQueryPrefix: true }));

`qs`—important options (and safe defaults)

qs.parse(str, opts) and qs.stringify(obj, opts) have knobs you must know about.

depth — maximum nesting depth parsed into objects. Prevents extremely deep payloads that CPU-bind the parser. (Set to a small reasonable value like 5–10 for public endpoints.)
npmdoc.github.io

parameterLimit — maximum number of parameters to parse. Prevents parameter explosion DoS.
Vulnerability Finder

arrayLimit — max number of array items parsed from numeric indices.

plainObjects — when true, create result objects with Object.create(null) (no prototype) — this reduces prototype-pollution surface.

allowPrototypes — if true parsed keys can populate prototype properties (dangerous). Keep allowPrototypes: false.

ignoreQueryPrefix — ignore leading ? when parsing raw query strings.

Example safe parser for Express:

const qs = require('qs');

app.set('query parser', (str) =>
  qs.parse(str, {
    ignoreQueryPrefix: true,
    depth: 6,
    parameterLimit: 2000,
    arrayLimit: 200,
    plainObjects: true,
    allowPrototypes: false
  })
);

Security threats & mitigations

Prototype pollution (real-world qs advisories)

qs has had prototype-pollution advisories (GHSA/CVE entries). Prototype pollution can let an attacker set proto properties via crafted query strings, which can change program behavior or escalate privilege. Mitigations:

Keep qs up to date.
Use plainObjects: true and allowPrototypes: false as parser options to avoid populating prototypes.
Never merge untrusted parsed objects directly into application-level prototypes or trusted config objects.

NoSQL / Database injection

If you accept arbitrary nested objects and pass them to User.find(req.query.filter) or similar, an attacker might submit Mongo operators or crafted objects to change queries (e.g. $ne, $where, $gt, or dot operators). Defenses:

Use sanitizers (e.g. express-mongo-sanitize) to remove leading $ keys and dotted keys.
Validate shapes with JOI/Zod/TypeBox and coerce types (numbers, booleans).
Whitelist allowed fields and operators; map client operators to DB operators explicitly (do not pass user keys straight through).

Parameter explosion / DoS

Very deep or very large query payloads can block the event loop or consume memory. Mitigations:

depth, parameterLimit, arrayLimit in qs.
Rate-limiting and size-checking at upstream layers.

Logging / exposure

Don't log entire req.query for every request in production (attacker could send huge or malicious content). Truncate logs or apply sampling.

Performance considerations

qs parsing is reasonably fast for typical queries, but extremely deep or huge queries can block the event loop — hence depth/parameter limits and rate limiting are important.

If you only need flat queries, prefer URLSearchParams (native) for a simpler, faster path.

Avoid synchronous JSON parsing of very large query values in hot paths.

Bracket-style nested query strings are a convenient and compact way to express structured filters in GET requests, but they also bring complexity and attack surface.

Treat query parsing as an important part of your input validation layer

💡 Have questions? Drop them in the comments!

From TCP to Express: Understanding Request Lifecycles and Cancellation

Ali nazari — Sun, 09 Nov 2025 16:44:40 +0000

Understanding how HTTP requests map to TCP connections gives backend engineers the ability to build efficient, responsive systems.

In Node.js, the req.socket property exposes the underlying TCP socket for each request, allowing servers to detect disconnects, cancel work, and free up resources when clients abort requests.

This article explores how req.socket works, how to use it to implement cancellation logic, and how to propagate abort signals through your application layers.

What `req.socket` Actually Is

Every Express request object (req) is an instance of Node.js’s IncomingMessage, which represents the HTTP request stream.

IncomingMessage holds a socket property that refers to the underlying net.Socket — the raw TCP connection between the client and the server.

// Example: inspecting a request's socket
app.get('/', (req, res) => {
  console.log(req.socket instanceof require('net').Socket); // true
  res.send('ok');
});

The socket is responsible for reading and writing bytes over the network. Express and the Node.js HTTP server simply interpret those bytes as HTTP.

Why This Matters for Request Cancellation

When a client (for example, a browser using fetch with an AbortController) cancels a request or closes a tab, the TCP connection is terminated.

Node.js reflects this event by emitting 'close' on the socket.

Without handling this event, your backend code continues executing:

Database queries continue running.
Heavy computations continue consuming CPU.
External API calls still happen.
Queued work is not canceled.

Detecting and acting upon socket closure allows the backend to reclaim resources early.

Key Socket Properties and Events

Property	Type	Description
`remoteAddress`	`string`	IP address of the client.
`remotePort`	`number`	Client port.
`localAddress`	`string`	Server’s IP address used for this connection.
`localPort`	`number`	Server’s listening port.
`destroyed`	`boolean`	Indicates whether the socket is closed.
`readyState`	`string`	TCP connection state: `open`, `readOnly`, `writeOnly`, `closed`.

Events:

'close': Connection closed (client aborted or timeout).
'end': Client finished sending data.
'error': A socket-level error occurred.

Detecting Client Disconnects

To observe cancellations, listen for the close event on the request’s socket:

app.get('/heavy', async (req, res) => {
  req.socket.once('close', () => {
    console.log('Client disconnected before completion.');
  });

  // Simulate long-running work
  await new Promise(r => setTimeout(r, 10000));

  if (req.socket.destroyed) return; // connection is gone
  res.send('Completed successfully.');
});

This pattern ensures that you don’t attempt to write a response after the connection is gone and provides a hook to clean up or cancel ongoing work.

Creating an Abort Signal for Unified Cancellation

A robust approach is to create an AbortController tied to the socket’s lifecycle:

import { AbortController } from 'node:abort_controller';

function createRequestAbortController(req, res) {
  const controller = new AbortController();
  const onClose = () => controller.abort();

  req.socket.once('close', onClose);
  res.once('finish', () => req.socket.off('close', onClose));
  res.once('close', () => req.socket.off('close', onClose));

  return controller;
}

You can then integrate it in your routes:

app.get('/report', async (req, res) => {
  const controller = createRequestAbortController(req, res);

  try {
    const data = await generateReport({ signal: controller.signal });
    if (!req.socket.destroyed) res.json(data);
  } catch (err) {
    if (controller.signal.aborted) {
      console.log('Request aborted by client.');
      return;
    }
    res.status(500).send('Error generating report.');
  }
});

Every layer that supports AbortSignal (e.g., fetch, pg v8+, node-mongodb-driver v5+) can now respond cooperatively to the cancellation.

Integrating with NestJS via Interceptor

You can generalize this logic in NestJS using an interceptor:

import {
  Injectable,
  NestInterceptor,
  ExecutionContext,
  CallHandler,
} from '@nestjs/common';
import { Observable } from 'rxjs';
import { tap } from 'rxjs/operators';

@Injectable()
export class RequestAbortInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const req = context.switchToHttp().getRequest();
    const res = context.switchToHttp().getResponse();

    const controller = new AbortController();
    const onClose = () => controller.abort();

    req.socket.once('close', onClose);
    req.signal = controller.signal;

    return next.handle().pipe(
      tap(() => req.socket.off('close', onClose))
    );
  }
}

Registering this interceptor globally ensures every request gains a signal property automatically.

Production-Ready Guidelines

Isolate CPU-intensive tasks in worker threads or child processes.
For background jobs, use distributed cancellation flags.
Log and monitor aborted request rates to optimize timeouts and capacity.

Cancellation is not automatic — it requires explicit cooperation from every layer. Once implemented, it improves server stability, scalability, and performance in high-load environments.

The Complete Guide to Request Cancellation in Web Applications Using Node.js

Ali nazari — Mon, 03 Nov 2025 13:00:23 +0000

In modern web architectures, request cancellation is not limited to the frontend. When a user cancels a request, closes a tab, or interrupts a network call, the frontend request may terminate, but the backend often continues to execute.

This can result in wasted computation, open database connections, and unnecessary resource consumption.

This article provides a detailed technical exploration of cancellation in web applications, focusing primarily on implementation within Node.js environments.

Understanding Request Cancellation

When a frontend issues an HTTP request such as:

fetch('/api/process');

several layers of processing are involved:

The browser initiates an HTTP request.
The network stack transmits data to the backend.
The backend receives the request and executes logic.
Downstream systems (databases, APIs, workers) may also participate.

If the user cancels the request or closes the tab, the browser terminates the network connection. However, unless explicitly handled, the backend continues its processing without knowledge of the cancellation.

Historical Context

Before 2017, JavaScript lacked a standardized mechanism for cancellation. Developers typically implemented cancellation through boolean flags or ad-hoc signaling:

let cancelled = false;

setTimeout(() => {
  if (cancelled) return;
  performTask();
}, 1000);

This approach was error-prone and not composable across asynchronous APIs.

The introduction of AbortController in the DOM specification standardized cancellation signaling. Node.js adopted this API in version 15 and above, enabling consistent cancellation semantics between client and server environments.

Frontend Request Cancellation

In modern browsers, cancellation is achieved using AbortController and AbortSignal:

const controller = new AbortController();

fetch('/api/heavy-task', { signal: controller.signal })
  .then(res => res.json())
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.log('Request cancelled');
  });

// later:
controller.abort();

Calling controller.abort() closes the underlying HTTP connection. However, the backend must be explicitly designed to respond to the disconnection.

Handling Cancellations in Node.js

When a request reaches a Node.js backend, the client may disconnect before the server completes processing. Frameworks like Express expose the underlying HTTP request stream, allowing developers to detect such events.

A basic implementation might look like this:

app.get('/api/heavy-task', (req, res) => {
  let cancelled = false;

  req.on('close', () => {
    cancelled = true;
    console.log('Client disconnected');
  });

  performWork().then(result => {
    if (!cancelled) res.json(result);
  });
});

This approach works but requires manual checks throughout the code, which can become difficult to maintain.

Modern Cancellation with AbortController in Node.js

Node.js now provides a native AbortController and AbortSignal API that aligns with browser semantics. This enables consistent and composable cancellation handling across asynchronous operations.

import express from 'express';
import { setTimeout as delay } from 'timers/promises';

const app = express();

app.get('/api/heavy-task', async (req, res) => {
  const controller = new AbortController();
  const { signal } = controller;

  req.on('close', () => controller.abort());

  try {
    // Simulated asynchronous work that supports cancellation
    await delay(10000, null, { signal });
    res.send('Completed');
  } catch (err) {
    if (err.name === 'AbortError') {
      console.log('Request cancelled');
    } else {
      console.error(err);
    }
  }
});

app.listen(3000);

When the client disconnects, the controller.abort() call triggers an AbortError in any asynchronous operation listening to the provided signal. This allows the backend to stop execution immediately.

Propagating Cancellation Across Multiple Components

Real-world applications often involve multiple asynchronous components such as file reads, database queries, and external API calls.

The same AbortSignal can be propagated through these layers to
create a cancellable pipeline:

async function executeWorkflow(signal) {
  await step1(signal);
  await step2(signal);
  await step3(signal);
}

function step1(signal) {
  return delay(2000, 'step1 done', { signal });
}

Each function must be designed to respect the AbortSignal. When the signal is triggered, any ongoing asynchronous operation should throw an AbortError.

Integration Examples

Axios

const controller = new AbortController();
axios.get('/api/data', { signal: controller.signal });
// controller.abort();

Node Fetch

const res = await fetch(url, { signal });

PostgreSQL (pg)

const { Client } = require('pg');
const client = new Client();

app.get('/api/query', async (req, res) => {
  const controller = new AbortController();
  req.on('close', () => controller.abort());

  try {
    const result = await client.query('SELECT pg_sleep(10)', { signal: controller.signal });
    res.json(result.rows);
  } catch (err) {
    if (err.name === 'AbortError') console.log('Query cancelled');
  }
});

If a library supports cancellation natively, passing an AbortSignal allows it to terminate long-running operations cleanly.

Implementation Guidelines

Initialize cancellation early

Create the AbortController as soon as the request is received.

Set timeouts

Use AbortSignal.timeout(ms) (available in Node.js 20+) to automatically abort long-running requests.

Clean up resources

Ensure that cancellation handlers release file handles, database connections, and other resources.

Handle disconnections explicitly

Listen for req.on('close') to avoid leaving processes running after the client disconnects.

Propagate signals

Pass the same AbortSignal through the entire async chain to ensure consistent behavior.

Request cancellation is a critical aspect of resource management in modern web applications. While the frontend can easily terminate a request, the backend must actively monitor for cancellation events to prevent unnecessary work.

The introduction of AbortController and AbortSignal has unified cancellation handling across client and server environments. By integrating these primitives throughout backend workflows, developers can ensure their systems remain efficient, responsive, and resilient under load

💡 Have questions? Drop them in the comments!

Tired of Regex Gibberish? This CLI Tool Decodes It Like Magic. ✨

Ali nazari — Wed, 10 Sep 2025 08:57:02 +0000

Let's be real. You're scrolling through a codebase, and you stumble upon this:

/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]{8,}$/

Is it a secret password validator? A cryptic incantation summoning ancient server demons? Or did a cat just walk across the keyboard?

For most of us, deciphering complex regular expressions feels like reading a language from another dimension. You copy-paste it into Stack Overflow, cross your fingers, and hope it works. But understanding it? That's a whole different battle.

What if you could just ask an expert to explain it to you in plain English?

Well, now you can. Let me introduce you to Regexplain – the command-line wizard that demystifies regex patterns using AI.

🤔 What is Regexplain?

In a nutshell, Regexplain is a CLI tool that uses AI to explain regular expressions. You feed it a regex pattern, and it gives you a clean, human-readable breakdown of what it actually does.

No more guessing. No more frantic Googling. Just instant clarity.

# It's as simple as this:
npx regexplain '^[\w.+\-]+@[a-z\d\-.]+\[a-z]+$'

And it spits out something beautiful:

📖 Explanation:

Breakdown:
- ^ : Start of the string
- [\w.+\-]+ : Matches one or more word characters, dots, plus signs, or hyphens
- @ : Literal @ character
- [a-z\d\-.]+ : Matches one or more lowercase letters, digits, hyphens, or dots
- \. : Escaped dot character (literal .)
- [a-z]+ : Matches one or more lowercase letters
- $ : End of the string

Overall Purpose: This pattern validates email addresses.

Mind. Blown. 🤯

✨ Why This Tool is a Game-Changer for Developers

I built this because I was tired of the regex struggle. It's not just for beginners; even senior devs waste precious minutes reverse-engineering a complex pattern they didn't write.

Here’s what makes Regexplain stand out:

AI-Powered, Not Just Regex Parsing: It doesn't just list the components; it uses Groq's lightning-fast AI to synthesize the information and tell you the purpose and even provide examples. It understands the pattern.
Zero Config, Max Comfort: It's a global npm install away. On first run, it securely stores your API key in your system's keychain (no sketchy files lying around). It even handles proxy settings for those behind corporate firewalls.
Built for the Terminal: It lives where you work. No context switching to a browser tab. Just a quick command in your terminal and you're done.
It's Just… Pleasant. The output is formatted for readability, with helpful emojis and clear structure. It feels like pairing with a regex expert who's always on call.

🚀 How to Start Demystifying Regex Today

Getting started is ridiculously easy.

1. Install it (or just use npx):

npm install -g regexplain

2. Run it with any regex pattern:

regexplain '<your-mysterious-regex-here>'

On first use, it will gently prompt you for a Groq API key (it's free to get started!) and save it securely. After that, you're set for life.

🌟 This Tool is For You If…

You’ve ever copied a regex from the internet and prayed it worked.
You do code reviews and get stuck on someone else's regex logic.
You're learning to code and find regex documentation impenetrable.
You're a DevOps engineer debugging log parsing rules.
You just love cool, well-built developer tools that solve a real problem.

This isn't just another CLI tool. It's a productivity hack. It's a learning aid. It's that little dose of magic that makes development just a bit more enjoyable.

❤️ Love It? Star It!

Regexplain is completely open-source and free under the MIT license.

If this tool saves you time, helps you learn, or just puts a smile on your face, the single biggest way you can support its development is to give it a star on GitHub.

⭐ Star the Regexplain Repository: https://github.com/Silent-Watcher/regexplain

Stars help the project gain visibility, encourage further development, and let other developers know it's a tool worth using. It’s a quick, free way to say "thanks" and ensure this tool keeps getting better.

I'd love to hear your thoughts, feature requests, or see your contributions. Let's make understanding regex a solved problem, together.

Happy coding, and may your patterns always match!

Forem: Ali nazari

Bulletproof Your Node.js Applications with Resilia

Bulletproof Your Node.js Applications with Resilia: A Lightweight Resilience Stack

Supercharge Your Node.js Application with Hedge-Fetch: Eliminating Tail Latency with Speculative Execution

The Theory: From Google's Paper to Your Codebase

Core Architecture: How Hedge-Fetch Works Under the Hood

1. The Adaptive P95 Hedge Trigger

2. Safe and Idempotent Hedging

3. Resource Management and Zero Leakage

4. Observability and Debugging

Putting It All Together: A Real-World Scenario

Getting Started and Joining the Community

Why setTimeout Returns an Object in Node.js (and Why setInterval Can Break Your App)

Browser Timers vs Node.js Timers

Node.js Is a Process That Must Decide When to Exit

Why setTimeout Returns an Object in Node.js

The Meaning of ref() and unref()

Default behavior: timers are “ref’d”

unref(): making a timer optional

ref(): undoing unref()

Why setInterval Is Riskier Than setTimeout

Lifecycle implications

The Silent Production Bug

Overlapping Execution: Another setInterval Hazard

Why Recursive setTimeout Is Safer

Best Practices Summary

Bulletproof Your Node.js Applications with Resilia: A Lightweight Resilience Stack

The Problem: Fragile Architectures

Meet Resilia

Layer 1: The Circuit Breaker

Layer 2: Intelligent Retries

Layer 3: The Bulkhead

How to Use It

Observability Built-In

Why Resilia?

Support the Project

Implementing a Circuit Breaker in Node.js

Walkthrough

execute method

Edge concerns

record method

Potential race conditions

checkThreshold method

getActiveBucket method - sliding window logic

trip method

updateState() method - Open -> HalfOpen transition

the whole picture

How to use this class

Implementing the Bulkhead Pattern in Node.js

Implementing the Bulkhead Pattern in Node.js

Introduction to System Resilience

The Core Mechanism: Semaphores

Step-by-Step Implementation

1. Defining the Bulkhead Class

2. Protecting the Database Layer

Why Custom JavaScript Errors Create Messy Stack Traces and How Error.captureStackTrace Fixes Them

The Problem with Basic Custom Errors

Understanding Error.captureStackTrace

How it works:

Implementing Professional Custom Errors

Real-World Use Cases

Database Layer Errors

API Validation Errors

Advanced Patterns

Error Factory Functions

Hierarchical Error Systems

Performance Considerations

Integration with Logging Systems

Preventing Accidental Interchangeability in TypeScript — Branding & the Unique Property Pattern

Problem: structural typing → accidental interchangeability

Overview of solutions

Simple branding (the classic trick)

Creating branded values

Unique symbol branding (safer)

Runtime factories and type guards (recommended)

Factory + Guard example

Branded types with generic utilities

Branded types in unions, generics, collections

Serialization and JSON

Best practices

Why `setTimeout` Returns an Object in Node.js

The Meaning of `ref()` and `unref()`

`unref()`: making a timer optional

`ref()`: undoing `unref()`

Why `setInterval` Is Riskier Than `setTimeout`

Overlapping Execution: Another `setInterval` Hazard

Why Recursive `setTimeout` Is Safer

`execute` method

`record` method

`checkThreshold` method

`getActiveBucket` method - sliding window logic

`trip` method

`updateState()` method - `Open -> HalfOpen` transition

What does `?filter[where][name]=John&filter[where][age][lt]=30` mean?

Native browser `URLSearchParams`

`qs` (de facto standard for nested parsing)

Express and `app.set('query parser', ...)`

`qs`—important options (and safe defaults)

What `req.socket` Actually Is