@foxify/http/.build/esm/Request.d.ts

Foxify HTTP module

/// <reference types="node" />
/// <reference types="node" />
import { IncomingHttpHeaders, IncomingMessage } from "http";
import { UrlWithStringQuery } from "url";
import { MethodT, ProtocolT } from "./constants";
import { Accepts, RANGE_PARSER_RESULT, RangeParserRangesI } from "./utils";
export declare const DEFAULT_SETTINGS: SettingsI;
export default class Request extends IncomingMessage {
    readonly headers: HeadersI;
    readonly method: MethodT;
    readonly params: Record<string, unknown>;
    readonly statusCode: undefined;
    readonly statusMessage: undefined;
    readonly url: string;
    protected _acceptsCache?: Accepts;
    protected _parsedUrl?: UrlWithStringQuery;
    protected _queryCache?: Record<string, unknown>;
    /**
     * Parse the "Host" header field to a hostname.
     *
     * When the "trust.proxy" setting trusts the socket
     * address, the "X-Forwarded-Host" header field will
     * be trusted.
     */
    get hostname(): string | undefined;
    /**
     * Return the remote address from the trusted proxy.
     *
     * This is the remote address on the socket unless
     * "trust.proxy" is set.
     */
    get ip(): string;
    /**
     * When "trust.proxy" is set, trusted proxy addresses + client.
     *
     * For example if the value were "client, proxy1, proxy2"
     * you would receive the array `["client", "proxy1", "proxy2"]`
     * where "proxy2" is the furthest down-stream and "proxy1" and
     * "proxy2" were trusted.
     */
    get ips(): string[];
    /**
     * Short-hand for `url.parseUrl(req.url).pathname`.
     */
    get path(): string;
    /**
     * Return the protocol string "http" or "https"
     * when requested with TLS. When the "trust.proxy"
     * setting trusts the socket address, the
     * "X-Forwarded-Proto" header field will be trusted
     * and used if present.
     *
     * If you're running behind a reverse proxy that
     * supplies https for you this may be enabled.
     */
    get protocol(): ProtocolT;
    get query(): Record<string, unknown>;
    /**
     * Short-hand for:
     *
     *    req.protocol === 'https'
     */
    get secure(): boolean;
    /**
     * Return subdomains as an array.
     *
     * Subdomains are the dot-separated parts of the host before the main domain of
     * the app. By default, the domain of the app is assumed to be the last two
     * parts of the host. This can be changed by setting "subdomain offset".
     *
     * For example, if the domain is "tobi.ferrets.example.com":
     * If "subdomain.offset" is not set, req.subdomains is `["ferrets", "tobi"]`.
     * If "subdomain.offset" is 3, req.subdomains is `["tobi"]`.
     */
    get subdomains(): string[];
    /**
     * Check if the request was an `_XMLHttpRequest_`.
     */
    get xhr(): boolean;
    protected get _accepts(): Accepts;
    /**
     * Check if the given `type(s)` is acceptable, returning
     * the best match when true, otherwise `undefined`, in which
     * case you should respond with 406 "Not Acceptable".
     *
     * The `type` value may be a single MIME type string
     * such as "application/json", an extension name
     * such as "json", a comma-delimited list such as "json, html, text/plain",
     * an argument list such as `"json", "html", "text/plain"`,
     * When a list is given, the _best_ match, if any is returned.
     *
     * @example
     * // Accept: text/html
     * req.accepts("html");
     * // => "html"
     * @example
     * // Accept: text/*, application/json
     * req.accepts("html");
     * // => "html"
     * req.accepts("text/html");
     * // => "text/html"
     * req.accepts("json, text");
     * // => "json"
     * req.accepts("application/json");
     * // => "application/json"
     * @example
     * // Accept: text/*, application/json
     * req.accepts("image/png");
     * req.accepts("png");
     * // => undefined
     * @example
     * // Accept: text/*;q=.5, application/json
     * req.accepts("html", "json");
     * req.accepts("html, json");
     * // => "json"
     */
    accepts(...types: string[]): string[] | string | false;
    /**
     * Check if the given `charset`s are acceptable,
     * otherwise you should respond with 406 "Not Acceptable".
     */
    acceptsCharsets(...charsets: string[]): string[] | string | false;
    /**
     * Check if the given `encoding`s are accepted.
     */
    acceptsEncodings(...encodings: string[]): string[] | string | false;
    /**
     * Check if the given `language`s are acceptable,
     * otherwise you should respond with 406 "Not Acceptable".
     */
    acceptsLanguages(...languages: string[]): string[] | string | false;
    /**
     * Return request header.
     *
     * The `Referrer` header field is special-cased,
     * both `Referrer` and `Referer` are interchangeable.
     *
     * @example
     * req.get("Content-Type"); // => "text/plain"
     * @example
     * req.get("content-type"); // => "text/plain"
     * @example
     * req.get("Something"); // => undefined
     */
    get<Header extends Extract<keyof HeadersI, string>>(name: Header | Uppercase<Header>): HeadersI[Header];
    /**
     * Check if the incoming request contains the "Content-Type"
     * header field, and it contains the give mime `type`.
     *
     * @example
     * // With Content-Type: text/html; charset=utf-8
     * req.is("html");
     * req.is("text/html");
     * req.is("text/*");
     * // => true
     * @example
     * // When Content-Type is application/json
     * req.is("json");
     * req.is("application/json");
     * req.is("application/*");
     * // => true
     * @example
     * req.is("html");
     * // => false
     */
    is(...types: string[]): string | false | null;
    /**
     * Parse Range header field, capping to the given `size`.
     *
     * Unspecified ranges such as "0-" require knowledge of your resource length. In
     * the case of a byte range this is of course the total number of bytes. If the
     * Range header field is not given `undefined` is returned, `-1` when unsatisfiable,
     * and `-2` when syntactically invalid.
     *
     * When ranges are returned, the array has a "type" property which is the type of
     * range that is required (most commonly, "bytes"). Each array element is an object
     * with a "start" and "end" property for the portion of the range.
     *
     * NOTE: remember that ranges are inclusive, so for example "Range: users=0-3"
     * should respond with 4 users when available, not 3.
     */
    range(size: number, combine?: boolean): RANGE_PARSER_RESULT | RangeParserRangesI | undefined;
}
export declare function settings(settings?: Partial<SettingsI>): void;
export interface HeadersI extends IncomingHttpHeaders {
    referrer: IncomingHttpHeaders["referer"];
    "x-forwarded-host"?: string;
    "x-forwarded-proto"?: string;
    "x-requested-with"?: string;
}
export interface SettingsI {
    "subdomain.offset": number;
    "query.parser"(str: string): Record<string, unknown>;
    "trust.proxy"(ip: string, hopIndex: number): boolean;
}
//# sourceMappingURL=Request.d.ts.map