@sheetxl/sdk 0.7.21 → 0.7.23-beta.2

package/types/src/date/_DateUtils.d.ts

@@ -0,0 +1,122 @@
+import { NumberFormatRef } from '../numFmt/BuiltInFormats';
+import { IRuntime } from '@sheetxl/primitives';
+export declare const MAX_SERIAL_DATE = 2958465;
+export declare function isValidDate(d: any, jsDateOnly?: boolean): boolean;
+export declare function minutesSinceMidnight(date: Date): number;
+export declare function dayDiff(d1: Date, d2: Date): number;
+export declare function monthDiff(startDate: Date, endDate: Date): number;
+export declare function yearDiff(d1: Date, d2: Date): number;
+export declare function dateUnitDiff(d1: Date, d2: Date, unit: DateUnit | string): number | undefined;
+export declare const DateUnit: {
+    readonly Day: "d";
+    readonly Month: "m";
+    readonly Year: "y";
+};
+export type DateUnit = typeof DateUnit[keyof typeof DateUnit];
+export declare function addDateUnit(date: Date, count: number, unit: DateUnit | string): Date | null;
+export declare function stringToLocalDate(value: string): Date | null;
+export declare function isISODateString(value: string): boolean;
+export declare function toUTCDate(utc: Date): Date;
+export declare function toLocalDate(utc: Date): Date;
+export declare function toISODateString(date: Date): string;
+export declare function toMidnight(date: Date | number): Date;
+export declare function today(): Date;
+export declare function largestDateUnit(datesOrig: readonly Date[], sorted?: boolean, _date1904?: boolean): DateUnit;
+export interface ParsedDateTime {
+    /** year */
+    year: number;
+    /** month. 1 based. 1 = Jan, 12 = Dec  */
+    month: number;
+    /** day of month. 1 based */
+    day: number;
+    /** hour. a 24 hour clock */
+    hour: number;
+    /** minute. a 0 based */
+    minute: number;
+    /** second. 0 based */
+    second: number;
+    /** millis-second. 0 based */
+    millis: number;
+    /** day of week. 1 based from Monday. 1 = Mon, 2 = Tue, ..., 7 = Sun */
+    dow: number;
+    /** date component without the time */
+    /** data and time component */
+    serial: number;
+}
+/**
+ * Splits a serial date into its calendar and clock fields.
+ *
+ * @param reuseParts Avoids allocating a fresh `ParsedDateTime`:
+ * - An object: the fields are written into THIS object, which is returned. The caller owns the
+ *   buffer's lifetime — do not hold onto a previous result across a reused call, each call
+ *   overwrites it in place. For an operator that calls this once per cell over a large range.
+ * - `true`: the fields are written into a shared module-level scratch object and returned —
+ *   for a one-off caller (a single-value formula function like `YEAR`/`MONTH`/`DAY`) that just
+ *   wants to avoid the allocation without owning a buffer itself. The result must be consumed
+ *   immediately (read a field, done) — a second `true` call anywhere overwrites it.
+ */
+export declare function parseSerialDate(serialDate: number, date1904?: boolean, reuseParts?: ParsedDateTime | boolean): ParsedDateTime | null;
+/**
+ * Serial date from parsed date/time fields.
+ *
+ * Computed directly from the fields (see {@link serialFromFields}) rather than
+ * by building a JS `Date` and converting it — that round trip was both lossy
+ * (~1e-12, catastrophic for bare times) and unable to express Excel's phantom
+ * `1900-02-29`, which a `Date` normalizes away.
+ */
+export declare function serialDateFromParsed(parsed: ParsedDateTime, date1904?: boolean): number | null;
+export declare function fromSerialDate(serialDate: number, date1904?: boolean): Date | null;
+/**
+ * Encode date to oa date (ole automation, used by Excel)
+ * @param {Date} date
+ * @param {boolean} [date1904] Whether to use the 1904 Date System. See https://bettersolutions.com/excel/dates-times/1904-date-system.htm
+ *
+ * http://markitondemand.github.io/moment-msdate/
+ *
+ * https://docs.microsoft.com/en-US/office/troubleshoot/excel/wrongly-assumes-1900-is-leap-year
+ * https://docs.microsoft.com/en-us/dotnet/api/system.datetime.tooadate?redirectedfrom=MSDN&view=net-5.0#System_DateTime_ToSerialDate
+ * https://bettersolutions.com/excel/dates-times/1904-date-system.htm
+ */
+export declare function toSerialDate(date: Date, date1904?: boolean): number | null;
+export interface DateNumberInput {
+    numberFormat: string;
+    asSerialDate: number;
+    asJSDate: Date;
+}
+export interface ParsedDateTimeInput {
+    numberFormat: string;
+    parsed: Partial<ParsedDateTime>;
+    leadingText: string;
+    /**
+     * Text after the time that is not part of it (`10:00 AM 2024-01-01` ->
+     * `2024-01-01`). Only ever non-empty when the caller opted in via
+     * `allowTrailingText`; without the opt-in such input fails to parse.
+     */
+    trailingText: string;
+}
+export declare function parseAsTimeInput(runtime: IRuntime, strValue: string, allowLeadingText?: boolean, allowTrailingText?: boolean): ParsedDateTimeInput | null;
+/**
+ * Adjusts a date parsed by date-fns to ensure consistent UTC interpretation
+ * while preserving the time component
+ */
+export declare function adjustDateForTimezone(parsedDate: Date): Date;
+/**
+ * Returns a DateNumberInput or null.
+ *
+ * @param strValue
+ * @returns DateNumberInput is parsable as a date or null if not
+ */
+export declare const parseAsDateInput: (runtime: IRuntime, strValue: string, currentTime?: number | null, 
+/** Internal: set on the one retry with digit<->letter boundaries spaced out, to stop recursion. */
+isBoundarySplit?: boolean, 
+/**
+ * Also accept the shapes Excel refuses that a clipboard paste produces — currently
+ * the weekday-prefixed long date (`Sunday, July 20, 1969`). Cell input passes
+ * `true`; the formula path leaves it `false` so `DATEVALUE` answers exactly what
+ * Excel answers. See {@link _buildDateInputFormats}.
+ */
+allowPasteShapes?: boolean) => DateNumberInput | null;
+export declare function isDateFormatter(fmt: NumberFormatRef): boolean;
+export declare function isTimeFormatter(fmt: NumberFormatRef): boolean;
+export declare function parseAsDateAndTimeInput(runtime: IRuntime, dateText: string, requireDate?: boolean): number | null;
+//# sourceMappingURL=_DateUtils.d.ts.map

