Data Transformations

/**
 * Applies transformations to DataFrames
 * @param options - Transformation context with config and data
 * @returns Observable stream of transformed DataFrames
 */
function transformDataFrame(options: DataTransformContext): Observable<DataFrame[]>;

/**
 * Registry of standard transformations
 */
const standardTransformers: Registry<DataTransformerInfo>;

/**
 * Registry for transformer registration and management
 */
const standardTransformersRegistry: Registry<TransformerRegistryItem>;

/**
 * Reduces field values to a single calculated value
 * @param field - Field to reduce
 * @param id - Reducer ID (calculation type)
 * @param nullValueMode - How to handle null values
 * @returns Reduced value
 */
function reduceField(field: Field, id: ReducerID, nullValueMode?: NullValueMode): ReduceDataOptions;

/**
 * Checks if string is a valid reducer ID
 * @param id - ID to check
 * @returns True if valid reducer ID
 */
function isReducerID(id: string): id is ReducerID;

/**
 * Registry of field reducers (calculations)
 */
const fieldReducers: Registry<FieldReducerInfo>;

/**
 * Default calculation types for field reduction
 */
const defaultCalcs: ReducerID[];

/**
 * Performs standard calculations on field values
 * @param values - Array of values to calculate
 * @returns Object with calculation results
 */
function doStandardCalcs(values: number[]): { [key: string]: number };

import { reduceField, fieldReducers, ReducerID } from "@grafana/data";

// Reduce field to mean value
const avgValue = reduceField(temperatureField, ReducerID.mean);

// Get all available reducers
const allReducers = fieldReducers.list();

// Perform multiple calculations
const calculations = doStandardCalcs([1, 2, 3, 4, 5]);
// Result: { mean: 3, sum: 15, count: 5, min: 1, max: 5, ... }

/**
 * Gets field matcher by ID
 * @param id - Field matcher ID
 * @returns Field matcher function
 */
function getFieldMatcher(id: FieldMatcherID): FieldMatcher;

/**
 * Gets frame matchers
 * @returns Array of frame matcher info
 */
function getFrameMatchers(): FrameMatcherInfo[];

/**
 * Gets value matcher by ID
 * @param id - Value matcher ID
 * @returns Value matcher function
 */
function getValueMatcher(id: ValueMatcherID): ValueMatcher;

/**
 * Collection of field matchers
 */
const fieldMatchers: Registry<FieldMatcherInfo>;

/**
 * Collection of frame matchers
 */
const frameMatchers: Registry<FrameMatcherInfo>;

/**
 * Collection of value matchers
 */
const valueMatchers: Registry<ValueMatcherInfo>;

/**
 * Applies null insertion threshold to create gaps in time series
 * @param frame - DataFrame to process
 * @param refField - Reference field for gap detection
 * @param threshold - Threshold for gap detection
 * @returns DataFrame with null values inserted for gaps
 */
function applyNullInsertThreshold(frame: DataFrame, refField?: Field, threshold?: number): DataFrame;

/**
 * Converts null values to specified value
 * @param frame - DataFrame to process
 * @param options - Null to value conversion options
 * @returns DataFrame with nulls replaced
 */
function nullToValue(frame: DataFrame, options: NullToValueOptions): DataFrame;

/**
 * Joins DataFrames using outer join strategy
 * @deprecated Use modern join transformers instead
 * @param dataFrames - Array of DataFrames to join
 * @returns Single joined DataFrame
 */
function joinDataFrames(dataFrames: DataFrame[]): DataFrame;

/**
 * Checks if vector values are likely in ascending order
 * @param values - Array of values to check
 * @returns True if values appear to be ascending
 */
function isLikelyAscendingVector(values: any[]): boolean;

/**
 * Ensures DataFrame has a time field, converting if necessary
 * @param frame - DataFrame to process
 * @returns DataFrame with guaranteed time field
 */
function ensureTimeField(frame: DataFrame): DataFrame;

/**
 * All histogram transformation functionality exported from histogram module
 * Includes functions for binning data and creating histogram DataFrames
 */
