/** HTTP method for an AJAX request. Common verbs are suggested, but any custom string is allowed. */
type AJAXMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | string;
/** Request body kind. Controls the `Content-Type`/`Accept` headers and how `data` is serialized. When omitted it is auto-detected from `data`. */
type AJAXRequestType = "NONE" | "JSON" | "XML" | "FORM" | "FORMDATA" | "TEXT" | "BLOB";
/** @deprecated Renamed to {@link AJAXRequestType}. */
type AJAXReqestType = AJAXRequestType;
/** Resolved kind of the response body, derived from the response `Content-Type`. `"blob"` only occurs for the fetch-based {@link request}; `ajaxRequest` (XHR) never returns blob. */
type ResponseType = "none" | "json" | "blob" | "text" | "html";
/** Callback invoked with the parsed response on success. */
type ResponseDelegate = (response: AjaxResponse) => void;
/** Callback invoked when a request fails or is aborted. `reason` is the thrown error or an abort/timeout message. */
type ErrorDelegate = (request: AjaxRequest, reason?: any) => void;
/** Query string parameters. Each value may be a single string or an array (repeated key). */
type QueryData = {
    [key: string]: string | string[];
};
/** Options describing an AJAX request. */
interface AjaxRequest<TState = any> {
    /** Target URL. Defaults to the current `location.href` when omitted. */
    url?: string | null;
    /** Query string parameters appended to the URL. */
    query?: QueryData | null;
    /** HTTP method. Defaults to `"GET"`; normalized to upper-case. */
    method?: AJAXMethod | null;
    /** Fetch request mode (e.g. `"cors"`). Only honored by the fetch-based {@link request}. */
    mode?: RequestMode;
    /** Fetch credentials policy. Defaults to `"include"` in {@link request}; XHR always sends credentials. */
    credentials?: RequestCredentials;
    /** Timeout in milliseconds. {@link request} defaults to 30000 ms when omitted; `0` disables the XHR timeout. */
    timeout?: number | null;
    /** Additional request headers. Entries with empty values are skipped. */
    headers?: {
        [key: string]: string;
    } | null;
    /** Body serialization kind. Auto-detected from `data` when omitted. */
    type?: AJAXRequestType | null;
    /** Request body. Not allowed for `GET` (and `HEAD` in {@link request}). */
    data?: string | object | Blob | FormData | HTMLFormElement | null;
    /** Signal used to abort the request. */
    abort?: AbortSignal;
    /** Called with the response on success. */
    success?: ResponseDelegate | null;
    /** Called on failure, abort or timeout. */
    error?: ErrorDelegate | null;
    /** When `true`, bypasses caching. {@link request} sends `cache: "no-store"`; `ajaxRequest` appends a `_=<timestamp>` cache-busting query param. */
    disableCache?: boolean | null;
    /** Arbitrary state passed through to the response unchanged. */
    state?: TState | null;
}
/** Parsed result of an AJAX request. */
interface AjaxResponse<TData = any, TState = any> {
    /** HTTP status code. */
    status: number;
    /** Whether the request was redirected. Always `false` for `ajaxRequest` (XHR). */
    redirected: boolean;
    /** Final response URL. */
    url: string | null;
    /** Resolved body kind derived from the response `Content-Type`. */
    type: ResponseType;
    /** Raw `Content-Type` header value. */
    contentType: string | null;
    /** Accessor over the response headers. */
    headers: ResponseHeaders;
    /** Parsed response body, or `null` when there is no body. */
    data: TData | null;
    /** State value carried over from the originating request. */
    state?: TState | null;
}
/** Read-only accessor over response headers, mirroring a subset of the Fetch `Headers` API. */
interface ResponseHeaders {
    /** Returns the value of the given header, or `null` if absent. */
    get(name: string): string | null;
    /** Returns whether the given header is present. */
    has(name: string): boolean;
    /** Iterates over each header value/name pair. */
    forEach(callbackfn: (value: string, key: string, parent: ResponseHeaders) => void, thisArg?: any): void;
}

/**
 * Performs an AJAX request using the Fetch API.
 *
 * The response body is parsed according to its `Content-Type`: JSON, `text/html`,
 * `text/plain`, otherwise a `Blob`. `disableCache` maps to `cache: "no-store"`.
 * The request is aborted when its `timeout` elapses (defaults to 30000 ms), or when
 * `options.abort` or the `abortSignal` argument signals.
 *
 * @param options Request options. `GET`/`HEAD` requests must not carry `data`.
 * @param abortSignal Optional additional signal used to cancel the request.
 * @returns The parsed response. `options.success` is also invoked before resolving.
 * @throws On network/abort/timeout errors, or for unsupported (opaque) response types; `options.error` is invoked before re-throwing.
 */
declare function request<TData = any, TState = any>(options: AjaxRequest<TState>, abortSignal?: AbortSignal): Promise<AjaxResponse<TData, TState>>;

