/**
 * Provides utility functions for the [CSVLayer](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-CSVLayer.html).
 *
 * @since 4.32
 * @see [CSVLayer](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-CSVLayer.html)
 */
import type Field from "./Field.js";
import type { AbortOptions } from "../../core/promiseUtils.js";
import type { CustomParameters } from "../mixins/CustomParametersMixin.js";

/**
 * The layer info inferred from the CSV file.
 *
 * @see [getCSVLayerInfo()](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-support-csvUtils.html#getCSVLayerInfo)
 */
export interface CSVLayerInfo {
  /** The custom parameters applied to the layer. */
  customParameters?: CustomParameters | null;
  /** The delimiter used in the CSV file. */
  delimiter: string;
  /** The fields on the layer. */
  fields: Field[];
  /** The field name containing the latitude values. */
  latitudeField?: string;
  /** The field name containing the longitude values. */
  longitudeField?: string;
  /** The URL to the CSV file. */
  url: string;
}

export interface CSVLayerInfoOptions extends AbortOptions {
  /** A list of key-value pairs of parameters to append to the url. */
  customParameters?: CustomParameters | null;
}

/**
 * Retrieves information about a CSV layer from a given URL.
 * This function throws an error if the CSV is empty or if the delimiter cannot be detected.
 *
 * @param url - The URL of the CSV file.
 * @param options - An object specifying additional options. See the
 *   object specification table below for the properties of this object.
 * @returns A promise that resolves to the CSV layer information.
 * @example
 * const url = "https://example.com/data.csv";
 * const info = await getCSVLayerInfo(url);
 * // present to the user the fields and the delimiter, then create the layer
 * const layer = new CSVLayer(info);
 */
export function getCSVLayerInfo(url: string, options?: CSVLayerInfoOptions): Promise<CSVLayerInfo>;