@autometa/http 1.2.0 → 1.3.0

package/dist/index.d.cts

@@ -1,127 +1,1094 @@
-import { Method, ResponseType } from 'axios';
 import { StatusCodes } from '@autometa/status-codes';
+import { AxiosRequestConfig } from 'axios';
+import { Class } from '@autometa/types';
 
-declare class HTTPResponse<T> {
-    status: number;
+declare class HTTPResponse<T = unknown> {
+    status: StatusCode;
     statusText: string;
     data: T;
     headers: Record<string, string>;
-    request: {
-        url: string;
-        method: Method;
-    };
-    static derive<TOriginal, TDerived>(original: HTTPResponse<TOriginal>, data: TDerived): HTTPResponse<TDerived>;
-    static derive<TOriginal, TDerived>(original: HTTPResponse<TOriginal>, data: (original: TOriginal) => TDerived): HTTPResponse<TDerived>;
+    request: HTTPRequest<unknown>;
+    constructor();
+    static fromRaw<T>(response: HTTPResponse<T>): HTTPResponse<T>;
+    /**
+     * Decomposes a response, creating an exact copy of the current response,
+     * but with a new data value. The data can be provided directly as is, or it
+     * can be generated through a callback function which receives the current
+     * response data as an argument.
+     *
+     * ```ts
+     * const response = await http.get("/products");
+     *
+     * // direct value
+     * const products = response.data;
+     * const firstProduct = response.decompose(products[0]);
+     * // callback transformer
+     * const secondProduct = response.decompose((products) => products[1]);
+     * // callback transformer with destructuring
+     * const secondProduct = response.decompose(([product]) => product);
+     * ```
+     * @param value
+     */
+    decompose<K>(value: K): HTTPResponse<K>;
+    decompose<K>(transformFn: (response: T) => K): HTTPResponse<K>;
 }
-declare class DerivedHTTPResponse<T, K> extends HTTPResponse<T> {
-    actual: HTTPResponse<K>;
+declare class HTTPResponseBuilder {
+    #private;
+    static create(): HTTPResponseBuilder;
+    derive(): HTTPResponseBuilder;
+    status(code: StatusCode): this;
+    statusText(text: string): this;
+    data<T>(data: T): this;
+    headers(dict: Record<string, string>): this;
+    header(name: string, value: string): this;
+    request(request: HTTPRequest<unknown>): this;
+    build(): HTTPResponse<unknown>;
 }
 
+type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS" | "TRACE" | "CONNECT" | "get" | "post" | "put" | "delete" | "patch" | "head" | "options" | "trace" | "connect";
+type HTTPAdditionalOptions<T> = {
+    [P in keyof T]: T[P];
+};
 type SchemaParser = {
     parse: (data: unknown) => unknown;
-};
+} | {
+    validate: (data: unknown) => unknown;
+} | ((data: unknown) => unknown);
 type StatusCode<T extends typeof StatusCodes = typeof StatusCodes> = {
     [P in keyof T]: T[P] extends {
         status: infer U;
     } ? U : never;
 }[keyof T];
-type RequestState = {
+type RequestHook = <T = unknown>(state: HTTPRequest<T>) => unknown;
+type ResponseHook<T> = (state: HTTPResponse<T>) => unknown;
+
+interface RequestBaseConfig {
+    headers?: Record<string, string>;
+    params?: Record<string, string | string[] | Record<string, unknown>>;
+    baseUrl?: string;
+    route?: string[];
+    method: HTTPMethod;
+    fullUrl(): string;
+}
+interface RequestData<T = unknown> {
+    data: T;
+}
+type RequestConfig<T> = RequestBaseConfig & RequestData<T>;
+type RequestConfigBasic = RequestConfig<Record<string, unknown>>;
+
+declare class HTTPRequest<T = unknown> implements RequestConfig<T> {
     headers: Record<string, string>;
-    params: Record<string, unknown>;
-    url: string;
+    params: Record<string, string | string[] | Record<string, unknown>>;
+    baseUrl?: string;
     route: string[];
-    responseType: ResponseType | undefined;
-    data: unknown;
-    method: Method;
-    get fullUrl(): string;
-};
-type RequestHook = (state: RequestState) => unknown;
-type ResponseHook<T> = (state: HTTPResponse<T>) => unknown;
+    method: HTTPMethod;
+    data: T;
+    constructor(config?: RequestConfigBasic);
+    /**
+     * Returns the full URL of the request, including the base url,
+     * routes, and query parameters.
+     *
+     * ```ts
+     *  console.log(request.fullUrl())// https://example.com/foo?bar=baz?array=1,2,3
+     * ```
+     *
+     * Note characters may be converted to escape codes. I.e (space => %20) and (comma => %2C)
+     *
+     * N.B this method estimates what the url will be. The actual value
+     * might be different depending on your underlying HTTPClient and
+     * configuration. For example, query parameters might
+     * use different array formats.
+     */
+    fullUrl(): string;
+    /**
+     * Returns a new independent copy of the request.
+     */
+    static derive(original: HTTPRequest<unknown>): HTTPRequest<unknown>;
+}
+declare class HTTPRequestBuilder<T extends HTTPRequest<unknown>> {
+    #private;
+    constructor(request?: T | (() => T));
+    static create<T extends HTTPRequest<unknown>>(): HTTPRequestBuilder<T>;
+    get request(): T;
+    resolveDynamicHeaders(): this;
+    url(url: string): this;
+    route(...route: string[]): this;
+    param(name: string, value: string | number | boolean | (string | number | boolean)[] | Record<string, string | number | boolean>): this;
+    params(dict: Record<string, unknown>): this;
+    data<T>(data: T): this;
+    header(name: string, value: string | number | boolean | null | (() => string | number | boolean | null)): this;
+    headers(dict: Record<string, string>): this;
+    get(): T;
+    method(method: HTTPMethod): this;
+    derive(): HTTPRequestBuilder<T>;
+    build(): HTTPRequest<T>;
+}
+
+declare let defaultClient: Class<HTTPClient>;
+declare abstract class HTTPClient {
+    static Use(): (target: Class<HTTPClient>) => void;
+    abstract request<TRequestType, TResponseType>(request: HTTPRequest<TRequestType>, options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponseType>>;
+}
+
+declare class AxiosClient extends HTTPClient {
+    request<TRequestType, TResponseType>(request: HTTPRequest<TRequestType>, options: HTTPAdditionalOptions<AxiosRequestConfig>): Promise<HTTPResponse<TResponseType>>;
+}
 
 declare class SchemaMap {
     #private;
-    register(parser: SchemaParser, ...codes: StatusCode[]): (typeof parser)["parse"];
-    register(parser: SchemaParser, ...range: {
-        from: StatusCode;
-        to: StatusCode;
-    }[]): (typeof parser)["parse"];
-    register(parser: SchemaParser, ...args: (StatusCode | {
-        from: StatusCode;
-        to: StatusCode;
-    })[]): (typeof parser)["parse"];
-    registerSingle(parser: SchemaParser, ...codes: StatusCode[]): void;
-    including(map: SchemaMap): this;
-    registerRange(parser: SchemaParser, ...range: {
-        from: StatusCode;
-        to: StatusCode;
-    }[]): void;
-    get(status: StatusCode): SchemaParser | undefined;
-    validate<T>(status: StatusCode, response: T, strict: boolean): T;
+    constructor(map?: Map<StatusCode, SchemaParser> | SchemaMap);
+    derive(): SchemaMap;
+    registerStatus(parser: SchemaParser, ...codes: StatusCode[]): void;
+    registerRange(parser: SchemaParser, from: StatusCode, to: StatusCode): void;
+    validate(status: StatusCode, data: unknown, requireSchema: boolean): unknown;
+    getParser(status: StatusCode, requireSchema: boolean): SchemaParser;
+    toObject(): Record<StatusCode<{
+        readonly CONTINUE: {
+            readonly status: 100;
+            readonly statusText: "Continue";
+        };
+        readonly SWITCHING_PROTOCOLS: {
+            readonly status: 101;
+            readonly statusText: "Switching Protocols";
+        };
+        readonly PROCESSING: {
+            readonly status: 102;
+            readonly statusText: "Processing";
+        };
+        readonly OK: {
+            readonly status: 200;
+            readonly statusText: "OK";
+        };
+        readonly CREATED: {
+            readonly status: 201;
+            readonly statusText: "Created";
+        };
+        readonly ACCEPTED: {
+            readonly status: 202;
+            readonly statusText: "Accepted";
+        };
+        readonly NON_AUTHORITATIVE_INFORMATION: {
+            readonly status: 203;
+            readonly statusText: "Non Authoritative Information";
+        };
+        readonly NO_CONTENT: {
+            readonly status: 204;
+            readonly statusText: "No Content";
+        };
+        readonly RESET_CONTENT: {
+            readonly status: 205;
+            readonly statusText: "Reset Content";
+        };
+        readonly PARTIAL_CONTENT: {
+            readonly status: 206;
+            readonly statusText: "Partial Content";
+        };
+        readonly MULTI_STATUS: {
+            readonly status: 207;
+            readonly statusText: "Multi-Status";
+        };
+        readonly MULTIPLE_CHOICES: {
+            readonly status: 300;
+            readonly statusText: "Multiple Choices";
+        };
+        readonly MOVED_PERMANENTLY: {
+            readonly status: 301;
+            readonly statusText: "Moved Permanently";
+        };
+        readonly MOVED_TEMPORARILY: {
+            readonly status: 302;
+            readonly statusText: "Moved Temporarily";
+        };
+        readonly SEE_OTHER: {
+            readonly status: 303;
+            readonly statusText: "See Other";
+        };
+        readonly NOT_MODIFIED: {
+            readonly status: 304;
+            readonly statusText: "Not Modified";
+        };
+        readonly USE_PROXY: {
+            readonly status: 305;
+            readonly statusText: "Use Proxy";
+        };
+        readonly TEMPORARY_REDIRECT: {
+            readonly status: 307;
+            readonly statusText: "Temporary Redirect";
+        };
+        readonly PERMANENT_REDIRECT: {
+            readonly status: 308;
+            readonly statusText: "Permanent Redirect";
+        };
+        readonly BAD_REQUEST: {
+            readonly status: 400;
+            readonly statusText: "Bad Request";
+        };
+        readonly UNAUTHORIZED: {
+            readonly status: 401;
+            readonly statusText: "Unauthorized";
+        };
+        readonly PAYMENT_REQUIRED: {
+            readonly status: 402;
+            readonly statusText: "Unauthorized";
+        };
+        readonly FORBIDDEN: {
+            readonly status: 403;
+            readonly statusText: "Forbidden";
+        };
+        readonly NOT_FOUND: {
+            readonly status: 404;
+            readonly statusText: "Not Found";
+        };
+        readonly METHOD_NOT_ALLOWED: {
+            readonly status: 405;
+            readonly statusText: "Method Not Allowed";
+        };
+        readonly NOT_ACCEPTABLE: {
+            readonly status: 406;
+            readonly statusText: "Not Acceptable";
+        };
+        readonly PROXY_AUTHENTICATION_REQUIRED: {
+            readonly status: 407;
+            readonly statusText: "Proxy Authentication Required";
+        };
+        readonly REQUEST_TIMEOUT: {
+            readonly status: 408;
+            readonly statusText: "Request Timeout";
+        };
+        readonly CONFLICT: {
+            readonly status: 409;
+            readonly statusText: "Conflict";
+        };
+        readonly GONE: {
+            readonly status: 410;
+            readonly statusText: "Gone";
+        };
+        readonly LENGTH_REQUIRED: {
+            readonly status: 411;
+            readonly statusText: "Length Required";
+        };
+        readonly PRECONDITION_FAILED: {
+            readonly status: 412;
+            readonly statusText: "Precondition Failed";
+        };
+        readonly REQUEST_TOO_LONG: {
+            readonly status: 413;
+            readonly statusText: "Request Entity Too Large";
+        };
+        readonly REQUEST_URI_TOO_LONG: {
+            readonly status: 414;
+            readonly statusText: "Request-URI Too Long";
+        };
+        readonly UNSUPPORTED_MEDIA_TYPE: {
+            readonly status: 415;
+            readonly statusText: "Unsupported Media Type";
+        };
+        readonly REQUESTED_RANGE_NOT_SATISFIABLE: {
+            readonly status: 416;
+            readonly statusText: "Requested Range Not Satisfiable";
+        };
+        readonly EXPECTATION_FAILED: {
+            readonly status: 417;
+            readonly statusText: "Expectation Failed";
+        };
+        readonly IM_A_TEAPOT: {
+            readonly status: 418;
+            readonly statusText: "I'm a teapot";
+        };
+        readonly INSUFFICIENT_SPACE_ON_RESOURCE: {
+            readonly status: 419;
+            readonly statusText: "Insufficient Space on Resource";
+        };
+        readonly METHOD_FAILURE: {
+            readonly status: 420;
+            readonly statusText: "Method Failure";
+        };
+        readonly MISDIRECTED_REQUEST: {
+            readonly status: 421;
+            readonly statusText: "Misdirected Request";
+        };
+        readonly UNPROCESSABLE_ENTITY: {
+            readonly status: 422;
+            readonly statusText: "Unprocessable Entity";
+        };
+        readonly LOCKED: {
+            readonly status: 423;
+            readonly statusText: "Unprocessable Entity";
+        };
+        readonly FAILED_DEPENDENCY: {
+            readonly status: 424;
+            readonly statusText: "Failed Dependency";
+        };
+        readonly PRECONDITION_REQUIRED: {
+            readonly status: 428;
+            readonly statusText: "Precondition Failed";
+        };
+        readonly TOO_MANY_REQUESTS: {
+            readonly status: 429;
+            readonly statusText: "Too Many Requests";
+        };
+        readonly REQUEST_HEADER_FIELDS_TOO_LARGE: {
+            readonly status: 431;
+            readonly statusText: "Request Header Fields Too Large";
+        };
+        readonly UNAVAILABLE_FOR_LEGAL_REASONS: {
+            readonly status: 451;
+            readonly statusText: "Unavailable For Legal Reasons";
+        };
+        readonly INTERNAL_SERVER_ERROR: {
+            readonly status: 500;
+            readonly statusText: "Internal Server Error";
+        };
+        readonly NOT_IMPLEMENTED: {
+            readonly status: 501;
+            readonly statusText: "Not Implemented";
+        };
+        readonly BAD_GATEWAY: {
+            readonly status: 502;
+            readonly statusText: "Bad Gateway";
+        };
+        readonly SERVICE_UNAVAILABLE: {
+            readonly status: 503;
+            readonly statusText: "Service Unavailable";
+        };
+        readonly GATEWAY_TIMEOUT: {
+            readonly status: 504;
+            readonly statusText: "Bad Gateway";
+        };
+        readonly HTTP_VERSION_NOT_SUPPORTED: {
+            readonly status: 505;
+            readonly statusText: "HTTP Version Not Supported";
+        };
+        readonly INSUFFICIENT_STORAGE: {
+            readonly status: 507;
+            readonly statusText: "Insufficient Storage";
+        };
+        readonly NETWORK_AUTHENTICATION_REQUIRED: {
+            readonly status: 511;
+            readonly statusText: "Network Authentication Required";
+        };
+    }>, SchemaParser>;
 }
 
-declare class HTTPRequestBuilder {
+interface SchemaConfig {
+    schemas: SchemaMap;
+    requireSchema: boolean;
+    allowPlainText: boolean;
+}
+interface HTTPHooks {
+    onSend: [string, RequestHook][];
+    onReceive: [string, ResponseHook<unknown>][];
+}
+declare class MetaConfig implements SchemaConfig, HTTPHooks {
+    schemas: SchemaMap;
+    requireSchema: boolean;
+    allowPlainText: boolean;
+    onSend: [string, RequestHook][];
+    onReceive: [string, ResponseHook<unknown>][];
+    throwOnServerError: boolean;
+}
+declare class MetaConfigBuilder {
     #private;
-    constructor(map: SchemaMap);
-    requireSchema(value: boolean): this;
-    get currentState(): RequestState;
-    get currentUrl(): string;
-    url(url: string): this;
-    allowPlainText(value: boolean): this;
-    schema(parser: SchemaParser, ...codes: StatusCode[]): HTTPRequestBuilder;
+    schemaMap(map: SchemaMap): this;
+    schema(parser: SchemaParser, ...codes: StatusCode[]): MetaConfigBuilder;
     schema(parser: SchemaParser, ...range: {
         from: StatusCode;
         to: StatusCode;
-    }[]): HTTPRequestBuilder;
-    onBeforeSend(...hook: RequestHook[]): this;
-    onReceivedResponse(...hook: ResponseHook<unknown>[]): this;
-    route(...route: (string | number | boolean)[]): this;
-    header<T>(name: string, value: T): this;
-    headers(dict: Record<string, string>): this;
-    param<T>(name: string, value: T): this;
-    params(dict: Record<string, unknown>): this;
-    data<T>(data: T): this;
-    post<TReturn>(): Promise<HTTPResponse<TReturn>>;
-    get<TReturn>(): Promise<HTTPResponse<TReturn>>;
-    delete<TReturn>(): Promise<HTTPResponse<TReturn>>;
-    put<TReturn>(): Promise<HTTPResponse<TReturn>>;
-    patch<TReturn>(): Promise<HTTPResponse<TReturn>>;
-    private _request;
-    private constructOptions;
-    private tryRunBeforeHooks;
-    private tryRunAfterHooks;
+    }[]): MetaConfigBuilder;
+    schema(parser: SchemaParser, ...args: (StatusCode | {
+        from: StatusCode;
+        to: StatusCode;
+    })[]): MetaConfigBuilder;
+    requireSchema(value: boolean): this;
+    allowPlainText(value: boolean): this;
+    onBeforeSend(description: string, hook: RequestHook): this;
+    throwOnServerError(value: boolean): this;
+    onReceiveResponse(description: string, hook: ResponseHook<unknown>): this;
+    build(): MetaConfig;
+    derive(): MetaConfigBuilder;
 }
 
-type DynamicHeader = () => string;
+/**
+ * The HTTP fixture allows requests to be built and sent to a server. In general,
+ * there are 2 modes of operation:
+ *
+ * * Shared Chain: The shared chain is used to configure the client for all requests, such as
+ * routes this instance will always be used. When a shared chain method is called, it returns
+ * the same instance of HTTP which can be further chained to configure the client.
+ * * Request Chain: The request chain is used to configure a single request, inheriting values
+ * set by the shared chain. When called, a new HTTP client instance is created and inherits the values
+ * set by it's parent.
+ *
+ * The 2 modes are intended to simplify configuring an object through an inheritance chain. For example,
+ * assume we have an API with 2 controller routes, `/product` and `/seller`. We can set up a Base Client
+ * which consumes the HTTP fixture and configures it with the base url of our API.
+ *
+ * Inheritors can further configure their HTTP instance's routes.
+ *
+ * ```ts
+ * \@Constructor(HTTP)
+ * export class BaseClient {
+ *  constructor(protected readonly http: HTTP) {
+ *    this.http.url("https://api.example.com");
+ *   }
+ * }
+ *
+ * export class ProductClient extends BaseClient {
+ *  constructor(http: HTTP) {
+ *   super(http);
+ *   this.http.sharedRoute("product");
+ *  }
+ *  getProduct(id: number) {
+ *   return this.http.route(id).get();
+ * }
+ *
+ * export class SellerClient extends BaseClient {
+ *  constructor(http: HTTP) {
+ *   super(http);
+ *   this.http.sharedRoute("seller");
+ *  }
+ *
+ *  getSeller(id: number) {
+ *    return this.http.route(id).get();
+ *  }
+ * }
+ * ```
+ *
+ * 'Schemas' can also be configured. A Schema is a function or an object with a `parse` method, which
+ * takes a response data payload and returns a validated object. Schemas are mapped to
+ * HTTP Status Codes, and if configured to be required the request will fail if no schema is found
+ * matching that code.
+ *
+ * Defining a schema function:
+ *
+ * ```
+ * // user.schema.ts
+ * export function UserSchema(data: unknown) {
+ *   if(typeof data !== "object") {
+ *    throw new Error("Expected an object");
+ *   }
+ *
+ *   if(typeof data.name !== "string") {
+ *    throw new Error("Expected a string");
+ *   }
+ *
+ *  return data as { name: string };
+ * }
+ *
+ * // user.controller.ts
+ * \@Fixture(INJECTION_SCOPE.TRANSIENT)
+ * export class UserController extends BaseController {
+ *   constructor(private readonly http: HTTP) {
+ *      super(http);
+ *      this.http
+ *          .sharedRoute("user")
+ *          .sharedSchema(ErrorSchema, { from: 400, to: 499 });
+ *   }
+ *
+ *   getUser(id: number) {
+ *    return this.http.route(id).schema(UserSchema, 200).get();
+ *    // or
+ *    return this.http
+ *               .route(id)
+ *               .schema(UserSchema, { from: 200, to: 299 })
+ *               .get();
+ *    // or
+ *    return this.http
+ *               .route(id)
+ *               .schema(UserSchema, 200, 201, 202)
+ *               .get();
+ *   }
+ * }
+ * ```
+ *
+ * Validation libraries which use a `.parse` or `.validation`,  method, such as Zod or MyZod, can also be used as schemas:
+ *
+ * ```ts
+ * // user.schema.ts
+ * import { z } from "myzod";
+ *
+ * export const UserSchema = z.object({
+ *  name: z.string()
+ * });
+ *
+ * // user.controller.ts
+ * \@Fixture(INJECTION_SCOPE.TRANSIENT)
+ * export class UserController extends BaseController {
+ *  constructor(private readonly http: HTTP) {
+ *   super(http);
+ *   this.http
+ *       .sharedRoute("user")
+ *       .sharedSchema(ErrorSchema, { from: 400, to: 499 })
+ *  }
+ *
+ *  getUser(id: number) {
+ *   return this.http.route(id).schema(UserSchema, 200).get();
+ *  }
+ * }
+ * ```
+ */
 declare class HTTP {
     #private;
-    allowPlainText(value: boolean): this;
-    requireSchema(value: boolean): this;
+    private readonly client;
+    constructor(client?: HTTPClient, builder?: HTTPRequestBuilder<HTTPRequest<unknown>>, metaConfig?: MetaConfigBuilder);
+    static create(client?: HTTPClient, builder?: HTTPRequestBuilder<HTTPRequest<unknown>>, metaConfig?: MetaConfigBuilder): HTTP;
+    /**
+     * Sets the base url of the request for this client, such as
+     * `https://api.example.com`, and could include always-used routes like
+     * the api version, such as `/v1` or `/api/v1` at the end.
+     *
+     * ```ts
+     *
+     * \@Fixture(INJECTION_SCOPE.TRANSIENT)
+     * export abstract class BaseClient {
+     *   constructor(protected readonly http: HTTP) {
+     *      this.http.url("https://api.example.com");
+     *   }
+     * }
+     * ```
+     * @param url
+     * @returns
+     */
     url(url: string): this;
-    sharedOnBeforeSend(hook: RequestHook): this;
-    sharedOnReceiveResponse(hook: ResponseHook<unknown>): this;
-    onBeforeSend(hook: RequestHook): HTTPRequestBuilder;
-    onReceiveResponse(hook: ResponseHook<unknown>): HTTPRequestBuilder;
+    /**
+     * If set to true, all requests derived from this client will require a schema be defined
+     * matching any response status code. If set to false, a schema will still be used for validation
+     * if defined, or the unadulterated original body will be returned if no schema matches.
+     *
+     * @param required Whether or not a schema is required for all responses.
+     * @returns This instance of HTTP.
+     */
+    requireSchema(required: boolean): this;
+    /**
+     * If set to true, all requests derived from this client will allow plain text
+     * responses. If set to false, plain text responses will throw an serialization error.
+     *
+     * Useful when an endpoint returns a HTML or plain text response. If the plain text
+     * is the value of `true` or `false`, or a number, it will be parsed into the
+     * appropriate type.
+     *
+     * This method is a shared chain method, and will return the same instance of HTTP.
+     *
+     * @param allow Whether or not plain text responses are allowed.
+     * @returns This instance of HTTP.
+     */
+    sharedAllowPlainText(allow: boolean): this;
+    /**
+     * If set to true, all requests derived from this client will allow plain text
+     * responses. If set to false, plain text responses will throw an serialization error.
+     *
+     * Useful when an endpoint returns a HTML or plain text response. If the plain text
+     * is the value of `true` or `false`, or a number, it will be parsed into the
+     * appropriate type.
+     *
+     * This method is a request chain method, and will return a new instance of HTTP.
+     *
+     * @param allow Whether or not plain text responses are allowed.
+     * @returns A new child instance of HTTP derived from this one.
+     */
+    allowPlainText(allow: boolean): HTTP;
+    /**
+     * Attaches a route to the request, such as `/product` or `/user`. Subsequent calls
+     * to this method will append the route to the existing route, such as `/product/1`.
+     *
+     * Numbers will be converted to strings automatically. Routes can be defined one
+     * at a time or as a spread argument.
+     *
+     * ```ts
+     * constructor(http: HTTP) {
+     *   super(http);
+     *   this.http.sharedRoute("user", id).get();
+     * }
+     *
+     * // or
+     *
+     * constructor(http: HTTP) {
+     *   super(http);
+     *   this.http
+     *       .sharedRoute("user")
+     *       .sharedRoute(id)
+     *       .get();
+     * }
+     * ```
+     *
+     * This method is a shared chain method, and will return the same instance of HTTP. All
+     * child clients will inherit the routes defined by this method. Useful to configure
+     * in the constructor body.
+     *
+     * @param route A route or spread list of routes to append to the request.
+     * @returns This instance of HTTP.
+     */
+    sharedRoute(...route: (string | number | boolean)[]): this;
+    /**
+     * Attaches a route to the request, such as `/product` or `/user`. Subsequent calls
+     * to this method will append the route to the existing route, such as `/product/1`.
+     *
+     * Numbers will be converted to strings automatically. Routes can be defined one
+     * at a time or as a spread argument.
+     *
+     * ```ts
+     * getUser(id: number) {
+     *   return this.http.route("user", id).get();
+     * }
+     *
+     * // or
+     *
+     * getUser(id: number) {
+     *  return this.http
+     *            .route("user")
+     *            .route(id)
+     *            .get();
+     * }
+     * ```
+     *
+     * This method is a request chain method, and will return a new instance of HTTP, inheriting
+     * any routes previously defined and appending the new route. Useful to configure
+     * in class methods as part of finalizing a request.
+     *
+     * @param route A route or spread list of routes to append to the request.
+     * @returns A new child instance of HTTP derived from this one.
+     */
+    route(...route: (string | number | boolean)[]): HTTP;
+    /**
+     * Attaches a shared schema mapping for all requests by this client. Schemas are
+     * mapped to HTTP Status Codes, and if configured to be required the request will fail
+     * if no schema is found matching that code.
+     *
+     * The status code mapping can be defined as a single code, a range of codes, or a spread list.
+     *
+     * ```ts
+     * \@Fixture(INJECTION_SCOPE.TRANSIENT)
+     * export class UserController extends BaseController {
+     *  constructor(private readonly http: HTTP) {
+     *   super(http);
+     *   this.http
+     *       .sharedRoute("user")
+     *       .sharedSchema(UserSchema, 200)
+     *       .sharedSchema(EmptySchema, 201, 204)
+     *       .sharedSchema(ErrorSchema, { from: 400, to: 499 });
+     *  }
+     * }
+     * ```
+     *
+     * This method is a shared chain method, and will return the same instance of HTTP. All
+     * child clients will inherit the schemas defined by this method. Useful to configure
+     * in the constructor body.
+     *
+     * @param parser The schema parser to use for this mapping.
+     * @param codes A single status code, a range of status codes, or a spread list of status codes.
+     * @returns This instance of HTTP.
+     */
     sharedSchema(parser: SchemaParser, ...codes: StatusCode[]): HTTP;
     sharedSchema(parser: SchemaParser, ...range: {
         from: StatusCode;
         to: StatusCode;
     }[]): HTTP;
-    schema(parser: SchemaParser, ...codes: StatusCode[]): HTTPRequestBuilder;
+    /**
+     * Attaches a schema mapping for this request. Schemas are
+     * mapped to HTTP Status Codes, and if configured to be required the request will fail
+     * if no schema is found matching that code.
+     *
+     * The status code mapping can be defined as a single code, a range of codes, or a spread list.
+     *
+     * ```ts
+     * \@Fixture(INJECTION_SCOPE.TRANSIENT)
+     * export class UserController extends BaseController {
+     *  constructor(private readonly http: HTTP) {
+     *   super(http);
+     *   this.http
+     *       .sharedRoute("user")
+     *       .schema(ErrorSchema, { from: 400, to: 499 });
+     *  }
+     *
+     *  getUser(id: number) {
+     *   return this.http.route(id).schema(UserSchema, 200).get();
+     *  }
+     *
+     *  getUsers(...ids: number[]) {
+     *    return this.http
+     *               .route("users")
+     *               .schema(UserSchema, { from: 200, to: 299 })
+     *               .schema(UserSchema, 200)
+     *               .get();
+     * }
+     * ```
+     *
+     * This method is a request chain method, and will return a new instance of HTTP, inheriting
+     * any schemas previously defined and appending the new schema. Useful to configure
+     * in class methods as part of finalizing a request.
+     *
+     * @param parser The schema parser to use for this mapping.
+     * @param codes A single status code, a range of status codes, or a spread list of status codes.
+     * @returns A new child instance of HTTP derived from this one.
+     */
+    schema(parser: SchemaParser, ...codes: StatusCode[]): HTTP;
     schema(parser: SchemaParser, ...range: {
         from: StatusCode;
         to: StatusCode;
-    }[]): HTTPRequestBuilder;
-    sharedRoute(...route: string[]): this;
-    param(name: string, value: string): HTTPRequestBuilder;
-    params(dict: Record<string, string>): HTTPRequestBuilder;
-    data<T>(data: T): HTTPRequestBuilder;
-    sharedHeader(name: string, value: string | DynamicHeader): this;
-    route(...route: (string | number | boolean)[]): HTTPRequestBuilder;
-    header<T>(name: string, value: T): HTTPRequestBuilder;
-    headers(dict: Record<string, string>): HTTPRequestBuilder;
-    get(): Promise<HTTPResponse<unknown>>;
-    private builder;
-    private convertFactoriesToString;
+    }[]): HTTP;
+    /**
+     * Attaches a shared query string parameter to all requests by this client. Query string
+     * parameters are key-value pairs which are appended to the request url, such as
+     * `https://api.example.com?name=John&age=30`.
+     *
+     * This method is a shared chain method, and will return the same instance of HTTP. All
+     * child clients will inherit the query string parameters defined by this method. Useful to configure
+     * in the constructor body.
+     *
+     * @param name The name of the query string parameter.
+     * @param value The value of the query string parameter.
+     * @returns This instance of HTTP.
+     */
+    sharedParam(name: string, value: Record<string, unknown>): HTTP;
+    sharedParam(name: string, ...value: (string | number | boolean)[]): HTTP;
+    /**
+     * `onSend` is a pre-request hook which will be executed in order of definition
+     * immediately before the request is sent. This hook can be used to analyze or
+     * log the request state.
+     *
+     * ```ts
+     *
+     * \@Fixture(INJECTION_SCOPE.TRANSIENT)
+     * export class UserController extends BaseController {
+     *  constructor(private readonly http: HTTP) {
+     *     super(http);
+     *     this.http
+     *         .sharedRoute("user")
+     *         .sharedOnSend("log request",
+     *                       (request) => console.log(JSON.stringify(request, null, 2))
+     *     );
+     *  }
+     * }
+     * ```
+     *
+     * This method is a shared chain method, and will return the same instance of HTTP. All
+     * child clients will inherit the onSend hooks defined by this method. Useful to configure
+     * in the constructor body.
+     *
+     * @param description A description of the hook, used for debugging.
+     * @param hook The hook to execute.
+     * @returns This instance of HTTP.
+     */
+    sharedOnSend(description: string, hook: RequestHook): this;
+    /**
+     * `onReceive` is a post-request hook which will be executed in order of definition
+     * immediately after the response is received. This hook can be used to analyze or
+     * log the response state.
+     *
+     * ```ts
+     *
+     * \@Fixture(INJECTION_SCOPE.TRANSIENT)
+     * export class UserController extends BaseController {
+     *  constructor(private readonly http: HTTP) {
+     *     super(http);
+     *     this.http
+     *         .sharedRoute("user")
+     *         .sharedOnReceive("log response",
+     *                          (response) => console.log(JSON.stringify(response, null, 2))
+     *     );
+     *  }
+     * }
+     * ```
+     *
+     * This method is a shared chain method, and will return the same instance of HTTP. All
+     * child clients will inherit the onReceive hooks defined by this method. Useful to configure
+     * in the constructor body.
+     *
+     * @param description A description of the hook, used for debugging.
+     * @param hook The hook to execute.
+     * @returns This instance of HTTP.
+     */
+    sharedOnReceive(description: string, hook: ResponseHook<unknown>): this;
+    /**
+     * Attaches a query string parameter object to the request. Query string
+     * parameters are key-value pairs which are appended to the request url, such as
+     * `https://api.example.com?name=John&age=30`.
+     *
+     * This method is a shared chain method, and will return the same instance of HTTP. All
+     * child clients will inherit the query string parameters defined by this method. Useful to configure
+     * in the constructor body.
+     *
+     * ```ts
+     * constructor(http: HTTP) {
+     *    super(http);
+     *    this.http
+     *        .sharedParams({ 'is-test': "true" })
+     * ```
+     * @param name The name of the query string parameter.
+     * @param value The value of the query string parameter.
+     * @returns This instance of HTTP.
+     */
+    sharedParams(dict: Record<string, unknown>): this;
+    /**
+     * Attaches a query string parameter to the request. Query string
+     * parameters are key-value pairs which are appended to the request url, such as
+     * `https://api.example.com?name=John&age=30`.
+     *
+     * This method is a request chain method, and will return a new instance of HTTP, inheriting
+     * any query string parameters previously defined and appending the new parameter. Useful to configure
+     * in class methods as part of finalizing a request.
+     *
+     * ```ts
+     * getUser(id: number) {
+     *   return this.http
+     *             .route(id)
+     *             .param("name", "John")
+     *             .param("age", 30)
+     * ```
+     *
+     * Note: Numbers and Booleans will be converted to strings automatically.
+     *
+     * @param name The name of the query string parameter.
+     * @param value The value of the query string parameter.
+     * @returns A new child instance of HTTP derived from this one.
+     */
+    param(name: string, value: Record<string, unknown>): HTTP;
+    param(name: string, ...value: (string | number | boolean)[]): HTTP;
+    /**
+     * Attaches a query string parameter object to the request. Query string
+     * parameters are key-value pairs which are appended to the request url, such as
+     * `https://api.example.com?name=John&age=30`.
+     *
+     * This method is a shared chain method, and will return the same instance of HTTP. All
+     * child clients will inherit the query string parameters defined by this method. Useful to configure
+     * in the constructor body.
+     *
+     * ```ts
+     * getUser(id: number) {
+     *   return this.http
+     *             .route(id)
+     *             .param({ name: "John", age: "30" })
+     *
+     * @param name The name of the query string parameter.
+     * @param value The value of the query string parameter.
+     * @returns This instance of HTTP.
+     */
+    params(dict: Record<string, string>): HTTP;
+    /**
+     * Attaches a shared data payload to this client. The data payload is the body of the request,
+     * and can be any type. If the data payload is an object, it will be serialized to JSON.
+     *
+     * This method is a shared chain method, and will return the same instance of HTTP. All
+     * child clients will inherit the data payload defined by this method. Useful to configure
+     * in the constructor body.
+     *
+     * @param data The data payload to attach to the request.
+     * @returns This instance of HTTP.
+     */
+    sharedData<T>(data: T): this;
+    /**
+     * Attaches a shared header to this client. Headers are string:string key-value pairs which are
+     * sent with the request, such as `Content-Type: application/json`.
+     *
+     * Numbers, Booleans and Null will be converted to string values automatically.
+     *
+     * A Factory function can also be provided to generate the header value at the time of request.
+     *
+     * This method is a shared chain method, and will return the same instance of HTTP. All
+     * child clients will inherit the header defined by this method. Useful to configure
+     * in the constructor body.
+     *
+     * @param name The name of the header.
+     * @param value The value of the header.
+     */
+    sharedHeader(name: string, value: string | number | boolean | null | (() => string | number | boolean | null)): this;
+    header(name: string, value: string): HTTP;
+    /**
+     * Attaches a data payload to this request. The data payload is the body of the request,
+     * and can be any type. If the data payload is an object, it will be serialized to JSON.
+     *
+     * This method is a request chain method, and will return a new instance of HTTP, inheriting
+     * any data payload previously defined and appending the new payload. Useful to configure
+     * in class methods as part of finalizing a request.
+     *
+     * @param data The data payload to attach to the request.
+     * @returns A new child instance of HTTP derived from this one.
+     */
+    data<T>(data: T): HTTP;
+    /**
+     * `onSend` is a pre-request hook which will be executed in order of definition
+     * immediately before the request is sent. This hook can be used to modify the request,
+     * or to log the state of a request before final send-off.
+     *
+     * ```ts
+     *
+     * \@Fixture(INJECTION_SCOPE.TRANSIENT)
+     * export class UserController extends BaseController {
+     *  constructor(private readonly http: HTTP) {
+     *   super(http);
+     *  }
+     *
+     *  getUser(id: number) {
+     *   return this.http
+     *              .route(id)
+     *              .onSend("log request",
+     *                (request) => console.log(JSON.stringify(request, null, 2)
+     *              )
+     *              .get();
+     * }
+     * ```
+     *
+     * This method is a request chain method, and will return a new instance of HTTP, inheriting
+     * any onSend hooks previously defined and appending the new hook. Useful to configure
+     * in class methods as part of finalizing a request.
+     *
+     * @param description A description of the hook, used for debugging.
+     * @param hook The hook to execute.
+     * @returns A new child instance of HTTP derived from this one.
+     */
+    onSend(description: string, hook: RequestHook): HTTP;
+    /**
+     * `onReceive` is a post-request hook which will be executed in order of definition
+     * immediately after the response is received. This hook can be used to modify the response,
+     * or to log the state of a response after it is received.
+     *
+     * ```ts
+     *
+     * \@Fixture(INJECTION_SCOPE.TRANSIENT)
+     * export class UserController extends BaseController {
+     *  constructor(private readonly http: HTTP) {
+     *   super(http);
+     *  }
+     *
+     *  getUser(id: number) {
+     *   return this.http
+     *              .route(id)
+     *              .onReceive("log response",
+     *                (response) => console.log(JSON.stringify(response, null, 2)
+     *              )
+     *              .get();
+     * }
+     * ```
+     *
+     * This method is a request chain method, and will return a new instance of HTTP, inheriting
+     * any onReceive hooks previously defined and appending the new hook. Useful to configure
+     * in class methods as part of finalizing a request.
+     *
+     * @param description A description of the hook, used for debugging.
+     * @param hook The hook to execute.
+     * @returns A new child instance of HTTP derived from this one.
+     */
+    onReceive(description: string, hook: ResponseHook<unknown>): HTTP;
+    /**
+     * Executes the current request state as a GET request.
+     *
+     * @param options Additional options to pass to the underlying http client, such
+     *                as e.g Axios configuration values.
+     * @returns A promise which resolves to the response.
+     */
+    get<TResponseType>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponseType>>;
+    /**
+     * Executes the current request state as a POST request.
+     *
+     * @param data The data payload to attach to the request.
+     * @param options Additional options to pass to the underlying http client, such
+     *                as e.g Axios configuration values.
+     * @returns A promise which resolves to the response.
+     */
+    post<TResponseType>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponseType>>;
+    /**
+     * Executes the current request state as a DELETE request.
+     *
+     * @param options Additional options to pass to the underlying http client, such
+     *                as e.g Axios configuration values.
+     * @returns A promise which resolves to the response.
+     *               as e.g Axios configuration values.
+     */
+    delete<TResponseType>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponseType>>;
+    /**
+     * Executes the current request state as a PUT request.
+     *
+     * @param options Additional options to pass to the underlying http client, such
+     *                as e.g Axios configuration values.
+     * @returns A promise which resolves to the response.
+     */
+    put<TResponseType>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponseType>>;
+    /**
+     * Executes the current request state as a PATCH request.
+     *
+     * @param options Additional options to pass to the underlying http client, such
+     *                as e.g Axios configuration values.
+     * @returns A promise which resolves to the response.
+     */
+    patch<TResponseType>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponseType>>;
+    head<TResponseType>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponseType>>;
+    options<TResponseType>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponseType>>;
+    trace<TResponseType>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponseType>>;
+    connect<TResponseType>(options?: HTTPAdditionalOptions<unknown>): Promise<HTTPResponse<TResponseType>>;
+    private runOnSendHooks;
+    private runOnReceiveHooks;
 }
 
