Skip to main content

Class: HTTPURI

@divine/uri.HTTPURI

The http: and https: protocol handler is used to access web services.

Redirects are handled automatically. To configure the handler, add an HTTPParamsSelector with addSelector. You can also provide authentication with an AuthSelector and add custom headers with a HeadersSelector.

Hierarchy

Constructors

constructor

new HTTPURI(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

NameTypeDescription
url?string | URL | UrlThe 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?ParamsAn optional record with parameters, used in case url is a string.

Inherited from

URI.constructor

Defined in

uri/src/uri.ts:232

new HTTPURI(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

NameTypeDescription
url?string | URL | UrlThe 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 | UrlA 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?ParamsAn optional record with parameters, used in case url and/or base is a string.

Inherited from

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

Inherited from

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

Inherited from

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

Inherited from

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

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

Inherited from

URI.selectors

Defined in

uri/src/uri.ts:196


FIELDS

Static Readonly FIELDS: symbol = FIELDS

An alias for FIELDS.

Inherited from

URI.FIELDS

Defined in

uri/src/uri.ts:148


FINALIZE

Static Readonly FINALIZE: symbol = FINALIZE

An alias for FIELDS.

Inherited from

URI.FINALIZE

Defined in

uri/src/uri.ts:151


HEADERS

Static Readonly HEADERS: symbol = HEADERS

An alias for HEADERS.

Inherited from

URI.HEADERS

Defined in

uri/src/uri.ts:154


NULL

Static Readonly NULL: symbol = NULL

An alias for NULL.

Inherited from

URI.NULL

Defined in

uri/src/uri.ts:145


STATUS

Static Readonly STATUS: symbol = STATUS

An alias for STATUS.

Inherited from

URI.STATUS

Defined in

uri/src/uri.ts:157


STATUS_TEXT

Static Readonly STATUS_TEXT: symbol = STATUS_TEXT

An alias for STATUS_TEXT.

Inherited from

URI.STATUS_TEXT

Defined in

uri/src/uri.ts:160


VOID

Static Readonly VOID: symbol = VOID

An alias for VOID.

Inherited from

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

NameTypeDescription
stringsTemplateStringsArrayThe template string array.
...valuesunknown[]The values to be encoded.

Returns

URI

A new URI subclass instance.

Inherited from

URI.$

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.

Inherited from

URI.[asyncIterator]

Defined in

uri/src/uri.ts:535


_getAuthorization

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

Parameters

NameType
reqAuthSchemeRequest
payload?Buffer | AsyncIterable<Buffer>
challenges?WWWAuthenticate[]

Returns

Promise<undefined | Authorization>

Inherited from

URI._getAuthorization

Defined in

uri/src/uri.ts:539


_getBestSelector

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

Type parameters

NameType
Textends SelectorBase

Parameters

NameType
selsundefined | T[]
challenge?WWWAuthenticate

Returns

null | T

Inherited from

URI._getBestSelector

Defined in

uri/src/uri.ts:581


_guessContentType

Protected _guessContentType(knownContentType?): undefined | ContentType

Parameters

NameType
knownContentType?string | ContentType

Returns

undefined | ContentType

Inherited from

URI._guessContentType

Defined in

uri/src/uri.ts:573


_makeIOError

Protected _makeIOError(err): IOError

Parameters

NameType
errunknown

Returns

IOError

Inherited from

URI._makeIOError

Defined in

uri/src/uri.ts:577


addSelector

addSelector<T>(selector): HTTPURI

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

NameType
Textends AuthSelector | HeadersSelector | ParamsSelector | SessionSelector

Parameters

NameTypeDescription
selectorTThe selector to add.

Returns

HTTPURI

This URI.

Inherited from

URI.addSelector

Defined in

uri/src/uri.ts:311


append

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

Issues a POST request with a serialized payload and parses the result.

Throws

IOError On I/O errors or if this the HTTP response status is outside the 200-299 range.

Throws

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

Type parameters

NameTypeDescription
Textends objectThe actual type returned.
DunknownThe type of data to send.

Parameters

NameTypeDescription
dataDThe data to send.
sendCT?string | ContentTypeOverride the default data serializer.
recvCT?string | ContentTypeOverride the default response parser. Defaults to the content-type response header.

Returns

Promise<T>

The HTTP response parsed as recvCT into an object, including MetaData.

Overrides

URI.append

Defined in

uri/src/protocols/http.ts:117


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>

Inherited from

URI.close

Defined in

uri/src/uri.ts:525


info

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

Issues a HEAD request and constructs a DirectoryEntry from the result.

Throws

IOError On I/O errors or if this the HTTP response status is outside the 200-299 range.

Type parameters

NameType
Textends DirectoryEntry

Returns

Promise<T & Metadata>

Information about this HTTP resource, including MetaData.

Overrides

URI.info

Defined in

uri/src/protocols/http.ts:55


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

NameTypeDescription
Textends DirectoryEntryThe actual type of information record returned. Must extend DirectoryEntry.

Returns

Promise<T[] & Metadata>

An array of information record describing the subresources.

Inherited from

URI.list

Defined in

uri/src/uri.ts:364


load

load<T>(recvCT?): Promise<T>

Issues a GET request and parses the result.

Throws

IOError On I/O errors or if this the HTTP response status is outside the 200-299 range.

Throws

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

Type parameters

NameTypeDescription
Textends objectThe actual type returned.

Parameters

NameTypeDescription
recvCT?string | ContentTypeOverride the default response parser. Defaults to the content-type response header.

Returns

Promise<T>

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

Overrides

URI.load

Defined in

uri/src/protocols/http.ts:83


modify

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

Issues a PATCH request with a serialized payload and parses the result.

Throws

IOError On I/O errors or if this the HTTP response status is outside the 200-299 range.

Throws

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

Type parameters

NameTypeDescription
Textends objectThe actual type returned.
DunknownThe type of the patch data.

Parameters

NameTypeDescription
dataDThe patch data to send.
sendCT?string | ContentTypeOverride the default data serializer.
recvCT?string | ContentTypeOverride the default response parser. Defaults to the content-type response header.

Returns

Promise<T>

The HTTP response parsed as recvCT into an object, including MetaData.

Overrides

URI.modify

Defined in

uri/src/protocols/http.ts:134


query

query<T, D>(method, headers?, data?, sendCT?, recvCT?): Promise<T>

Issues a custom HTTP request, optionally with a serialized payload, and parses the result.

Throws

IOError On I/O errors or if this the HTTP response status is outside the 200-299 range.

Throws

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

Type parameters

NameTypeDescription
Textends objectThe actual type returned.
DunknownThe type of the patch data.

Parameters

NameTypeDescription
methodstringThe (case-sensitive) HTTP method to issue.
headers?null | StringParamsCustom headers to send, in addition to those specified via HeadersSelector.
data?DThe data/payload to send.
sendCT?string | ContentTypeOverride the default data serializer.
recvCT?string | ContentTypeOverride the default response parser. Defaults to the content-type response header.

Returns

Promise<T>

The HTTP response parsed as recvCT into an object, including MetaData.

Overrides

URI.query

Defined in

uri/src/protocols/http.ts:166


remove

remove<T>(recvCT?): Promise<T>

Issues a DELETE request and parses the result.

Throws

IOError On I/O errors or if this the HTTP response status is outside the 200-299 range.

Throws

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

Type parameters

NameTypeDescription
Textends objectThe actual type returned.

Parameters

NameTypeDescription
recvCT?string | ContentTypeOverride the default response parser. Defaults to the content-type response header.

Returns

Promise<T>

The HTTP response parsed as recvCT into an object, including MetaData.

Overrides

URI.remove

Defined in

uri/src/protocols/http.ts:147


save

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

Issues a PUT request with a serialized payload and parses the result.

Throws

IOError On I/O errors or if this the HTTP response status is outside the 200-299 range.

Throws

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

Type parameters

NameTypeDescription
Textends objectThe actual type returned.
DunknownThe type of data to store.

Parameters

NameTypeDescription
dataDThe data to store.
sendCT?string | ContentTypeOverride the default data serializer.
recvCT?string | ContentTypeOverride the default response parser. Defaults to the content-type response header.

Returns

Promise<T>

The HTTP response parsed as recvCT into an object, including MetaData.

Overrides

URI.save

Defined in

uri/src/protocols/http.ts:100


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

NameTypeDescription
...argsunknown[]Depends on the subclass.

Returns

AsyncIterable<object & Metadata>

A stream of change events together with MetaData.

Inherited from

URI.watch

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

NameTypeDescription
stringsTemplateStringsArrayThe template string array.
...valuesunknown[]The values to be encoded.

Returns

URI

A new URI subclass instance.

Inherited from

URI.$

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

NameTypeDescription
protocolstringThe URL protocol to register. Must include the trailing colon.
uritypeof URIThe URI subclass.

Returns

typeof URI

The URI baseclass (for chaining).

Inherited from

URI.register

Defined in

uri/src/uri.ts:169