bare-url

stable

bare-url — WHATWG URL implementation for JavaScript, built on liburl. 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 | URL, base?: string | URL)`

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

Parameters

Parameter	Type	Default	Description
`input`	`string` \| `URL`	—	The URL string to parse.
`base?`	`string` \| `URL`	—	A base URL that `input` is resolved relative to, if provided.

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

Parameter	Type	Default	Description
`input`	`string`	—	The URL string to parse.
`base?`	`string` \| `URL`	—	A base URL that `input` is resolved relative to, if provided.

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

Parameter	Type	Default	Description
`input`	`string`	—	The URL string to test.
`base?`	`string` \| `URL`	—	A base URL that `input` is resolved relative to, if provided.

Components

`href: string`

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

`protocol: string`

The URL scheme followed by ':', for example '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, for example 'example.com:8080'.

`port: string`

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

`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.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

Parameter	Type	Default	Description
`url`	`URL` \| `string`	—	The `file:` URL to convert, as a `URL` instance or a string.

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.

On Windows, a UNC path such as \\server\share\foo becomes file://server/share/foo. An extended-length path loses its \\?\ prefix: \\?\C:\foo\bar becomes file:///C:/foo/bar, and \\?\UNC\server\share\foo becomes file://server/share/foo. Only the upper-case \\?\UNC\ prefix marks a UNC path: \\?\unc\server\share\foo becomes file:///unc/server/share/foo. Added in v2.5.5: support for \\?\ paths, which threw INVALID_URL before, and the INVALID_ARG_VALUE error for a UNC path without a server name or a resource path, which before produced a file: URL with the wrong host or path.

Parameters

Parameter	Type	Default	Description
`pathname`	`string`	—	The platform-specific file path to convert.

Throws

INVALID_ARG_VALUE — (Windows) pathname is a UNC path with an empty server name, such as \\\share\foo, or with no resource path, such as \\server or \\?\UNC\server. An empty server name in the \\?\UNC\ form does not throw: \\?\UNC\\share gives file:///share.
INVALID_URL — pathname does not form a valid file: URL, for example a UNC server name that contains a space.

Type checks

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

Return true if value is a URL instance.

Parameters

Parameter	Type	Default	Description
`value`	`unknown`	—	The value to test.

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

Return true if value is a URLSearchParams instance.

Parameters

Parameter	Type	Default	Description
`value`	`unknown`	—	The value to test.

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

Parameter	Type	Default	Description
`init`	`string \| Record<string, string> \| Iterable<[string, string]>`	—	A query string, an iterable of `[name, value]` pairs, or an object of key-value pairs to initialize the params from.

Reading and writing parameters

`get(name: string): string | undefined`

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

Parameters

Parameter	Type	Default	Description
`name`	`string`	—	The parameter name to look up.

`getAll(name: string): string[]`

Return all values for name as an array.

Parameters

Parameter	Type	Default	Description
`name`	`string`	—	The parameter name to look up.

`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

Parameter	Type	Default	Description
`name`	`string`	—	The parameter name to check.
`value?`	`string`	—	If provided, the pair must also match this value.

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

Append a new name/value pair.

Parameters

Parameter	Type	Default	Description
`name`	`string`	—	The parameter name.
`value`	`string`	—	The parameter value.

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

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

Parameters

Parameter	Type	Default	Description
`name`	`string`	—	The parameter name.
`value`	`string`	—	The value to set.

`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

Parameter	Type	Default	Description
`name`	`string`	—	The parameter name to remove.
`value?`	`string`	—	If provided, only pairs also matching this value are removed.

