👽 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

octoper / ufo