modify-url

A simple utility library for modifying a URL by specifying the properties to change of it.

Note that this is different from resolving a relative URL; this library will let you modify the hostname without changing the path, for example, whereas that's not possible with url.resolve.

License, donations, and other boilerplate

Licensed under either the WTFPL or CC0, at your choice. In practice, that means it's more or less public domain, and you can do whatever you want with it. Giving credit is not required, but still very much appreciated! I'd love to hear from you if this module was useful to you.

Creating and maintaining open-source modules is a lot of work. A donation is also not required, but much appreciated! You can donate here.

By contributing to this module, you agree that your contributions will be licensed under the licenses mentioned above.

Examples

Scroll down for the detailed API reference.

Some examples of using this module:

"use strict";

const modifyUrl = require("modify-url");

let modified1 = modifyUrl("http://example.com/some/lengthy/path?with=a&query=string", {
	hostname: "example.net",
	query: {}
});

console.log(modified1); // http://example.net/some/lengthy/path

let modified2 = modifyUrl("http://example.com/?some=value", {
	protocol: "https",
	hostname: "subdomain.example.org",
	port: 8443,
	query: {
		other: "value"
	}
}, { mergeQuery: true });

console.log(modified2); // https://subdomain.example.org:8443/?some=value&other=value

let modified3 = modifyUrl("http://example.com/path", {
	host: "example.org:8080"
});

console.log(modified3); // http://example.org:8080/path

let modified4 = modifyUrl("http://example.com/path", {
	port: 8080
});

console.log(modified4); // http://example.com:8080/path

API

modifyUrl(baseUrl, newProperties[, options])

Generates a modified URL. Returns the modified URL as a string. Keep in mind that the query object is not merged by default; see the mergeQuery option below to change that.

This function does not change the baseUrl string or the newProperties object you pass in; it creates and returns a new URL string entirely.

• baseUrl: The URL that you want to modify, as a string.
• newProperties: The properties of the URL that you want to change, following the naming conventions of the legacy URL object. Like in that API, query takes precedence over search, and hostname/port take precedence over host. All keys are optional.
• options: (Optional.) An object of extra options.
  • mergeQuery: (Optional.) By default, the query object replaces the query string in the old URL entirely. By setting this to true, it's merged into the query string in the old URL instead. This only works with query, not with search!