@sheetxl/primitives 0.7.27 → 0.7.28-beta.1

package/types/src/LocaleProfile.d.ts

@@ -0,0 +1,79 @@
+/** 0=Sun..6=Sat */
+export type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+export type CurrencyDisplay = "symbol" | "code" | "name";
+export type CurrencyPosition = "before" | "after";
+export type CurrencySpacing = "tight" | "space";
+/**
+ * Everything regional behavior depends on, resolved for a single locale.
+ *
+ * @remarks
+ * This is the one source of truth for separators, date patterns, currency, and
+ * collation. It is derived data -- the identity is the BCP 47 tag, which is what
+ * a workbook persists.
+ */
+export interface LocaleProfile {
+    /** The BCP 47 tag this profile was resolved from, e.g. `de-DE`. */
+    tag: string;
+    numberingSystem: string;
+    decimal: string;
+    group: string;
+    /** e.g. `[3]`, or `[3,2]` for hi-IN. */
+    grouping: number[];
+    minusSign: string;
+    percentSign: string;
+    /** usually `‰` */
+    permilleSign: string;
+    /** ISO 4217 code for the region, e.g. `EUR`. */
+    currencyCode: string;
+    /** The rendered symbol for {@link LocaleProfile.currencyCode}, e.g. `€`. */
+    currencySymbol: string;
+    currencyDisplay: CurrencyDisplay;
+    currencyPosition: CurrencyPosition;
+    currencySpacing: CurrencySpacing;
+    date: {
+        /** e.g. `gregory` */
+        calendar: string;
+        /** e.g. `M/d/yy` */
+        short: string;
+        /** e.g. `MMM d, y` */
+        medium: string;
+        /** e.g. `MMMM d, y` */
+        long: string;
+        /** e.g. `h:mm a` or `HH:mm` */
+        timeShort: string;
+        /** e.g. `h:mm:ss a z` -- note: `z` is a hint only */
+        timeLong: string;
+        am?: string;
+        pm?: string;
+        firstDay: DayOfWeek;
+        weekend: [DayOfWeek, DayOfWeek];
+        monthsWide: string[];
+        monthsAbbr: string[];
+        weekdaysWide: string[];
+        weekdaysAbbr: string[];
+        hour12: boolean;
+    };
+    /** Function/list argument separator, like Excel (`,` or `;`). */
+    listSeparator: string;
+    csvDelimiter: string;
+    rtl: boolean;
+    /** Collation defaults for sorting. */
+    collator: Intl.CollatorOptions;
+}
+/**
+ * A patch over an `Intl`-derived {@link LocaleProfile} — the regional-override escape
+ * hatch. Excel/Windows honor OS regional *customizations* (a custom decimal symbol,
+ * a different currency) that browser `Intl` cannot see; a workbook may persist
+ * `{ tag, overrides? }` to reproduce them.
+ *
+ * @remarks
+ * Overrides are applied **literally** on top of the derived profile — nothing is
+ * re-derived. In particular {@link LocaleProfile.listSeparator} /
+ * {@link LocaleProfile.csvDelimiter} are normally derived from `decimal`, so patch
+ * them too if you patch `decimal`. The `date` sub-object merges one level deep; the
+ * `tag` is the identity and cannot be overridden.
+ */
+export type LocaleProfileOverrides = Partial<Omit<LocaleProfile, 'tag' | 'date'>> & {
+    date?: Partial<LocaleProfile['date']>;
+};
+//# sourceMappingURL=LocaleProfile.d.ts.map

package/types/src/Observable.d.ts

