commoner - npm Package Compare versions

Comparing version 0.8.6 to 0.8.7

lib/cache.js

@@ -9,3 +9,13 @@ var assert = require("assert");
 
-
+/**
+ * DiskCache persists processed text to disk so that the work of
+ * re-processing the input text can be avoided in the future.  It doubles
+ * as an in-process cache so that the underlying file only needs to be
+ * accessed once within the same process.
+ *
+ * Commoner uses the DiskCache to store fully processed module files in
+ * the .module-cache/ directory.  When an appropriate module file already
+ * exists in the cache directory, a hard link can be quickly created
+ * between the cached file and the file in the build output directory.
+ */
 function DiskCache(cacheDirP) {
@@ -22,2 +32,18 @@ var self = this;
 
+/**
+ * Primary method for setting the value of a key in the DiskCache.
+ *
+ * Typically, toStringP will be a zero-argument thunk that is expensive to
+ * execute, and its execution will be avoided when the cache already has a
+ * value for the given key.
+ *
+ * The fromStringP callback takes the string generated by toStringP() and
+ * deserializes it.  The resulting value is cached in memory within the
+ * process.
+ *
+ * Commoner calls setDefaultP with a toStringP function that does all the
+ * necessary processing to generate a pure CommonJS module string, and
+ * provides a fromStringP function that constructs a convenient Module
+ * object from that string.
+ */
 DCp.setDefaultP = util.cachedMethod(function(key, toStringP, fromStringP) {
@@ -41,2 +67,10 @@ return this.cacheDirP.then(function(cacheDir) {
 
+/**
+ * Method for creating a hard link between the underlying cache file and
+ * some other file that should appear to contain the same contents.
+ *
+ * The cache directory structure is perfectly flat, with each file named
+ * <key>.js according to its key.  Files that are hard-linked to files in
+ * the cache directory can have arbitrary names and directory paths.
+ */
 DCp.linkP = function(key, file) {
@@ -60,3 +94,8 @@ return Q.all([
 
-
+/**
+ * The ProcessCache behaves just like the DiskCache except that it makes
+ * no effort to persist the result of toStringP to disk.  In other words,
+ * the only benefit of the ProcessCache is that it caches the final result
+ * of fromStringP within the current process (hence the name).
+ */
 function ProcessCache() {
@@ -77,2 +116,7 @@ assert.ok(this instanceof ProcessCache);
 
+/**
+ * Since there is no underlying file with which to create a hard link,
+ * this method just writes a copy of the cached file contents into the
+ * desired file.
+ */
 PCp.linkP = function(key, file) {
@@ -99,3 +143,10 @@ return Q.all([
 
-
+/**
+ * ReadFileCache is an EventEmitter subclass that caches file contents in
+ * memory so that subsequent calls to readFileP return the same contents,
+ * regardless of any changes in the underlying file.
+ *
+ * Note that this class has little to do with DiskCache and ProcessCache,
+ * except that all three are caches.
+ */
 function ReadFileCache(sourceDir) {
@@ -115,2 +166,5 @@ assert.ok(this instanceof ReadFileCache);
 
+/**
+ * Read a file from the cache if possible, else from disk.
+ */
 RFCp.readFileP = function(relativePath) {
@@ -126,2 +180,8 @@ var cache = this.sourceCache;
 
+/**
+ * Read (or re-read) a file without using the cache.
+ *
+ * The new contents are stored in the cache for any future calls to
+ * readFileP.
+ */
 RFCp.noCacheReadFileP = function(relativePath) {
@@ -141,2 +201,8 @@ relativePath = path.normalize(relativePath);
 
+/**
+ * If you have reason to believe the contents of a file have changed, call
+ * this method to re-read the file and compare the new contents to the
+ * cached contents.  If the new contents differ from the contents of the
+ * cache, the "changed" event will be emitted.
+ */
 RFCp.reportPossiblyChanged = function(relativePath) {
@@ -157,2 +223,7 @@ var self = this;
 
+/**
+ * Invoke the given callback for all files currently known to the
+ * ReadFileCache, and invoke it in the future when any new files become
+ * known to the cache.
+ */
 RFCp.subscribe = function(callback, context) {
@@ -170,2 +241,5 @@ for (var relativePath in this.sourceCache) {
 
+/**
+ * Avoid memory leaks by removing listeners and emptying the cache.
+ */
 RFCp.clear = function() {
@@ -172,0 +246,0 @@ this.removeAllListeners();

lib/commoner.js

@@ -24,2 +24,3 @@ var assert = require("assert");
     Object.defineProperties(self, {
+        customVersion: { value: null, writable: true },
         resolvers: { value: [] },
@@ -32,2 +33,7 @@ processors: { value: [] }
 
+Cp.version = function(version) {
+    this.customVersion = version;
+    return this; // For chaining.
+};
+
 // A resolver is a function that takes a module identifier and returns
@@ -182,4 +188,8 @@ // the unmodified source of the corresponding module, either as a string
 
-Cp.cliBuildP = function(version) {
-    var commoner = this;
+Cp.cliBuildP = function() {
+    var version = this.customVersion || require("../package.json").version;
+    return Q.all([this, version]).spread(cliBuildP);
+};
+
+function cliBuildP(commoner, version) {
     var options = require("commander");
@@ -207,6 +217,6 @@ var workingDir = process.cwd();
     // variables is preferable to passing them as arguments.
-    this.preferredFileExtension = pfe;
-    this.watch = options.watch;
-    this.ignoreDependencies = !options.followRequires;
-    this.relativize = options.relativize;
+    commoner.preferredFileExtension = pfe;
+    commoner.watch = options.watch;
+    commoner.ignoreDependencies = !options.followRequires;
+    commoner.relativize = options.relativize;
 
@@ -234,3 +244,3 @@ function fileToId(file) {
         // Ignore dependencies because we wouldn't know how to find them.
-        this.ignoreDependencies = true;
+        commoner.ignoreDependencies = true;
 
@@ -249,3 +259,3 @@ } else {
             // Ignore dependencies because we wouldn't know how to find them.
-            this.ignoreDependencies = true;
+            commoner.ignoreDependencies = true;
 
@@ -257,3 +267,3 @@ } else if (stats.isDirectory(first)) {
             if (roots.length === 0)
-                roots.push(this.preferredFileExtension.glob());
+                roots.push(commoner.preferredFileExtension.glob());
 
@@ -266,10 +276,10 @@ } else {
 
-    this.cacheDir = null;
+    commoner.cacheDir = null;
     if (options.cacheDir === false) {
         // Received the --no-cache-dir option, so disable the disk cache.
     } else if (typeof options.cacheDir === "string") {
-        this.cacheDir = absolutePath(workingDir, options.cacheDir);
+        commoner.cacheDir = absolutePath(workingDir, options.cacheDir);
     } else if (outputDir) {
         // The default cache directory lives inside the output directory.
-        this.cacheDir = path.join(outputDir, ".module-cache");
+        commoner.cacheDir = path.join(outputDir, ".module-cache");
     }
@@ -293,3 +303,3 @@
     ]).spread(commoner.buildP.bind(commoner));
-};
+}
 
@@ -296,0 +306,0 @@ function absolutePath(workingDir, pathToJoin) {

main.js

 var path = require("path");
-var util = require("./lib/util");
-
-var versionP = util.readJsonFileP(
-    path.join(__dirname, "package.json")
-).get("version");
-
 var Commoner = require("./lib/commoner").Commoner;
@@ -14,11 +8,10 @@ exports.Commoner = Commoner;
         var commoner = new Commoner;
-
-        versionP.then(function(version) {
-            commoner.cliBuildP(version);
-        });
-
-        return commoner[name].apply(commoner, arguments);
+        commoner[name].apply(commoner, arguments);
+        commoner.cliBuildP();
+        return commoner;
     };
 }
+
+defCallback("version");
 defCallback("resolve");
 defCallback("process");

package.json

@@ -17,3 +17,3 @@ {
   ],
-  "version": "0.8.6",
+  "version": "0.8.7",
   "license": "MIT",
@@ -20,0 +20,0 @@ "homepage": "http://github.com/benjamn/commoner",

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

85251

increased by4%

Lines of code

2073

increased by4.07%

No dependency changes