inline-js-core

inline-js-core
==============


The core part of inline-js. Create an inliner with multiple resource loaders, transformers, and shortcuts.

Installation
------------
``
npm install inline-js-core
`

API
----

This module exports following members:

* createInliner: Create an inliner.



$3



`js
const inliner = createInliner({
maxDepth?: Number
});
`

maxDepth - the max recursion depth. Default: 10.

$3

`js
const inlineResult = await inliner.inline({
target: {
name: String,
args: Array
},
source?: Object,
content?: String|Buffer
});
`

Read the resource from target and process $inline directives recursively.

target is a resource specifier. A simple file could be represented as:

`js
{
name: "file",
args: ["D:\myfile.txt"]
}
`

source is also a resource specifier like target. It is only used to resolve relative path to absolute path:

`js
const source = {
name: "file",
args: ["D:\foo.txt"]
};
const target = {
name: "file",
args: ["bar.txt"]
};
inliner.resource.resolve(source, target);
console.log(target);
/*
{
name: "file",
args: ["D:\bar.txt"]
}
*/
`

inlineResult has following properties:

* content: Buffer|String - the output content.
* target: Object - the target resource that is processed.
* children: [...inlineResult: Object] - inlineResults of child dependencies (i.e. files being inlined by target).

$3

`js
inliner.useConfig({
resources?: Array,
transforms?: Array,
shortcuts?: Array
});
`

A utility function to add resources, shortcuts, and transforms from a config object. If the argument is falsy, this function has no effect.

$3

`js
inliner.resource.add({
name: String,
read: async (source: Object, target: Object) => String|Buffer,
resolve?: (source: Object, target: Object) => null,
hash?: (source: Object, target: Object) => String
});
`

Add a resource loader.

name is the name of the resource loader.

read should return the content of target file. source is the parent file that inlines target.

If resolve is defined, inliner would call this function before read.

hash should convert a (source, target) pair into a unique string that inliner would use it to cache the content. If hash is undefined then the content is never cached.

$3

`js
inliner.resource.remove(name: String);
`

Remove a resource loader that the name is name.

$3

`js
const content = await inliner.resource.read(source: Object, target: Object);
`

Find the resource loader matching target.name then call the read function of the resource loader. Inliner would try caching the result after read.

$3

A Map object containing hash: String/pendingContent: Promise pairs.

$3

`js
inliner.transformer.add({
name: String,
transform: async (context: Object, content: String|Buffer, ...args) => outputContent: String|Buffer
});
`

name is the name of the transformer.

transform function is used to transform content.

context object provides some additional information about the source resource. It has following properties:

* inlineTarget: Object - the target resource. The file that is being inlined and transformed.
* inlineDirective - an object that represents an inline directive. It has following properties:

- type: String - could be $inline, line, start, or open.
- params: Array - arguments of the inline function.
- start: Number - the start index of the replace range.
- end: Number - the end index of the replace range.

* source: Object - the source resource. The file containing the inline directive.
* sourceContent: String - the content of source.

Other args is specified by the $inline directive. For example:

`js
$inline("myfile|transformA:foo,bar")
`

In this case, args would be ["foo", "bar"].

$3

`js
inliner.transformer.remove(name: String)
`

Remove the transformer.

$3

`js
const outputContent = await inliner.transformer.transform(
context: Object,
content: String|Buffer,
transforms: Array