Code improvements

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 #### v3.0.0
 
+- New Features:
+  - The _middleware_ function must not need a Promise anymore, but is still recommended.
+
 - **CLI & API Changes (Backwards Incompatible!):**
   - Removed support for Node.js < v4.0
   - Default `options.indent` is 2 (instead of 4) now which seems to be more common in the JS/Node.js community
@@ -23,7 +26,7 @@
   - Removal of _development_ branch
   - Usage of [babel](https://babeljs.io/) and therefore most modern language features
   - Code base could be shrinked and readabilty was improved
-  - Usage of _native promises_ instead of [bluebird](http://bluebirdjs.com/docs/getting-started.html)
+  - Usage of _native_ Promises instead of [bluebird](http://bluebirdjs.com/docs/getting-started.html)
   - Tests re-written in [Jest](https://facebook.github.io/jest) (could get rid  of [assert](https://github.com/defunctzombie/commonjs-assert),
     [mocha](https://mochajs.org/) and [istanbul](https://github.com/gotwarlost/istanbul))
   - Add travis build for Node.js v8.x

README.md

@@ -36,7 +36,8 @@ npm install jy-transform --global
 ```javascript
 import { transform, read, write } from 'jy-transform';
 
-// --- transform
+
+// --- transform from source to destination ---
 
 const transformOptions = {
   src: 'foo/bar.yaml',
@@ -49,25 +50,28 @@ const transformFunc = async (object) => {
   return object;
 };
 
+// of course, inside an async
 try {
   const msg = await transform(transformOptions, transformFunc);
   console.log(msg);
 } catch (err) {
   console.error(err.stack);
 }
 
-// --- read
+
+// --- read into JS object from particular source (file, stream or JS object) ---
 
 let object;
 
 try {
-  object = await read({ src: 'foo/bar.yaml' });
+  object = await read({ src: 'foo/bar.yaml' }); // here: read from file
   console.log(JSON.stringify(object));
 } catch (err) {
   console.error(err.stack);
 }
 
-// --- write
+
+// --- write a JS object to particular destination ---
 
 try {
   const msg = await write(object, { dest: 'foo/bar.yaml' });
@@ -87,7 +91,8 @@ types into each other format.
 
 ## Usage
 
-The module can be used on CLI or as API (the latter is fully [Promise](http://bluebirdjs.com/docs/api-reference.html)
+The module can be used on CLI or as API (the latter is fully
+[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise))
 based).
 
 ### Usage Types
@@ -111,23 +116,26 @@ these consists of different phases:
 
 #### Reading
 
-Reading from:
+From:
 
 - _*.yaml_ file
 - _*.js_ file
 - _*.json_ file
 
-Additionally, on API level to a:
+Additionally, on API level from a:
 
 - `stream.Readable`
- - Serialized JSON and YAML
- - Requires `options.origin` property set
+ - Contain serialized JS, JSON or YAML
+ - If not file stream it requires `options.origin` property set
  - Reads as UTF-8
-- JS `object` (actually, this means the reading phase is skipped, because object is in-memory already)
+- JS `object`
+ - Actually, this means the reading phase is "skipped", because object is in-memory already
+ - Of course, this case _cannot_ not be applied to serialized JSON or YAML content
 
-#### Transformation
+#### Transformation [+ Middleware] 
 
-The transformation can take place into several directions:
+The _transformation_ is usually a format change, but can also be refer to content changes on the
+intermediate JS object (the latter via _middleware_). All possible directions are:
 
 - YAML ⇒ JS
 - YAML ⇒ JSON
@@ -145,14 +153,12 @@ while:
 - [JS](https://developer.mozilla.org/en-US/docs/Web/JavaScript) = _*.js_ (JS object)
 - [JSON](http://json.org) = _*.json_ (JS object serialized as JSON)
 
-#### Middleware
-
-Apply actions on the intermediate JS object via injected [Promise](http://bluebirdjs.com/docs/api-reference.html)
-functions. This is an optional part for [transformation](#transformation) phase.
+As mentioned above a _middleware_ can apply particular actions on the intermediate JS object via injected functions.
+This is an optional part for [transformation](#transformation) phase.
 
 #### Writing
 
-Writing to:
+To:
 
 - _*.yaml_ file
 - _*.js_ file
@@ -164,7 +170,9 @@ Additionally, on API level to a:
  - Serialized JS, JSON and YAML
  - Requires `options.target` property set
  - Writes UTF-8
-- JS `object`
+- JS `object
+ - JS as simple reference
+ - YAML and JSON as serialized string
 
 ### Limitations
 

readme/DOCUMENTATION.md

@@ -561,17 +561,17 @@ given (initially empty) JS object.
 
 ```javascript
 const key1 = async (data) => {
-  objectPath.set(data, 'key1', 'value1');
+  odata.key1 = 'value1';
   return data;
 };
 
 const key2 = async (data) => {
-  objectPath.set(data, 'key2', 'value2');
+  data.key2 = 'value2';
   return data;
 };
 
 const key3 = async (data) => {
-  objectPath.set(data, 'key3', 'value3');
+  data.key3 = 'value3';
   return data;
 };
 ```

src/cli.js

@@ -81,7 +81,7 @@ function error(err) {
  *
  * @param {Array} args     - The first mandatory argument is the input file (`args[0]`), the second (optional)
  *                           argument is the output file (`args[1]`).
- * @param {module:type-definitions~Options} cliOptions - The options provided via CLI.
+ * @param {module:jy-transform:type-definitions~Options} cliOptions - The options provided via CLI.
  * @private
  */
 function main(args, cliOptions) {

src/constants.js

@@ -1,15 +1,15 @@
 /**
  * @module jy-transform:constants
  * @description Useful constants used for the module and its usage.
- * @public
+ * @private
  */
 
 /**
  * The 'utf8' constant.
  *
  * @type {string}
  * @constant
- * @public
+ * @private
  */
 export const UTF8 = 'utf8';
 
@@ -42,7 +42,7 @@ export const TYPE_JS = 'js';
  * A map for extensions to type.
  *
  * @type {{yml: string, yaml: string, js: string, json: string}}
- * @public
+ * @private
  */
 export const TYPE_MAP = {
   yml: TYPE_YAML,
@@ -55,55 +55,55 @@ export const TYPE_MAP = {
  * The default file indention (4 SPACEs).
  * @type {number}
  * @constant
- * @public
+ * @private
  */
 export const DEFAULT_INDENT = 2;
 
 /**
  * The minimum file indention (0 SPACE).
  * @type {number}
  * @constant
- * @public
+ * @private
  */
 export const MIN_INDENT = 0;
 
 /**
  * The maximum file indention (8 SPACEs).
  * @type {number}
  * @constant
- * @public
+ * @private
  */
 export const MAX_INDENT = 8;
 
 /**
  * The default `origin` value: 'yaml'.
  * @type {string}
  * @constant
- * @public
+ * @private
  */
 export const DEFAULT_ORIGIN = TYPE_YAML;
 
 /**
  * The default `origin` value: 'js'.
  * @type {string}
  * @constant
- * @public
+ * @private
  */
 export const DEFAULT_TARGET = TYPE_JS;
 
 /**
  * Whether to overwrite existing file or object on output.
  * @type {boolean}
  * @constant
- * @public
+ * @private
  */
 export const DEFAULT_FORCE_FILE_OVERWRITE = false;
 
 /**
  * The `origin` description value.
  * @type {string}
  * @constant
- * @public
+ * @private
  */
 export const ORIGIN_DESCRIPTION = 'if not given, the type is tried to be inferred from the extension of source path, ' +
   'else it is \'' + DEFAULT_ORIGIN + '\'';
@@ -112,7 +112,7 @@ export const ORIGIN_DESCRIPTION = 'if not given, the type is tried to be inferre
  * The `target` description value.
  * @type {string}
  * @constant
- * @public
+ * @private
  */
 export const TARGET_DESCRIPTION = 'if not given, the type is tried to be inferred from the extension of destination' +
   ' path, else it is \'' + DEFAULT_TARGET + '\'';
@@ -121,14 +121,14 @@ export const TARGET_DESCRIPTION = 'if not given, the type is tried to be inferre
  * The `dest` description value.
  * @type {string}
  * @constant
- * @public
+ * @private
  */
 export const DEST_DESCRIPTION = 'storing relative to input file';
 
 /**
  * The `src` exports identifier value to read.
  * @type {string}
- * @public
+ * @private
  * @constant
  * @example
  * module.exports.foo = {...}; // here 'foo' is the identifier for an object to read from the source!
@@ -138,7 +138,7 @@ export const DEFAULT_JS_IMPORTS_IDENTIFIER = undefined;
 /**
  * The `dest` exports identifier value to write.
  * @type {string}
- * @public
+ * @private
  * @constant
  */
 export const DEFAULT_JS_EXPORTS_IDENTIFIER = undefined;
@@ -157,6 +157,7 @@ export const DEFAULT_JS_EXPORTS_IDENTIFIER = undefined;
  * @see {@link ORIGIN_DESCRIPTION}
  * @see {@link TARGET_DESCRIPTION}
  * @see {@link DEST_DESCRIPTION}
+ * @private
  */
 export const DEFAULT_OPTIONS = {
   origin: ORIGIN_DESCRIPTION,