Stream Transform

Inject custom stream transformations

Accepts a list of functions that should return stream classes to be injected into the transformation pipeline.

The highlight transform implementation serves as a good example; it highlights code blocks with info strings and rewrites the document stream.

Install

npm i mktransform --save

For the command line interface install mkdoc globally (npm i -g mkdoc).

• Install
• Usage
• Example
• Stream Functions
• Help
• API
  • transform
• License

Usage

Create a file for the transform function like upper.js:

// converts level one headings to upper case
function upper(through, ast) {
  var Node = ast.Node
    , collect = ast.NodeWalker.collect
    , i
    , text;

  function transform(chunk, encoding, cb) {
    if(Node.is(chunk, Node.HEADING) && chunk.level === 1) {
      text = collect(chunk, Node.TEXT);
      for(i = 0;i < text.length;i++) {
        text[i].literal = text[i].literal.toUpperCase();
      }
    }
    this.push(chunk);
    cb();
  }

  return through.transform(transform);
}

module.exports = upper;

And pass in the transform function:

var tfm = require('mktransform')
  , ast = require('mkast')
  , upper = require('./upper');

ast.src('# Project\n\nThis is a paragraph.\n\n## Install')
  .pipe(tfm(upper))
  .pipe(ast.stringify({indent: 2}))
  .pipe(process.stdout);

Example

Run a custom stream transformation:

mkcat README.md | mktransform doc/upper.js | mkout

Run multiple transformations:

mkcat README.md | mktransform test/fixtures/upper1.js test/fixtures/upper2.js | mkout

Stream Functions

A stream function has the signature:

function(through, ast, opts)

It is passed the through module so you can easily create stream transform classes and ast so you may easily inspect nodes; the opts object is the original options object. The function must return a transform stream subclass.

The input and output data should always be abstract syntax tree nodes.

To create a transform stream subclass:

function transformer(through) {

  function transform(chunk, encoding, cb) {
    // pass through stream
    cb(null, chunk);
  }

  // return the stream subclass
  return through.transform(transform);
}

module.exports = transformer;

If you also need a flush function:

function transformer(through) {

  function transform(chunk, encoding, cb) {
    cb(null, chunk);
  }

  function flush(cb) {
    cb(); 
  }

  return through.transform(transform, flush);
}

module.exports = transformer;

To use a specific constructor:

function transformer(through) {

  function Component(opts) {
    this.opts = opts || {}; 
  }

  function transform(chunk, encoding, cb) {
    cb(null, chunk);
  }

  return through.transform(transform, {ctor: Component});
}

module.exports = transformer;

See through, ast and the api docs for more detail.

Help

Usage: mktransform [files...]

  Custom stream transformations.

Options
  -h, --help              Display help and exit
  --version               Print the version and exit

[email protected]

API

transform

transform(opts[, cb])

Injects custom stream transform classes into the pipeline.

Accepts a single function, array of functions or an object with a transforms array.

Functions have the signature:

function(through, ast, opts)

They are passed the through and ast modules to help with creating stream subclasses and inspecting nodes and the original options.

If you are using multiple stream transformations the options are shared between them so take care to avoid name collisions.

Each function must return a transform stream subclass.

The returned subclass is instantiated and when multiple transform functions are being used a pipeline is created between the streams in the order supplied.

When a single stream is being created it is returned otherwise an array of all the created streams is returned.

If both the input and output options are given additional wrapper streams are created that parse JSON from the input stream and write JSON to the output stream, in this instance you may pass a callback function which is added as a listener for the error and finish events on the output stream; the output stream is returned.

Returns an output stream or array of streams.

• opts Function|Array|Object processing options.
• cb Function callback function.

Options

• transforms Array list of transform functions.
• input Readable input stream.
• output Writable output stream.

Throws

• TypeError if the target is not a function.
• TypeError if the return value is not a function.
• TypeError if the stream instance has no pipe function.

License

MIT

Created by mkdoc on April 18, 2016