`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

Parameter	Type	Default	Description
`value`	`unknown`	—	The value to test.

Errors

`URLError`

class URLError {
  cause: unknown
  code: string
  input: string
  message: string
  name: string
  stack: string
}

`bare-url/global`

Types

`URLConstructor`

type URLConstructor = typeof url.URL

`URLSearchParamsConstructor`

type URLSearchParamsConstructor = typeof url.URLSearchParams

Threat model

bare-url is one of the addons Bare compiles into its binary, so every Bare process has it, sealed or not, and it inherits Bare's threat model. The module's own threat model, added in v2.5.5, says where it sits in that one. It parses and serializes WHATWG URLs through liburl and does not fetch, resolve, or open anything, so holding a URL reaches nothing. The risk is in the parser, which runs C code over strings an attacker chose. The module system uses URLs to name things and to pick a protocol, so an input whose scheme, host, origin, or path differs from what the WHATWG URL Standard says matters more than the parse itself suggests.

bare-url

UsageCopy Anchor Link

APICopy Anchor Link

Constructing and parsingCopy Anchor Link

new URL(input: string | URL, base?: string | URL)Copy Anchor Link

URL.parse(input: string, base?: string | URL): URL | nullCopy Anchor Link

URL.canParse(input: string, base?: string | URL): booleanCopy Anchor Link

ComponentsCopy Anchor Link

href: stringCopy Anchor Link

protocol: stringCopy Anchor Link

username: stringCopy Anchor Link

password: stringCopy Anchor Link

host: stringCopy Anchor Link

hostname: stringCopy Anchor Link

port: stringCopy Anchor Link

pathname: stringCopy Anchor Link

search: stringCopy Anchor Link

searchParams: URLSearchParamsCopy Anchor Link

hash: stringCopy Anchor Link

Converting to stringCopy Anchor Link

URL.toString(): stringCopy Anchor Link

URL.toJSON(): stringCopy Anchor Link

File URL conversionCopy Anchor Link

URL.fileURLToPath(url: URL | string): stringCopy Anchor Link

URL.pathToFileURL(pathname: string): URLCopy Anchor Link

Type checksCopy Anchor Link

URL.isURL(value: unknown): value is URLCopy Anchor Link

URL.isURLSearchParams(value: unknown): value is URLSearchParamsCopy Anchor Link

Constructing search paramsCopy Anchor Link

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

Reading and writing parametersCopy Anchor Link

get(name: string): string | undefinedCopy Anchor Link

getAll(name: string): string[]Copy Anchor Link

has(name: string, value?: string): booleanCopy Anchor Link

append(name: string, value: string): voidCopy Anchor Link

set(name: string, value: string): voidCopy Anchor Link

delete(name: string, value?: string): voidCopy Anchor Link

size: numberCopy Anchor Link

Serializing search paramsCopy Anchor Link

URLSearchParams.toString(): stringCopy Anchor Link

URLSearchParams.toJSON(): stringCopy Anchor Link

Search params type checkCopy Anchor Link

URLSearchParams.isURLSearchParams(value: unknown): value is URLSearchParamsCopy Anchor Link

ErrorsCopy Anchor Link

URLErrorCopy Anchor Link

bare-url/globalCopy Anchor Link

TypesCopy Anchor Link

URLConstructorCopy Anchor Link

URLSearchParamsConstructorCopy Anchor Link

Threat modelCopy Anchor Link

See alsoCopy Anchor Link

On this page

Usage

API

Constructing and parsing

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

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

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

Components

`href: string`

`protocol: string`

`username: string`

`password: string`

`host: string`

`hostname: string`

`port: string`

`pathname: string`

`search: string`

`searchParams: URLSearchParams`

`hash: string`

Converting to string

`URL.toString(): string`

`URL.toJSON(): string`

File URL conversion

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

`URL.pathToFileURL(pathname: string): URL`

Type checks

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

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

Constructing search params

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

Reading and writing parameters

`get(name: string): string | undefined`

`getAll(name: string): string[]`

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

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

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

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

`size: number`

Serializing search params

`URLSearchParams.toString(): string`

`URLSearchParams.toJSON(): string`

Search params type check

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

Errors

`URLError`

`bare-url/global`

Types

`URLConstructor`

`URLSearchParamsConstructor`

Threat model

See also