Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/thisconnect/fildes
Magicless helps working with file descriptors
https://github.com/thisconnect/fildes
filesystem fs promise
Last synced: 5 days ago
JSON representation
Magicless helps working with file descriptors
- Host: GitHub
- URL: https://github.com/thisconnect/fildes
- Owner: thisconnect
- License: mit
- Created: 2015-10-11T09:47:07.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T02:23:10.000Z (almost 2 years ago)
- Last Synced: 2024-04-14T01:00:35.488Z (7 months ago)
- Topics: filesystem, fs, promise
- Language: JavaScript
- Homepage:
- Size: 676 KB
- Stars: 8
- Watchers: 2
- Forks: 1
- Open Issues: 17
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- License: license
Awesome Lists containing this project
README
# fildes
[](https://www.npmjs.com/package/fildes)
[](https://github.com/thisconnect/fildes/blob/master/license)
Provides native promises for all file system methods involving file descriptors (FD), basically manages `fs.open` for you.
> file descriptor (FD, less frequently *fildes*)
[en.wikipedia.org/wiki/File_descriptor](https://en.wikipedia.org/wiki/File_descriptor)
[](https://circleci.com/gh/thisconnect/fildes)
[](https://ci.appveyor.com/project/thisconnect/fildes)
[](https://travis-ci.org/thisconnect/fildes)
[](https://codecov.io/gh/thisconnect/fildes)
[](https://libraries.io/github/thisconnect/fildes)
## Usage
`fildes` always return a new [Promise](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise)!
```javascript
const { write } = require('fildes');
write('./path/to/file.txt', 'The quick green fix')
.then(() => console.log('done!'))
.catch(console.error);
```
### Why?
- I needed an API that returns Promises
- provides smart defaults i.e. suitable flags for `open`, `read` and `write`, see [fildes/issues/1](https://github.com/thisconnect/fildes/issues/1)
- creates a directories if flag is `w`, `w+`, `a` or `a+`
- `open` is optional and useful for keeping the fd for multiple operations
- uses no magic
- some very popular node modules use `fs.exists()` which is deprecated…
> `fs.exists()` should not be used to check if a file exists before calling `fs.open()`. Doing so introduces a race condition since other processes may change the file's state between the two calls. Instead, user code should call `fs.open()` directly and handle the error raised if the file is non-existent.
[fs.exists Stability: 0 - Deprecated](https://nodejs.org/api/fs.html#fs_fs_exists_path_callback) (Node.js v5.1.0 File System API)
##### Bad (NOT RECOMMENDED)
```javascript
fs.exists('myfile', (exists) => {
if (exists) {
console.error('myfile already exists');
} else {
fs.open('myfile', 'wx', (err, fd) => {
if (err) throw err;
fs.write(fd, 'Hello', callback);
});
}
});
```
##### Good (RECOMMENDED)
```javascript
fs.open('myfile', 'wx', (err, fd) => {
if (err) {
if (err.code === 'EEXIST') {
console.error('myfile already exists');
return;
}
throw err;
}
fs.write(fd, 'Hello', callback);
});
```
##### Using `fildes`
```javascript
const { open, write, close } = require('fildes');
open('myfile', { flag: 'wx' })
.then(fd => {
return write(fd, 'Hello')
.then(() => close(fd));
})
.catch(console.error);
```
This is the same as:
```javascript
const { write } = require('fildes');
write('myfile', 'Hello', { flag: 'wx' })
.catch(console.error);
```
## Install
```bash
npm i --save fildes
```
`fildes` with support for Node.js 4.x can be found here https://github.com/thisconnect/fildes/tree/v1.x
## API
- [access](https://github.com/thisconnect/fildes/tree/master/lib/access)
- [appendFile](https://github.com/thisconnect/fildes/tree/master/lib/appendFile)
- [chmod](https://github.com/thisconnect/fildes/tree/master/lib/chmod)
- [chown](https://github.com/thisconnect/fildes/tree/master/lib/chown)
- [close](https://github.com/thisconnect/fildes/tree/master/lib/close)
- [link](https://github.com/thisconnect/fildes/tree/master/lib/link)
- [mkdir](https://github.com/thisconnect/fildes/tree/master/lib/mkdir)
- [open](https://github.com/thisconnect/fildes/tree/master/lib/open)
- [read](https://github.com/thisconnect/fildes/tree/master/lib/read)
- [readdir](https://github.com/thisconnect/fildes/tree/master/lib/readdir)
- [readFile](https://github.com/thisconnect/fildes/tree/master/lib/readFile)
- [rename](https://github.com/thisconnect/fildes/tree/master/lib/rename)
- [rm](https://github.com/thisconnect/fildes/tree/master/lib/rm)
- [stats](https://github.com/thisconnect/fildes/tree/master/lib/stats)
- [symlink](https://github.com/thisconnect/fildes/tree/master/lib/symlink)
- [sync](https://github.com/thisconnect/fildes/tree/master/lib/sync)
- [truncate](https://github.com/thisconnect/fildes/tree/master/lib/truncate)
- [unlink](https://github.com/thisconnect/fildes/tree/master/lib/unlink)
- [utimes](https://github.com/thisconnect/fildes/tree/master/lib/utimes)
- [write](https://github.com/thisconnect/fildes/tree/master/lib/write)
- [writeFile](https://github.com/thisconnect/fildes/tree/master/lib/writeFile)
### Examples
- [Get the size of many files](https://github.com/thisconnect/fildes/tree/master/examples/get-sizes)
- [List files](https://github.com/thisconnect/fildes/tree/master/examples/list-files)
- [Keep file descriptor (FD) open and use multiple times](https://github.com/thisconnect/fildes/tree/master/examples/operate-on-fd)
- [Read chunk of many files](https://github.com/thisconnect/fildes/tree/master/examples/read-chunks)