package/types/src/date/_DateUtils.d.ts.map

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

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/date/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,aAAa,CAAC"}

package/types/src/externalBook/ExternalBookCollection.d.ts

@@ -0,0 +1,36 @@
+import { IExternalBook } from './IExternalBook';
+import { IExternalBookCollection } from './IExternalBookCollection';
+/**
+ * Implementation for {@link IExternalBookCollection}.
+ */
+export declare class ExternalBookCollection implements IExternalBookCollection {
+    /**
+     * Positional, `[n]`-indexed (`_items[0]` is `[1]`) — `null` at a position is a DDE/OLE link or
+     * otherwise unmodeled. Gaps carry meaning (the position still counts), so this is never compacted.
+     */
+    private _items;
+    constructor(options?: ExternalBookCollection.ConstructorOptions);
+    [Symbol.iterator](): IterableIterator<IExternalBook>;
+    /** Only the modeled books — gaps (DDE/OLE) are omitted, not positional. Use {@link getByIndex} for `[n]` lookup. */
+    getItems(): IExternalBook[];
+    getCount(): number;
+    getByIndex(n: number): IExternalBook | null;
+    toJSON(): (IExternalBook.JSON | null)[] | null;
+    readonly isIExternalBookCollection: true;
+}
+export declare namespace ExternalBookCollection {
+    interface ConstructorOptions {
+        /**
+         * Books to hydrate at construction, in `IWorkbook.JSON.externalBooks` order — which IS `[n]`
+         * order (1-based). A `null` entry is a preserved gap (see {@link IExternalBookCollection.getByIndex}).
+         *
+         * @remarks
+         * Taken here rather than through a separate `fromJSON()` call — mirrors
+         * `NamedFormulaCollection`'s reasoning: this collection owns the items, so hydrating at
+         * construction avoids a pre-load lifecycle state. Unlike named formulas, nothing here is
+         * mutable yet, so there is no transactional persist scope to speak of either.
+         */
+        json?: (IExternalBook.JSON | null)[];
+    }
+}
+//# sourceMappingURL=ExternalBookCollection.d.ts.map

