@adguard/agtree/dist/types/parser/css/balancing.d.ts

Tool set for working with adblock filter lists

/**
 * @file Tokenizer helpers for balanced pairs.
 */
import { type OnErrorCallback, type OnTokenCallback, type TokenizerContextFunction } from '@adguard/css-tokenizer';
/**
 * Utility type to get the last element from a tuple, handling optional last elements correctly.
 *
 * @param T - The tuple to extract the last element from.
 * @returns The last element of the tuple if present; `L | undefined` if the last element is optional.
 */
type Last<T extends unknown[]> = T extends [...infer _I, infer L] ? L : T extends [...infer _I, (infer L)?] ? L | undefined : never;
/**
 * Utility type to remove the last element from a tuple, handling optional last elements correctly.
 *
 * @param T - The tuple to remove the last element from.
 * @returns A tuple without the last element. If the last element is optional, it is also removed.
 */
type OmitLast<T extends unknown[]> = T extends [...infer Rest, infer _Last] ? Rest : T extends [...infer Rest, (infer _Last)?] ? Rest : never;
/**
 * Extracts the parameters of `OnTokenCallback` as a tuple.
 */
type OnTokenCallbackParameters = Parameters<OnTokenCallback>;
/**
 * Extended version of `OnTokenCallback` which also receives a `balance` parameter.
 *
 * @param type Type of the token.
 * @param start Start index in the source string.
 * @param end End index in the source string.
 * @param props Additional properties of the token (if any - can be `undefined`, depending on the token type).
 * @param balance Calculated balance level of the token.
 * @param stop Function to halt tokenization.
 * @note This function is keeping the same signature as the original `OnTokenCallback` to avoid breaking changes,
 * just adding the `balance` parameter at the end.
 */
export type OnBalancedTokenCallback = (...args: [...OmitLast<OnTokenCallbackParameters>, balance: number, Last<OnTokenCallbackParameters>]) => ReturnType<OnTokenCallback>;
/**
 * Tokenize and ensure balanced pairs for standard CSS.
 *
 * @param raw Raw CSS string to tokenize
 * @param onToken Callback which will be invoked for each token, extended with a `balance` parameter
 * @param onError Error callback which is called when a parsing error is found (optional)
 * @param functionHandlers Custom function handlers (optional)
 * @throws If the input is not balanced
 */
export declare const tokenizeBalanced: (raw: string, onToken: OnBalancedTokenCallback, onError?: OnErrorCallback, functionHandlers?: Map<number, TokenizerContextFunction>) => void;
/**
 * Tokenize and ensure balanced pairs for function calls.
 *
 * @param raw Raw CSS string to tokenize
 * @param onToken Callback which will be invoked for each token, extended with a `balance` parameter
 * @param onError Error callback which is called when a parsing error is found (optional)
 * @param functionHandlers Custom function handlers (optional)
 * @throws If the input is not balanced
 */
export declare const tokenizeFnBalanced: (raw: string, onToken: OnBalancedTokenCallback, onError?: OnErrorCallback, functionHandlers?: Map<number, TokenizerContextFunction>) => void;
export {};