/**
 * `FormulaEngine` — the facade that owns and coordinates every formula
 * subsystem (configuration, function registry, formula store, and — wired in
 * later phases — the tokenizer, parser, evaluator, dependency graph and
 * calculation engine). It is the single object the grid injects and calls.
 *
 * It is a thin coordinator: each responsibility lives in its own module, so this
 * class never becomes a God object. It depends only on the {@link
 * FormulaGridAdapter} port, never on concrete grid/DOM types, keeping the engine
 * framework-independent and unit-testable.
 *
 * @packageDocumentation
 */
import type { FormulaConfig } from '../types/formula.types';
import type { FormulaState } from './types/formula.types';
import type { ResolvedFormulaConfig } from './config/formula-config';
import { FunctionRegistry } from './functions/function-registry';
import type { FormulaFunction } from './functions/formula-function';
import type { FormulaGridAdapter } from './formula-grid-adapter';
import type { FormulaClock } from './calc/calculation-engine';
import type { NamedRangeEntry } from './named-range-manager';
import type { Offset } from './formula-transposer';
/**
 * A cell whose stored value changed, identified by the engine's native stable
 * identities. The grid integration layer translates its `{nodeId, field}`
 * changes into these before notifying the engine.
 */
export interface FormulaCellChange {
    /** Stable row identity. */
    readonly nodeId: string;
    /** Immutable column identity. */
    readonly colId: string;
}
/**
 * Outcome of a {@link FormulaEngine.setFormula} call — the set of cells whose
 * displayed value changed as a result (so the caller can repaint precisely).
 */
