Component Processing

/**
 * Percent-encode characters in a URI component
 * @param str - The string to escape
 * @param options - Optional encoding configuration (iri mode affects which characters are escaped)
 * @returns Percent-encoded string
 */
function escapeComponent(str: string, options?: URIOptions): string;

import { escapeComponent } from "uri-js";

// Basic escaping for URI components
const escaped = escapeComponent("hello world");
console.log(escaped); // "hello%20world"

// Escape special characters
const special = escapeComponent("user@domain.com");
console.log(special); // "user%40domain.com"

// Escape with IRI mode (preserves more Unicode characters)
const iriEscaped = escapeComponent("café", { iri: true });
console.log(iriEscaped); // "café" (Unicode preserved in IRI mode)

// Escape without IRI mode
const uriEscaped = escapeComponent("café");
console.log(uriEscaped); // "caf%C3%A9" (Unicode encoded)

/**
 * Decode percent-encoded characters in a URI component
 * @param str - The string to unescape
 * @param options - Optional decoding configuration (iri mode affects decoding behavior)
 * @returns Decoded string
 */
function unescapeComponent(str: string, options?: URIOptions): string;

import { unescapeComponent } from "uri-js";

// Basic unescaping
const unescaped = unescapeComponent("hello%20world");
console.log(unescaped); // "hello world"

// Unescape encoded characters
const email = unescapeComponent("user%40domain.com");
console.log(email); // "user@domain.com"

// Unescape Unicode characters
const unicode = unescapeComponent("caf%C3%A9");
console.log(unicode); // "café"

// Unescape with IRI mode
const iriUnescaped = unescapeComponent("ros%C3%A9", { iri: true });
console.log(iriUnescaped); // "rosé"

/**
 * Remove dot segments from a URI path according to RFC 3986
 * @param input - The path string containing dot segments
 * @returns Path with dot segments removed
 */
function removeDotSegments(input: string): string;

import { removeDotSegments } from "uri-js";

// Remove single dot segments
const simple = removeDotSegments("/a/b/c/./../../g");
console.log(simple); // "/a/g"

// Remove complex dot segments
const complex = removeDotSegments("/a/b/c/./../d/./e/../f");
console.log(complex); // "/a/b/d/f"

// Handle edge cases
const edgeCase = removeDotSegments("../../../g");
console.log(edgeCase); // "g"

// Preserve trailing slashes
const trailing = removeDotSegments("/a/b/c/../");
console.log(trailing); // "/a/b/"

/**
 * Resolve relative URI components against base URI components
 * @param base - Base URI components
 * @param relative - Relative URI components to resolve
 * @param options - Optional resolution configuration
 * @param skipNormalization - Skip normalization of input components (default: false)
 * @returns Resolved URI components
 */
function resolveComponents(
  base: URIComponents, 
  relative: URIComponents, 
  options: URIOptions = {}, 
  skipNormalization?: boolean
): URIComponents;

import { resolveComponents } from "uri-js";

// Basic component resolution
const base = {
  scheme: "http",
  host: "example.com",
  path: "/a/b/c/d"
};

const relative = {
  path: "../../g"
};

const resolved = resolveComponents(base, relative);
console.log(resolved);
// {
//   scheme: "http",
//   host: "example.com", 
//   path: "/a/g"
// }

// Resolve with query changes
const withQuery = resolveComponents(base, { query: "newquery" });
console.log(withQuery.query); // "newquery"
console.log(withQuery.path); // "/a/b/c/d" (preserved from base)

// Resolve with fragment
const withFragment = resolveComponents(base, { fragment: "section" });
console.log(withFragment.fragment); // "section"

// Resolve with authority override
const withAuthority = resolveComponents(base, {
  host: "other.com",
  path: "/new/path"
});
console.log(withAuthority);
// {
//   scheme: "http",
//   host: "other.com",
//   path: "/new/path"
// }

// Skip normalization for performance
const skipNorm = resolveComponents(base, relative, {}, true);

/**
 * Percent-encode a single character
 * @param chr - Character to encode  
 * @returns Percent-encoded character
 */
function pctEncChar(chr: string): string;

/**
 * Decode a sequence of percent-encoded characters
 * @param str - String containing percent-encoded sequences
 * @returns Decoded string
 */
function pctDecChars(str: string): string;

import { pctEncChar, pctDecChars } from "uri-js";

// Encode single character
const encoded = pctEncChar("@");
console.log(encoded); // "%40"

// Encode Unicode character
const unicode = pctEncChar("é");
console.log(unicode); // "%C3%A9"

// Decode character sequence
const decoded = pctDecChars("%48%65%6C%6C%6F");
console.log(decoded); // "Hello"

// Decode Unicode sequence
const unicodeDecoded = pctDecChars("%C3%A9");
console.log(unicodeDecoded); // "é"

import { parse, serialize, resolveComponents, removeDotSegments, escapeComponent } from "uri-js";

// Parse, modify components, and rebuild
const original = "http://example.com/path with spaces/../file.html";
const components = parse(original);

// Clean up the path
components.path = removeDotSegments(components.path || "");

// Escape spaces in path
components.path = escapeComponent(components.path);

// Add query parameter
components.query = "version=1.0";

// Rebuild URI
const result = serialize(components);
console.log(result); // "http://example.com/path%20with%20spaces/file.html?version=1.0"

import { unescapeComponent, removeDotSegments } from "uri-js";

// Handles invalid encoding gracefully
const invalid = unescapeComponent("%ZZ");
console.log(invalid); // "%ZZ" (unchanged)

// Handles empty input
const empty = removeDotSegments("");
console.log(empty); // ""