@egodigital/egoose/lib/http/index.d.ts

/**
 * This file is part of the @egodigital/egoose distribution.
 * Copyright (c) e.GO Digital GmbH, Aachen, Germany (https://www.e-go-digital.com/)
 *
 * @egodigital/egoose is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, version 3.
 *
 * @egodigital/egoose is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */
/// <reference types="node" />
import * as HTTP from 'http';
import { Readable, Writable } from 'stream';
import * as url from 'url';
/**
 * Possible input values for a request body.
 */
export declare type HttpRequestBody = string | Buffer | HttpRequestBodyProvider | Readable;
/**
 * Possible values for a request body.
 */
export declare type HttpRequestBodyValue = string | Buffer | Readable;
/**
 * A function, which provides a request body value.
 *
 * @return {HttpRequestBodyValue|Promise<HttpRequestBodyValue>} The result with the body to send.
 */
export declare type HttpRequestBodyProvider = () => HttpRequestBodyValue | Promise<HttpRequestBodyValue>;
/**
 * Options for a HTTP request.
 */
export interface HttpRequestOptions {
    /**
     * Do not normalize the names of HTTP request headers.
     */
    doNotNormalizeHeaders?: boolean;
    /**
     * The custom headers to send.
     */
    headers?: any;
    /**
     * The path to the (UNIX) socket.
     */
    socket?: string;
    /**
     * Custom request timeout.
     */
    timeout?: number;
}
/**
 * Options for a HTTP request with a body.
 */
export interface HttpRequestOptionsWithBody extends HttpRequestOptions {
    /**
     * The body to send.
     */
    body?: HttpRequestBody;
    /**
     * The custom string encoding for the input body to use.
     */
    encoding?: string;
}
/**
 * A possible value for a request URI.
 */
export declare type HttpRequestUrl = string | url.Url;
/**
 * A response of a HTTP request.
 */
export interface HttpResponse {
    /**
     * The status code.
     */
    code: number;
    /**
     * The response headers.
     */
    headers: HTTP.IncomingHttpHeaders;
    /**
     * Pipes the response body to a target.
     *
     * @param {Writable} target The target stream.
     *
     * @return this
     */
    pipe(target: Writable): Writable;
    /**
     * Reads the response body.
     *
     * @return {Promise<Buffer>} The promise with the data.
     */
    readBody(): Promise<Buffer>;
    /**
     * Reads the body and handles it as JSON object.
     *
     * @param {string} [enc] The custom string encoding to use.
     *
     * @return {Promise<T>} The promise with the parsed JSON object.
     */
    readJSON<T = any>(enc?: string): Promise<T>;
    /**
     * Reads the body and handles it as string.
     *
     * @param {string} [enc] The custom string encoding to use.
     *
     * @return {Promise<string>} The promise with response body as string.
     */
    readString(enc?: string): Promise<string>;
    /**
     * The request context.
     */
    request: HTTP.ClientRequest;
    /**
     * The response context.
     */
    response: any;
    /**
     * The status message.
     */
    status: string;
}
/**
 * Does a HTTP 'CONNECT' request.
 *
 * @param {HttpRequestUrl} u The URL to call.
 * @param {HttpRequestOptionsWithBody} [opts] Options for the request.
 *
 * @return {Promise<HttpResponse>} The promise with the response.
 */
export declare function CONNECT(u: HttpRequestUrl, opts?: HttpRequestOptionsWithBody): Promise<HttpResponse>;
/**
 * Does a HTTP 'DELETE' request.
 *
 * @param {HttpRequestUrl} u The URL to call.
 * @param {HttpRequestOptionsWithBody} [opts] Options for the request.
 *
 * @return {Promise<HttpResponse>} The promise with the response.
 */
export declare function DELETE(u: HttpRequestUrl, opts?: HttpRequestOptionsWithBody): Promise<HttpResponse>;
/**
 * Does a HTTP 'GET' request.
 *
 * @param {HttpRequestUrl} u The URL to call.
 * @param {HttpRequestOptions} [opts] Options for the request.
 *
 * @return {Promise<HttpResponse>} The promise with the response.
 */
export declare function GET(u: HttpRequestUrl, opts?: HttpRequestOptions): Promise<HttpResponse>;
/**
 * Does a HTTP 'HEAD' request.
 *
 * @param {HttpRequestUrl} u The URL to call.
 * @param {HttpRequestOptionsWithBody} [opts] Options for the request.
 *
 * @return {Promise<HttpResponse>} The promise with the response.
 */
export declare function HEAD(u: HttpRequestUrl, opts?: HttpRequestOptionsWithBody): Promise<HttpResponse>;
/**
 * Does a HTTP 'OPTIONS' request.
 *
 * @param {HttpRequestUrl} u The URL to call.
 * @param {HttpRequestOptionsWithBody} [opts] Options for the request.
 *
 * @return {Promise<HttpResponse>} The promise with the response.
 */
export declare function OPTIONS(u: HttpRequestUrl, opts?: HttpRequestOptionsWithBody): Promise<HttpResponse>;
/**
 * Does a HTTP 'PATCH' request.
 *
 * @param {HttpRequestUrl} u The URL to call.
 * @param {HttpRequestOptionsWithBody} [opts] Options for the request.
 *
 * @return {Promise<HttpResponse>} The promise with the response.
 */
export declare function PATCH(u: HttpRequestUrl, opts?: HttpRequestOptionsWithBody): Promise<HttpResponse>;
/**
 * Does a HTTP 'POST' request.
 *
 * @param {HttpRequestUrl} u The URL to call.
 * @param {HttpRequestOptionsWithBody} [opts] Options for the request.
 *
 * @return {Promise<HttpResponse>} The promise with the response.
 */
export declare function POST(u: HttpRequestUrl, opts?: HttpRequestOptionsWithBody): Promise<HttpResponse>;
/**
 * Does a HTTP 'PUT' request.
 *
 * @param {HttpRequestUrl} u The URL to call.
 * @param {HttpRequestOptionsWithBody} [opts] Options for the request.
 *
 * @return {Promise<HttpResponse>} The promise with the response.
 */
export declare function PUT(u: HttpRequestUrl, opts?: HttpRequestOptionsWithBody): Promise<HttpResponse>;
/**
 * Does a HTTP 'GET' request.
 *
 * @param {string} method The method.
 * @param {HttpRequestUrl} u The URL to call.
 * @param {HttpRequestOptionsWithBody} [opts] Options for the request.
 *
 * @return {Promise<HttpResponse>} The promise with the response.
 */
export declare function request(method: string, u: HttpRequestUrl, opts?: HttpRequestOptionsWithBody): Promise<HttpResponse>;
/**
 * Does a HTTP 'TRACE' request.
 *
 * @param {HttpRequestUrl} u The URL to call.
 * @param {HttpRequestOptionsWithBody} [opts] Options for the request.
 *
 * @return {Promise<HttpResponse>} The promise with the response.
 */
export declare function TRACE(u: HttpRequestUrl, opts?: HttpRequestOptionsWithBody): Promise<HttpResponse>;