import { type Maybe, type ArrayOrValue, type IterableOrValue, type ObjectKey } from '@dereekb/util';
/**
 * Options for makeUrlSearchParams()
 */
export interface MakeUrlSearchParamsOptions {
    /**
     * Optional iterable of keys to remove from the search params.
     */
    readonly omitKeys?: Maybe<IterableOrValue<ObjectKey>>;
    /**
     * Whether to filter out empty values from the input objects.
     *
     * Defaults to true.
     */
    readonly filterEmptyValues?: boolean;
    /**
     * Whether to encode spaces as `%20` instead of `+` in the output string.
     *
     * `URLSearchParams.toString()` uses `application/x-www-form-urlencoded` encoding,
     * which represents spaces as `+`. However, `URL.search` and `decodeURIComponent()`
     * encode spaces as `%20`. This mismatch means that consumers like Angular's router
     * that use `decodeURIComponent()` will not decode `+` back to a space, corrupting
     * values (e.g., `"openid profile"` becomes `"openid+profile"`).
     *
     * Set to `true` when building redirect URLs or any URL that will be decoded with
     * `decodeURIComponent()` rather than form-data parsing.
     *
     * Defaults to false.
     *
     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams#interaction_with_url.searchparams | MDN: Interaction with URL.searchParams}
     */
    readonly useUrlSearchSpaceHandling?: boolean;
}
/**
 * Creates URLSearchParams from the input objects. The input objects are merged together.
 *
 * @param input - one or more objects (or nullish values) whose key-value pairs become search parameters
 * @param options - optional configuration for filtering, omitting keys, and space encoding
 * @returns a URLSearchParams instance built from the merged and filtered input
 */
export declare function makeUrlSearchParams(input: Maybe<ArrayOrValue<Maybe<object | Record<string, string | number>>>>, options?: Maybe<MakeUrlSearchParamsOptions>): URLSearchParams;
/**
 * Creates a URL query string from the input objects.
 *
 * Equivalent to `makeUrlSearchParams(...).toString()`, but respects the
 * {@link MakeUrlSearchParamsOptions.usePercentEncoding} option to produce
 * RFC 3986 percent-encoded output (`%20` for spaces) instead of the
 * `application/x-www-form-urlencoded` default (`+` for spaces).
 *
 * @param input - objects to encode as query parameters
 * @param options - encoding options
 * @returns the encoded query string (without a leading `?`)
 */
export declare function makeUrlSearchParamsString(input: Maybe<ArrayOrValue<Maybe<object | Record<string, string | number>>>>, options?: Maybe<MakeUrlSearchParamsOptions>): string;
/**
 * Updates or adds query parameters on an existing URL string.
 *
 * Parses the URL's existing query string, merges in the new parameters (new values
 * override existing keys), and returns the rebuilt URL. Respects all
 * {@link MakeUrlSearchParamsOptions} such as `omitKeys`, `filterEmptyValues`, and
 * `useUrlSearchSpaceHandling`.
 *
 * @example
 * ```typescript
 * // Add params to a URL with no query string
 * updateUrlSearchParams('https://example.com/form', { name: 'Alice', age: 30 });
 * // => 'https://example.com/form?name=Alice&age=30'
 *
 * // Override an existing param
 * updateUrlSearchParams('https://example.com?page=1&sort=asc', { page: 2 });
 * // => 'https://example.com?page=2&sort=asc'
 *
 * // Use percent-encoded spaces for redirect URLs
 * updateUrlSearchParams('https://example.com', { scope: 'openid profile' }, { useUrlSearchSpaceHandling: true });
 * // => 'https://example.com?scope=openid%20profile'
 * ```
 *
 * @param url - the URL string to update
 * @param params - new search parameters to merge into the URL
 * @param options - optional configuration for filtering, omitting keys, and space encoding
 * @returns the URL string with updated query parameters
 */
export declare function updateUrlSearchParams(url: string, params: Maybe<ArrayOrValue<Maybe<object | Record<string, string | number>>>>, options?: Maybe<MakeUrlSearchParamsOptions>): string;
/**
 * Merges an array of MakeUrlSearchParamsOptions into a single MakeUrlSearchParamsOptions value.
 *
 * @param options - one or more options objects whose omitKeys sets are combined
 * @returns a single MakeUrlSearchParamsOptions with the union of all omitKeys
 */
export declare function mergeMakeUrlSearchParamsOptions(options: ArrayOrValue<Maybe<MakeUrlSearchParamsOptions>>): MakeUrlSearchParamsOptions;