hyperformula/typings/DependencyGraph/AddressMapping/AddressMapping.d.ts

HyperFormula is a JavaScript engine for efficient processing of spreadsheet-like data and formulas

/**
 * @license
 * Copyright (c) 2025 Handsoncode. All rights reserved.
 */
import { SimpleCellAddress } from '../../Cell';
import { RawCellContent } from '../../CellContentParser';
import { InterpreterValue } from '../../interpreter/InterpreterValue';
import { Maybe } from '../../Maybe';
import { SheetBoundaries } from '../../Sheet';
import { ColumnsSpan, RowsSpan } from '../../Span';
import { CellVertex } from '../Vertex';
import { ChooseAddressMapping } from './ChooseAddressMappingPolicy';
import { AddressMappingStrategy } from './AddressMappingStrategy';
/**
 * Options for adding a sheet to the address mapping.
 */
export interface AddressMappingAddSheetOptions {
    throwIfSheetAlreadyExists: boolean;
}
export interface AddressMappingGetCellOptions {
    throwIfSheetNotExists?: boolean;
    throwIfCellNotExists?: boolean;
}
/**
 * Manages cell vertices and provides access to vertex by SimpleCellAddress.
 * For each sheet it stores vertices according to AddressMappingStrategy: DenseStrategy or SparseStrategy.
 *
 * Pleceholder sheets:
 * - for placeholders sheets (sheets that are used in formulas but not yet added), it stores placeholder strategy entries (DenseStrategy(0, 0))
 * - placeholder strategy entries may contain EmptyCellVertex-es but never ValueCellVertex or FormulaVertex as they content is empty
 * - vertices in placeholder strategy entries are used only for dependency tracking
 */
