node package manager


Recursively resolve templates in an object, string or array.


Recursively resolve templates in an object, string or array.

v0.2.0 API changes

The top-level export now returns a function that takes an options object, which then returns the function to use.

var expand = require('expand');
var resolve = expand({regex: /:(\w+)/});
resolve(':a/:b', {a: 'foo', b: 'bar'});
//=> 'foo/bar' 

Install with npm

$ npm i expand --save
var expand = require('expand')();
expand({a: '<%= b %>', b: 'c'});
//=> {a: 'c', b: 'c'} 
expand({a: '<%= b.c.d %>', b: {c: {d: 'eee'}}});
//=> {a: 'eee', b: {c: {d: 'eee' }}} 


expand(valueToExpand, dataToUse, options);
  • value {String|Array|Object}: The value with templates to resolve.
  • data {Object}: Pass the data to use for resolving templates. If the first argument is an object, this is optional.
  • options {Object}: Pass the regex to use for matching templates.
  • returns {any}: Returns a string, object or array based on what was passed.


If an object is passed, only the first argument is strictly necessary.

expand({a: '<%= b %>', b: '<%= c %>', c: 'It worked!'});
//=> {a: 'It worked!', b: 'It worked!', c: 'It worked!'} 
expand({a: {c: '<%= d %>'}, d: {f: 'g'}});
//=>  {a: {c: {f: 'g'}}, d: {f: 'g'}}; 
expand(['<%= a %>'], {a: 'b'});
//=> ['b'] 
expand('<%= a %>', {a: 'b'});
//=> 'b' 
expand(['<%= a %>', '<%= b %>'], {a: 'b', b: 'c'});
//=> ['b', 'c'] 
var data = {a: {b: {c: 'd'}}};
expand({foo: '<%= a.b.c %>'}, data);
//=> {foo: 'd'} 
var data = {a: '<%= b %>', b: '<%= c %>', c: 'the end!'};
expand('<%= a %>', data);
//=> 'the end!' 
var str = '<%= a %>/<%= b %>';
expand(str, {a: 'foo', b: 'bar'});
//=> 'foo/bar' 
var data = {
  a: {
    c: '<%= d %>/<%= e %>'
  d: 'ddd',
  e: 'eee'
//=> 'ddd/eee' 
var data = {
  a: '<%= b %>/<%= c %>',
  b: 'xxx',
  c: '<%= y %>',
  y: 'zzz'
expand('<%= a %>', data);
//=> 'xxx/zzz' 
var ctx = {
  foo: 'bar',
  c: {
    d: {
      efunction (str) {
        return str.toUpperCase();
expand('abc <%= c.d.e(foo) %> xyz', ctx);
//=> 'abc BAR xyz' 

Options may be passed as the third argument. Currently options.regex is the only option.

var data = {a: 'bbb', c: 'ddd', e: 'fff'};
expand({foo: ':c/:e'}, data, {regex: /:([(\w ),]+)/});
//=> {foo: 'ddd/fff'} 
var data = {
  a: {c: ':d/:e/:upper(f)'},
  d: 'ddd',
  e: 'eee',
  f: 'foo',
  upperfunction (str) {
    return str.toUpperCase();
var result = expand(data, data, {regex: /:([(\w ),]+)/});
//=> 'ddd/eee/FOO' 
  • engine: Template engine based on Lo-Dash template, but adds features like the ability to register helpers… more | homepage
  • expand-object: Expand a string into a JavaScript object using a simple notation. Use the CLI or… more | homepage
  • get-value: Use property paths (a.b.c) to get a nested value from an object. | homepage
  • glob-object: Filter an object using glob patterns and dot notation. | homepage
  • set-value: Create nested values and any intermediaries using dot notation ('a.b.c') paths. | homepage

Here are some great libs by other authors. My needs for expand differed enough to create a new library, but these are definitely worth a look:

Install dev dependencies:

$ npm i -d && npm test

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Jon Schlinkert

Copyright © 2015 Jon Schlinkert Released under the MIT license.

This file was generated by verb on December 13, 2015.