import { IParseBaseOptions, IStringifyBaseOptions } from 'qs';
import { Dictionary } from '../../types';
/**
 * Returns the query string from a given URL.
 *
 * This function takes a URL and an optional flag as input.
 * It parses the URL to extract the query string, which is the part of the URL after the `?` character.
 * If the `addQuestionSeparator` flag is true, the query string is returned with a leading `?` character.
 *
 * @param uri The URL to extract the query string from.
 * @param addQuestionSeparator Whether to include the `?` character in the returned query string (default: true).
 * @returns The query string associated with the given URL.
 * @example
 * ```typescript
 * const url = 'https://example.com/path?a=1&b=2';
 * console.log(extractQueryString(url)); // Output: "?a=1&b=2"
 * console.log(extractQueryString(url, false)); // Output: "a=1&b=2"
 * ```
 */
export declare const extractQueryString: (uri?: string, addQuestionSeparator?: boolean) => string;
/**
 * Returns the query parameters from a given URL as an object.
 *
 * This function takes a URL and an optional options object as input.
 * It extracts the query string from the URL using the `extractQueryString` function and then parses it into an object using the `queryString.parse` method.
 * The `queryString.parse` method is configured to allow sparse arrays and to merge the provided options with the default options.
 *
 * @param uri The URL to extract the query parameters from.
 * @param queryStringOpts Options for the `queryString.parse` method (default: {}).
 * @returns An object containing the query parameters.
 * @example
 * ```typescript
 * const url = 'https://example.com/path?a=1&b=2&c[]=3&c[]=4';
 * console.log(getQueryParams(url)); // Output: { a: '1', b: '2', c: [ '3', '4' ] }
 * ```
 */
export declare const getQueryParams: (uri: string | null | undefined, queryStringOpts?: IParseBaseOptions) => Dictionary;
/**
 * Removes the query string from a given URL and returns the resulting URL.
 *
 * This function takes a URL and an optional flag as input.
 * It removes the query string and any fragment identifier from the URL using regular expressions.
 * If the `_decodeURIComponent` flag is true, the resulting URL is decoded using the `decodeURIComponent` function.
 *
 * @param uri The URL to remove the query string from.
 * @param _decodeURIComponent Whether to decode the resulting URL using `decodeURIComponent` (default: false).
 * @returns The URL with the query string removed.
 * @example
 * ```typescript
 * const url = 'https://example.com/path?a=1&b=2#fragment';
 * console.log(removeQueryString(url)); // Output: "https://example.com/path"
 * console.log(removeQueryString(url, true)); // Output: "https://example.com/path" (decoded)
 * ```
 */
export declare const removeQueryString: (uri: string | undefined | null, _decodeURIComponent?: boolean) => string;
/**
 * Adds query parameters to a given URL.
 *
 * This function takes a URL, a key-value pair or an object of key-value pairs, and optional options as input.
 * It removes any existing query string from the URL, merges the new query parameters with the existing ones, and then appends the resulting query string to the URL.
 *
 * @param url The URL to add query parameters to.
 * @param key A string key or an object of key-value pairs to add to the query string.
 * @param value The value associated with the key, only applicable when key is a string.
 * @param options Options for the `queryString.stringify` method (default: {}).
 * @returns The URL with the query parameters added.
 * @example
 * ```typescript
 * const url = 'https://example.com/path';
 * console.log(setQueryParams(url, 'a', 1)); // Output: "https://example.com/path?a=1"
 * console.log(setQueryParams(url, { a: 1, b: 2 })); // Output: "https://example.com/path?a=1&b=2"
 * ```
 */
export declare function setQueryParams(url: string | undefined | null, key: any, value?: any, options?: IStringifyBaseOptions): string;
/**
 * Converts an object to a query string.
 *
 * This function takes an object and an optional flag as input.
 * It recursively iterates through the object's properties and converts them to a query string format.
 * If the `encodeURI` flag is true, the values are encoded using the `encodeURIComponent` function.
 *
 * @param o The object to convert to a query string.
 * @param encodeURI Whether to encode the values using `encodeURIComponent` (default: false).
 * @returns The object converted to a query string.
 * @example
 * ```typescript
 * const obj = { a: 1, b: 2, c: { d: 3, e: 4 } };
 * console.log(objectToQueryString(obj)); // Output: "a=1&b=2&c[d]=3&c[e]=4"
 * console.log(objectToQueryString(obj, true)); // Output: "a=1&b=2&c%5Bd%5D=3&c%5Be%5D=4"
 * ```
 */
