/**
 * Provides utility functions for the [ParquetLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/ParquetLayer/).
 *
 * @since 4.33
 * @see [ParquetLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/ParquetLayer/)
 */
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 { ParquetDataUnion, ParquetGeometryEncodingUnion } from "./types.js";

/**
 * Contains an information inferred from the parquet files.
 *
 * @since 5.0
 * @see [getParquetLayerInfo()](https://developers.arcgis.com/javascript/latest/references/core/layers/support/parquetUtils/#getParquetLayerInfo)
 */
export interface ParquetLayerInfo {
  /**
   * The data backing the parquet layer.
   *
   * @since 5.0
   */
  data?: ParquetDataUnion;
  /**
   * 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/references/core/layers/ParquetLayer/#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/references/core/layers/support/parquetUtils/#getParquetLayerInfo).
 *
 * @see [ParquetLayer.geometryType](https://developers.arcgis.com/javascript/latest/references/core/layers/ParquetLayer/#geometryType)
 */
export type ParquetGeometryType = "point" | "polygon" | "polyline" | "multipoint";

/** Options for the [getParquetLayerInfo()](https://developers.arcgis.com/javascript/latest/references/core/layers/support/parquetUtils/#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/references/core/layers/ParquetLayer/) from the first Parquet file in the specified data source.
 * Throws an error if the parquet file is empty or if the information cannot be determined.
 *
 * @param data - The data source for the parquet layer. Pass a [ParquetFilesData](https://developers.arcgis.com/javascript/latest/references/core/layers/support/ParquetFilesData/), a
 * [ParquetPortalItemData](https://developers.arcgis.com/javascript/latest/references/core/layers/support/ParquetPortalItemData/), or an array of URLs pointing to parquet files for backward compatibility.
 * @param options - An object specifying additional options. See [ParquetLayerInfoOptions](https://developers.arcgis.com/javascript/latest/references/core/layers/support/parquetUtils/#ParquetLayerInfoOptions) for details.
 * @returns A promise that resolves to the parquet layer information.
 * @example
 * ```js
 * const data = new ParquetFilesData({
 *   urls: ["url-to-your-parquet-file.parquet"]
 * });
 * const info = await parquetUtils.getParquetLayerInfo(data);
 *
 * // create new parquet layer using the retrieved info
 * const layer = new ParquetLayer(info);
 * ```
 */
export function getParquetLayerInfo(data: string[] | ParquetDataUnion, options?: ParquetLayerInfoOptions): Promise<ParquetLayerInfo>;