@sheetxl/primitives 0.7.21 → 0.7.23-beta.1

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

package/types/src/FormulaError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormulaError.d.ts","sourceRoot":"","sources":["../../../src/FormulaError.ts"],"names":[],"mappings":"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"}