DataFrame Operations

/**
 * Creates a DataFrame from partial data structure
 * @param data - Partial DataFrame with name, fields, and metadata
 * @returns Complete DataFrame with computed length and field defaults
 */
function createDataFrame(data: PartialDataFrame): DataFrame;

/**
 * Creates a DataFrame from array data
 * @param source - Array of objects or simple values
 * @param names - Optional field names for ordering (source must be array of objects)
 * @returns DataFrame with inferred field types
 */
function arrayToDataFrame(source: Array<Record<string, unknown>> | unknown[], names?: string[]): DataFrame;

/**
 * Converts various data formats to DataFrame
 * @param data - Legacy table data, time series, or other formats
 * @returns Normalized DataFrame
 */
function toDataFrame(data: any): DataFrame;

import { createDataFrame, FieldType } from "@grafana/data";

// Create from structured data
const frame = createDataFrame({
  name: "Sales Data",
  fields: [
    { name: "month", type: FieldType.string, values: ["Jan", "Feb", "Mar"] },
    { name: "sales", type: FieldType.number, values: [100, 150, 200] },
    { name: "target", type: FieldType.number, values: [120, 140, 180] }
  ]
});

// Create from array of objects
const arrayFrame = arrayToDataFrame([
  { name: "Alice", score: 95, active: true },
  { name: "Bob", score: 87, active: false },
  { name: "Charlie", score: 92, active: true }
]);

/**
 * Mutable DataFrame implementation allowing dynamic field and row manipulation
 */
class MutableDataFrame<T = any> implements DataFrame {
  constructor(source?: DataFrameDTO | DataFrame);
  
  /** Add a new field to the DataFrame */
  addField(field: Field): void;
  /** Add a new row of values */
  add(value: T): void;
  /** Set values for a complete row */
  set(index: number, value: T): void;
  /** Get values for a specific row */
  get(index: number): T;
  /** Remove a row by index */
  delete(index: number): void;
}

/**
 * DataFrame backed by arrays for efficient memory usage
 * @deprecated use arrayToDataFrame function instead
 */
class ArrayDataFrame<T = any> implements DataFrame {
  constructor(source: T[], names?: string[]);
}

/**
 * Real-time streaming DataFrame for live data updates
 */
class StreamingDataFrame implements DataFrame {
  constructor(frame: DataFrame, options?: StreamingFrameOptions);
  
  /** Push new data points to the streaming frame */
  push(data: any[]): void;
  /** Get the latest N data points */
  getLatest(count: number): DataFrame;
}

/**
 * Circular buffer DataFrame for fixed-size time windows
 */
class CircularDataFrame<T = Vector<any> = Vector<any>> implements DataFrame {
  constructor(options: CircularDataFrameOptions);
  
  /** Add data maintaining circular buffer behavior */
  add(data: any[]): void;
}

/**
 * Sorts DataFrame by specified field
 * @param frame - DataFrame to sort
 * @param fieldIndex - Index of field to sort by
 * @param reverse - Whether to sort in descending order
 * @returns New sorted DataFrame
 */
function sortDataFrame(frame: DataFrame, fieldIndex: number, reverse?: boolean): DataFrame;

/**
 * Reverses the row order of a DataFrame
 * @param frame - DataFrame to reverse
 * @returns New DataFrame with reversed rows
 */
function reverseDataFrame(frame: DataFrame): DataFrame;

/**
 * Gets a specific row from a DataFrame
 * @param frame - Source DataFrame
 * @param rowIndex - Index of row to retrieve
 * @returns Object with field names as keys and row values
 */
function getDataFrameRow(frame: DataFrame, rowIndex: number): any;

/**
 * Compares the structure of two DataFrames
 * @param a - First DataFrame
 * @param b - Second DataFrame
 * @returns True if structures match (same field names and types)
 */
function compareDataFrameStructures(a: DataFrame, b: DataFrame): boolean;

/**
 * Converts DataFrame to JSON representation
 * @param frame - DataFrame to serialize
 * @returns JSON representation suitable for transmission
 */
function dataFrameToJSON(frame: DataFrame): DataFrameJSON;

/**
 * Creates DataFrame from JSON representation
 * @param json - JSON data from dataFrameToJSON
 * @returns Reconstructed DataFrame
 */
function dataFrameFromJSON(json: DataFrameJSON): DataFrame;

/**
 * Converts DataFrame to Data Transfer Object
 * @param frame - Source DataFrame
 * @returns DTO with simplified structure
 */
function toDataFrameDTO(frame: DataFrame): DataFrameDTO;

/**
 * Creates filtered DTO based on predicate
 * @param frame - Source DataFrame
 * @param predicate - Function to filter rows
 * @returns Filtered DTO
 */
function toFilteredDataFrameDTO(frame: DataFrame, predicate: (index: number) => boolean): DataFrameDTO;

/**
 * Infers field type from field name and sample value
 * @param name - Field name
 * @param value - Sample value from the field
 * @returns Inferred FieldType
 */
function guessFieldTypeFromNameAndValue(name: string, value: any): FieldType;

