URI Templates (RFC 6570)

URI Templates (RFC6570) library including de-substitution.

It also supports URI maps using pairs of templates.

Templates and maps methods can also be exported as code (function expression). The code is smaller than the module (a few hundred bytes instead of a few thousand) so could be included in autogenerated files instead of depending on the module.

It is tested against the official test suite, including the extended tests.

The "de-substitution" extracts parameter values from URIs. It is also tested against the official test suite (including extended tests).

UriTemplate

This module loads as a CommonJS/Node, an AMD module or a browser global (UriTemplate);

var UriTemplate = require('uri-templates-codegen');

// Use of "new" is optional
var template1 = UriTemplate("/date/{colour}/{shape}/");
var template2 = new UriTemplate("/prefix/{?params*}");

Options

You can supply an options object as a second argument: UriTemplate(str, {...}). Available options are:

• .object: the input to .fill() will always be an object, not a function.
• .fixedTypes: guarantees the types of some expressions:
  • {?query*}, {&query*} and {;query*} are always objects (even without '=' present)
  • {/list*} and {.list*} are always arrays (even when empty)

Both of these options reduce code size.

.fill()

// "/date/green/round/"
var uri1 = template1.fill({
	colour: "green",
	shape: "round"
});
// "/prefix/?a=A&b=B&c=C"
var uri2 = template2.fillFromObject({
	params: {a: "A", b: "B", c: "C"}
});
// "/categories/example_colour/example_shape/"
var uri1b = template1.fill(function (varName) {
	return "example_" + varName;
});

A function expression for this method is available in .fillCode.

.test()

var uri2b = "/prefix/?beep=boop&bleep=bloop";
var isMatch = template2.fromUri(uri2b);

A function expression for this method is available in .testCode.

.fromUri()

var uri2b = "/prefix/?beep=boop&bleep=bloop";
var guess = template2.fromUri(uri2b);
/*
	{
		params: {
			beep: "boop",
			bleep: "bloop"
		}
	}
*/

While templates can be ambiguous (e.g. "{var1}{var2}"), it will still produce something that reconstructs into the original URI.

It can handle all the cases in the official test suite, including the extended tests:

var template = uriTemplate("{/id*}{?fields,token}");

var values = template.fromUri("/person/albums?fields=id,name,picture&token=12345");
/*
{
	id: ["person", 'albums"],
	fields: ["id", "name", "picture"],
	token: "12345"
}
*/

A function expression for this method is available in .fillUriCode.

UriTemplate.Map

You can define a URI map by supplying pairs of templates in an object. The "forward" direction uses the key template extracts parameters and (if it matches) fills the value template with those parameters.

The code generated by a map is smaller than the codes for the individual templates, because of shared code.

var UriTemplateMap = require('uri-templates-codegen').Map;

// A simple object will product a map
var map = UriTemplateMap({
	"/foo/{value}": "/bar/{value}",
	"/users/{user}/{postId}": "{?user,postId}"
});

// If more than one might match, use an array to specify order
var map = UriTemplateMap([
	{"/foo/{value}": "/bar/{value}"},
	{"/{+url}": "/prefix/{+url}"}
]);

.forward()

var preUrl = '/foo/someValue';
var postUrl = map.forward(preUrl);
// postUrl: "/bar/someValue"

A function expression for this method is available in .forwardCode.

.reverse()

var postUrl = '/bar/someValue';
var preUrl = map.reverse(preUrl);
// postUrl: "/fpp/someValue"

A function expression for this method is available in .reverseCode.

.mapCode

Returns an expression (immediately-executed function) that returns an object with .forward() and .reverse() methods.

Because of shared code, this is shorter than joining .forwardCode and .reverseCode together.

License

This project is released as public-domain. Anybody can modify or re-license it for any purpose, without restriction.