www.aleph1.co.uk Git - yaffs-website/blob - node_modules/fstream/node_modules/graceful-fs/README.md

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