{"id":15544790,"url":"https://github.com/slevithan/parseuri","last_synced_at":"2025-04-04T21:06:05.076Z","repository":{"id":231777514,"uuid":"782695536","full_name":"slevithan/parseuri","owner":"slevithan","description":"Mighty but tiny URI parser","archived":false,"fork":false,"pushed_at":"2024-11-23T11:22:33.000Z","size":118,"stargazers_count":27,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-28T15:52:21.765Z","etag":null,"topics":["uri","uri-parser","url","url-parser"],"latest_commit_sha":null,"homepage":"https://slevithan.github.io/parseuri/demo/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slevithan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"slevithan"}},"created_at":"2024-04-05T20:32:23.000Z","updated_at":"2025-03-20T15:32:16.000Z","dependencies_parsed_at":"2024-06-18T14:05:06.615Z","dependency_job_id":"5bbaef0a-5e9d-4f00-93e2-74e77d13b760","html_url":"https://github.com/slevithan/parseuri","commit_stats":{"total_commits":59,"total_committers":1,"mean_commits":59.0,"dds":0.0,"last_synced_commit":"c72d3a0c6421b7ea34ef2bbc5868d5bc4f5df201"},"previous_names":["slevithan/parseuri"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slevithan%2Fparseuri","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slevithan%2Fparseuri/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slevithan%2Fparseuri/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slevithan%2Fparseuri/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slevithan","download_url":"https://codeload.github.com/slevithan/parseuri/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247249524,"owners_count":20908212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["uri","uri-parser","url","url-parser"],"created_at":"2024-10-02T12:40:23.434Z","updated_at":"2025-04-04T21:06:05.050Z","avatar_url":"https://github.com/slevithan.png","language":"JavaScript","funding_links":["https://github.com/sponsors/slevithan"],"categories":[],"sub_categories":[],"readme":"# parseUri\n\n[![npm version][npm-version-src]][npm-version-href]\n[![npm downloads][npm-downloads-src]][npm-downloads-href]\n[![bundle][bundle-src]][bundle-href]\n\n`parseUri` is a mighty but tiny JavaScript URI/URN/URL parser that splits any URI into its parts (all of which are optional). Its combination of accuracy, comprehensiveness, and brevity is unrivaled (\u003c 1KB min/gzip, with no dependencies).\n\n## Breaking changes\n\nVersion 2 was a major, breaking change that might require updating URI part names in your code and/or providing `'friendly'` as a second argument to preserve the previous default handling of relative paths. See details in the [v2 release notes](https://github.com/slevithan/parseuri/releases/tag/v2.0.0), and compare results with v1.2.2 on the [demo page](https://slevithan.github.io/parseuri/demo/?compareV1=true\u0026friendlyMode=true). Version 3 was a minor update published on npm as pure ESM.\n\n## Compared to the `URL` constructor\n\n`parseUri` includes several advantages over JavaScript’s built-in [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL):\n\n* It gives you many additional properties (`authority`, `userinfo`, `subdomain`, `domain`, `tld`, `resource`, `directory`, `filename`, `suffix`) that aren’t available from `URL`.\n* `URL` throws e.g. if not given a protocol, and in many other cases of valid (but not supported) and invalid URIs. `parseUri` makes a best case effort even with partial or invalid URIs and is extremely good with edge cases.\n* `URL`’s rules don’t allow correctly handling many non-web protocols. For example, `URL` doesn’t throw on any of `'git://localhost:1234'`, `'ssh://myid@192.168.1.101'`, or `'t2ab:///path/entry'`, but it also doesn’t get their details correct since it treats everything after `\u003cnon-web-protocol\u003e:` up to `?` or `#` as part of the `pathname`.\n* `parseUri` includes a “friendly” parsing mode (in addition to its default mode) that handles human-friendly URLs like `'example.com/file.html'` as expected.\n* `parseUri` supports providing a list of second-level domains that should be treated as part of the top-level domain (ex: `co.uk`).\n\nConversely, `parseUri` is single-purpose and doesn’t apply normalization.\n\nYou can compare with `URL`’s results on the [demo page](https://slevithan.github.io/parseuri/demo/?urlStandard=true).\n\n## Results / URI parts\n\nReturns an object with 20 URI parts as properties plus `queryParams`, a [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object that includes methods `get(key)`, `getAll(key)`, etc.\n\nHere’s an example of what each part contains:\n\n```text\n┌──────────────────────────────────────────────────────────────────────────────────────────────────────────┐\n│                                                  href                                                    │\n├────────────────────────────────────────────────────────────────┬─────────────────────────────────────────┤\n│                             origin                             │                resource                 │\n├──────────┬─┬───────────────────────────────────────────────────┼──────────────────────┬───────┬──────────┤\n│ protocol │ │                     authority                     │       pathname       │ query │ fragment │\n│          │ ├─────────────────────┬─────────────────────────────┼───────────┬──────────┤       │          │\n│          │ │      userinfo       │            host             │ directory │ filename │       │          │\n│          │ ├──────────┬──────────┼──────────────────────┬──────┤           ├─┬────────┤       │          │\n│          │ │ username │ password │       hostname       │ port │           │ │ suffix │       │          │\n│          │ │          │          ├───────────┬──────────┤      │           │ ├────────┤       │          │\n│          │ │          │          │ subdomain │  domain  │      │           │ │        │       │          │\n│          │ │          │          │           ├────┬─────┤      │           │ │        │       │          │\n│          │ │          │          │           │    │ tld │      │           │ │        │       │          │\n\"  https   ://   user   :   pass   @ sub1.sub2 . dom.com  : 8080   /p/a/t/h/  a.html    ?  q=1  #   hash   \"\n└──────────────────────────────────────────────────────────────────────────────────────────────────────────┘\n```\n\n\u003e If this chart isn’t appearing correctly, view it on [GitHub](https://github.com/slevithan/parseuri/blob/main/README.md#results--uri-parts).\n\n`parseUri` additionally supports IPv4 and IPv6 addresses, URNs, and many edge cases not shown here. See the extensive [tests](https://slevithan.github.io/parseuri/spec/). References include [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) and [WHATWG URL](https://url.spec.whatwg.org/).\n\n## Parsing modes\n\n`parseUri` has two parsing modes (default and friendly), specified via an optional second argument:\n\n```js\n// Default mode\nparseUri(uri);\n// Also default mode\nparseUri(uri, 'default');\n// Friendly mode\nparseUri(uri, 'friendly');\n```\n\nThe default mode follows official URI standards, whereas friendly mode handles human-friendly URLs like `'example.com/file.html'` as expected. Results are identical for any URI that starts with `\u003cprotocol\u003e://`, `\u003cweb-protocol\u003e:`, `:`, `//`, `/`, `\\`, `?`, or `#`.\n\nTo be precise, the only difference is that friendly mode doesn’t require `\u003cprotocol\u003e:`, `:`, `//`, or other repeating slashes to signal the start of an authority. This has the following effects:\n\n- It allows starting a URI with an authority, such as `'example.com'`.\n- It therefore precludes proper handling for relative paths (without a leading `/` or `\\`) such as `'dir/file.html'`. Friendly mode considers this example to start with hostname `dir`.\n- It avoids requiring `//` after a non-web protocol.\n  - The “web protocols” are `http`, `https`, `ws`, `wss`, and `ftp`. They never require `//`, and friendly mode extends this handling to non-web protocols.\n\nYou can compare results of the default and friendly modes on the [demo page](https://slevithan.github.io/parseuri/demo/?friendlyMode=true).\n\n## Examples\n\n```js\nlet uri = parseUri('https://a.b.example.com:80/@user/a/my.img.jpg?q=x\u0026q=#hash');\nuri.protocol // → 'https'\nuri.host // → 'a.b.example.com:80'\nuri.hostname // → 'a.b.example.com'\nuri.subdomain // → 'a.b'\nuri.domain // → 'example.com'\nuri.port // → '80'\nuri.resource // → '/@user/a/my.img.jpg?q=x\u0026q=#hash'\nuri.pathname // → '/@user/a/my.img.jpg'\nuri.directory // → '/@user/a/'\nuri.filename // → 'my.img.jpg'\nuri.suffix // → 'jpg'\nuri.query // → 'q=x\u0026q='\nuri.fragment // → 'hash'\nuri.queryParams.get('q') // → 'x'\nuri.queryParams.getAll('q') // → ['x', '']\nuri.queryParams.get('not-present') // → null\nuri.queryParams.getAll('not-present') // → []\n// Also available: href, origin, authority, userinfo, username, password, tld\n\n// Relative path\nuri = parseUri('dir/file.html?q=x');\nuri.hostname // → ''\nuri.directory // → 'dir/'\nuri.filename // → 'file.html'\nuri.query // → 'q=x'\n\n// Friendly mode allows starting with an authority\nuri = parseUri('example.com/file.html', 'friendly');\nuri.hostname // → 'example.com'\nuri.directory // → '/'\nuri.filename // → 'file.html'\n\n// IPv4 address\nuri = parseUri('ssh://myid@192.168.1.101');\nuri.protocol // → 'ssh'\nuri.username // → 'myid'\nuri.hostname // → '192.168.1.101'\nuri.domain // → ''\n\n// IPv6 address\nuri = parseUri('https://[2001:db8:85a3::7334]:80?q=x');\nuri.hostname // → '[2001:db8:85a3::7334]'\nuri.port // → '80'\nuri.domain // → ''\nuri.query // → 'q=x'\n\n// Mailto\nuri = parseUri('mailto:me@my.com?subject=Hey\u0026body=Sign%20me%20up!');\nuri.protocol // → 'mailto'\nuri.authority // → ''\nuri.username // → ''\nuri.hostname // → ''\nuri.pathname // → 'me@my.com'\nuri.query // → 'subject=Hey\u0026body=Sign%20me%20up!'\nuri.queryParams.get('body') // → 'Sign me up!'\n\n// Mailto in friendly mode\nuri = parseUri('mailto:me@my.com', 'friendly');\nuri.protocol // → 'mailto'\nuri.authority // → 'me@my.com'\nuri.username // → 'me'\nuri.hostname // → 'my.com'\nuri.pathname // → ''\n\n/* Also supports e.g.:\n- https://[2001:db8:85a3::7334%en1]/ipv6-with-zone-identifier\n- git://localhost:1234\n- file:///path/file\n- tel:+1-800-555-1212\n- urn:uuid:c5542ab6-3d96-403e-8e6b-b8bb52f48d9a?q=x\n*/\n```\n\nTest and compare results on the [demo page](https://slevithan.github.io/parseuri/demo/).\n\n## Install and use\n\n```bash\nnpm install parseuri\n```\n\n```js\nimport { parseUri, setTlds } from 'parseuri';\n```\n\nIn browsers:\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/parseuri/dist/parseuri.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  console.log(parseUri('https://example.com/'));\n  // If needed, use `parseUri.setTlds`\n\u003c/script\u003e\n```\n\n\u003c!-- Badges --\u003e\n\n[npm-version-src]: https://img.shields.io/npm/v/parseuri?color=78C372\n[npm-version-href]: https://npmjs.com/package/parseuri\n[npm-downloads-src]: https://img.shields.io/npm/dm/parseuri?color=78C372\n[npm-downloads-href]: https://npmjs.com/package/parseuri\n[bundle-src]: https://img.shields.io/bundlejs/size/parseuri?color=78C372\u0026label=minzip\n[bundle-href]: https://bundlejs.com/?q=parseuri\u0026treeshake=[*]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslevithan%2Fparseuri","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslevithan%2Fparseuri","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslevithan%2Fparseuri/lists"}