@stackline/lockfile

Maintained compatibility-first file locking with observable asynchronous unlock failures.

Documentation | npm | Issues | Repository

Current package version: 1.0.10

Why this package?

Compatibility-first filesystem lock files for CommonJS, with asynchronous unlock failures made observable.

This is an independent Stackline continuation of lockfile. It is not affiliated with or endorsed by Isaac Z. Schlueter, npm, the original maintainers, or the upstream project.

Compatibility

TypeScript and runtime support

First-party declarations model the callback-based CommonJS API, optional arguments, options, mutable filetime, and actual undefined success values. They are additive: the package does not introduce Promise methods, an ESM runtime, or a second implementation.

The supported runtime is Node.js >=14.17. Development and release tooling may require a newer Node.js version than consumers do.

Installation

Install

For new code, install and import the scoped package directly:

Usage

npm install @stackline/lockfile@1.0.10

var lockfile = require('@stackline/lockfile')

To keep an existing require('lockfile') unchanged, install the scoped package under the historical dependency key:

npm install lockfile@npm:@stackline/lockfile@1.0.10

The equivalent manifest entry is:

{
  "dependencies": {
    "lockfile": "npm:@stackline/lockfile@1.0.10"
  }
}

Quick start

var lockfile = require('@stackline/lockfile')
var path = 'work.lock'

lockfile.lock(path, { wait: 2000, stale: 30000 }, function (lockError) {
  if (lockError) throw lockError

  // Perform the work protected by this cooperative lock.

  lockfile.unlock(path, function (unlockError) {
    if (unlockError) throw unlockError
  })
})

Always inspect the unlock callback when cleanup matters. There is no Promise API: omitting the optional callback also omits the place where an unlink error can be observed.

Features and Integrations

The bounded unlock correction

Upstream issue npm/lockfile#18 identified the error boundary. In lockfile@1.0.4, asynchronous unlock discarded every fs.unlink error and always reported success.

@stackline/lockfile@1.0.7 changed only that branch:

• ENOENT still means already unlocked and remains a successful no-op;
• successful unlink still settles as callback() with undefined;
• a non-ENOENT unlink failure such as EACCES, EPERM, or an I/O error is delivered as the original error, exactly once; and
• synchronous unlockSync remains best-effort and suppresses unlink errors.

Acquisition, checking, retry, wait, stale, callback, on-disk, and process-exit behavior otherwise remain compatible with the published 1.0.4 artifact.

More documentation

• Migration guide
• Compatibility contract
• Security policy and trust boundary
• Contributing
• Publishing gates
• Notices
• Third-party licenses
• Alexandro.Net documentation

Security

Filesystem boundary

This package creates a zero-byte file with exclusive wx access. It is a cooperative coordination primitive, not an authorization or security boundary. Correctness depends on every participant using the same path and on the filesystem providing sufficiently atomic exclusive-create, link, unlink, and metadata behavior.

Network and distributed filesystems can weaken visibility and timestamp assumptions through attribute caches, clock differences, or coarse timestamp resolution. In particular, validate the intended mount and workload before using stale takeover on NFS or across hosts. A stale threshold that is too low can remove a live lock. Abrupt termination can leave a lock despite best-effort signal-exit cleanup.

The zero-byte format has no owner, PID, heartbeat, fencing token, or embedded stale policy. Consequently, the conflicting-threshold problem described in npm/lockfile#30 is not fixed. If you need leases, heartbeats, ownership metadata, or compromise detection, evaluate a protocol such as proper-lockfile; it is not a drop-in replacement.

API Surface

CommonJS API

The runtime preserves the six-method API from lockfile@1.0.4:

• lock(path, [options], callback) acquires a lock asynchronously and calls callback(error); success has no value.
• lockSync(path, [options]) acquires a lock or throws; success returns undefined.
• unlock(path, [callback]) removes a lock asynchronously. Success and a missing lock both call callback() with no error. Other unlink errors are passed through unchanged.
• unlockSync(path) makes a best-effort removal, suppresses every unlink error, and returns undefined.
• check(path, [options], callback) calls callback(error, isLocked).
• checkSync(path, [options]) returns a boolean or throws.

The mutable lockfile.filetime property defaults to ctime on POSIX and mtime on Windows and selects the stat timestamp used for stale checks.

Options

• wait: milliseconds that asynchronous lock may keep polling before it returns the original contention error.
• pollPeriod: milliseconds between polls while waiting; default 100.
• stale: age in milliseconds after which a lock may be taken over.
• retries: additional acquisition attempts for lock and lockSync.
• retryWait: delay in milliseconds between asynchronous retries.

lockSync rejects wait and retryWait because it cannot sleep between attempts. checkSync rejects wait. As in the upstream implementation, supplied option objects are mutable bookkeeping inputs; avoid sharing one object between independent attempts.

Local Development

git clone https://github.com/alexandroit/stackline-lockfile.git
cd stackline-lockfile
npm ci
npm run validate

Release tooling uses Node.js 24.20.0 and npm 11.19.0. The consumer runtime contract remains the one documented above.

Consumer Smoke Test

Run the repository's existing consumer/package check after installing development dependencies:

npm run check:packed

Release Checklist

Run npm run validate and inspect the package contents before release. Publish a new version through the GitHub Actions publishing workflow, using the SHA-512 digest of the reviewed tarball. Verify the exact published version, tarball integrity, and npm provenance after the run.

License

ISC. See the license for the complete terms.

Original authorship and third-party attribution are preserved in NOTICE.

Credits and original authors

• Original project: lockfile.
• Stackline Maintainers.
• Isaac Z. Schlueter and Contributors.
• Stackline maintenance: Alexandro Paixao Marques and Stackline contributors.

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

• Stackline website
• GitHub projects
• npm packages
• Reddit community — r/Stackline
• Maintainer LinkedIn

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.