export interface RecalculationResult {
    /** Stable row ids of every cell whose value changed. */
    readonly changedNodeIds: ReadonlySet<string>;
}
export declare class FormulaEngine {
    private readonly adapter;
    private readonly configManager;
    private registry;
    private readonly store;
    private readonly calc;
    private readonly namedRanges;
    /**
     * @param adapter - Port giving the engine access to grid cell values and
     *                  coordinate spaces without a framework dependency.
     * @param config  - Optional initial configuration.
     * @param clock   - Optional time/random source for volatile functions
     *                  (defaults to the system clock; injected in tests).
     */
    constructor(adapter: FormulaGridAdapter, config?: FormulaConfig, clock?: FormulaClock);
    /**
     * Applies a configuration patch (merged over the current config) and returns
     * the resolved result. Newly-supplied custom functions are registered.
     *
     * @param patch - Partial public configuration.
     */
    configure(patch: FormulaConfig | undefined): ResolvedFormulaConfig;
    /** @returns The current fully-resolved configuration. */
    getConfig(): ResolvedFormulaConfig;
    /** @returns `true` when the engine is enabled (`formula.enabled`). */
    isEnabled(): boolean;
    /** @returns The function registry (for advanced/plugin use). */
    getRegistry(): FunctionRegistry;
    /**
     * Registers (or overrides) a formula function.
     *
     * @param fn - The function implementation.
     */
    registerFunction(fn: FormulaFunction): void;
    private registerConfiguredFunctions;
    /**
     * @param nodeId - Stable row identity.
     * @param colId  - Immutable column identity.
     * @returns The formula source (including `=`), or `null` if the cell has none.
     */
    getFormula(nodeId: string, colId: string): string | null;
    /**
     * @param nodeId - Stable row identity.
     * @param colId  - Immutable column identity.
     * @returns `true` when the cell holds a formula.
     */
    hasFormula(nodeId: string, colId: string): boolean;
    /**
     * Assigns (or replaces) the formula on a cell: compiles it, updates the
     * dependency graph, and recomputes the cell plus everything downstream.
     *
     * A disabled engine or a column that did not opt in (`colDef.allowFormula`)
     * is a no-op. Never throws — a malformed formula stores as `#ERROR!`.
     *
     * @param nodeId - Stable row identity.
     * @param colId  - Immutable column identity.
     * @param source - The raw formula source (including the leading `=`).
     * @returns The cells whose value changed as a result.
     */
    setFormula(nodeId: string, colId: string, source: string): RecalculationResult;
    /**
     * Removes the formula from a cell (leaving its last computed value in place)
     * and recomputes anything that depended on it.
     *
     * @param nodeId - Stable row identity.
     * @param colId  - Immutable column identity.
     * @returns `true` if a formula was removed.
     */
    clearFormula(nodeId: string, colId: string): boolean;
    /**
     * Like {@link clearFormula} but returns the cells whose value changed as a
     * result (dependents that recomputed). Used by the clipboard/fill integration.
     *
     * @param nodeId - Stable row identity.
     * @param colId  - Immutable column identity.
     */
    removeFormula(nodeId: string, colId: string): RecalculationResult;
    /**
     * Notifies the engine that one or more non-formula cells changed (from an
     * edit, paste, fill, cut or undo), so cells depending on them — plus volatile
     * cells — are recomputed.
     *
     * @param changes - The changed cells.
     * @returns The cells whose value changed as a result.
     */
    onCellsChanged(changes: readonly FormulaCellChange[]): RecalculationResult;
    /**
     * Bulk-registers many formulas (declarative discovery from column defs / row
     * data) and recomputes once. Entries whose column did not opt in
     * (`colDef.allowFormula`) are skipped. A disabled engine is a no-op. Later
     * `setFormula`/`setCellFormula` calls override any entry set here.
     *
     * @param entries - `{ nodeId, colId, source }` formulas to register.
     * @returns The cells whose value changed.
     */
    setFormulas(entries: readonly {
        nodeId: string;
        colId: string;
        source: string;
    }[]): RecalculationResult;
    /**
     * Removes every formula owned by any of the given rows (e.g. deleted rows) and
     * recomputes dependents, so structural row changes leave no orphaned formulas.
     *
     * @param nodeIds - Stable ids of the removed rows.
     * @returns The cells whose value changed.
     */
    purgeNodes(nodeIds: ReadonlySet<string>): RecalculationResult;
    /**
     * Recomputes formula cells. Volatile cells are always recomputed; when
     * `force` is `true`, every formula cell is recomputed.
     *
     * @param force - Recompute all cells, not just dirty/volatile ones.
     * @returns The cells whose value changed as a result.
     */
    recalculate(force?: boolean): RecalculationResult;
    /**
     * Adjusts a formula's relative references for a copy/fill displacement, so
     * `=A1+B1` filled down one row becomes `=A2+B2`. Absolute (`$`) parts are
     * preserved; references pushed off-grid become `#REF!`.
     *
     * @param source - The source formula (including `=`).
     * @param offset - The row/column displacement.
     * @returns The transposed source string.
     */
    transposeFormula(source: string, offset: Offset): string;
    /**
     * Defines (or replaces) a named range, then recalculates so formulas using the
     * name pick it up.
     *
     * @param name   - The name (case-insensitive).
     * @param target - Its A1-notation target (e.g. `"B1"`, `"A1:C3"`).
     * @returns The cells whose value changed.
     */
    setNamedRange(name: string, target: string): RecalculationResult;
    /**
     * Removes a named range, then recalculates.
     *
     * @param name - The name (case-insensitive).
     * @returns The cells whose value changed.
     */
    removeNamedRange(name: string): RecalculationResult;
    /** @returns All defined named ranges. */
    getNamedRanges(): NamedRangeEntry[];
    /**
     * @returns A serializable snapshot of every formula cell (sources only).
     */
    getState(): FormulaState;
    /**
     * Restores formula cells from a serialized {@link FormulaState}, replacing any
     * current formulas, then recalculates.
     *
     * @param state - A snapshot previously produced by {@link getState}.
     */
    setState(state: FormulaState): void;
    /** Releases all engine state. Called from `GridApi.destroy`. */
    destroy(): void;
}
//# sourceMappingURL=formula-engine.d.ts.map