{"id":13339953,"url":"https://github.com/integreat-io/great-uri-template","last_synced_at":"2025-10-28T18:56:42.845Z","repository":{"id":57253882,"uuid":"104323659","full_name":"integreat-io/great-uri-template","owner":"integreat-io","description":"URI template format for Integreat, loosely based on RFC 6570","archived":false,"fork":false,"pushed_at":"2020-08-04T14:02:11.000Z","size":328,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-24T02:35:45.609Z","etag":null,"topics":["filter-functions","integreat","rfc-6570","uri-template"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/integreat-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-21T08:45:30.000Z","updated_at":"2023-09-08T17:30:14.000Z","dependencies_parsed_at":"2022-08-31T08:21:16.942Z","dependency_job_id":null,"html_url":"https://github.com/integreat-io/great-uri-template","commit_stats":null,"previous_names":["kjellmorten/great-uri-template"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/integreat-io%2Fgreat-uri-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/integreat-io%2Fgreat-uri-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/integreat-io%2Fgreat-uri-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/integreat-io%2Fgreat-uri-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/integreat-io","download_url":"https://codeload.github.com/integreat-io/great-uri-template/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243059730,"owners_count":20229625,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["filter-functions","integreat","rfc-6570","uri-template"],"created_at":"2024-07-29T19:21:23.073Z","updated_at":"2025-10-28T18:56:37.583Z","avatar_url":"https://github.com/integreat-io.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Integreat URI Template\n\nTemplate format loosely based on the\n[RFC 6570 standard](https://tools.ietf.org/html/rfc6570), with some\nomissions and some extra features needed for\n[Integreat](https://github.com/integreat-io/integreat). A main feature is the\ncompilation of the string-based template format to a more runtime friendly\nformat.\n\n[![Build Status](https://travis-ci.org/integreat-io/great-uri-template.svg?branch=master)](https://travis-ci.org/integreat-io/great-uri-template)\n[![Coverage Status](https://coveralls.io/repos/github/integreat-io/great-uri-template/badge.svg)](https://coveralls.io/github/integreat-io/great-uri-template)\n[![Dependency Status](https://dependencyci.com/github/integreat-io/great-uri-template/badge)](https://dependencyci.com/github/integreat-io/great-uri-template)\n\n## Getting started\n\n### Prerequisits\n\nRequires node v7, but has no other production dependencies.\n\n### Installing\n\nInstall from npm:\n\n```\nnpm install great-uri-template\n```\n\nExample of use:\n```\nconst greatUri = require('great-uri-template')\n\nconst template = 'http://example.com/{type}/{id}{?first,max}'\nconst params = {id: 'ent1', type: 'entry', first: 0, max: 20}\n\nconst compiled = greatUri.compile(template)\nconst uri = greatUri.generate(compiled, params)\n\nconsole.log(uri)\n//--\u003e http://example.com/entry/ent1?first=0\u0026max=20\n```\n\n### Running the tests\n\nThe tests can be run with `npm test`.\n\n## The template format\n\n### Parameter replacement\n\nThe simplest template features parameter replacements. Parameters are indicated\nin the template by putting parameter names in curly brackets: `{id}`.\n\nExample: `http://example.com/{type}/{id}`\n\nSeveral parameters may be included within the brackets, seperated by commas. The\nvalues of these parameters will be expanded in the order they are specified,\nalso seperated by commas. E.g.: `http://example.com/{first,second,third}`.\n\nParameters are required by default, but may be made optional by suffixing them\nwith a question mark. Here, the `id` parameter is optional:\n`http://example.com/{type}/{id?}`. Optional params without a value will simply\nbe excluded from the resulting uri. With the `type` parameter set to `entry` and\nan undefined `id` parameter, this template would expand to the uri\n`http://example.com/entry/`.\n\nTo include curly brackets in the url, without replacement, simply escape them:\n`?brackets=\\\\{\\\\}`. (Remember double escape characters to escape the\nescape character in JavaScript.)\n\n### Query parameters\n\nIncluding several parameters in the query string is such a common case, that it\nhas its own modifier. Prefixing a parameter with a question mark creates a\nquery component, where several parameters may be included, separated by a comma.\nA query component will be expanded to a key-value list, prefixed by a question\nmark, and delimited by ampersands.\n\nThe template `http://example.com{?first,max}`, given the param object\n`{first: 0, max: 20}`, will generate the uri\n`http://example.com?first=0\u0026max=20`.\n\nHere, the parameter name is used as key, but a different key name may be\nspecified like so: `http://example.com{?page=first}`, which will generate the\nuri `http://example.com?page=0`.\n\nWhen the query string question mark is already specified in a template, the\nquery continuation component should be used, to avoid a second question mark.\nThe template `http://example.com?section=archive{\u0026first,max}` will expand to the\nuri `http://example.com?section=archive\u0026first=0\u0026max=20`.\n\n### Other modifiers\n\nRFC 6570 specifies several modifiers like the query component, where a list of\nparameters will be expanded to a list with relevant prefix and delimiters.\n\nThe following is supported with Integreat URI Template (example with the `var`\nparameter as an array of three values):\n\n- Fragment Expansion: `{#var}` -\u003e `#value1,value2,value3`\n- Label Expansion: `{.var}` -\u003e `.value1.value2.value3`\n- Path Segments Expansion: `{/var}` -\u003e `/value1/value2/value3`\n- Path-Style Paramter Expansion: `{;var}` -\u003e `;var=value1,value2,value3`\n- Reserved Expansion: `{+var}` -\u003e `value1,value2,value3`\n\nFor Label and Path Segment Expansion, the 'explode' flag is on by default.\n\nWhen expanding parameters, all uri reserved characters are encoded, except for\nFragment and Reserved expansion. With a parameter `path` set to\n`sections/news`, the template `http://example.com/{path}` will result\nin the uri `http://example.com/sections%2Fnews`. So to expand `path` as\nan actual path, use the template `http://example.com/{+path}`, which will\nexpand to `http://example.com/sections/news`. See [Variable Expansion](https://tools.ietf.org/html/rfc6570#section-3.2.1) in RFC 6570 for\nmore on encoding.\n\n### Filter functions\n\nFunctions may be added to a parameter after a pipe character, to filter or\nmodify the parameter value before it is expanded in the uri. This is an\nextension to RFC 6570.\n\nE.g., with the `section` parameter set to `news`, the template segment\n`{section|append(_archive)}` will expand to `news_archive`, as the filter\nfunction `append` appends the string within the parentheses to the parameter\nvalue. If this was an optional parameter and the value was empty, nothing would\nbe appended.\n\nSeveral functions may be chained, where the result of the first is given as the\nvalue for the next, etc.\n\nFor filter functions without arguments, parentheses are optional.\n\n#### `append(string)`\nAppend the given string to the value. Will not touch null values or empty\nstrings.\n\nExample:\n```\nconst params = {section: 'news'}\nconst template = 'http://example.com/{section|append(_archive)}'\n...\n//--\u003e http://example.com/news_archive\n```\n\n#### `prepend(string)`\nPrepend the given string to the value. Will not touch null values or empty\nstrings.\n\nExample:\n```\nconst params = {section: 'news'}\nconst template = 'http://example.com/{section|prepend(local_)}'\n...\n//--\u003e http://example.com/local_news\n```\n\n#### `date(format)`\nFormats a date according to the given date format string.\n\nUses `date-and-time` under the hood, so refer to\n[their documentation](https://github.com/knowledgecode/date-and-time#formatdateobj-formatstring-utc).\n\nIn addition, two custom formats are available: `ms-epoc` and `s-epoc`. They\nformat the date as number of microseconds or seconds since 1970-01-01. For\nseconds, microsencods are rounded off to nearest second.\n\n”Example:\n```\nconst params = {updatedAfter: new Date('2020-03-19T14:08:44Z')}\nconst template = 'http://example.com/all{?updatedAfter|date(DD/MM/YYYY HH:mm:ss)}'\n...\n//--\u003e http://example.com/all?updatedAfter=20%2F03%2F2020%2019%3A43%3A11\n```\n\n#### `lower()`\nTransform the given value to lower case.\n\nExample:\n```\nconst params = {section: 'News'}\nconst template = 'http://example.com/{section|lower}'\n...\n//--\u003e http://example.com/news\n```\n\n#### `upper()`\nTransform the given value to upper case.\n\nExample:\n```\nconst params = {section: 'News'}\nconst template = 'http://example.com/{?section|upper}'\n...\n//--\u003e http://example.com/?section=NEWS\n```\n\n#### `max(length)`\nCut the value to a string of the given length. If length is higher than the\nnumber of characters in value, value is left untouched.\n\nExample:\n```\nconst params = {section: 'entertainment'}\nconst template = 'http://example.com/{section|max(3)}'\n...\n//--\u003e http://example.com/ent\n```\n\n#### `wrap(outerLeft, [innerLeft, innerRight,] outerRight)`\nWrap the value in the given strings.\n\nThe value is wrapped in `outerLeft` and `outerRight`. If the value is an array,\nit is joined with commas, before it is wrapped.\n\nIf `innerLeft` and `innerRight` is specified, each element in array will be\nwrapped in these, before the entire list is wrapped in `outerLeft` and\n`outerRight`. A non-array value is wrapped in all four the same way an array\nwith one element would.\n\nExample:\n```\nconst params = {section: 'news', ids=['ent1', 'ent2', ent5]}\nconst template = 'http://example.com/{section|wrap(_, _)}{?ids|wrap([, \", \", ])}'\n...\n//--\u003e http://example.com/_news_/?ids=[\"ent1\", \"ent2\", \"ent5\"]\n```\n\n#### `map(from=to[, from=to[, ...]])`\nWill map the given value to a replacement according to the `from=to` pairs\ngiven as arguments to the `map` function. If no match is found, the value is\nnot replaced.\n\n```\nconst params = {type: 'entry'}\nconst template = 'http://example.com/{type|map(article=articles, entry=entries)}'\n...\n//--\u003e http://example.com/entries\n```\n\n### Max length\n\nRFC 6570 specifies a 'prefix modifier', that limits the length of the value, by\nsuffixing a parameter with a colon and the max number of characters. This is\nimplemented in Integreat URI Template through the `max` filter function, but the\nRFC 6570 syntax is available as a handy shortcut.\n\nExample: With the `section` parameter set to `entertainment`, the template\nsegment `{section:3}` will expand to `ent`. This is equivalent to\n`{section|max(3)}`.\n\n## Contributing\n\nPlease read\n[CONTRIBUTING](https://github.com/integreat-io/great-uri-template/blob/master/CONTRIBUTING.md)\nfor details on our code of conduct, and the process for submitting pull\nrequests.\n\n## License\n\nThis project is licensed under the ISC License - see the\n[LICENSE](https://github.com/integreat-io/great-uri-template/blob/master/LICENSE)\nfile for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintegreat-io%2Fgreat-uri-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintegreat-io%2Fgreat-uri-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintegreat-io%2Fgreat-uri-template/lists"}