tessl/npm-ufo

URL utils for humans with comprehensive parsing, manipulation, encoding, and normalization functions.

—

Pending

Overview

Eval results

Files

URL Encoding & Decoding

Name: tessl/npm-ufo
Author: tessl

Comprehensive encoding and decoding functions for different URL components with proper handling of special characters, spaces, and international characters. Each function is optimized for specific URL components to ensure proper encoding while maintaining readability and compatibility.

Capabilities

General Encoding & Decoding

Basic encoding and decoding functions for URL components.

/**
 * Encodes characters that need to be encoded in URL path, search and hash sections
 * @param text - String or number to encode
 * @returns URL-encoded string
 */
function encode(text: string | number): string;

/**
 * Decodes text using decodeURIComponent, returns original text if decoding fails
 * @param text - String or number to decode (defaults to empty string)
 * @returns Decoded string
 */
function decode(text?: string | number): string;

Usage Examples:

import { encode, decode } from "ufo";

// Basic encoding
const encoded = encode("hello world");
// "hello%20world"

const special = encode("path/with special#chars");
// "path/with%20special%23chars"

// Safe decoding (won't throw on malformed input)
const decoded = decode("hello%20world");
// "hello world"

const malformed = decode("invalid%2");
// "invalid%2" (returns original on error)

Path Encoding & Decoding

Specialized encoding for URL path components with proper slash handling.

/**
 * Encodes characters for URL path section
 * @param text - String or number to encode for path
 * @returns Path-encoded string
 */
function encodePath(text: string | number): string;

/**
 * Decodes path section with consistent slash encoding handling
 * @param text - Path string to decode
 * @returns Decoded path string
 */
function decodePath(text: string): string;

/**
 * Encodes path parameters (includes slash encoding)
 * @param text - String or number to encode as path parameter
 * @returns Parameter-encoded string
 */
function encodeParam(text: string | number): string;

Usage Examples:

import { encodePath, decodePath, encodeParam } from "ufo";

// Path encoding preserves forward slashes
const path = encodePath("/api/users/user name");
// "/api/users/user%20name"

// Parameter encoding encodes slashes too
const param = encodeParam("user/name");
// "user%2Fname"

// Decode path components
const decoded = decodePath("/api/users%2Fprofile");
// "/api/users/profile"

Query Encoding & Decoding

Specialized encoding for query string components with proper space and plus handling.

/**
 * Encodes query values with proper space/plus handling
 * @param input - Query value to encode (various types supported)
 * @returns Query-encoded string
 */
function encodeQueryValue(input: QueryValue): string;

/**
 * Decodes query values with plus-to-space conversion
 * @param text - Query value string to decode
 * @returns Decoded query value
 */
function decodeQueryValue(text: string): string;

/**
 * Encodes query keys including equals sign encoding
 * @param text - Query key to encode
 * @returns Encoded query key
 */
function encodeQueryKey(text: string | number): string;

/**
 * Decodes query keys with plus-to-space conversion
 * @param text - Query key to decode
 * @returns Decoded query key
 */
function decodeQueryKey(text: string): string;

type QueryValue = string | number | undefined | null | boolean | Array<QueryValue> | Record<string, any>;

Usage Examples:

import { encodeQueryValue, decodeQueryValue, encodeQueryKey, decodeQueryKey } from "ufo";

// Query value encoding (spaces become +)
const value = encodeQueryValue("hello world");
// "hello+world"

const complex = encodeQueryValue({ key: "value with spaces" });
// "%7B%22key%22%3A%22value+with+spaces%22%7D"

// Query key encoding
const key = encodeQueryKey("search query");
// "search+query"

const keyWithEquals = encodeQueryKey("key=value");
// "key%3Dvalue"

// Decoding (+ becomes space)
const decodedValue = decodeQueryValue("hello+world");
// "hello world"

const decodedKey = decodeQueryKey("search+term");
// "search term"

Hash Encoding

Specialized encoding for URL hash/fragment sections.

/**
 * Encodes characters for URL hash section
 * @param text - String to encode for hash
 * @returns Hash-encoded string
 */
function encodeHash(text: string): string;

Usage Examples:

import { encodeHash } from "ufo";

const hash = encodeHash("section with spaces");
// "section%20with%20spaces"

const withSpecial = encodeHash("user{profile}^section");
// "user{profile}^section" (some chars preserved for readability)

Host Encoding

International domain name encoding using Punycode.

/**
 * Encodes hostname using Punycode for international domain names
 * @param name - Hostname to encode (defaults to empty string)
 * @returns ASCII-encoded hostname
 */
function encodeHost(name?: string): string;

Usage Examples:

import { encodeHost } from "ufo";

// International domain encoding
const international = encodeHost("пример.рф");
// "xn--e1afmkfd.xn--p1ai"

const mixed = encodeHost("bücher.example.com");
// "xn--bcher-kva.example.com"

// Regular domains pass through
const regular = encodeHost("example.com");
// "example.com"

// Email-style hostnames
const email = encodeHost("user@пример.рф");
// "user@xn--e1afmkfd.xn--p1ai"