// Re-exported from histogram module - see histogram transformer documentation

/**
 * Configuration for regex or names matchers
 */
interface RegexpOrNamesMatcherOptions {
  pattern?: string;
  names?: string[];
}

/**
 * Configuration for by-names matchers
 */
interface ByNamesMatcherOptions {
  mode: ByNamesMatcherMode;
  names: string[];
  readOnly?: boolean;
}

/**
 * By-names matcher modes
 */
enum ByNamesMatcherMode {
  exclude = 'exclude',
  include = 'include'
}

/**
 * Field value matcher configuration
 */
interface FieldValueMatcherConfig {
  id: string;
  options?: any;
}

/**
 * Value matcher options base interface
 */
interface ValueMatcherOptions {
  value: any;
}

/**
 * Basic value matcher options
 */
interface BasicValueMatcherOptions extends ValueMatcherOptions {
  value: string | number;
}

/**
 * Range value matcher options
 */
interface RangeValueMatcherOptions {
  from: number;
  to: number;
}

/**
 * Rename by regex transformer options
 */
interface RenameByRegexTransformerOptions {
  regex: string;
  renamePattern: string;
}

/**
 * Grouping to matrix transformer options
 */
interface GroupingToMatrixTransformerOptions {
  columnField?: string;
  rowField?: string;
  valueField?: string;
  emptyValue?: number;
}

/**
 * Data transformation context
 */
interface DataTransformContext {
  data: DataFrame[];
  interpolate: InterpolateFunction;
  options?: any;
}

/**
 * Data transformer information
 */
interface DataTransformerInfo<TOptions = any> {
  id: string;
  name: string;
  description: string;
  defaultOptions: TOptions;
  operator: (options: TOptions, ctx: DataTransformContext) => Observable<DataFrame[]>;
  transformer: (options: TOptions) => (source: Observable<DataFrame[]>) => Observable<DataFrame[]>;
}

/**
 * Synchronous data transformer
 */
interface SynchronousDataTransformerInfo<TOptions = any> extends Omit<DataTransformerInfo<TOptions>, 'transformer'> {
  transformer: (options: TOptions) => (data: DataFrame[]) => DataFrame[];
}

/**
 * Custom transform operator
 */
type CustomTransformOperator<TOptions> = (options: TOptions, ctx: DataTransformContext) => Observable<DataFrame[]>;

/**
 * Data transformer configuration
 */
interface DataTransformerConfig<TOptions = any> {
  id: string;
  disabled?: boolean;
  options: TOptions;
  filter?: MatcherConfig;
}

/**
 * Matcher configuration
 */
interface MatcherConfig<TOptions = any> {
  id: string;
  options?: TOptions;
}

/**
 * Field matcher function type
 */
type FieldMatcher = (field: Field, frame: DataFrame, allFrames: DataFrame[]) => boolean;

/**
 * Frame matcher function type
 */
type FrameMatcher = (frame: DataFrame, allFrames: DataFrame[]) => boolean;

/**
 * Value matcher function type
 */
type ValueMatcher = (valueIndex: number, field: Field, frame: DataFrame, allFrames: DataFrame[]) => boolean;

/**
 * Field matcher information
 */
interface FieldMatcherInfo<TOptions = any> {
  id: FieldMatcherID;
  name: string;
  description: string;
  defaultOptions?: TOptions;
  get: (options?: TOptions) => FieldMatcher;
}

/**
 * Frame matcher information
 */
interface FrameMatcherInfo<TOptions = any> {
  id: FrameMatcherID;
  name: string;
  description: string;
  defaultOptions?: TOptions;
  get: (options?: TOptions) => FrameMatcher;
}

/**
 * Value matcher information
 */
interface ValueMatcherInfo<TOptions = any> {
  id: ValueMatcherID;
  name: string;
  description: string;
  defaultOptions?: TOptions;
  get: (options?: TOptions) => ValueMatcher;
}

/**
 * Field reducer information
 */
