simple-url v1.1.8

simple-url

simple-url is a lib of utilities for url which can be used in both browser and node.js.

Installing

Use via npm:

npm install simple-url

var url = require('simple-url');

// Use es6 import
import url from 'simple-url';

Use in browser:

Scripts for browser is under build directory, use url.js for development (contains inline source maps) or use url.min.js for production. The reference in browser is window.simpleUrl.

The structure of a url

The following illustration comes from nodejs docs.

┌─────────────────────────────────────────────────────────────────────────────┐
│                                    href                                     │
├──────────┬┬───────────┬─────────────────┬───────────────────────────┬───────┤
│ protocol ││   auth    │      host       │           path            │ hash  │
│          ││           ├──────────┬──────┼──────────┬────────────────┤       │
│          ││           │ hostname │ port │ pathname │     search     │       │
│          ││           │          │      │          ├─┬──────────────┤       │
│          ││           │          │      │          │ │    query     │       │
"  http:   // user:pass @ host.com : 8080   /p/a/t/h  ?  query=string   #hash "
│          ││           │          │      │          │ │              │       │
└──────────┴┴───────────┴──────────┴──────┴──────────┴─┴──────────────┴───────┘
(all spaces in the "" line should be ignored -- they are purely for formatting)

Examples

Parse a url:

var simpleUrl = require('simple-url');

var parsedUrl = simpleUrl.parse('http://foo.com/pathname/?foo=bar', true);
console.log(parsedUrl);
/**
* The output is:
* {
*   protocol: 'http',
*   auth: '',
*   host: 'foo.com',
*   pathname: '/pathname/',
*   query: {foo: 'bar'},
*   hash: ''
* }
*/

Trim origin:

var simpleUrl = require('simple-url');

console.log(simpleUrl.trimOrigin('http://foo.com/pathname/?foo=bar'));
// Output: /pathname/?foo=bar

console.log(simpleUrl.trimOrigin(/pathname/?foo=bar));
// Output: /pathanem/?foo=bar

Create a url:

var simpleUrl = require('simple-url');

var url = simpleUrl.create({
    protocol: 'https',
    host: 'github.com',
    query: {colors: ['red', 'green', 'blue']}
  });
console.log(url);
/**
* The output is:
* https://github.com/?colors%5B0%5D=red&colors%5B1%5D=green&colors%5B2%5D=blue
*/

Create a path:

var path1 = simpleUrl.createPath(
    '/foo/bar',
    {colors: ['red', 'green', 'blue']}
  );
console.log(path);
/*
* The output is:
* /foo/bar?colors%5B0%5D=red&colors%5B1%5D=green&colors%5B2%5D=blue
*/

var path2 = simpleUrl.createPath({
    pathname: '/foo/bar',
    query: {colors: ['red', 'green', 'blue']}
  });
console.log(path1 === path2)
/**
* The output is:
* true
*/

methods

url.parse(url, parseQuery)

This method parses the given url and returns null(invalid url) or object like:

{
  protocol: 'http', // '' if mismatch
  auth: 'user:pass', // '' if mismatch
  host: 'host.com:8080', // '' if mismatch
  pathname: '/p/a/t/h', // '' if mismatch
  query: {foo: 'bar'}, // {} if mismatch
  hash: 'hash' // '' if mismatch
}

Note: url for url.parse is not necessary to be a complete url, it can be //host.com : 8080/path?query=string#hash, /path?query=string, etc.

url.create(options)

This method creates a url with the given options.

None of these options is required, it will produce a "http://localhost" if you call url.create() only.

url.createPath(pathname, query, hash) or url.createPath(options)

This method simply crates a path and it's params have the same defaults with url.create's. It leaves param hash there for convenience though it is not a part of path.

url.trimOrigin(url)

This method will trim origin of the given url, and it will not decode any uri component or query.

url.qs

This is exactly a reference to qs, which is the only dependency of simple-url. It is exposed just for convenience.

License

MIT