SheetXL - v1.0.2
    Preparing search index...

    Interface ICalculation

    Calculation is the process of computing formulas and then displaying the results as values in the cells that contain the formulas.

    interface ICalculation {
        isICalculation: true;
        isIModel: true;
        start: () => Promise<void>;
        stop: () => Promise<void>;
        addListeners(
            listeners: ICalculation.IListeners,
            options?: IListener.Options,
        ): Remove;
        beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
        calculate(
            options?: boolean | CalculateOptions,
        ): Promise<ICalculation.Status>;
        cancelAsync(options?: CancelOptions): Promise<ICalculation.Status>;
        close(): void;
        createFormula(
            expression: string,
            coords?: Partial<CellCoords>,
            options?: CreateFormulaOptions,
        ): IFormula;
        delete?(options?: ITransaction.OperationOptions): void;
        doBatch<R = any>(
            callback: (commit: ICommit) => R | Promise<R>,
            options?: string | ITransaction.OperationOptions,
        ): R | Promise<R>;
        evaluate(
            expression: string,
            options?:
                | number
                | EvaluateOptions & Partial<CellCoords> & CreateFormulaOptions,
        ): Promise<Scalar | IRange<Scalar>>;
        evaluateBatch(request: BatchRequest): Promise<IRange<Scalar>[]>;
        getCalculationMode(): ICalculation.CalculationMode;
        getCalculationState(): ICalculation.CalculationState;
        getExternalBooks(): IExternalBookCollection;
        getFunctions(): IFunctionCollection;
        getId(): string;
        getIterativeCalculation(): IterativeCalculation;
        getNamedFormulas(): INamedFormulasCollection;
        getPendingCount(): number;
        getRuntime(): IRuntime;
        getStatus(): ICalculation.Status;
        getType(): string;
        getVersionId(): number;
        isCalculationRequired(): boolean;
        isClosed(): boolean;
        isDeleted(): boolean;
        isReadOnly(): boolean;
        ready(options?: CalculateOptions): Promise<ICalculation.Status>;
        setCalculationMode(mode: ICalculation.CalculationMode): this;
        setIterativeCalculation(
            options: boolean | Partial<IterativeCalculation>,
        ): this;
        toJSON(): ICalculation.JSON;
        waitUntil<T>(work: Promise<T>): Promise<T>;
        whenPendingDone(options?: { timeout?: number }): Promise<boolean>;
    }

    Hierarchy

    • IModel
      • ICalculation
    Index
    isICalculation isIModel start stop
    addListeners beginCommit calculate cancelAsync close createFormula delete? doBatch evaluate evaluateBatch getCalculationMode getCalculationState getExternalBooks getFunctions getId getIterativeCalculation getNamedFormulas getPendingCount getRuntime getStatus getType getVersionId isCalculationRequired isClosed isDeleted isReadOnly ready setCalculationMode setIterativeCalculation toJSON waitUntil whenPendingDone
    isICalculation: true

    For runtime type checking.

    isIModel: true

    For runtime type checking.

    start: () => Promise<void>

    Starts the ICalculation engine.

    • This is required to be called before any calculations can be performed.
    • This will initialize the calculation engine and prepare it for use.
    • Will fire events and return a promise when the calculation is started. (or errors);
    stop: () => Promise<void>

    Stops the ICalculation engine.

    • 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.

    • Execute a calculate on the Graph.

      Parameters

      • Optionaloptions: boolean | CalculateOptions

        The options or a boolean. If `true' a full calculation will be done.

      Returns Promise<ICalculation.Status>

      A promise that will be resolved when the calculation is completed.

      For async functions this will return before they are completed. An async function is called again unless its call is still running; what it fetches is answered from the workbook's cache unless ICalculation.CalculateOptions.external is set.

    • Stops waiting for async function calls — Excel's Cancel Refresh: each pending call the options cover is closed, and the function is told (its onCancel).

      Parameters

      • Optionaloptions: CancelOptions

        Which calls; every call when absent.

      Returns Promise<ICalculation.Status>

      A promise that resolves once the cells have been recalculated.

      • A cell keeps what it showed — its last answer, or the value its function returned while it waited — and is no longer pending. An answer that arrives later is dropped.
      • A recalculation of a cancelled cell calls its function again.

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

      Returns void

    • Parses a formula expression and returns a transient formula object.

      Parameters

      • expression: string

        The formula expression, with or without a leading =.

      • Optionalcoords: Partial<CellCoords>

        Optional anchor coordinates.

      • Optionaloptions: CreateFormulaOptions

        Optional parse options.

      Returns IFormula

      • This does not register the formula in the workbook or dependency graph.
      • The expression is read as storage text (English function names, , separators) unless options.target is 'display' — text a user typed in their language and locale.
      • Use it for:
        • interactive editing (tooltips, watches, function help)
        • condition / validation expressions
        • ad-hoc “what-if” evaluations
      calculation.createFormula('SUM(A1,1.5)');
      // With a German language pack active:
      calculation.createFormula('SUMME(A1;1,5)', undefined, { target: 'display' });

    • 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.

    • Evaluates a expression in the context of the sheet and returns the resulting value.

      Parameters

      Returns Promise<Scalar | IRange<Scalar>>

      This is similar convenience method for getCalculation().createFormula(expression).evaluate(options). The expression is read as storage text unless options.target is 'display'.

    • Evaluates several formulas over values of the caller's, in one request.

      Parameters

      Returns Promise<IRange<Scalar>[]>

      One range per formula, in the order given, the shape of its coords (a single cell included), read with local coordinates: getValueAt(0, 0) is the top-left of coords.

      • The values and formulas sit on a grid of their own, on no sheet, kept for this request only. Nothing in the workbook changes, and it is never an undo step.
      • A formula reads the values by address and may read another formula's cells; the engine orders them. Each is filled across its coords, relative references moving with it.
      • A cell that errors carries its error; the others are unaffected.
      const [margin, doubled] = await calculation.evaluateBatch({
        values: [[0, [[0, [100, 60]]]], [1, [[0, [50, 40]]]]],
        formulas: [
          { expression: 'A1-B1', coords: { rowStart: 0, colStart: 2, rowEnd: 1, colEnd: 2 } },
          { expression: 'C1*2', coords: { rowStart: 0, colStart: 3, rowEnd: 1, colEnd: 3 } }
        ]
      });
      margin.getValueAt(1, 0); // 10
      doubled.getValueAt(1, 0); // 20

    • The workbook's external books — the [n] a formula cites — in position order.

      Returns IExternalBookCollection

      Owned by the engine, as defined names are: a book is a symbol formulas bind into, and which formulas cite a book is the engine's index. Also reachable as IWorkbook.getExternalBooks().

    • A unique identifier for the record. This will never change.

      Returns string

      This enables the record to be identified across transactions and users in a collaborative environment. The id is store-issued (IStore.create); the store keys all state by it.

    • How many async function calls are waiting for an answer.

      Returns number

    • Returns IRuntime

    • Returns an immutable type string.

      Returns string

    • 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 formula is out of date — Excel's Calculate indicator in the status bar.

      Returns boolean

      Meaningful in manual mode, where edits accumulate until calculate. In automatic mode it is true only between an edit and the pass it schedules.

    • Returns true if no more operations are allowed.

      Returns boolean

    • If the model unable to be modified.

      Returns boolean

    • If the model unable to be modified.

      Returns boolean

    • Resolves once the engine is running and idle: its calculation state is ICalculation.CalculationState.Done, or ICalculation.CalculationState.Pending in manual mode (and, under AutomaticExceptTables, with only data tables out of date).

      Parameters

      • Optionaloptions: CalculateOptions

        Pass { full: true } to recalculate every grid rather than only the dirty ones.

      Returns Promise<ICalculation.Status>

      • After it, every answer the engine owes has landed: a formula written before it reads as compiled, and its value is current (in automatic mode).
      • Manual mode does not wait for a recalculation nobody has asked for; call calculate.
      • Waits for what consumers derive from the results too (waitUntil): a conditional format reads as painted after it, including one a read just asked to evaluate.
      • An async function's result in flight is not waited for: its cell reads as what the function returned until the result arrives.
      • Starts the engine if it is ICalculation.Status.Off. An engine in ICalculation.Status.Error is not started; start tries again.

    • Enables, disables or configures iterative calculation.

      Parameters

      • options: boolean | Partial<IterativeCalculation>

        true/false toggles enabled alone; an object updates the fields given and keeps the rest.

      Returns this

      Every cell in a cycle is recalculated when this changes: turning iteration on resolves the cycles the workbook shows as unresolved, turning it off writes 0 to them again.

    • The calculation settings as JSON — what an xlsx carries in calcPr.

      Returns ICalculation.JSON

      Sparse: a setting at its default is omitted. Settings a file carried that this engine does not act on (calcOnSave, fullCalcOnLoad, fullPrecision, …) are kept and written back.

    • Counts work that a consumer derives from the engine's results as calculation in flight until it settles: ready waits for it, and getCalculationState reads Calculating meanwhile.

      Type Parameters

      • T

      Parameters

      • work: Promise<T>

        The derived work. Its failure is the consumer's: it settles the wait either way.

      Returns Promise<T>

      work.

      For anything whose answer follows from a pass and lands after it - a conditional format re-judging its cells once the pass delivers its formula's values - so that a reader who waited for ready() reads the answer rather than the one before it. Not counted in manual mode, where the pass such work waits for runs only when asked.

    • Resolves once no async function call is pending (getPendingCount is 0) and every answer has been calculated into the workbook — Excel's CalculateUntilAsyncQueriesDone.

      Parameters

      • Optionaloptions: { timeout?: number }

        timeout in milliseconds; 30 seconds when absent.

      Returns Promise<boolean>

      true when nothing is pending; false when the timeout came first.

      • An answer that makes a formula ask a new question (one call's answer is another's input) is waited for too.
      • ready is the engine's own readiness and does not wait for answers.

    Settings
    Member Visibility

    On This Page
    Properties
    Methods