Preventing Race Conditions in Node.js with Distributed Locks

Picture this: Your payment processing service is humming along perfectly until Black Friday hits. Suddenly, customers are getting charged twice for the same order. Your support tickets are exploding, and your CEO is asking uncomfortable questions.

What happened? Race conditions happened.

When multiple Node.js processes try to modify the same resource simultaneously, chaos ensues. But there's a solution: distributed locks.

What Are Race Conditions?

A race condition occurs when multiple processes access shared resources concurrently, leading to unpredictable results. In distributed Node.js applications, this commonly happens with:

• Payment processing (double charges)
• Job processing (duplicate work)
• Database migrations (corruption)
• Rate limiting (bypass protection)

The Solution: Distributed Locks

Distributed locks ensure only one process can access a critical section at a time, even across multiple servers. Think of it as a "Do Not Disturb" sign for your code.

SyncGuard: Simple Distributed Locking

Let's see how to implement distributed locks using SyncGuard, a TypeScript library that supports both Redis and Firestore backends.

Installation

npm install syncguard @google-cloud/firestore
# or for Redis
npm install syncguard ioredis

Basic Usage: Preventing Double Payments

import { createLock } from "syncguard/firestore";
import { Firestore } from "@google-cloud/firestore";

const db = new Firestore();
const lock = createLock(db);

const processPayment = async (paymentId: string) => {
  // The lock function automatically manages acquire/release
  await lock(
    async () => {
      const payment = await getPayment(paymentId);

      // Critical section - only one process can execute this
      if (payment.status === "pending") {
        await chargeCustomer(payment);
        await updatePaymentStatus(paymentId, "completed");
      }
      // If another process already processed it, we safely skip
    },
    { 
      key: `payment:${paymentId}`,
      ttlMs: 60000, // Lock expires in 60 seconds
      timeoutMs: 5000 // Wait max 5 seconds to acquire
    }
  );
};

Manual Lock Control for Complex Scenarios

Sometimes you need more control over lock lifetime:

const generateReport = async () => {
  const result = await lock.acquire({
    key: "daily-report",
    ttlMs: 300000, // 5 minutes
    timeoutMs: 10000 // Wait up to 10 seconds
  });

  if (result.success) {
    try {
      await processLargeDataset();

      // Extend lock if processing takes longer
      const extended = await lock.extend(result.lockId, 300000);
      if (!extended) {
        throw new Error("Failed to extend lock - aborting");
      }

      await generateAndSaveReport();
    } finally {
      await lock.release(result.lockId);
    }
  } else {
    console.log("Report already being generated:", result.error);
  }
};

Multiple Backend Support

SyncGuard works with different storage backends:

// Firestore (great for serverless)
import { createLock } from "syncguard/firestore";
const firestoreLock = createLock(new Firestore());

// Redis (maximum performance)
import { createLock } from "syncguard/redis";
const redisLock = createLock(redisClient);

// Custom backend
import { createLock } from "syncguard";
const customLock = createLock(myBackend);

Real-World Patterns

Job Queue Processing

const processJob = async (jobId: string) => {
  await lock(
    async () => {
      const job = await getJob(jobId);
      if (job.status === "pending") {
        await executeJob(job);
        await markJobComplete(jobId);
      }
      // Already processed? No problem - idempotent!
    },
    { key: `job:${jobId}`, ttlMs: 300000 }
  );
};

Rate Limiting

const checkRateLimit = async (userId: string) => {
  const result = await lock.acquire({
    key: `rate:${userId}`,
    ttlMs: 60000, // 1 minute window
    timeoutMs: 0, // Fail immediately
    maxRetries: 0
  });

  if (!result.success) {
    throw new Error("Rate limit exceeded");
  }

  // Don't release - let it expire for rate limiting
  return performOperation(userId);
};

Key Benefits

✅ Bulletproof concurrency - No more race conditions

✅ Automatic cleanup - Locks expire even if processes crash

✅ Multiple backends - Choose Redis for speed or Firestore for simplicity

✅ TypeScript first - Full type safety and great DX

✅ Zero dependencies for core package

Best Practices

1. Keep critical sections short - Don't hold locks longer than necessary
2. Set appropriate TTLs - Balance safety vs. availability
3. Handle lock failures gracefully - Always have a fallback strategy
4. Use descriptive lock keys - Make debugging easier
5. Monitor lock contention - High contention indicates bottlenecks

Conclusion

Race conditions are silent killers in distributed Node.js applications. Distributed locks provide a simple, effective solution that can save you from costly bugs and angry customers.

SyncGuard makes implementing distributed locks trivial with its clean API and multiple backend support. Whether you're processing payments, managing job queues, or coordinating microservices, distributed locks should be in your toolkit.

Ready to lock down your race conditions? Check out SyncGuard on GitHub and never worry about duplicate payments again! 🔒

Want to dive deeper? Join our Discord community for discussions and support.