/**
 * Provides utility functions for the [CSVLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/CSVLayer/).
 *
 * @since 4.32
 * @see [CSVLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/CSVLayer/)
 */
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/references/core/layers/support/csvUtils/#getCSVLayerInfo)
 */
export interface CSVLayerInfo {
  /** The URL to the CSV file. */
  url: string;
  /** 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 custom parameters applied to the layer. */
  customParameters?: CustomParameters | null;
}

/** Options for the [getCSVLayerInfo()](https://developers.arcgis.com/javascript/latest/references/core/layers/support/csvUtils/#getCSVLayerInfo) function. */
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 [CSVLayerInfoOptions](https://developers.arcgis.com/javascript/latest/references/core/layers/support/csvUtils/#CSVLayerInfoOptions) for details.
 * @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>;