CursedWordsTranslator.Request - AjaxGb/CursedWords GitHub Wiki

From scripts/translator.js

An abstraction of a request in process. It is similar to an ES6 Promise, but with more emphasis on the process than on the result. Unlike a Promise, a Request can emit progress events and be aborted by external code.

• Constructor
  • new Request(executor(resolve, reject, progress) -> cancel)
• Properties
  • state
• Methods
  • abort()
  • onprogress(callback(...info)) -> this
  • onsuccess(callback(...result)) -> this
  • onerror(callback(error, [...info])) -> this
  • onabort(callback()) -> this
  • onfinalize(callback()) -> this

Constructor

new Request(executor(resolve, reject, progress) -> cancel)

Parameters

• executor - The function that performs the actual request. It is passed functions it may call to end the request in success or failure, or to update listeners on the progress of the request. It should return a function that can be called to stop the request.

  • resolve(...result) - A function that can be called to end the request in success. Takes the result(s) of the request.
  • reject(error, [...info]) - A function that can be called to end the request in failure. Takes the error and any extra data regarding the failure.
  • progress(...info) - A function that can be called to send progress updates to listeners. Takes any arbitrary arguments to send to any listeners.
  • Return value - A function that can be called to cancel any ongoing processes associated with the request. Optional.

Properties

state

The current state of the request. Can be one of Request.RUNNING, Request.SUCCESS, Request.ERROR, or Request.ABORTED.

Methods

abort()

Ends the request prematurely. If the executor provided a cancellation function, it will be called.

It is an error to call this method after the request has already finalized.

onprogress(callback(...info)) -> this

Adds a listener for progress updates. The callback will be called whenever the progress method that was passed to the executor is called, with the same arguments.

The method returns this for easy method chaining.

onsuccess(callback(...result)) -> this

Adds a listener for successful completion of the request. The callback will be called with the result of the request as soon as the request completes successfully. If the request has already completed successfully, the callback will be called immediately (before the method returns).

The method returns this for easy method chaining.

onerror(callback(error, [...info])) -> this

Adds a listener for the failure of the request. The callback will be called with the error value and optional extra data as soon as the request is rejected. If the request has already ended in failure, the callback will be called immediately (before the method returns).

The method returns this for easy method chaining.

onabort(callback()) -> this

Adds a listener for the abortion of the request. The callback will be called as soon as the request is aborted. If the request has already been aborted, the callback will be called immediately (before the method returns).

The method returns this for easy method chaining.

onfinalize(callback()) -> this

Adds a listener for the success, error, or abortion of the request. The callback will be called as soon as the request has finalized in some way, with the appropriate data if any. If the request has already finalized, the callback will be called immediately (before the method returns).

The method returns this for easy method chaining.

Note: If both onfinalize and "specific" callbacks exist for an event, the order in which callbacks are called is entirely dependent on the order in which they were added, and not on the type of the callback. So, for example:

someRequestReturningFunction()
	.onfinalize(() => console.log("Callback 1 - Finalize"))
	.onsuccess (() => console.log("Callback 2 - Success"))
	.onfinalize(() => console.log("Callback 3 - Finalize"));

will print

Callback 1 - Finalize
Callback 2 - Success
Callback 3 - Finalize