import { Dictionary } from '../types';
/**
 * Options for the interpolate function.
 */
export interface InterpolateOptions {
    /**
     * Custom regex pattern to match placeholders.
     * Defaults to `\%\{([^}]+)\}` for `%{key}` format.
     * The regex should have a capturing group for the key.
     */
    tagRegex?: RegExp;
    /**
     * Custom function to format values before interpolation.
     * If not provided, a default formatter will be used.
     * @param value - The value to format
     * @param tagName - The name of the tag being replaced
     * @param defaultFormatter - The default value formatter function
     * @returns The formatted string representation
     */
    valueFormatter?: (value: any, tagName: string, defaultFormatter: typeof defaultValueFormatter) => string;
}
/**
 * Interpolates placeholders in a string with values from a parameters object.
 *
 * This function is particularly useful for internationalization (i18n) and dynamic string formatting,
 * where text templates contain placeholders that need to be replaced with actual values.
 * By default, placeholders are in the format `%{key}`, where `key` can be a simple string or a dotted path.
 *
 * If a placeholder's key is not found in the params object or the value is empty,
 * the placeholder is replaced with an empty string.
 *
 * @param text - The template string containing placeholders.
 * @param params - An object containing key-value pairs for interpolation.
 * @param options - Optional configuration object for interpolation behavior.
 * @returns The interpolated string with placeholders replaced by their corresponding values.
 *
 * @example
 * // Basic interpolation with default %{key} format
 * const result = interpolate("Hello, %{name}!", { name: "World" });
 * // Result: "Hello, World!"
 *
 * @example
 * // Multiple placeholders
 * const result = interpolate("User %{firstName} %{lastName} is %{age} years old.", {
 *   firstName: "John",
 *   lastName: "Doe",
 *   age: 30
 * });
 * // Result: "User John Doe is 30 years old."
 *
 * @example
 * // Missing or empty parameters - placeholders are removed
 * const result = interpolate("Welcome %{user} to %{location}.", {
 *   user: "Alice"
 * });
 * // Result: "Welcome Alice to ."
 *
 * @example
 * // Dotted keys (treated as flat keys)
 * const result = interpolate("Contact: %{user.email}", {
 *   "user.email": "alice@example.com"
 * });
 * // Result: "Contact: alice@example.com"
 *
 * @example
 * // Custom regex for double braces {{key}}
 * const result = interpolate("Hello, {{name}}!", { name: "World" }, { tagRegex: /\{\{([^}]+)\}\}/g });
 * // Result: "Hello, World!"
 *
 * @example
 * // Custom value formatter for uppercase strings
 * const result = interpolate("Hello %{name}!", { name: "world" }, {
 *   valueFormatter: (value, tagName) => typeof value === 'string' ? value.toUpperCase() : String(value)
 * });
 * // Result: "Hello WORLD!"
 *
 * @example
 * // Custom value formatter for numbers with currency
 * const result = interpolate("Price: %{amount}", { amount: 99.99 }, {
 *   valueFormatter: (value, tagName) => typeof value === 'number' ? `$${value.toFixed(2)}` : String(value)
 * });
 * // Result: "Price: $99.99"
 *
 * @example
 * // Custom value formatter based on tag name
 * const result = interpolate("User: %{name}, Age: %{age}", { name: "John", age: 25 }, {
 *   valueFormatter: (value, tagName) => {
 *     if (tagName === 'age') return `${value} years old`;
 *     return String(value);
 *   }
 * });
 * // Result: "User: John, Age: 25 years old"
 *
 * @example
 * // No params provided - returns original string
 * const result = interpolate("No placeholders here.");
 * // Result: "No placeholders here."
 *
/**
 * Default value formatter for interpolation.
 * Handles all common JavaScript value types, including:
 * - Primitives (string, number, boolean, null, undefined)
 * - Dates (uses .toFormat() if available/Moment.js, else .toISOString())
 * - Errors (returns "Error: message")
 * - Regular Expressions (returns string representation)
 * - Arrays (returns JSON string)
 * - Objects (uses custom .toString(), or JSON string fallback)
 *
 * @param value - The value to format.
 * @param tagName - The name of the placeholder tag (unused in default formatter but available for custom ones).
 * @returns The formatted string representation of the value.
 */
declare function defaultValueFormatter(value: any, tagName: string): string;
/**
 * Interpolates placeholders in a string with values from a parameters object.
 *
 * This function is the core of the library's dynamic string replacement.
 * It identifies placeholders in the format `%{key}` (or custom format), looks up matching values
 * in the provided `params` object, formats them using a value formatter, and replaces
 * the placeholders in the original text.
 *
 * Key features:
 * - Supports default `%{key}` syntax.
 * - Supports custom regex via `options.tagRegex`.
 * - Supports custom value formatting via `options.valueFormatter`.
 * - Handles missing values gracefully (defaults to empty string).
 * - Safe replacement logic to avoid regex injection issues from value strings.
 *
 * @param text - The template string containing placeholders.
 * @param params - An object containing key-value pairs for interpolation.
 * @param options - Optional configuration object for interpolation behavior.
 * @returns The interpolated string with placeholders replaced by their corresponding values.
 */
export declare function interpolate(text?: string, params?: Dictionary, options?: InterpolateOptions): string;
export {};