1 |
3a515b92
|
cagy
|
# graceful-fs
|
2 |
|
|
|
3 |
|
|
graceful-fs functions as a drop-in replacement for the fs module,
|
4 |
|
|
making various improvements.
|
5 |
|
|
|
6 |
|
|
The improvements are meant to normalize behavior across different
|
7 |
|
|
platforms and environments, and to make filesystem access more
|
8 |
|
|
resilient to errors.
|
9 |
|
|
|
10 |
|
|
## Improvements over [fs module](https://nodejs.org/api/fs.html)
|
11 |
|
|
|
12 |
|
|
* Queues up `open` and `readdir` calls, and retries them once
|
13 |
|
|
something closes if there is an EMFILE error from too many file
|
14 |
|
|
descriptors.
|
15 |
|
|
* fixes `lchmod` for Node versions prior to 0.6.2.
|
16 |
|
|
* implements `fs.lutimes` if possible. Otherwise it becomes a noop.
|
17 |
|
|
* ignores `EINVAL` and `EPERM` errors in `chown`, `fchown` or
|
18 |
|
|
`lchown` if the user isn't root.
|
19 |
|
|
* makes `lchmod` and `lchown` become noops, if not available.
|
20 |
|
|
* retries reading a file if `read` results in EAGAIN error.
|
21 |
|
|
|
22 |
|
|
On Windows, it retries renaming a file for up to one second if `EACCESS`
|
23 |
|
|
or `EPERM` error occurs, likely because antivirus software has locked
|
24 |
|
|
the directory.
|
25 |
|
|
|
26 |
|
|
## USAGE
|
27 |
|
|
|
28 |
|
|
```javascript
|
29 |
|
|
// use just like fs
|
30 |
|
|
var fs = require('graceful-fs')
|
31 |
|
|
|
32 |
|
|
// now go and do stuff with it...
|
33 |
|
|
fs.readFileSync('some-file-or-whatever')
|
34 |
|
|
```
|
35 |
|
|
|
36 |
|
|
## Global Patching
|
37 |
|
|
|
38 |
|
|
If you want to patch the global fs module (or any other fs-like
|
39 |
|
|
module) you can do this:
|
40 |
|
|
|
41 |
|
|
```javascript
|
42 |
|
|
// Make sure to read the caveat below.
|
43 |
|
|
var realFs = require('fs')
|
44 |
|
|
var gracefulFs = require('graceful-fs')
|
45 |
|
|
gracefulFs.gracefulify(realFs)
|
46 |
|
|
```
|
47 |
|
|
|
48 |
|
|
This should only ever be done at the top-level application layer, in
|
49 |
|
|
order to delay on EMFILE errors from any fs-using dependencies. You
|
50 |
|
|
should **not** do this in a library, because it can cause unexpected
|
51 |
|
|
delays in other parts of the program.
|
52 |
|
|
|
53 |
|
|
## Changes
|
54 |
|
|
|
55 |
|
|
This module is fairly stable at this point, and used by a lot of
|
56 |
|
|
things. That being said, because it implements a subtle behavior
|
57 |
|
|
change in a core part of the node API, even modest changes can be
|
58 |
|
|
extremely breaking, and the versioning is thus biased towards
|
59 |
|
|
bumping the major when in doubt.
|
60 |
|
|
|
61 |
|
|
The main change between major versions has been switching between
|
62 |
|
|
providing a fully-patched `fs` module vs monkey-patching the node core
|
63 |
|
|
builtin, and the approach by which a non-monkey-patched `fs` was
|
64 |
|
|
created.
|
65 |
|
|
|
66 |
|
|
The goal is to trade `EMFILE` errors for slower fs operations. So, if
|
67 |
|
|
you try to open a zillion files, rather than crashing, `open`
|
68 |
|
|
operations will be queued up and wait for something else to `close`.
|
69 |
|
|
|
70 |
|
|
There are advantages to each approach. Monkey-patching the fs means
|
71 |
|
|
that no `EMFILE` errors can possibly occur anywhere in your
|
72 |
|
|
application, because everything is using the same core `fs` module,
|
73 |
|
|
which is patched. However, it can also obviously cause undesirable
|
74 |
|
|
side-effects, especially if the module is loaded multiple times.
|
75 |
|
|
|
76 |
|
|
Implementing a separate-but-identical patched `fs` module is more
|
77 |
|
|
surgical (and doesn't run the risk of patching multiple times), but
|
78 |
|
|
also imposes the challenge of keeping in sync with the core module.
|
79 |
|
|
|
80 |
|
|
The current approach loads the `fs` module, and then creates a
|
81 |
|
|
lookalike object that has all the same methods, except a few that are
|
82 |
|
|
patched. It is safe to use in all versions of Node from 0.8 through
|
83 |
|
|
7.0.
|
84 |
|
|
|
85 |
|
|
### v4
|
86 |
|
|
|
87 |
|
|
* Do not monkey-patch the fs module. This module may now be used as a
|
88 |
|
|
drop-in dep, and users can opt into monkey-patching the fs builtin
|
89 |
|
|
if their app requires it.
|
90 |
|
|
|
91 |
|
|
### v3
|
92 |
|
|
|
93 |
|
|
* Monkey-patch fs, because the eval approach no longer works on recent
|
94 |
|
|
node.
|
95 |
|
|
* fixed possible type-error throw if rename fails on windows
|
96 |
|
|
* verify that we *never* get EMFILE errors
|
97 |
|
|
* Ignore ENOSYS from chmod/chown
|
98 |
|
|
* clarify that graceful-fs must be used as a drop-in
|
99 |
|
|
|
100 |
|
|
### v2.1.0
|
101 |
|
|
|
102 |
|
|
* Use eval rather than monkey-patching fs.
|
103 |
|
|
* readdir: Always sort the results
|
104 |
|
|
* win32: requeue a file if error has an OK status
|
105 |
|
|
|
106 |
|
|
### v2.0
|
107 |
|
|
|
108 |
|
|
* A return to monkey patching
|
109 |
|
|
* wrap process.cwd
|
110 |
|
|
|
111 |
|
|
### v1.1
|
112 |
|
|
|
113 |
|
|
* wrap readFile
|
114 |
|
|
* Wrap fs.writeFile.
|
115 |
|
|
* readdir protection
|
116 |
|
|
* Don't clobber the fs builtin
|
117 |
|
|
* Handle fs.read EAGAIN errors by trying again
|
118 |
|
|
* Expose the curOpen counter
|
119 |
|
|
* No-op lchown/lchmod if not implemented
|
120 |
|
|
* fs.rename patch only for win32
|
121 |
|
|
* Patch fs.rename to handle AV software on Windows
|
122 |
|
|
* Close #4 Chown should not fail on einval or eperm if non-root
|
123 |
|
|
* Fix isaacs/fstream#1 Only wrap fs one time
|
124 |
|
|
* Fix #3 Start at 1024 max files, then back off on EMFILE
|
125 |
|
|
* lutimes that doens't blow up on Linux
|
126 |
|
|
* A full on-rewrite using a queue instead of just swallowing the EMFILE error
|
127 |
|
|
* Wrap Read/Write streams as well
|
128 |
|
|
|
129 |
|
|
### 1.0
|
130 |
|
|
|
131 |
|
|
* Update engines for node 0.6
|
132 |
|
|
* Be lstat-graceful on Windows
|
133 |
|
|
* first
|