1 | # 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.readFile('some-file-or-whatever', (err, data) => {
|
34 | // Do stuff here.
|
35 | })
|
36 | ```
|
37 |
|
38 | ## Sync methods
|
39 |
|
40 | This module cannot intercept or handle `EMFILE` or `ENFILE` errors from sync
|
41 | methods. If you use sync methods which open file descriptors then you are
|
42 | responsible for dealing with any errors.
|
43 |
|
44 | This is a known limitation, not a bug.
|
45 |
|
46 | ## Global Patching
|
47 |
|
48 | If you want to patch the global fs module (or any other fs-like
|
49 | module) you can do this:
|
50 |
|
51 | ```javascript
|
52 | // Make sure to read the caveat below.
|
53 | var realFs = require('fs')
|
54 | var gracefulFs = require('graceful-fs')
|
55 | gracefulFs.gracefulify(realFs)
|
56 | ```
|
57 |
|
58 | This should only ever be done at the top-level application layer, in
|
59 | order to delay on EMFILE errors from any fs-using dependencies. You
|
60 | should **not** do this in a library, because it can cause unexpected
|
61 | delays in other parts of the program.
|
62 |
|
63 | ## Changes
|
64 |
|
65 | This module is fairly stable at this point, and used by a lot of
|
66 | things. That being said, because it implements a subtle behavior
|
67 | change in a core part of the node API, even modest changes can be
|
68 | extremely breaking, and the versioning is thus biased towards
|
69 | bumping the major when in doubt.
|
70 |
|
71 | The main change between major versions has been switching between
|
72 | providing a fully-patched `fs` module vs monkey-patching the node core
|
73 | builtin, and the approach by which a non-monkey-patched `fs` was
|
74 | created.
|
75 |
|
76 | The goal is to trade `EMFILE` errors for slower fs operations. So, if
|
77 | you try to open a zillion files, rather than crashing, `open`
|
78 | operations will be queued up and wait for something else to `close`.
|
79 |
|
80 | There are advantages to each approach. Monkey-patching the fs means
|
81 | that no `EMFILE` errors can possibly occur anywhere in your
|
82 | application, because everything is using the same core `fs` module,
|
83 | which is patched. However, it can also obviously cause undesirable
|
84 | side-effects, especially if the module is loaded multiple times.
|
85 |
|
86 | Implementing a separate-but-identical patched `fs` module is more
|
87 | surgical (and doesn't run the risk of patching multiple times), but
|
88 | also imposes the challenge of keeping in sync with the core module.
|
89 |
|
90 | The current approach loads the `fs` module, and then creates a
|
91 | lookalike object that has all the same methods, except a few that are
|
92 | patched. It is safe to use in all versions of Node from 0.8 through
|
93 | 7.0.
|
94 |
|
95 | ### v4
|
96 |
|
97 | * Do not monkey-patch the fs module. This module may now be used as a
|
98 | drop-in dep, and users can opt into monkey-patching the fs builtin
|
99 | if their app requires it.
|
100 |
|
101 | ### v3
|
102 |
|
103 | * Monkey-patch fs, because the eval approach no longer works on recent
|
104 | node.
|
105 | * fixed possible type-error throw if rename fails on windows
|
106 | * verify that we *never* get EMFILE errors
|
107 | * Ignore ENOSYS from chmod/chown
|
108 | * clarify that graceful-fs must be used as a drop-in
|
109 |
|
110 | ### v2.1.0
|
111 |
|
112 | * Use eval rather than monkey-patching fs.
|
113 | * readdir: Always sort the results
|
114 | * win32: requeue a file if error has an OK status
|
115 |
|
116 | ### v2.0
|
117 |
|
118 | * A return to monkey patching
|
119 | * wrap process.cwd
|
120 |
|
121 | ### v1.1
|
122 |
|
123 | * wrap readFile
|
124 | * Wrap fs.writeFile.
|
125 | * readdir protection
|
126 | * Don't clobber the fs builtin
|
127 | * Handle fs.read EAGAIN errors by trying again
|
128 | * Expose the curOpen counter
|
129 | * No-op lchown/lchmod if not implemented
|
130 | * fs.rename patch only for win32
|
131 | * Patch fs.rename to handle AV software on Windows
|
132 | * Close #4 Chown should not fail on einval or eperm if non-root
|
133 | * Fix isaacs/fstream#1 Only wrap fs one time
|
134 | * Fix #3 Start at 1024 max files, then back off on EMFILE
|
135 | * lutimes that doens't blow up on Linux
|
136 | * A full on-rewrite using a queue instead of just swallowing the EMFILE error
|
137 | * Wrap Read/Write streams as well
|
138 |
|
139 | ### 1.0
|
140 |
|
141 | * Update engines for node 0.6
|
142 | * Be lstat-graceful on Windows
|
143 | * first
|