{"id":23634986,"url":"https://github.com/wizard04wsu/uri_parsing","last_synced_at":"2025-10-19T10:33:34.522Z","repository":{"id":13882752,"uuid":"16580871","full_name":"wizard04wsu/URI_Parsing","owner":"wizard04wsu","description":"JavaScript functions for validating, normalizing, and parsing URIs and email addresses.","archived":false,"fork":false,"pushed_at":"2022-09-04T08:35:55.000Z","size":136,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-01T17:58:27.325Z","etag":null,"topics":["domain","email","ip","ipv4","ipv6","mailbox","mailto","module","parser","schemes","uri","uri-parser","url","url-parser"],"latest_commit_sha":null,"homepage":"","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/wizard04wsu.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}},"created_at":"2014-02-06T13:58:42.000Z","updated_at":"2024-09-26T04:19:11.000Z","dependencies_parsed_at":"2023-01-11T20:21:24.502Z","dependency_job_id":null,"html_url":"https://github.com/wizard04wsu/URI_Parsing","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/wizard04wsu/URI_Parsing","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wizard04wsu%2FURI_Parsing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wizard04wsu%2FURI_Parsing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wizard04wsu%2FURI_Parsing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wizard04wsu%2FURI_Parsing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wizard04wsu","download_url":"https://codeload.github.com/wizard04wsu/URI_Parsing/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wizard04wsu%2FURI_Parsing/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272971369,"owners_count":25024091,"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","status":"online","status_checked_at":"2025-08-31T02:00:09.071Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["domain","email","ip","ipv4","ipv6","mailbox","mailto","module","parser","schemes","uri","uri-parser","url","url-parser"],"created_at":"2024-12-28T05:29:26.187Z","updated_at":"2025-10-19T10:33:34.431Z","avatar_url":"https://github.com/wizard04wsu.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Parsing for URIs and Email Addresses\n\nJavaScript functions for validating, normalizing, and parsing URIs and email addresses.\n\nScheme-specific processing can be easily added. Processing for *http*, *https*, and *mailto* schemes is already included.\n\nThis script does not support:\n- internationalized domain names (IDNs)\n- IPvFuture literal address formats\n- obsolete syntaxes\n- non-ASCII email addresses\n\nThis is a JavaScript module that exports: [`URI`](#uri) (default), [`SegmentedString`](#segmentedstring), [`isDNSDomain`](#isdnsdomain), [`parseMailbox`](#parsemailbox)\n\n[Try it on JSFiddle](https://jsfiddle.net/wizard04/evxog8r2/)\n\n---\n\n## Classes\n\n### SegmentedString\n\nThe **SegmentedString** class extends the **String** class. When coercing an instance to a primitive string value, the value is generated by a custom function instead of using the object's inherent value.\n\nSyntax:\n\u003e `new SegmentedString(toPrimitive, initialMembers)`\n\nParameters:\n- ***toPrimitive*** - (function) This function is called when the object is being coerced into a primitive. Whatever it returns will be converted to a primitive string value.\n- ***initialMembers*** - (object) Optional. The enumerable properties of this object are added to the new instance of SegmentedString.\n\n---\n\n## URI Parsing\n\n### URI()\n\nThe **URI()** function validates and normalizes a URI, splits it into its parts, and does any [additional processing for defined schemes](#scheme-specific-parsers).\n\nSyntax:\n\u003e `URI(uri)`\n\nParameters:\n- ***uri*** - (string) A URI.\n\nReturn value:\n- A [SegmentedString](#SegmentedString) object representing the normalized URI and its parts. Throws a URIError if the URI is invalid or does not conform to its scheme's syntax.\n\n\n### URI.parse()\n\nThe static **URI.parse()** method validates and normalizes a URI and splits it into its generic parts. It does not do any scheme-specific processing.\n\nSyntax:\n\u003e `URI.parse(uri)`\n\nParameters:\n- ***uri*** - (string) A URI.\n\nReturn value:\n- A [SegmentedString](#SegmentedString) object representing the normalized URI and its parts. Throws a URIError if the URI is invalid.\n\n| Property | Type | Description |\n| --- | --- | --- |\n| .**scheme** | string ||\n| .**authority** | SegmentedString | Undefined if the URI does not include an authority. |\n| .authority.**userinfo** | string ||\n| .authority.**host** | SegmentedString | An empty string, registered name, or an IP address. |\n| .authority.host.**name** | string | A registered name. Undefined if the host is an IP address. |\n| .authority.host.**ip** | SegmentedString | An IP address. (IPv4 is preferred, then IPv6 mixed, then IPv6 hex-only.) Undefined if the host is a registered name. |\n| .authority.host.ip.**v4** | string | IPv4 address. Undefined if the host can't be represented as an IPv4 address. |\n| .authority.host.ip.**v6mixed** | string | IPv6 address using mixed hexadecimal and dot-decimal notations to represent an IPv4-mapped IPv6 address. Undefined if the host can't be represented as an IPv4 address. |\n| .authority.host.ip.**v6** | string | IPv6 address using only hexadecimal notation. |\n| .authority.**port** | string ||\n| .**path** | string ||\n| .**query** | string ||\n| .**fragment** | string ||\n\n\n### URI.resolveRelativeReference()\n\nThe static **URI.resolveRelativeReference()** method determines the target URI of a relative reference.\n\nSyntax:\n\u003e `URI.resolveRelativeReference(relativeReference, baseURI)`\n\nParameters:\n- ***relativeReference*** - (string) A relative reference.\n- ***baseURI*** - (string) The URI that the reference is relative to.\n\nReturn value:\n- (string) The target URI.\n\n\n### URI.parseHost()\n\nThe static **URI.parseHost()** method converts an obscured host to a more readable one, along with related representations.\n\nSyntax:\n\u003e `URI.parseHost(host)`\n\nParameters:\n- ***host*** - (string) A registered name or IP address.\n\nReturn value:\n- A [SegmentedString](#SegmentedString) object representing the normalized host (IP address or registered name) and related representations. Throws a URIError if it's not a valid host.\n\n| Property | Type | Description |\n| --- | --- | --- |\n| .**name** | string | A registered name. Undefined if the host is an IP address. |\n| .**ip** | SegmentedString | An IP address. (IPv4 is preferred, then IPv6 mixed, then IPv6 hex-only.) Undefined if the host is a registered name. |\n| .ip.**v4** | string | IPv4 address. Undefined if the host can't be represented as an IPv4 address. |\n| .ip.**v6mixed** | string | IPv6 address using mixed hexadecimal and dot-decimal notations to represent an IPv4-mapped IPv6 address. Undefined if the host can't be represented as an IPv4 address. |\n| .ip.**v6** | string | IPv6 address using only hexadecimal notation. |\n\n\n### URI.parseQuery()\n\nThe static **URI.parseQuery()** method parses a query string as a sequence of key/value pairs.\n\nSyntax:\n\u003e `URI.parseQuery(query, pairSeparator, keyValueSeparator)`\n\nParameters:\n- ***query*** - (string) Query string without the leading \"?\".\n- ***pairSeparator*** - (string) String separating the key/value pairs. Default is `\"\u0026\"`.\n- ***keyValueSeparator*** - (string) String separating a key from its value. Default is `\"=\"`.\n\nReturn value:\n- A [SegmentedString](#SegmentedString) object representing the normalized query string and its key/value pairs.\n\n| Property | Type | Description |\n| --- | --- | --- |\n| .**pairs** | array | An array of decoded key/value pairs. Each pair is an object with properties `key` and `value`. |\n\n\n## Scheme-specific Parsers\n\n### URI.schemeParser\n\nThe name of each of this object's methods corresponds to a URI scheme. Each method takes a generically parsed URI of its scheme and further processes it.\n\nMethods can be added to **URI.schemeParser** to handle any scheme. Methods are included for *[http](#urischemeparserhttp-and-urischemeparserhttps)*, *[https](#urischemeparserhttp-and-urischemeparserhttps)*, and *[mailto](#urischemeparsermailto)*.\n\n### URI.schemeParser.http() and URI.schemeParser.https()\n\nThe static **URI.schemeParser.http()** and **URI.schemeParser.https()** methods continue parsing and normalizing an *http* or *https* URI, respectively, according to the scheme's syntax.\n\nSyntax:\n\u003e `URI.schemeParser.http(parsed)`\n\u003e `URI.schemeParser.https(parsed)`\n\nParameters:\n- ***parsed*** - ([SegmentedString](#SegmentedString)) The generically parsed URI. This object will be modified.\n\nReturn value:\n- Nothing is returned. The ***parsed*** parameter is modified, adding the following properties. Throws a URIError if the URI does not conform to the scheme.\n\n| Property | Type | Description |\n| --- | --- | --- |\n| .query.**pairs** | array | An array of decoded key/value pairs from the query string. Each pair is an object with properties `key` and `value`. |\n\n### URI.schemeParser.mailto()\n\nThe static **URI.schemeParser.mailto()** method continues parsing and normalizing a *mailto* URI according to the scheme's syntax. Email addresses are validated and normalized using the [parseMailbox](#parsemailbox) function. Invalid email addresses are simply left out.\n\nSyntax:\n\u003e `URI.schemeParser.mailto(parsed)`\n\nParameters:\n- ***parsed*** - ([SegmentedString](#SegmentedString)) The generically parsed *mailto*-schemed URI. This object will be modified.\n\nReturn value:\n- Nothing is returned. The ***parsed*** parameter is modified, adding the following properties. Throws a URIError if the URI does not conform to the scheme.\n\n| Property | Type | Description |\n| --- | --- | --- |\n| .query.**pairs** | array | An array of decoded key/value pairs from the query string. Each pair is an object with properties `key` and `value`. |\n| .**to** | array | An array of valid and normalized email addresses. |\n| .**cc** | array | An array of valid and normalized email addresses. |\n| .**bcc** | array | An array of valid and normalized email addresses. |\n| .**subject** | string ||\n| .**body** | string ||\n| .**headers** | array | An array of decoded key/value pairs for any additional email headers in the URI. Each header is an object with properties `name` and `value`. |\n\n---\n\n## Miscellaneous functions\n\n### isDNSDomain()\n\nThe **isDNSDomain()** function determines if a host name conforms to the domain name system (DNS) specifications. (I.e., if it can be used as a domain name.)\n\nSyntax:\n\u003e `isDNSDomain(host)`\n\nParameters:\n- ***host*** - (string)\n\nReturn value:\n- (boolean)\n\n### parseMailbox()\n\nThe **parseMailbox()** function validates and normalizes a mailbox or email address and splits it into its parts.\n\nSyntax:\n\u003e `parseMailbox(mailbox)`\n\nParameters:\n- ***mailbox*** - (string) An email address (e.g., *john.doe@example.com*) or mailbox (e.g., *\"John Doe\" \\\u003cjohn.doe@example.com\\\u003e*).\n\nReturn value:\n- An object containing the following properties. Returns `null` if the mailbox is invalid.\n\n| Property | Type | Description |\n| --- | --- | --- |\n| .**full** | string | If there is a display name: *\"display name\" \\\u003clocal@domain\\\u003e*. If there isn't: *local@domain*. |\n| .**simple** | string | The email address: *local@domain*. |\n| .**displayName** | string | The display name or an empty string. |\n| .**localPart** | string | The local part of the address (to the left of \"@\"). |\n| .**domain** | string | The domain part of the address. Only DNS domains and IP addresses are deemed valid. |\n\n---\n\n## General References\n\n- RFC 3986 \"Uniform Resource Identifier (URI): Generic Syntax\" \u0026nbsp; https://tools.ietf.org/html/rfc3986\n- How to Obscure Any URL \u0026nbsp; http://www.pc-help.org/obscure.htm\n- RFC 6068 \"The 'mailto' URI Scheme\" \u0026nbsp; https://tools.ietf.org/html/rfc6068\n- Wikipedia: Email address \u0026nbsp; https://en.wikipedia.org/wiki/Email_address\n- RFC 5322 \"Internet Message Format\" \u0026nbsp; https://tools.ietf.org/html/rfc5322\n- RFC 5321 \"Simple Mail Transfer Protocol\" \u0026nbsp; https://tools.ietf.org/html/rfc5321#section-4.1.2\n- RFC 5234 \"Augmented BNF for Syntax Specifications: ABNF\" \u0026nbsp; https://tools.ietf.org/html/rfc5234#appendix-B.1\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwizard04wsu%2Furi_parsing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwizard04wsu%2Furi_parsing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwizard04wsu%2Furi_parsing/lists"}