@sheetxl/primitives 0.7.26 → 0.7.28-beta.1

package/types/src/ErrorPolicy.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Parameter markers that declare how the engine handles `FormulaError` values *before* a
+ * function body runs. At the type level they are identity aliases — the body sees plain `T` —
+ * but the declaration records the policy for the engine.
+ *
+ * **ONE default, every position: errors reject.** Scalar arguments, lifted members,
+ * flattened members, and range parameters alike propagate the first error — preserving its
+ * identity (`#N/A` stays `#N/A`) — and the body never runs. Opt out with {@link AcceptError}.
+ * The single exception needs no marker: a `FormulaError.Known`-typed parameter receives
+ * errors because the type declares it.
+ *
+ * > *Errors propagate unless your function opts in to seeing them.*
+ *
+ * | position | default | opt-out |
+ * | --- | --- | --- |
+ * | scalar argument | reject — propagate with identity, body never runs | `AcceptError<T>` — body receives raw |
+ * | lifted member | reject — error becomes an error **member** of the output | `AcceptError<T>` |
+ * | flattened member (`Scalar[]`, rest) | reject — first error wins, argument order, row-major | `AcceptError<T>` |
+ * | range parameter | reject — first error (row-major) outranks everything | `AcceptError<IRange>` — members arrive raw |
+ * | `FormulaError.Known` parameter | receive (the type declares it) | — |
+ *
+ * One parameter splits the two by ARGUMENT SHAPE rather than picking one:
+ * {@link AcceptRefError} rejects a direct/computed error and accepts a reference-shaped one.
+ *
+ * There is no marker for the default. A `RejectError<T>` alias existed and declared nothing the
+ * engine did not already do, so it was removed rather than left as a second way to say nothing.
+ *
+ * Which-error-wins is ARGUMENT ORDER: the whole of argument N is scanned before argument
+ * N+1, row-major within each. The engine's range scan rides `IRange.errors()` /
+ * `IRange.hasError()` — raw stored members only, same definition as
+ * `getStats().getTypedCounts([ScalarType.Error])`.
+ *
+ * The tolerant set — parameters that declare `AcceptError` — is finite and documented
+ * (RANGE-ERROR-PROP.md §6.3): operators (broadcast is per-member), reshapers / dynamic
+ * arrays (error members pass through to the output), lookups (errors in never-consumed
+ * cells are tolerated), shape-only reference params (ROWS, COLUMNS, INDEX, OFFSET…),
+ * conditional consumers (SUMIF-family; the database family and SUBTOTAL/AGGREGATE keep
+ * their in-body, data-dependent policy), counters (COUNT, COUNTA), and the error handlers
+ * themselves (IS*, IFERROR…).
+ */
+/**
+ * Opts a parameter out of the reject default: the body receives `FormulaError` values raw.
+ * Use this for functions whose job is to inspect, replace, or render errors (the IS*
+ * family, IFERROR, ERROR.TYPE, VALUETOTEXT…), that remap errors rather than propagate
+ * them, or that legitimately tolerate error members they may never consume (lookups,
+ * reshapers, conditional consumers — the §6.3 tolerant set).
+ *
+ * On a TYPED parameter (`IRange<number>`), `AcceptError` means errors and failed coercions
+ * arrive as raw MEMBERS instead of propagating — COUNT ignores them, COUNTA counts them.
+ *
+ * @example
+ * ```ts
+ * export function ISERROR(value: AcceptError<Scalar>): Scalar { ... }
+ * export function IFERROR(value: AcceptError<Scalar>, valueIfError: AcceptError<Scalar>): Scalar { ... }
+ * // Both parameters: an unused error fallback must pass through untouched (IFERROR(5,NA()) → 5).
+ * export function ROWS(array: AcceptError<IRange>): number { ... }
+ * // Shape-only: ROWS(A1:A2) is 2 even if A1 is #REF!.
+ * ```
+ */
+export type AcceptError<T> = T;
+/**
+ * Splits the policy by the ARGUMENT'S SHAPE: a **direct or computed** error rejects (propagates
+ * with its identity, exactly the default), while a **reference-shaped** one is accepted and the
+ * body receives it raw. "Direct" is the same runtime-shape test the coercion uses — a scalar,
+ * typed or computed; a reference or a computed array is not (`isDirectArg` in `TypedFunction`).
+*
+ * ```
+ * =DSUM(A1:B3,NA(),G1:G2)     #N/A       direct    — rejects, identity preserved
+ * =DSUM(A1:B3,NA()+0,G1:G2)   #N/A       computed  — still direct
+ * =DSUM(A1:B3,E1,G1:G2)       #VALUE!    E1=#N/A   — reference: body remaps
+ * =DSUM(A1:B3,E2,G1:G2)       #VALUE!    E2=#DIV/0!
+ * ```
+ *
+ * A body under this marker MUST handle the error it may now receive; a `FormulaError` reaching
+ * an unguarded body is the item 18 hazard.
+ */
+export type AcceptRefError<T> = T;
+//# sourceMappingURL=ErrorPolicy.d.ts.map

