TransformURL

Build URLs by transforming a template with params.

Installation

yarn add transform-url

or

npm install --save transform-url

Usage

Query params

The first argument to transformUrl is a URL template, with the second being a params object of key/value pairs.

const transformUrl = require('transform-url');
const params = {
  userId: 'user-1234',
  orderId: 'order-6789'
};
 
const url = transformUrl('https://example.com', params);
// https://example.com?orderId=order-6789&userId=user-1234

Path params

If you want some params to be applied as path params, add placeholders to the URL template.

const url = transformUrl('https://example.com/api/users/:userId/orders/:orderId', params);
// https://example.com/api/users/user-1234/orders/order-6789

Mixed params

Any remaining params not specified in the URL template, will be applied as query params.

const url = transformUrl('https://example.com/api/users/:userId', params);
// https://example.com/api/users/user-1234?orderId=order-6789

Other params

Besides path and query params, placeholders can be added to any other part of the URL template.

const moreParams = {
  ...params,
  scheme: 'https',
  domain: 'example.com',
  hash: 'somePlace'
};
 
const url = transformUrl('{scheme}://{domain}/api/users/:userId#{hash}', moreParams);
// https://example.com/api/users/user-1234?orderId=order-6789#somePlace

Matchers

URL template placeholders can use either :colon or {curlyBraces} matchers. Additionally, it is possible to provide a custom matcher via options.

const options = {
  matcher: /\$(\w+)/g   // match `$paramName`
};
 
const url = transformUrl('$scheme://$domain/api/users/$userId#$hash', moreParams, options);
// https://example.com/api/users/user-1234?orderId=order-6789#somePlace

For additional options, see the API Reference below.

API Reference

transformUrl(urlTemplate, params, [options]) ⇒ String

Transform URL templates with provided params. Params that are not placeholders in the url template will be append as query params. Urls with a port number will be respected, for example http://example.com:8080

Kind: global function
Returns: String - transformed url

Param	Type	Description
urlTemplate	String	URL template to be transformed with params. URL template placeholders can use either :colon or {curlyBraces} matchers.
params	Object	Key/value pairs to be applied as path and/or query params. Required to include params for all placeholders.
[options]	Object	Optional configuration to output results.
[options.matcher]	RegExp	Specify regular expression for custom placeholders in URL templates.