Class: URI

@divine/uri.URI

The mother of all URI classes.

Literally: This is the base class for all URI subclasses, which are the classes that actually implement a specific URI protocol.

Figuratively: This class defines a basic API that operates on any resource that can be described by or referenced with an URI. It integrates pluggable parsers and serializers, encoders and decoders and authentication methods to load, save, modify, delete any resource in any format, using any transport/transfer encoding and any authentication protocol.

The URI class naturally handles all kinds of URLs, like file: and http:, but also some — perhaps no so obvious — non-URL URIs like database connections for many common SQL databases.

Below is a list of all known URI/protocol handlers:

URI scheme/protocol	URI class
cache:	CacheURI
file:	FileURI
http:	HTTPURI
https:	HTTPURI
jdbc:	JDBCURI
mariadb:	MySQLURI
mysql:	MySQLURI
pg:	PostgresURI
postgres:	PostgresURI
postgresql:	PostgresURI
sqlite:	SQLiteURI
sqlserver:	TDSURI
tds:	TDSURI

Hierarchy

• URL

  ↳ URI

  ↳↳ CacheURI

  ↳↳ DatabaseURI

  ↳↳ FileURI

  ↳↳ HTTPURI

Implements

• AsyncIterable<Buffer>

Constructors

constructor

• new URI(url?, params?)

Constructs a new URI subclass. The URI constructor is a bit unusual, as it will always return an URI subclass and never a plain URI object.

If the URI contains user information (credentials), it will be added as an AuthSelector and removed from the URI.

Parameters

Name	Type	Description
url?	string | URL | Url	The URL to construct. If relative, it will be resolved as a file: URL relative to the current working directory. If url is a string and params is provided, the string may contain {prop} placeholders, which will then be resolved and percent-encoded against properties in params.
params?	Params	An optional record with parameters, used in case url is a string.

Overrides

URL.constructor

Defined in

uri/src/uri.ts:232

• new URI(url?, base?, params?)

Constructs a new URI subclass. The URI constructor is a bit unusual, as it will always return an URI subclass and never a plain URI object.

If the URI contains user information (credentials), it will be added as an AuthSelector and removed from the URI.

NOTE: If base is an URI, all its selectors will be inherited by the newly constructed URI.

Parameters

Name	Type	Description
url?	string | URL | Url	The URL to construct. If relative, it will be resolved against base. If url is a string and params are provided, the string may contain {prop} placeholders, which will then be resolved and percent-encoded against properties in params.
base?	string | URL | Url	A base URL that url will be resolved relative to, in case url is relative. If base itself is relative, base will first be resolved as a file: URL relative to the current working directory. Just like url, if base is a string and params is provided, {prop} placeholders may be present in the string.
params?	Params	An optional record with parameters, used in case url and/or base is a string.

Overrides

URL.constructor

Defined in

uri/src/uri.ts:251

Properties

href

• Readonly href: string

This URI's string representation. Unlike in URL, this property may not be changed/updated.

Overrides

URL.href

Defined in

uri/src/uri.ts:211

---

origin

• Readonly origin: string

This URI's origin. Unlike in URL, this property may not be changed/updated.

Overrides

URL.origin

Defined in

uri/src/uri.ts:214

---

protocol

• Readonly protocol: string

This URI's protocol. Unlike in URL, this property may not be changed/updated.

Overrides

URL.protocol

Defined in

uri/src/uri.ts:217

---

selectors

• selectors: Object

All selectors that may apply to this URI. Use addSelector to modify this property.

Type declaration

Name	Type	Description
auth?	AuthSelector[]	Authentication/Credentials selectors. See AuthSelector.
headers?	HeadersSelector[]	Headers selectors. See HeadersSelector.
params?	ParamsSelector[]	Parameter selectos. See ParamsSelector.
session?	SessionSelector[]	Session selectors. Only used internally.

Defined in

uri/src/uri.ts:196

---

FIELDS

▪ Static Readonly FIELDS: symbol = FIELDS

An alias for FIELDS.

Defined in

