0.1.6 • Public • Published

Integreat URI Template

Template format loosely based on the RFC 6570 standard, with some omissions and some extra features needed for Integreat. A main feature is the compilation of the string-based template format to a more runtime friendly format.

Build Status Coverage Status Dependency Status

Getting started


Requires node v7, but has no other production dependencies.


Install from npm:

npm install great-uri-template

Example of use:

const greatUri = require('great-uri-template')

const template = '{type}/{id}{?first,max}'
const params = {id: 'ent1', type: 'entry', first: 0, max: 20}

const compiled = greatUri.compile(template)
const uri = greatUri.generate(compiled, params)


Running the tests

The tests can be run with npm test.

The template format

Parameter replacement

The simplest template features parameter replacements. Parameters are indicated in the template by putting parameter names in curly brackets: {id}.


Several parameters may be included within the brackets, seperated by commas. The values of these parameters will be expanded in the order they are specified, also seperated by commas. E.g.:{first,second,third}.

Parameters are required by default, but may be made optional by suffixing them with a question mark. Here, the id parameter is optional:{type}/{id?}. Optional params without a value will simply be excluded from the resulting uri. With the type parameter set to entry and an undefined id parameter, this template would expand to the uri

To include curly brackets in the url, without replacement, simply escape them: ?brackets=\\{\\}. (Remember double escape characters to escape the escape character in JavaScript.)

Query parameters

Including several parameters in the query string is such a common case, that it has its own modifier. Prefixing a parameter with a question mark creates a query component, where several parameters may be included, separated by a comma. A query component will be expanded to a key-value list, prefixed by a question mark, and delimited by ampersands.

The template{?first,max}, given the param object {first: 0, max: 20}, will generate the uri

Here, the parameter name is used as key, but a different key name may be specified like so:{?page=first}, which will generate the uri

When the query string question mark is already specified in a template, the query continuation component should be used, to avoid a second question mark. The template{&first,max} will expand to the uri

Other modifiers

RFC 6570 specifies several modifiers like the query component, where a list of parameters will be expanded to a list with relevant prefix and delimiters.

The following is supported with Integreat URI Template (example with the var parameter as an array of three values):

  • Fragment Expansion: {#var} -> #value1,value2,value3
  • Label Expansion: {.var} -> .value1.value2.value3
  • Path Segments Expansion: {/var} -> /value1/value2/value3
  • Path-Style Paramter Expansion: {;var} -> ;var=value1,value2,value3
  • Reserved Expansion: {+var} -> value1,value2,value3

For Label and Path Segment Expansion, the 'explode' flag is on by default.

When expanding parameters, all uri reserved characters are encoded, except for Fragment and Reserved expansion. With a parameter path set to sections/news, the template{path} will result in the uri So to expand path as an actual path, use the template{+path}, which will expand to See Variable Expansion in RFC 6570 for more on encoding.

Filter functions

Functions may be added to a parameter after a pipe character, to filter or modify the parameter value before it is expanded in the uri. This is an extension to RFC 6570.

E.g., with the section parameter set to news, the template segment {section|append(_archive)} will expand to news_archive, as the filter function append appends the string within the parentheses to the parameter value. If this was an optional parameter and the value was empty, nothing would be appended.

Several functions may be chained, where the result of the first is given as the value for the next, etc.

For filter functions without arguments, parentheses are optional.


Append the given string to the value. Will not touch null values or empty strings.


const params = {section: 'news'}
const template = '{section|append(_archive)}'


Prepend the given string to the value. Will not touch null values or empty strings.


const params = {section: 'news'}
const template = '{section|prepend(local_)}'


Formats a date according to the given date format string.

Uses date-and-time under the hood, so refer to their documentation.

In addition, two custom formats are available: ms-epoc and s-epoc. They format the date as number of microseconds or seconds since 1970-01-01. For seconds, microsencods are rounded off to nearest second.


const params = {updatedAfter: new Date('2020-03-19T14:08:44Z')}
const template = '{?updatedAfter|date(DD/MM/YYYY HH:mm:ss)}'


Transform the given value to lower case.


const params = {section: 'News'}
const template = '{section|lower}'


Transform the given value to upper case.


const params = {section: 'News'}
const template = '{?section|upper}'


Cut the value to a string of the given length. If length is higher than the number of characters in value, value is left untouched.


const params = {section: 'entertainment'}
const template = '{section|max(3)}'

wrap(outerLeft, [innerLeft, innerRight,] outerRight)

Wrap the value in the given strings.

The value is wrapped in outerLeft and outerRight. If the value is an array, it is joined with commas, before it is wrapped.

If innerLeft and innerRight is specified, each element in array will be wrapped in these, before the entire list is wrapped in outerLeft and outerRight. A non-array value is wrapped in all four the same way an array with one element would.


const params = {section: 'news', ids=['ent1', 'ent2', ent5]}
const template = '{section|wrap(_, _)}{?ids|wrap([, ", ", ])}'
//-->["ent1", "ent2", "ent5"]

map(from=to[, from=to[, ...]])

Will map the given value to a replacement according to the from=to pairs given as arguments to the map function. If no match is found, the value is not replaced.

const params = {type: 'entry'}
const template = '{type|map(article=articles, entry=entries)}'

Max length

RFC 6570 specifies a 'prefix modifier', that limits the length of the value, by suffixing a parameter with a colon and the max number of characters. This is implemented in Integreat URI Template through the max filter function, but the RFC 6570 syntax is available as a handy shortcut.

Example: With the section parameter set to entertainment, the template segment {section:3} will expand to ent. This is equivalent to {section|max(3)}.


Please read CONTRIBUTING for details on our code of conduct, and the process for submitting pull requests.


This project is licensed under the ISC License - see the LICENSE file for details.




Package Sidebar


npm i great-uri-template

Weekly Downloads






Unpacked Size

26.2 kB

Total Files


Last publish


  • kjellmorten