/**
 * Safe JSON Parsing Utilities
 *
 * Centralized JSON parsing utilities that handle errors gracefully.
 * Provides safe parsing that doesn't throw on invalid JSON.
 */
import type { SafeParseResult } from "../../types/index.js";
/**
 * Safely parse a JSON string without throwing.
 *
 * This is the preferred method for parsing JSON from external sources
 * (user input, API responses, etc.) where invalid JSON is possible.
 *
 * @param str - The string to parse as JSON
 * @returns Object with success flag and either data or error
 *
 * @example
 * ```typescript
 * const result = safeParseJsonResult<UserData>(userInput);
 * if (result.success) {
 *   console.log(result.data.name);
 * } else {
 *   console.error('Invalid JSON:', result.error.message);
 * }
 * ```
 */
export declare function safeParseJsonResult<T = unknown>(str: string): SafeParseResult<T>;
/**
 * Safely parse JSON with fallback value.
 *
 * Useful when you need a value regardless of parse success.
 *
 * @param str - The string to parse as JSON
 * @param fallback - Value to return if parsing fails
 * @returns Parsed value or fallback
 *
 * @example
 * ```typescript
 * const config = safeParseJson(configString, { theme: 'light' });
 * // Always returns an object, never throws
 * ```
 */
export declare function safeParseJson<T>(str: string, fallback: T): T;
/**
 * Parse JSON or return undefined if invalid.
 *
 * @param str - The string to parse as JSON
 * @returns Parsed value or undefined
 *
 * @example
 * ```typescript
 * const data = parseJsonOrUndefined<Config>(input);
 * if (data) {
 *   // Use data
 * }
 * ```
 */
export declare function parseJsonOrUndefined<T>(str: string): T | undefined;
/**
 * Parse JSON or return null if invalid.
 *
 * @param str - The string to parse as JSON
 * @returns Parsed value or null
 *
 * @example
 * ```typescript
 * const data = parseJsonOrNull<Config>(input);
 * if (data !== null) {
 *   // Use data
 * }
 * ```
 */
export declare function parseJsonOrNull<T>(str: string): T | null;
/**
 * Check if a string is valid JSON.
 *
 * @param str - The string to validate
 * @returns true if the string is valid JSON
 *
 * @example
 * ```typescript
 * if (isValidJson(userInput)) {
 *   // Proceed with parsing
 * }
 * ```
 */
export declare function isValidJson(str: string): boolean;
/**
 * Safe stringify with circular reference handling.
 *
 * Handles circular references, BigInt values, and other edge cases gracefully.
 *
 * @param obj - Value to stringify
 * @param space - Optional indentation (number of spaces)
 * @returns JSON string, with circular references replaced by "[Circular]"
 *
 * @example
 * ```typescript
 * const obj = { name: 'test' };
 * obj.self = obj; // Circular reference
 *
 * const json = safeStringify(obj);
 * // Returns: '{"name":"test","self":"[Circular]"}'
 *
 * const prettyJson = safeStringify(data, 2);
 * // Returns formatted JSON with 2-space indentation
 * ```
 */
export declare function safeStringify(obj: unknown, space?: number): string;
/**
 * Safe stringify with options for more control.
 *
 * @param obj - Value to stringify
 * @param options - Stringify options
 * @returns JSON string or fallback string on error
 *
 * @example
 * ```typescript
 * const json = safeStringifyWithOptions(data, {
 *   pretty: true,
 *   fallback: '{}',
 * });
 * ```
 */
export declare function safeStringifyWithOptions(obj: unknown, options?: {
    /** Use 2-space indentation */
    pretty?: boolean;
    /** Value to return if stringify fails */
    fallback?: string;
}): string;