uri/src/uri.ts:148

---

FINALIZE

▪ Static Readonly FINALIZE: symbol = FINALIZE

An alias for FIELDS.

Defined in

uri/src/uri.ts:151

---

HEADERS

▪ Static Readonly HEADERS: symbol = HEADERS

An alias for HEADERS.

Defined in

uri/src/uri.ts:154

---

NULL

▪ Static Readonly NULL: symbol = NULL

An alias for NULL.

Defined in

uri/src/uri.ts:145

---

STATUS

▪ Static Readonly STATUS: symbol = STATUS

An alias for STATUS.

Defined in

uri/src/uri.ts:157

---

STATUS_TEXT

▪ Static Readonly STATUS_TEXT: symbol = STATUS_TEXT

An alias for STATUS_TEXT.

Defined in

uri/src/uri.ts:160

---

VOID

▪ Static Readonly VOID: symbol = VOID

An alias for VOID.

Defined in

uri/src/uri.ts:142

Methods

$

▸ $(strings, ...values): URI

Constructs a new URI, relative to this URI, from a template string, percent-encoding all arguments.

Example:

const base = new URI('http://api.example.com/v1/');
const info = await base.$`items/${item}/info`.load();

Parameters

Name	Type	Description
strings	TemplateStringsArray	The template string array.
...values	unknown[]	The values to be encoded.

Returns

URI

A new URI subclass instance.

Defined in

uri/src/uri.ts:289

---

[asyncIterator]

▸ [asyncIterator](): AsyncIterator<Buffer, any, undefined> & Metadata

All URIs are AsyncIterable<Buffer>. This method implements that interface by calling load(stream).

Returns

AsyncIterator<Buffer, any, undefined> & Metadata

An AsyncIterator<Buffer> stream.

Implementation of

AsyncIterable.[asyncIterator]

Defined in

uri/src/uri.ts:535

---

_getAuthorization

▸ Protected _getAuthorization(req, payload?, challenges?): Promise<undefined | Authorization>

Parameters

Name	Type
req	AuthSchemeRequest
payload?	Buffer | AsyncIterable<Buffer>
challenges?	WWWAuthenticate[]

Returns

Promise<undefined | Authorization>

Defined in

uri/src/uri.ts:539

---

_getBestSelector

▸ Protected _getBestSelector<T>(sels, challenge?): null | T

Type parameters

Name	Type
T	extends SelectorBase

Parameters

Name	Type
sels	undefined | T[]
challenge?	WWWAuthenticate

Returns

null | T

Defined in

uri/src/uri.ts:581

---

_guessContentType

▸ Protected _guessContentType(knownContentType?): undefined | ContentType

Parameters

Name	Type
knownContentType?	string | ContentType

Returns

undefined | ContentType

Defined in

uri/src/uri.ts:573

---

_makeIOError

▸ Protected _makeIOError(err): IOError

Parameters

Name	Type
err	unknown

Returns

IOError

Defined in

uri/src/uri.ts:577

---

addSelector

▸ addSelector<T>(selector): URI

Adds a new selector to this URI.

Selectors is a way to specify in what situations some kind of parameters or configuration is valid. When some kind of configuration is required (such as authentication of connection parameters), all registered selectors are evaluated and based on the matching score, the best selector is chosen. The more specific a selector is, the higher the score it will receive if it matches.

Based on this, it's possible to limit the scope of credentials or to configure certain HTTP headers to be sent to a specific set of servers.

It's also perfectly valid not to specify a selector for some kind of parameters. As long as there is only one kind of this configuration, it will apply unconditionally.

Throws

TypeError If the selector to add is invalid.

Type parameters

Name	Type
T	extends AuthSelector | HeadersSelector | ParamsSelector | SessionSelector

Parameters

Name	Type	Description
selector	T	The selector to add.

Returns

URI

This URI.

Defined in

uri/src/uri.ts:311

---

append

▸ append<T, D>(data, sendCT?, recvCT?): Promise<T & Metadata>

Serializes and appends/adds data to the resource this URI references, if the subclass supports it.

