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

    Interface IContext

    The context provided to condition predicates during evaluation.

    Includes information about the current cell being evaluated, the range, and utility methods for value transformation and formula resolution.

    interface IContext {
        createFormula(
            expression: string,
            coords?: CellCoords | null,
        ): IFormula | null;
        deferBatch(key?: any): void;
        fromSerialDate(serialDate: number): Date;
        getCoords(): Readonly<IRange.Coords>;
        getDateParts(
            serialDate: number,
            reuseParts?: boolean | ParsedDateTime,
        ): ParsedDateTime;
        getDisplayText(): string | null;
        getNow(): number;
        getPosition(): Readonly<IRange.CellCoords>;
        getRange(): IRange;
        getType(value: Scalar): InteropScalarType;
        resolveInput<C = any>(input: Input<C>): Promise<ICondition<any> | null>;
        toSerialDate(date: Date): number;
        toType<T extends InteropScalar>(value: Scalar, type: InteropScalarType): T;
        watchFormula(
            formula: string | IFormula,
        ): MaybePromise<IRange<Scalar> | null>;
    }
    Index
    createFormula deferBatch fromSerialDate getCoords getDateParts getDisplayText getNow getPosition getRange getType resolveInput toSerialDate toType watchFormula

    • Returns a formula instance if calculations are available.

      Parameters

      • expression: string
      • Optionalcoords: CellCoords | null

      Returns IFormula | null

      This can be used by operators that need to create temporary formulas for evaluating expressions or other complex logic.

    • Defers evaluation of the current value so it can be processed in a batched call to ICondition.IOperator.doBatch.

      Parameters

      • Optionalkey: any

        A grouping key used to batch or deduplicate values. The key can be any value; typical choices are:

        • The raw cell value (to dedupe identical values).
        • A normalized form (e.g. lower-cased email, trimmed address).
        • A composite object if the operator needs multiple fields for batching.

      Returns void

      This method is intended for advanced operators that want to:

      • Call external services (e.g. email verification, address lookup).
      • Perform expensive computations once per unique value or per batch.

      When a predicate calls ctx.deferBatch(key):

      • The engine records the current value (and its cell context) into a batch associated with the active operator.
      • The immediate boolean return value of the predicate is ignored for that call; the final result will come from the operator’s ICondition.IOperator.doBatch implementation.
      • After the scan, the engine invokes doBatch once with the collected values and uses its boolean results as the actual condition outcomes.

      Rules that do not use batching can ignore this API entirely.

      Error Throws if deferBatch is called but the active operator does not implement ICondition.IOperator.doBatch. This protects against accidentally deferring work for a operator that has no batch handler.

    • Returns a date from an SerialDate value. This is used for date calculations.

      Parameters

      • serialDate: number

        A serialized date as a number.

      Returns Date

    • Returns the range for the entire area being valuated.

      Returns Readonly<IRange.Coords>

      Convenience method for getRange().getCoords().

    • Splits a serial date into its calendar and clock fields, without constructing a Date.

      Parameters

      • serialDate: number

        The serial date to split.

      • OptionalreuseParts: boolean | ParsedDateTime

        Avoids allocating a fresh ParsedDateTime:

        • An object: the fields are written into THIS object, which is returned. The caller owns the buffer's lifetime — do not hold onto a previous result across a reused call, each call overwrites it in place. For an operator that calls this once per cell over a large range (e.g. matching a date-group filter).
        • true: the fields are written into a shared scratch object and returned — for a one-off caller that just wants to avoid the allocation without owning a buffer itself. The result must be consumed immediately (read a field, done).

      Returns ParsedDateTime

      Prefer this to fromSerialDate for calendar-field comparisons (year/month/day/…) — it skips the Date allocation entirely, not just the reuse of one.

    • The text the current cell shows, under a filter; null elsewhere.

      Returns string | null

      Read by an operator asked to match displayed text (InSetOption.byDisplay): a cell holding 1.5 and showing 1.50 is the item 1.50. A conditional format or a data validation has no displayed text, so this answers null there and the operator compares the value.

      Formatted on demand, so an operator that never asks pays nothing.

    • Gets now as a serial number.

      Returns number

    • Return the current location in the sheet.

      Returns Readonly<IRange.CellCoords>

    • Return the range for the condition.

      Returns IRange

    • Returns the raw cell type for the current cell being evaluated.

      Parameters

      • value: Scalar

      Returns InteropScalarType

    • Resolves a condition input to a fully-built ICondition instance.

      Type Parameters

      • C = any

      Parameters

      • input: Input<C>

        Any valid condition input (ICondition, properties, predicate function, string)

      Returns Promise<ICondition<any> | null>

      A resolved ICondition ready for evaluation, or null if the input could not be resolved

      For Combinator Authors:

      • Call this to recursively resolve child conditions
      • Handles all input formats (objects, strings, functions)
      • Enables composition without type worries

      Why This Exists:

      • Uniform handling of condition inputs
      • Enables recursive composition (AND/OR/NOT)
      • Keeps combinator code clean

    • Returns an SerialDate value from a date. This is used for date calculations.

      Parameters

      • date: Date

        A date as a javascript object.

      Returns number

    • Convert the value to the specified scalar type.

      Type Parameters

      • T extends InteropScalar

      Parameters

      • value: Scalar
      • type: InteropScalarType

      Returns T

    • Declares that this condition depends on formula, and resolves to its values across getCoords.

      Parameters

      Returns MaybePromise<IRange<Scalar> | null>

      One value per cell of getCoords, read with LOCAL coordinates (getValueAt(0, 0) is the coords' top-left), or null when there is no engine to answer with. Already-delivered values come back without awaiting anything.

      The ONLY way an operator should reach a formula. Await it in createPredicate — which is itself awaited — and the predicate that comes out is a plain synchronous read of the values. No operator needs to compile, evaluate, or batch anything.

      What happens behind it depends on who is asking, and an operator neither knows nor cares:

      • A long-lived owner (a conditional format, a data validation) watches. The first call registers, so that when anything the formula reads changes — including cells outside the rule's own ranges, which its range listener cannot see — the rule re-runs and this returns the new values. The owner holds the registration, because a watch outlives the predicate.
      • A one-shot caller (Range.filter()) has no lifetime to keep fresh, so it simply evaluates once and resolves. Correct there, and identical from here.

    Settings
    Member Visibility

    On This Page
    Methods