tessl/npm-ufo

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

—

Pending

Overview

Eval results

Files

URL Class (Deprecated)

Name: tessl/npm-ufo
Author: tessl

Legacy URL class implementation provided for backward compatibility. This class is deprecated - new projects should use the native URL constructor or the functional parseURL API for better performance and standards compliance.

Capabilities

$URL Class

Object-oriented URL manipulation class with automatic parsing and property access.

/**
 * @deprecated Use native URL with `new URL(input)` or `ufo.parseURL(input)`
 */
class $URL implements URL {
  protocol: string;
  host: string;
  auth: string;
  pathname: string;
  query: QueryObject;
  hash: string;

  /**
   * Creates a new $URL instance from a URL string
   * @param input - URL string to parse (defaults to empty string)
   * @throws TypeError if input is not a string
   */
  constructor(input?: string);

  // Computed properties
  readonly hostname: string;
  readonly port: string;
  readonly username: string;
  readonly password: string;
  readonly hasProtocol: boolean;
  readonly isAbsolute: boolean;
  readonly search: string;
  readonly searchParams: URLSearchParams;
  readonly origin: string;
  readonly fullpath: string;
  readonly encodedAuth: string;
  readonly href: string;

  /**
   * Appends another $URL to this one
   * @param url - $URL instance to append
   * @throws Error if the URL to append has a protocol
   */
  append(url: $URL): void;

  /**
   * Returns the URL as a JSON string
   * @returns URL string
   */
  toJSON(): string;

  /**
   * Returns the URL as a string
   * @returns URL string
   */
  toString(): string;
}

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

Create URL Function

Factory function for creating $URL instances.

/**
 * @deprecated Use native URL with `new URL(input)` or `ufo.parseURL(input)`
 */
function createURL(input: string): $URL;

Usage Examples

⚠️ Warning: These examples show deprecated functionality. Use native URL or parseURL instead.

import { $URL, createURL } from "ufo";

// Creating URL instances (DEPRECATED)
const url = new $URL("https://user:pass@example.com:8080/path?foo=bar#section");

// Accessing properties
console.log(url.protocol);   // "https:"
console.log(url.hostname);   // "example.com"
console.log(url.port);       // "8080"
console.log(url.username);   // "user"
console.log(url.password);   // "pass"
console.log(url.pathname);   // "/path"
console.log(url.search);     // "?foo=bar"
console.log(url.hash);       // "#section"

// Query object access
console.log(url.query);      // { foo: "bar" }
url.query.newParam = "value";
console.log(url.search);     // "?foo=bar&newParam=value"

// Computed properties
console.log(url.origin);     // "https://example.com:8080"
console.log(url.href);       // "https://user:pass@example.com:8080/path?foo=bar&newParam=value#section"
console.log(url.isAbsolute); // true
console.log(url.hasProtocol);// true

// URL manipulation
const base = new $URL("https://api.example.com/v1/");
const path = new $URL("users/123?active=true");
base.append(path);
console.log(base.href); // "https://api.example.com/v1/users/123?active=true"

// Factory function (DEPRECATED)
const url2 = createURL("https://example.com/path");
console.log(url2.pathname); // "/path"

Modern Alternatives

Instead of using the deprecated $URL class, use these modern approaches:

Native URL (Recommended)

// Modern approach using native URL
const url = new URL("https://example.com/path?foo=bar#section");

console.log(url.protocol);   // "https:"
console.log(url.hostname);   // "example.com"
console.log(url.pathname);   // "/path"
console.log(url.search);     // "?foo=bar"
console.log(url.hash);       // "#section"

// Modify query parameters
url.searchParams.set("newParam", "value");
console.log(url.href); // "https://example.com/path?foo=bar&newParam=value#section"

UFO Functional API (Recommended)

import { parseURL, stringifyParsedURL, withQuery } from "ufo";

// Parse URL functionally
const parsed = parseURL("https://example.com/path?foo=bar#section");
console.log(parsed.protocol);  // "https:"
console.log(parsed.hostname);  // "example.com" (need to use parseHost)
console.log(parsed.pathname);  // "/path"

// Modify and reconstruct
const modified = {
  ...parsed,
  pathname: "/newpath"
};
const newUrl = stringifyParsedURL(modified);

// Add query parameters functionally
const withParams = withQuery("/path", { foo: "bar", newParam: "value" });
// "/path?foo=bar&newParam=value"

Migration Guide

From $URL to Native URL

// OLD (deprecated)
const oldUrl = new $URL("https://example.com/path?foo=bar");
oldUrl.query.newParam = "value";
const result = oldUrl.href;

// NEW (recommended)
const newUrl = new URL("https://example.com/path?foo=bar");
newUrl.searchParams.set("newParam", "value");
const result = newUrl.href;

From $URL to UFO Functional API

// OLD (deprecated)
const oldUrl = new $URL("https://example.com/path?foo=bar");
oldUrl.pathname = "/newpath";
const result = oldUrl.href;

// NEW (recommended)
import { parseURL, stringifyParsedURL } from "ufo";

const parsed = parseURL("https://example.com/path?foo=bar");
const modified = { ...parsed, pathname: "/newpath" };
const result = stringifyParsedURL(modified);

URL Joining Migration

// OLD (deprecated)
const base = new $URL("https://api.example.com/v1/");
const path = new $URL("users/123");
base.append(path);
const result = base.href;

// NEW (recommended)
import { joinURL } from "ufo";

const result = joinURL("https://api.example.com/v1/", "users/123");