@sheetxl/sdk 0.7.21 → 0.7.23-beta.2

package/types/src/picture/IPicture.d.ts

@@ -0,0 +1,69 @@
+import { Size } from '@sheetxl/utils';
+import { IListener } from '../listener';
+import { IResource } from '../resource';
+import { IModel } from '../model';
+/**
+ * Interface for working with Pictures (both Images and SVG).
+ */
+export interface IPicture extends IModel {
+    toJSON(toResourceId?: (resource: IResource) => number | null): IPicture.JSON;
+    /**
+     * Returns the resource associated with this picture.
+     */
+    getResource(): IResource;
+    /**
+     * Returns an image blob.
+     */
+    toImage(): Promise<Blob>;
+    /**
+     * Return an html string or `null` if not supported.
+     */
+    toHtml(): Promise<string> | string | null;
+    /**
+     * Returns a local object URL for placing in an image tag.
+     */
+    getDetails(): Promise<IPicture.Details>;
+}
+/**
+ * {@inheritDoc IPicture}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IPicture}
+ */
+export declare namespace IPicture {
+    /**
+     * A set of values that can be set on an IPicture.
+     *
+     * @see
+     * {@link IPicture}
+     */
+    interface Properties {
+    }
+    interface JSON {
+        /**
+         * The resource id of the picture.
+         */
+        resId?: number;
+        effects?: string[];
+    }
+    interface Details {
+        /**
+         * The size of the image without any constraints. This info is determined by the file.
+         */
+        getNaturalSize(): Size;
+        /**
+         * As a url that can be attached to the dom.
+         */
+        asUrl(): string;
+        /**
+         * For SVG text.
+         */
+        asSVGText(): string | null;
+    }
+    interface Events extends IModel.Events {
+    }
+    interface IListeners extends IListener.Callbacks<IPicture, IPicture.Events> {
+    }
+}
+//# sourceMappingURL=IPicture.d.ts.map

package/types/src/picture/IPicture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IPicture.d.ts","sourceRoot":"","sources":["../../../../src/picture/IPicture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;GAEG;AAEH,MAAM,WAAW,QAAS,SAAQ,MAAM;IAEtC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,MAAM,GAAG,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAA;IAc5E;;OAEG;IACH,WAAW,IAAI,SAAS,CAAC;IACzB;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;IAC1C;;OAEG;IAEH,UAAU,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;CAEzC;AAED;;;;;;GAMG;AACH,yBAAiB,QAAQ,CAAC;IAExB;;;;;OAKG;IACH,UAAiB,UAAU;KAK1B;IAED,UAAiB,IAAI;QACnB;;WAEG;QACH,KAAK,CAAC,EAAE,MAAM,CAAC;QAQf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;KAWpB;IAED,UAAiB,OAAO;QACtB;;WAEG;QACH,cAAc,IAAI,IAAI,CAAC;QACvB;;WAEG;QACH,KAAK,IAAI,MAAM,CAAC;QAChB;;WAEG;QACH,SAAS,IAAI,MAAM,GAAG,IAAI,CAAC;KAC5B;IAED,UAAiB,MAAO,SAAQ,MAAM,CAAC,MAAM;KAU5C;IAED,UAAiB,UAAW,SAAQ,SAAS,CAAC,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC;KAAG;CAEtF"}

package/types/src/picture/Picture.d.ts

