Concurrency Control and File Locking Strategies in Node.js

Managing access to shared resources is a fundamental challenge in Node.js development. Whether you are preventing race conditions on an in-memory cache or ensuring two separate scripts don't corrupt the same log file, you need reliable locking mechanisms. The packages async-lock, lockfile, and proper-lockfile address these needs, but they operate at different levels: one manages code execution within a process, while the others manage file access across processes.

🧠 In-Memory Serialization vs. File System Locks

The most critical distinction is where the lock lives. async-lock operates entirely in memory within a single Node.js process. It acts as a mutex (mutual exclusion) to ensure that only one asynchronous function executes a critical section at a time. In contrast, lockfile and proper-lockfile create actual files on your disk (.lock files) to signal to the operating system and other processes that a resource is busy.

async-lock is used when you have shared variables in memory that multiple async functions might try to modify simultaneously.

// async-lock: Protecting in-memory state within one process
const AsyncLock = require('async-lock');
const lock = new AsyncLock();

let sharedCounter = 0;

async function increment() {
  await lock.acquire('counter-key', async () => {
    // Only one function can be here at a time
    const current = sharedCounter;
    await new Promise(r => setTimeout(r, 10)); // Simulate async work
    sharedCounter = current + 1;
  });
}

proper-lockfile creates a physical file on the disk to stop other processes from touching a target file. This works even if the processes are completely unrelated.

// proper-lockfile: Protecting a file across multiple processes
const properLockfile = require('proper-lockfile');
const fs = require('fs');

async function writeToFile() {
  // Create a lock for 'data.txt'
  const release = await properLockfile.lock('data.txt');
  
  try {
    // Safe to write; other processes are blocked
    fs.writeFileSync('data.txt', 'new content');
  } finally {
    // Always release the lock
    await release();
  }
}

lockfile attempts the same file-based approach but uses older, less reliable methods.

// lockfile: Legacy file locking (Deprecated)
const lockfile = require('lockfile');

lockfile.lock('data.txt', function (err) {
  if (err) return console.error('Could not lock');
  
  // Perform file operations
  
  // Must manually unlock
  lockfile.unlock('data.txt', function (err) {
    if (err) console.error('Failed to unlock');
  });
});

🛡️ Handling Crashes and Stale Locks

One of the biggest risks in file locking is the "stale lock" problem. If a process crashes or is killed (e.g., kill -9) while holding a lock, a naive locking system will leave the lock file behind forever. This blocks all future processes from ever accessing the resource again.

lockfile does not handle this well. It relies on simple file existence checks. If a process dies unexpectedly, the lock remains, and you often have to manually delete the lock file to recover. This makes it dangerous for production systems.

proper-lockfile solves this by using atomic operations and monitoring. It periodically updates the lock file's metadata while the lock is held. If the process dies, the updates stop. Other processes checking the lock will see it hasn't been updated recently and will treat it as stale, allowing them to safely steal the lock and proceed.

// proper-lockfile: Automatically handles stale locks via options
const release = await properLockfile.lock('data.txt', {
  stale: 10000, // Consider lock stale if not updated in 10s
  update: 2000, // Update lock every 2s to show we are alive
  retries: { 
    retries: 5, // Retry 5 times if lock is busy
    factor: 2,  // Exponential backoff
    maxTimeout: 1000 
  }
});

// If the previous process crashed, proper-lockfile detects it 
// and acquires the lock automatically after the 'stale' timeout.

There is no equivalent safety mechanism in async-lock because if a Node.js process crashes, all in-memory locks vanish instantly. However, async-lock does offer options to limit how long a task can wait before giving up, preventing indefinite hangs.

// async-lock: Preventing indefinite waits
await lock.acquire('key', async () => {
  // Critical section
}, {
  timeout: 5000, // Throw error if waiting longer than 5s
  maxOccupationTime: 2000 // Throw error if task runs longer than 2s
});

🔄 Usage Patterns: Callbacks vs. Promises

Modern Node.js development heavily favors Promises and async/await. The API design of these libraries reflects their age and target use cases.

