/**
 * JSON primitive types: `null`, `boolean`, `number`, or `string`.
 *
 * @example
 * ```ts
 * const primitives: JsonPrimitive[] = [null, true, 42, 'hello']
 * ```
 */
export type JsonPrimitive = null | boolean | number | string;
/**
 * Any valid JSON value: primitive, object, or array.
 *
 * @example
 * ```ts
 * const values: JsonValue[] = [
 *   null,
 *   true,
 *   42,
 *   'hello',
 *   { key: 'value' },
 *   [1, 2, 3]
 * ]
 * ```
 */
export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
/**
 * A JSON object with string keys and JSON values.
 *
 * @example
 * ```ts
 * const obj: JsonObject = {
 *   name: 'example',
 *   count: 42,
 *   active: true,
 *   nested: { key: 'value' }
 * }
 * ```
 */
export interface JsonObject {
    [key: string]: JsonValue;
}
/**
 * A JSON array containing JSON values.
 *
 * @example
 * ```ts
 * const arr: JsonArray = [1, 'two', { three: 3 }, [4, 5]]
 * ```
 */
export interface JsonArray extends Array<JsonValue> {
}
/**
 * Reviver function for transforming parsed JSON values.
 * Called for each key-value pair during parsing.
 *
 * @param key - The object key or array index being parsed
 * @param value - The parsed value
 * @returns The transformed value (or original if no transform needed)
 *
 * @example
 * ```ts
 * // Convert date strings to Date objects
 * const reviver: JsonReviver = (key, value) => {
 *   if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value)) {
 *     return new Date(value)
 *   }
 *   return value
 * }
 * ```
 */
export type JsonReviver = (key: string, value: unknown) => unknown;
/**
 * Options for JSON parsing operations.
 */
export interface JsonParseOptions {
    /**
     * Optional filepath for improved error messages.
     * When provided, errors will be prefixed with the filepath.
     *
     * @example
     * ```ts
     * // Error message will be: "config.json: Unexpected token } in JSON"
     * jsonParse('invalid', { filepath: 'config.json' })
     * ```
     */
    filepath?: string | undefined;
    /**
     * Optional reviver function to transform parsed values.
     * Called for each key-value pair during parsing.
     *
     * @example
     * ```ts
     * // Convert ISO date strings to Date objects
     * const options = {
     *   reviver: (key, value) => {
     *     if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value)) {
     *       return new Date(value)
     *     }
     *     return value
     *   }
     * }
     * ```
     */
    reviver?: JsonReviver | undefined;
    /**
     * Whether to throw on parse errors.
     * When `false`, returns `undefined` instead of throwing.
     *
     * @default true
     *
     * @example
     * ```ts
     * // Throws error
     * jsonParse('invalid', { throws: true })
     *
     * // Returns undefined
     * const result = jsonParse('invalid', { throws: false })
     * ```
     */
    throws?: boolean | undefined;
}
/**
 * Check if a value is a JSON primitive type.
 * JSON primitives are: `null`, `boolean`, `number`, or `string`.
 *
 * @param value - Value to check
 * @returns `true` if value is a JSON primitive, `false` otherwise
 *
 * @example
 * ```ts
 * isJsonPrimitive(null) // => true
 * isJsonPrimitive(true) // => true
 * isJsonPrimitive(42) // => true
 * isJsonPrimitive('hello') // => true
 * isJsonPrimitive({}) // => false
 * isJsonPrimitive([]) // => false
 * isJsonPrimitive(undefined) // => false
 * ```
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function isJsonPrimitive(value: unknown): value is JsonPrimitive;
/**
 * Parse JSON content with automatic Buffer handling and BOM stripping.
 * Provides safer JSON parsing with helpful error messages and optional error suppression.
 *
 * Features:
 * - Automatic UTF-8 Buffer conversion
 * - BOM (Byte Order Mark) stripping for cross-platform compatibility
 * - Enhanced error messages with filepath context
 * - Optional error suppression (returns `undefined` instead of throwing)
 * - Optional reviver for transforming parsed values
 *
 * @param content - JSON string or Buffer to parse
 * @param options - Optional parsing configuration
 * @returns Parsed JSON value, or `undefined` if parsing fails and `throws` is `false`
 *
 * @throws {SyntaxError} When JSON is invalid and `throws` is `true` (default)
 *
 * @example
 * ```ts
 * // Basic usage
 * const data = jsonParse('{"name":"example"}')
 * console.log(data.name) // => 'example'
 *
 * // Parse Buffer with UTF-8 BOM
 * const buffer = Buffer.from('\uFEFF{"value":42}')
 * const data = jsonParse(buffer)
 * console.log(data.value) // => 42
 *
 * // Enhanced error messages with filepath
 * try {
 *   jsonParse('invalid', { filepath: 'config.json' })
 * } catch (err) {
 *   console.error(err.message)
 *   // => "config.json: Unexpected token i in JSON at position 0"
 * }
 *
 * // Suppress errors
 * const result = jsonParse('invalid', { throws: false })
 * console.log(result) // => undefined
 *
 * // Transform values with reviver
 * const json = '{"created":"2024-01-15T10:30:00Z"}'
 * const data = jsonParse(json, {
 *   reviver: (key, value) => {
 *     if (key === 'created' && typeof value === 'string') {
 *       return new Date(value)
 *     }
 *     return value
 *   }
 * })
 * console.log(data.created instanceof Date) // => true
 * ```
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function jsonParse(content: string | Buffer, options?: JsonParseOptions | undefined): JsonValue | undefined;
