From 275b1d9a8990b1e36eb9c843195376bb9c3e9b68 Mon Sep 17 00:00:00 2001 From: Sven Slootweg Date: Thu, 9 May 2019 21:36:30 +0200 Subject: [PATCH] Initial commit --- README.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++ example.js | 33 ++++++++++++++++++++++++++ index.js | 44 +++++++++++++++++++++++++++++++++++ package.json | 8 +++++++ 4 files changed, 151 insertions(+) create mode 100644 README.md create mode 100644 example.js create mode 100644 index.js create mode 100644 package.json diff --git a/README.md b/README.md new file mode 100644 index 0000000..a744877 --- /dev/null +++ b/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`! \ No newline at end of file diff --git a/example.js b/example.js new file mode 100644 index 0000000..fc4c18c --- /dev/null +++ b/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 diff --git a/index.js b/index.js new file mode 100644 index 0000000..34d4096 --- /dev/null +++ b/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 + })); + } +}; \ No newline at end of file diff --git a/package.json b/package.json new file mode 100644 index 0000000..dd9238d --- /dev/null +++ b/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 ", + "license": "WTFPL OR CC0-1.0" +}