uri-templates

What is uri-templates?

The 'uri-templates' npm package allows you to parse and expand URI templates as defined by RFC 6570. It provides a simple and efficient way to handle URI templates, making it easier to work with dynamic URLs in your applications.

What are uri-templates's main functionalities?

Parsing URI Templates

This feature allows you to parse a URI template and extract variables from a given URI. In the example, the template '/{username}/repos' is used to parse the URI '/john/repos', extracting the variable 'username' with the value 'john'.

const UriTemplate = require('uri-templates');
const template = UriTemplate('/{username}/repos');
const parsed = template.fromUri('/john/repos');
console.log(parsed); // { username: 'john' }

Expanding URI Templates

This feature allows you to expand a URI template by providing values for the variables. In the example, the template '/{username}/repos' is expanded with the value 'john' for the variable 'username', resulting in the URI '/john/repos'.

const UriTemplate = require('uri-templates');
const template = UriTemplate('/{username}/repos');
const expanded = template.fill({ username: 'john' });
console.log(expanded); // '/john/repos'

Handling Complex Templates

This feature allows you to handle more complex URI templates with query parameters. In the example, the template '/search{?q,lang}' is expanded with the values 'nodejs' for 'q' and 'en' for 'lang', resulting in the URI '/search?q=nodejs&lang=en'.

const UriTemplate = require('uri-templates');
const template = UriTemplate('/search{?q,lang}');
const expanded = template.fill({ q: 'nodejs', lang: 'en' });
console.log(expanded); // '/search?q=nodejs&lang=en'

Other packages similar to uri-templates

uritemplate

The 'uritemplate' package is another implementation of URI templates based on RFC 6570. It provides similar functionality to 'uri-templates' for parsing and expanding URI templates. However, 'uritemplate' focuses on providing a more comprehensive and flexible API for handling URI templates.

url-template

The 'url-template' package is a lightweight library for parsing and expanding URI templates. It offers a straightforward API and is designed to be easy to use. Compared to 'uri-templates', 'url-template' may have a simpler interface but might lack some advanced features.

uri-template-lite

The 'uri-template-lite' package is a minimalistic implementation of URI templates. It provides basic functionality for parsing and expanding URI templates with a focus on performance and small footprint. It is suitable for use cases where a lightweight solution is preferred over a feature-rich one.

README

uri-templates

URI Templates (RFC6570) in JavaScript, including de-substitution.

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).

Creation

In Node:

var uriTemplates = require('uri-templates');
var template1 = uriTemplates("/date/{colour}/{shape}/");

In browser:

var template2 = new UriTemplate("/prefix/{?params*}");

Substitution using an object

// "/categories/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"}
});

Substitution using a callback

// "/categories/example_colour/example_shape/"
var uri1b = template1.fill(function (varName) {
	return "example_" + varName;
});

Guess variables from URI ("de-substitution")

var uri2b = "/prefix/?beep=boop&bleep=bloop";
var params = template2.fromUri(url2b);
/*
	{
		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"
}
*/

strict option

Sometimes, you might want a more exact match, instead of a best guess. For example, this could be useful when using URI Templates for routing.

The strict option performs more checks, to see whether the URI being matched is plausible:

var template = uriTemplate("/prefix/{value}/{suffix}");

// Matches, even though "foo/bar" contains a "/" which is not allowed
var looseMatch = template.fromUri('/prefix/foo/bar/suffix');
// Does not match
var strictMatch = template.fromUri('/prefix/foo/bar/suffix', {strict: true});

Test URI

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

This returns a boolean, and takes the same options as .fromUri().

License

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