ufo

What is ufo?

The ufo npm package provides utilities for URL formatting and normalization. It helps in parsing, resolving, and normalizing URLs, as well as providing utilities for handling query parameters.

What are ufo's main functionalities?

Parsing and normalizing URLs

This feature allows you to normalize URLs, which includes removing the default port for HTTP and HTTPS, decoding unnecessary percent-encoded characters, and removing duplicate slashes.

const { normalizeURL } = require('ufo');
const normalizedUrl = normalizeURL('http://example.com:80/path/');

Handling query parameters

This feature enables you to easily add query parameters to a URL, which can be useful for constructing URLs with dynamic query strings.

const { withQuery } = require('ufo');
const urlWithQuery = withQuery('http://example.com', { query: 'value' });

Joining URLs

This feature is used to concatenate URL parts safely, ensuring that there are no duplicate slashes and that the query string is properly appended.

const { joinURL } = require('ufo');
const fullUrl = joinURL('http://example.com', '/path', '?query=value');

Other packages similar to ufo

url-parse

The url-parse package offers similar URL parsing and manipulation functionalities. It provides a more detailed breakdown of the URL components and can be used in both Node.js and browser environments, whereas ufo is more focused on URL normalization and handling.

qs

The qs package is used for parsing and stringifying query strings. It goes into more depth for handling nested objects within query strings compared to ufo's simpler query parameter utilities.

urijs

URI.js is a URL mutation library that offers comprehensive URL manipulation capabilities. It has a fluent API for building and altering URL components, which might be more intuitive for some developers compared to ufo's more functional approach.

README

👽 ufo

URL utils for humans.

Install

Install using npm or your favourite package manager:

npm i ufo

Import:

// CommonJS
const { normalizeURL, joinURL } = require('ufo')

// ESM
import { normalizeURL, joinURL } from 'ufo'

// Deno
import { parseURL } from 'https://unpkg.com/ufo/dist/index.mjs'

Notice: You may need to transpile package and add URL polyfill for legacy environments

Usage

normalizeURL

• Ensures URL is properly encoded
• Ensures pathname starts with slash
• Preserves protocol/host if provided

normalizeURL('test?query=123 123#hash, test')
// test?query=123%20123#hash,%20test

normalizeURL('http://localhost:3000')
// http://localhost:3000/

joinURL

joinURL('a', '/b', '/c')
// a/b/c

resolveURL

resolveURL('http://foo.com/foo?test=123#token', 'bar', 'baz')
// http://foo.com/foo/bar/baz?test=123#token

parseURL

parseURL('http://foo.com/foo?test=123#token')
// { protocol: 'http:', auth: '', host: 'foo.com', pathname: '/foo', search: '?test=123', hash: '#token' }

parseURL('foo.com/foo?test=123#token')
// { pathname: 'foo.com/foo', search: '?test=123', hash: '#token' }

parseURL('foo.com/foo?test=123#token', 'https://')
// { protocol: 'https:', auth: '', host: 'foo.com', pathname: '/foo', search: '?test=123', hash: '#token' }

stringifyParsedURL

const obj = parseURL('http://foo.com/foo?test=123#token')
obj.host = 'bar.com'

stringifyParsedURL(obj)
// http://bar.com/foo?test=123#token

withQuery

withQuery('/foo?page=a', { token: 'secret' })
// /foo?page=a&token=secret

getQuery

getQuery('http://foo.com/foo?test=123&unicode=%E5%A5%BD')
// { test: '123', unicode: '好' }

$URL

Implementing URL interface with improvements:

• Supporting schemeless and hostless URLs
• Supporting relative URLs
• Preserving trailing-slash status
• Decoded and mutable class properties (protocol, host, auth, pathname, query, hash)
• Consistent URL parser independent of environment
• Consistent encoding independent of environment
• Punycode support for host encoding

new $URL('http://localhost:3000/hello?world=true')
// { protocol: 'http:', host: 'localhost:3000', auth: '', pathname: '/hello', query: { world: 'true' }, hash: '' }

withTrailingSlash

Ensures url ends with a trailing slash.

withTrailingSlash('/foo')
// /foo/

Set the second option to true to support query parameters:

withTrailingSlash('/path?query=true', true)
// /path/?query=true

withoutTrailingSlash

Ensures url does not ends with a trailing slash.

withoutTrailingSlash('/foo/')
// /foo

Set the second option to true to support query parameters:

withoutTrailingSlash('/path/?query=true', true)
// /path?query=true

cleanDoubleSlashes

Ensures url does not have double slash (except for protocol).

cleanDoubleSlashes('//foo//bar//')
// /foo/bar/

cleanDoubleSlashes('http://example.com/analyze//http://localhost:3000//')
// http://example.com/analyze/http://localhost:3000/

isSamePath

Check two paths are equal or not. Trailing slash and encoding are normalized before comparation.

isSamePath('/foo', '/foo/')
// true

isRelative

Check if a path starts with ./ or ../.

isRelative('./foo')
// true

withHttp

Ensures url protocol is http

withHttp('https://example.com')
// http://example.com

withHttps

Ensures url protocol is https

withHttps('http://example.com')
// https://example.com

withProtocol

Changes url protocol passed as second argument

withProtocol('http://example.com', 'ftp://')
// ftp://example.com

withoutProtocol

Removes url protocol

withoutProtocol('http://example.com')
// example.com

isEqual

Compare two URLs regardless of their slash condition or encoding:

isEqual('/foo', 'foo')
// true
isEqual('foo/', 'foo')
// true
isEqual('/foo bar', '/foo%20bar')
// true

// Strict compare
isEqual('/foo', 'foo', { leadingSlash: true })
// false
isEqual('foo/', 'foo', { trailingSlash: true })
// false
isEqual('/foo bar', '/foo%20bar', { encoding: true })
// false

License

MIT

Special thanks to Eduardo San Martin Morote (posva) for encoding utlities

Changelog

v1.1.2

compare changes

🩹 Fixes

• Provide node16 style types field (#133)

📖 Documentation

• Add jsdocs for parse utils (#134)
• Add stringifyParsedURL (81e92b2)

🏡 Chore

• readme: Improvements (e38bdf6)
• Update lockfile (29fd478)

❤️ Contributors

• Pooya Parsa (@pi0)
• Nozomu Ikuta
• Sébastien Chopin [e-mail]
• Daniel Roe [e-mail]