The actual operation depends on what kind of URI this is. See append or append for two common examples.

See parse for details about the returned object (never a primitive). You may always set recvCT to ContentType.bytes to receive a Node.js Buffer and ContentType.stream for an AsyncIterable<Buffer> stream, if you prefer raw data.

Throws

IOError On I/O errors or if the subclass does not support this method.

Throws

ParserError If the media type is unsupported or the parser fails to parse the response.

Type parameters

Name	Type	Description
T	extends object	The actual type returned.
D	unknown	The type of data to append.

Parameters

Name	Type	Description
data	D	The data to append.
sendCT?	string | ContentType	Override the default data serializer.
recvCT?	string | ContentType	Override the default response parser.

Returns

Promise<T & Metadata>

If the operation produced a result, it will be parsed as recvCT into an object, including MetaData.

Defined in

uri/src/uri.ts:435

---

close

▸ close(): Promise<void>

Closes this URI and frees any temporary resources in use.

URIs are usually stateless, but some protocols may use a connection pool, and this method can be used to shut down the pool and all remaining connections that may otherwise prevent the process from exiting.

Returns

Promise<void>

Defined in

uri/src/uri.ts:525

---

info

▸ info<T>(): Promise<T & Metadata>

This method will return information about the resource this URI references, if the subclass supports it.

The actual operation depends on what kind of URI this is. See info or info for two common examples.

Throws

IOError On I/O errors or if the subclass does not support this method.

Type parameters

Name	Type	Description
T	extends DirectoryEntry	The actual type of information record returned. Must extend DirectoryEntry.

Returns

Promise<T & Metadata>

An information record describing the resources.

Defined in

uri/src/uri.ts:351

---

list

▸ list<T>(): Promise<T[] & Metadata>

This method will return information about this URI's children/subresources, if the subclass supports it.

The actual operation depends on what kind of URI this is. See info for a common example.

Throws

IOError On I/O errors or if the subclass does not support this method.

Type parameters

Name	Type	Description
T	extends DirectoryEntry	The actual type of information record returned. Must extend DirectoryEntry.

Returns

Promise<T[] & Metadata>

An array of information record describing the subresources.

Defined in

uri/src/uri.ts:364

---

load

▸ load<T>(recvCT?): Promise<T & Metadata>

Loads and parses the resource this URI references, if the subclass supports it.

The actual operation depends on what kind of URI this is. See load or load for two common examples.

See parse for details about the returned object (never a primitive). You may always set recvCT to ContentType.bytes to receive a Node.js Buffer and ContentType.stream for an AsyncIterable<Buffer> stream, if you prefer raw data.

Throws

IOError On I/O errors or if the subclass does not support this method.

Throws

ParserError If the media type is unsupported or the parser fails to parse the resource.

Type parameters

Name	Type	Description
T	extends object	The actual type returned.

Parameters

Name	Type	Description
recvCT?	string | ContentType	Override the default response parser.

Returns

Promise<T & Metadata>

The remote resource parsed as recvCT into an object, including MetaData.

Defined in

uri/src/uri.ts:385

---

modify

▸ modify<T, D>(data, sendCT?, recvCT?): Promise<T & Metadata>

Modifies/patches data the resource this URI references, if the subclass supports it.

The actual operation depends on what kind of URI this is. See modify or modify for two common examples.

See parse for details about the returned object (never a primitive). You may always set recvCT to ContentType.bytes to receive a Node.js Buffer and ContentType.stream for an AsyncIterable<Buffer> stream, if you prefer raw data.

Throws

IOError On I/O errors or if the subclass does not support this method.

Throws

ParserError If the media type is unsupported or the parser fails to parse the response.

Type parameters

Name	Type	Description
T	extends object	The actual type returned.
D	unknown	The type of patch data to apply.

Parameters

Name	Type	Description
data	D	The patch data to apply.
sendCT?	string | ContentType	Override the default data serializer.
recvCT?	string | ContentType	Override the default response parser.

Returns

Promise<T & Metadata>

