File Concurrency and Dependency Security Locks in Node.js

Developers often confuse these packages because of their names, but they solve two completely different problems. lockfile and proper-lockfile manage runtime process synchronization using file locks. lockfile-lint validates dependency lockfiles for security risks. Using the wrong tool can lead to race conditions or security vulnerabilities. Let's break down how they work and when to use each.

🚦 File Locking: lockfile vs proper-lockfile

Both packages prevent multiple processes from writing to the same file simultaneously. They create a temporary .lock file to signal ownership. However, their implementation details differ significantly.

lockfile is the legacy option.

• Uses callback-based APIs.
• Can leave stale locks if a process crashes.
• Known to fail on network file systems (NFS).

// lockfile: Callback-based API
const lockfile = require('lockfile');

lockfile.lock('data.txt', { wait: true }, function (err) {
  if (err) return console.error(err);
  
  // Do work...
  
  lockfile.unlock('data.txt', function (err) {
    if (err) console.error(err);
  });
});

proper-lockfile is the modern standard.

• Uses Promise-based APIs (async/await).
• Automatically cleans up stale locks using update intervals.
• Works reliably on NFS and Docker volumes.

// proper-lockfile: Promise-based API
const properLockfile = require('proper-lockfile');

async function run() {
  const release = await properLockfile.lock('data.txt', { retries: 1000 });
  
  try {
    // Do work...
  } finally {
    await release(); // Ensures unlock even if error occurs
  }
}

run().catch(console.error);

🛡️ Dependency Security: lockfile-lint

lockfile-lint does not lock files for concurrency. Instead, it reads your package-lock.json or yarn.lock to ensure dependencies come from trusted sources. This is critical for supply chain security.

lockfile-lint validates dependency integrity.

• Checks if packages are hosted on allowed registries.
• Ensures HTTPS is used for all resources.
• Runs primarily in CI/CD pipelines.

# lockfile-lint: CLI usage in CI
npx lockfile-lint --path package-lock.json --validate-https --allowed-hosts npm yarn

You can also use it programmatically within a build script.

// lockfile-lint: Programmatic API
const lockfileLint = require('lockfile-lint');

const validator = lockfileLint.LockfileValidator();

const result = validator.validate({
  lockfilePath: './package-lock.json',
  validateHttps: true,
  allowedHosts: ['npm', 'yarn']
});

if (!result.valid) {
  console.error('Security check failed:', result.errors);
  process.exit(1);
}

⚠️ Stale Lock Handling

When a process crashes without unlocking, the lock file remains. This can block other processes forever.

lockfile requires manual cleanup.

• You must write extra code to detect and remove old locks.
• Risk of two processes thinking they own the lock.

// lockfile: Manual stale check
lockfile.check('data.txt', function (err, isLocked) {
  if (isLocked) {
    // Must manually inspect file age and unlink if stale
    // Error-prone and platform-dependent
  }
});

proper-lockfile handles this automatically.

• Uses a heartbeat mechanism to keep locks alive.
• If the process dies, the heartbeat stops and the lock expires.

// proper-lockfile: Automatic stale handling
// The 'update' option keeps the lock fresh while work continues
const release = await properLockfile.lock('data.txt', { 
  update: 1000 
});

// Lock auto-releases if process crashes before release()

🌐 Real-World Scenarios

Scenario 1: Preventing Concurrent Writes

You have a background job processing a shared queue file.

• ✅ Best choice: proper-lockfile
• Why? You need async/await support and safety against crashes.

// proper-lockfile: Safe concurrent access
await properLockfile.lock('queue.json');
await processQueue();
await properLockfile.unlock('queue.json');

Scenario 2: Legacy Script Maintenance

You are updating an old Node.js script that already uses lockfile.

• ⚠️ Choice: lockfile (Temporary)
• Why? Refactoring to Promises might introduce bugs. Plan to migrate later.

// lockfile: Legacy compatibility
lockfile.lock('legacy.txt', cb);

Scenario 3: CI/CD Security Gate

You want to block installs from GitHub repos or untrusted registries.

• ✅ Best choice: lockfile-lint
• Why? It enforces policy before dependencies reach production.

# lockfile-lint: CI Pipeline Step
npx lockfile-lint --path package-lock.json --allowed-hosts npm

📊 Summary Table

💡 Final Recommendation

proper-lockfile is the clear winner for file locking. It saves you from hard-to-debug race conditions and works in modern environments like Docker. Treat lockfile as legacy code — do not start new projects with it.

lockfile-lint belongs in your security toolkit, not your runtime code. Add it to your CI pipeline to ensure no one sneaks in untrusted dependencies.

Final Thought: Don't let the similar names fool you. Use proper-lockfile to manage running processes and lockfile-lint to manage your dependency tree. Mixing them up won't work — they solve different layers of the stack.