@@ -0,0 +1,67 @@
+import { IResource } from '../resource';
+import { AbstractModel, IModel } from '../model';
+import { IPicture } from './IPicture';
+interface State extends AbstractModel.State {
+    effects?: string[];
+}
+/**
+ * Implementation for {@link IPicture}.
+ */
+export declare class Picture extends AbstractModel<State, IPicture.JSON> implements IPicture {
+    private _resource;
+    private _details?;
+    private _dataUrl?;
+    constructor(options: Picture.ConstructorOptions);
+    /** {@inheritDoc IPicture.getType} */ getType(): string;
+    toJSON(toResourceId?: (resource: IResource) => number | null): IPicture.JSON;
+    getTypeDescription(): string;
+    /** @internal */
+    protected _asDataUrl(): Promise<string>;
+    /** {@inheritDoc IPicture.toHtml} */
+    toHtml(): Promise<string> | string | null;
+    /** {@inheritDoc IPicture.toImage} */
+    toImage(): Promise<Blob>;
+    /** {@inheritDoc IPicture.toArrayBuffer} */
+    toArrayBuffer(): Promise<ArrayBuffer>;
+    /** {@inheritDoc IPicture.getResource} */
+    getResource(): IResource;
+    /** {@inheritDoc IPicture.getDetails} */
+    getDetails(): Promise<IPicture.Details>;
+    /** @internal */
+    protected _getActionDescription(_action: 'delete'): string | null;
+    /** @internal */
+    protected _fromDrawingJSON(json: IPicture.JSON, fromResourceId?: (id: number) => IResource): void;
+    /** @internal */
+    protected _toDrawingJSON(toResourceId?: (resource: IResource) => number | null): IPicture.JSON;
+    /** @internal */
+    protected _processDelete(): void;
+}
+/**
+ * Interfaces for creating `Picture` items.
+ *
+ * @see
+ * ### **Interface**
+ *
+ * {@link Picture}
+ */
+export declare namespace Picture {
+    /**
+     * Options for creating an IPicture.
+     */
+    interface ConstructorOptions extends IModel.ConstructorOptions<IPicture.JSON> {
+        resource?: IResource;
+        /**
+         * Returns an IResource from the resourceId or null if not found.
+         */
+        fromResourceId?: (resourceId: number) => IResource;
+        /**
+         * Useful for load/save/copying.
+         */
+        /**
+         * Allow for the default lock aspect ratio to be overwritten.
+         */
+        defaultLockAspectRatio?: boolean;
+    }
+}
+export {};
+//# sourceMappingURL=Picture.d.ts.map

package/types/src/picture/Picture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Picture.d.ts","sourceRoot":"","sources":["../../../../src/picture/Picture.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAEtD,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE1C,UAAU,KAAM,SAAQ,aAAa,CAAC,KAAK;IACzC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AACD;;GAEG;AAGH,qBAAa,OAAQ,SAAQ,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAE,YAAW,QAAQ;IAClF,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,CAA4B;IAC7C,OAAO,CAAC,QAAQ,CAAC,CAAS;gBAEd,OAAO,EAAE,OAAO,CAAC,kBAAkB;IAY/C,qCAAqC,CACrC,OAAO,IAAI,MAAM;IAKjB,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,MAAM,GAAG,IAAI,GAAG,QAAQ,CAAC,IAAI;IAgB5E,kBAAkB,IAAI,MAAM;IAI5B,gBAAgB;cACA,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAU7C,oCAAoC;IACpC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI;IAKzC,qCAAqC;IAC/B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9B,2CAA2C;IACrC,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC;IAO3C,yCAAyC;IACzC,WAAW,IAAI,SAAS;IAIxB,wCAAwC;IAClC,UAAU,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAwB7C,gBAAgB;IAChB,SAAS,CAAC,qBAAqB,CAAC,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI;IAIjE,gBAAgB;IAChB,SAAS,CAAC,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI;IAOjG,gBAAgB;IAChB,SAAS,CAAC,cAAc,CAAC,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,MAAM,GAAG,IAAI,GAAG,QAAQ,CAAC,IAAI;IAS9F,gBAAgB;IAChB,SAAS,CAAC,cAAc,IAAI,IAAI;CAWjC;AAED;;;;;;;GAOG;AACH,yBAAiB,OAAO,CAAC;IACvB;;OAEG;IACH,UAAiB,kBAAmB,SAAQ,MAAM,CAAC,kBAAkB,CAAC,QAAQ,CAAC,IAAI,CAAC;QAClF,QAAQ,CAAC,EAAE,SAAS,CAAC;QACrB;;WAEG;QACH,cAAc,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,SAAS,CAAC;QACnD;;WAEG;QAEH;;WAEG;QAEH,sBAAsB,CAAC,EAAE,OAAO,CAAC;KAClC;CACF"}

package/types/src/picture/index.d.ts

@@ -0,0 +1,2 @@
+export * from './IPicture';
+//# sourceMappingURL=index.d.ts.map

