# fs-ext

> Extensions to core 'fs' module.

Latest version **2.1.1** (published 2024-11-04) · 0 weekly downloads

## Install

```sh
npm install fs-ext
pnpm add fs-ext
yarn add fs-ext
bun add fs-ext
```

## Health

**Score 48/100 (D)** — status: stable.

Positive: has types package; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 2.1.1 |
| Published | 2024-11-04 |
| First published | 2011-06-10 |
| Weekly downloads | 0 |
| TypeScript types | separate (@types/fs-ext) |
| Module format | CommonJS |
| Node | >= 8.0.0 |
| Dependencies | 1 |
| Unpacked size | 78.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | yes |
| GitHub stars | 110 |
| Author | Matt Sergeant |
| Maintainers | msergeant |
| Keywords | fs, filesystem, flock, seek |

## Links

- npm: https://www.npmjs.com/package/fs-ext
- Repository: https://github.com/baudehlo/node-fs-ext
- Homepage: https://github.com/baudehlo/node-fs-ext/
- Issues: https://github.com/baudehlo/node-fs-ext/issues
- npm.io page: https://npm.io/package/fs-ext

## Dependencies (1)

- [nan](https://npm.io/package/nan.md) ^2.21.0

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 2.1.1 (latest) — 2024-11-04
- 2.1.0 — 2024-11-04
- 2.0.0 — 2019-11-07
- 1.3.0 — 2019-05-24
- 1.2.1 — 2018-06-18
- 1.2.0 — 2018-06-14
- 1.1.0 — 2018-06-11
- 1.0.0 — 2017-09-19
- 0.6.0 — 2017-03-07
- 0.5.0 — 2015-10-15
- 0.4.6 — 2015-08-06
- 0.4.5 — 2015-05-14
- 0.4.4 — 2015-02-27
- 0.4.3 — 2015-01-21
- 0.4.2 — 2014-12-06
- … 9 more at https://npm.io/package/fs-ext/versions

## README

fs-ext
======

[![Build Status][ci-img]][ci-url]
[![Coverage Status][cov-img]][cov-url]
[![Windows Status][ci-win-img]][ci-win-url]

Extras not included in Node's fs module.

**Note**:

* From `v2.0.0` onwards, module doesn't override `fs` and `constants` Node.js core modules. Instead
  import functions and constants directly:

  ```js
  const {flock, constants} = require('fs-ext');
  // or
  const fsExt = require('fs-ext');
  // fsExt.flock
  // fsExt.constants
  ```

* From `v1.0.0` onwards, fs.utime and fs.utimeSync have been removed.
  Use fs.utimes and fs.utimesSync instead.

Installation
------------

Install via npm:

```sh
npm install fs-ext
```

Usage
-----

fs-ext imports all of the methods from the core 'fs' module, so you don't
need two objects.

```js
const fs = require('fs');
const {flock} = require('fs-ext');

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

For an advanced example checkout `example.js`.

API
---

### flock(fd, flags, [callback])

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.


### flockSync(fd, flags)

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

### fcntl(fd, cmd, [arg], [callback])

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 )

Requiring this module adds `FD_CLOEXEC` to the constants module, for use with F_SETFD,
and also F_RDLCK, F_WRLCK and F_UNLCK for use with F_SETLK (etc).

File locking can be used like so:

```js
const {fnctl, constants} = require('fs-ext');

fcntl(fd, 'setlkw', constants.F_WRLCK, (err) => {
    if (!err) {
        // Lock succeeded
    }
});
```

### fcntlSync(fd, flags)

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

### seek(fd, offset, whence, [callback])

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).

### seekSync(fd, offset, whence)

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



[ci-img]: https://travis-ci.org/baudehlo/node-fs-ext.svg?branch=master
[ci-url]: https://travis-ci.org/baudehlo/node-fs-ext
[cov-img]: https://codecov.io/github/baudehlo/node-fs-ext/coverage.svg
[cov-url]: https://codecov.io/github/baudehlo/node-fs-ext?branch=master
[ci-win-img]: https://ci.appveyor.com/api/projects/status/pqbnutckk0n46uc8?svg=true
[ci-win-url]: https://ci.appveyor.com/project/baudehlo/node-fs-ext/branch/master

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