bramstein / url-template

A JavaScript URI template implementation (RFC 6570 compliant)

A JavaScript URI template implementation

This is a simple URI template implementation following the RFC 6570 URI Template specification. The implementation supports all levels defined in the specification and is extensively tested.

Installation

For use with Node.js or build tools you can install it through npm:

$ npm install url-template

If you want to use it directly in a browser use a CDN like Skypack.

Example

import { parseTemplate } from 'url-template';

const emailUrlTemplate = parseTemplate('/{email}/{folder}/{id}');
const emailUrl = emailUrlTemplate.expand({
  email: 'user@domain',
  folder: 'test',
  id: 42
});

console.log(emailUrl);
// Returns '/user@domain/test/42'

A note on error handling and reporting

The RFC states that errors in the templates could optionally be handled and reported to the user. This implementation takes a slightly different approach in that it tries to do a best effort template expansion and leaves erroneous expressions in the returned URI instead of throwing errors. So for example, the incorrect expression {unclosed will return {unclosed as output. The leaves incorrect URLs to be handled by your URL library of choice.

Supported Node.js versions

The same versions that are actively supported by Node.js are also supported by url-template, older versions of Node.js might be compatible as well, but are not actively tested against.

url-template's Issues

v2.0.4 does not include LICENSE

Please release a version that includes your LICENSE file so that I can parse and included for the credits section of my app.

Browser compatibility

It should be trivial to release a browser version. Do so.

Switch for already encoded data

Is there a way for the template to not call encodeURIComponent, for if the data is already in the proper encoding when passed to '''expand''' ?

Transpile to CommonJS

I'm just wondering, is there a reason you're not transpiling a CommonJS version of the package and offering both CJS and ESM? It's making it very difficult, nay, impossible to create downstream "dual packages". 😢

Issues running this library in IE8

Have some issue with use of this library on IE8 because of following methods.
indexOf
map
forEach

Release 3.0

@bramstein I've tagged a commit on main for release, could you do an npm publish to push the new version to the NPM registry?

Should have an option to force an error for missing required template variables

Currently if there is a URL template that contains a required template variable:

.../?required={required}{&page,page_size}

the expand function will not throw an error if the context does not include this required value.

I would like an option to set a 'strict' mode upon instantiation:

new UrlTemplate(this.href, true); // Second argument sets the mode to strict

I believe this can be done in a backwards compatible way.

Missing arrays and objects in type definition

Expanding objects and array variables is supported.

But the type definition of expand does not reflect this.

It should probably be more like:

type VariableValue = string | number | boolean | null | VariablesMap;
type VariablesMap = Record<string, VariableValue>;

export interface Template {
  expand(context: VariablesMap): string;
}

Is this package dead?

@bramstein it looks like there are several issues and PRs open since quite some time. Do you need help maintaining this package or are you willing to perhaps add me as a maintainer? I'm working on a project that uses this library and I would like to help modernize this package so we can keep using it.

Let met know.

Should the expand function allow for undefined?

I'm using this module on a variable that will be a string but sometimes due to bad data, the string could be undefined. The module currently throws the following error when trying to expand a variable that was parsed with undefined Cannot read property 'replace' of undefined.

Instead of doing urlTemplate.parse(item.url || '') every time the module is used, it would be good if there was a default value of an empty string so no errors are thrown.

Here's the error reproduced:
https://runkit.com/59106f7a0c1a3d00124401b6/591077f93ae0c30012649458

Importing package inside a Jest test is problematic (ESM export not CJS)

Currently the main export is using:

export function parseTemplate(template) {

which is tricky when using this library inside a Jest test suite. Jest do only handle CommonJS modules fine right now and this construction lead to a parse error. It might be possible to work-around the issue by having a quite complex extension in the configuration to compile this node_module, but easier would be without.

Error message from Jest:

Test suite failed to run

    Jest encountered an unexpected token

    Jest failed to parse a file. This happens e.g. when your code or its dependencies use non-standard JavaScript syntax, or when Jest is not configured to support such syntax.

    Out of the box Jest supports Babel, which will be used to transform your files into valid JS based on your Babel configuration.

    By default "node_modules" folder is ignored by transformers.

...

Details:

    MY_PROJECT/node_modules/url-template/lib/url-template.js:97
    export function parseTemplate(template) {
    ^^^^^^

When changing the line to:

exports.parseTemplate = function parseTemplate(template) {

everything works fine.

Expand nested objects

Is it possible to do something like this?

const params = {
    user: {
        id: 123
    }
};

template.parse("/users/{user.id}").expand(params); // => "/users/123"

no license

could you please give it any license ?

A code is implicitly copyrighted the moment it is written, and, by default, you have no legal right to redistribute it, or produce derived works from it (of course, the author might not mind, but that's another matter entirely). In other words, lack of license is roughly the same as "look but don't touch" license."

Incorrect Types for expand.

Hi! 👋

Firstly, thanks for your work on this project! 🙂

Today I used patch-package to patch [email protected] for the project I'm working on.

Type was incorrect for Template.expand as it did not allow objects that contain arrays. Resolved by changing the type as below.

Here is the diff that solved my problem:

diff --git a/node_modules/url-template/lib/url-template.d.ts b/node_modules/url-template/lib/url-template.d.ts
index feae94a..8a9b227 100644
--- a/node_modules/url-template/lib/url-template.d.ts
+++ b/node_modules/url-template/lib/url-template.d.ts
@@ -1,7 +1,7 @@
 export type PrimitiveValue = string | number | boolean | null;
 
 export interface Template {
-  expand(context: Record<string, PrimitiveValue | PrimitiveValue[] | Record<string, PrimitiveValue>>): string;
+  expand(context: Record<string, PrimitiveValue | PrimitiveValue[] | Record<string, PrimitiveValue | PrimitiveValue[]>>): string;
 }
 
 export function parseTemplate(template: string): Template;

This issue body was partially generated by patch-package.

Change API

Change API so that:

var template = require('url-template');

var myUrl = template.parse('/{some}/{url}');

myUrl.expand(...);

works, instead of having to instantiate the UrlTemplate class.

TypeScript usage

Unclear how to import this module with typescript.

Dependencies added:

yarn add url-template
yarn add @types/url-template --dev

tried:

import urltemplate from "url-template";
import { urltemplate } from "url-template";
import { TemplateParser } from "url-template";
import { Template } from "url-template";

all say no such export.

"that.encodeReserved is not a function" when parse() is called

TypeError: that.encodeReserved is not a function
at /opt/PROJECT/node_modules/url-template/lib/url-template.js:171:25
at String.replace (native)

summary of code in main file of express app

t = urlTempl.parse(href); // works fine , called in main file

// called inside a route;
url = t.expand( { email: req.params.email } ); // above error

I try to replicate this issue in my tests .. but I must be missing something obvious
because url-temple always manage to work there ...

3.0.0 migration guide suggests cjs syntax is usable but we get errors when we use require. Please clarify if CJS is supported

Hi,

The 3.0.0 migration guide suggests I can use the following syntax to use version 3.0.0:

const { parseTemplate } = require('url-template');
const emailUrlTemplate = parseTemplate('/{email}/{folder}/{id}');

But when I do so in my project I get the following error message:

Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: /root/*********/browzine_cms/node_modules/url-template/lib/url-template.js
require() of ES modules is not supported.
require() of /root/*********/browzine_cms/node_modules/url-template/lib/url-template.js from /root/*********/browzine_cms/lib/models/user_model.js is an ES module file as it is a .js file whose nearest parent package.json contains "type": "module" which defines all .js files in that package scope as ES modules.
Instead rename url-template.js to end in .cjs, change the requiring code to use import(), or remove "type": "module" from /root/*********/browzine_cms/node_modules/url-template/package.json.

Can you advise if CJS style imports are actually still intended to be supported? Do I need to do something on my end or is this an issue in url-template that the syntax in the migration guide isn't working?

option to leave unknown params

Would it be acceptable to add an option to the expand function which would allow parameters to be expanded only if they are known/set? For example

var template = urlTemplate.parse('/cars/{model}/engine/{engineId}');
console.log(urlTemplate.expand({model: "ford-taurus"}, false);
// "/cars/ford-taurus/engine/{engineId}"

see my fork for the hack i'm currently using

My use case is for dynamic generation of hypermedia links for subresources where certain parameters are known, but other still need to be filled in

Parse should parse

At present parse returns an object with a an expand method in it. Parse does not do any ahead of time work, all of the work of parsing the template &c is part of the second expand method.

Ideally, parse would do some parsing work, such that the expand method could be shorter & do less work. If I am trying to make 1000 requests/second to a service, I don't want to have to keep re-parsing the template for each of these requests: I'd expect the parse method to break up & parse the template, such that the expand method could simply drop values into place & go.

Please add license to package.json

Please could you add the BSD license to package.json? This will ensure that any automated tools that check the license on NPM will be able to determine it's BSD-based. Thank you.