g1.url

g1.url provides URL manipulation utilities.

g1.url.parse

g1.url.parse(url_string) parses a URL into an object mostly compatible with URL, and with a few additional features.

url attributes

var url = g1.url.parse(
  "https://user:pwd@example.com:80/~folder/subfolder/filename.html?a=1&a=2&b=3%2E&d#hash",
);

This parses the URL and returns an object with the following attributes matching window.location:

Attribute Value
href the original URL
protocol https
origin user:pwd@example.com:80
username user
password pwd
hostname example.com
port 80
pathname folder/subfolder/filename.html
search a=1&a=2&b=3%2E&d
hash hash

… and additional attributes:

Attribute Value
userinfo user:pwd
relative folder/subfolder/filename.html?a=1&a=2&b=3%2E&d#hash
directory folder/subfolder/
file filename.html
searchKey {'a:'2', b:'3.', d:''}
searchList {'a:['1', '2'], b:['3.'], d:['']}

It can also parse URL query strings.

var url = g1.url.parse("?a=1&a=2&b=3%2E&d#hash");
Attribute Value
search a=1&a=2&b=3%2E&d
hash hash
searchKey {a:'2', b:'3.', d:''}
searchList a:['1', '2'], b:['3.'], d:['']

These attributes are not mutable. To change the URL, use url.join or url.update.

url.toString

The url object has a .toString() method that converts the object back into a string.

url.join

var url = url.join(another_url);

updates the url with the attributes from another_url. For example:

url joined with gives
/path/p a/b/c /path/a/b/c
/path/p/q/ ../a/.. /path/p/
http://host1/p http://host2/q http://host2/q
https://a:b@host1/p //c:d@host2/q?x=1 https://c:d@host2/q?x=1
/path/p?b=1 ./?a=1#top /path/?a=1#top

.join() updates the query parameters and hash fragment as well. To prevent this, use:

url.join(another_url, { query: false, hash: false });

For example:

g1.url.parse("/").join("/?x=1#y=1", { hash: false }).toString() == "/?x=1";
g1.url.parse("/").join("/?x=1#y=1", { query: false }).toString() == "/#y=1";

url.update

var url = url.update(object);

updates the url query parameters with the attributes from object. For example:

url updated with gives
/ {a:1} /?a=1
/?a=1&b=2 {b:3, a:4, c:''} /?a=4&b=3&c=
/?a=1&b=2 {a:null} /?b=2
/?a=1&b=2 {a:[3,4], b:[4,5]} /?a=3&a=4&b=4&b=5

By default, it updates the query parameters. But:

For example:

url updated with in mode gives
/?a=1&a=2 {a:3, b:1} add /?a=1&a=2&a=3&b=1
/?a=1&a=2' {a:[3,4]} add /?a=1&a=2&a=3&a=4
/?a=1&a=2&b=1 {a:2, b:2} del /?a=1&b=1
/?a=1&a=2&b=1 {a:[1,4]} del /?a=2&b=1
/?a=1&a=2 {a:1, b:1} toggle /?a=2&b=1
/?a=1&a=2&b=1&b=2 {a:[2,3], b:[1,3]} toggle /?a=1&a=3&b=2&b=3

You can specify different modes for different query parameters.

g1.url
  .parse("/?a=1&b=2&c=3&d=4") // Update this URL
  .update(
    { a: 1, b: [2, 3], c: 6, d: 7 }, // With this object
    "a=del&b=toggle&c=add",
  ); // Delete ?a, Toggle ?b, Add ?c, Update ?d
// Returns /?b=3&c=3&c=6&d=7