package/types/src/externalBook/ExternalBookCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExternalBookCollection.d.ts","sourceRoot":"","sources":["../../../../src/externalBook/ExternalBookCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,KAAK,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAoCzE;;GAEG;AACH,qBAAa,sBAAuB,YAAW,uBAAuB;IAEpE;;;OAGG;IACH,OAAO,CAAC,MAAM,CAA0B;gBAE5B,OAAO,CAAC,EAAE,sBAAsB,CAAC,kBAAkB;IAI/D,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,aAAa,CAAC;IAIpD,oHAAoH;IACpH,QAAQ,IAAI,aAAa,EAAE;IAU3B,QAAQ,IAAI,MAAM;IAIlB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAI3C,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,GAAG,IAAI;IAK9C,QAAQ,CAAC,yBAAyB,EAAG,IAAI,CAAU;CACpD;AAED,yBAAiB,sBAAsB,CAAC;IACtC,UAAiB,kBAAkB;QACjC;;;;;;;;;WASG;QACH,IAAI,CAAC,EAAE,CAAC,aAAa,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;KACtC;CACF"}

package/types/src/externalBook/IExternalBook.d.ts

@@ -0,0 +1,97 @@
+import { Tuple } from '../collections';
+import { ICell } from '../cell';
+/**
+ * A cached snapshot of another workbook, referenced from a formula as `[n]Sheet1!$A$1`.
+ *
+ * @remarks
+ * Excel's external link is not a live reference — it is the cache plus enough identity to go
+ * re-fetch the source. See the design doc for the full model:
+ * `private-assets/design/calc/DESIGN-EXTERNAL-LINKS.md`.
+ *
+ * Read-only. There is no `setPath`/`breakLinks` here yet — authoring lands with the resolver API
+ * (design doc §4C), not this phase.
+ */
+export interface IExternalBook {
+    /**
+     * The book's identity, as read from its part's own relationships — an ORDERED list, not a single
+     * path with optional alternates. A book can carry several of these at once (`externalLinkPath`,
+     * `xlExternalLinkPath/xlPathMissing`, `externalLinkLongPath`, and the xxl21 `alternateUrls`
+     * extension are all instances of this one shape).
+     */
+    getIdentity(): readonly IExternalBook.IdentityEntry[];
+    /**
+     * The source book's sheet names, in its own order — the ONLY names the book is known by.
+     *
+     * @remarks
+     * `[n]Sheet1!...` addresses a sheet by its position in THIS list, not by a stable id — the source
+     * workbook has no idea SheetXL exists.
+     */
+    getSheetNames(): readonly string[];
+    /**
+     * The source book's own defined names, as seen at cache time — raw, uncompiled text.
+     *
+     * @remarks
+     * Parsing `refersTo` into something evaluable is phase 2/3's job (design doc §5). Kept verbatim
+     * here so nothing is lost between read and then.
+     */
+    getDefinedNames(): readonly IExternalBook.DefinedNameEntry[];
+    /**
+     * The cached cell values for one of the book's sheets, or `null` if that sheet was never cached.
+     *
+     * @remarks
+     * **Sparse, and uncached is not the same as empty.** Values only — no format, no style, no
+     * comment; a cached date is a plain serial (design doc §2.5).
+     *
+     * @param sheetIndex Position in {@link getSheetNames}, matching the XML's `sheetId` (0-based).
+     */
+    getSheetData(sheetIndex: number): IExternalBook.SheetData | null;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIExternalBook: true;
+    toJSON?(): IExternalBook.JSON | null;
+}
+export declare namespace IExternalBook {
+    /**
+     * One `(relTypeUri, target)` pair from the book part's own relationships.
+     *
+     * @remarks
+     * `type` is the full relationship-type URI (not a shorthand) — it is what tells apart an
+     * `externalLinkPath`, an `xlExternalLinkPath/xlPathMissing` (a bare name, not a URI), an
+     * `externalLinkLongPath`, and an xxl21 `alternateUrls` entry. Emitting one under a hard-coded rel
+     * type would silently rewrite what the source file said.
+     */
+    interface IdentityEntry {
+        type: string;
+        target: string;
+    }
+    interface DefinedNameEntry {
+        name: string;
+        /** The raw `[0]Sheet1!$A$1`-style text — not parsed or compiled in this phase. */
+        refersTo: string;
+        /** Position in {@link IExternalBook.getSheetNames}, when the name is sheet-scoped. */
+        sheetIndex?: number;
+    }
+    interface SheetData {
+        /** Position in {@link IExternalBook.getSheetNames} this cache belongs to — the XML's `sheetId`, 0-based. */
+        sheetIndex: number;
+        /** `<sheetData refreshError="1">` — Excel could not refresh this sheet's cache last time it tried. */
+        refreshError?: boolean;
+        /**
+         * Sparse cell values — the same encoding `ISheet.JSON.data` uses (`ICell.JSON` is already just
+         * the value+type pair; style/formula live in sibling fields there, none of which apply to a
+         * values-only cache — design doc §2.5).
+         */
+        data: Tuple.GridTuple<ICell.JSON>;
+    }
+    interface JSON {
+        identity: IdentityEntry[];
+        sheetNames: string[];
+        definedNames?: DefinedNameEntry[];
+        /** One entry per CACHED sheet, not per sheet — a sheet absent here was never cached (not empty). */
+        sheetDataSet?: SheetData[];
+        /** `mc:Ignorable="x14 xxl21"` was present on the part root — preserved so a future writer round-trips it. */
+        mceIgnorable?: boolean;
+    }
+}
+//# sourceMappingURL=IExternalBook.d.ts.map

