What is url-parse?
The url-parse package is a robust tool for parsing URLs in Node.js and browser environments. It provides a convenient way to break down a URL into its components, such as protocol, host, path, query parameters, and hash. This package is useful for applications that need to manipulate or extract information from URLs.
What are url-parse's main functionalities?
Parsing URL
This feature allows you to parse a full URL into its constituent parts, including protocol, username, password, host, port, pathname, query, and hash. The second parameter set to true parses the query string into an object.
const parse = require('url-parse');
const url = parse('http://username:password@host.com:8080/p/a/t/h?query=string#hash', true);
console.log(url.protocol); // 'http:'
console.log(url.host); // 'host.com:8080'
Manipulating Query Strings
This feature demonstrates how to manipulate query strings. After parsing the URL with the query string parsing option enabled, you can easily add, modify, or delete query parameters and then serialize the URL back to a string.
const parse = require('url-parse');
const url = parse('http://example.com?foo=bar', true);
url.query.newParam = 'newValue';
console.log(url.toString()); // 'http://example.com/?foo=bar&newParam=newValue'
Relative URL Resolution
This feature shows how to resolve relative URLs against a base URL. By parsing both the base and relative URLs, you can combine their components to form a new, resolved URL.
const parse = require('url-parse');
const baseUrl = parse('http://example.com/directory/');
const relativeUrl = parse('another/directory', true);
const resolvedUrl = baseUrl.set('pathname', baseUrl.pathname + relativeUrl.pathname);
console.log(resolvedUrl.toString()); // 'http://example.com/directory/another/directory'
Other packages similar to url-parse
whatwg-url
This package implements the URL standard as specified by the WHATWG (Web Hypertext Application Technology Working Group). It offers more comprehensive support for the URL standard than url-parse, including features like URLSearchParams. However, it might be more complex to use for simple URL parsing and manipulation tasks.
url-parse
The url-parse
method exposes two different API interfaces. The
url
interface that you know from Node.js
and the new URL
interface that is available in the latest browsers.
Since 0.1
we've moved away from using the DOM's <a>
element for URL parsing
and moving to a full Regular Expression solution. The main reason for this
change is to make the URL parser available in different JavaScript environments
as you don't always have access to the DOM like Worker
environments. This
module still have a really small foot print as this module's main intention is
to be bundled with client-side code. The only problem however with a RegExp
based solution is that it required a lot of lookups causing major problems in
FireFox. So the last and the current solution was a pure string parsing
solution which chops up the URL in smaller pieces.
In addition to URL parsing we also expose the bundled querystringify
module.
Installation
This module is designed to be used using either browserify or node.js it's
released in the public npm registry and can be installed using:
npm install url-parse
Usage
All examples assume that this library is bootstrapped using:
'use strict';
var URL = require('url-parse');
To parse an URL simply call the URL
method with the URL that needs to be
transformed in to an object.
var url = new URL('https://github.com/foo/bar');
The new
keyword is optional but it will save you an extra function invocation.
In the example above we've demonstrated the URL interface, but as said in the
module description we also support the node.js interface. So you could also use
the library in this way:
'use strict';
var parse = require('url-parse')
, url = parse('https://github.com/foo/bar', true);
The returned url
instance contains the following properties:
protocol
: Requested protocol without slashes (e.g. http:
).username
: Username of basic authentication.password
: Password of basic authentication.auth
: Authentication information portion (e.g. username:password
).host
: Host name with port number.hostname
: Host name without port number.port
: Optional port number.pathname
: URL path.query
: Parsed object containing query string, unless parsing is set to false.hash
: The "fragment" portion of the URL including the pound-sign (#
).href
: The full URL.
URL.set(key, value)
A simple helper function to change parts of the URL and propagating it through
all properties. When you set a new host
you want the same value to be applied
to port
if has a different port number, hostname
so it has a correct name
again and href
so you have a complete URL.
var parsed = parse('http://google.com/parse-things');
parsed.set('hostname', 'yahoo.com');
console.log(parsed.href);
It's aware of default ports so you cannot set a port 80 on an URL which has
http
as protocol.
URL.toString()
The returned url
object comes with a custom toString
method which will
generate a full URL again when called. The method accepts an extra function
which will stringify the query string for you. If you don't supply a function we
will use our default method.
var location = url.toString();
You would rarely need to use this method as the full URL is also available as
href
property. If you are using the URL.set
method to make changes, this
will automatically update.
Testing
The testing of this module is done in 3 different ways:
- We have unit tests setup which run under Node.js using the normal
npm test
command. - Code coverage can be run manually using
npm run coverage
- For browser testing we use
testling
to startup a test server. We do assume
that you testling
installed globally, if not please run npm install -g testling
and after that testling -u
in the root of this repository. When
you visit the outputted URL all unit tests that were written from the Node
can now be ran inside browsers.
License
MIT