-export { DerivedHTTPResponse, DynamicHeader, HTTP, HTTPResponse, RequestHook, RequestState, ResponseHook, SchemaParser, StatusCode };
+/**
+ * Schema which does not care about data validation.
+ *
+ * Useful if `requireSchema` is set to true, but a specific
+ * endpoints response does not matter.
+ * @param data
+ * @returns
+ */
+declare function AnySchema(data: unknown): unknown;
+/**
+ * Schema which validates that a response is empty. This can mean
+ * the data payload was `null`, `undefined` or the string `'null'`.
+ *
+ * Useful if `requireSchema` is set to true, but a specific
+ * endpoints response should be null or not defined.
+ * @param data
+ * @returns
+ */
+declare function EmptySchema(data: unknown): null | undefined;
+/**
+ * Schema which validates a response was null.
+ *
+ * Useful if `requireSchema` is set to true, but a specific
+ * endpoints response should be null.
+ * @param data
+ * @returns
+ */
+declare function NullSchema(data: unknown): null;
+/**
+ * Schema which validates a response was undefined.
+ *
+ * Useful if `requireSchema` is set to true, but a specific
+ * endpoints response should be undefined.
+ *
+ * @param data
+ * @returns
+ */
+declare function UndefinedSchema(data: unknown): undefined;
+/**
+ * Schema which validates a response was a boolean, or a string of value
+ * `'true'` or `'false'`.
+ *
+ * Useful if `requireSchema` is set to true, but a specific
+ * endpoints response should be a boolean.
+ *
+ * @param data
+ * @returns
+ */
+declare function BooleanSchema(data: unknown): any;
+/**
+ * Schema which validates a response was a number, or a string of value
+ * of a number.
+ *
+ * Useful if `requireSchema` is set to true, but a specific
+ * endpoints response should be a number.
+ *
+ * @param data
+ * @returns
+ */
+declare function NumberSchema(data: unknown): any;
+/**
+ * Schema which validates a response was a string.
+ *
+ * Useful if `requireSchema` is set to true, but a specific
+ * endpoints response should be a string.
+ *
+ * @param data
+ * @returns
+ */
+declare function StringSchema(data: unknown): string;
+declare function JSONSchema<T = unknown>(data: unknown): any;
+
+export { AnySchema, AxiosClient, BooleanSchema, EmptySchema, HTTP, HTTPAdditionalOptions, HTTPClient, HTTPMethod, HTTPRequest, HTTPRequestBuilder, HTTPResponse, HTTPResponseBuilder, JSONSchema, NullSchema, NumberSchema, RequestHook, ResponseHook, SchemaParser, StringSchema, UndefinedSchema, defaultClient };