package/types/src/picture/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/picture/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}

package/types/src/primitives/CompositeRangeStats.d.ts

@@ -0,0 +1,63 @@
+import { ScalarType, IRange, IRangeStats, Scalar } from '@sheetxl/primitives';
+import { SortedNumbers } from './stats';
+/**
+ * An {@link IRangeStats} composed of multiple underlying stats — merge-on-read.
+ *
+ * @remarks
+ * {@link RangeStats} is bound to a single value grid; this class combines stats that span
+ * grids (e.g. `IWorkbook.getStats`, where every sheet owns its own grid and segment cache).
+ * The children do all scanning and caching — composition only merges their results:
+ *
+ * - Counts and typed counts sum exactly.
+ * - Aggregates recombine from each child's `(numericalCount, sum, varP, min, max)` — the sum
+ *   of squares is recovered as `n·varP + sum²/n`, so variance and stdDev agree with a
+ *   single-scan computation up to floating-point rounding.
+ * - Sorted numbers merge the children's already-sorted populations (no re-sort).
+ *
+ * Like the single-grid stats, an instance is a read-time snapshot view — create, query,
+ * discard; per-instance lazy results are not invalidated by later data changes.
+ */
+export declare class CompositeRangeStats implements IRangeStats {
+    protected _children: readonly IRangeStats[];
+    protected _sortedNumbers: SortedNumbers | undefined;
+    protected _aggregates: Readonly<IRangeStats.Aggregates> | undefined;
+    protected _typedCounts: Readonly<Record<ScalarType, number>> | undefined;
+    protected _frequencies: Readonly<IRangeStats.IFrequency> | undefined;
+    constructor(children: readonly IRangeStats[]);
+    /** @inheritdoc IRangeStats.getSize */
+    getSize(): number;
+    /** @inheritdoc IRangeStats.getCount */
+    getCount(): number;
+    /** @inheritdoc IRangeStats.getAggregates */
+    getAggregates(options?: IRange.IteratorOptions): Readonly<IRangeStats.Aggregates>;
+    /** @inheritdoc IRangeStats.getSnappedSum */
+    getSnappedSum(total?: number): number;
+    /** @inheritdoc IRangeStats.getSortedNumbers */
+    getSortedNumbers(): IRangeStats.ISortedNumbers;
+    /** @inheritdoc IRangeStats.getRanked */
+    getRanked(options?: IRangeStats.GetRankedOptions): IterableIterator<Scalar>;
+    /** @inheritdoc IRangeStats.getFrequencies */
+    getFrequencies(options?: IRangeStats.GetFrequenciesOptions): Readonly<IRangeStats.IFrequency>;
+    /**
+     * Merges each child's already-scanned frequencies by re-keying their values — children do the
+     * scanning, this only combines results (the class's own doctrine, see the class remarks).
+     *
+     * @remarks
+     * A child-local `limit` bounds each child's OWN scan, not the composite's, so the merge would
+     * otherwise reach `children.length * limit` distinct values (and `children` here is sheets, not
+     * cells — the same scale `_mergeSortedPopulations` assumes). The merge therefore stops admitting
+     * NEW values at `limit` while still accumulating counts into the ones it has, which is what
+     * `FrequencyStats.fromGrid` does when its own scan hits the cap. `limit` means "cap how many
+     * distinct values were examined," that same "first-N-discovered" contract — not "top N by
+     * frequency" (that guarantee belongs to `getRanked`).
+     */
+    protected _mergeFrequencies(options?: IRangeStats.GetFrequenciesOptions): Readonly<IRangeStats.IFrequency>;
+    /** @inheritdoc IRangeStats.getTypedCounts */
+    getTypedCounts(types?: readonly ScalarType[]): {
+        [key in ScalarType]?: number;
+    };
+    /** {@inheritDoc IRangeStats.isIRangeStats} */
+    get isIRangeStats(): true;
+    protected _mergeAggregates(options?: IRange.IteratorOptions): Readonly<IRangeStats.Aggregates>;
+}
+//# sourceMappingURL=CompositeRangeStats.d.ts.map

