@ima/core
Version:
IMA.js framework for isomorphic javascript application
262 lines • 11.4 kB
TypeScript
import { ImaRequestInit, HttpAgentRequestOptions, HttpAgentResponse } from './HttpAgent';
import { UrlTransformer } from './UrlTransformer';
import { GenericError } from '../error/GenericError';
import { StringParameters, UnknownParameters } from '../types';
import { Window } from '../window/Window';
/**
* An object representing the complete request parameters used to create and
* send the HTTP request.
* @typedef HttpProxy~RequestParams
* @property method The HTTP method.
* @property url The original URL to which to make the request.
* @property transformedUrl The actual URL to which to make the
* request, created by applying the URL transformer to the
* original URL.
* @property data The request
* data, sent as query or body.
* @property options The high-level request options
* provided by the HTTP agent.
*/
export type HttpProxyRequestParams = {
method: string;
url: string;
transformedUrl: string;
data?: UnknownParameters;
options: HttpAgentRequestOptions;
};
/**
* An object that describes a failed HTTP request, providing
* information about both the failure reported by the server and how the
* request has been sent to the server.
* @typedef HttpProxy~ErrorParams
* @property errorName An error name.
* @property status The HTTP response status code send by the
* server.
* @property body The body of HTTP error response (detailed
* information).
* @property cause The low-level cause error.
* @property params An object representing the
* complete request parameters used to create and send the HTTP
* request.
*/
export type HttpProxyErrorParams<B = unknown> = {
errorName: string;
status: number;
body: B;
cause: Error;
} & HttpProxyRequestParams;
/**
* Middleware proxy between {@link HttpAgent} implementations and the
* {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API Fetch API},
* providing a Promise-oriented API for sending requests.
*/
export declare class HttpProxy {
protected _transformer: UrlTransformer;
protected _window: Window;
protected _defaultHeaders: Map<string, string>;
/**
* Initializes the HTTP proxy.
*
* @param transformer A transformer of URLs to which
* requests are made.
* @param window Helper for manipulating the global object `window`
* regardless of the client/server-side environment.
*/
constructor(transformer: UrlTransformer, window: Window);
/**
* Executes a HTTP request to the specified URL using the specified HTTP
* method, carrying the provided data.
*
* @param method The HTTP method to use.
* @param url The URL to which the request should be made.
* @param data The data to
* be send to the server. The data will be included as query
* parameters if the request method is `GET` or `HEAD`, and as
* a request body for any other request method.
* @param options Optional request options.
* @return A promise that resolves to the server
* response.
*/
request<B>(method: string, url: string, data: UnknownParameters | undefined, options: HttpAgentRequestOptions): Promise<HttpAgentResponse<B>>;
/**
* Sets the specified default HTTP header. The header will be sent with all
* subsequent HTTP requests unless reconfigured using this method,
* overridden by request options, or cleared by
* {@link HttpProxy#clearDefaultHeaders} method.
*
* @param header A header name.
* @param value A header value.
* @returns this
*/
setDefaultHeader(header: string, value: string): this;
/**
* Clears all defaults headers sent with all requests.
*
* @returns this
*/
clearDefaultHeaders(): this;
/**
* Gets an object that describes a failed HTTP request, providing
* information about both the failure reported by the server and how the
* request has been sent to the server.
*
* @param method The HTTP method used to make the request.
* @param url The URL to which the request has been made.
* @param data The data sent
* with the request.
* @param options Optional request options.
* @param status The HTTP response status code send by the server.
* @param body The body of HTTP error response (detailed
* information).
* @param cause The low-level cause error.
* @return An object containing both the details of
* the error and the request that lead to it.
*/
getErrorParams<B = unknown>(method: string, url: string, data: UnknownParameters | undefined, options: HttpAgentRequestOptions, status: number, body: B | undefined, cause: Error): HttpProxyErrorParams<B>;
/**
* Returns `true` if cookies have to be processed manually by setting
* `Cookie` HTTP header on requests and parsing the `Set-Cookie` HTTP
* response header.
*
* The result of this method depends on the current application
* environment, the client-side usually handles cookie processing
* automatically, leading this method returning `false`.
*
* At the client-side, the method tests whether the client has cookies
* enabled (which results in cookies being automatically processed by the
* browser), and returns `true` or `false` accordingly.
*
* `true` if cookies are not processed automatically by
* the environment and have to be handled manually by parsing
* response headers and setting request headers, otherwise `false`.
*/
haveToSetCookiesManually(): boolean;
/**
* Processes the response received from the server.
*
* @param requestParams The original request's
* parameters.
* @param response The Fetch API's `Response` object representing
* the server's response.
* @param responseBody The server's response body.
* @return The server's response along with all related
* metadata.
*/
_processResponse<B>(requestParams: HttpProxyRequestParams, response: Response, responseBody: B): HttpAgentResponse<B>;
/**
* Converts the provided Fetch API's `Headers` object to a plain object.
*
* @param headers The headers to convert.
* @return Converted headers.
*/
_headersToPlainObject(headers: Headers): StringParameters;
/**
* Processes the provided Fetch API or internal error and creates an error
* to expose to the calling API.
*
* @param fetchError The internal error to process.
* @param requestParams An object representing the
* complete request parameters used to create and send the HTTP
* request.
* @return The error to provide to the calling API.
*/
_processError(fetchError: GenericError | Error, requestParams: HttpProxyRequestParams): GenericError;
/**
* Creates an error that represents a failed HTTP request.
*
* @param cause The error's message.
* @param requestParams An object representing the
* complete request parameters used to create and send the HTTP
* request.
* @param status Server's response HTTP status code.
* @param responseBody The body of the server's response, if any.
* @return The error representing a failed HTTP request.
*/
_createError(cause: GenericError | Error, requestParams: HttpProxyRequestParams, status: number, responseBody?: unknown): GenericError;
/**
* Composes an object representing the HTTP request parameters from the
* provided arguments.
*
* @param method The HTTP method to use.
* @param url The URL to which the request should be sent.
* @param data The data to
* send with the request.
* @param options Optional request options.
* @return An object representing the complete request parameters used to create and
* send the HTTP request.
*/
_composeRequestParams(method: string, url: string, data: UnknownParameters | undefined, options: HttpAgentRequestOptions): HttpProxyRequestParams;
/**
* Composes an init object, which can be used as a second argument of
* `window.fetch` method.
*
* @param method The HTTP method to use.
* @param data The data to
* be send with a request.
* @param options Options provided by the HTTP
* agent.
* @return {ImaRequestInit} An `ImaRequestInit` object (extended from `RequestInit` of the Fetch API).
*/
_composeRequestInit(method: string, data: UnknownParameters | undefined, options: HttpAgentRequestOptions): ImaRequestInit;
/**
* Gets a `Content-Type` header value for defined method, data and options.
*
* @param method The HTTP method to use.
* @param data The data to
* be send with a request.
* @param options Options provided by the HTTP
* agent.
* @return A `Content-Type` header value, null for requests
* with no body.
*/
_getContentType(method: string, data: UnknownParameters | undefined, headers: Record<string, string>): string | null;
/**
* Transforms the provided URL using the current URL transformer and adds
* the provided data to the URL's query string.
*
* @param url The URL to prepare for use with the fetch API.
* @param data The data to be attached to the query string.
* @return The transformed URL with the provided data attached to
* its query string.
*/
_composeRequestUrl(url: string, data: StringParameters | undefined): string;
/**
* Checks if a request should have a body (`GET` and `HEAD` requests don't
* have a body).
*
* @param method The HTTP method.
* @param data The data to
* be send with a request.
* @return `true` if a request has a body, otherwise `false`.
*/
_shouldRequestHaveBody(method: string, data: UnknownParameters | undefined): boolean;
/**
* Formats request body according to request headers.
*
* @param data The data to
* be send with a request.
* @param headers Headers object from options provided by the HTTP
* agent.
* @private
*/
_transformRequestBody(data: UnknownParameters | undefined, headers: Record<string, string>): string | UnknownParameters | FormData | undefined;
/**
* Returns query string representation of the data parameter.
* (Returned string does not contain ? at the beginning)
*
* @param object The object to be converted
* @returns Query string representation of the given object
* @private
*/
_convertObjectToQueryString<T extends Record<string, string | number | boolean>>(object: T | undefined): string | undefined;
/**
* Converts given data to FormData object.
* If FormData object is not supported by the browser the original object is returned.
*
* @param object The object to be converted
* @returns
* @private
*/
_convertObjectToFormData<T extends Record<string, string | Blob>>(object: T | undefined): T | FormData | undefined;
}
//# sourceMappingURL=HttpProxy.d.ts.map