node-modify-url/README.md

# 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](http://www.wtfpl.net/txt/copying/) or [CC0](https://creativecommons.org/publicdomain/zero/1.0/), 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](mailto:admin@cryto.net) 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](http://cryto.net/~joepie91/donate.html).

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:

```js
"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](https://nodejs.org/api/url.html#url_legacy_url_api). 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`!