broccoli-persistent-filter - npm Package Compare versions

Comparing version 0.0.1 to 0.0.2

index.js

@@ -5,5 +5,68 @@ var Filter = require('broccoli-filter');
 var fs = require('fs');
+var hashForDep = require('hash-for-dep');
 
 module.exports = PersistentFilter;
 
+/*
+ * @public
+ *
+ * `broccoli-persistent-filter` is broccoli-filter but it is able to persit
+ * state across restarts. This exists to mitigate the upfront cost of some more
+ * expensive transforms on warm boot.
+ *
+ * Why isn't this the default behaviour?
+ *
+ * Deriving the correct cache key for a
+ * given filter can be tricky. In addition, this should be seen as a last
+ * resort, if a given filter is too slow often times it should be improved
+ * rather then opting for caching.
+ *
+ * What does this do?
+ *
+ * * This does not aim to improve incremental build performance, if it does, it
+ *   should indicate something is wrong with the filter ir input filter in
+ *   question.
+ *
+ * * This does not improve cold boot times.
+ *
+ * How does it work?
+ *
+ * It does so but establishing a 2 layer file cache.
+ * The first layer, is the entire bucket. The second, `cacheKeyProcessString`
+ * is a per file cache key.
+ *
+ * Together, these two layers should provide the right balance of speed and
+ * sensibility.
+ *
+ * The bucket level cacheKey must be stable but also never become stale. If the
+ * key is not stable, state between restarts will be lost and performance will
+ * suffer.  On the flip-side, if the cacheKey becomes stale changes may not be
+ * correctly reflected.
+ *
+ * It is configured by subclassing and refining `cacheKey` method. A good key
+ * here, is likely the name of the plugin, its version and the actual versions
+ * of its dependencies
+ *
+ * ```js
+ * Subclass.prototype.cacheKey = function() {
+ *  return md5(Filter.prototype.call(this) + inputOptionsChecksum + dependencyVersionChecksum);
+ * }
+ * ```
+ *
+ * The second key, represents the contents of the file. Typically the
+ * base-class's functionality is sufficient, as it merely generates a checksum
+ * of the file contents. If for some reason this is not sufficient, it can be
+ * re-configured via subclassing.
+ *
+ * ```js
+ * Subbclass.prototype.cacheKeyProcessString = function(string, relativePath) {
+ *   return superAwsomeDigest(string);
+ * }
+ * ```
+ *
+ * @class PersistentFilter
+ * @param {Tree} inputTree
+ * @param {Object} options
+ *
+ * */
 function PersistentFilter(inputTree, options) {
@@ -16,7 +79,28 @@ Filter.call(this, inputTree, options);
 
+/*
+ * @private
+ * 
+ *
+ * @method cachKey
+ * @return {String} this filters top-level cache key
+ */
 PersistentFilter.prototype.cacheKey = function() {
-  // this will be have to be derived from the checksum of the dependencies
-  return 'persistent-filter-3';
+  return hashForDep(this.baseDir());
 };
 
+/* @public
+ *
+ * @method baseDir
+ * @returns {String} absolute path to the root of the filter...
+ */
+PersistentFilter.prototype.baseDir = function() {
+  throw Error('Filter must implement prototype.baseDir');
+};
+
+/*
+ * @public
+ *
+ * @method cacheKeyProcessString
+ * @return {String} this filters top-level cache key
+ */
 PersistentFilter.prototype.cacheKeyProcessString = function(string, relativePath) {
@@ -26,2 +110,12 @@ return crypto.createHash('md5').update(string).digest('hex');
 
+
+/*
+ * @private
+ *
+ * @method processFile
+ * @param {String} srcDir
+ * @param {String} destDir
+ * @param {String} relativePath
+ * @return {Promise}
+ */
 PersistentFilter.prototype.processFile = function(srcDir, destDir, relativePath) {
@@ -28,0 +122,0 @@ var filter = this;

package.json

 {
   "name": "broccoli-persistent-filter",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "broccoli filter but with a persistent cache",
@@ -25,4 +25,5 @@ "main": "index.js",
     "async-disk-cache": "0.0.1",
-    "broccoli-filter": "^0.1.12"
+    "broccoli-filter": "^0.1.12",
+    "hash-for-dep": "0.0.3"
   }
 }

No alert changes

Improved metrics

Total package byte prevSize

4948

increased by119.42%

Lines of code

124

increased by287.5%

Worsened metrics

Dependency count

3

increased by50%

Dependency changes

• + Addedhash-for-dep@0.0.3

• + Addedfunction-bind@1.1.2(transitive)

• + Addedhash-for-dep@0.0.3(transitive)

• + Addedhasown@2.0.2(transitive)

• + Addedis-core-module@2.14.0(transitive)

• + Addedpath-parse@1.0.7(transitive)

• + Addedresolve@1.22.8(transitive)

• + Addedsupports-preserve-symlinks-flag@1.0.0(transitive)