feat(pipe): uniform steps (#377)

BREAKING CHANGE: removed before(), once() and after() methods in favor of use()
- added new uniform method pipe.use()
- added new method pipe.attach.replace() to replace pipeline steps
- pipe.attach() now public API, accepts object with before, replace and after keys
- removed methods before(), once() and after()

Author: rofe

README.md

@@ -53,13 +53,13 @@ module.exports.pipe = function(cont, context, action) {
     action.logger.log("debug", "Constructing Custom Pipeline");
 
     return pipeline()
-        .before(adjustContent)
-        .once(cont)            // required: execute the continuation function
-        .after(cleanupContent)
+        .use(adjustContent)
+        .use(cont)            // execute the continuation function
+        .use(cleanupContent)
 }
 ```
 
-In a typical pipeline, you will add additional processing steps as `.before(require('some-module'))` or as `.after(require('some-module'))`.
+In a typical pipeline, you will add additional processing steps as `.use(require('some-module'))`.
 
 ### The Main Function
 
@@ -138,11 +138,11 @@ Example:
 
 ```js
 new pipeline()
-  .before(doSomething)
-  .once(render)
-  .after(cleanup)
+  .use(doSomething)
+  .use(render)
+  .use(cleanup)
   .error(handleError)
-  .after(done);
+  .use(done);
 ```
 
 If in the above example, the `doSomething` causes an error, subsequently, `render` and `cleanup` will not be invoked. but `handleError` will. If `handleError` clears the error state (i.e. sets `context.error = null`), the `done` function will be invoked again.
@@ -151,16 +151,16 @@ If in the above example, none of the functions causes an error, the `handleError
 
 ### Extension Points
 
-In addition to the (optional) wrapper function which can be invoked prior to the `once` function, pipeline creators can expose named extension points. These extension points allow users of a pipeline to inject additional functions that will be called right before or right after an extension point. To keep the extension points independent from the implementation (i.e. the name of the function), pipeline authors should use the `expose(name)` function to expose a particular extension point.
+In addition to the (optional) wrapper function which can be invoked prior to the `once` function, pipeline creators can expose named extension points. These extension points allow users of a pipeline to inject additional functions that will be called right before, right after or instead of an extension point. To keep the extension points independent from the implementation (i.e. the name of the function), pipeline authors should use the `expose(name)` function to expose a particular extension point.
 
 Example:
 
 ```js
 new pipeline()
-  .before(doSomething).expose('init')
-  .once(render)
-  .after(cleanup).expose('cleanup')
-  .after(done);
+  .use(doSomething).expose('init')
+  .use(render)
+  .use(cleanup).expose('cleanup')
+  .use(done);
 ```
 
 In this example, two extension points, `init` and `cleanup` have been defined. Note how the name of the extension point can be the same as the name of the function (i.e. `cleanup`), but does not have to be the same (i.e. `init` vs. `doSomething`).
@@ -181,6 +181,7 @@ The easiest way to use extension points is by expanding on the [Wrapper Function
 
 - a `before` object
 - an `after` object
+- a `replace` object
 
 Each of these objects can have keys that correspond to the named extension points defined for the pipeline.
 
@@ -198,6 +199,12 @@ module.exports.after = {
     // will get called after the "fetch" pipeline step
   }
 }
+
+module.exports.replace = {
+  meta: (context, action) => {
+    // will get called instead of the "meta" pipeline step
+  }
+}
 ```
 
 All functions that are using the `before` and `after` extension points need to follow the same interface that all other pipeline functions follow, i.e. they have access to `context` and `action` and they should return a modified `context` object.

src/defaults/default.js

@@ -24,7 +24,7 @@ const Pipeline = require('../pipeline.js');
  */
 function pipe(next, context, action) {
   const mypipeline = new Pipeline(action);
-  mypipeline.once(next);
+  mypipeline.use(next);
   return mypipeline.run(context);
 }
 

src/defaults/html.pipe.js

@@ -59,31 +59,31 @@ const htmlpipe = (cont, context, action) => {
     .every(dump.record)
     .every(validate).when(() => !production())
     .every(timer.update)
-    .before(resolveRef).expose('resolve').when(hascontent)
-    .before(fetch).expose('fetch').when(hascontent)
-    .before(parse).expose('parse')
-    .before(parseFrontmatter)
-    .before(embeds)
-    .before(smartypants)
-    .before(sections)
-    .before(meta).expose('meta')
-    .before(unwrapSoleImages)
-    .before(selectstrain)
-    .before(selecttest)
-    .before(html).expose('html')
-    .before(sanitize).when(paranoid)
-    .once(cont)
-    .after(type('text/html'))
-    .after(cache).when(uncached)
-    .after(key)
-    .after(tovdom).expose('post') // start HTML post-processing
-    .after(removeHlxProps).when(() => production())
-    .after(rewriteLinks).when(production)
-    .after(addHeaders)
-    .after(tohtml) // end HTML post-processing
-    .after(flag).expose('esi').when(esi) // flag ESI when there is ESI in the response
-    .after(debug)
-    .after(timer.report)
+    .use(resolveRef).expose('resolve').when(hascontent)
+    .use(fetch).expose('fetch').when(hascontent)
+    .use(parse).expose('parse')
+    .use(parseFrontmatter)
+    .use(embeds)
+    .use(smartypants)
+    .use(sections)
+    .use(meta).expose('meta')
+    .use(unwrapSoleImages)
+    .use(selectstrain)
+    .use(selecttest)
+    .use(html).expose('html')
+    .use(sanitize).when(paranoid)
+    .use(cont)
+    .use(type('text/html'))
+    .use(cache).when(uncached)
+    .use(key)
+    .use(tovdom).expose('post') // start HTML post-processing
+    .use(removeHlxProps).when(() => production())
+    .use(rewriteLinks).when(production)
+    .use(addHeaders)
+    .use(tohtml) // end HTML post-processing
+    .use(flag).expose('esi').when(esi) // flag ESI when there is ESI in the response
+    .use(debug)
+    .use(timer.report)
     .error(dump.report)
     .error(selectStatus);
 

src/defaults/json.pipe.js

@@ -37,16 +37,16 @@ const jsonpipe = (cont, context, action) => {
     .every(dump.record)
     .every(validate).when(() => !production())
     .every(timer.update)
-    .before(fetch).expose('fetch')
-    .before(parse).expose('parse')
-    .before(parseFrontmatter)
-    .before(smartypants)
-    .before(sections)
-    .before(meta).expose('meta')
-    .once(cont)
-    .after(emit).expose('json')
-    .after(type('application/json'))
-    .after(timer.report)
+    .use(fetch).expose('fetch')
+    .use(parse).expose('parse')
+    .use(parseFrontmatter)
+    .use(smartypants)
+    .use(sections)
+    .use(meta).expose('meta')
+    .use(cont)
+    .use(emit).expose('json')
+    .use(type('application/json'))
+    .use(timer.report)
     .error(dump.report)
     .error(selectStatus(production()));
 

src/defaults/xml.pipe.js

@@ -41,21 +41,20 @@ const xmlpipe = (cont, context, action) => {
     .every(dump.record)
     .every(validate).when(() => !production())
     .every(timer.update)
-    .before(fetch).expose('fetch')
-    .before(parse).expose('parse')
-    .before(parseFrontmatter)
-    .before(smartypants)
-    .before(sections)
-    .before(meta).expose('meta')
-    .once(cont)
-    .after(emit).expose('xml')
-    .after(type('application/xml'))
-    .after(check)
-    .after(cache)
-    .when(uncached)
-    .after(key)
-    .after(flag).expose('esi').when(esi) // flag ESI when there is ESI in the response
-    .after(timer.report)
+    .use(fetch).expose('fetch')
+    .use(parse).expose('parse')
+    .use(parseFrontmatter)
+    .use(smartypants)
+    .use(sections)
+    .use(meta).expose('meta')
+    .use(cont)
+    .use(emit).expose('xml')
+    .use(type('application/xml'))
+    .use(check)
+    .use(cache).when(uncached)
+    .use(key)
+    .use(flag).expose('esi').when(esi) // flag ESI when there is ESI in the response
+    .use(timer.report)
     .error(dump.report)
     .error(selectStatus);