package/types/src/primitives/CompositeRangeStats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompositeRangeStats.d.ts","sourceRoot":"","sources":["../../../../src/primitives/CompositeRangeStats.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,MAAM,EAAE,KAAK,WAAW,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7F,OAAO,EACiE,aAAa,EAEpF,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,mBAAoB,YAAW,WAAW;IACrD,SAAS,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE,CAAC;IAG5C,SAAS,CAAC,cAAc,EAAE,aAAa,GAAG,SAAS,CAAC;IACpD,SAAS,CAAC,WAAW,EAAE,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,SAAS,CAAC;IACpE,SAAS,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IACzE,SAAS,CAAC,YAAY,EAAE,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,SAAS,CAAC;gBAEzD,QAAQ,EAAE,SAAS,WAAW,EAAE;IAI5C,sCAAsC;IACtC,OAAO,IAAI,MAAM;IAUjB,uCAAuC;IACvC,QAAQ,IAAI,MAAM;IAUlB,4CAA4C;IAC5C,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,eAAe,GAAG,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC;IAcjF,4CAA4C;IAC5C,aAAa,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;IAYrC,+CAA+C;IAC/C,gBAAgB,IAAI,WAAW,CAAC,cAAc;IAgB9C,wCAAwC;IACxC,SAAS,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,gBAAgB,GAAG,gBAAgB,CAAC,MAAM,CAAC;IAO3E,6CAA6C;IAC7C,cAAc,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,qBAAqB,GAAG,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC;IAU7F;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,qBAAqB,GAAG,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC;IA2C1G,6CAA6C;IAC7C,cAAc,CAAC,KAAK,CAAC,EAAE,SAAS,UAAU,EAAE,GAAG;SAAG,GAAG,IAAI,UAAU,CAAC,CAAC,EAAE,MAAM;KAAE;IAmC/E,8CAA8C;IAC9C,IAAI,aAAa,IAAI,IAAI,CAAiB;IAE1C,SAAS,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,eAAe,GAAG,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC;CAmC/F"}

package/types/src/primitives/Criteria.d.ts

@@ -0,0 +1,35 @@
+import { IFormulaContext, Scalar } from '@sheetxl/primitives';
+/**
+ * Excel's criteria mini-language: the text a user types as the second argument of `COUNTIF`.
+ *
+ * @remarks
+ * One rule, shared by `COUNTIF`/`COUNTIFS`, `SUMIF`/`SUMIFS`, `AVERAGEIF`/`AVERAGEIFS`,
+ * `MAXIFS`/`MINIFS`, the `D` functions' criteria table, and `IFS`-style filtering — a criteria is
+ * a leading comparison operator, a wildcard pattern, or a literal, and every one of those is
+ * ultimately answered by {@link IFormulaContext.compare}.
+ *
+ * ### Not public API
+ *
+ * Reached as {@link IFormulaContext.createCriteria}, so a formula function never constructs one and
+ * never sees the parse. That is what lets the rule stay one implementation while
+ * `@sheetxl/formulas` — which sits below this package — uses it; the same arrangement
+ * `ScalarCollation` has, and for the same reason.
+ *
+ * ### The three planes
+ *
+ * A criteria string touches every localization plane at once, so all three are read through the
+ * context rather than hard-coded here:
+ * * the operand of a comparison parses as a NUMBER in the workbook's locale
+ *   ({@link IFormulaContext.parseAsNumber} — decimal separator, dates, percent);
+ * * a bare boolean word or error label reads in the workbook's LANGUAGE
+ *   ({@link IFormulaContext.parseAsLiteral} — `WAHR`, `#WERT!`);
+ * * text compares by the workbook's COLLATION ({@link IFormulaContext.compare}).
+ */
+export declare const Criteria: {
+    /**
+     * Parse criteria and return a predicate function for testing values against it.
+     * Each operator gets its own closure, avoiding repeated branching on every call.
+     */
+    createEvaluator: (context: IFormulaContext, criteria: Scalar) => IFormulaContext.CriteriaEvaluator;
+};
+//# sourceMappingURL=Criteria.d.ts.map