export declare class AddressMapping {
    private readonly policy;
    private mapping;
    constructor(policy: ChooseAddressMapping);
    /**
     * Gets the cell vertex at the specified address.
     */
    getCell(address: SimpleCellAddress, options?: AddressMappingGetCellOptions): Maybe<CellVertex>;
    /**
     * Gets the cell vertex at the specified address or throws if it doesn't exist.
     * @throws {NoSheetWithIdError} if sheet doesn't exist
     * @throws {Error} if cell doesn't exist
     */
    getCellOrThrow(address: SimpleCellAddress): CellVertex;
    /**
     * Gets the address mapping strategy for the specified sheet.
     * @throws {NoSheetWithIdError} if sheet doesn't exist
     */
    getStrategyForSheetOrThrow(sheetId: number): AddressMappingStrategy;
    /**
     * Adds a new sheet with the specified strategy.
     * @throws {Error} if sheet is already added and throwIfSheetAlreadyExists is true
     */
    addSheetWithStrategy(sheetId: number, strategy: AddressMappingStrategy, options?: AddressMappingAddSheetOptions): AddressMappingStrategy;
    /**
     * Adds a sheet or changes the strategy for an existing sheet.
     * Designed for the purpose of exchanging the placeholder strategy for a real strategy.
     */
    addSheetOrChangeStrategy(sheetId: number, sheetBoundaries: SheetBoundaries): AddressMappingStrategy;
    /**
     * Moves the content of the source strategy to the target strategy.
     */
    private moveStrategyContent;
    /**
     * Adds a sheet and sets the strategy based on the sheet boundaries.
     * @throws {Error} if sheet already exists and throwIfSheetAlreadyExists is true
     */
    addSheetAndSetStrategyBasedOnBoundaries(sheetId: number, sheetBoundaries: SheetBoundaries, options?: AddressMappingAddSheetOptions): void;
    /**
     * Creates a strategy based on the sheet boundaries.
     */
    private createStrategyBasedOnBoundaries;
    /**
     * Adds a placeholder strategy (DenseStrategy) for a sheet. If the sheet already exists, does nothing.
     */
    addSheetStrategyPlaceholderIfNotExists(sheetId: number): void;
    /**
     * Removes a sheet from the address mapping.
     * If sheet does not exist, does nothing.
     * @returns {boolean} true if sheet was removed, false if it did not exist.
     */
    removeSheetIfExists(sheetId: number): boolean;
    /**
     * Gets the interpreter value of a cell at the specified address.
     * @returns {InterpreterValue} The interpreter value (returns EmptyValue if cell doesn't exist)
     */
    getCellValue(address: SimpleCellAddress): InterpreterValue;
    /**
     * Gets the raw cell content at the specified address.
     * @returns {RawCellContent} The raw cell content or null if cell doesn't exist or is not a value cell
     */
    getRawValue(address: SimpleCellAddress): RawCellContent;
    /**
     * Sets a cell vertex at the specified address.
     * @throws {Error} if sheet not initialized
     */
    setCell(address: SimpleCellAddress, newVertex: CellVertex): void;
    /**
     * Moves a cell from source address to destination address.
     * Supports cross-sheet moves (used for placeholder sheet merging).
     * @throws {Error} if source sheet not initialized
     * @throws {Error} if destination occupied
     * @throws {Error} if source cell doesn't exist
     */
    moveCell(source: SimpleCellAddress, destination: SimpleCellAddress): void;
    /**
     * Removes a cell at the specified address.
     * @throws Error if sheet not initialized
     */
    removeCell(address: SimpleCellAddress): void;
    /**
     * Checks if a cell exists at the specified address.
     */
    has(address: SimpleCellAddress): boolean;
    /**
     * Gets the height of the specified sheet.
     */
    getSheetHeight(sheetId: number): number;
    /**
     * Gets the width of the specified sheet.
     */
    getSheetWidth(sheetId: number): number;
    /**
     * Adds rows to a sheet.
     */
    addRows(sheetId: number, row: number, numberOfRows: number): void;
    /**
     * Removes rows from a sheet.
     */
    removeRows(removedRows: RowsSpan): void;
    /**
     * Adds columns to a sheet starting at the specified column index.
     */
    addColumns(sheetId: number, column: number, numberOfColumns: number): void;
    /**
     * Removes columns from a sheet.
     */
    removeColumns(removedColumns: ColumnsSpan): void;
    /**
     * Returns an iterator of cell vertices within the specified rows span.
     */
    verticesFromRowsSpan(rowsSpan: RowsSpan): IterableIterator<CellVertex>;
    /**
     * Returns an iterator of cell vertices within the specified columns span.
     */
    verticesFromColumnsSpan(columnsSpan: ColumnsSpan): IterableIterator<CellVertex>;
    /**
     * Returns an iterator of address-vertex pairs within the specified rows span.
     */
    entriesFromRowsSpan(rowsSpan: RowsSpan): IterableIterator<[SimpleCellAddress, CellVertex]>;
    /**
     * Returns an iterator of address-vertex pairs within the specified columns span.
     */
    entriesFromColumnsSpan(columnsSpan: ColumnsSpan): IterableIterator<[SimpleCellAddress, CellVertex]>;
    /**
     * Returns an iterator of all address-vertex pairs across all sheets.
     * @returns {IterableIterator<[SimpleCellAddress, Maybe<CellVertex>]>} Iterator of [address, vertex] tuples
     */
    entries(): IterableIterator<[SimpleCellAddress, Maybe<CellVertex>]>;
    /**
     * Returns an iterator of address-vertex pairs for a specific sheet.
     * @returns {IterableIterator<[SimpleCellAddress, CellVertex]>} Iterator of [address, vertex] tuples
     * @throws {NoSheetWithIdError} if sheet doesn't exist
     */
    sheetEntries(sheetId: number): IterableIterator<[SimpleCellAddress, CellVertex]>;
    /**
     * Checks if a sheet has any entries.
     * @throws {NoSheetWithIdError} if sheet doesn't exist
     */
    hasAnyEntries(sheetId: number): boolean;
}