# fs-native-extensions

> Native file system extensions for advanced file operations

Latest version **1.5.1** (published 2026-08-31) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install fs-native-extensions
pnpm add fs-native-extensions
yarn add fs-native-extensions
bun add fs-native-extensions
```

## Health

**Score 60/100 (C)** — status: active.

Positive: no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.5.1 |
| Published | 2026-08-31 |
| First published | 2022-06-27 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 1.4 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 36 |
| Author | Kasper Isager Dalsgarð |
| Maintainers | mafintosh |

## Links

- npm: https://www.npmjs.com/package/fs-native-extensions
- Repository: https://github.com/holepunchto/fs-native-extensions
- Homepage: https://github.com/holepunchto/fs-native-extensions#readme
- Issues: https://github.com/holepunchto/fs-native-extensions/issues
- npm.io page: https://npm.io/package/fs-native-extensions

## Dependencies (2)

- [require-addon](https://npm.io/package/require-addon.md) ^1.1.0
- [which-runtime](https://npm.io/package/which-runtime.md) ^1.2.0

## Recent versions

- 1.5.1 (latest) — 2026-08-31
- 1.5.0 — 2026-04-13
- 1.4.5 — 2025-11-11
- 1.4.4 — 2025-09-19
- 1.4.3 — 2025-08-21
- 1.4.2 — 2025-03-26
- 1.4.1 — 2025-03-20
- 1.4.0 — 2025-03-14
- 1.3.4 — 2025-02-20
- 1.3.3 — 2025-02-11
- 1.3.2 — 2024-10-22
- 1.3.1 — 2024-10-01
- 1.3.0 — 2024-09-27
- 1.2.7 — 2024-02-09
- 1.2.6 — 2024-02-09
- … 9 more at https://npm.io/package/fs-native-extensions/versions

## README

# fs-native-extensions

Native file system extensions for advanced file operations

```
npm install fs-native-extensions
```

## Usage

Write to a file using an exclusive lock:

```js
const { open } = require('fs/promises')
const { waitForLock, unlock } = require('fs-native-extensions')

const file = await open('file.txt', 'a+')

await waitForLock(file.fd)

try {
  await file.write('hello world')
} finally {
  unlock(file.fd)
}
```

## API

#### `const granted = tryLock(fd[, offset[, length]][, options])`

Request a lock on a file, returning `true` if the lock was granted or `false` if another file descriptor currently holds the lock.

To lock only a portion of the file, `offset` and `length` may be passed. A `length` of `0` will request a lock from `offset` to the end of the file.

On macOS, BSD locks are used and so only locks on the whole file are supported.

Note that the lock is only advisory and there is nothing stopping another process from accessing the file by simply ignoring the lock.

Options include:

```js
{
  // If `true`, request a shared lock, i.e. a read lock, on the file. By
  // default, an exclusive lock, i.e. a write lock, is requested.
  // Be aware that an exclusive lock can only be granted to files that are
  // writable!
  shared: false
}
```

#### `await waitForLock(fd[, offset[, length]][, options])`

Request a lock on a file, resolving when the lock is granted. If another file descriptor holds the lock, the lock will not be granted until the other file descriptor releases the lock.

Options are the same as `tryLock()`.

#### `waitForLockSync(fd[, offset[, length]][, options])`

Synchronous version of `waitForLock()`. Blocks the calling thread until the lock is granted.

Options are the same as `tryLock()`.

#### `const granted = tryDowngradeLock(fd[, offset[, length]])`

Request a downgrade from an already held exclusive lock to a shared lock, returning `true` if the lock was granted or `false` if another process currently holds the lock. If `false` is returned, the exclusive lock is lost and must be requested again.

On Windows, the downgrade will happen atomically and be immediately granted.

#### `await waitForDowngradeLock(fd[, offset[, length]])`

Request a downgrade from an already held exclusive lock to a shared lock.

On Windows, the downgrade will happen atomically and be immediately granted.

#### `waitForDowngradeLockSync(fd[, offset[, length]])`

Synchronous version of `waitForDowngradeLock()`. Blocks the calling thread until the downgrade is granted.

#### `const granted = tryUpgradeLock(fd[, offset[, length]])`

Request an upgrade from an already held shared lock to an exclusive lock, returning `true` if the lock was granted or `false` if another process currently holds the lock. If `false` is returned, the shared lock is lost and must be requested again.

#### `await waitForUpgradeLock(fd[, offset[, length]])`

Request an upgrade from an already held shared lock to an exclusive lock.

#### `waitForUpgradeLockSync(fd[, offset[, length]])`

Synchronous version of `waitForUpgradeLock()`. Blocks the calling thread until the upgrade is granted.

#### `unlock(fd[, offset[, length]])`

Release a lock on a file.

#### `await trim(fd, offset, length)`

Create a hole in a file at `offset` for `length` bytes. On file systems that support sparse files, file blocks wholly covered by a hole will take up no physical space.

On Windows, the file must first be marked sparse using `sparse(fd)`. Otherwise, zeros will be explicitly written to the hole.

#### `trimSync(fd, offset, length)`

Synchronous version of `trim()`.

#### `await sparse(fd)`

Mark a file as sparse. On Windows, this operation is required before holes can be created in the file. On other systems, this operation has no effect.

#### `sparseSync(fd)`

Synchronous version of `sparse()`.

#### `await swap(from, to)`

Swap the paths `from` and `to`, making `from` assume the identity of `to` and `to` assume the identity of `from`.

On Windows, the swap is performed by first moving `to` to a temporary path, then moving `from` to `to`, and finally moving the temporary path to `from`.

On macOS and Linux, the swap is performed atomically.

#### `swapSync(from, to)`

Synchronous version of `swap()`.

#### `const value = await getAttr(fd, name)`

Get the value of the extended file attribute `name`. If the attribute doesn't exist, `null` is returned.

#### `const value = getAttrSync(fd, name)`

Synchronous version of `getAttr()`.

#### `await setAttr(fd, name, value[, encoding])`

Set the value of the extended file attribute `name` to `value`.

#### `setAttrSync(fd, name, value[, encoding])`

Synchronous version of `setAttr()`.

#### `await removeAttr(fd, name)`

Remove the extended file attribute `name`.

#### `removeAttrSync(fd, name)`

Synchronous version of `removeAttr()`.

#### `const names = await listAttrs(fd)`

List all extended file attributes.

#### `const names = listAttrsSync(fd)`

Synchronous version of `listAttrs()`.

## License

Apache-2.0

---
_Source: https://npm.io/package/fs-native-extensions · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._