fs-ext-extra-prebuilt

A fork of fs-ext that ships prebuilt binaries for all major platforms and adds Windows-specific file locking APIs.

Why this fork?

The original fs-ext package requires compilation during npm install, which can fail in environments without build tools. This fork:

- Ships prebuilt binaries for macOS (x64, arm64), Linux (x64, arm64), and Windows (x64, arm64)
- Adds LockFileEx/UnlockFileEx Windows APIs for byte-range file locking
- Supports Node.js 20+ and Electron
- Falls back to local compilation if no prebuilt binary matches your platform

Installation

``sh
npm install fs-ext-extra-prebuilt
`

Usage

`js
const { flock, flockSync } = require('fs-ext-extra-prebuilt');
const fs = require('fs');

const fd = fs.openSync('foo.txt', 'r');
flock(fd, 'ex', (err) => {
if (err) {
return console.error("Couldn't lock file");
}
// file is locked
});
`

API

$3

Asynchronous flock(2). No arguments other than a possible error are passed to
the callback. Flags can be 'sh', 'ex', 'shnb', 'exnb', 'un' and correspond
to the various LOCK_SH, LOCK_EX, LOCK_SH|LOCK_NB, etc.

NOTE (from flock() man page): flock() does not lock files over NFS. Use fcntl(2)
instead: that does work over NFS, given a sufficiently recent version of Linux
and a server which supports locking.

$3

Synchronous flock(2). Throws an exception on error.

$3

Asynchronous fcntl(2).

callback will be given two arguments (err, result).

The supported commands are:

- 'getfd' ( F_GETFD )
- 'setfd' ( F_SETFD )
- 'setlk' ( F_SETLK )
- 'getlk' ( F_GETLK )
- 'setlkw' ( F_SETLKW )

For F_SETLK and F_SETLKW, the arg parameter specifies the lock type (F_RDLCK, F_WRLCK, or F_UNLCK).
The optional start and len parameters specify the byte range to lock. If omitted, they default
to 0, which locks the entire file.

$3

Synchronous fcntl(2). Throws an exception on error.

$3

Asynchronous lseek(2).

callback will be given two arguments (err, currFilePos).

whence can be 0 (SEEK_SET) to set the new position in bytes to offset,
1 (SEEK_CUR) to set the new position to the current position plus offset
bytes (can be negative), or 2 (SEEK_END) to set to the end of the file
plus offset bytes (usually negative or zero to seek to the end of the file).

$3

Synchronous lseek(2). Throws an exception on error. Returns current file position.

$3

Asynchronous LockFileEx. Locks a byte range in a file.

Flags:

- 0 - shared lock
- constants.LOCKFILE_EXCLUSIVE_LOCK - exclusive lock
- constants.LOCKFILE_FAIL_IMMEDIATELY - non-blocking (can be OR'd with above)

$3

Synchronous LockFileEx. Throws an exception on error.

$3

Asynchronous UnlockFileEx. Unlocks a byte range in a file.

$3

Synchronous UnlockFileEx. Throws an exception on error.

Constants

Available via require('fs-ext-extra-prebuilt').constants:

- LOCK_SH, LOCK_EX, LOCK_NB, LOCK_UN - flock flags
- F_GETFD, F_SETFD, F_GETLK, F_SETLK, F_SETLKW - fcntl commands
- F_RDLCK, F_WRLCK, F_UNLCK - fcntl lock types
- FD_CLOEXEC - close-on-exec flag
- LOCKFILE_EXCLUSIVE_LOCK, LOCKFILE_FAIL_IMMEDIATELY` - Windows LockFileEx flags

License

MIT