package/types/src/Flatten.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Declares that a parameter takes ONE argument and receives it UNPACKED into a list.
+ *
+ * The length comes from the argument's CONTENTS, which is what separates it from every repeating
+ * form — there the length comes from the argument COUNT:
+ *
+ * ```
+ * IRR(values: Flatten<number>, guess?: number)   IRR(A1:A5)  → values is [1,2,3,4,5]   ONE argument
+ * SUM(number: IRange<number>[])                  SUM(A1:A5)  → number is [IRange]      ONE argument
+ * ```
+ *
+ * ### What "unpacked" means depends on the element type
+ *
+ * | `T` | the list holds | example |
+ * | --- | --- | --- |
+ * | a scalar (`number`, `string`, `Scalar`) | the argument's MEMBERS, blanks skipped | `NETWORKDAYS`'s holidays |
+ * | a range (`IRange`, `IReferenceRange`) | the argument's AREAS | `INDEX((A1:B2,C3:D4),…)` |
+ *
+ * Both are the same mechanism at different granularity — the marshaller picks the unit from the
+ * element type — and a blank drops out of either. The scalar case is the common one; the range case
+ * exists because a reference UNION is a single argument holding several areas, and a parameter that
+ * does not declare `Flatten` refuses one outright (`#REF!` — `ROWS((A1:A3,C1:C5))` in Excel).
+ *
+ * At the type level it is `T[]`, so the body reads the list directly.
+ *
+ * @example
+ * ```ts
+ * export function IRR(values: Flatten<number>, guess?: number): number { ... }
+ * export function NETWORKDAYS(start: Date, end: Date, holidays?: Flatten<Scalar>): number { ... }
+ * export function INDEX(array: Flatten<AcceptError<IRange>>, rowNum?: number, ...): any { ... }
+ * ```
+ */
+export type Flatten<T> = T[];
+//# sourceMappingURL=Flatten.d.ts.map

package/types/src/FormulaContext.d.ts

