Skip to main content
Version: 2.x.x

Dispatcher


Introduction

All requests in this library (except those triggered directly in the client) go to the dispatcher before being sent. The dispatcher handles request dispatch and manages retries, queueing, offline handling, canceling, deduplicating, and sending the received data to the cache.

There are two dispatcher instances in the Builder class: one for fetching and one for submitting requests. This was designed for configuration reasons and gives you much more flexibility.

Every request in the dispatcher is stored in the queue structure. This allows us to perform many operations (e.g. stopping, pausing, or starting) on the dispatched requests. However, this does not mean that all requests will be sent individually; there are multiple dispatching modes available, which you can read about in the dispatching modes section.


Purpose

  • Handles request flow
  • Queues requests in storage
  • Emits request results

QueueKey

queueKey, which is kept on the instance of the Command being used, plays an important role in queues. It is used in propagation and reception of request events on a given queue and in management of incoming and outgoing requests. By default, the queueKey value is automatically based on the method, endpoint, and query parameters of the given command. However, you can add the key manually when setting the Command or using one of its methods.


RequestId

requestId is autogenerated by the dispatchers when a request is added. It's used when we need exact communication with the dispatched requests, e.g. if we want to listen to the exact request emitted events.

const requestId = builder.fetchDispatcher.add(command);

builder.commandManager.events.onUploadProgressById(requestId, console.log);
builder.commandManager.events.onDownloadProgressById(requestId, console.log);

Features

Queueing

Queues can be stopped, paused, or started. The difference between stop and pause is that stopping causes in-progress requests to be canceled (but not removed from the queue), while pausing completes in-progress requests and suspends waiting requests.

Queue - Pausing / Stopping / Starting

You can stop, pause and start any group of requests using that group’s queueKey. Stopping cancels all started requests; pausing completes in-progress requests and holds all others.

builder.fetchDispatcher.stop("my-queue-key");
builder.fetchDispatcher.pause("my-queue-key");
builder.fetchDispatcher.start("my-queue-key");

Request - Stopping / Starting

You can stop and start individual requests with the stopRequest and startRequest methods. A stopped request is canceled and must wait in the dispatch queue until it is started again.

builder.fetchDispatcher.stopRequest("my-queue-key", "requestId");
builder.fetchDispatcher.startRequest("my-queue-key", "requestId");

Offline

When the connection is lost, the queue is stopped and the failed or interrupted requests will wait for the connection to recover. This prevents data loss.

Lifecycle

Queues have optional options with events (such as onUpdateStorage and onInitialization) that are fired at certain moments in their lifecycle.


Dispatching Modes

Every dispatcher queue has several modes that can be selected by command props.

Concurrent

When using this mode, requests are not limited in any way; they can all be called at any time, all at once. This is the default mode for commands.

Enable this mode by setting the command queued prop to false.

Cancelable

Cancelable mode avoids race-conditioning when multiple requests are sent simultaneously but only the last request matters. This mode is ideal for paginated lists of data, i.e. where only a single page needs to be shown regardless if the user is triggering new requests with rapidly changing pagination.

Enable this mode by setting the command cancelable prop to true.

Queued

This mode is ideal for a one-by-one sending solution. It allows you to combine requests into one ordered list that will be resolved one item at a time. In this mode, you can start, stop, or pause the entire queue.

Enable this mode by setting the command queued prop to true.

Deduplication

Deduplication optimizes the data exchange with the server. If we ask the server for the same data twice at the same time with different requests, this mode will perform one call and propagate the request to both sources.

Enable this mode by setting the command deduplication prop to true.