# fs.promised

> Promise-implementation-agnostic wrapper for fs

Latest version **3.0.0** (published 2016-01-21) · ISC license · 0 weekly downloads

## Install

```sh
npm install fs.promised
pnpm add fs.promised
yarn add fs.promised
bun add fs.promised
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2016-01-21 |
| First published | 2015-08-14 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 9 |
| Author | Shawn Dellysse |
| Maintainers | sdellysse |

## Links

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

## Recent versions

- 3.0.0 (latest) — 2016-01-21
- 2.2.1 — 2015-08-15
- 2.2.0 — 2015-08-14
- 2.1.3 — 2015-08-14
- 2.1.2 — 2015-08-14
- 2.1.1 — 2015-08-14

## README

# Promise-implementation-agnostic wrapper for fs #

Promises are great. Node's default implementation of the fs module, using
callbacks, are not. What's also not great is a fs wrapper that is dependant
upon a specific promise implementation, especially since native promises have
landed in ES2015. This library intends to be a drop-in replacement for the
built-in fs module, where all the async functions now use Promises instead of
callbacks. Any other functions on the fs module are passed through untouched.

## Notes ##
* All the examples in this README will be using ES2015/ES2016. The library is
  written in ES3 for maximum compatibility, but Promises are just so much easier
  to work with in ES2015+.

* By default, this library will use `global.Promise` as its promise
  implementation. If you are using an older version of node, or want to use a
  different Promise implementation for any reason, you need to do something
  like this:

  ```javascript
  var fs = require("fs.promised/promisify")(require("bluebird"));
  ```

  The `promisify` include takes a second optional parameter, `shouldCache`,
  which will cache the generated promise wrappers so that when `promisify` is
  called in another module with the same Promise implementation the same wrapper
  is returned. Set this to false if you wish to disable.

## Usage ##

```javascript
const fs = require("fs.promised");

const doSomething_ES2015 = function () {
    return fs.mkdir("/tmp/fs")
    .then(() => fs.writeFile("/tmp/fs/test", "blah blah blah"))
    .then(() => fs.unlink("/tmp/fs/test"))
    ;
}

const doSomething_ES2016 = async function () {
    await fs.mkdir("/tmp/fs");
    await fs.writeFile("/tmp/fs/test", "blah blah blah");
    await fs.unlink("/tmp/fs/test");
}
```

### Caveats ###

* Exceptions:
    If the wrapped function throws an error, the promise will be rejected with
    the the erro. This shouldn't matter as async fs functions shouldn't throw
    errors synchonously but the promise will still capture it if it does.

* Callbacks with multiple success values:
    This should only affect `fs.write` and `fs.read`. Functions that give a
    callback more than one success value (as in, values after the first "error"
    value) will be resolved with an array. Example:

    ```javascript
    const multiArgs_ES2015 = function () {
        return fs.read(fd, data)
        .then(([ written, string ]) => {
            //...
        })
        ;
    };

    /* ES2016 */
    const multiArgs_ES2016 = async function () {
        let [written, string] = await fs.read(fd, data);
        //...
    };
    ```

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