/**
 * Determines field type from a single value
 * @param value - Value to analyze
 * @returns Appropriate FieldType
 */
function getFieldTypeFromValue(value: any): FieldType;

/**
 * Analyzes entire field to determine most appropriate type
 * @param field - Field to analyze
 * @returns Best-fit FieldType based on all values
 */
function guessFieldTypeForField(field: Field): FieldType;

/**
 * Processes all fields in a data structure to guess types
 * @param data - Data structure with fields
 * @returns Data structure with updated field types
 */
function guessFieldTypes<T extends { fields: Field[] }>(data: T): T;

/**
 * Checks if DataFrame represents time series data
 * @param frame - DataFrame to check
 * @returns True if frame has time field and value fields
 */
function isTimeSeriesFrame(frame: DataFrame): boolean;

/**
 * Checks if multiple DataFrames are all time series
 * @param frames - Array of DataFrames
 * @returns True if all frames are time series
 */
function isTimeSeriesFrames(frames: DataFrame[]): boolean;

/**
 * Locates the time field in a DataFrame
 * @param frame - DataFrame to search
 * @returns Time field or undefined if not found
 */
function getTimeField(frame: DataFrame): Field | undefined;

/**
 * Checks if any series in an array has a time field
 * @param frames - Array of DataFrames
 * @returns True if at least one frame has a time field
 */
function anySeriesWithTimeField(frames: DataFrame[]): boolean;

/**
 * Verifies if a DataFrame has a time field
 * @param frame - DataFrame to check
 * @returns True if frame contains a time field
 */
function hasTimeField(frame: DataFrame): boolean;

/**
 * Checks if a field represents time series data
 * @param field - Field to check
 * @returns True if field is time type
 */
function isTimeSeriesField(field: Field): boolean;

/**
 * Provides optimized view over DataFrame data
 */
class DataFrameView<T = any> {
  constructor(source: DataFrame);
  
  /** Get value at specific row and field */
  get(row: number): T;
  /** Iterate over all rows */
  forEach(callback: (row: T, index: number) => void): void;
  /** Map over all rows */
  map<U>(callback: (row: T, index: number) => U): U[];
  /** Filter rows based on predicate */
  filter(callback: (row: T, index: number) => boolean): T[];
}

/**
 * Caching mechanism for field lookups and indexing
 */
class FieldCache {
  constructor(source: DataFrame);
  
  /** Get field by name with caching */
  getField(name: string): Field | undefined;
  /** Get field by index with validation */
  getFieldByIndex(index: number): Field | undefined;
  /** Get all field names */
  getFieldNames(): string[];
}

/**
 * Generates unique identifier for a DataFrame row
 * @param frame - Source DataFrame
 * @param rowIndex - Index of the row
 * @returns Unique string identifier
 */
function getRowUniqueId(frame: DataFrame, rowIndex: number): string;

/**
 * Adds a new row to a DataFrame
 * @param frame - Target DataFrame (must be mutable)
 * @param values - Values for the new row
 */
function addRow(frame: MutableDataFrame, values: any[]): void;

/**
 * Core DataFrame interface representing tabular data
 */
interface DataFrame {
  /** Optional name for the DataFrame */
  name?: string;
  /** Array of fields (columns) */
  fields: Field[];
  /** Number of rows */
  length: number;
  /** Reference ID for query correlation */
  refId?: string;
  /** Metadata about the query result */
  meta?: QueryResultMeta;
}

/**
 * Partial DataFrame structure for creation
 */
interface PartialDataFrame {
  name?: string;
  fields: Array<Partial<Field>>;
  refId?: string;
  meta?: QueryResultMeta;
}

/**
 * DataFrame Data Transfer Object for serialization
 */
interface DataFrameDTO {
  name?: string;
  fields: FieldDTO[];
  refId?: string;
  meta?: QueryResultMeta;
}

/**
 * JSON representation of DataFrame
 */
interface DataFrameJSON {
  schema?: DataFrameSchema;
  data?: DataFrameData;
}

/**
 * DataFrame schema definition
 */
interface DataFrameSchema {
  name?: string;
  refId?: string;
  meta?: QueryResultMeta;
  fields: FieldSchema[];
}

/**
 * DataFrame raw data
 */
interface DataFrameData {
  values: any[][];
  entities?: FieldValueEntityLookup[];
  enums?: FieldValueEntityLookup[];
}

/**
 * Options for streaming DataFrames
 */
interface StreamingFrameOptions {
  maxLength?: number;
  maxDelta?: number;
  action?: StreamingFrameAction;
}

/**
 * Actions for streaming frame updates
 */
enum StreamingFrameAction {
  Append = 'append',
  Replace = 'replace'
}

/**
 * Field with index information
 */
interface FieldWithIndex extends Field {
  index: number;
}

/**
 * Constants for missing values
 */
const MISSING_VALUE: any;
const TIME_SERIES_VALUE_FIELD_NAME = 'Value';
const TIME_SERIES_TIME_FIELD_NAME = 'Time'; 
const TIME_SERIES_METRIC_FIELD_NAME = 'Metric';