Small Footprint URL Parser

Common errors

• url.query remains a string, not an object

  cause The `parser` option for query string parsing is `false` by default, meaning the query string is stored as a raw string.
  fix Pass `true` as the second argument to the `URLParse` constructor/function: `const url = new URLParse('http://example.com?a=1', true);` to enable default querystring parsing.

• TypeError: URLParse is not a constructor (or 'parse is not a function')

  cause Incorrect CommonJS or ES Module import syntax. The package primarily exports a callable constructor function as its default export.
  fix For CommonJS: `const URLParse = require('url-parse');`. For ES Modules, which might require bundler support for this CJS-first package: `import URLParse from 'url-parse';`. Avoid named imports like `import { URLParse } from 'url-parse';` for the main export.

• Relative URL does not resolve correctly without a base URL

  cause When parsing a relative URL string (e.g., '/path' or '../file.html'), `url-parse` requires a `baseURL` argument to resolve it into an absolute URL. Without it, the result might be unexpected or incomplete.
  fix Provide a base URL string or `URLParse` object as the second argument when parsing relative URLs: `const resolvedUrl = new URLParse('/images/logo.png', 'http://example.com/');`

Warnings

• deprecated The maintainers strongly recommend using the native WHATWG `URL` API (available in Node.js and modern browsers) for new development. They cite better security and accuracy, positioning `url-parse` primarily for legacy compatibility due to inconsistencies that can be weaponized in security attacks.
  Fix: For new projects, use `new URL()` or `URL.parse()` (if available) and `URLSearchParams` for query string manipulation. Review existing code for potential security implications if `url-parse` handles untrusted input.
• gotcha By default, the `parser` option for querystring parsing is `false`. To parse the query string into an object, you must explicitly pass `true` as the second argument to the `URLParse` constructor/function, or a custom parsing function. Otherwise, the `query` property will remain an unparsed string (e.g., '?key=value').
  Fix: When creating a `URLParse` instance, pass `true` as the second argument: `new URLParse('your-url', true)` to enable default query string parsing. Alternatively, use `urlParseInstance.set('query', { /* new object */ }, true);` to trigger re-parsing.
• breaking Version 1.0.0 fundamentally changed the parsing strategy from a RegExp-based solution to a pure string parsing approach. While intended to improve cross-environment compatibility and reduce Firefox-specific issues, this was a significant internal rewrite that could introduce subtle differences in how certain malformed or edge-case URLs are parsed compared to prior versions.
  Fix: Thoroughly test parsing behavior for critical URL patterns when migrating to or from version 1.0.0, especially if relying on specific outcomes for unusual or malformed URLs.
• breaking Version 0.1 moved from a DOM-based parsing solution (leveraging `<a>` elements) to a Regular Expression solution. This change specifically impacted environments without DOM access, such as Web Workers. While later superseded, it represents a significant shift in compatibility and parsing technique for that version.
  Fix: If migrating from pre-0.1 versions, ensure your environment supports the new parsing mechanism. For Web Worker compatibility, version 0.1 was an improvement, but later versions refined parsing further.

Install

• npm install url-parse npm
• yarn add url-parse yarn
• pnpm add url-parse pnpm

Imports

• URLParse (constructor/function)
  wrong:

  import { URLParse } from 'url-parse';
  const URLParse = require('url-parse').URLParse;

  correct:

  import URLParse from 'url-parse';
  // Or for CommonJS:
  const URLParse = require('url-parse');

  The primary export is a constructor function (e.g., `new URLParse()`) that can also be called directly as a parsing function (e.g., `URLParse('...')`). Given its age, it is primarily a CommonJS module, and ES Module `import` typically relies on bundlers.
• querystringify (module)
  wrong:

  import { querystringify } from 'url-parse';

  correct:

  import querystringify from 'url-parse/lib/querystringify';
  // Or for CommonJS:
  const querystringify = require('url-parse/lib/querystringify');

  The bundled `querystringify` module, used for parsing and stringifying query strings, is exposed via a sub-path import.

Quickstart

Demonstrates basic URL parsing, enabling query string parsing, resolving relative URLs with a base, and direct usage of the bundled `querystringify` module.

'use strict';

const URLParse = require('url-parse');

// Basic parsing with 'new' keyword (optional)
const urlObj1 = new URLParse('https://user:pass@github.com:8080/foo/bar?baz=qux#hash');
console.log('Protocol:', urlObj1.protocol); // 'https:'
console.log('Host:', urlObj1.host);     // 'github.com:8080'
console.log('Pathname:', urlObj1.pathname); // '/foo/bar'
console.log('Query (unparsed):', urlObj1.query); // '?baz=qux'

// Parsing as a function with querystring parsing enabled
const urlObj2 = URLParse('http://localhost:3000/path?key=value&arr[]=1&arr[]=2', true);
console.log('Protocol:', urlObj2.protocol); // 'http:'
console.log('Query (parsed):', urlObj2.query); // { key: 'value', arr: [ '1', '2' ] }

// Using a base URL for relative paths
const baseUrl = 'http://example.com/a/b/';
const relativeUrlObj = new URLParse('../c', baseUrl);
console.log('Resolved Path:', relativeUrlObj.pathname); // '/a/c'
console.log('Resolved URL:', relativeUrlObj.href); // 'http://example.com/a/c'

// Accessing querystringify directly
const querystringify = require('url-parse/lib/querystringify');
const qString = querystringify.stringify({ name: 'Alice', age: 30 });
console.log('Stringified Query:', qString); // 'name=Alice&age=30'