package/types/src/externalBook/IExternalBook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IExternalBook.d.ts","sourceRoot":"","sources":["../../../../src/externalBook/IExternalBook.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,WAAW,IAAI,SAAS,aAAa,CAAC,aAAa,EAAE,CAAC;IACtD;;;;;;OAMG;IACH,aAAa,IAAI,SAAS,MAAM,EAAE,CAAC;IACnC;;;;;;OAMG;IACH,eAAe,IAAI,SAAS,aAAa,CAAC,gBAAgB,EAAE,CAAC;IAC7D;;;;;;;;OAQG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CAAC,SAAS,GAAG,IAAI,CAAC;IACjE;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAC;IAE/B,MAAM,CAAC,IAAI,aAAa,CAAC,IAAI,GAAG,IAAI,CAAC;CACtC;AAED,yBAAiB,aAAa,CAAC;IAE7B;;;;;;;;OAQG;IACH,UAAiB,aAAa;QAC5B,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;KAChB;IAED,UAAiB,gBAAgB;QAC/B,IAAI,EAAE,MAAM,CAAC;QACb,kFAAkF;QAClF,QAAQ,EAAE,MAAM,CAAC;QACjB,sFAAsF;QACtF,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB;IAED,UAAiB,SAAS;QACxB,4GAA4G;QAC5G,UAAU,EAAE,MAAM,CAAC;QACnB,sGAAsG;QACtG,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB;;;;WAIG;QACH,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;KACnC;IAED,UAAiB,IAAI;QACnB,QAAQ,EAAE,aAAa,EAAE,CAAC;QAC1B,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,YAAY,CAAC,EAAE,gBAAgB,EAAE,CAAC;QAClC,oGAAoG;QACpG,YAAY,CAAC,EAAE,SAAS,EAAE,CAAC;QAC3B,6GAA6G;QAC7G,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB;CAEF"}

package/types/src/externalBook/IExternalBookCollection.d.ts

@@ -0,0 +1,29 @@
+import { ICollection } from '../type';
+import { IExternalBook } from './IExternalBook';
+/**
+ * The workbook's external books, in `[n]` order.
+ *
+ * @remarks
+ * **Positional, not an identity — see {@link IExternalBook}.** `[n]` in a formula is this
+ * collection's index at read time; nothing in the source file names a book any other way. Read-only
+ * for now: there is no `add`/`remove` here yet, matching the design doc's phase 1 scope (authoring
+ * arrives with the resolver API in a later phase).
+ */
+export interface IExternalBookCollection extends ICollection<IExternalBook> {
+    /**
+     * The book that formula text `[n]` (1-based) addresses, or `null` if `n` is beyond what was
+     * preserved on read, or its position is a DDE/OLE link (unmodeled — see {@link getItems}).
+     */
+    getByIndex(n: number): IExternalBook | null;
+    /**
+     * @returns The positional array, gaps included — `null` at index `i` means `[i+1]` is a DDE/OLE
+     * link or otherwise unmodeled, not that it is absent. `null` overall if there are no entries at
+     * all (nothing to preserve).
+     */
+    toJSON(): (IExternalBook.JSON | null)[] | null;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIExternalBookCollection: true;
+}
+//# sourceMappingURL=IExternalBookCollection.d.ts.map

package/types/src/externalBook/IExternalBookCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IExternalBookCollection.d.ts","sourceRoot":"","sources":["../../../../src/externalBook/IExternalBookCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAwB,SAAQ,WAAW,CAAC,aAAa,CAAC;IACzE;;;OAGG;IACH,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAAC;IAE5C;;;;OAIG;IACH,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,yBAAyB,EAAE,IAAI,CAAC;CAC1C"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/externalBook/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC"}