import type { FormulaErrorValue } from "./formulaErrors.mjs";
import type { FormulaCellRef, FormulaRangeValue, FormulaScalar } from "./formulaTypes.mjs";
import type { compareFormulaScalars } from "./formulaValues.mjs";
import { isEmptyFormulaValue, toFormulaBoolean, toFormulaNumber, toFormulaText } from "./formulaValues.mjs";
/**
 * Coercion helpers shared with function implementations, so that custom
 * functions follow the same coercion rules as the built-ins.
 */
export interface FormulaFunctionCoercionHelpers {
  toNumber: typeof toFormulaNumber;
  toText: typeof toFormulaText;
  toBoolean: typeof toFormulaBoolean;
  isEmpty: typeof isEmptyFormulaValue;
  compare: typeof compareFormulaScalars;
}
export interface FormulaFunctionContext {
  coerce: FormulaFunctionCoercionHelpers;
  currentCell: FormulaCellRef;
}
export type FormulaFunctionEagerArg = FormulaScalar | FormulaErrorValue | FormulaRangeValue;
/**
 * Eager functions receive resolved values; `lazy` functions receive thunks
 * (so untaken `IF` branches are never evaluated).
 */
export type FormulaFunctionArg = FormulaFunctionEagerArg | (() => FormulaFunctionEagerArg);
export interface FormulaFunctionDefinition {
  /**
   * Canonical uppercase name; lookup is case-insensitive.
   */
  name: string;
  minArgs: number;
  /**
   * `null` means variadic.
   */
  maxArgs: number | null;
  /**
   * Arguments are delivered as thunks; the function controls their evaluation.
   */
  lazy?: boolean;
  /**
   * The function may receive `FormulaRangeValue` arguments.
   */
  acceptsRanges?: boolean;
  /**
   * Error arguments are passed through instead of short-circuiting (IFERROR, ISBLANK).
   */
  acceptsErrors?: boolean;
  /**
   * Reserved: formulas calling a volatile function are re-evaluated on every
   * recompute pass. No built-in is volatile.
   */
  volatile?: boolean;
  /**
   * One-line call signature shown by the formula editor autocomplete, e.g.
   * `SUM(value1, value2, …)`. Optional — a generic signature is derived from
   * `minArgs`/`maxArgs` when omitted.
   */
  signature?: string;
  /**
   * Short description shown by the formula editor autocomplete.
   */
  description?: string;
  /**
   * Category label used to group the function in the formula editor autocomplete.
   */
  category?: string;
  apply: (args: FormulaFunctionArg[], context: FormulaFunctionContext) => FormulaScalar | FormulaErrorValue;
}
export interface FormulaFunctionRegistry {
  get: (name: string) => FormulaFunctionDefinition | undefined;
  names: () => string[];
}
export declare const FORMULA_BUILT_IN_FUNCTIONS: readonly FormulaFunctionDefinition[];
/**
 * Static arity check shared by the evaluator and the validation layer so
 * their messages stay in sync. Returns `null` when the call is well-formed.
 */
export declare function getFormulaFunctionArityError(definition: FormulaFunctionDefinition, argCount: number): FormulaErrorValue | null;
/**
 * Builds the registry from the complete function set: passing an argument
 * REPLACES the built-ins (callers wanting built-ins plus extras spread
 * `FORMULA_BUILT_IN_FUNCTIONS` explicitly). This mirrors the
 * `aggregationFunctions` prop semantics the adapter exposes.
 */
export declare function createFormulaFunctionRegistry(functions?: readonly FormulaFunctionDefinition[]): FormulaFunctionRegistry;