export declare function objectToQueryString(o: any, encodeURI?: boolean): string;
/**
 * Parses a URI and returns the parsed object.
 *
 * This function takes a URI as input and returns an object containing the parsed components of the URI.
 * The object includes properties for the hash, host, hostname, href, origin, pathname, port, protocol, search, username, and password.
 *
 * @param uri The URI to parse.
 * @returns The parsed URI object.
 * @example
 * ```typescript
 * const uri = 'http://username:password@localhost:257/deploy/?asd=asd#asd';
 * console.log(parseURI(uri));
 * // Output:
 * // {
 * //   hash: "#asd",
 * //   host: "localhost:257",
 * //   hostname: "localhost",
 * //   href: "http://username:password@localhost:257/deploy/?asd=asd#asd",
 * //   origin: "http://username:password@localhost:257",
 * //   pathname: "/deploy/",
 * //   port: "257",
 * //   protocol: "http:",
 * //   search: "?asd=asd",
 * //   username: "username",
 * //   password: "password"
 * // }
 * ```
 */
export declare const parseURI: (uri: string | null | undefined) => {
    hash?: string;
    host?: string;
    hostname?: string;
    href?: string;
    origin?: string;
    pathname?: string;
    port?: string;
    protocol?: string;
    search?: string;
    username?: string;
    password?: string;
};
/**
 * Options for configuring URL validation behavior.
 *
 * @public
 */
export interface IsUrlOptions {
    /**
     * If true, only allows protocols that require a hostname (http, https, ftp, etc.).
     * If false, allows all valid protocols including mailto, tel, data, etc.
     *
     * @defaultValue true
     */
    requireHost?: boolean;
    /**
     * List of allowed protocols. If provided, only URLs with these protocols are considered valid.
     * Protocols should be specified without the trailing colon (e.g., 'http', not 'http:').
     *
     * @defaultValue undefined (all protocols allowed based on requireHost setting)
     *
     * @example
     * ```typescript
     * // Only allow HTTPS URLs
     * isUrl('https://example.com', { allowedProtocols: ['https'] }); // true
     * isUrl('http://example.com', { allowedProtocols: ['https'] }); // false
     * ```
     */
    allowedProtocols?: string[];
}
/**
 * Validates whether a given string is a valid, full URL.
 *
 * @remarks
 * This function uses a dual-approach validation strategy:
 * 1. First attempts to use the native URL constructor if available (modern environments)
 * 2. Falls back to a comprehensive regex pattern for environments without URL support
 *
 * By default, a valid full URL must include:
 * - A protocol (http, https, ftp, etc.)
 * - A domain/host (for protocols that require one)
 * - Optional path, query parameters, and hash fragments
 *
 * The function can be configured to:
 * - Accept only host-requiring protocols (default)
 * - Accept any valid URI including mailto:, tel:, data:, etc.
 * - Restrict to specific protocols only
 *
 * @param value - The string to test for URL validity
 * @param options - Optional configuration for validation behavior
 *
 * @returns `true` if the string is a valid full URL, `false` otherwise
 *
 * @example
 * Basic usage:
 * ```typescript
 * isUrl('https://example.com'); // true
 * isUrl('example.com'); // false (missing protocol)
 * isUrl('mailto:user@example.com'); // false (default requires host)
 * ```
 *
 * @example
 * Allow all valid URIs:
 * ```typescript
 * isUrl('mailto:user@example.com', { requireHost: false }); // true
 * isUrl('tel:+1234567890', { requireHost: false }); // true
 * isUrl('data:text/plain,hello', { requireHost: false }); // true
 * ```
 *
 * @example
 * Restrict to specific protocols:
 * ```typescript
 * isUrl('https://example.com', { allowedProtocols: ['https'] }); // true
 * isUrl('http://example.com', { allowedProtocols: ['https'] }); // false
 * ```
 *
 * @public
 */