async-lock is built for Promises. It returns a Promise from the acquire method, making it seamless to use with modern async functions. You can also wrap the acquisition in a try/finally block to ensure locks are always released, even if an error occurs.

// async-lock: Native Promise support
async function safeOperation() {
  try {
    await lock.acquire('resource', async () => {
      await doSomethingAsync();
      await doAnotherThing();
    });
  } catch (err) {
    console.error('Lock acquisition failed or task threw', err);
  }
}

proper-lockfile also provides a clean Promise-based API. The lock method returns a Promise that resolves to a release function. This pattern is explicit and easy to reason about.

// proper-lockfile: Promise-based with explicit release function
async function safeFileWrite() {
  let release;
  try {
    release = await properLockfile.lock('config.json');
    await fs.promises.writeFile('config.json', '{"updated": true}');
  } catch (err) {
    console.error('Failed to lock or write', err);
  } finally {
    if (release) await release();
  }
}

lockfile was written in an era where callbacks were the standard. While you can wrap it in a Promise yourself, the native API requires nested callbacks, which can lead to "callback hell" and makes error handling more verbose.

// lockfile: Callback-based API (requires wrapping for async/await)
function lockFilePromise(file) {
  return new Promise((resolve, reject) => {
    lockfile.lock(file, (err) => {
      if (err) reject(err);
      else resolve(() => {
        return new Promise((res, rej) => {
          lockfile.unlock(file, (err) => err ? rej(err) : res());
        });
      });
    });
  });
}

🌐 Cross-Process Coordination Scenarios

Understanding when to use which tool comes down to your architecture.

Scenario 1: Rate Limiting API Calls in a Single Server

You have a single Node.js server that needs to call an external API, but the API only allows one request at a time per account. You need to queue these requests internally.

• ✅ Best Choice: async-lock
• Why? Everything happens in one process. You don't need file I/O overhead. async-lock efficiently queues the promises in memory.

// Using async-lock for rate limiting
const lock = new AsyncLock();

async function callExternalApi(userId) {
  return lock.acquire(`user-${userId}`, async () => {
    return fetch(`https://api.example.com/data?user=${userId}`);
  });
}

Scenario 2: Multiple Build Scripts Updating a Shared Cache

You have several CI/CD jobs or local developer terminals running build scripts that all read/write to the same node_modules/.cache file. These are separate processes.

• ✅ Best Choice: proper-lockfile
• Why? async-lock won't work because the processes don't share memory. lockfile is too risky if a build script crashes. proper-lockfile ensures only one script writes at a time and recovers automatically if a script is killed.

// Using proper-lockfile for cache safety
async function updateCache(data) {
  const release = await properLockfile.lock('cache.json', { stale: 60000 });
  try {
    const current = JSON.parse(await fs.promises.readFile('cache.json'));
    await fs.promises.writeFile('cache.json', JSON.stringify({ ...current, ...data }));
  } finally {
    await release();
  }
}

Scenario 3: Legacy Maintenance

You are maintaining an old tool written 8 years ago that uses lockfile.

• ⚠️ Action Required: Refactor to proper-lockfile.
• Why? Continuing to use lockfile invites hard-to-debug deadlocks in modern environments. The API is similar enough that migration is straightforward, but the reliability gain is massive.

📊 Summary: Key Differences

💡 The Big Picture

Choosing the right locking mechanism prevents some of the hardest bugs to reproduce in distributed systems.

async-lock is your go-to for internal consistency. If your problem is "two async functions in my server are fighting over this variable," this is the lightweight, efficient solution. It adds almost no overhead and integrates perfectly with modern JavaScript syntax.

proper-lockfile is the industry standard for file safety. If your problem is "two different scripts might overwrite this file," you need a lock that lives on the disk. Its ability to detect crashed processes and clean up after them makes it robust enough for critical infrastructure, build tools, and multi-process applications.

lockfile belongs in the past. Its deprecation is a clear signal that its approach to file locking is insufficient for the reliability demands of modern software. Migrating away from it should be a priority for any team still relying on it.

Final Thought: Always match the lock scope to your problem scope. Don't use a heavy file lock for in-memory problems, and never trust a memory lock to solve cross-process conflicts.