URL Hostname Normalizer

Build a URL normalization utility that extracts and normalizes hostnames from various URL formats. The utility should handle diverse input types and provide clean hostname outputs for comparison and grouping operations.

Requirements

Implement a module that provides the following functionality:

Core Functionality

Create a function normalizeHostname(url: string): string | null that:

• Extracts the hostname from a complete URL
• Removes protocol prefixes (http://, https://, etc.)
• Strips authentication credentials if present
• Removes port numbers
• Removes paths, query strings, and fragments
• Returns null for invalid inputs or IP addresses
• Handles IPv6 bracket notation correctly

Batch Processing

Create a function normalizeHostnames(urls: string[]): Array<string | null> that:

• Processes an array of URLs
• Returns an array of normalized hostnames in the same order
• Preserves null values for invalid URLs

Grouping by Hostname

Create a function groupByHostname(urls: string[]): Record<string, string[]> that:

• Groups URLs by their normalized hostname
• Returns an object where keys are hostnames and values are arrays of original URLs
• Excludes URLs with invalid or null hostnames

Test Cases { @test }

Test file: test/normalizer.test.ts

Basic hostname extraction

• Given URL "https://www.example.com/path", normalizeHostname returns "www.example.com" @test
• Given URL "http://api.github.com:8080/v1/users?id=123", normalizeHostname returns "api.github.com" @test
• Given URL "https://user:pass@secure.example.org/admin", normalizeHostname returns "secure.example.org" @test

Edge cases

• Given plain hostname "example.com", normalizeHostname returns "example.com" @test
• Given IP address "https://192.168.1.1/path", normalizeHostname returns null @test
• Given IPv6 URL "http://[2001:db8::1]:8080/", normalizeHostname returns null @test

Batch processing

• Given array ["https://example.com/a", "http://test.org/b", "https://192.168.1.1/c"], normalizeHostnames returns ["example.com", "test.org", null] @test

Grouping

• Given URLs ["https://example.com/page1", "https://example.com/page2", "http://test.org/home"], groupByHostname returns object with keys "example.com" and "test.org" containing their respective original URLs @test

Implementation

@generates

API

/**
 * Normalizes a URL by extracting its hostname
 * @param url - The URL string to normalize
 * @returns The normalized hostname or null if invalid/IP address
 */
export function normalizeHostname(url: string): string | null;

/**
 * Normalizes an array of URLs
 * @param urls - Array of URL strings
 * @returns Array of normalized hostnames in the same order
 */
export function normalizeHostnames(urls: string[]): Array<string | null>;

/**
 * Groups URLs by their normalized hostname
 * @param urls - Array of URL strings
 * @returns Object mapping hostnames to arrays of original URLs
 */
export function groupByHostname(urls: string[]): Record<string, string[]>;

Dependencies { .dependencies }

tldts { .dependency }

Provides URL parsing and hostname extraction functionality.