url-normalize

Normalize a URL — faithful Rust port of sindresorhus/normalize-url v9.0.0.

Useful when you need to display, store, deduplicate, sort, compare, etc., URLs.

Usage

use url_normalize::{normalize_url, Options};

// Basic usage with default options
let result = normalize_url("HTTP://www.Example.com/foo/", &Options::default()).unwrap();
assert_eq!(result, "http://example.com/foo");

// Custom options
let opts = Options {
    strip_hash: true,
    force_https: true,
    ..Options::default()
};
let result = normalize_url("http://www.example.com/path#fragment", &opts).unwrap();
assert_eq!(result, "https://example.com/path");

Add to your Cargo.toml:

[dependencies]
url-normalize = "0.1"

What it does

Lowercases the protocol and hostname
Removes default ports (80 for HTTP, 443 for HTTPS)
Resolves relative paths (/../, /./)
Removes duplicate slashes in paths
Removes www. from the hostname
Removes trailing slashes
Removes URL fragments (optional)
Removes known tracking parameters (e.g., utm_*)
Sorts query parameters alphabetically
Decodes unnecessarily encoded URI octets
Encodes query values like URLSearchParams
Handles international domain names (IDNA/Punycode)
Handles data URLs
Handles custom protocol schemes

Options

Option	Type	Default	Description
`default_protocol`	`Protocol`	`Http`	Protocol to use for protocol-relative URLs
`custom_protocols`	`Vec<String>`	`[]`	Additional protocols to normalize
`normalize_protocol`	`bool`	`true`	Prepend default protocol to `//` URLs
`force_http`	`bool`	`false`	Convert HTTPS → HTTP
`force_https`	`bool`	`false`	Convert HTTP → HTTPS
`strip_authentication`	`bool`	`true`	Remove `user:password@`
`strip_hash`	`bool`	`false`	Remove `#fragment`
`strip_protocol`	`bool`	`false`	Remove `https://` prefix
`strip_text_fragment`	`bool`	`true`	Remove `#:~:text=` fragments
`strip_www`	`bool`	`true`	Remove `www.` from hostname
`remove_query_parameters`	`RemoveQueryParameters`	UTM filter	Remove matching query params
`keep_query_parameters`	`Option<Vec<QueryFilter>>`	`None`	Keep only matching query params
`remove_trailing_slash`	`bool`	`true`	Remove trailing `/` from path
`remove_single_slash`	`bool`	`true`	Remove sole `/` path
`remove_directory_index`	`RemoveDirectoryIndex`	`None`	Remove `index.html` etc.
`remove_explicit_port`	`bool`	`false`	Remove all port numbers
`sort_query_parameters`	`bool`	`true`	Sort query params by key
`empty_query_value`	`EmptyQueryValue`	`Preserve`	How to handle `?key` vs `?key=`
`remove_path`	`bool`	`false`	Remove the entire URL path
`transform_path`	`Option<Box<dyn Fn(...)>>`	`None`	Custom path transformation

Examples

Remove tracking parameters

use url_normalize::{normalize_url, Options};

let url = "https://example.com/page?utm_source=google&utm_medium=cpc&id=123";
let result = normalize_url(url, &Options::default()).unwrap();
assert_eq!(result, "https://example.com/page?id=123");

Remove all query parameters

use url_normalize::{normalize_url, Options, RemoveQueryParameters};

let opts = Options {
    remove_query_parameters: RemoveQueryParameters::All,
    ..Options::default()
};
let result = normalize_url("https://example.com?a=1&b=2", &opts).unwrap();
assert_eq!(result, "https://example.com");

Custom protocols

use url_normalize::{normalize_url, Options};

let opts = Options {
    custom_protocols: vec!["myapp".to_string()],
    ..Options::default()
};
let result = normalize_url("myapp://www.example.com/path/", &opts).unwrap();
assert_eq!(result, "myapp://example.com/path");

Directory index removal

use url_normalize::{normalize_url, Options, RemoveDirectoryIndex};

let opts = Options {
    remove_directory_index: RemoveDirectoryIndex::Default,
    ..Options::default()
};
let result = normalize_url("https://example.com/page/index.html", &opts).unwrap();
assert_eq!(result, "https://example.com/page");

Dependencies

Minimal by design:

idna — International domain name encoding (IDNA/Punycode)

Everything else (URL parsing, percent-encoding, pattern matching) is hand-rolled.

Testing

The implementation is verified against the actual JavaScript test suite from sindresorhus/normalize-url v9.0.0:

# Rust tests (175 tests)
cargo test

# Run the actual JS test.js against our implementation
cargo build --features cli --bin normalize_cli
cd tests/js_bridge && npm install && npx ava actual_test.mjs --timeout=60s

Attribution

This is a Rust port of normalize-url by Sindre Sorhus, licensed under the MIT License.

License

MIT

url-normalize 0.1.0