Dynamic Application API

stream()

async

Provides an interface for making HTTP requests, processing responses, polling, streaming data, and tracking the execution result.

Supports data streaming, continuous server polling, and tracking request progress.
This makes it suitable for file transfers, monitoring downloads, managing various data exchanges, and building real-time communication tools.
Accepts an optional object with the following properties:

Property

Type

Description

url

string

Specifies the URL of the resource for the request.
The URL can be relative or absolute.

method

string

Request method, e.g., "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD".

headers

object

An object containing the headers for the request.

body

object
string
number
DOM element

The request body.
If a DOM element is provided, it must be a form.
The form's data will be automatically converted into a request object.

format

string

The format for receiving data from the request, e.g., "json", "text", "blob", "arraybuffer", "document".
If the format is not specified, it is determined automatically.

polling

boolean
number

Determine whether continuous polling of the server is needed, using the following options:

Option

Description

false

Continuous polling has been disabled.
This is the default value.

true

Continuous polling has been enabled, with the ability to interrupt it later.

number

Continuous polling has been enabled with a delay between polls specified in milliseconds, and it can be interrupted later.

credentials

boolean

Determines whether cross-domain requests include credentials (like cookies, authorization headers, or TLS certificates).
It has no effect on same-domain requests.
When set to true, it allows sending credentials with the request, and cookies in the response will not be ignored.
To set cookies from another domain, this flag must be true.
However, third-party cookies are still subject to the same-origin policy and cannot be accessed via document.cookie or response headers.
The default value is false.

progress

function

A function that accepts an argument containing an object with the following properties:

Property

Type

Description

type

string

It can be either "download" (when data is being downloaded) or "upload" (when data is being uploaded).

loaded

number

The size of data downloaded or uploaded in bytes.

total

number

The total size of data being downloaded or uploaded in bytes.

percent

number

The percentage of data downloaded or uploaded as a floating-point number.

This function defines the logic during downloading or uploading data.
Allows dynamic modification of the request object's data during polling.
To interrupt polling, set this.polling to false.

response

function

A function that accepts an argument containing data from the server's response.
This function defines the logic based on the server's response.
Allows dynamic modification of the request object's data during polling.
To interrupt polling, set this.polling to false.

All properties are optional.
The "url", "method", and "format" properties are taken from the "api" property of the "config.js" configuration file if they are not specified.
A token can be set or overwritten with a new one for subsequent requests if the server's response contains a JSON string with the "token" property.
The token assigned by the server will automatically be included in the "Authorization" header of each request, following the format: {Authorization: 'Bearer token'}.
If custom headers are included in the request, the "Authorization" header will be automatically added if the token has been set.
If a custom "Authorization" header is specified in the request, it will be sent, but the server-set header will not be overwritten.
For subsequent requests that do not include an "Authorization" header, the token previously set by the server will be used.
Supports sending files both directly from forms and from a specified object, without requiring the explicit use of "multipart/form-data" in the headers or the "enctype" attribute of the form.
Await should only be used if waiting for the full completion of a request or poll.
Returns true when the request or polling is complete.
Returns false on failure.

Example:

// The request data will be taken from the configuration object.
stream();

// The basic request with data provided in the body.
// The "Authorization" header will be added automatically if the server has previously set a token.
stream({body: 'updateBooks'});
stream({body: {method: 'updateBook', id: 1}});

// Uploading files.
stream({
   url: '/stream',
   method: 'POST',
   body: $('form'),
   /*
      body: {
         'method': 'uploadFiles'
         'myFile': File,
         'myFiles': [File, File]
      }
   */
   progress: function(e) {
      if (e.type === 'upload') {
         $('#status').txt(`${e.loaded} / ${e.total}, ${e.percent}`);
      } 
   },
   response: function(e) {
      $('#status').html(e.body);
   }
});

// Continuous server polling.
stream({
   url: '/stream',
   method: 'POST',
   headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'Authorization': 'Bearer 8q2jLiT13fxDYAe2tJllusRSZ273h2'
   },
   body: {
      method: 'getBooks',
      offset: 0
   },
   format: 'json',
   polling: true,
   response: function(e) {
      if (e.noMoreBooks === true) {
         this.polling = false;
      } else {
         this.body.offset = e.newOffset;
      }
   }
});

// The GraphQL-based request.
stream({
   url: '/graphql',
   method: 'POST',
   headers: {'Content-Type': 'application/json'},
   body: {query: `
      query {
         users {
            id
            name
         }
      }
   `},
   response: function(e) {
      // your code
   }
});

// Waits for the full completion of a request or poll.
await stream();

Previous spa() Next readFile()