export declare function isUrl(value: unknown, options?: IsUrlOptions): boolean;
/**
 * Detects if a URL string has been encoded using encodeURIComponent.
 *
 * This function uses multiple heuristics to determine if a string has been
 * encoded with encodeURIComponent. It checks for:
 * 1. Presence of valid encoded character sequences (%XX where XX are hex digits)
 * 2. Whether decoding changes the string (indicating encoded content)
 * 3. Handles mixed encoded/unencoded content properly
 *
 * @param {any} str - The string to check for encoding
 * @returns {boolean} - Returns true if the string appears to be encoded, false otherwise
 *
 * @example
 * console.log(isUriEncoded('hello%20world')); // true
 * console.log(isUriEncoded('hello world')); // false
 * console.log(isUriEncoded('hello%2Bworld')); // true
 * console.log(isUriEncoded('hello+world')); // false
 * console.log(isUriEncoded('https%3A%2F%2Fexample.com')); // true
 * console.log(isUriEncoded('https://example.com')); // false
 * console.log(isUriEncoded('hello%20world%21normal')); // true (mixed)
 */
export declare const isUriEncoded: (str: string) => boolean;
/**
 * Options for configuring Data URL validation behavior.
 *
 * @public
 */
export interface IsDataUrlOptions {
    /**
     * List of allowed MIME types. If provided, only Data URLs with these MIME types are considered valid.
     * MIME types should be specified in lowercase (e.g., 'image/png', 'text/plain').
     *
     * @defaultValue undefined (all MIME types allowed)
     *
     * @example
     * ```typescript
     * // Only allow image Data URLs
     * isDataUrl('data:image/png;base64,ABC', { allowedMimeTypes: ['image/png', 'image/jpeg'] }); // true
     * isDataUrl('data:text/plain;base64,ABC', { allowedMimeTypes: ['image/png'] }); // false
     * ```
     */
    allowedMimeTypes?: string[];
    /**
     * If true, requires the Data URL to use base64 encoding.
     * If false, allows both base64 and URL-encoded data.
     *
     * @defaultValue false
     *
     * @example
     * ```typescript
     * isDataUrl('data:text/plain;base64,SGVsbG8=', { requireBase64: true }); // true
     * isDataUrl('data:text/plain,Hello', { requireBase64: true }); // false
     * ```
     */
    requireBase64?: boolean;
    /**
     * If true, validates that base64-encoded data appears to be valid base64.
     * Performs basic validation of base64 character set and padding.
     *
     * @defaultValue false
     *
     * @example
     * ```typescript
     * isDataUrl('data:text/plain;base64,SGVsbG8=', { validateBase64: true }); // true
     * isDataUrl('data:text/plain;base64,!!!invalid', { validateBase64: true }); // false
     * ```
     */
    validateBase64?: boolean;
}
/**
 * Validates whether a given string is a valid Data URL (RFC 2897).
 *
 * @remarks
 * Data URLs allow embedding small files inline in documents using the format:
 * `data:[<mediatype>][;base64],<data>`
 *
 * This function validates:
 * - Proper data: protocol prefix
 * - Valid MIME type format (if present)
 * - Proper encoding declaration (base64 or URL-encoded)
 * - Data payload presence
 *
 * Components of a Data URL:
 * - Protocol: Always "data:"
 * - Media type (optional): MIME type like "text/plain" or "image/png" (defaults to "text/plain;charset=US-ASCII")
 * - Encoding (optional): ";base64" for base64 encoding (defaults to URL encoding)
 * - Data: The actual content after the comma
 *
 * The function uses a dual-approach validation strategy:
 * 1. First attempts to use the native URL constructor if available (modern environments)
 * 2. Falls back to a comprehensive regex pattern for environments without URL support
 *
 * @param value - The string to test for Data URL validity
 * @param options - Optional configuration for validation behavior
 *
 * @returns `true` if the string is a valid Data URL, `false` otherwise
 *
 * @example
 * Basic usage:
 * ```typescript
 * isDataUrl('data:text/plain,Hello%20World'); // true
 * isDataUrl('data:text/plain;base64,SGVsbG8gV29ybGQ='); // true
 * isDataUrl('data:image/png;base64,iVBORw0KG...'); // true
 * isDataUrl('not a data url'); // false
 * ```
 *
 * @example
 * With MIME type filtering:
 * ```typescript
 * isDataUrl('data:image/png;base64,ABC', { allowedMimeTypes: ['image/png'] }); // true
 * isDataUrl('data:text/plain,Hello', { allowedMimeTypes: ['image/png'] }); // false
 * ```
 *
 * @example
 * Require base64 encoding:
 * ```typescript
 * isDataUrl('data:text/plain;base64,SGVsbG8=', { requireBase64: true }); // true
 * isDataUrl('data:text/plain,Hello', { requireBase64: true }); // false
 * ```
 *
 * @public
 */
export declare function isDataUrl(value: string, options?: IsDataUrlOptions): boolean;