/**
 * Performs an AJAX request using `XMLHttpRequest`, always with credentials.
 *
 * The response body is parsed by `Content-Type` into JSON, `text/plain` or `text/html`;
 * unlike the fetch-based {@link request}, there is no `blob` response type. `disableCache`
 * appends a `_=<timestamp>` cache-busting query parameter (rather than `cache: "no-store"`).
 * Results and errors are delivered through `options.success` / `options.error`; this
 * function does not return a promise.
 *
 * @param options Request options. `GET` requests must not carry `data`. `timeout` of `0` disables the timeout.
 * @returns The underlying `XMLHttpRequest`, which can be used to `abort()` the request.
 */
declare const ajaxRequest: (options: AjaxRequest) => XMLHttpRequest;

/** Queue that executes AJAX requests one at a time, in the order they were added. */
declare class AjaxQueue {
    private _options;
    private _requests;
    private _current;
    private _destroyed;
    /** @param options Optional queue-wide hooks. */
    constructor(options?: AjaxQueueOptions);
    /** Number of requests waiting in the queue (excluding the one currently executing). */
    get length(): number;
    /** `true` when nothing is queued and no request is currently executing. */
    get isFree(): boolean;
    /** `true` when no requests are waiting in the queue (a request may still be executing). */
    get isEmpty(): boolean;
    /**
     * Adds a request to the queue. Starts executing immediately if the queue is idle.
     *
     * @param request Request options; its `success`/`error` callbacks are invoked as usual.
     * @param abortSignal Optional signal used to cancel this specific request.
     * @throws If the queue has been destroyed.
     */
    push(request: AjaxRequest, abortSignal?: AbortSignal): void;
    /**
     * Adds a request to the queue and returns a promise for its response.
     *
     * Wraps {@link push}; the request's own `success`/`error` callbacks are still invoked,
     * then the promise resolves with the response or rejects with the failure reason.
     *
     * @param request Request options.
     * @param abortSignal Optional signal used to cancel this specific request.
     * @returns A promise resolving with the {@link AjaxResponse}.
     */
    enqueue<TResponse = any>(request: AjaxRequest, abortSignal?: AbortSignal): Promise<AjaxResponse<TResponse, any>>;
    /** @deprecated Renamed to {@link enqueue}. */
    enque<TResponse = any>(request: AjaxRequest, abortSignal?: AbortSignal): Promise<AjaxResponse<TResponse, any>>;
    /**
     * Clears all queued (not-yet-started) requests.
     *
     * @param cancelCurrentRequest When `true`, also aborts the request currently executing.
     */
    reset(cancelCurrentRequest?: boolean): void;
    /** Destroys the queue: clears pending requests and aborts the current one. Subsequent {@link push} calls throw. */
    destroy(): void;
    private __execute;
    private __next;
}
/** Queue-wide hooks invoked for every request processed by an {@link AjaxQueue}. */
interface AjaxQueueOptions {
    /** Called before a request is sent; returning `false` skips it (it is dropped without being sent). */
    canRequest?: (request: AjaxRequest) => boolean | void;
    /** Called after a request completes successfully. */
    successRequest?: (request: AjaxRequest, response: AjaxResponse) => void;
    /** Called when a request fails or is aborted. */
    errorRequest?: (response: AjaxRequest, reason?: any) => void;
}

/**
 * Builds a `URLSearchParams` from query data or a `FormData`.
 *
 * Array values produce repeated keys; `null` values are skipped.
 *
 * @param query Source parameters.
 * @returns The populated `URLSearchParams` (empty when `query` is nullish).
 */
declare const createQuery: (query?: QueryData | FormData | null) => URLSearchParams;
/**
 * Appends query parameters to a URL, choosing `?` or `&` as appropriate.
 *
 * @param url Base URL.
 * @param query Parameters to append; nothing is added when empty.
 * @returns The resulting URL.
 */
declare const addQuery: (url: string, query?: QueryData | FormData | null) => string;
/**
 * Encodes a `FormData` as an `application/x-www-form-urlencoded` string.
 *
 * @param data Form data to encode.
 * @returns The URL-encoded form string.
 */
declare const encodeForm: (data: FormData) => string;

declare const helpers_addQuery: typeof addQuery;
declare const helpers_createQuery: typeof createQuery;
declare const helpers_encodeForm: typeof encodeForm;
declare namespace helpers {
  export {
    helpers_addQuery as addQuery,
    helpers_createQuery as createQuery,
    helpers_encodeForm as encodeForm,
  };
}

export { AjaxQueue, helpers as RequestHelper, ajaxRequest, request };
export type { AJAXMethod, AJAXReqestType, AJAXRequestType, AjaxQueueOptions, AjaxRequest, AjaxResponse, ErrorDelegate, QueryData, ResponseDelegate, ResponseHeaders, ResponseType };