{"_id":"url-normalize","_rev":"19-ad4116ad76239e3d4e154ec75ee22689","name":"url-normalize","dist-tags":{"latest":"2.3.0"},"versions":{"1.1.0":{"name":"url-normalize","version":"1.1.0","keywords":["url","normalize","normalization","uri","url-normalization","url-normalize","querystrings","domain","extract","canonical"],"author":{"name":"Vlad Pronsky","email":"v.pronsky@gmail.com"},"license":"MIT","_id":"url-normalize@1.1.0","maintainers":[{"name":"vladkens","email":"v.pronsky@gmail.com"}],"dist":{"shasum":"d4cefbfdf2dce35687b6a1d264264469bee08c4b","tarball":"https://registry.npmjs.org/url-normalize/-/url-normalize-1.1.0.tgz","fileCount":12,"integrity":"sha512-LL9Ca2W5anE5m3h/q7lM6K9Vl0sYpAYUTa+uu9WQN9zExPRT8bdE2PKER/SXzw6Zh3IicjPmkkxSBQBaOhLIUQ==","signatures":[{"sig":"MEUCIEvoHcRfT4F6H4TUO9JKoNTA5cW3VyHbDwRpE6a8RkyTAiEAqFsspkUiw7RAV7hxlmcT/Q44m2Y1NUEHfEE7EptQNek=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":25126},"type":"module","exports":{"types":"./dist/main.d.ts","import":"./dist/main.mjs","require":"./dist/main.cjs"},"gitHead":"1595dc80ecc0d5efab8abf9e816659ca8c55a7e9","scripts":{"test":"uvu -r tsm tests/","build":"rm -rf dist && microbundle -f cjs,modern","test-cov":"c8 --include=src yarn test","test-watch":"watchexec -e ts 'clear && yarn test'","format-check":"prettier --check \"{src,tests}/**/*.{js,jsx,ts,tsx}\""},"_npmUser":{"name":"vladkens","email":"v.pronsky@gmail.com"},"_npmVersion":"9.5.1","description":"
\"version\" \n\n[\"version\"](https://npmjs.org/package/url-normalize)\n[\"size\"](https://packagephobia.now.sh/result?p=url-normalize)\n[\"downloads\"](https://npmjs.org/package/url-normalize)\n[\"license\"](https://github.com/vladkens/url-normalize/blob/main/LICENSE)\n\n
\n\nTurns any URL-like string into a clean, canonical `https://` URL — returns `null` if it can't.\n\n- **Safe.** Returns `null` for invalid input — no try/catch needed.\n- **Tiny.** 980 bytes (brotli). One dependency.\n- **Smart defaults.** HTTPS, no `www`, sorted query params, stripped default ports — automatic.\n- **Configurable.** 12 options to control every part of the URL.\n- **International.** Unicode ↔ Punycode conversion in both directions.\n- **Batteries included.** `extractDomain` and `humanizeUrl` utilities come with the package.\n\nWorks with bare domains (`example.com`), protocol-relative (`//example.com`), and messy real-world URLs. Compared to [normalize-url](https://github.com/sindresorhus/normalize-url): dual CJS + ESM exports, `null` return instead of throwing, and built-in domain/display utilities.\n\n## Install\n\n```sh\nnpm i url-normalize\n```\n\n## Usage\n\n```typescript\nimport { urlNormalize } from \"url-normalize\"\n\nurlNormalize(\"example.com\")\n// → \"https://example.com\"\n\nurlNormalize(\"//www.example.com:443/../foo/bar?b=2&a=1#tag\")\n// → \"https://example.com/foo/bar?a=1&b=2\"\n\nurlNormalize(\"👻💥.ws\")\n// → \"https://xn--9q8huc.ws\"\n\n// Invalid input returns null — no exceptions\nurlNormalize(\"example\") // → null\nurlNormalize(\"mailto:user@example.com\") // → null\n```\n\n## Options\n\nAll options have sensible defaults. Pass an options object as the second argument.\n\n### `defaultProtocol` (default: `\"https\"`)\n\nProtocol to prepend when the URL has none. Preserves an existing protocol.\n\n```typescript\nurlNormalize(\"example.com\", { defaultProtocol: \"http\" })\n// → \"http://example.com\"\n\n// Existing protocol is preserved\nurlNormalize(\"https://example.com\", { defaultProtocol: \"http\" })\n// → \"https://example.com\"\n```\n\n### `protocol` (default: `true`)\n\nInclude or strip the protocol prefix.\n\n```typescript\nurlNormalize(\"https://example.com/foo?bar=baz\", { protocol: false })\n// → \"example.com/foo?bar=baz\"\n```\n\n### `www` (default: `false`)\n\nKeep or remove the `www.` subdomain.\n\n```typescript\nurlNormalize(\"www.example.com\") // → \"https://example.com\"\nurlNormalize(\"www.example.com\", { www: true }) // → \"https://www.example.com\"\n```\n\n### `auth` (default: `false`)\n\nKeep or strip `user:pass@` credentials.\n\n```typescript\nurlNormalize(\"https://user:pass@example.com\") // → \"https://example.com\"\nurlNormalize(\"https://user:pass@example.com\", { auth: true }) // → \"https://user:pass@example.com\"\n```\n\n### `port` (default: `false`)\n\nKeep or strip port numbers. Default ports (80 for HTTP, 443 for HTTPS) are always removed.\n\n```typescript\nurlNormalize(\"https://example.com:8080\", { port: true }) // → \"https://example.com:8080\"\nurlNormalize(\"https://example.com:443\", { port: true }) // → \"https://example.com\"\n```\n\n### `index` (default: `true`)\n\nWhen `false`, strips `index.html` / `index.htm` from path endings.\n\n```typescript\nurlNormalize(\"example.com/foo/index.html\") // → \"https://example.com/foo/index.html\"\nurlNormalize(\"example.com/foo/index.html\", { index: false }) // → \"https://example.com/foo\"\n```\n\n### `search` (default: `true`)\n\nKeep or strip the query string.\n\n```typescript\nurlNormalize(\"example.com/?a=1&b=2\", { search: false }) // → \"https://example.com\"\n```\n\n### `sortSearch` (default: `true`)\n\nSort query parameters alphabetically.\n\n```typescript\nurlNormalize(\"example.com/?b=2&a=1\") // → \"https://example.com/?a=1&b=2\"\nurlNormalize(\"example.com/?b=2&a=1\", { sortSearch: false }) // → \"https://example.com/?b=2&a=1\"\n```\n\n### `filterSearch`\n\nKeep only matching query parameters.\n\n```typescript\nurlNormalize(\"example.com/?c=3&b=2&a=1\", { filterSearch: (k, v) => k === \"a\" || v === \"3\" })\n// → \"https://example.com/?a=1&c=3\"\n```\n\n### `fragment` (default: `true`)\n\nKeep or strip the URL hash fragment.\n\n```typescript\nurlNormalize(\"example.com/#foo\") // → \"https://example.com/#foo\"\nurlNormalize(\"example.com/#foo\", { fragment: false }) // → \"https://example.com\"\n```\n\n### `textFragment` (default: `false`)\n\nKeep or strip [text fragment](https://wicg.github.io/scroll-to-text-fragment/) anchors (`#:~:text=…`).\n\n```typescript\nurlNormalize(\"example.com/#:~:text=hello\") // → \"https://example.com\"\nurlNormalize(\"example.com/#:~:text=hello\", { textFragment: true }) // → \"https://example.com/#:~:text=hello\"\n```\n\n### `customProtocol` (default: `false`)\n\nAllow non-standard protocols like `tg://`, `ftps://`, etc.\n\n```typescript\nurlNormalize(\"tg://example.com\") // → null\nurlNormalize(\"tg://example.com\", { customProtocol: true }) // → \"tg://example.com\"\n```\n\n### `forceProtocol`\n\nReplace the protocol with a fixed value regardless of input.\n\n```typescript\nurlNormalize(\"https://example.com\", { forceProtocol: \"sftp\" }) // → \"sftp://example.com\"\n```\n\n### `unicode` (default: `false`)\n\nReturn Unicode domain names instead of Punycode.\n\n```typescript\nurlNormalize(\"👻💥.ws\", { unicode: true }) // → \"https://👻💥.ws\"\nurlNormalize(\"https://xn--9q8huc.ws\", { unicode: true }) // → \"https://👻💥.ws\"\n```\n\n## Advanced\n\n### `createUrlNormalize`\n\nCreates a reusable normalizer with preset options.\n\n```typescript\nimport { createUrlNormalize } from \"url-normalize\"\n\nconst normalize = createUrlNormalize({ defaultProtocol: \"http\", fragment: false })\n\nnormalize(\"example.com/foo#tag\") // → \"http://example.com/foo\"\n```\n\n### `urlNormalizeOrFail`\n\nThrows instead of returning `null` on invalid input.\n\n```typescript\nimport { urlNormalizeOrFail } from \"url-normalize\"\n\nurlNormalizeOrFail(\"invalid\") // throws\nurlNormalizeOrFail(\"example.com\") // → \"https://example.com\"\n```\n\n### `extractDomain` / `extractDomainOrFail`\n\nExtracts the bare domain from any URL.\n\n```typescript\nimport { extractDomain, extractDomainOrFail } from \"url-normalize\"\n\nextractDomain(\"https://example.com:8080/?a=1&b=2#tag\") // → \"example.com\"\nextractDomain(\"invalid\") // → null\nextractDomainOrFail(\"invalid\") // throws\n```\n\n### `humanizeUrl` / `humanizeUrlOrFail`\n\nStrips the protocol for display-friendly URLs.\n\n```typescript\nimport { humanizeUrl, humanizeUrlOrFail } from \"url-normalize\"\n\nhumanizeUrl(\"https://example.com/foo/bar\") // → \"example.com/foo/bar\"\nhumanizeUrl(\"invalid\") // → null\nhumanizeUrlOrFail(\"invalid\") // throws\n```\n\n## Similar\n\n- [sindresorhus/normalize-url](https://github.com/sindresorhus/normalize-url)\n","readmeFilename":"readme.md"}