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.
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 = 'http://example.com/{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)
console.log(uri)
//--> http://example.com/entry/ent1?first=0&max=20
The tests can be run with npm test.
The simplest template features parameter replacements. Parameters are indicated
in the template by putting parameter names in curly brackets: {id}.
Example: http://example.com/{type}/{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.: http://example.com/{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:
http://example.com/{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
http://example.com/entry/.
To include curly brackets in the url, without replacement, simply escape them:
?brackets=\\{\\}. (Remember double escape characters to escape the
escape character in JavaScript.)
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 http://example.com{?first,max}, given the param object
{first: 0, max: 20}, will generate the uri
http://example.com?first=0&max=20.
Here, the parameter name is used as key, but a different key name may be
specified like so: http://example.com{?page=first}, which will generate the
uri http://example.com?page=0.
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 http://example.com?section=archive{&first,max} will expand to the
uri http://example.com?section=archive&first=0&max=20.
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 http://example.com/{path} will result
in the uri http://example.com/sections%2Fnews. So to expand path as
an actual path, use the template http://example.com/{+path}, which will
expand to http://example.com/sections/news. See Variable Expansion in RFC 6570 for
more on encoding.
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.
Example:
const params = {section: 'news'}
const template = 'http://example.com/{section|append(_archive)}'
...
//--> http://example.com/news_archive
Prepend the given string to the value. Will not touch null values or empty strings.
Example:
const params = {section: 'news'}
const template = 'http://example.com/{section|prepend(local_)}'
...
//--> http://example.com/local_news
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.
”Example:
const params = {updatedAfter: new Date('2020-03-19T14:08:44Z')}
const template = 'http://example.com/all{?updatedAfter|date(DD/MM/YYYY HH:mm:ss)}'
...
//--> http://example.com/all?updatedAfter=20%2F03%2F2020%2019%3A43%3A11
Transform the given value to lower case.
Example:
const params = {section: 'News'}
const template = 'http://example.com/{section|lower}'
...
//--> http://example.com/news
Transform the given value to upper case.
Example:
const params = {section: 'News'}
const template = 'http://example.com/{?section|upper}'
...
//--> http://example.com/?section=NEWS
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.
Example:
const params = {section: 'entertainment'}
const template = 'http://example.com/{section|max(3)}'
...
//--> http://example.com/ent
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.
Example:
const params = {section: 'news', ids=['ent1', 'ent2', ent5]}
const template = 'http://example.com/{section|wrap(_, _)}{?ids|wrap([, ", ", ])}'
...
//--> http://example.com/_news_/?ids=["ent1", "ent2", "ent5"]
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 = 'http://example.com/{type|map(article=articles, entry=entries)}'
...
//--> http://example.com/entries
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.