tessl/npm-ufo

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

—

Pending

Overview

Eval results

Files

URL Parsing & Stringification

Name: tessl/npm-ufo
Author: tessl

Complete URL parsing functionality that breaks down URLs into structured components and reconstructs them back to strings. Handles various URL formats, protocols, and edge cases including special protocols, authentication, and international domains.

Capabilities

Parse URL

Parses a complete URL string into structured components.

/**
 * Takes a URL string and returns an object with the URL's components
 * @param input - The URL string to parse
 * @param defaultProto - Default protocol to use if input doesn't have one
 * @returns Parsed URL object with protocol, host, auth, pathname, search, hash
 */
function parseURL(input?: string, defaultProto?: string): ParsedURL;

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

Usage Examples:

import { parseURL } from "ufo";

// Parse complete URL
const parsed = parseURL("http://foo.com/foo?test=123#token");
// { protocol: 'http:', auth: '', host: 'foo.com', pathname: '/foo', search: '?test=123', hash: '#token' }

// Parse URL without protocol
const pathOnly = parseURL("foo.com/foo?test=123#token");
// { pathname: 'foo.com/foo', search: '?test=123', hash: '#token' }

// Parse with default protocol
const withDefault = parseURL("foo.com/foo?test=123#token", "https://");
// { protocol: 'https:', auth: '', host: 'foo.com', pathname: '/foo', search: '?test=123', hash: '#token' }

// Special protocols
const blob = parseURL("blob:data-content");
// { protocol: 'blob:', pathname: 'data-content', href: 'blob:data-content', auth: '', host: '', search: '', hash: '' }

Parse Path

Splits a path string into pathname, search, and hash components.

/**
 * Splits the input string into pathname, search, and hash parts
 * @param input - The path string to parse
 * @returns Object with pathname, search, and hash properties
 */
function parsePath(input?: string): ParsedURL;

Usage Examples:

import { parsePath } from "ufo";

const pathParts = parsePath("/users/123?active=true#profile");
// { pathname: '/users/123', search: '?active=true', hash: '#profile' }

const simple = parsePath("/api/data");
// { pathname: '/api/data', search: '', hash: '' }

Parse Authentication

Parses authentication string into username and password components.

/**
 * Parses a string of the form 'username:password' into components
 * @param input - Authentication string to parse
 * @returns Object with decoded username and password
 */
function parseAuth(input?: string): ParsedAuth;

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

Usage Examples:

import { parseAuth } from "ufo";

const auth = parseAuth("john:secret123");
// { username: 'john', password: 'secret123' }

const encoded = parseAuth("user%40domain:pass%20word");
// { username: 'user@domain', password: 'pass word' }

Parse Host

Extracts hostname and port from a host string.

/**
 * Parses a host string into hostname and port components
 * @param input - Host string to parse
 * @returns Object with decoded hostname and port
 */
function parseHost(input?: string): ParsedHost;

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

Usage Examples:

import { parseHost } from "ufo";

const host = parseHost("example.com:8080");
// { hostname: 'example.com', port: '8080' }

const hostOnly = parseHost("api.example.com");
// { hostname: 'api.example.com', port: undefined }

const encoded = parseHost("xn--e1afmkfd.xn--p1ai:3000");
// { hostname: 'пример.рф', port: '3000' }

Stringify Parsed URL

Converts a ParsedURL object back into a URL string.

/**
 * Takes a ParsedURL object and returns the stringified URL
 * @param parsed - Parsed URL object to stringify
 * @returns Complete URL string
 */
function stringifyParsedURL(parsed: Partial<ParsedURL>): string;

Usage Examples:

import { parseURL, stringifyParsedURL } from "ufo";

const parsed = parseURL("http://foo.com/foo?test=123#token");
parsed.host = "bar.com";
parsed.pathname = "/updated";

const newUrl = stringifyParsedURL(parsed);
// "http://bar.com/updated?test=123#token"

// Build URL from parts
const custom = stringifyParsedURL({
  protocol: "https:",
  host: "api.example.com",
  pathname: "/v1/users",
  search: "?limit=10",
  hash: "#results"
});
// "https://api.example.com/v1/users?limit=10#results"

Parse Filename

Extracts filename from URL path with optional strict mode.

/**
 * Parses a URL and returns last segment in path as filename
 * @param input - URL string to parse
 * @param opts - Options including strict mode for extension requirement
 * @returns Filename string or undefined if not found
 */
function parseFilename(input?: string, opts?: { strict?: boolean }): string | undefined;

Usage Examples:

import { parseFilename } from "ufo";

// Extract filename with extension
const filename = parseFilename("http://example.com/path/to/document.pdf");
// "document.pdf"

// Extract last segment (non-strict)
const segment = parseFilename("/api/users/profile");
// "profile"

// Strict mode requires extension
const strict = parseFilename("/path/to/.hidden-file", { strict: true });
// undefined

const strictValid = parseFilename("/path/to/image.jpg", { strict: true });
// "image.jpg"

Install with Tessl CLI