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

/**
 * Contains an information inferred from the parquet files.
 *
 * @since 5.0
 * @see [getParquetLayerInfo()](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-support-parquetUtils.html#getParquetLayerInfo)
 */
export interface ParquetLayerInfo {
  /**
   * A collection of URLs pointing to the parquet files.
   *
   * @since 5.0
   */
  urls: Collection<string>;
  /**
   * The fields derived from the parquet files.
   *
   * @since 5.0
   */
  fields?: Field[];
  /**
   * The encoding format used to store geometries in the parquet files.
   *  See [ParquetLayer.geometryEncoding](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-ParquetLayer.html#geometryEncoding) for more information.
   *
   * @since 5.0
   */
  geometryEncoding?: ParquetGeometryEncodingUnion | null;
  /**
   * The geometry type of the features in the layer.
   *
   * @since 5.0
   */
  geometryType?: ParquetGeometryType | null;
  /**
   * The spatial reference of the layer.
   *
   * @since 5.0
   */
  spatialReference?: SpatialReference;
}

/**
 * The geometry type of the layer’s features, inferred from the Parquet file and returned by [getParquetLayerInfo()](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-support-parquetUtils.html#getParquetLayerInfo).
 *
 * @see [ParquetLayer.geometryType](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-ParquetLayer.html#geometryType)
 */
export type ParquetGeometryType = "point" | "polygon" | "polyline" | "multipoint";

/** Options for the [getParquetLayerInfo()](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-support-parquetUtils.html#getParquetLayerInfo) function. */
export interface ParquetLayerInfoOptions extends AbortOptions {
  /** A list of key-value pairs of parameters to append to the url. */
  customParameters?: CustomParameters | null;
}

/**
 * Retrieves information about a [ParquetLayer](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-ParquetLayer.html) from the first parquet file in the specified URLs array.
 * Throws an error if the parquet file is empty or if the information cannot be determined.
 *
 * @param urls - An array of URLs pointing to parquet files. At least one url must be provided.
 * @param options - An object specifying additional options. See [ParquetLayerInfoOptions](https://developers.arcgis.com/javascript/latest/api-reference/esri-layers-support-parquetUtils.html#ParquetLayerInfoOptions) for details.
 * @returns A promise that resolves to the parquet layer information.
 * @example
 * const urls = ["url-to-your-parquet-file.parquet"];
 * const info = await parquetUtils.getParquetLayerInfo(urls);
 *
 * // create new parquet layer using the retrieved info
 * const layer = new ParquetLayer(info);
 */
export function getParquetLayerInfo(urls: string[], options?: ParquetLayerInfoOptions): Promise<ParquetLayerInfo>;