@@ -0,0 +1,46 @@
+/**
+ * An object interface that defines a set of callback functions a user can use to get
+ * notified of any set of {@link Observable}.
+ *
+ * @see {@link https://rxjs.dev/api/index/class/Observable | Observable}
+ */
+export declare class Observable<T = any> {
+    protected _subscribeFn: (subscriber: Subscriber<T>) => () => void;
+    constructor(subscribeFn: (subscriber: Subscriber<T>) => () => void);
+    subscribe(next: any, error: (err: any) => void, complete: () => void): {
+        next: any;
+        error: any;
+        complete: any;
+        unsubscribe: () => void;
+    };
+}
+/**
+ * An object interface that defines a set of callback functions a user can use to get
+ * notified of any set of {@link Observable}.
+ */
+export interface Subscriber<T> {
+    /**
+     * A callback function that gets called by the producer during the subscription when
+     * the producer "has" the `value`. It won't be called if `error` or `complete` callback
+     * functions have been called, nor after the consumer has unsubscribed.
+     */
+    next: (value: T) => void;
+    /**
+     * A callback function that gets called by the producer if and when it encountered a
+     * problem of any kind. The errored value will be provided through the `err` parameter.
+     * This callback can't be called more than one time, it can't be called if the
+     * `complete` callback function have been called previously, nor it can't be called if
+     * the consumer has unsubscribed.
+     */
+    error: (err: any) => void;
+    /**
+     * A callback function that gets called by the producer if and when it has no more
+     * values to provide (by calling `next` callback function). This means that no error
+     * has happened. This callback can't be called more than one time, it can't be called
+     * if the `error` callback function have been called previously, nor it can't be called
+     * if the consumer has unsubscribed.
+     */
+    complete: () => void;
+    unsubscribe: () => void;
+}
+//# sourceMappingURL=Observable.d.ts.map

package/types/src/Omittable.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Declares what a parameter means when the caller supplies it EMPTY — `FIXED(1.5,)`, a comma with
+ * nothing before it.
+ *
+ * @remarks
+ * A spreadsheet argument has three positions rather than two, and each carries its own meaning:
+ *
+ * | call | position | the parameter receives |
+ * | --- | --- | --- |
+ * | `FIXED(1.5)` | absent | nothing, so the parameter's own initializer applies |
+ * | `FIXED(1.5,)` | omitted | whatever this marker declares |
+ * | `FIXED(1.5,E1)` | a blank cell | the value `0` / `false` / `""` |
+ *
+ * The last row is why omission needs a declaration of its own. A blank cell is a VALUE the caller
+ * supplied and coerces like any other, so "empty" cannot simply mean "unspecified" everywhere —
+ * and functions disagree about which of the two an empty comma resembles.
+ *
+ * Undeclared, an omitted argument coerces exactly as a blank cell does. Declared, it means `V`
+ * where one is given, and otherwise means whatever an absent argument means.
+ *
+ * @typeParam T - the parameter's type; the marker is otherwise transparent.
+ * @typeParam V - what an omitted argument means, where that differs from the absent default.
+ *
+ * @example An omitted argument means the default, and one initializer serves both positions.
+ * ```ts
+ * export function FIXED(number: number, decimals: Omittable<number> = 2): string
+ * ```
+ *
+ * @example An omitted argument means something else, so both values are spelled out.
+ * ```ts
+ * // absent is 1 (approximate); omitted is 0 (exact)
+ * export function MATCH(lookupValue: IRange, lookupArray: IRange,
+ *   matchType: Omittable<number, 0> = 1): Scalar
+ * ```
+ *
+ * @example An omitted argument is not a value at all, and the body answers for it. Without an
+ * initializer to fall back on, the parameter is REQUIRED and the omission reaches it as
+ * `undefined` — which is a different thing from the `null` a blank cell coerces to.
+ * ```ts
+ * export function WEEKNUM(serialNumber: Omittable<Scalar>, returnType: Omittable<Scalar> = 1): number
+ * ```
+ *
+ * Supplying `V` leaves the parameter's type untouched; leaving it off adds `undefined`, so a
+ * declaration carrying an initializer sees a plain `T` while one without it is made to handle the
+ * omission.
+ *
+ * @see {@link IFunction.ParameterTypeJSON.omittable}
+ */
+export type Omittable<T, V = never> = [V] extends [never] ? T | undefined : T;
+//# sourceMappingURL=Omittable.d.ts.map

