Initial commit

README.md

@@ -0,0 +1,66 @@
+# 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.
+
+- __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`!

example.js

@@ -0,0 +1,33 @@
+"use strict";
+
+const modifyUrl = require("./");
+
+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

index.js

@@ -0,0 +1,44 @@
+"use strict";
+
+const url = require("url");
+
+module.exports = function modifyUrl(baseUrl, newProps_, options = {}) {
+	if (baseUrl == null) {
+		throw new Error("Must specify a base URL");
+	} else if (newProps_ == null) {
+		throw new Error("Must specify new properties");
+	} else if (typeof baseUrl !== "string") {
+		throw new Error("Base URL must be a string");
+	} else if (typeof newProps_ !== "object" || Array.isArray(newProps_)) {
+		throw new Error("New properties must be an object");
+	} else if (options.mergeQuery === true && newProps_.search != null) {
+		throw new Error("You can only use `query`, not `search`, when the `mergeQuery` option is enabled");
+	} else {
+		let parsedBaseUrl = url.parse(baseUrl, true);
+		let newProps = Object.assign({}, newProps_);
+	
+		if (newProps.query != null) {
+			parsedBaseUrl.search = null;
+		}
+	
+		if (newProps.hostname != null || newProps.port != null) {
+			parsedBaseUrl.host = null;
+		}
+	
+		let newQuery;
+	
+		if (newProps.query != null) {
+			if (options.mergeQuery === true) {
+				newQuery = Object.assign(parsedBaseUrl.query, newProps.query)
+			} else {
+				newQuery = newProps.query;
+			}
+		} else {
+			newQuery = parsedBaseUrl.query;
+		}
+	
+		return url.format(Object.assign({}, parsedBaseUrl, newProps, {
+			query: newQuery
+		}));
+	}
+};

package.json

@@ -0,0 +1,8 @@
+{
+  "name": "modify-url",
+  "version": "1.0.0",
+  "main": "index.js",
+  "repository": "http://git.cryto.net/joepie91/node-modify-url.git",
+  "author": "Sven Slootweg <admin@cryto.net>",
+  "license": "WTFPL OR CC0-1.0"
+}