or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

encoding.mdindex.mdparsing.mdquery.mdurl-class.mdutilities.md
tile.json

tessl/npm-ufo

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/ufo@1.6.x

To install, run

npx @tessl/cli install tessl/npm-ufo@1.6.0

index.mddocs/

UFO

UFO is a comprehensive URL utility library for JavaScript and TypeScript that provides over 40 utility functions for parsing, manipulating, encoding, and normalizing URLs and their components. It features zero dependencies, full TypeScript support, and cross-platform compatibility for both browser and Node.js environments.

Package Information

  • Package Name: ufo
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install ufo

Core Imports

import { parseURL, joinURL, normalizeURL, withQuery } from "ufo";

For CommonJS:

const { parseURL, joinURL, normalizeURL, withQuery } = require("ufo");

For specific functionality:

// URL parsing
import { parseURL, parsePath, parseQuery } from "ufo";
// Encoding/decoding
import { encode, decode, encodePath, decodePath } from "ufo";
// URL manipulation
import { joinURL, withBase, withQuery, normalizeURL } from "ufo";

Basic Usage

import { parseURL, joinURL, withQuery, normalizeURL } from "ufo";

// Parse URLs into components
const parsed = parseURL("https://example.com/path?foo=bar#section");
// { protocol: 'https:', host: 'example.com', pathname: '/path', search: '?foo=bar', hash: '#section' }

// Join URL segments
const fullUrl = joinURL("https://api.example.com", "v1", "users", "123");
// "https://api.example.com/v1/users/123"

// Add query parameters
const urlWithQuery = withQuery("/search", { q: "javascript", page: 2 });
// "/search?q=javascript&page=2"

// Normalize URLs for consistency
const normalized = normalizeURL("//example.com//path//to//resource");
// "//example.com/path/to/resource"

Architecture

UFO is organized into several functional modules:

  • Parsing Engine: Core URL parsing with support for various URL formats and edge cases
  • Encoding System: Safe encoding/decoding for different URL components (path, query, hash, host)
  • Query Handler: Complete query string parsing with array support and type preservation
  • Path Utilities: Comprehensive path manipulation with relative path resolution
  • Protocol Management: Add, remove, or change URL protocols with validation
  • Cross-platform Support: Works consistently across browsers and Node.js environments

Capabilities

URL Parsing & Stringification

Complete URL parsing into structured components with support for various formats, protocols, and edge cases. Handles everything from simple paths to complex URLs with authentication and international domains.

function parseURL(input?: string, defaultProto?: string): ParsedURL;
function parsePath(input?: string): ParsedURL;
function parseAuth(input?: string): ParsedAuth;
function parseHost(input?: string): ParsedHost;
function stringifyParsedURL(parsed: Partial<ParsedURL>): string;
function parseFilename(input?: string, opts?: { strict?: boolean }): string | undefined;

URL Parsing & Stringification

URL Encoding & Decoding

Safe encoding and decoding functions for different URL components with proper handling of special characters, spaces, and international characters. Includes punycode support for international domain names.

function encode(text: string | number): string;
function decode(text?: string | number): string;
function encodePath(text: string | number): string;
function decodePath(text: string): string;
function encodeQueryValue(input: QueryValue): string;
function decodeQueryValue(text: string): string;
function encodeHost(name?: string): string;

URL Encoding & Decoding

Query String Handling

Comprehensive query string parsing and manipulation with support for arrays, nested objects, and complex data types. Includes protection against prototype pollution and flexible serialization options.

function parseQuery<T extends ParsedQuery = ParsedQuery>(parametersString?: string): T;
function stringifyQuery(query: QueryObject): string;
function encodeQueryItem(key: string, value: QueryValue | QueryValue[]): string;
function getQuery<T extends ParsedQuery = ParsedQuery>(input: string): T;

Query String Handling

URL Utilities

Extensive collection of utility functions for URL manipulation including path joining, protocol management, slash handling, base URL operations, and URL comparison with flexible options.

function joinURL(base: string, ...input: string[]): string;
function joinRelativeURL(...input: string[]): string;
function resolveURL(base?: string, ...inputs: string[]): string;
function normalizeURL(input: string): string;
function withBase(input: string, base: string): string;
function withQuery(input: string, query: QueryObject): string;
function hasProtocol(inputString: string, opts?: HasProtocolOptions): boolean;

URL Utilities

URL Class (Deprecated)

Legacy URL class implementation provided for backward compatibility. New projects should use native URL constructor or the functional parseURL API.

class $URL implements URL {
  constructor(input?: string);
  readonly hostname: string;
  readonly port: string;
  readonly hasProtocol: boolean;
  readonly isAbsolute: boolean;
  append(url: $URL): void;
  toString(): string;
}

function createURL(input: string): $URL;

URL Class (Deprecated)

Types

interface ParsedURL {
  protocol?: string;
  host?: string;
  auth?: string;
  href?: string;
  pathname: string;
  hash: string;
  search: string;
  [protocolRelative]?: boolean;
}

interface ParsedAuth {
  username: string;
  password: string;
}

interface ParsedHost {
  hostname: string;
  port: string;
}

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

interface HasProtocolOptions {
  acceptRelative?: boolean;
  strict?: boolean;
}

interface CompareURLOptions {
  trailingSlash?: boolean;
  leadingSlash?: boolean;
  encoding?: boolean;
}