Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface CreateRequestOptions<D>

Options for a request

Type parameters

  • D = unknown

    response data type

Hierarchy

Index

Properties

Methods

Properties

Optional api

api?: RequestAPI

A map of API parameters.

These parameters apply if the original request URL is not absolute, and they can be used to customize the base API URL depending on the runtime environment. If you define the base API URL via config#api or globalOpts.api, these parameters will be mapped on it.

example
// URL (IS_PROD === true): https://foo.com/users
// URL (IS_PROD === false): https://foo.com/foo-stage

request('/users', {
  api: {
    protocol: 'https',
    domain2: () => IS_PROD ? 'foo' : 'foo-stage',
    zone: 'com'
  }
}).data.then(console.log);


// URL (globalOpts.api === 'https://api.foo.com' && IS_PROD === true): https://api.foo.com/users
// URL (globalOpts.api === 'https://api.foo.com' && IS_PROD === false): https://api.foo-stage.com/users

request('/users', {
  api: {
    domain2: () => IS_PROD ? 'foo' : 'foo-stage',
  }
}).data.then(console.log);

Optional body

body?: RequestBody

Request body. Mind, not every HTTP method can send data in this way. For instance, GET or HEAD requests can send data only with URLs (@see query).

Optional cacheId

cacheId?: string | symbol

Unique cache identifier: it can be useful to create request factories with isolated cache storages

Optional cacheMethods

cacheMethods?: RequestMethod[]

List of request methods that support caching

default

['GET']

Optional cacheStrategy

cacheStrategy?: CacheStrategy

Strategy of caching for requests that support caching (by default, only GET requests can be cached):

  1. 'forever' - caches all requests and stores their values forever within the active session or until the cache expires (if cacheTTL is specified);
  2. 'queue' - caches all requests, but more frequent requests will push less frequent requests;
  3. 'never' - never caches any requests;
  4. Or, you can pass a custom cache object.
example
import request, { cache } from 'core/request';
import RestrictedCache from 'core/cache/restricted';

request('/users', {
  cacheStrategy: 'forever'
}).data.then(console.log);

request('/users', {
  cacheStrategy: new RestrictedCache(50)
}).data.then(console.log);

// If you set a strategy using string identifiers, all requests will be stored within the global cache objects.
cache.forever.clear();

Optional cacheTTL

cacheTTL?: number

Value in milliseconds that indicates how long a request value should keep in the cache (all requests are stored within the active session without expiring by default)

Optional contentType

contentType?: string

Mime type of the request data (if not specified, it will be cast dynamically)

example
request('//create-user', {
  method: 'POST',
  body: {name: 'Bob'},
  contentType: 'application/x-msgpack',
  encoder: toMessagePack
}).data.then(console.log);

Optional credentials

credentials?: boolean | RequestCredentials

Enables providing of credentials for cross-domain requests. Also, you can manage to omit any credentials if the used request engine supports it.

Optional decoder

decoder?: Decoders | Decoder<unknown, unknown>

A function (or a sequence of functions) takes the current request response data and returns new data to respond. If you provide a sequence of functions, the first function will pass a result to the next function from the sequence, etc.

Optional encoder

encoder?: Encoders | Encoder<unknown, unknown>

A function (or a sequence of functions) takes the current request data and returns new data to request. If you provide a sequence of functions, the first function will pass a result in the next function from the sequence, etc.

Optional engine

engine?: RequestEngine

A request engine to use. The engine - is a simple function that takes request parameters and returns an abortable promise resolved with the core/request/response instance. Mind, some engines provide extra features. For instance, you can listen to upload progress events with the XHR engine. Or, you can parse responses in a stream form with the Fetch engine.

example
import AbortablePromise from 'core/promise/abortable';

import request from 'core/request';
import Response from 'core/request/response';

import fetchEngine from 'core/request/engines/fetch';
import xhrEngine from 'core/request/engines/xhr';

request('//users', {
  engine: fetchEngine,
  credentials: 'omit'
}).data.then(console.log);

request('//users', {
  engine: xhrEngine
}).data.then(console.log);

request('//users', {
  engine: (params) => new AbortablePromise((resolve) => {
    const res = new Response({
      message: 'Hello world'
    }, {responseType: 'object'});

    resolve(res);

  }, params.parent)

}).data.then(console.log);

Optional headers

headers?: RawHeaders

Additional HTTP request headers. You can provide them as a simple dictionary or an instance of the Headers class. Also, you can pass headers as an instance of the core/request/headers class.

see

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers

Optional important

important?: boolean