package/types/src/Repeating.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Declares a REPEATING PARAMETER GROUP: one declared parameter whose arguments arrive as a
+ * fixed-size cycle repeated N times. `SUMIFS(sum, r1, c1, r2, c2, …)` is one `sumRange` followed
+ * by a `[criteriaRange, criteria]` group repeated as many times as the caller supplied.
+ *
+ * At the type level it is `T[]`, so the body reads exactly what it is handed:
+ *
+ * | declaration | period | body receives |
+ * | --- | --- | --- |
+ * | `Repeating<[a: IRange, b: Scalar]>` | 2 | `[IRange, Scalar][]` |
+ * | `Repeating<IRange>` | 1 | `IRange[]` |
+ *
+ * **Period 1 is spelled without the tuple** — a one-element tuple is a compiler error, because
+ * `[IRange][]` and `IRange[]` would otherwise be two ways to say the same thing. A period-1 group
+ * takes its slot name from the parameter itself, so `array: Repeating<IRange>` shows as
+ * `array1, array2, …` — the same display a rest parameter gets, and the reason `Repeating` can
+ * replace the `first + ...rest` split that reads as `array, rest1, rest2`.
+ *
+ * ### Why this exists rather than a rest parameter
+ *
+ * `...rest: T[]` has ONE type for every trailing argument, so a period-2 group has to declare its
+ * slots as their union — which makes the criteria slots of pairs 2+ invisible to every consumer
+ * that reads the declaration per position. The implicit-intersection site predicate is the one
+ * that matters: it saw `SUMIFS`'s criteria as a range parameter and under-marked the formula.
+ * A group binds argument `i` to slot `(i − prefix) % period`, so every repetition types the same
+ * as the first.
+ *
+ * A group also carries a real MINIMUM: at least one repetition is required. That is the whole
+ * difference from a rest parameter, which is 0-or-more and remains the spelling for it:
+ *
+ * ```ts
+ * ...x: T[]                    // 0 or more
+ * x: T[]                       // 1 or more  (a period-1 group; an array IS a repeat of one)
+ * x: Repeating<[a: A, b: B]>   // 1 or more, period 2+
+ * ```
+ *
+ * So `x?: T[]` is refused — it would be a second way to say `...x: T[]`.
+ *
+ * ### Arity is arithmetic, never type-directed
+ *
+ * `n = (argc − prefix − suffix) / period`, and a non-zero remainder is an error.
+ *
+ * ### The one short form
+ *
+ * The LAST slot of a group may be declared optional, which means exactly one thing: it may be
+ * omitted when there is a single repetition. `SORTBY`'s legal arities are 2 and 1+2n and nothing
+ * else — `SORTBY(array, by1)` is legal, `SORTBY(array, by1, o1, by2)` is not. It is not a general
+ * "the final element of the final group may be omitted" rule; that rule would accept a formula
+ * Excel refuses. An optional slot anywhere else in the group is a compiler error.
+ *
+ * @example
+ * ```ts
+ * export function SUMIFS(
+ *   sumRange: AcceptError<IRange>,
+ *   criteria: Repeating<[criteriaRange: AcceptError<IReferenceRange>, criteria: AcceptError<IRange>]>
+ * ): IRange {
+ *   for (const [range, test] of criteria) { ... }
+ * }
+ *
+ * export function HSTACK(array: Repeating<AcceptError<IRange>>): IRange {
+ *   return array.reduce((acc, next) => acc.concat(next, IRange.Axis.Column));
+ * }
+ * ```
+ */
+export type Repeating<T> = T[];
+//# sourceMappingURL=Repeating.d.ts.map

package/types/src/Scalar.d.ts

