summaryrefslogtreecommitdiff
path: root/tools/node_modules/eslint/node_modules/file-entry-cache/README.md
diff options
context:
space:
mode:
authorMichaël Zasso <targos@protonmail.com>2017-12-22 16:53:42 +0100
committerMichaël Zasso <targos@protonmail.com>2018-01-11 09:48:05 +0100
commit3dc30632755713179f345f4af024bd904c6162d0 (patch)
treef28c4f6dd6dfc5992edf301449d1a371d229755b /tools/node_modules/eslint/node_modules/file-entry-cache/README.md
parenta2c7085dd4a8e60d1a47572aca8bb6fcb7a32f88 (diff)
downloadandroid-node-v8-3dc30632755713179f345f4af024bd904c6162d0.tar.gz
android-node-v8-3dc30632755713179f345f4af024bd904c6162d0.tar.bz2
android-node-v8-3dc30632755713179f345f4af024bd904c6162d0.zip
tools: move eslint from tools to tools/node_modules
This is required because we need to add the babel-eslint dependency and it has to be able to resolve "eslint". babel-eslint is required to support future ES features such as async iterators and import.meta. Refs: https://github.com/nodejs/node/pull/17755 PR-URL: https://github.com/nodejs/node/pull/17820 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Diffstat (limited to 'tools/node_modules/eslint/node_modules/file-entry-cache/README.md')
-rw-r--r--tools/node_modules/eslint/node_modules/file-entry-cache/README.md107
1 files changed, 107 insertions, 0 deletions
diff --git a/tools/node_modules/eslint/node_modules/file-entry-cache/README.md b/tools/node_modules/eslint/node_modules/file-entry-cache/README.md
new file mode 100644
index 0000000000..19d25f0445
--- /dev/null
+++ b/tools/node_modules/eslint/node_modules/file-entry-cache/README.md
@@ -0,0 +1,107 @@
+# file-entry-cache
+> Super simple cache for file metadata, useful for process that work o a given series of files
+> and that only need to repeat the job on the changed ones since the previous run of the process — Edit
+
+[![NPM Version](http://img.shields.io/npm/v/file-entry-cache.svg?style=flat)](https://npmjs.org/package/file-entry-cache)
+[![Build Status](http://img.shields.io/travis/royriojas/file-entry-cache.svg?style=flat)](https://travis-ci.org/royriojas/file-entry-cache)
+
+## install
+
+```bash
+npm i --save file-entry-cache
+```
+
+## Usage
+
+```js
+// loads the cache, if one does not exists for the given
+// Id a new one will be prepared to be created
+var fileEntryCache = require('file-entry-cache');
+
+var cache = fileEntryCache.create('testCache');
+
+var files = expand('../fixtures/*.txt');
+
+// the first time this method is called, will return all the files
+var oFiles = cache.getUpdatedFiles(files);
+
+// this will persist this to disk checking each file stats and
+// updating the meta attributes `size` and `mtime`.
+// custom fields could also be added to the meta object and will be persisted
+// in order to retrieve them later
+cache.reconcile();
+
+// use this if you want the non visited file entries to be kept in the cache
+// for more than one execution
+//
+// cache.reconcile( true /* noPrune */)
+
+// on a second run
+var cache2 = fileEntryCache.create('testCache');
+
+// will return now only the files that were modified or none
+// if no files were modified previous to the execution of this function
+var oFiles = cache.getUpdatedFiles(files);
+
+// if you want to prevent a file from being considered non modified
+// something useful if a file failed some sort of validation
+// you can then remove the entry from the cache doing
+cache.removeEntry('path/to/file'); // path to file should be the same path of the file received on `getUpdatedFiles`
+// that will effectively make the file to appear again as modified until the validation is passed. In that
+// case you should not remove it from the cache
+
+// if you need all the files, so you can determine what to do with the changed ones
+// you can call
+var oFiles = cache.normalizeEntries(files);
+
+// oFiles will be an array of objects like the following
+entry = {
+ key: 'some/name/file', the path to the file
+ changed: true, // if the file was changed since previous run
+ meta: {
+ size: 3242, // the size of the file
+ mtime: 231231231, // the modification time of the file
+ data: {} // some extra field stored for this file (useful to save the result of a transformation on the file
+ }
+}
+
+```
+
+## Motivation for this module
+
+I needed a super simple and dumb **in-memory cache** with optional disk persistence (write-back cache) in order to make
+a script that will beautify files with `esformatter` to execute only on the files that were changed since the last run.
+
+In doing so the process of beautifying files was reduced from several seconds to a small fraction of a second.
+
+This module uses [flat-cache](https://www.npmjs.com/package/flat-cache) a super simple `key/value` cache storage with
+optional file persistance.
+
+The main idea is to read the files when the task begins, apply the transforms required, and if the process succeed,
+then store the new state of the files. The next time this module request for `getChangedFiles` will return only
+the files that were modified. Making the process to end faster.
+
+This module could also be used by processes that modify the files applying a transform, in that case the result of the
+transform could be stored in the `meta` field, of the entries. Anything added to the meta field will be persisted.
+Those processes won't need to call `getChangedFiles` they will instead call `normalizeEntries` that will return the
+entries with a `changed` field that can be used to determine if the file was changed or not. If it was not changed
+the transformed stored data could be used instead of actually applying the transformation, saving time in case of only
+a few files changed.
+
+In the worst case scenario all the files will be processed. In the best case scenario only a few of them will be processed.
+
+## Important notes
+- The values set on the meta attribute of the entries should be `stringify-able` ones if possible, flat-cache uses `circular-json` to try to persist circular structures, but this should be considered experimental. The best results are always obtained with non circular values
+- All the changes to the cache state are done to memory first and only persisted after reconcile.
+- By default non visited entries are removed from the cache. This is done to prevent the file from growing too much. If this is not an issue and
+ you prefer to do a manual pruning of the cache files, you can pass `true` to the `reconcile` call. Like this:
+
+ ```javascript
+ cache.reconcile( true /* noPrune */ );
+ ```
+
+## License
+
+MIT
+
+