interface FieldReducerInfo {
  id: ReducerID;
  name: string;
  description: string;
  standard: boolean;
  aliasIds?: string[];
  reduce?: (field: Field, ignoreNulls: boolean, nullAsZero: boolean) => ReduceDataOptions;
}

/**
 * Transformation applicability levels
 */
enum TransformationApplicabilityLevels {
  NotApplicable = 0,  
  Manual = 1,
  Suggested = 2
}

/**
 * Transformation applicability score
 */
type TransformationApplicabilityScore = TransformationApplicabilityLevels;

/**
 * Transformer registry item
 */
interface TransformerRegistryItem<TOptions = any> {
  id: string;
  category: TransformerCategory;
  name: string;
  description: string;
  state: FeatureState;
  transformation: DataTransformerInfo<TOptions>;
  help?: string;
  applicability?: (data: DataFrame[]) => TransformationApplicabilityScore;
}

/**
 * Transformer UI properties
 */
interface TransformerUIProps<T> {
  options: T;
  onChange: (options: T) => void;
  input: DataFrame[];
}

/**
 * Transformer categories
 */
enum TransformerCategory {
  Combine = 'combine',
  Calculate = 'calculate',
  Filter = 'filter',
  Reformat = 'reformat',
  Spatial = 'spatial'
}

/**
 * Reducer IDs (calculation types)
 */
enum ReducerID {
  sum = 'sum',
  max = 'max',
  min = 'min',
  logmin = 'logmin',
  mean = 'mean',
  last = 'last',
  first = 'first',
  count = 'count',
  range = 'range',
  diff = 'diff',
  delta = 'delta',
  step = 'step',
  firstNotNull = 'firstNotNull',
  lastNotNull = 'lastNotNull',
  changeCount = 'changeCount',
  distinctCount = 'distinctCount',
  allIsZero = 'allIsZero',
  allIsNull = 'allIsNull',
  variance = 'variance',
  stdDev = 'stdDev',
  allValues = 'allValues'
}

/**
 * Data transformer IDs
 */
enum DataTransformerID {
  append = 'append',
  reduce = 'reduce',
  order = 'order',
  organize = 'organize',
  rename = 'rename',
  calculateField = 'calculateField',
  joinByField = 'joinByField',
  seriesToRows = 'seriesToRows',
  concatenate = 'concatenate',
  merge = 'merge',
  limit = 'limit',
  sortBy = 'sortBy',
  noop = 'noop',
  filterByName = 'filterByName',
  filterByRefId = 'filterByRefId',
  filterByValue = 'filterByValue',
  convertFieldType = 'convertFieldType',
  ensureColumns = 'ensureColumns',
  groupBy = 'groupBy',
  pivot = 'pivot',
  histogram = 'histogram'
}

/**
 * Matcher IDs
 */
enum MatcherID {
  anyMatch = 'anyMatch',
  allMatch = 'allMatch',
  invertMatch = 'invertMatch'
}

/**
 * Field matcher IDs
 */
enum FieldMatcherID {
  numeric = 'numeric',
  time = 'time',  
  first = 'first',
  firstTimeField = 'firstTimeField',
  byName = 'byName',
  byNames = 'byNames',
  byType = 'byType',
  byTypes = 'byTypes',
  byRegexp = 'byRegexp',
  byFrameRefID = 'byFrameRefID'
}

/**
 * Frame matcher IDs
 */
enum FrameMatcherID {
  byName = 'byName',
  byIndex = 'byIndex',
  byRefId = 'byRefId'
}

/**
 * Value matcher IDs
 */
enum ValueMatcherID {
  greater = 'greater',
  greaterOrEqual = 'greaterOrEqual',
  lower = 'lower',
  lowerOrEqual = 'lowerOrEqual',
  equal = 'equal',
  notEqual = 'notEqual',
  substring = 'substring',
  regex = 'regex',
  isNull = 'isNull',
  isNotNull = 'isNotNull',
  range = 'range'
}

/**
 * Special values for transformations
 */
enum SpecialValue {
  True = 'true',
  False = 'false',
  Null = 'null',
  Empty = 'empty'
}