{"id":14210,"library":"url-toolkit","title":"URL Toolkit","description":"URL Toolkit is a lightweight, dependency-free JavaScript library designed to build absolute URLs from a base URL and a relative URL, specifically adhering to RFC 1808. The current stable version is `2.2.5`. The project maintains a steady release cadence, primarily focusing on bug fixes, performance improvements (like regex optimizations), and security updates (such as ReDoS vulnerability patches), with occasional documentation enhancements. Its key differentiator from the native `URL()` constructor in browsers and Node.js is its strict adherence to RFC 1808, which differs from the WHATWG URL Living Standard used by `URL()`. This difference notably affects how 'special URLs' (like `http:///example.com`) are normalized and parsed, making URL Toolkit suitable for environments or applications that require precise RFC 1808 compliance.","status":"active","version":"2.2.5","language":"javascript","source_language":"en","source_url":"https://github.com/tjenkinson/url-toolkit","tags":["javascript","url","relative","absolute","parser","typescript"],"install":[{"cmd":"npm install url-toolkit","lang":"bash","label":"npm"},{"cmd":"yarn add url-toolkit","lang":"bash","label":"yarn"},{"cmd":"pnpm add url-toolkit","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library exports a namespace object, not a default export. Use `* as` for consistent ESM usage.","wrong":"import URLToolkit from 'url-toolkit';","symbol":"URLToolkit","correct":"import * as URLToolkit from 'url-toolkit';"},{"note":"While CommonJS `require` works, named imports are preferred in modern ESM/TypeScript projects for tree-shaking and clarity.","wrong":"const { buildAbsoluteURL } = require('url-toolkit');","symbol":"buildAbsoluteURL","correct":"import { buildAbsoluteURL } from 'url-toolkit';"},{"note":"For CommonJS, directly accessing the property is valid, but named ESM imports are generally better practice.","wrong":"const parseURL = require('url-toolkit').parseURL;","symbol":"parseURL","correct":"import { parseURL } from 'url-toolkit';"}],"quickstart":{"code":"import { buildAbsoluteURL, parseURL } from 'url-toolkit';\n\nconst baseURL = 'https://example.com/path/to/resource.m3u8?query=param#fragment';\nconst relativeURL = '../new-resource.ts?other=param#anotherFragment';\n\n// Build an absolute URL\nconst absoluteUrl = buildAbsoluteURL(baseURL, relativeURL);\nconsole.log('Absolute URL:', absoluteUrl);\n// Expected: https://example.com/path/new-resource.ts?other=param#anotherFragment\n\n// Build an absolute URL with explicit path normalization\nconst absoluteUrlNormalized = buildAbsoluteURL(baseURL, '/root/other.ts', { alwaysNormalize: true });\nconsole.log('Absolute URL (normalized path):', absoluteUrlNormalized);\n// Expected: https://example.com/root/other.ts\n\n// Parse a URL into its components\nconst parsed = parseURL('http://user:pass@host.com:8080/path;params?query=string#hash');\nconsole.log('Parsed URL:', JSON.stringify(parsed, null, 2));\n/* Expected:\n{\n  \"scheme\": \"http:\",\n  \"netLoc\": \"//user:pass@host.com:8080\",\n  \"path\": \"/path\",\n  \"params\": \";params\",\n  \"query\": \"?query=string\",\n  \"fragment\": \"#hash\"\n}*/","lang":"typescript","description":"Demonstrates building absolute URLs with and without explicit path normalization, and parsing a URL into its RFC 1808 components."},"warnings":[{"fix":"Thoroughly test URL parsing and resolution if migrating from or using alongside `URL()`. Understand RFC 1808 specifications for expected behavior or use `URL()` if WHATWG standard is preferred.","message":"URL Toolkit adheres to RFC 1808, which differs from the WHATWG URL Living Standard implemented by the native `URL()` API. This means parsing and resolution logic, especially for 'special URLs' or certain edge cases, will produce different results. For example, `http:///example.com` will be parsed differently.","severity":"gotcha","affected_versions":"*"},{"fix":"Upgrade to version `2.2.4` or later to incorporate the patched regular expressions: `npm install url-toolkit@latest`.","message":"Versions of `url-toolkit` prior to `2.2.4` were vulnerable to Regular Expression Denial of Service (ReDoS) attacks due to inefficient regex patterns in URL parsing logic. Upgrading is crucial for security.","severity":"breaking","affected_versions":"<2.2.4"},{"fix":"Always use `./` prefix for relative URLs with colons if you intend for them to be resolved against the base URL (e.g., `buildAbsoluteURL(baseURL, './a:b')`).","message":"When resolving relative URLs containing a colon (e.g., `a:b`), `url-toolkit` treats them as absolute if not prefixed with `./`. To ensure such URLs are treated as relative, explicitly prefix them with `./` (e.g., `./a:b`).","severity":"gotcha","affected_versions":"*"},{"fix":"Pass `{ alwaysNormalize: true }` as the third argument to `buildAbsoluteURL` if consistent path normalization is desired: `buildAbsoluteURL(baseURL, relativeURL, { alwaysNormalize: true })`.","message":"Path normalization (e.g., resolving `../` or `./`) is not always applied by default unless necessary according to RFC 1808. If you require consistent, full path normalization, you must explicitly set `opts.alwaysNormalize` to `true`.","severity":"gotcha","affected_versions":"*"},{"fix":"Upgrade to `url-toolkit@2.1.5` or later to ensure correct handling of semicolons within URL fragments.","message":"Version `2.1.5` changed how semicolons (`;`) are handled within URL fragments, allowing them to be correctly included. Older versions might have incorrectly parsed or truncated fragments containing semicolons.","severity":"gotcha","affected_versions":"<2.1.5"}],"env_vars":null,"search_vec":"'/example.com':104 '1808':30,84,121 '2.2.5':36 'absolut':16,126 'adher':27,81 'affect':99 'applic':116 'base':20 'browser':75 'bug':47 'build':15 'cadenc':43 'complianc':122 'constructor':73 'current':32 'depend':9 'dependency-fre':8 'design':13 'differ':86,97 'differenti':68 'document':64 'enhanc':65 'environ':114 'fix':48 'focus':45 'free':10 'improv':50 'javascript':11,123 'key':67 'librari':12 'lightweight':7 'like':51,103 'live':91 'maintain':39 'make':109 'nativ':71 'node.js':77 'normal':106 'notabl':98 'occasion':63 'optim':53 'pars':108 'parser':127 'patch':61 'perform':49 'precis':119 'primarili':44 'project':38 'redo':59 'regex':52 'relat':24,125 'releas':42 'requir':118 'rfc':29,83,120 'secur':55 'special':101 'specif':26 'stabl':33 'standard':92 'steadi':41 'strict':80 'suitabl':112 'toolkit':2,4,111 'typescript':128 'updat':56 'url':1,3,17,21,25,72,90,95,102,110,124 'use':93 'version':34 'vulner':60 'whatwg':89","created_at":"2026-04-20T01:58:30.637342+00:00","updated_at":"2026-04-20T01:58:30.637342+00:00","problems":[{"fix":"For CommonJS, use `const URLToolkit = require('url-toolkit'); URLToolkit.buildAbsoluteURL(...)`. For ESM/TypeScript, use `import { buildAbsoluteURL } from 'url-toolkit';` or `import * as URLToolkit from 'url-toolkit'; URLToolkit.buildAbsoluteURL(...)`.","cause":"Attempting to destructure `URLToolkit` when using CommonJS `require()` or incorrectly importing in an ESM context.","error":"TypeError: URLToolkit.buildAbsoluteURL is not a function"},{"fix":"Ensure you are using `import * as URLToolkit from 'url-toolkit';` or `import { buildAbsoluteURL } from 'url-toolkit';` to correctly access the functions.","cause":"Incorrect TypeScript import statement, often trying to use a default import instead of a namespace or named import.","error":"Property 'buildAbsoluteURL' does not exist on type 'typeof import(\"url-toolkit\")' (TypeScript)"},{"fix":"Review the documentation on 'Differences to JS `URL()`' in the `url-toolkit` README. If WHATWG-compliant behavior is required, consider using the native `URL()` constructor instead.","cause":"Misunderstanding the difference between RFC 1808 (implemented by `url-toolkit`) and the WHATWG URL Standard (used by native `URL()`). `url-toolkit` will not perform 'special URL' normalizations like `URL()`.","error":"Unexpected URL resolution result (e.g., `http:///example.com` not normalizing to `http://example.com`)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/tjenkinson/url-toolkit","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/url-toolkit","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}