@@ -0,0 +1,67 @@
+import { FormulaError } from './FormulaError';
+import { IRichData } from './IRichData';
+/**
+ * The fundamental value type of the spreadsheet engine.
+ *
+ * `Scalar` is what cells hold and what formula functions receive and return.
+ * It covers every native spreadsheet type — numbers (including dates, which
+ * are stored as serial numbers), strings, booleans, errors, rich data objects,
+ * and blank (`null`).
+ *
+ * Use `Scalar` wherever a value could be any cell-compatible type. When you
+ * need to accept a JavaScript `Date` at an API boundary, use {@link InteropScalar}
+ * instead.
+ *
+ * @remarks
+ * Dates are not a distinct `Scalar` variant — they are numbers with a format
+ * applied. `FormulaContext.parseAsDate` / `toSerialDate` convert between the
+ * two representations.
+ *
+ * @see {@link InteropScalar} for a version that includes `Date`.
+ * @see {@link ScalarType} for the companion enum that identifies which variant a value is.
+ */
+export type Scalar = number | boolean | string | FormulaError.Known | IRichData | null;
+export declare namespace Scalar {
+    /**
+     * The most characters a text scalar (and therefore a cell) can hold.
+     */
+    const MAX_TEXT_LENGTH = 32767;
+    /**
+     * The most significant digits a number parsed FROM TEXT can carry.
+     */
+    const MAX_SIGNIFICANT_DIGITS = 15;
+    /**
+     * Applies Excel's entry rule to numeric text: every significand digit past the
+     * 15th becomes `0`, so the text parses to the double Excel would store.
+     *
+     * @param text Numeric text in any accepted form — signed, grouped, percent,
+     * currency-affixed, or scientific. The scan is locale-blind: only digit
+     * characters count toward significance (separators pass through untouched),
+     * leading zeros carry none, and the scan stops at an exponent marker so `E5`
+     * keeps its magnitude. Excess digits are zeroed rather than dropped so the
+     * text's shape (decimal places, grouping) survives for format inference.
+     *
+     * @remarks
+     * Callers apply this to every text→number path and to nothing else — measured
+     * truncation, not rounding: `1234567890.123456789` stores `…345`, never `…346`.
+     */
+    function truncateNumberText(text: string): string;
+}
+/**
+ * Represents a cell value in JavaScript, including `Date` for convenience.
+ *
+ * Extends `Scalar` to support `Date`.
+ *
+ * @remarks
+ * ** IMPORTANT** Spreadsheets store dates internally as serial numbers (SerialDates) to optimize calculation performance. These are integer values representing
+ * the number of days since either January 1, 1900, or January 1, 1904, depending on the container's settings.
+ *
+ * For type-safe date retrieval consider using the method, which returns null if the cell value is not a valid date.
+ *
+ * @see
+ * Refer to the following resources for more details:
+ * * {@link https://support.microsoft.com/en-us/office/date-systems-in-excel-e7fe7167-48a9-4b96-bb53-5612a800b487 | Date systems in Excel}
+ * * {@link https://learn.microsoft.com/en-us/dotnet/api/system.datetime.tooadate?view=net-8.0 | DateTime.ToSerialDate Method}
+ */
+export type InteropScalar = Scalar | Date;
+//# sourceMappingURL=Scalar.d.ts.map

