Repository files navigation

url-parse was created in 2014 when the WHATWG URL API was not available inNode.js and theURL interface was supported only in some browsers. Today thisis no longer true. TheURL interface is available in all supported Node.jsrelease lines and basically all browsers. Consider using it for better securityand accuracy.

Theurl-parse method exposes two different API interfaces. Theurl interface that you know from Node.jsand the newURLinterface that is available in the latest browsers.

In version0.1 we moved from a DOM based parsing solution, using the<a>element, to a full Regular Expression solution. The main reason for this wasto make the URL parser available in different JavaScript environments as youdon't always have access to the DOM. An example of such environment is theWorker interface.The RegExp based solution didn't work well as it required a lot of lookupscausing major problems in FireFox. In version1.0.0 we ditched the RegExpbased solution in favor of a pure string parsing solution which chops up theURL into smaller pieces. This module still has a really small footprint as ithas been designed to be used on the client side.

In addition to URL parsing we also expose the bundledquerystringify module.

This module is designed to be used using either browserify or Node.js it'sreleased in the public npm registry and can be installed using:

npm install url-parse

All examples assume that this library is bootstrapped using:

'use strict';varUrl=require('url-parse');

To parse an URL simply call theURL method with the URL that needs to betransformed into an object.

varurl=newUrl('https://github.com/foo/bar');

Thenew keyword is optional but it will save you an extra function invocation.The constructor takes the following arguments:

• url (String): A string representing an absolute or relative URL.
• baseURL (Object |String): An object or string representingthe base URL to use in caseurl is a relative URL. This argument isoptional and defaults tolocationin the browser.
• parser (Boolean |Function): This argument is optional and specifieshow to parse the query string. By default it isfalse so the query stringis not parsed. If you passtrue the query string is parsed using theembeddedquerystringify module. If you pass a function the query stringwill be parsed using this function.

As said above we also support the Node.js interface so you can also use thelibrary in this way:

'use strict';varparse=require('url-parse'),url=parse('https://github.com/foo/bar',true);

The returnedurl instance contains the following properties:

• protocol: The protocol scheme of the URL (e.g.http:).
• slashes: A boolean which indicates whether theprotocol is followed by twoforward slashes (//).
• auth: Authentication information portion (e.g.username:password).
• username: Username of basic authentication.
• password: Password of basic authentication.
• host: Host name with port number. The hostname might be invalid.
• hostname: Host name without port number. This might be an invalid hostname.
• 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.
• origin: The origin of the URL.

Note that whenurl-parse is used in a browser environment, it will default tousing the browser's current window location as the base URL when parsing allinputs. To parse an input independently of the browser's current URL (e.g. forfunctionality parity with the library in a Node environment), pass an emptylocation object as the second parameter:

varparse=require('url-parse');parse('hostname',{});

A simple helper function to change parts of the URL and propagating it throughall properties. When you set a newhost you want the same value to be appliedtoport if has a different port number,hostname so it has a correct nameagain andhref so you have a complete URL.

varparsed=parse('http://google.com/parse-things');parsed.set('hostname','yahoo.com');console.log(parsed.href);// http://yahoo.com/parse-things

It's aware of default ports so you cannot set a port 80 on an URL which hashttp as protocol.

The returnedurl object comes with a customtoString method which willgenerate a full URL again when called. The method accepts an extra functionwhich will stringify the query string for you. If you don't supply a function wewill use our default method.

varlocation=url.toString();// http://example.com/whatever/?qs=32

You would rarely need to use this method as the full URL is also available ashref property. If you are using theURL.set method to make changes, thiswill automatically update.

The testing of this module is done in 3 different ways:

1. We have unit tests that run under Node.js. You can run these tests with thenpm test command.
2. Code coverage can be run manually usingnpm run coverage.
3. For browser testing we use Sauce Labs andzuul. You can run browser testsusing thenpm run test-browser command.

MIT