If the operation produced a result, it will be parsed as recvCT into an object, including MetaData.

Defined in

uri/src/uri.ts:460

---

query

▸ query<T>(...args): Promise<T & Metadata>

A generic method that sends/applies some kind of query to the resource and returns a response.

The actual operation depends on what kind of URI this is. See query or query for two common examples.

Throws

IOError On I/O errors or if the subclass does not support this method.

Throws

ParserError If the media type is unsupported or the parser fails to parse the response.

Type parameters

Name	Type	Description
T	extends object	The actual type returned.

Parameters

Name	Type	Description
...args	unknown[]	Depends on the subclass.

Returns

Promise<T & Metadata>

If the operation produced a result, it will returned together with MetaData.

Defined in

uri/src/uri.ts:499

---

remove

▸ remove<T>(_recvCT?): Promise<T & Metadata>

Removes the resource this URI references, if the subclass supports it.

The actual operation depends on what kind of URI this is. See remove or remove for two common examples.

See parse for details about the returned object (never a primitive). You may always set recvCT to ContentType.bytes to receive a Node.js Buffer and ContentType.stream for an AsyncIterable<Buffer> stream, if you prefer raw data.

Throws

IOError On I/O errors or if the subclass does not support this method.

Throws

ParserError If the media type is unsupported or the parser fails to parse the response.

Type parameters

Name	Type	Description
T	extends object	The actual type returned.

Parameters

Name	Type
_recvCT?	string | ContentType

Returns

Promise<T & Metadata>

If the operation produced a result, it will be parsed as recvCT into an object, including MetaData.

Defined in

uri/src/uri.ts:482

---

save

▸ save<T, D>(data, sendCT?, recvCT?): Promise<T & Metadata>

Serializes and stores data to the resource this URI references, if the subclass supports it.

The actual operation depends on what kind of URI this is. See save or save for two common examples.

See parse for details about the returned object (never a primitive). You may always set recvCT to ContentType.bytes to receive a Node.js Buffer and ContentType.stream for an AsyncIterable<Buffer> stream, if you prefer raw data.

Throws

IOError On I/O errors or if the subclass does not support this method.

Throws

ParserError If the media type is unsupported or the parser fails to parse the response.

Type parameters

Name	Type	Description
T	extends object	The actual type returned.
D	unknown	The type of data to store.

Parameters

Name	Type	Description
data	D	The data to store.
sendCT?	string | ContentType	Override the default data serializer.
recvCT?	string | ContentType	Override the default response parser.

Returns

Promise<T & Metadata>

If the operation produced a result, it will be parsed as recvCT into an object, including MetaData.

Defined in

uri/src/uri.ts:410

---

watch

▸ watch(...args): AsyncIterable<object & Metadata>

Watches a resource for changes and returns a stream of subclass-specific events, if the subclass supports it.

The actual operation depends on what kind of URI this is. See watch or watch for two common examples.

Throws

IOError On I/O errors or if the subclass does not support this method.

Throws

ParserError If the media type is unsupported or the parser fails to parse the response.

Parameters

Name	Type	Description
...args	unknown[]	Depends on the subclass.

Returns

AsyncIterable<object & Metadata>

A stream of change events together with MetaData.

Defined in

uri/src/uri.ts:515

---

$

▸ Static $(strings, ...values): URI

Creates a new URI from a template string, percent-encoding all arguments.

Example:

const href = URI.$`http://${host}/blobs/${blob}?as=${ct}

Parameters

Name	Type	Description
strings	TemplateStringsArray	The template string array.
...values	unknown[]	The values to be encoded.

Returns

URI

A new URI subclass instance.

Defined in

uri/src/uri.ts:187

---

register

▸ Static register(protocol, uri): typeof URI

Registers a new URI protocol. All subclasses must register their URL protocol support with this method.

Parameters

Name	Type	Description
protocol	string	The URL protocol to register. Must include the trailing colon.
uri	typeof URI	The URI subclass.

Returns

typeof URI

The URI baseclass (for chaining).

Defined in

uri/src/uri.ts:169