@@ -0,0 +1,227 @@
+import { Scalar } from './Scalar';
+import { FormulaError } from './FormulaError';
+import { IRange } from './IRange';
+import { IReferenceRange } from './IReferenceRange';
+import { IFunction } from './IFunction';
+import { IFormulaContext } from './IFormulaContext';
+import { IRuntime } from './IRuntime';
+import { LocaleProfile } from './LocaleProfile';
+/**
+ * Default implementation of the IFormulaContext interface.
+ *
+ * @see IFormulaContext
+ *
+ * @remarks
+ * This is a stubbed implementation of the IFormulaContext interface.
+ * Runtime engines should provide a complete implementation.
+ * @internal
+ * @hidden
+ */
+export declare class StubbedFormulaContext implements IFormulaContext {
+    /** @inheritdoc IFormulaContext.createRange */
+    createRange<TS extends Scalar = Scalar>(rows?: number, columns?: number, values?: Scalar | Scalar[][] | ((value: TS, coords: IRange.CellCoords, range: IRange<TS>) => TS)): IRange;
+    /** @inheritdoc IFormulaContext.getReference */
+    getReference(coords?: Readonly<IRange.Coords>, r1c1?: boolean): IReferenceRange;
+    /** @inheritdoc IFormulaContext.getResizedReference */
+    getResizedReference(anchor: Readonly<IRange.Coords>, rowCount: number, colCount: number): IReferenceRange;
+    /** @inheritdoc IFormulaContext.getNumberFormat */
+    getNumberFormat(formatText: string, value: Scalar): string;
+    /** @inheritdoc IFormulaContext.fromSerialDate */
+    fromSerialDate(serialDate: number, dateOnly?: boolean): Date;
+    /** @inheritdoc IFormulaContext.toSerialDate */
+    toSerialDate(date: Date, dateOnly?: boolean): number;
+    /** @inheritdoc IFormulaContext.getDateParts */
+    getDateParts(serialDate: number, reuseParts?: IFormulaContext.DateParts | boolean): IFormulaContext.DateParts;
+    /** @inheritdoc IFormulaContext.getSerialDate */
+    getSerialDate(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millis?: number): number;
+    /** @inheritdoc IFormulaContext.getNow */
+    getNow(): number;
+    /** @inheritdoc IFormulaContext.getValueAt */
+    getValueAt(row: number, column: number, sheetName?: string, options?: IRange.ValueOptions): Scalar | null;
+    /** @inheritdoc IFormulaContext.getEntireCoords */
+    getEntireCoords(): IRange.Coords;
+    /** @inheritdoc IFormulaContext.isValidDate */
+    isValidDate(value: any, jsDateOnly?: boolean): boolean;
+    /** @inheritdoc IFormulaContext.getRow */
+    getRow(): number;
+    /** @inheritdoc IFormulaContext.getColumn */
+    getColumn(): number;
+    /** @inheritdoc IFormulaContext.getFormulaAt */
+    getFormulaAt(row: number, column: number, sheetName?: string): string | null;
+    /** @inheritdoc IFormulaContext.getSpillAt */
+    getSpillAt(row: number, column: number, sheetName?: string): IReferenceRange | null;
+    /** @inheritdoc IFormulaContext.getSheetIndex */
+    getSheetIndex(sheet?: string | IReferenceRange): number;
+    /** @inheritdoc IFormulaContext.getSheetCount */
+    getSheetCount(): number | null;
+    /** @inheritdoc IFormulaContext.markVolatile */
+    markVolatile(): void;
+    /** @inheritdoc IFormulaContext.formatResults */
+    formatResults(numFmt: string): void;
+    /** @inheritdoc IFormulaContext.filterHidden */
+    filterHidden(range: IRange, axes?: IRange.AxisSelection): IRange;
+    /** @inheritdoc IFormulaContext.filterTotals */
+    filterTotals(range: IRange): IRange;
+    /** @inheritdoc IFormulaContext.getFunction */
+    getFunction(name: string): IFunction | null;
+    /** @inheritdoc IFormulaContext.getAddress */
+    getAddress(coords?: Readonly<IRange.FixableCoords | IRange.FixableCellCoords>, r1c1?: boolean): string;
+    /** @inheritdoc IFormulaContext.parseAsSerialDate */
+    parseAsSerialDate(textOrNumber: string | number, requireDate?: boolean): number;
+    /** @inheritdoc IFormulaContext.parseAsDate */
+    parseAsDate(serialOrString: string | number | Date | any, requireDate?: boolean): Date;
+    /** @inheritdoc IFormulaContext.parseAsNumber */
+    parseAsNumber(textOrNumber: Scalar, options?: IFormulaContext.ParseNumberOptions): number;
+    parseAsNumber(textOrNumber: Scalar | undefined, options?: IFormulaContext.ParseNumberOptions): number | undefined;
+    /**
+     * Unimplemented. See {@link IFormulaContext.createCriteria}.
+     *
+     * @remarks
+     * Unimplemented rather than approximated. Criteria parsing is the one rule that needs all three
+     * localization planes at once, and this stub has none of them — a "basic" version would answer
+     * plausibly and wrongly, where throwing names the actual mistake (evaluating criteria outside an
+     * installed scope).
+     */
+    createCriteria(criteria: Scalar): IFormulaContext.CriteriaEvaluator;
+    /**
+     * Parses the canonical English boolean and error literals.
+     * See {@link IFormulaContext.parseAsLiteral}.
+     *
+     * @remarks
+     * CANONICAL English only, deliberately. The localized spellings live in a language pack, which
+     * `@sheetxl/sdk` resolves and this package cannot see — the engine reaches `parseBooleanLocal` /
+     * `parseErrorLocal` through the calculation context and never lands here. Canonical is always
+     * accepted there too, so this stub is that rule with the localized alternates missing.
+     */
+    parseAsLiteral(text: string): boolean | FormulaError.Known | undefined;
+    /**
+     * Renders a scalar as text. See {@link IFormulaContext.toText}.
+     *
+     * @remarks
+     * A BASIC rendering, deliberately NOT Excel's. Excel's rule -- coercion General (15
+     * significant digits, plain decimal while the rendering fits 20 characters, else
+     * scientific) written with the workbook LOCALE's decimal separator -- is
+     * `formatNumberGeneral` in `@sheetxl/sdk`, and every evaluation path reaches it through
+     * the calculation context rather than through this stub. Numbers here get the plain JS
+     * rendering, which diverges from Excel on both precision and separator.
+     *
+     * This exists so authoring, type defs and other non-runtime access get usable text
+     * instead of throwing. Anything that needs Excel parity is running in the engine, and
+     * the engine never lands here.
+     */
+    toText(value: Scalar | undefined): string;
+    /**
+     * Orders two scalars. See {@link IFormulaContext.compare}.
+     *
+     * @remarks
+     * A BASIC total order, deliberately NOT Excel's. Excel's rule -- locale collation, the word
+     * sort, a blank taking the other operand's type, 11-decimal numeric normalization -- is
+     * `ScalarCollation` in `@sheetxl/sdk`, and every evaluation path reaches it through the
+     * calculation context rather than through this stub. `options` is ignored: strength is a
+     * collation concept and nothing here collates.
+     *
+     * This exists so authoring, type defs and other non-runtime access get a usable ordering
+     * instead of throwing. Anything that needs Excel parity is running in the engine, and the
+     * engine never lands here.
+     */
+    compare(a: Scalar, b: Scalar, options?: Intl.CollatorOptions): number;
+    /** @inheritdoc IFormulaContext.getRuntime */
+    getRuntime(): IRuntime;
+}
+/**
+ * The single, shared {@link IFormulaContext} that formula implementations use (via
+ * `import { FormulaContext } from '@sheetxl/primitives'`).
+ *
+ * @remarks
+ * A thin delegate: every method forwards to the currently-installed scope. The runtime (the
+ * calculation engine) installs the active per-evaluation scope; outside a calculation it falls back
+ * to {@link StubbedFormulaContext}. `@sheetxl/primitives` owns the interface and a default; the
+ * runtime supplies the implementation.
+ */
+export declare class ScopedFormulaContext implements IFormulaContext {
+    protected _scope: Partial<IFormulaContext>;
+    /** @hidden Installed by the runtime around each evaluation; `null` restores the stub. */
+    _setScope(scope: Partial<IFormulaContext> | null): void;
+    /** @hidden */
+    _getScope(): Partial<IFormulaContext>;
+    /** @inheritdoc IFormulaContext.getNumberFormat */
+    getNumberFormat(formatText: string, value: Scalar): string | null;
+    /** @inheritdoc IFormulaContext.getEntireCoords */
+    getEntireCoords(): IRange.Coords;
+    /** @inheritdoc IFormulaContext.parseAsSerialDate */
+    parseAsSerialDate(textOrNumber: Scalar, requireDate?: boolean): number;
+    /** @inheritdoc IFormulaContext.parseAsDate */
+    parseAsDate(serialOrString: string | number | Date | any, requireDate?: boolean): Date;
+    /** @inheritdoc IFormulaContext.parseAsNumber */
+    parseAsNumber(textOrNumber: Scalar, options?: IFormulaContext.ParseNumberOptions): number;
+    parseAsNumber(textOrNumber: Scalar | undefined, options?: IFormulaContext.ParseNumberOptions): number | undefined;
+    /** @inheritdoc IFormulaContext.createCriteria */
+    createCriteria(criteria: Scalar): IFormulaContext.CriteriaEvaluator;
+    /** @inheritdoc IFormulaContext.parseAsLiteral */
+    parseAsLiteral(text: string): boolean | FormulaError.Known | undefined;
+    /** @inheritdoc IFormulaContext.toText */
+    toText(value: Scalar | undefined): string;
+    /** @inheritdoc IFormulaContext.isValidDate */
+    isValidDate(value: any, jsDateOnly?: boolean): boolean;
+    /** @inheritdoc IFormulaContext.fromSerialDate */
+    fromSerialDate(serialDate: number, dateOnly?: boolean): Date;
+    /** @inheritdoc IFormulaContext.toSerialDate */
+    toSerialDate(date: Date, dateOnly?: boolean): number;
+    /** @inheritdoc IFormulaContext.getDateParts */
+    getDateParts(serialDate: number, reuseParts?: IFormulaContext.DateParts | boolean): IFormulaContext.DateParts;
+    /** @inheritdoc IFormulaContext.getSerialDate */
+    getSerialDate(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millis?: number): number;
+    /** @inheritdoc IFormulaContext.getNow */
+    getNow(): number;
+    /** @inheritdoc IFormulaContext.createRange */
+    createRange<TS extends Scalar = Scalar>(rows?: number, columns?: number, values?: Scalar | Scalar[][] | ((value: TS, coords: IRange.CellCoords, range: IRange<TS>) => TS)): IRange;
+    /** @inheritdoc IFormulaContext.getRow */
+    getRow(): number;
+    /** @inheritdoc IFormulaContext.getColumn */
+    getColumn(): number;
+    /** @inheritdoc IFormulaContext.getReference */
+    getReference(coords?: Readonly<IRange.Coords>, r1c1?: boolean): IReferenceRange;
+    /** @inheritdoc IFormulaContext.getResizedReference */
+    getResizedReference(anchor: Readonly<IRange.Coords>, rowCount: number, colCount: number): IReferenceRange;
+    /** @inheritdoc IFormulaContext.getValueAt */
+    getValueAt(row: number, column: number, scope: string): Scalar | null;
+    /** @inheritdoc IFormulaContext.getFormulaAt */
+    getFormulaAt(row: number, column: number, scope: string): string | null;
+    /** @inheritdoc IFormulaContext.getSpillAt */
+    getSpillAt(row: number, column: number, scope: string): IReferenceRange | null;
+    /** @inheritdoc IFormulaContext.getSheetIndex */
+    getSheetIndex(sheet?: string | IReferenceRange): number;
+    /** @inheritdoc IFormulaContext.getSheetCount */
+    getSheetCount(): number | null;
+    /** @inheritdoc IFormulaContext.markVolatile */
+    markVolatile(): void;
+    /** @inheritdoc IFormulaContext.formatResults */
+    formatResults(numFmt: string): void;
+    /** @inheritdoc IFormulaContext.filterHidden */
+    filterHidden(range: IRange, axes?: IRange.AxisSelection): IRange;
+    /** @inheritdoc IFormulaContext.filterTotals */
+    filterTotals(range: IRange): IRange;
+    /** @inheritdoc IFormulaContext.getFunction */
+    getFunction(fnName: string): IFunction | null;
+    /** @inheritdoc IFormulaContext.getAddress */
+    getAddress(coords?: Readonly<IRange.FixableCoords | IRange.FixableCellCoords>, r1c1?: boolean): string;
+    /** @inheritdoc IFormulaContext.compare */
+    compare(a: Scalar, b: Scalar, options?: Intl.CollatorOptions): number;
+    /** @inheritdoc IFormulaContext.getRuntime */
+    getRuntime(): IRuntime;
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+}
+/**
+ * A plain en-US profile, for stubs and for environments without `Intl`.
+ *
+ * @remarks
+ * Deliberately static data -- no probing. Real profiles come from
+ * `makeLocaleProfile` in `@sheetxl/sdk`.
+ */
+export declare const DEFAULT_LOCALE_PROFILE: LocaleProfile;
+/**
+ * The shared {@link IFormulaContext} for formula implementations. See {@link ScopedFormulaContext}.
+ */
+export declare const FormulaContext: IFormulaContext;
+//# sourceMappingURL=FormulaContext.d.ts.map