package/types/src/ScalarType.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Identifies which variant of {@link Scalar} a cell value is.
+ *
+ * Because `Scalar` is a union type, `ScalarType` gives you a safe, string-based
+ * discriminant for branching on value kind — useful in formula implementations,
+ * data-profiling UIs, and type-coercion logic without relying on `typeof` or
+ * `instanceof` checks that do not cover all cases (e.g. `null`, `FormulaError`,
+ * `IRichData`).
+ *
+ * @remarks
+ * Dates have no dedicated variant. They are stored as `Number` values with a
+ * number format applied. Use `FormulaContext.isValidDate` to distinguish them
+ * at runtime. `InteropScalarType` extends this enum with a `Date` variant for
+ * API boundaries that accept JavaScript `Date` objects.
+ *
+ * @see {@link Scalar} for the value type this enum describes.
+ * @see {@link InteropScalarType} for the superset that includes `Date`.
+ */
+export declare const ScalarType: {
+    /**
+     * A numeric value.
+     *
+     * @remarks
+     * Dates are expressed as formatted numbers within cells. They are internally stored as
+     * serial numbers and can be formatted to display as dates.
+     */
+    readonly Number: "number";
+    /**
+     * A string value.
+     */
+    readonly String: "string";
+    /**
+     * A boolean value (`true` or `false`).
+     */
+    readonly Boolean: "boolean";
+    /**
+     * A cell that contains an error value.
+     *
+     * @remarks
+     * Error cells represent cells where an error occurred during formula evaluation or data processing.
+     */
+    readonly Error: "error";
+    /**
+     * A complex data type represented as {@link IRichData}.
+     *
+     * @remarks
+     * Rich data are objects that have complex structures and can contain data that goes beyond simple strings, numbers,
+     * booleans, or error values. For example, hyperlinks and images are represented as rich data.
+     */
+    readonly RichData: "richData";
+    /**
+     * Represents the absence of a value.
+     */
+    readonly Null: "null";
+};
+export type ScalarType = typeof ScalarType[keyof typeof ScalarType];
+/**
+ * Extends ScalarType to support `Date`.
+ *
+ * @see {@link InteropScalar | Javascript Dates}
+ */
+export declare const InteropScalarType: {
+    /**
+     * A date value.
+     *
+     * @remarks
+     * Dates are represented as serial numbers in the underlying data model but
+     * can be identified as dates through formatting. This type is used to indicate that a
+     * cell's value should be treated as a date, even though it's stored as a number.
+     */
+    readonly Date: "date";
+    /**
+     * A numeric value.
+     *
+     * @remarks
+     * Dates are expressed as formatted numbers within cells. They are internally stored as
+     * serial numbers and can be formatted to display as dates.
+     */
+    readonly Number: "number";
+    /**
+     * A string value.
+     */
+    readonly String: "string";
+    /**
+     * A boolean value (`true` or `false`).
+     */
+    readonly Boolean: "boolean";
+    /**
+     * A cell that contains an error value.
+     *
+     * @remarks
+     * Error cells represent cells where an error occurred during formula evaluation or data processing.
+     */
+    readonly Error: "error";
+    /**
+     * A complex data type represented as {@link IRichData}.
+     *
+     * @remarks
+     * Rich data are objects that have complex structures and can contain data that goes beyond simple strings, numbers,
+     * booleans, or error values. For example, hyperlinks and images are represented as rich data.
+     */
+    readonly RichData: "richData";
+    /**
+     * Represents the absence of a value.
+     */
+    readonly Null: "null";
+};
+export type InteropScalarType = typeof InteropScalarType[keyof typeof InteropScalarType];
+//# sourceMappingURL=ScalarType.d.ts.map

package/types/src/WildCard.d.ts

@@ -0,0 +1,26 @@
+import { Scalar } from './Scalar';
+/**
+ * Wildcard syntax: `*` for any run of characters, `?` for exactly one, `~` to escape.
+ */
+export declare const WildCard: {
+    /**
+     * Indicates if the give item is a wildcard string.
+     */
+    isWildCard: (obj: Scalar) => boolean;
+    /**
+     * Compiles Excel wildcard text into a regex.
+     *
+     * @param anchor Whether the pattern must match the WHOLE string. Excel matches a whole cell, so
+     * every lookup and criteria caller anchors; `SEARCH`, which looks for a substring, does not.
+     *
+     * @remarks
+     * `~` escapes the next `*`, `?` or `~`; standing alone it is a literal tilde (`COUNTIF(range,
+     * "a~b")` finds the text `a~b`). One left-to-right pass, because chained replaces cannot express
+     * this: the previous implementation guarded its `*`/`?` rewrites with `([^~]??)`, a lazy OPTIONAL
+     * group that matches empty and so guards nothing, and then unescaped `~([?*])` — which could
+     * never fire, the `*` and `?` having already become `.*` and `.`. Every escape was silently
+     * ignored, so `"~*"` compiled to `~.*`: a literal tilde followed by anything.
+     */
+    toRegex: (lookupText: string, flags?: any, anchor?: boolean) => RegExp;
+};
+//# sourceMappingURL=WildCard.d.ts.map

package/types/src/index.d.ts

@@ -0,0 +1,20 @@
+export * from './Scalar';
+export * from './ScalarType';
+export * from './WildCard';
+export * from './Lambda';
+export * from './ErrorPolicy';
+export * from './Repeating';
+export * from './Flatten';
+export * from './Omittable';
+export * from './IRange';
+export * from './IReferenceRange';
+export * from './IRichData';
+export * from './IFunction';
+export * from './IFormulaContext';
+export * from './LocaleProfile';
+export * from './IRuntime';
+export * from './IRangeStats';
+export * from './FormulaError';
+export * from './Observable';
+export * from './FormulaContext';
+//# sourceMappingURL=index.d.ts.map