README.md
1<p align="center"><img src="https://cdn.rawgit.com/jstransformers/jstransformer/2bb6dc6c410e8683a17a4af5f1b73bcbee95aada/logo.svg" width="300px" height="299px" /></p>
2<h1 align="center">JSTransformer</h1>
3<p align="center">Normalize the API of any jstransformer</p>
4
5<p align="center"><a href="https://travis-ci.org/jstransformers/jstransformer"><img src="https://img.shields.io/travis/jstransformers/jstransformer/master.svg" alt="Build Status"></a>
6<a href="https://david-dm.org/jstransformers/jstransformer"><img src="https://img.shields.io/david/jstransformers/jstransformer.svg" alt="Dependency Status"></a>
7<a href="https://david-dm.org/jstransformers/jstransformer#info=devDependencies"><img src="https://img.shields.io/david/dev/jstransformers/jstransformer.svg" alt="Developers' Dependency Status"></a>
8<a href="https://coveralls.io/r/jstransformers/jstransformer?branch=master"><img src="https://img.shields.io/coveralls/jstransformers/jstransformer/master.svg" alt="Coverage Status"></a>
9<a href="https://www.npmjs.org/package/jstransformer"><img src="https://img.shields.io/npm/v/jstransformer.svg" alt="NPM version"></a></p>
10
11## Installation
12
13 npm install jstransformer
14
15## Usage
16
17```js
18var transformer = require('jstransformer');
19var marked = transformer(require('jstransformer-marked'));
20
21var options = {};
22var res = marked.render('Some **markdown**', options);
23// => {body: 'Some <strong>markdown</strong>', dependencies: []}
24```
25
26This gives the same API regardless of the jstransformer passed in.
27
28## API
29
30A transformer, once normalised using this module, will implement the following methods. Note that if the underlying transformer cannot be used to implement the functionality, it may ultimately just throw an error.
31
32### Returned object from `.render*`
33
34```js
35{body: String, dependencies: Array.<String>}
36```
37
38 - `body` represents the result as a string
39 - `dependencies` is an array of files that were read in as part of the render process (or an empty array if there were no dependencies)
40
41### `.render`
42
43```js
44transformer.render(str, options, locals);
45=> {body: String, dependencies: Array.<String>}
46```
47
48_requires the underlying transform to implement `.render` or `.compile`_
49
50Transform a string and return an object.
51
52### `.renderAsync`
53
54```js
55transformer.renderAsync(str[, options], locals, callback);
56```
57
58```js
59transformer.renderAsync(str[, options], locals);
60=> Promise({body: String, dependencies: Array.<String>})
61```
62
63_requires the underlying transform to implement `.renderAsync` or `.render`_
64
65Transform a string asynchronously. If a callback is provided, it is called as `callback(err, data)`, otherwise a Promise is returned.
66
67### `.renderFile`
68
69```js
70transformer.renderFile(filename, options, locals)
71=> {body: String, dependencies: Array.<String>}
72```
73
74_requires the underlying transform to implement `.renderFile`, `.render`, `.compileFile`, or `.compile`_
75
76Transform a file and return an object.
77
78### `.renderFileAsync`
79
80```js
81transformer.renderFileAsync(filename[, options], locals, callback);
82```
83
84```js
85transformer.renderFileAsync(filename[, options], locals);
86=> Promise({body: String, dependencies: Array.<String>})
87```
88
89_requires the underlying transform to implement `.renderFileAsync`, `.renderFile`, `.renderAsync`, `.render`, `.compileFileAsync`, `.compileFile`, `.compileAsync`, or `.compileFile`_
90
91Transform a file asynchronously. If a callback is provided, it is called as `callback(err, data)`, otherwise a Promise is returned.
92
93### `.inputFormats`
94
95```js
96var formats = transformer.inputFormats;
97=> ['md', 'markdown']
98```
99
100Returns an array of strings representing potential input formats for the transform. If not provided directly by the transform, results in an array containing the name of the transform.
101
102### `.outputFormat`
103
104```js
105var md = require('jstransformer')(require('jstransformer-markdown'))
106var outputFormat = md.outputFormat
107=> 'html'
108```
109
110Returns a string representing the default output format the transform would be expected to return when calling `.render()`.
111
112## License
113
114MIT
115
