js0n-templates

A simple node modules that provides the ability to take your normal JSON, YAML, or file and extend them through the use of templates. This module supports both browser and node usage. However js0n-templates is more useful for the node user at is lets you parse files, and extend from the process object if running in node.

Intro

At its simplest js0n-templates can grab data from other areas of the JSON object. It uses JSON path from the root level node to resolve the templates. In the below example there are two templates {{fizz}} and {{buzz}}. A template is indicated by an opening character sequences and closing character sequences. In this case it defaults to "{{" and "}}". But js0n-templates supports the option to create your own.

var Compiler = require("js0n-templates");
var json = {
  fizzBuzz: "{{fizz}}{{buzz}}",
  fizz: "Fizz",
  buzz: "Buzz",
};

Compiler.compile(json);

// result === {
//     fizzBuzz: 'FizzBuzz',
//     fizz: 'Fizz',
//     buzz: 'Buzz'
// }

Secondary Sources

js0n-templates supports multiple sources to extend your JSON object from. First the template will try to resolve from its own self then move on to the secondary sources in attempt to resolve the template. Secondary can be an array or a single JSON object, path to file (resolve to json or yaml), or yaml string.

var Compiler = require("js0n-templates");
var json = {
  fizzBuzz: "{{fizz}}{{buzz}}",
};

var sources = [{ fizz: "Fizz" }, { buzz: "Buzz" }];

Compiler.compile(json, { sources });

// result === {
//     fizzBuzz: 'FizzBuzz',
// }

Custom Template

By default js0n-templates defaults to its own internal template start:"{{" end:"}}" but this can be changed to anything the user wants. The start and end template are provided individually as arguments.

var Compiler = require("js0n-templates");
var json = {
  fizzBuzz: "${fizz}${buzz}",
  fizz: "Fizz",
  buzz: "Buzz",
};

Compiler.compile(json, {
  start: "${",
  end: "}",
});

// result === {
//     fizzBuzz: 'FizzBuzz',
//     fizz: 'Fizz',
//     buzz: 'Buzz'
// }

defaults

js0n-templates will recursively resolve templates until no more template can be resolved. At which time defaults will be used to give the template a value. Templates can be used as defaults and can be continuously nested depending on the use case. A default is indicated by the value which takes place after a colon inside the template start and end characters.

var Compiler = require("js0n-templates");
var json = {
  fizzBuzz: "${fizz: Fizz}${buzz: ${Buzz: Buzz }}",
};

const compiler = new Compiler(json, {
  start: "${",
  end: "}",
});

compiler.compile()

// result === {
//     fizzBuzz: 'FizzBuzz',
// }

extend

There may be a need to merge multiple results together into a single object. Doing this with plain templates cannot be done in json and yaml structs. Using the extend option we can extend multiple objects and deeply merge them together. When the extend option is set to true any node named **extend will have its value deeply merged into the target object. As long as the two are objects themselves. The **extend node will be deleted after the merge. If __extend is not a plain object it will not be merged to the target object and will be deleted from the final result.

var Compiler = require("js0n-templates");
var sources = { source: { fizzBuzz: "{{fizz}}{{buzz}}" } };
var target = {
  __extend: "{{source}}",
  fizz: "Fizz",
  buzz: "Buzz",
};

var compiler = new Compiler(target, { extend: true })

// can pass source at runtime to the compile method
// instead of passing them when create the Compiler

compiler.compile(sources)

// result === {
//     fizzBuzz: 'FizzBuzz',
//     fizz: 'Fizz',
//     buzz: 'Buzz'
// }

this

When starting a template path with the prefix this the path that will be used not start at the root but where ever the template exist in the object itself. This only works in the source object and not in sources and you cant reference yourself by just using this in the template as that would create a circular reference.

compileIncludeUnresolvedTemplates

The method/static method compileIncludeUnresolvedTemplates on the Compiler class returns an array where index 0 is the result and index 1 is an object of unresolved templates key = path, value = the template itself.

var Compiler = require("js0n-templates");
var sources = { source: { fizzBuzz: "{{fizz}}{{buzz}}" } };
var target = { hello: "{{world}}" };

var compiler = new Compiler(target, { extend: true })

// can pass source at runtime to the compile method
// instead of passing them when create the Compiler

var [result, unresolved] = compiler.compileIncludeUnresolvedTemplates(sources)

// result === {
//     hello: '{{world}}'
// }

// unresolved === {
//     "['hello']": '{{world}}'
// }

add

Add works very similar to extend but does not override values that exist (non undefined) when they are present in the source/target.

Options

key	description
clone	deeply clones the object which is passed in as the main source. By default will edit in place. Does not support circular references
sources	array of data source to pull data from to populate templates
start	the start character sequence of a template
end	the end character sequence of a template
safe	if true will ignore circular references if false will throw an error of the template and path location of the circular reference
extend	will search for __extend and __add nodes in json and yaml and deeply merge the extension will only extend plain objects
useEnv	will pull data from the env which prefixes with vcap or process
strict	will throw error if all templates are not resolved
ignore	a list of templates to ignore and not resolve
templateHandler	callback is executed for every template which is found. The value returned from the callback is injected into the source.

templateHandler

The callback is executed for every template which is found. The value returned from the callback is injected into the source.

value, match, str, main, secondaries

params	description
value	the value found based on the template if no value found defaults to template
match	the matching template string includes the start and end template characters
str	the full string the template was found
source	the main source
sources	the secondaries sources