Net Namespace Reference

Description

The Net namespace contains static functions for working with network requests.

Functions
Promise	fetch (String url, object options={})
Promise	request (String url, object options={})

Function Documentation

fetch()

Promise fetch	(	String	url,
		object	options = {}
	)

The Net.fetch() method starts the process of fetching a resource from the network, returning a Promise object which is fulfilled once a result is available.

The fetch() method itself works the same as the standard (see, eg. MDN fetch() for details), as it is simply a wrapper around other API objects. The returned Promise is resolved on a successful request/response, or rejected on failure.

Specifically:

• In case of success (XMLHttpRequest.onload()), the promise is resolved with a Response object as the argument.
  • Note: the non-standard option rejectOnError can be set to true, in which case fetch() will reject the promise if the returned HTTP status code is not in the 200-299 range, in the same way as if a network error occurred (see below).
• In case of errors in options values or during configuration of the underlying XMLHttpRequest object the promise is rejected with TypeError or ReferenceError.
• In case of any network error (XMLHttpRequest.onerror()), or if rejectOnError was set to true and the result status was not in the 200-299 range, the promise is rejected with a DOMException type named NetworkError (legacy ID DOMException.NETWORK_ERR).
  The exception object has a custom property named response, which contains a Response object which holds whatever results could be retrieved, if any. If the request failed altogether (eg. server not found), the response.status will be 0.
• In case of a network timeout (XMLHttpRequest.ontimeout()) the promise is rejected with a DOMException type named TimeoutError (legacy ID DOMException.TIMEOUT_ERR). This exception object also has a custom property named response, as described above (it may contain some actual response, for example in case of a redirect where the new URL timed out, the original response data may be available).
  Note that the promise is rejected with the timeout exception first, before the general error rejection described above.
• In case the request was aborted (XMLHttpRequest.onabort()) the promise is rejected with a DOMException type named AbortError (legacy ID DOMException.ABORT_ERR). This exception object also has a custom property named response, as described above (it may contain some actual response, for example if the request was aborted after the headers were already loaded).
  Note that the promise is rejected with the abort exception first, before the general error rejection described above.

The few other differences of this implementation are in the Request and Response objects which are used to initialize the request and return the results, respectively. These are documented on their own pages.

The optional options argument passed to fetch() can, as in the standard, be either a basic object of option/value keys (eg. { method: "GET", timeout: 5000 }) or a Request object set up with the desired options. The available options are all the Request properties, which are documented there.

Basic example of sending an image to Touch Portal for use as an icon:

Net.fetch("https://mpaperno.github.io/DSEP4TP/images/logo/icon_64.png")
.then(response => response.base64())
.then((b64data) => {
    TP.stateUpdate(b64data);
})
.catch((e) => { console.error(e); })

See Fetch and Notify for a more complete example using JSON a data request.

request()

Response request	(	String	url,
		object	options = {}
	)

This is a fully synchronous version of Net.fetch().

Instead of returning a Promise, Net.request() returns a Request object type. The returned Request can then be used to invoke its methods which actually send the request: Request.get(), Request.head(), Request.post(), and Request.put(). These are all shorthand for the respective HTTP methods. See the linked documentation for details.

The optional options argument passed to request() can, as with fetch(), be either a basic object of option/value keys (eg. ‘{ timeout: 5000, redirect: 'error’ }) or aRequestobject set up with the desired options. The available options are all theRequest` properties, which are documented there.

Unless the Request.noThrow option is set to true, synchronous requests may throw one of the DOMException types mentioned in the fetch() documentation, or a TypeError or ReferenceError if invalid options are passed or an exception is caught during configuration of the underlying XMLHttpRequest object.

Here is a synchronous version of the fetch() example above:

try {
  const b64data = Net.request("https://mpaperno.github.io/DSEP4TP/images/logo/icon_64.png").get().base64();
  TP.stateUpdate(b64data);
}
catch (e) { console.error(e); }

If error trapping isn't important, the image data could be returned directly from a single-line expression.

Note

This method blocks until the request completes or the timeout specified in options expires. An AbortSignal may be passed in the options object's signal property in order to terminate the request from another process (eg. a timer).