@polka/url

Super fast, memoized req.url parser; not limited to Polka!

Parses the url from a IncomingMessage request. The returned object will always only contain the following keys: search, query, pathname, path, href, and _raw.

Note: This library does not process protocol, hostname, port, etc.
This is because the incoming req.url value only begins with the path information.

Parsed requests will be mutated with a _parsedUrl key, containing the returned output. This is used for future memoization, so as to avoid parsing the same url value multiple times.

Install

$ npm install --save @polka/url

Usage

const parse = require('@polka/url');

let req = { url: '/foo/bar?fizz=buzz' };
let foo = parse(req);
//=> { search: '?fizz=buzz',
//=>   query: 'fizz=buzz',
//=>   pathname: '/foo/bar',
//=>   path: '/foo/bar?fizz=buzz',
//=>   href: '/foo/bar?fizz=buzz',
//=>   _raw: '/foo/bar?fizz=buzz' }

// Attaches result for future memoization
assert.deepEqual(foo, req._parsedUrl); //=> true

// Example with `toDecode` param
req = { url: '/f%C3%B8%C3%B8%C3%9F%E2%88%82r?phone=%2b8675309' };
parse(req, true);
//=> { search: '?phone=+8675309',
//=>   query: { phone: '+8675309' },
//=>   pathname: '/føøß∂r',
//=>   path: '/føøß∂r?phone=+8675309',
//=>   href: '/føøß∂r?phone=+8675309',
//=>   _raw: '/føøß∂r?phone=+8675309' }

// Attaches awareness key
assert(req._decoded); //=> true

API

url(req, toDecode)

Returns: Object or undefined

Important: The req must have a url key, otherwise undefined will be returned.
If no input is provided at all, a TypeError will be thrown.

req

Type: IncomingMessage or Object

The incoming HTTP request (req) or a plain Object with a url key.

Note: In Node.js servers, the req.url begins with a pathname & does not include a hash.

toDecode

Type: Boolean
Default: false

If enabled, the url will be fully decoded (via decodeURIComponent) and the output keys will be slightly different:

path, pathname, href, _raw — will be the decoded strings
search — if there is a value, will be decoded string, else remain null
query — if there is a value, will be a decoded object, else remain null

Additionally, the req is mutated with req._decoded = true so as to prevent repetitive decoding.

Benchmarks

Check out the bench directory for in-depth benchmark results and comparisons.

Support

Any issues or questions can be sent to the Polka repository.
However, please specify that your inquiry is about @polka/url specifically.

readme.md