bare-url

bare-url — WHATWG URL implementation for JavaScript. It is a native addon.

Mirrors the Node.js url module.

npm i bare-url

Usage

const { URL, URLSearchParams } = require('bare-url')

const url = new URL('https://example.com/path?foo=bar#hash')

console.log(url.hostname) // 'example.com'
console.log(url.pathname) // '/path'
console.log(url.searchParams.get('foo')) // 'bar'

To register URL and URLSearchParams as globals:

require('bare-url/global')

API

Constructing and parsing

new URL(input: string, base?: string | URL)

Parse input as a URL. If base is provided, input is resolved relative to base.

Parameters

Throws

• INVALID_URL — input is not a valid URL.

URL.parse(input: string, base?: string | URL): URL | null

Parse input as a URL without throwing.

Parameters

Returns URL | null — A URL instance if input parses successfully, or null on failure.

URL.canParse(input: string, base?: string | URL): boolean

Return true if input can be parsed as a valid URL, optionally relative to base.

Parameters

Components

href: string

The full serialized URL string. Setting this property reparses the URL.

protocol: string

The URL scheme followed by ':', e.g. 'https:'.

username: string

The username portion of the URL, or an empty string.

password: string

The password portion of the URL, or an empty string.

host: string

The hostname and port, e.g. 'example.com:8080'.

hostname: string

The hostname without the port.

port: string

The port as a string, or an empty string if not present.

pathname: string

The path portion of the URL.

search: string

The query string including the leading '?', or an empty string.

searchParams: URLSearchParams

A URLSearchParams object for the query string. Mutations to the params are reflected in the URL.

hash: string

The fragment including the leading '#', or an empty string.

Converting to string

URL.toString(): string

Returns the serialized string form.

URL.toJSON(): string

Returns the serialized string form. Suitable for JSON serialization.

File URL conversion

URL.fileURLToPath(url: URL | string): string

Convert a file: URL to a platform-specific file path. url may be a URL instance or a string.

Parameters

Throws

• INVALID_URL_SCHEME — the URL does not use the file: protocol.
• INVALID_FILE_URL_HOST — (non-Windows) the URL has a host other than empty or 'localhost'.
• INVALID_FILE_URL_PATH — the URL path contains an encoded path-separator or NUL character, or, on Windows, is not an absolute drive path.

URL.pathToFileURL(pathname: string): URL

Convert a platform-specific file path to a file: URL.

Parameters

Type checks

URL.isURL(value: unknown): value is URL

Return true if value is a URL instance.

Parameters

URL.isURLSearchParams(value: unknown): value is URLSearchParams

Return true if value is a URLSearchParams instance.

Parameters

Constructing search params

new URLSearchParams(init: string | Record<string, string> | Iterable<[string, string]>)

Create a new URLSearchParams instance. init may be a query string, an iterable of [name, value] pairs, or an object of key-value pairs.

Parameters

Reading and writing parameters

get(name: string): string | undefined

Return the first value for name, or null if not present.

Parameters

getAll(name: string): string[]

Return all values for name as an array.

Parameters

has(name: string, value?: string): boolean

Return true if a pair with name exists. If value is provided, the pair must also match value.

Parameters

append(name: string, value: string): void

Append a new name/value pair.

Parameters

set(name: string, value: string): void

Set the value for name, replacing any existing pairs with that name.

Parameters

delete(name: string, value?: string): void

Remove all pairs with name. If value is provided, only pairs with both the matching name and value are removed.

Parameters

size: number

The total number of search parameters.

Serializing search params

URLSearchParams.toString(): string

Returns the serialized string form.

URLSearchParams.toJSON(): string

Returns the serialized string form. Suitable for JSON serialization.

Search params type check

URLSearchParams.isURLSearchParams(value: unknown): value is URLSearchParams

Return true if value is a URLSearchParams instance.

Parameters

Errors

URLError

class URLError {
  code: string
  input: string
}

bare-url/global

Types

URLConstructor

type URLConstructor = typeof url.URL

URLSearchParamsConstructor

type URLSearchParamsConstructor = typeof url.URLSearchParams

See also

• bare-path — provides the platform-specific path handling used by fileURLToPath/pathToFileURL.
• Bare modules — the full bare-* catalog.
• Bare runtime API — the runtime these modules extend.