/**
 * Traverse Object Utility
 *
 * TypeScript port of yt-dlp's traverse_obj function for safe nested object traversal.
 * Provides defensive extraction that won't crash on missing keys.
 *
 * @see https://github.com/yt-dlp/yt-dlp/blob/master/yt_dlp/utils/traversal.py
 */
/**
 * Type for path keys - can be string, number, regex, function, or special symbols
 */
export type PathKey = string | number | RegExp | ((obj: unknown, key: string | number) => boolean) | typeof TRAVERSE_ALL | typeof TRAVERSE_FIRST | typeof TRAVERSE_REQUIRE;
/**
 * Special traversal symbols
 */
export declare const TRAVERSE_ALL: unique symbol;
export declare const TRAVERSE_FIRST: unique symbol;
export declare const TRAVERSE_REQUIRE: unique symbol;
/**
 * Path specification - array of keys to traverse
 */
export type TraversePath = PathKey[];
/**
 * Options for traverse_obj
 */
export interface TraverseOptions<T> {
    /** Default value if path not found */
    default?: T;
    /** Expected type - filter results to this type */
    expectedType?: 'string' | 'number' | 'boolean' | 'object' | 'array' | ((val: unknown) => val is T);
    /** Whether to get all matching values (default: true for arrays) */
    getAll?: boolean;
    /** Case-insensitive key matching (default: true) */
    caseSensitive?: boolean;
    /** Allow traversing into strings (default: false) */
    traverseString?: boolean;
}
/**
 * Safely traverse nested objects and arrays
 *
 * Unlike direct property access, this won't throw on missing keys.
 * Supports multiple paths (tries each until one succeeds).
 *
 * @example
 * // Basic usage
 * traverseObj(data, ['response', 'items', 0, 'title'])
 *
 * @example
 * // Multiple paths (fallback)
 * traverseObj(data, ['title'], ['name'], ['headline'])
 *
 * @example
 * // With regex key matching
 * traverseObj(data, ['items', /^item_\d+$/, 'value'])
 *
 * @example
 * // With type filtering
 * traverseObj(data, ['price'], { expectedType: 'number' })
 *
 * @example
 * // Get all values
 * traverseObj(data, ['items', TRAVERSE_ALL, 'name'], { getAll: true })
 */
export declare function traverseObj<T = unknown>(obj: unknown, ...args: (TraversePath | TraverseOptions<T>)[]): T | T[] | undefined;
/**
 * Shorthand for getting a single value
 */
export declare function getFirst<T = unknown>(obj: unknown, ...paths: TraversePath[]): T | undefined;
/**
 * Shorthand for getting all matching values
 */
export declare function getAll<T = unknown>(obj: unknown, path: TraversePath): T[];
/**
 * Get a string value, returns undefined if not a string
 */
export declare function getString(obj: unknown, ...paths: TraversePath[]): string | undefined;
/**
 * Get a number value, returns undefined if not a number
 */
export declare function getNumber(obj: unknown, ...paths: TraversePath[]): number | undefined;
/**
 * Get a boolean value, returns undefined if not a boolean
 */
export declare function getBoolean(obj: unknown, ...paths: TraversePath[]): boolean | undefined;
/**
 * Get an array value, returns undefined if not an array
 */
export declare function getArray<T = unknown>(obj: unknown, ...paths: TraversePath[]): T[] | undefined;
/**
 * Get an object value, returns undefined if not an object
 */
export declare function getObject(obj: unknown, ...paths: TraversePath[]): Record<string, unknown> | undefined;
/**
 * Check if a path exists in an object
 */
export declare function hasPath(obj: unknown, path: TraversePath): boolean;
/**
 * Extract multiple fields from an object
 *
 * @example
 * extractFields(data, {
 *   title: [['name'], ['title'], ['headline']],
 *   price: [['price'], ['cost'], ['amount']],
 *   image: [['image'], ['thumbnail'], ['photo']],
 * })
 */
export declare function extractFields<T extends Record<string, TraversePath[]>>(obj: unknown, fieldPaths: T): {
    [K in keyof T]: unknown;
};
/**
 * Safely get nested property using dot notation
 * Simpler alternative to traverseObj for basic cases
 *
 * @example
 * get(data, 'response.items.0.title')
 * get(data, 'response.items[0].title')
 */
export declare function get<T = unknown>(obj: unknown, path: string, defaultValue?: T): T | undefined;
/**
 * Set a nested property value (immutably)
 * Returns a new object with the value set
 */
export declare function setPath<T>(obj: T, path: TraversePath, value: unknown): T;
export default traverseObj;
//# sourceMappingURL=traverse-obj.d.ts.map