DOC: Updated documentation

README.md

@@ -16,28 +16,72 @@ npm i --save file-entry-cache
 ```js
 // loads the cache, if one does not exists for the given 
 // Id a new one will be prepared to be created
-var cache = require('file-entry-cache').create('cacheId');
+var fileEntryCache = require('file-entry-cache');
 
-cache.getUpdatedFiles()
+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(); 
+
+// 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 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
+  }
+}
 
-var cache = require('file-entry-cache').load('cacheId', path.resolve('./path/to/folder'));
 ```
 
 ## Motivation for this module
 
-I needed a super simple and dumb **in-memory cache** with optional disk persistance in order to make 
-a script that will beutify files with `esformatter` only execute on the files that were changed since the last run.
-To make that possible we need to store the `fileSize` and `modificationTime` of the files. So a simple `key/value` 
-storage was needed and Bam! this module was born.
+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
-- If no directory is especified when the `load` method is called, a folder named `.cache` will be created 
-  inside the module directory when `cache.save` is called. If you're committing your `node_modules` to any vcs, you
-  might want to ignore the default `.cache` folder, or specify a custom directory.
-- The values set on the keys of the cache should be `stringify-able` ones, meaning no circular references
-- All the changes to the cache state are done to memory
-- I could have used a timer or `Object.observe` to deliver the changes to disk, but I wanted to keep this module
-  intentionally dumb and simple
+- The values set on the meta attribute of the entries should be `stringify-able` ones, meaning no circular references
+- All the changes to the cache state are done to memory first and only persisted after reconcile
 
 ## License