👽 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')
parseFilename
parseFilename('http://example.com/path/to/filename.ext')
parseFilename('/path/to/.hidden-file', { strict: true })
$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 comparison.
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 utilities