include-by-tag v0.0.5
Include by tag
Library to include a file(s) within another file. It will not work on circular imports due to recursive strategy.
For example we have some configuration hierarchy of JSON configuration files:
config
├── main.json
├── entries.json
├── colors.json
└── templates
├── number.json
├── string.json
└── boolean.json
With content
main.json
{
"name": "ibt",
"date": "2000-01-01T00:00+02:00",
"entries": "!include entries.json",
"templates": "!include templates/*.json"
}
entries.json
{
"actions": [ "To be", "Not to be" ],
"colors": "!include colors.json"
}
colors.json
[
{ "name": "black", "type": "boolean" },
{ "name": "white", "type": "boolean" },
{ "name": "red", "type": "number" },
{ "name": "blue", "type": "string" },
{ "name": "green", "type": "string" }
]
number.json
{
"name": "number",
"prop": "Final countdown"
}
string.json
{
"name": "string",
"prop": "A word is enough to the wise"
}
boolean.json
{
"name": "boolean",
"prop": "Bisected world"
}
And if we will reading main.json config we can asynchronously read included files:
main.json ->| entries.json ->| colors.json ->|
| boolean.json ->|
| number.json ->|
| string.json ->|
-------------------------------------------->| Full config
Final JSON will look like:
{
"name": "ibt",
"date": "2000-01-01T00:00+02:00",
"entries": {
"actions": [ "To be", "Not to be" ],
"colors": [
{ "name": "black", "type": "boolean" },
{ "name": "white", "type": "boolean" },
{ "name": "red", "type": "number" },
{ "name": "blue", "type": "string" },
{ "name": "green", "type": "string" }
]
},
"templates": [
{ "name": "boolean", "prop": "Bisected world" },
{ "name": "number", "prop": "Final countdown" },
{ "name": "string", "prop": "A word is enough to the wise" }
]
}
Usage
const IBT = require('include-by-tag');
const yaml = require('js-yaml');
const options = {
parser: { parse: yaml.safeLoad },
includeTag: '!Include'
};
const ibt = new IBT(options);
ibt.read('/etc/superapp/config.yml', '/usr/lib/superapp/config.yml')
.then(config => {
console.log(config);
});
~include~ string recognize globs. All globs interpreted like array. So value !include tests/*.json
and file tests/first.json
with content { "first": "test" }
will be recognized as
{
"tests": [{ "first": "test" }]
}
Included files are sorted alphabetically.
API
new IBT(options);
Options
parser
(Object, default:JSON
): Any object that has.parse
method. It must return parsed Object. For example, to use YAML parser options must look like{ parser: { parse: require('js-yaml').safeLoad }}
includeTag
(String, default:!include
): Tag for include. Filepath followed by tag, ex.!include ext/file.json
Methods
ibt.read(filepath, ...filepath)
read() is a primary method to read file includes. If method call with multiple
filepaths, it will be merged after full files reading and composing like Object.assign(parsedFile0, parsedFile1,
...)
.
Method return promise, with object as argument.