Class: 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

URI
↳ HTTPURI

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

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.

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

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.

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

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.

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

Name	Type	Description
`strings`	`TemplateStringsArray`	The template string array.
`...values`	`unknown`[]	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

Name	Type
`req`	`AuthSchemeRequest`
`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

Name	Type
`T`	extends `SelectorBase`

Parameters

Name	Type
`sels`	`undefined` \| `T`[]
`challenge?`	`WWWAuthenticate`

Returns

null | T

Inherited from

URI._getBestSelector

Defined in

uri/src/uri.ts:581

_guessContentType

▸ Protected _guessContentType(knownContentType?): undefined | ContentType

Parameters

Name	Type
`knownContentType?`	`string` \| `ContentType`

Returns

undefined | ContentType

Inherited from

URI._guessContentType

Defined in

uri/src/uri.ts:573

_makeIOError

▸ Protected _makeIOError(err): IOError

Parameters

Name	Type
`err`	`unknown`

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

Name	Type
`T`	extends `AuthSelector` \| `HeadersSelector` \| `ParamsSelector` \| `SessionSelector`

Parameters

Name	Type	Description
`selector`	`T`	The 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

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

Parameters

Name	Type	Description
`data`	`D`	The data to send.
`sendCT?`	`string` \| `ContentType`	Override the default data serializer.
`recvCT?`	`string` \| `ContentType`	Override 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

Name	Type
`T`	extends `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

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.

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

Name	Type	Description
`T`	extends `object`	The actual type returned.

Parameters

Name	Type	Description
`recvCT?`	`string` \| `ContentType`	Override 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

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

Parameters

Name	Type	Description
`data`	`D`	The patch data to send.
`sendCT?`	`string` \| `ContentType`	Override the default data serializer.
`recvCT?`	`string` \| `ContentType`	Override 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

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

Parameters

Name	Type	Description
`method`	`string`	The (case-sensitive) HTTP method to issue.
`headers?`	`null` \| `StringParams`	Custom headers to send, in addition to those specified via HeadersSelector.
`data?`	`D`	The data/payload to send.
`sendCT?`	`string` \| `ContentType`	Override the default data serializer.
`recvCT?`	`string` \| `ContentType`	Override 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

Name	Type	Description
`T`	extends `object`	The actual type returned.

Parameters

Name	Type	Description
`recvCT?`	`string` \| `ContentType`	Override 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

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

Name	Type	Description
`...args`	`unknown`[]	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

Name	Type	Description
`strings`	`TemplateStringsArray`	The template string array.
`...values`	`unknown`[]	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

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

Inherited from

URI.register

Defined in

uri/src/uri.ts:169

Hierarchy​

Constructors​

constructor​

Parameters​

Inherited from​

Defined in​

Parameters​

Inherited from​

Defined in​

Properties​

href​

Inherited from​

Defined in​

origin​

Inherited from​

Defined in​

protocol​

Inherited from​

Defined in​

selectors​

Type declaration​

Inherited from​

Defined in​

FIELDS​

Inherited from​

Defined in​

FINALIZE​

Inherited from​

Defined in​

HEADERS​

Inherited from​

Defined in​

NULL​

Inherited from​

Defined in​

STATUS​

Inherited from​

Defined in​

STATUS_TEXT​

Inherited from​

Defined in​

VOID​

Inherited from​

Defined in​

Methods​

$

Parameters​

Returns​

Inherited from​

Defined in​

[asyncIterator]​

Returns​

Inherited from​

Defined in​

_getAuthorization​

Parameters​

Returns​

Inherited from​

Defined in​

_getBestSelector​

Type parameters​

Parameters​

Returns​

Inherited from​

Defined in​

_guessContentType​

Parameters​

Returns​

Inherited from​

Defined in​

_makeIOError​

Parameters​

Returns​

Inherited from​

Defined in​

addSelector​

Type parameters​

Parameters​

Returns​

Inherited from​

Hierarchy

Constructors

constructor

Parameters

Inherited from

Defined in

Parameters

Inherited from

Defined in

Properties

href

Inherited from

Defined in

origin

Inherited from

Defined in

protocol

Inherited from

Defined in

selectors

Type declaration

Inherited from

Defined in

FIELDS

Inherited from

Defined in

FINALIZE

Inherited from

Defined in

HEADERS

Inherited from

Defined in

NULL

Inherited from

Defined in

STATUS

Inherited from

Defined in

STATUS_TEXT

Inherited from

Defined in

VOID

Inherited from

Defined in

Methods

Parameters

Returns

Inherited from

Defined in

[asyncIterator]

Returns

Inherited from

Defined in

_getAuthorization

Parameters

Returns

Inherited from

Defined in

_getBestSelector

Type parameters

Parameters

Returns

Inherited from

Defined in

_guessContentType

Parameters

Returns

Inherited from

Defined in

_makeIOError

Parameters

Returns

Inherited from

Defined in

addSelector

Type parameters

Parameters

Returns

Inherited from

Defined in