SheetXL - v0.8.0-beta.9+sites.210.e2d420901
    Preparing search index...

    Interface INamedFormula

    A defined name owned by the calculation engine.

    Extends INamed so calc's items can flow through the aggregating INamedCollection without an adapter — an adapter would carry a second copy of each name's state, which is the duplication defined-name ownership exists to remove.

    It is both: a name (getName, getScope, isHidden) and the formula that name is bound to (getText, getReferences, evaluate). INamed.getRanges arrives from INamed and is meaningful exactly when IFormula.isReferenceOnly holds.

    interface INamedFormula {
        isIFormula: true;
        isIModel: true;
        isINamed: true;
        addListeners(
            listeners: INamed.IListeners,
            options?: IListener.Options,
        ): Remove;
        autoCorrect(): IFormula | null;
        beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
        close(): void;
        delete(): void;
        doBatch<R = any>(
            callback: (commit: ICommit) => R | Promise<R>,
            options?: string | ITransaction.OperationOptions,
        ): R | Promise<R>;
        evaluate(
            options?: number | EvaluateOptions,
        ): Promise<Scalar | IRange<Scalar>>;
        getAnchor(): CellCoords | null;
        getCalculationStatus(): ICalculation.ResultStatus;
        getComment(): string | null;
        getDependents(): Promise<ICellRanges | null>;
        getDirectDependents(): Promise<ICellRanges | null>;
        getDirectPrecedents(): Promise<ICellRanges | null>;
        getExpression(options?: FormulaTextOptions): string;
        getId(): string;
        getName(): string;
        getPartReference?(
            coords: readonly Coords[],
            home?: CellCoords | null,
        ): string | null;
        getPrecedents(): Promise<ICellRanges | null>;
        getRanges(): ICellRanges | null;
        getReferences(): ICellRanges | null;
        getScope(): string | null;
        getTokens(evalIndex?: number): readonly FormulaToken[];
        getType(): string;
        getValue(): string;
        getVersionId(): number;
        hasRefError(): boolean;
        isClosed(): boolean;
        isCompiled(): boolean;
        isDeleted(): boolean;
        isHidden(): boolean;
        isReadOnly(): boolean;
        isReferenceOnly(): boolean;
        isValid(): boolean;
        isVolatile(): Promise<boolean>;
        select(options?: ITypes.SelectOptions): Promise<INamedFormula>;
        setComment(
            comment: string | null,
            options?: ITransaction.OperationOptions,
        ): this;
        setExpression(
            expression: string,
            options?: ITransaction.OperationOptions,
        ): this;
        setHidden(hidden: boolean, options?: ITransaction.OperationOptions): this;
        setName(name: string): this;
        setReferenceAt(
            index: number,
            reference: ICellRange.Address,
            options?: string | ITransaction.OperationOptions,
        ): Promise<INamedFormula>;
        setReferenceModeAt(
            index: number,
            side?: ReferenceSide,
            mode?: number,
            options?: string | ITransaction.OperationOptions,
        ): Promise<INamedFormula>;
        shift(target: CellCoords): IFormula | null;
        toJSON(): INamed.JSON | null;
    }

    Hierarchy (View Summary)

    Index
    isIFormula isIModel isINamed
    addListeners autoCorrect beginCommit close delete doBatch evaluate getAnchor getCalculationStatus getComment getDependents getDirectDependents getDirectPrecedents getExpression getId getName getPartReference? getPrecedents getRanges getReferences getScope getTokens getType getValue getVersionId hasRefError isClosed isCompiled isDeleted isHidden isReadOnly isReferenceOnly isValid isVolatile select setComment setExpression setHidden setName setReferenceAt setReferenceModeAt shift toJSON
    isIFormula: true

    For runtime type checking.

    isIModel: true

    For runtime type checking.

    isINamed: true

    For runtime type checking.

    • Attempt Excel-style Formula AutoCorrect on an invalid formula.

      Returns IFormula | null

      A corrected, DETACHED formula (not committed anywhere — the same shape ICalculation.createFormula returns, anchored at this formula's cell), or null when this formula is already valid or no safe correction exists.

      Currently ONE deliberately narrow rule: append the missing trailing closers (], ), }) — =SUM(A1:A2 → =SUM(A1:A2), =SUM(Sales[Amount → =SUM(Sales[Amount]) — and only when the repaired text parses clean. Excel closes parens and braces but not a structured reference's brackets. A repair that would still be invalid (=SUM( → =SUM() fails arity) is never returned, nor is anything attempted for over-closed / interleaved brackets or an unterminated string. Never mutates this formula. Interactive hosts call this at commit; programmatic writes (setValue, file load) never auto-correct.

    • Batches all 'transactional' changes until they have all be committed or rolled back.

      Parameters

      • Optionaloptions: string | ITransaction.OperationOptions

        Description of the operation or additional options. Used for tracking undo/redo and history. Default Value User Operation.

      Returns ITransaction

      Any changes that are made to this object will be reflected in the local record but not committed to the transactional store until the batch is popped.

      Useful for operations that are longer running but generally not recommended as it keeps a transaction open. doBatch is the preferred option.

    • Close the record and cleans resources. Can't be undone.

      Returns void

    • Removes this named formula from its collection.

      Returns void

    • Provides a mechanism to perform a set of operations in a batch.

      Type Parameters

      • R = any

      Parameters

      • callback: (commit: ICommit) => R | Promise<R>

        A callback that performs multiple operations all within the same transaction.

      • Optionaloptions: string | ITransaction.OperationOptions

        Description of the operation or additional options. Used for tracking undo/redo and history. Default Value User Operation.

      Returns R | Promise<R>

      Writes are tracked automatically: a batch that performs no state updates (a read-only batch) is elided — the commit id is unchanged, no events fire, and nothing is added to the undo stack or commit log.

    • Return the value for a formula.

      Parameters

      Returns Promise<Scalar | IRange<Scalar>>

      ICalculation.FormulaToken.evalIndex

    • The cell this formula is anchored at — the cell its relative references are written from.

      Returns CellCoords | null

      A1 in a formula anchored at B1 means "the cell to my left"; the same text anchored at B6 means "five rows up and one left". The anchor is what makes that text unambiguous, and a caller re-siting a formula (shift) needs it to know where it is starting from.

      null for a formula with no cell of its own — a temporary formula created without coords, which evaluates in a virtual space.

    • The comment, or null if none has been set.

      Returns string | null

    • The transitive downstream of this name — everything that would recalculate if its expression changed, cells and names both.

      Returns Promise<ICellRanges | null>

      getDirectDependents walked to exhaustion across BOTH graphs (the symbol edges names ride on, and the ordinary cell graph between them), and the same distinction the cell family draws (ICell.getDependents). Direct is the blast radius of DELETING the name (those dependents go #NAME?); this is the blast radius of REDEFINING it.

      With Outer = Mid*3 and Mid = Base*2, Base reports Mid and Outer as name nodes plus every cell downstream of either. A cycle terminates and reports the names on it, this one included.

    • What references this SYMBOL — cells and names, one answer; null when nothing does. Asked of the engine, as ICell.getDirectPrecedents is.

      Returns Promise<ICellRanges | null>

      Symbol-level, not target-level. =SUM(Revenue) is a dependent of Revenue; =SUM(Sales!$B$2:$B$100) is not, even where that is exactly what Revenue designates. So named.getRanges()?.getDirectDependents() is not a substitute — it answers the address question, and for a name holding an expression (TaxRate = 0.21) there are no ranges to ask at all.

      A dependent NAME rides in the same collection as an INamedRange node: with Doubled = Base*2, Doubled is a dependent of Base as surely as any cell that names it — delete Base and every cell reading Doubled goes #NAME? too, without ever having mentioned Base. Such a member carries the isINamedRange brand; its coords are the name's ANCHOR (its defining cell), never a target, so lead with getName() when displaying one.

      This is the "is it safe to redefine or delete this name?" primitive: these are precisely the dependents that go #NAME? if the name is removed — an answer with no members at all (null) is the only genuinely-unused reading. The engine already tracks both edges — a name compiles into its own grid, and every formula that mentions one carries its id — so this is a door onto existing bookkeeping.

      Cells are reduced to regions rather than listed per cell, exactly as ICell.getDirectDependents does: a column of 400 formulas reading the name comes back as one range. Name nodes lead, cells follow.

    • What this name's body reads — cells and names, one hop, one answer; null when it reads nothing.

      Returns Promise<ICellRanges | null>

      The precedent half of the same four graph methods ICell exposes, resolved at the DEFINING anchor (the cell the body was authored from) — the same answer the Name Manager gives, since a name with relative references has no one answer until applied somewhere.

      A name the body reads rides in the collection as an INamedRange node, exactly as in getDirectDependents — Doubled = Base*2 reports the Base node plus whatever cells the body reads directly. Contrast IFormula.getReferences: that is the ordered, index-aligned reference list (the setReferenceAt currency, #REF! slots included); this is the graph answer.

    • Return the formula's expression — the text WITHOUT a leading =.

      Parameters

      Returns string

      One shape for every kind of formula, a cell's and a defined name's alike. It is the STORED shape, which is what OOXML <f> and <definedName> hold and what setExpression takes back, so read/modify/write needs no adjusting in between.

      The form with the leading = — what Excel's API answers (Range.Formula) and what a cell is entered with — is ICell.getFormulaText.

      The text is the storage form (English names, , separators) whatever language or locale is active. For the form a person reads or edits, pass { target: 'display' }.

      // With a German language pack active:
      formula.getExpression();                       // 'SUM(A1,1.5)'
      formula.getExpression({ target: 'display' });  // 'SUMME(A1;1,5)'

    • A unique stable id.

      Returns string

    • A reference to a part of this item that the given coords designate exactly, or null.

      Parameters

      • coords: readonly Coords[]

        The coords to match, sheet-qualified (scope) and in row-first order.

      • Optionalhome: CellCoords | null

        The cell of the formula the reference is for, when there is one. A reference can be written relative to it: Sales[@Amount] for a table cell in the formula's own row, and from inside the table [@Amount] and [Amount].

      Returns string | null

      • Optional

      Backs INamedCollection.getByRanges with includeParts. Some named things address regions that are not themselves names: a table's column is written Sales[Amount], its header row Sales[#Headers]. Those are structured references, not entries in the collection — there is no INamed to return for one, which is why this returns text rather than an item.

      Implemented by whatever owns the parts (a table), so the collection stays out of the business of knowing what kinds of items have insides.

    • Everything upstream of this name — getDirectPrecedents walked to exhaustion.

      Returns Promise<ICellRanges | null>

      The walk unions the body's cell-graph precedents with every name the body reaches through the symbol graph, each contributing its own body's walk; a cycle terminates and reports the names on it. One hop it deliberately does not flatten: a name referenced by an UPSTREAM CELL (X = A1*2, A1 = SomeName) is that cell's precedent, not this answer's — a tree walk crosses it through the cell's own ICell.getDirectPrecedents.

    • Returns an ordered list of ranges referenced in this formula.

      Returns ICellRanges | null

      • Returns null if there are no references.
      • These are the resolved ranges from setReferenceAt()

    • The sheet name this formula is scoped to, or null for global scope.

      Returns string | null

    • Return the formula as an array of tokenized values.

      Parameters

      • OptionalevalIndex: number

        Allows for a partial evaluation based on a token index.

      Returns readonly FormulaToken[]

      These can be used by advanced editors.

      ICalculation.FormulaToken.evalIndex

    • A string to identify the type of named item.

      Returns string

      Immutable

    • The underlying item that is being referenced.

      Returns string

      Immutable

      What T is depends on getType, and for the common case it is text. A defined name (type 'formula') is an ICalculation.INamedFormula, so this is its refers-to EXPRESSION as a string with no leading = — Sheet1!$B$4, or 0.21 for a name holding a constant. A table's is the ITable. It is never the target: the string Sheet1!$B$4 is what the name says, not the cells it designates and not what they contain.

      The two questions this is mistaken for have their own calls:

      • Which cells? getRanges — the ranges, or null for a name holding an expression.
      • What is it worth right now? ICalculation.IFormula.evaluate(), which every named formula has. Returns a Scalar for a value name and an IRange for a reference one, so there is no parse-the-text-and-re-query hop. Note that a name written with relative references evaluates per calling CELL, so its one anchored answer is not the answer every dependent sees.

    • Every committed update gives the record a new, strictly increasing version id.

      Returns number

      Used with getId to uniquely identify a version of the record.

      The id is an identity, not a per-record count: ids are drawn from a single store-wide sequence bumped once per commit, so all records written in the same commit share an id and a given record's ids increase but are not sequential.

      Records are immutable so a restore/revert doesn't change them — it repoints, and the version id reported is the one for the snapshot the store is currently at. Version ids are never reused: a write after an undo receives an id higher than any previously issued, so a stale reader can always detect the change.

    • Whether any reference in this formula is unresolvable — #REF!.

      Returns boolean

      Asks the compiled references, not the text: a "#REF!" STRING literal in the formula is not a reference error. A reference degrades to one when its target is deleted, or when a shift pushes a relative reference above or left of the sheet.

    • Returns true if no more operations are allowed.

      Returns boolean

    • Whether the calculation engine has compiled this formula.

      Returns boolean

      A formula is model state: it is stored, and reads back, the moment it is set - in every engine state, a stopped or never-started one included. The COMPILED body arrives when the engine gets to it. Until then this is false; getExpression answers from the text as written, getTokens is empty, getReferences is null, a reference edit throws, and evaluate waits for a Starting engine and rejects on an Off one rather than starting it. The handle heals: it reads the engine's block the first time one exists, so one taken cold is fully functional once the engine has compiled the cell.

      A formula created detached (ICalculation.createFormula) or a defined name is compiled on creation and is always true.

    • If the model unable to be modified.

      Returns boolean

    • If true the name is not shown in the UI. This does not affect resolution in formulas.

      Returns boolean

    • If the model unable to be modified.

      Returns boolean

    • Returns true if the formula consists entirely of cell or range references and range operators (:, , #, etc.) with no function calls or computed expressions.

      Returns boolean

      A pure-reference formula always resolves to a range, making it suitable for use as a navigation target. Named formulas that return true can meaningfully implement getRanges().

    • Whether the formula text parsed without error. false for an in-progress / malformed formula (=SUM(, =A1:, =1+) — the parser recovered a best-effort token stream but the input isn't a complete expression. This is a PARSE concern only: a well-formed formula that evaluates to an error (=1/0) is still valid. Lets an editor flag "more input expected" without re-parsing.

      Returns boolean

    • Returns true if this formula contains one or more volatile functions (e.g. NOW, RAND, OFFSET, INDIRECT).

      Returns Promise<boolean>

      • Volatile formulas are re-evaluated on every calculation cycle regardless of whether their inputs have changed.
      • This is a runtime property tracked by the calculation engine — it cannot be derived from static AST analysis alone.
      • Named formulas where isVolatile() is true should not be used as navigation targets even if isReferenceOnly() returns true, since their resolved range may differ by context.
      • Asked of the engine: resolves in order behind the writes made before it, and false while the engine is Off.

    • Redefines the expression this name is bound to.

      Parameters

      Returns this

      A redefinition, not a replacement: the stable symbol id is unchanged, so formulas referencing this name pick up the new expression rather than going #NAME?. A leading = is optional — a bare range address is simply a reference expression.

    • Renames this defined name.

      Parameters

      • name: string

      Returns this

      A rename, not a redefinition: the stable symbol id is unchanged, so formulas that reference this name keep resolving and re-render with the new text.

    • Replaces a specific reference in the formula with a new one.

      Parameters

      • index: number

        The zero-based index of the reference to be updated (from getReferences()).

      • reference: ICellRange.Address

        The new address or range to occupy that position.

      • Optionaloptions: string | ITransaction.OperationOptions

        Optional transaction or operation options.

      Returns Promise<INamedFormula>

      Error is index is out of bounds relative to getReferences().

      This is the primary way to "refactor" a formula—for example, if a user drags a highlighted range in the UI to a new location.

    • Cycles the absolute/relative ($) style of the reference at the specified index.

      Parameters

      • index: number

        The zero-based index of the reference to be cycled (from getReferences()).

      • Optionalside: ReferenceSide

        Which part of the reference to cycle (relative to a range operator :):

        • 'self' (default) — the reference has no range operator (a single cell); cycles the whole reference as a unit, keeping it a single cell.
        • 'left' — the left operand of a range (the "start" corner).
        • 'right' — the right operand of a range (the "end" corner). A single-cell range (e.g. A1:A1) is still a range — it has a 'left' and a 'right', so it is NOT 'self'. That distinction only survives in the tokens (see FormulaToken.refSide).
      • Optionalmode: number

        Optional target mode. If omitted, cycles to the next mode in the sequence.

      • Optionaloptions: string | ITransaction.OperationOptions

        Optional transaction or operation options.

      Returns Promise<INamedFormula>

      The modes are:

      • 0: Absolute (e.g., $A$1)
      • 1: Absolute row, relative column (e.g., A$1)
      • 2: Absolute column, relative row (e.g., $A1)
      • 3: Relative (e.g., A1)
      • This is the F4 Cycle behavior commonly found in spreadsheet editors.

    • This formula as it would read at target: a DETACHED copy, filled.

      Parameters

      • target: CellCoords

        The cell the copy is anchored at.

      Returns IFormula | null

      The filled copy, or null when this formula has no compiler behind it to mint one.

      Excel's fill/copy, not its move: relative references follow the formula to its new home and absolute ($) ones stay put, so the copy means at target what this one means at its own anchor. A1*2 anchored at B1, shifted to B6, is A6*2.

      The distinction matters and is easy to invert. Re-compiling getExpression's text at another cell keeps the TEXT and changes the meaning — that is a move, and a formula that meant "myself" starts meaning "some cells up". This keeps the meaning and changes the text.

      Nothing is committed; the copy is anchored at target whether or not anything lives there.

    Settings
    Member Visibility

    On This Page
    Properties
    Methods