package/types/src/FormulaError.d.ts

@@ -0,0 +1,328 @@
+import { IRange } from './IRange';
+import { IReferenceRange } from './IReferenceRange';
+/**
+ * An error returned from a formula calculation.
+ *
+ * Standard Error Codes
+ *  0. #PARSE! If the formula contains a syntax error. (Not part of the OOXML spec.)
+ *  1. #NULL! Intersection of two ranges that don't intersect.
+ *  2. #DIV/0! Division by zero.
+ *  3. #VALUE! Wrong type of argument or operand.
+ *  4. #REF! Invalid cell reference.
+ *  5. #NAME? Unrecognized name (function, named range, etc.).
+ *  6. #NUM! Invalid numeric value.
+ *  7. #N/A Value not available.
+ * # Office 365
+ *  8. #GETTING_DATA This is raised for long running calculations that are not yet complete.
+ *
+ *  (Saves as #N/A to disk)
+ *  9. #SPILL! Formula's output range is blocked.
+ *
+ *  SpillErrorScalarSubType | "Unknown" | "Collision" | "IndeterminateSize" | "WorksheetEdge" | "OutOfMemoryWhileCalc" | "Table" | "MergedCell"
+ * # Office 2023
+ * 10. #CONNECT! This occurs when a data type is used that is not currently supported in this version of Excel.
+ * 11. #BLOCKED! Indicates that an action or feature is blocked, possibly due to security settings, protected view, or other restrictions. Often related to online features, external links, or macros.
+ * 12. #UNKNOWN! May be returned in the case of a protected workbook.
+ * 13. #FIELD! Invalid field name for a data type.
+ * 14. #CALC! Calculation error (often with LET or LAMBDA or a splitted array).
+ * 15.
+ * 16.  #BUSY! When waiting on an external data source to return data.
+ * 17.
+ * 18.
+ * 19. #PYTHON! The Python interpreter returned the following error: Unexpected failure.
+ * 20. #TIMEOUT! Indicates that the operation took too long to complete.
+*/
+export declare namespace FormulaError {
+    /**
+     * Standardized error codes for error types.
+     */
+    const Code: {
+        readonly Parse: 0;
+        readonly Null: 1;
+        readonly Div0: 2;
+        readonly Value: 3;
+        readonly Ref: 4;
+        readonly Name: 5;
+        readonly Num: 6;
+        readonly NA: 7;
+        readonly GettingData: 8;
+        readonly Spill: 9;
+        readonly Connect: 10;
+        readonly Blocked: 11;
+        readonly Unknown: 12;
+        readonly Field: 13;
+        readonly Calc: 14;
+        readonly Busy: 16;
+        readonly Python: 19;
+        readonly Timeout: 20;
+    };
+    /**
+     * Standardized error labels for error types.
+     */
+    const Label: {
+        readonly Parse: "#PARSE!";
+        readonly Null: "#NULL!";
+        readonly Div0: "#DIV/0!";
+        readonly Value: "#VALUE!";
+        readonly Ref: "#REF!";
+        readonly Name: "#NAME?";
+        readonly Num: "#NUM!";
+        readonly NA: "#N/A";
+        readonly GettingData: "#GETTING_DATA";
+        readonly Spill: "#SPILL!";
+        readonly Connect: "#CONNECT!";
+        readonly Blocked: "#BLOCKED!";
+        readonly Unknown: "#UNKNOWN!";
+        readonly Field: "#FIELD!";
+        readonly Calc: "#CALC!";
+        readonly Busy: "#BUSY!";
+        readonly Python: "#PYTHON!";
+        readonly Timeout: "#TIMEOUT!";
+    };
+    class Known extends Error {
+        protected _label: string;
+        protected _code: number;
+        protected details: any;
+        constructor(code: number, label: string, message?: string, details?: ErrorOptions);
+        static code: number;
+        get isFormulaError(): true;
+        getLabel(): string;
+        getCode(): number;
+        /**
+         * Return true if two errors are same.
+         *
+         * @param other any object to compare.
+         * @returns if two errors are the same type.
+         */
+        equals(other: any): boolean;
+        get [Symbol.toStringTag](): string;
+        /**
+         * The canonical spreadsheet spelling — `#VALUE!`, `#N/A`.
+         *
+         * @remarks
+         * Localization is a display concern and belongs to the layer that has a language pack
+         * (`localizeErrorLabel`); this stays canonical.
+         */
+        toString(): string;
+    }
+    /**
+     * #Parse!
+     *
+     * @remarks
+     * Not part of the OOXML spec.
+     */
+    class Parse extends Known {
+        constructor(message?: string, details?: ErrorOptions & {
+            line?: number;
+            column?: number;
+            offset?: number;
+            length?: number;
+        });
+        static code: number;
+        getDetails(): {
+            line: number;
+            column: number;
+            offset: number;
+            length: number;
+        };
+    }
+    /**
+     * When a reference is provided that doesn't exist. Usually an invalid range specification.
+     * =SUM(G5 G23)
+     */
+    class Null extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+    /**
+     * Divide by Zero.
+     * * ex: The formula or function used is divided by zero.
+     */
+    class Div0 extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+    /**
+     * Wrong argument in the formula. For example a string was given but a number was
+     * * ex: The row index number is too small. Specify a number great than or equal to 1.
+     */
+    class Value extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+    /**
+     * Reference was remove due to a move or delete of cells.
+     * * ex: Moving or deleting cells caused an invalid cell reference, or function is returning reference error.
+     */
+    class Ref extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+    /**
+     * A formula has references that can not be resolved or may contain parsing errors.
+     * * ex: The formula contains unrecognized text.
+     */
+    class Name extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+    /**
+     * Invalid number.
+     */
+    class Num extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+    /**
+     * Not available.
+     *
+     * @remarks
+     * Indicates the data needed is not available.
+     */
+    class NA extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+    /**
+     * Getting Data.
+     */
+    class GettingData extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+    /**
+     * Spill.
+     */
+    class Spill extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+    /**
+     * Connect.
+     */
+    class Connect extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+    /**
+     * Blocked.
+     */
+    class Blocked extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+    /**
+     * Unknown.
+     */
+    class Unknown extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+    /**
+     * Field does not exist.
+     *
+     * @remarks
+     * Indicates a field or property being access is not available.
+     */
+    class Field extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+    /**
+     * Calc.
+     */
+    class Calc extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+    /**
+     * Busy.
+     */
+    class Busy extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+    /**
+     * Python.
+     */
+    class Python extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+    /**
+     * Unknown.
+     */
+    class Timeout extends Known {
+        constructor(message?: string, details?: ErrorOptions);
+        static code: number;
+    }
+}
+export declare namespace FormulaError {
+    /**
+     * Returns a built-in error instance based on the error code.
+     *
+     * @param code The error code corresponding to a built-in error type.
+     * @returns A built-in error instance.
+     */
+    const getBuiltInByCode: (code: number) => FormulaError.Known | undefined;
+    /**
+     * Built-in errors instances for easy reference and comparison.
+     */
+    const BuiltIn: {
+        readonly Parse: FormulaError.Known;
+        readonly Null: FormulaError.Known;
+        readonly Div0: FormulaError.Known;
+        readonly Value: FormulaError.Known;
+        readonly Ref: FormulaError.Known;
+        readonly Name: FormulaError.Known;
+        readonly Num: FormulaError.Known;
+        readonly NA: FormulaError.Known;
+        readonly GettingData: FormulaError.Known;
+        readonly Spill: FormulaError.Known;
+        readonly Connect: FormulaError.Known;
+        readonly Blocked: FormulaError.Known;
+        readonly Unknown: FormulaError.Known;
+        readonly Field: FormulaError.Known;
+        readonly Calc: FormulaError.Known;
+        readonly Busy: FormulaError.Known;
+        readonly Python: FormulaError.Known;
+        readonly Timeout: FormulaError.Known;
+    };
+    /**
+     * Creates a new error instance based on the provided label or code.
+     *
+     * @param label The error label or code corresponding to a built-in error type.
+     * @param message Optional custom error message.
+     * @param details Optional additional error details.
+     * @returns A new instance of the specified error type, or an Unknown error if the label/code is not recognized.
+     *
+     * @remarks
+     * * Useful when wanting to convey details beyond the standard error code.
+     * * This should be used sparingly as creating new objects can have a performance impact.
+     */
+    const newTypedError: (label: string | number, message?: string, details?: ErrorOptions) => FormulaError.Known;
+    /**
+     * Returns a built-in error instance based on the error label.
+     *
+     * @param label The error label corresponding to a built-in error type.
+     * @returns A built-in error instance.
+     */
+    const getBuiltInByLabel: (label: string) => FormulaError.Known | undefined;
+    /**
+     * Used to determine if a value is a FormulaError.Known.
+     *
+     * @param v The value to check.
+     * @param code If provided, also checks that the error code matches.
+     * @returns a boolean.
+     */
+    function isError(v: unknown, code?: number): v is FormulaError.Known;
+    interface Known extends IRange {
+    }
+    interface Known extends IReferenceRange {
+    }
+}
+/**
+ * Indicates that the value can either be a valid value of type T or a FormulaError.Known.
+ */
+export type MaybeError<T> = T | FormulaError.Known;
+//# sourceMappingURL=FormulaError.d.ts.map