A meta flag that indicates that the request is important: is usually used with middlewares to indicate that the request needs to be executed as soon as possible

example
request('/users', {
  important: true,

  middlewares: {
    doSomeWork({ctx}) {
      if (ctx.important) {
        // Do some work...
      }
    }
  }
}).data.then(console.log);

Optional jsonReviver

jsonReviver?: false | JSONCb

Reviver function for JSON.parse or false to disable defaults. By default, it parses some strings as Date instances.

default

convertIfDate

Optional meta

meta?: Dictionary<unknown>

A dictionary with some extra parameters for the request: is usually used with middlewares to provide domain-specific information

Optional method

method?: RequestMethod

HTTP method to create a request

see

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods

Optional middlewares

middlewares?: Middlewares<D>

A dictionary or iterable value with middleware functions: functions take an environment of request parameters and can modify theirs.

Please notice that the order of middleware depends on the structure you use. Also, if at least one of the middlewares returns a function, invoking this function will be returned as the request result. It can be helpful to organize mocks of data and other similar cases when you don't want to execute a real request.

example
request('/users', {
  middlewares: {
    addAPI({globalOpts}) {
      if (globalOpts.api == null) {
        globalOpts.api = 'https://api.foo.com';
      }
    },

    addSession({opts}) {
      opts.headers.set('Authorization', myJWT);
    }
  }
}).data.then(console.log);

// Mocking response data
request('/users', {
  middlewares: [
    ({ctx}) => () => ctx.wrapAsResponse([
      {name: 'Bob'},
      {name: 'Robert'}
    ])
  ]
});

Optional offlineCache

offlineCache?: boolean

Enables support of offline caching. By default, a request can only be taken from a cache if there is no network. You can customize this logic by providing a custom cache object with the core/cache/decorators/persistent decorator.

default

false

example
import request from 'core/request';
import { asyncLocal } from 'core/kv-storage';

import addPersistent from 'core/cache/decorators/persistent';
import SimpleCache from 'core/cache/simple';

request('/users', {
  cacheStrategy: 'forever',
  offlineCache: true
});

const
  opts = {loadFromStorage: 'onInit'},
  persistentCache = await addPersistent(new SimpleCache(), asyncLocal, opts);

request('/users', {
  cacheStrategy: persistentCache
});

Optional offlineCacheTTL

offlineCacheTTL?: number

Value in milliseconds that indicates how long a request value should keep in the offline cache

default

(1).day()

Optional okStatuses

okStatuses?: OkStatuses

A list of status codes (or a single code) that match successful operation. Also, you can pass a range of codes.

default

new Range(200, 299)

Optional query

query?: RequestQuery

Request parameters that will be serialized to a string and passed via a request URL. To customize how to encode data to a query string, see querySerializer.

Optional responseType

responseType?: ResponseType

Type of the response data (if not specified, it will be cast dynamically from the response headers):

  1. 'text' - result is interpreted as a simple string;
  2. 'json' - result is interpreted as a JSON object;
  3. 'document' - result is interpreted as an XML/HTML document;
  4. 'formData' - result is interpreted as a FormData object;
  5. 'blob' - result is interpreted as a Blob object;
  6. 'arrayBuffer' - result is interpreted as a raw array buffer;
  7. 'object' - result is interpreted "as is" without any converting.
example
request('//users', {
  responseType: 'arrayBuffer',
  decoder: fromMessagePack
}).data.then(console.log);

Optional retry

retry?: number | RetryOptions<unknown>

Options to retry bad requests or a number of maximum request retries

example
request('//users', {
  timeout: (10).seconds(),
  retry: 3
}).data.then(console.log);

request('//users', {
  timeout: (10).seconds(),
  retry: {
    attempts: 3,
    delay: (attempt) => attempt * (3).seconds()
  }
}).data.then(console.log);

Optional streamDecoder

streamDecoder?: StreamDecoder<unknown, unknown> | StreamDecoders

A function (or a sequence of functions) takes the current request response data chunk and yields a new chunk to respond via an async iterator. If you provide a sequence of functions, the first function will pass a result to the next function from the sequence, etc. This parameter is used when you're parsing responses in a stream form.

Optional timeout

timeout?: number

Value in milliseconds for a request timeout

Methods

Optional querySerializer

  • Returns a serialized value of the specified query object

    example
    import request from 'core/request';
    import { toQueryString } from 'core/url';

    request('//user', {
      query: {ids: [125, 35, 454]},
      querySerializer: (data) => toQueryString(data, {arraySyntax: true})
    }).data.then(console.log);

    Parameters

    Returns string