package/types/src/primitives/Criteria.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Criteria.d.ts","sourceRoot":"","sources":["../../../../src/primitives/Criteria.ts"],"names":[],"mappings":"AAAA,OAAO,EACmB,KAAK,eAAe,EAAE,KAAK,MAAM,EAC1D,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,QAAQ;IACnB;;;OAGG;+BACwB,eAAe,YAAY,MAAM,KAAG,eAAe,CAAC,iBAAiB;CAqFjG,CAAC"}

package/types/src/primitives/FormulaContext.d.ts

@@ -0,0 +1,2 @@
+export { FormulaContext, ScopedFormulaContext } from '@sheetxl/primitives';
+//# sourceMappingURL=FormulaContext.d.ts.map

package/types/src/primitives/FormulaContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormulaContext.d.ts","sourceRoot":"","sources":["../../../../src/primitives/FormulaContext.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}

package/types/src/primitives/PrimitiveUtils.d.ts

@@ -0,0 +1,255 @@
+import { ScalarType, InteropScalarType, FormulaError, IRange, Scalar, IFunction, IFormulaContext, InteropScalar, IRuntime } from '@sheetxl/primitives';
+import { ISparseGrid } from '../collections';
+export declare const REGEX_LITERAL_ARRAY: RegExp;
+export declare const defaultEntireCoords: IRange.Coords;
+export declare function defaultGetEntireCoords(): IRange.Coords;
+/**
+ * Stand-in bounds for a grid that conceptually has NONE — currently the virtual grid backing a
+ * named formula.
+ *
+ * @remarks
+ * A reference outside a grid's bounds rendering as `#REF!` is correct behavior, not a defect: a
+ * sheet has a size and an address beyond it is genuinely invalid. A virtual grid is different — it
+ * is a compilation host, not a sheet, and the references it holds belong to whatever sheets they
+ * name. It has no size for them to be outside of.
+ *
+ * The honest model is "no bounds at all", but enough of the engine assumes a bounds object exists
+ * (the full-calc dirty region, spill-bounds checks, entire-range collapse) that this approximates
+ * it with a value nothing can exceed.
+ *
+ * Deliberately NOT {@link defaultEntireCoords}, which is the DEFAULT sheet size (Excel's limits) —
+ * sheets may be larger. `MIN_SAFE_INTEGER` / `MAX_SAFE_INTEGER` are reserved as the sentinels for
+ * entire row / column references, so the value stays well clear of them: relative offsets are added
+ * to it without reaching a sentinel or losing integer precision.
+ */
+export declare const maxEntireCoords: IRange.Coords;
+export declare function maxGetEntireCoords(): IRange.Coords;
+/**
+ * Find the implied type from a Javascript value.
+ *
+ * @param jsV The `InteropScalar`.
+ * @param checkDate If `true` will check for `Date` and return a InteropScalarType..
+ * @returns The ScalarType or `null` if unable to determine.
+ *
+ * @remarks
+ * This will return a InteropScalarType if checkDate is set to true.
+ */
+export declare const typeFromJsValue: (jsV: InteropScalar, checkDate?: boolean) => ScalarType;
+export declare function valueTypeToString(type: IFunction.ValueTypeJSON): string;
+/**
+ * The largest magnitude Excel will PARSE from text or a formula literal — the biggest
+ * 15-significant-digit value below 1E+308. Measured (formula-tests/probe-boundaries.ps1):
+ * `=9.99999999999999E+307` commits, `=1.00000000000000E+308` is refused outright.
+ *
+ * An ENTRY rule only. Computed results are bounded by the double, not by this — `8.9E+307*2`
+ * = 1.78E+308 is far past it and Excel keeps, compares and round-trips the value happily.
+ */
+export declare const EXCEL_MAX_NUMBER = 9.99999999999999e+307;
+/**
+ * Renders a number the way Excel coerces one to TEXT (`&`, CONCAT, `LEFT(1/3,5)`, ...).
+ *
+ * This is NOT display "General" (that one is column-width-aware and caps at ~11 digits —
+ * `numfmt` implements it). Coercion General, measured against Excel 16.0
+ * (`spreadsheetbench/formula-tests/probe-general-coercion.ps1`):
+ *
+ * 1. round to 15 significant digits, trim trailing fraction zeros (`0.1+0.2` → `0.3`,
+ *    `2^0.5` → `1.4142135623731`);
+ * 2. write the plain decimal expansion if it fits in 20 characters, sign excluded
+ *    (`1/3*1E-3` → `0.000333333333333333` at exactly 20; `2^60` → `1152921504606850000`,
+ *    integers pad with zeros);
+ * 3. otherwise scientific with a two-digit-minimum exponent (`1E+20`, `3.33333333333333E-05` —
+ *    note `-99999999999999900000` is still decimal, but `1E+20` is not);
+ * 4. the DECIMAL SEPARATOR is the workbook locale's (`probe-general-locale.ps1`: `="" & 1.5`
+ *    is `1,5` once Excel's decimal separator is `,`). Only that one separator moves —
+ *    coercion never groups, so `1234.5` is `1234,5` and never `1.234,5`.
+ *
+ * This cannot route to `numfmt`: its `General` is the display one, its 11-character budget is
+ * not configurable (there is no precision option on `FormatOptions`), and "15 significant
+ * digits capped at 20 characters" is not expressible as an ECMA-376 pattern either —
+ * `0.##############` counts decimal PLACES, not significant digits.
+ *
+ * Formula modules reach this as `IFormulaContext.toText`, which is the only entry point that
+ * also handles non-numbers; this is the number-only form the coercion paths use.
+ *
+ * @param value The number to render.
+ * @param runtime Supplies the locale profile. `IRuntime.getLocaleProfile` is the single
+ * authority for separators — never derive one independently.
+ */
+export declare function formatNumberGeneral(value: number, runtime: IRuntime): string;
+/**
+ * Renders any scalar the way Excel coerces one to TEXT — the full
+ * {@link IFormulaContext.toText} rule, of which {@link formatNumberGeneral} is the number
+ * branch.
+ *
+ * Text passes through; blank (`null`/`undefined`) is `''`; booleans take the spreadsheet
+ * LANGUAGE's word (`=TRUE&""` is `"WAHR"` in German) — a different plane from the decimal
+ * separator, which comes from the workbook locale.
+ *
+ * @throws The incoming `FormulaError` itself — the error propagates with its identity, never
+ * a laundered `#VALUE!` (same convention as `IFormulaContext.parseAsNumber`).
+ */
+export declare function scalarToText(value: Scalar | undefined, runtime: IRuntime): string;
+export declare function createCoerceScalarFn(runtime: IRuntime, toType: InteropScalarType, coerceTypes?: readonly InteropScalarType[]): (fromValue: Scalar, fromType: InteropScalarType, options?: IFormulaContext.ParseNumberOptions) => Scalar;
+/**
+ * Will will convert a value from one type to another.
+ * This takes a string in additional to a ScalarType to support
+ * boxing non native types like `Date`.
+ */
+export declare function coerceScalar(runtime: IRuntime, value: any, fromType: InteropScalarType, toType?: InteropScalarType, includeBoolean?: boolean): Scalar;
+/**
+ * Returns FormulaError.Value if more than 1 value or doesn't convert.
+ *
+ * @param value The value to extract
+ * @param forceOne If true this will return an error if an range with size > 1.
+ *
+ * @remarks
+ * This will not extract if the range is a reference Range
+ */
+export declare function coerceToSingleValue(value: any, forceOne?: boolean): any;
+/**
+ * Returns FormulaError.Value if more than 1 value or doesn't convert.
+ *
+ * @param value
+ */
+export declare function isSingleValue(value: any): boolean;
+/**
+ * True when a value is a MULTI-AREA reference: the array of areas a union evaluates to —
+ * `(A1:A3,C1:C5)`, or a named formula whose body is a comma union. Each element is either a
+ * resolved range or the bare `Coords` an eval slot holds for a single-cell area.
+ *
+ * Distinguishes a union from the value arrays a function returns (`[1,2,3]`, `[[1,2],[3,4]]`),
+ * which are ordinary array results and coerce normally.
+ */
+export declare function isMultiAreaValue(value: any): boolean;
+/**
+ * Counts the depth of the array. If it is an IRange then it will always add 2.
+ */
+export declare function countArgDepth(value: any): number;
+export declare function flattenToScalarArray(context: IFormulaContext, coercedArr: FixedPackedArray | Scalar[], currentArg: any, isDirect: boolean | undefined, rangeType: string | null, // the range preference for dims higher than 2 (if not specified then will materialize to array values
+scalarType: ScalarType | null, // the scalar preference. If not specified no coercion will occur.
+errors?: 'reject' | 'accept' | null): void | FormulaError.Known;
+/**
+ * Returns a 2d shape. Either a reference.
+ */
+export declare function convertTo2D(context: IFormulaContext, currentArg: any, // IRange or coords
+rangeType: string | null, scalarType: ScalarType | null, // the scalar preference. If not specified no coercion will occur.
+isDirect: boolean, errors?: 'reject' | 'accept' | null): IRange | any[][] | FormulaError.Known;
+/**
+ * This will coerce a value and add it to the coercedArr. This is used in the argument coercion of typed functions.
+ *
+ * CoercedValues behave in special ways
+ *
+ * 1. If a value is *direct* (a scalar, whether typed or computed) it always coerces to the type.
+ * 2. If a value is a MEMBER of an array or a reference
+ *   a. It ignores everything except like values and errors
+ * 3. We then coerce to Ranges.
+ *
+ * `isDirect` is Excel's "the argument itself" vs "a member of a container" distinction —
+ * `SUM(1,TRUE)` is `2` but `SUM({1,TRUE})` is `1`. Callers derive it from the runtime shape of the
+ * evaluated argument; see `isDirectArg` in `TypedFunction`.
+ *
+ * Two things it is NOT, both measured (`probe-direct-vs-literal.ps1`, pinned in
+ * `functions2/coercion/DIRECT-VS-MEMBER.json`):
+ *
+ * - **Not literalness.** `{1,TRUE}` and `A1:A2` behave IDENTICALLY (members of both are filtered),
+ *   and the COMPUTED `A2>0` behaves like a typed `TRUE`. A container being a literal or a
+ *   reference changes nothing anywhere in the matrix.
+ * - **Not a property of the argument alone.** Membership requires a slot that CONSUMES members:
+ *   a scalar parameter takes one value, so a single-cell reference reaching it is dereferenced and
+ *   IS the argument (`ABS(A1)` and `MONTH(A1)` are 1 with A1=TRUE, while `SUM(A1)` is 0). Hence
+ *   `isMember` below is `!isDirect && flatten`, not `!isDirect`.
+ *
+ * The two halves at an aggregating slot: DIRECT arguments are COERCED (and a bad one errors —
+ * `SUM(1,"7e")` is `#VALUE!`), MEMBERS are TYPE-FILTERED (skipped silently, never coerced —
+ * `SUM({1,"7","7e","TRUE",TRUE})` is `1`).
+ *
+ * Some Built-in excel functions behave differently. When this occurs
+ * the use an argument type of Scalar (no coerce) and manage themselves
+ */
+export declare function addCoercedValue(context: IFormulaContext, coercedArr: FixedPackedArray | Scalar[], currentArg: any, isDirect: boolean, rangeType: 'p' | 'r' | 'm' | null, scalarType: ScalarType | null, // the scalar preference. If not specified then no coercion will occur.
+allowError: boolean, flatten: boolean, // indicates we should flatten
+errors?: 'reject' | 'accept' | null): FormulaError.Known | void;
+/**
+ * Minimal validation used from the return value of functions.
+ */
+/**
+ * Makes a raw JS double look like an Excel one. Excel arithmetic has neither Infinity nor
+ * subnormals, and this is the single rule that enforces both. Measured against Excel 16.0
+ * (formula-tests: probe-num-overflow.ps1, probe-boundaries.ps1, probe-api-nonfinite.ps1):
+ *
+ * * ANY non-finite value is #NUM! — NaN and ±Infinity alike. `9E+307*2`, `9E+307+9E+307` and
+ *   `9E+307/0.1` all report `ERROR.TYPE` 6, and a raw NaN or ±Infinity written through the
+ *   Value2 API lands as #NUM! too. Infinity does NOT mean #DIV/0!: Excel never derives that
+ *   error from a float, it raises it deliberately before dividing. Functions say so themselves
+ *   by returning `FormulaError.BuiltIn.Div0`.
+ * * a magnitude below the smallest NORMAL double flushes to ZERO, which also folds -0 to 0.
+ *   `1E-300*2.224E-8` is 0 while `1E-300*2.226E-8` survives, and the flush lands before the next
+ *   operator reads it — `=1/(1E-300*1E-100)` is #DIV/0!, not a huge number. The API agrees:
+ *   writing `Double.Epsilon` reads back 0.
+ *
+ * Excel applies this at EVERY boundary, so SheetXL does too — `minCoerce` for a calculated
+ * result, and the cell-write path for a value handed in through the API.
+ */
+export declare function normalizeNumber(value: number): number | FormulaError.Known;
+export declare function minCoerce(value: any, context?: IFormulaContext | null, type?: string): any;
+/**
+ * Loads a (possibly nested) array literal into a sparse grid and returns the pieces a `Range`
+ * constructor (or `Range._newRange`) needs to wrap it — not an `IRange` itself. Callers build the
+ * actual range (a `new Range(...)`, or `this._newRange(...)` to preserve a subclass) because doing
+ * it here would need this module to import `Range`, and `Range` imports this module for its own
+ * coercion helpers — a cycle that broke module init order for `condition/_ConditionUtils.ts`'s
+ * top-level `class ... extends Range` (see git history 2026-08-18).
+ */
+export declare function gridFromArray(value: Scalar | Scalar[][], values?: ISparseGrid, coords?: IRange.Coords | null): {
+    values: ISparseGrid;
+    coords: IRange.Coords;
+    isLiteral: boolean;
+};
+/**
+ * V8 Optimization
+ *
+ * This allows for reusing arrays. This requires not using the length on the array.
+ */
+export interface FixedPackedArray<T = any> {
+    values: T[];
+    length: number;
+}
+/**
+ * V8 Optimization
+ *
+ * Is seems the new Array(length) because it uses holey arrays.
+ * Push causes reallocation a bunch times.
+ *
+ * This should be only used for reusable arrays where they are long lived
+ * and need to be fast (and not resized (much)).
+ */
+export declare function createPackedArray<T = any>(length: number, value?: T): T[];
+/**
+ * Create a packed array but with undefined values.
+ *
+ * @see createPackedArray
+ */
+export declare function createEmptyPackedArray<T = any>(length: number): T[];
+export declare const StringCoerceTypes: readonly InteropScalarType[];
+export declare const BooleanCoerceTypes: readonly InteropScalarType[];
+/**
+ * What a `date` parameter accepts, and deliberately the same set the scalar path
+ * ({@link coerceScalar}) already accepted — a serial, date-like or numeric text, and an empty cell
+ * (serial 0, so `HOUR(<empty>)` is 0 rather than `#VALUE!`).
+ *
+ * A spreadsheet has no distinct date type; a date IS a number. So unlike `number` — which is
+ * deliberately strict, because a range aggregate must ignore stray text the way Excel does —
+ * `date` has to coerce from number, or every date function over a range matches nothing at all.
+ */
+export declare const DateCoerceTypes: readonly InteropScalarType[];
+/**
+ * What a `null` read accepts. Coercing TO `null` asks for each value's empty equivalent — `0`,
+ * `''`, `false` — which is exactly what the branch in {@link createCoerceScalarFn} already
+ * implemented, and which was unreachable for the same reason `date`'s was (CALC-ISSUES §14 H2).
+ *
+ * Not reachable from a declaration — `TypedFunction` normalizes a `null` scalar param to "no
+ * type" — so this serves a direct `toType(ScalarType.Null)` caller.
+ */
+export declare const NullCoerceTypes: readonly InteropScalarType[];
+export declare const AllScalarTypes: readonly InteropScalarType[];
+//# sourceMappingURL=PrimitiveUtils.d.ts.map

package/types/src/primitives/PrimitiveUtils.d.ts.map

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