hyperformula/typings/DependencyGraph/SheetMapping.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 { TranslationPackage } from '../i18n';
import { Maybe } from '../Maybe';
/**
 * Options for querying the sheet mapping.
 */
export interface SheetMappingQueryOptions {
    includePlaceholders?: boolean;
}
/**
 * Manages the sheets in the instance.
 * - Can convert between sheet names and ids and vice versa.
 * - Also stores placeholders for sheets that are used in formulas but not yet added. They are marked as isPlaceholder=true.
 * - Sheetnames thet differ only in case are considered the same. (See: canonicalizeSheetName)
 */
export declare class SheetMapping {
    /**
     * Prefix for new sheet names if no name is provided by the user
     */
    private readonly sheetNamePrefix;
    /**
     * Last used sheet ID. Used to generate new sheet IDs.
     */
    private lastSheetId;
    /**
     * Mapping from canonical sheet name to sheet ID.
     */
    private mappingFromCanonicalNameToId;
    /**
     * Mapping from sheet ID to sheet.
     */
    private allSheets;
    constructor(languages: TranslationPackage);
    /**
     * Converts sheet name to canonical/normalized form.
     * @static
     */
    static canonicalizeSheetName(sheetDisplayName: string): string;
    /**
     * Returns sheet ID for the given name. By default excludes placeholders.
     */
    getSheetId(sheetName: string, options?: SheetMappingQueryOptions): Maybe<number>;
    /**
     * Returns sheet ID for the given name. Excludes placeholders.
     *
     * @throws {NoSheetWithNameError} if the sheet with the given name does not exist.
     */
    getSheetIdOrThrowError(sheetName: string): number;
    /**
     * Returns display name for the given sheet ID. Excludes placeholders.
     *
     * @returns {Maybe<string>} the display name, or undefined if the sheet with the given ID does not exist.
     */
    getSheetName(sheetId: number): Maybe<string>;
    /**
     * Returns display name for the given sheet ID. Excludes placeholders.
     *
     * @throws {NoSheetWithIdError} if the sheet with the given ID does not exist.
     */
    getSheetNameOrThrowError(sheetId: number, options?: SheetMappingQueryOptions): string;
    /**
     * Iterates over all sheet display names. By default excludes placeholders.
     */
    iterateSheetNames(options?: SheetMappingQueryOptions): IterableIterator<string>;
    /**
     * Returns array of all sheet display names. By default excludes placeholders.
     */
    getSheetNames(options?: SheetMappingQueryOptions): string[];
    /**
     * Returns total count of sheets. By default excludes placeholders.
     */
    numberOfSheets(options?: SheetMappingQueryOptions): number;
    /**
     * Checks if sheet with given ID exists. By default excludes placeholders.
     */
    hasSheetWithId(sheetId: number, options?: SheetMappingQueryOptions): boolean;
    /**
     * Checks if sheet with given name exists (case-insensitive). Excludes placeholders.
     */
    hasSheetWithName(sheetName: string): boolean;
    /**
     * Adds new sheet with optional name and returns its ID.
     * If called with a name of an existing placeholder sheet, converts the placeholder sheet to a real sheet.
     *
     * @throws {SheetNameAlreadyTakenError} if the sheet with the given name already exists.
     */
    addSheet(newSheetDisplayName?: string): number;
    /**
     * Adds a sheet with a specific ID and name. Used for redo operations.
     * If called with a name of an existing placeholder sheet, converts the placeholder sheet to a real sheet.
     *
     * @throws {SheetNameAlreadyTakenError} if the sheet with the given name already exists.
     */
    addSheetWithId(sheetId: number, sheetDisplayName: string): void;
    /**
     * Adds a placeholder sheet with the given name if it does not exist yet
     */
    addPlaceholderIfNotExists(sheetName: string): number;
    /**
     * Adds a placeholder sheet with a specific ID and name.
     * Used for undo operations to restore previously merged placeholder sheets.
     *
     * @throws {SheetNameAlreadyTakenError} if the sheet with the given name already exists.
     */
    addPlaceholderWithId(sheetId: number, sheetDisplayName: string): void;
    /**
     *
     * Removes sheet with given ID.
     * If sheet does not exist, does nothing.
     * @returns {boolean} true if sheet was removed, false if it did not exist.
     */
    removeSheetIfExists(sheetId: number, options?: SheetMappingQueryOptions): boolean;
    /**
     * Marks sheet with given ID as a placeholder.
     * @throws {NoSheetWithIdError} if the sheet with the given ID does not exist
     */
    markSheetAsPlaceholder(sheetId: number): void;
    /**
     * Renames sheet.
     * - If called with sheetId of a placeholder sheet, throws {NoSheetWithIdError}.
     * - If newDisplayName is conflicting with an existing sheet, throws {SheetNameAlreadyTakenError}.
     * - If newDisplayName is conflicting with a placeholder sheet name, deletes the placeholder sheet and returns its id as mergedWithPlaceholderSheet.
     *
     * @throws {SheetNameAlreadyTakenError} if the sheet with the given name already exists.
     * @throws {NoSheetWithIdError} if the sheet with the given ID does not exist.
     */
    renameSheet(sheetId: number, newDisplayName: string): {
        previousDisplayName: Maybe<string>;
        mergedWithPlaceholderSheet?: number;
    };
    /**
     * Stores sheet in both internal mappings.
     * - If ID exists, it is updated. If not, it is added.
     * - If canonical name exists, it is updated. If not, it is added.
     *
     * @internal
     */
    private _storeSheetInMappings;
    /**
     * Returns sheet by ID
     *
     * @returns {Maybe<Sheet>} the sheet, or undefined if not found.
     * @internal
     */
    private _getSheet;
    /**
     * Returns sheet by name
     *
     * @returns {Maybe<Sheet>} the sheet, or undefined if not found.
     * @internal
     */
    private _getSheetByName;
    /**
     * Returns sheet by ID
     *
     * @throws {NoSheetWithIdError} if the sheet with the given ID does not exist.
     * @internal
     */
    private _getSheetOrThrowError;
}