Skip to main content
Deno 2 is finally here πŸŽ‰οΈ
Learn more

npm version npm downloads Github Actions Codecov bundle

πŸ‘½ ufo

Install

Install using npm or yarn:

npm i ufo
# or
yarn add 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
// Result: test?query=123%20123#hash,%20test
normalizeURL('test?query=123 123#hash, test')

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

joinURL

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

resolveURL

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

parseURL

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

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

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

withQuery

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

getQuery

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

$URL

Implementing URL interface with some improvements:

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

withTrailingSlash

Ensures url ends with a trailing slash

// Result: /foo/
withTrailingSlash('/foo')
// Result: /path/?query=true
withTrailingSlash('/path?query=true', true)

withoutTrailingSlash

Ensures url does not ends with a trailing slash

// Result: /foo
withoutTrailingSlash('/foo/')
// Result: /path?query=true
withoutTrailingSlash('/path/?query=true', true)

cleanDoubleSlashes

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

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

isSamePath

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

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

isRelative

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

// Result: true
isRelative('./foo')

withHttp

Ensures url protocol is http

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

withHttps

Ensures url protocol is https

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

withProtocol

Changes url protocol passed as second argument

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

withoutProtocol

Removes url protocol

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

License

MIT

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