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.
👽 ufo
![JSDocs](https://img.shields.io/badge/jsDocs.io-reference-18181B?style=flat&colorA=18181B&colorB=F0DB4F)
URL utils for humans.
Install
Install using npm or your favourite package manager:
npm i ufo
Import:
const { normalizeURL, joinURL } = require('ufo')
import { normalizeURL, joinURL } from 'ufo'
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')
normalizeURL('http://localhost:3000')
joinURL
joinURL('a', '/b', '/c')
resolveURL
resolveURL('http://foo.com/foo?test=123#token', 'bar', 'baz')
parseURL
parseURL('http://foo.com/foo?test=123#token')
parseURL('foo.com/foo?test=123#token')
parseURL('foo.com/foo?test=123#token', 'https://')
stringifyParsedURL
const obj = parseURL('http://foo.com/foo?test=123#token')
obj.host = 'bar.com'
stringifyParsedURL(obj)
withQuery
withQuery('/foo?page=a', { token: 'secret' })
getQuery
getQuery('http://foo.com/foo?test=123&unicode=%E5%A5%BD')
$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')
withTrailingSlash
Ensures url ends with a trailing slash.
withTrailingSlash('/foo')
Set the second option to true
to support query parameters:
withTrailingSlash('/path?query=true', true)
withoutTrailingSlash
Ensures url does not ends with a trailing slash.
withoutTrailingSlash('/foo/')
Set the second option to true
to support query parameters:
withoutTrailingSlash('/path/?query=true', true)
cleanDoubleSlashes
Ensures url does not have double slash (except for protocol).
cleanDoubleSlashes('//foo//bar//')
cleanDoubleSlashes('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/')
isRelative
Check if a path starts with ./
or ../
.
isRelative('./foo')
withHttp
Ensures url protocol is http
withHttp('https://example.com')
withHttps
Ensures url protocol is https
withHttps('http://example.com')
withProtocol
Changes url protocol passed as second argument
withProtocol('http://example.com', 'ftp://')
withoutProtocol
Removes url protocol
withoutProtocol('http://example.com')
isEqual
Compare two URLs regardless of their slash condition or encoding:
isEqual('/foo', 'foo')
isEqual('foo/', 'foo')
isEqual('/foo bar', '/foo%20bar')
isEqual('/foo', 'foo', { leadingSlash: true })
isEqual('foo/', 'foo', { trailingSlash: true })
isEqual('/foo bar', '/foo%20bar', { encoding: true })
License
MIT
Special thanks to Eduardo San Martin Morote (posva) for encoding utlities