Minor tweaks for sync docs

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## Head
+
+- Added: `sync` option.
+
 ## 2.1.3
 
 - Licensing improvement: switched from `json-parse-helpfulerror` to `parse-json`.

README.md

@@ -14,7 +14,7 @@ For example, if your module's name is "soursocks," cosmiconfig will search out c
 - a `soursocks.config.js` file exporting a JS object (anywhere down the file tree)
 - a CLI `--config` argument
 
-cosmiconfig continues to search in these places all the way down the file tree until it finds acceptable configuration (or hits the home directory). And it does all this asynchronously by default, so it shouldn't get in your way.
+cosmiconfig continues to search in these places all the way down the file tree until it finds acceptable configuration (or hits the home directory).
 
 Additionally, all of these search locations are configurable: you can customize filenames or turn off any location.
 
@@ -49,7 +49,7 @@ explorer.load(yourSearchPath)
 The function `cosmiconfig()` searches for a configuration object and returns a Promise,
 which resolves with an object containing the information you're looking for.
 
-You can also pass option `sync: true` to load the config synchronously.
+You can also pass option `sync: true` to load the config synchronously, returning the config itself.
 
 So let's say `var yourModuleName = 'goldengrahams'` — here's how cosmiconfig will work:
 
@@ -183,8 +183,8 @@ Type: `Function`
 
 A function that transforms the parsed configuration. Receives the result object with `config` and `filepath` properties.
 
-If the option `sync` is `false`(default), the function must return a Promise that resolves with the transformed result.
-Otherwise, `transform` should be a synchronous function which returns the transformed result.
+If the option `sync` is `false` (default), the function must return a Promise that resolves with the transformed result.
+If the option `sync` is `true`, though, `transform` should be a synchronous function which returns the transformed result.
 
 The reason you might use this option instead of simply applying your transform function some other way is that *the transformed result will be cached*. If your transformation involves additional filesystem I/O or other potentially slow processing, you can use this option to avoid repeating those steps every time a given configuration is loaded.
 
@@ -229,7 +229,7 @@ Performs both `clearFileCache()` and `clearDirectoryCache()`.
 - Built-in support for JSON, YAML, and CommonJS formats.
 - Stops at the first configuration found, instead of finding all that can be found down the filetree and merging them automatically.
 - Options.
-- Asynchronous by default, can be forced to use synchronous mode.
+- Asynchronous by default (though can be run synchronously).
 
 ## Contributing & Development
 

lib/createExplorer.js

@@ -9,8 +9,8 @@ var loadDefinedFile = require('./loadDefinedFile');
 var funcRunner = require('./funcRunner');
 
 module.exports = function (options) {
-  // When `options.sync` is `false`(default),
-  // These cache Promises that resolve with results, not the results themselves
+  // When `options.sync` is `false` (default),
+// these cache Promises that resolve with results, not the results themselves.
   var fileCache = (options.cache) ? new Map() : null;
   var directoryCache = (options.cache) ? new Map() : null;
   var transform = options.transform || (options.sync) ? identitySync : identityPromise;

lib/funcRunner.js

@@ -3,23 +3,26 @@
 var isPromise = require('is-promise');
 
 /**
- * Runs given functions. If the `init` param is a promise, functions are
- * chained using `p.then()`. Otherwise, functions are chained by passing
+ * Runs the given functions sequentially. If the `init` param is a promise,
+ * functions are chained using `p.then()`. Otherwise, functions are chained by passing
  * the result of each function to the next.
  *
- * @param {*} init
+ * @param {Promise | void} init
  * @param {Array<Function>} funcs
- * @returns {*} A promise if `init` was one, otherwise result of function
+ * @returns {Promise<*> | *} - A promise if `init` was one, otherwise result of function
  * chain execution.
  */
 module.exports = function funcRunner(init, funcs) {
-  var async = isPromise(init);
+  var isAsync = isPromise(init);
 
-  var res = init;
+  var result = init;
   funcs.forEach(function (func) {
-    if (async === true) res = res.then(func);
-    else res = func(res);
+    if (isAsync === true) {
+      result = result.then(func);
+    } else {
+      result = func(result);
+    }
   });
 
-  return res;
+  return result;
 };