nhb-toolbox/dist/dts/dom/query.d.ts

A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.

import type { ParsedQuery, ParsedQueryGeneric, QueryObject } from '../object/types';
import type { QueryString } from '../string/types';
/**
 * * Utility to generate query parameters from an object.
 *
 * @param params - Object containing query parameters.
 * @returns A query string as a URL-encoded string, e.g., `?key1=value1&key2=value2`.
 *
 * @example
 * generateQueryParams({ key1: 'value1', key2: 42 }); // "?key1=value1&key2=42"
 * generateQueryParams({ key1: ['value1', 'value2'], key2: 42 }); // "?key1=value1&key1=value2&key2=42"
 * generateQueryParams({ key1: '', key2: null }); // ""
 * generateQueryParams({ key1: true, key2: false }); // "?key1=true&key2=false"
 * generateQueryParams({ filters: { category: 'laptop', price: 1000 } }); // "?category=laptop&price=1000"
 */
export declare function generateQueryParams<T extends QueryObject>(params?: T): QueryString;
/**
 * * Get query params as standard `JavaScript` Object `Record<string, string>`. You can define the type by passing a type argument.
 *
 * - **Note:** *Extracts query parameters from the current URL (window.location.search).*
 *
 * @returns Query string as key-value paired object. `Record<string, string>`.
 */
export declare function getQueryParams<QParams extends Record<string, string>>(): QParams;
/**
 * * Update query params in the browser URL with given key and value.
 * @param key Key for the query to update.
 * @param value Value to updated against the given key.
 */
export declare function updateQueryParam(key: string, value: string): void;
/**
 * Parses a query string (with optional `?` prefix) into an object.
 * Supports multiple values for the same key by returning arrays.
 * Optionally parses primitive string values into actual types (e.g., "1" → 1, "true" → true).
 *
 * @remarks This utility is designed to parse generic string, for literal use, try {@link parseQueryStringLiteral}.
 *
 * - **Note:** *This function does **not** access or depend on `current URL` a.k.a `window.location.search`.*
 *
 * @param query - The query string to parse.
 * @param parsePrimitives - Whether to convert stringified primitives into real values (default: true).
 * @returns An object where keys are strings and values can be string, array, number, boolean, or null/undefined.
 */
export declare function parseQueryString<QParams extends ParsedQueryGeneric>(query: string, parsePrimitives?: boolean): QParams;
/**
 * Parses a query string (with optional `?` prefix) into an object.
 * Supports multiple values for the same key by returning arrays.
 * It returns properly typed object.
 *
 * @remarks This utility is designed to parse literal string, for generic use, try {@link parseQueryString}.
 *
 * - **Note:** *This function does **not** access or depend on `current URL` a.k.a `window.location.search`.*
 *
 * @param query - The literal query string to parse.
 * @returns An object where keys are strings and values can be string, array, or null/undefined.
 */
export declare function parseQueryStringLiteral<Q extends string>(query: Q): ParsedQuery<Q>;