@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.11

package/types/src/sheet/WorksheetCollection.d.ts

@@ -0,0 +1,39 @@
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
+import { IWorksheetCollection } from './IWorksheetCollection';
+import { IWorksheet } from './IWorksheet';
+import { ISheet } from './ISheet';
+/**
+ * Implementation for {@link IWorksheetCollection}.
+ *
+ * @remarks
+ * A front over the workbook's own sheet state — the workbook keeps the store and the events,
+ * this class keeps the API. `onCollectionChange` is the workbook's `onSheetsChange`, forwarded
+ * with this collection as the source.
+ */
+export declare class WorksheetCollection extends AbstractCollection<IWorksheet, IWorksheetCollection.GetItemsOptions> implements IWorksheetCollection {
+    private _add;
+    private _get;
+    private _addListeners;
+    private _getSelected;
+    constructor(add: (options: IWorksheetCollection.AddOptions | string | number) => IWorksheet, get: (name?: string, visibility?: ISheet.Visibility) => IWorksheet[], addListeners: (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove, getSelected: () => IWorksheet | null);
+    /** {@inheritDoc IWorksheetCollection.getActive} */
+    getActive(): IWorksheet | null;
+    /** {@inheritDoc IWorksheetCollection.getAt} */
+    getAt(index: number): IWorksheet | null;
+    /** {@inheritDoc IWorksheetCollection.getByIndex} */
+    getByIndex(index: number): IWorksheet | null;
+    /** {@inheritDoc IWorksheetCollection.getAll} */
+    getAll(): IWorksheet[];
+    /** {@inheritDoc IWorksheetCollection.add} */
+    add(options?: IWorksheetCollection.AddOptions | string | number): IWorksheet;
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: IWorksheetCollection.GetItemsOptions): IWorksheet[];
+    /** {@inheritDoc IWorksheetCollection.getByName} */
+    getByName(name: string): IWorksheet;
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IWorksheetCollection.isIWorksheetCollection} */
+    get isIWorksheetCollection(): true;
+}
+//# sourceMappingURL=WorksheetCollection.d.ts.map

package/types/src/sheet/_Anomalies.d.ts

@@ -0,0 +1,109 @@
+import { IRange } from '@sheetxl/primitives';
+import { ICell } from '../cell';
+import { ISpatialMap, ISpatialQuery } from '../collections';
+import { ICellStyle, IStyleCollection } from '../style';
+import { IProperties } from '../type';
+import { IWorksheet } from './IWorksheet';
+import { IgnoredErrors } from './_IgnoredErrors';
+import { CellKind } from './_Kinds';
+/**
+ * The findings at a cell, interned per map: equal findings are one object, in rank order, so a
+ * region's payload identity is its content and the fragments of one finding regroup.
+ * @internal
+ */
+export type AnomalySet = readonly ICell.Anomaly[];
+type StyleMap = ISpatialQuery<IProperties.ICellRanged<ICellStyle.Properties>>;
+/** What the role layer is read from: a sheet's content and its formulas, as they are now. @internal */
+export interface RoleSource {
+    readonly sheet: IWorksheet;
+    /** The extent the checks run over; `null` for an empty sheet. */
+    readonly bounds: IRange.Coords | null;
+    /** What each cell holds (`ICellRange.Feature.Kind`). */
+    readonly kinds: ISpatialQuery<CellKind>;
+    readonly contentful: ISpatialQuery<unknown>;
+    readonly formulas: ISpatialQuery<unknown>;
+}
+/** What the checks read. Everything is the sheet as it is now; nothing here is written. @internal */
+export interface AnomalySource extends RoleSource {
+    /** Each cell's job (`ICellRange.Feature.Role`), the layer the pairing reads. */
+    readonly roles: ISpatialQuery<ICell.Role>;
+    /** The direct styles that carry font, number format and alignment. */
+    readonly contentStyles: StyleMap;
+    /** The direct fills. */
+    readonly fillStyles: StyleMap;
+    /** Where the named styles, Normal among them, are read. */
+    readonly styles: IStyleCollection;
+    readonly ignored: IgnoredErrors;
+    /** Excel draws no unlocked-formula indicator on a protected sheet. */
+    readonly isProtected: boolean;
+    /** The font colors the workbook's other sheets write their roles in ({@link roleColorsOf}). */
+    readonly workbookRoleColors: () => ReadonlySet<string>;
+}
+type Rect = IRange.Coords;
+/** @internal */
+export type Evidence = ICell.Anomaly['evidence'];
+/** One sheet's findings at their first-pass rank, before the workbook's repeats are counted. @internal */
+export interface AnomalyFindings {
+    readonly entries: readonly ISpatialMap.Entry<ICell.Anomaly>[];
+    /** For each repeat-ranked finding, its identity across sheets and the rectangles it holds here. */
+    readonly repeats: ReadonlyMap<ICell.Anomaly, {
+        readonly key: string;
+        readonly count: number;
+    }>;
+}
+/**
+ * The first pass: where the error checks fire on one sheet, each finding ranked alone.
+ *
+ * @remarks
+ * Every check reads the sheet's partitions and its formulas' references, at the altitude of a
+ * region: a formula region is one authored formula, so its references are a function of the
+ * cell's position, and the cells a check names are found by rectangle arithmetic against the
+ * partitions. No check reads a cell.
+ * @internal
+ */
+export declare function findAnomalies(source: AnomalySource): AnomalyFindings;
+/** How often each repeat-ranked finding occurs over the sheets given, by identity. @internal */
+export declare function repeatsOf(sheets: readonly AnomalyFindings[]): Map<string, number>;
+/**
+ * The second pass: one sheet's map, each repeat-ranked finding's rank divided by how often it
+ * occurs in the workbook (`repeats`), so the exception ranks above the pattern.
+ * @internal
+ */
+export declare function buildAnomalies(own: AnomalyFindings, repeats: ReadonlyMap<string, number>, ignored: IgnoredErrors): ISpatialMap<AnomalySet>;
+/** The findings so far, one rectangle list per distinct finding. @internal */
+export declare class _Findings {
+    private readonly _groups;
+    /** The rank of a check's finding before its evidence scales it. */
+    weightOf(check: ICell.ErrorCheck): number;
+    /** `rank` is a function of the check and the evidence, so one finding has one. */
+    add(check: ICell.ErrorCheck, evidence: Evidence, rect: Rect, rank?: number): void;
+    /**
+     * One entry per merged rectangle of each finding (a finding's rectangles may overlap), and the
+     * count of those rectangles for the repeat-ranked ones.
+     */
+    result(): AnomalyFindings;
+}
+/** A formula region: one authored formula over a rectangle. @internal */
+export interface FormulaRegion {
+    readonly coords: Rect;
+    /** The formula in R1C1, which is what agrees between two cells of one run. */
+    readonly r1c1: string;
+}
+/**
+ * The role layer (`ICellRange.Feature.Role`): the kind layer refined by what a formula reads and
+ * by who reads a cell. Typed cells are `label` (nothing reads them) or `input` (something does); a
+ * formula is a `link`, a `reference`, else `computed` where something reads it and `output` where
+ * nothing does. "Who reads it" is this sheet's own formulas (`referencesOf`); a reader on another
+ * sheet is not seen, so a cell only another sheet reads is a `label` or an `output` here.
+ * @internal
+ */
+export declare function buildRoles(source: RoleSource): ISpatialMap<ICell.Role>;
+/**
+ * The font colors a sheet's roles are written in: the plurality color of each role, typed cells'
+ * among them. A workbook's role colors are the union over its sheets, which is what tells the
+ * inputs' blue from a decorative red on a sheet whose own typed numbers are mostly black years.
+ * @internal
+ */
+export declare function roleColorsOf(source: AnomalySource): ReadonlySet<string>;
+export {};
+//# sourceMappingURL=_Anomalies.d.ts.map

package/types/src/sheet/_AnomalyFormulaChecks.d.ts

@@ -0,0 +1,125 @@
+import { IRange } from '@sheetxl/primitives';
+import { ICalculation } from '../calculation';
+import { SpatialMap } from '../collections';
+import { IWorksheet } from './IWorksheet';
+import { AnomalySource, FormulaRegion, RoleSource, _Findings } from './_Anomalies';
+type Node = ICalculation.FormulaNode;
+type Rect = IRange.Coords;
+type At = IRange.CellCoords;
+/**
+ * `repeatedReference`: the same cell or range counted twice in one sum — `SUM(F24:F29)+F25`,
+ * `N20-N23-N23-N26`. Two references overlap when they share a cell; they count twice when they
+ * carry the same sign, so `SUM(B2:B9)-B5` (taking one out) does not fire.
+ */
+export declare function checkRepeatedReference(source: AnomalySource, regions: readonly FormulaRegion[], findings: _Findings): void;
+/**
+ * `degenerateCall`: an aggregate that aggregates nothing — `AVERAGE(J96)` over one cell, or
+ * `SUM(360,365)` over typed numbers.
+ */
+export declare function checkDegenerateCall(source: AnomalySource, regions: readonly FormulaRegion[], findings: _Findings): void;
+/**
+ * `sumIncludesSubtotal`: a sum that holds a cell that is itself a sum of the sum's own cells
+ * (`SUM(F17:F21)` where F21 sums F17:F20; `=F21+F18` likewise), or a summed range holding a
+ * percent-formatted ratio (`=F19/F18`, a margin row inside a total). The cell may be on the sheet
+ * the sum reads. A ratio of a typed divisor (`=F3/12`) is an allocation and does not fire, nor
+ * does a ratio the sheet does not show as a percent (a per-unit line item).
+ */
+export declare function checkSumIncludesSubtotal(source: AnomalySource, regions: readonly FormulaRegion[], findings: _Findings): void;
+/**
+ * `misalignedReference`: a formula in the row that closes (or opens) its block sums the block and
+ * also adds a cell outside it — `=SUM(K51:K53)+J46`. A block is the contentful lines in the
+ * region's own columns (rows) between blank lines that span them; a row-wise total reads the
+ * same with the axes swapped. A term is aligned when it lands inside the block in the cell's own
+ * column. Only a sum with an aligned term fires, so a grand total of other blocks' totals does not;
+ * and only a term added the way an aligned one is, so `=D20-D18` (a deduction) does not.
+ */
+export declare function checkMisalignedReference(source: AnomalySource, regions: readonly FormulaRegion[], findings: _Findings): void;
+/**
+ * `approximateMatch`: a lookup that matches the nearest key rather than the key — `MATCH` with a
+ * type of `1` or `-1` or none, `VLOOKUP` / `HLOOKUP` without `FALSE`, `XMATCH` / `XLOOKUP` with a
+ * match mode of `1` or `-1`. Fires even on a sorted selector: the type is the fact. A type read
+ * from a cell is not known here and does not fire.
+ */
+export declare function checkApproximateMatch(source: AnomalySource, regions: readonly FormulaRegion[], findings: _Findings): void;
+/**
+ * `lookupShape`: a lookup whose two arrays do not line up — `INDEX(M30:M32,MATCH(x,L29:L31,0))`, or
+ * `XLOOKUP(x,L29:L31,M30:M32)`. The position found in one is read from the other, so a different
+ * start or end along the vector's axis reads the wrong line.
+ */
+export declare function checkLookupShape(source: AnomalySource, regions: readonly FormulaRegion[], findings: _Findings): void;
+/**
+ * `externalReference`: a formula that reads outside this workbook or nowhere — `[1]Sheet!A1` to
+ * another workbook (`kind: 'workbook'`), a `#REF!` left by a deletion (`'deleted'`), a function
+ * a converter wrapped as unknown (`_XLUDF.`, `'udf'`).
+ */
+export declare function checkExternalReference(source: AnomalySource, regions: readonly FormulaRegion[], findings: _Findings): void;
+/** One term of a sum: a reference, added (`1`) or taken away (`-1`). */
+export interface Leaf {
+    readonly node: Node;
+    readonly sign: 1 | -1;
+}
+/**
+ * Every sum in a tree, as the references it adds and takes away. A sum is a `SUM` or a run of
+ * `+` and `-`, with parentheses read through; anything else (`*`, `IF`, `AVERAGE`) ends it, and
+ * its arguments start sums of their own. A reference that is not summed (`AVERAGE(B2:B9)`,
+ * `INDEX(B2:B9,3)`) is in no sum.
+ * @internal
+ */
+export declare function additiveChains(root: Node): Leaf[][];
+/** Every node of a tree, the root first. @internal */
+export declare function nodesOf(root: Node): Generator<Node>;
+/** @internal */
+export declare function treeOf(sheet: IWorksheet, region: FormulaRegion): Node | null;
+/** A sheet's formula regions, indexed by where they lie. @internal */
+export interface SheetFormulas {
+    readonly sheet: IWorksheet;
+    readonly regions: readonly FormulaRegion[];
+    readonly index: SpatialMap<FormulaRegion>;
+}
+/**
+ * The sheets a build's references land on, by lower-case name: this one, and each other sheet of
+ * the workbook read once, as its formula partition.
+ * @internal
+ */
+export declare class _Sheets {
+    private readonly _source;
+    readonly own: string;
+    private readonly _formulas;
+    private readonly _sheets;
+    constructor(_source: AnomalySource, regions: readonly FormulaRegion[]);
+    /** The worksheet a reference's sheet name names, or `null` when the workbook has none. */
+    sheetOf(name: string): IWorksheet | null;
+    formulasOf(name: string): SheetFormulas | null;
+}
+/** The sheet reader of one build, shared by its checks. @internal */
+export declare function sheetsOf(source: AnomalySource, regions: readonly FormulaRegion[]): _Sheets;
+/** `SUM`, with the file format's `_xlfn.` / `_xlws.` spelling taken off. @internal */
+export declare const functionName: (node: Node) => string;
+/** @internal */
+export declare const firstCellOf: (region: FormulaRegion) => At;
+/**
+ * Where a fact found at a region's first cell holds: the whole region when it holds at its last
+ * cell as well, otherwise the first cell alone; `null` when it does not hold at the first cell.
+ * A filled formula moves every relative reference by the same step, so the two ends decide it.
+ * @internal
+ */
+export declare function extentOf(region: FormulaRegion, holds: (at: At) => boolean): Rect | null;
+/** A reference in R1C1, read from `at`, with its sheet when it names one. @internal */
+export declare const imageOf: (node: Node, at: At) => string;
+/** @internal */
+export declare const isReference: (node: Node) => boolean;
+/** Strips parentheses. @internal */
+export declare function unwrap(node: Node): Node;
+/** The number a literal argument is (`-1`, `(1)`, `TRUE` as `1`), or `undefined`. @internal */
+export declare function numberOf(node: Node): number | undefined;
+/** The sheet name references are compared under. @internal */
+export declare const ownSheetName: (source: RoleSource) => string;
+/** A reference read from a cell: its sheet (lower case) and its cells. @internal */
+export interface Resolved {
+    readonly sheet: string;
+    readonly rect: Rect;
+}
+/** Where a cell or range reference lands when its formula sits at `at`; `null` for anything else. @internal */
+export declare function resolve(node: Node, at: At, own: string): Resolved | null;
+export {};
+//# sourceMappingURL=_AnomalyFormulaChecks.d.ts.map

package/types/src/sheet/_AnomalyLabelChecks.d.ts

@@ -0,0 +1,21 @@
+import { AnomalySource, FormulaRegion, _Findings } from './_Anomalies';
+/**
+ * `linkLabelMismatch`: a link to another sheet whose target row is labeled other than the row it
+ * sits in — the row labeled Interest reading the row labeled Tax. Labels compare after case,
+ * punctuation and spacing are dropped; a row with no label on either side says nothing.
+ *
+ * Rows only: column headers differ between a model's sheets as a matter of layout (`2026P` against
+ * `Millions`), and on the v2 goldens the column pair found no planted link the row pair missed.
+ */
+export declare function checkLinkLabelMismatch(source: AnomalySource, regions: readonly FormulaRegion[], findings: _Findings): void;
+/**
+ * `keyLabelMismatch`: a lookup keyed by a typed string that is neither the label of the row nor
+ * of the column the formula sits in — `MATCH("Tax",…)` in the row labeled Interest.
+ */
+export declare function checkKeyLabelMismatch(source: AnomalySource, regions: readonly FormulaRegion[], findings: _Findings): void;
+/**
+ * `signVsSiblings`: a link into a row that the sheet's other links into that row read with the
+ * other sign — `=-'Debt'!C20` where two other links read `='Debt'!D20`, `='Debt'!E20`.
+ */
+export declare function checkSignVsSiblings(source: AnomalySource, regions: readonly FormulaRegion[], findings: _Findings): void;
+//# sourceMappingURL=_AnomalyLabelChecks.d.ts.map

package/types/src/sheet/_CellBuffer.d.ts

@@ -0,0 +1,224 @@
+import { Scalar, IRange } from '@sheetxl/primitives';
+import { CoordUtils } from '@sheetxl/utils';
+import { ITransaction } from '../transaction';
+import { Tuple, ISpatialMap } from '../collections';
+import { ICellRange } from '../cellRange';
+import { ICell } from '../cell';
+import { ICellStyle } from '../style';
+import { InternalTupleUpdate } from './_SheetStateTypes';
+import { SheetMutationContext } from './Worksheet';
+import { ScanStyleUpdate } from './_SheetMutations';
+/**
+ * What {@link CellBuffer} needs from its sheet.
+ * @internal
+ */
+export interface CellBufferContext {
+    readonly isDataColumn: boolean;
+    readonly transactions: ITransaction.IStore;
+    /**
+     * The records a flush writes: the sheet's, and the calculation's it marks dirty. A read of one
+     * from the store makes the held writes first.
+     */
+    readonly writes: readonly string[];
+    isClosed(): boolean;
+    getEntireCoords(): IRange.Coords | null;
+    /**
+     * The sheet's spills as `transaction` sees them - a read that does not flush: nothing a held
+     * write makes changes them.
+     */
+    getSpills(transaction: ITransaction): ISpatialMap;
+    /**
+     * Whether a style update written to one cell changes that cell alone, as `transaction` sees the
+     * sheet; see {@link CellBuffer.holdStyle}.
+     */
+    isLocalStyle(transaction: ITransaction, rowIndex: number, colIndex: number, update: ICellStyle.Update): boolean;
+    /** What the sheet's cell writes are made through; the held ones are scanned and written with it. */
+    getMutations(): SheetMutationContext;
+    /**
+     * Whether a write is to be made as it comes: a batch it would be held in is told of each of its
+     * steps, and a held write would be told late.
+     */
+    isMadeAsItComes(): boolean;
+}
+/**
+ * Single-cell writes made inside an open transaction, held and made as ONE write when something
+ * needs them made.
+ *
+ * @remarks
+ * A loop that writes a cell per call makes one full write per cell, and leaves one formula block
+ * per cell. Held, the loop is one write, and the formulas in it conflate into runs as they do in
+ * one `setValues`.
+ *
+ * A held run IS that one write, left open: each cell goes through the write's own scan as it
+ * comes ({@link scanCell}), and making the run is the scan's finish ({@link finishTupleScan}). So
+ * a cell is resolved once, by the rules of any other write, and what the scan refuses it refuses
+ * at the call.
+ *
+ * Holding has no outward behavior. Inside a transaction the events and the undo step are the
+ * transaction's anyway, and everything that could see the difference makes the held writes first
+ * (`ITransaction.Hooks`): a read of a record they change - the sheet's, or the calculation's they
+ * mark dirty - a transaction beginning inside the one that holds them, and its commit. Only what
+ * cannot fail once scanned is held: a write that is part of an array, or that carries a merge, a
+ * hyperlink or comments, is made as it comes, after the held ones. A LOCKED sheet is held like any
+ * other: the scan rules on every cell against its exemptions and throws at the call, and the run
+ * it makes stands its commit-time catch-all down exactly as one `setValues` over those cells does.
+ *
+ * A scan asks for its cells in one order. The sheet stores along its major axis and a loop usually
+ * writes across it (row by row into a column-major sheet), so the order is decided by the second
+ * cell written, and the scan and the {@link Tuple.IBuilder} the values are placed in follow it. A
+ * write that does not continue that order - a step back, a second value to the same cell, a change
+ * between `updateCells` and `setValue` - flushes what is held and starts a new run.
+ *
+ * A style set on a cell on its own ({@link holdStyle}) is held in the same run: styling the cell
+ * just written, or styling it again, continues it. The styles of a cell styled more than once are
+ * written in the order they were set.
+ *
+ * The first write of a run is scanned on its own, within its one cell. The second begins the scan
+ * the run keeps - over the whole sheet, since where the run ends is not known - and the first
+ * cell goes through it again. A loop that makes every write as it comes never pays for the sheet.
+ *
+ * A read of a held cell answers from what the scan has: the value from the builder it was placed
+ * in, and a clear, a formula or a style from the scan's collectors. Nothing is kept by cell.
+ * @internal
+ */
+export declare class CellBuffer {
+    private readonly _ctx;
+    private _transaction;
+    private _count;
+    private _isCell;
+    private _scan;
+    private _isBeginning;
+    private _isOriented;
+    private _isTransposed;
+    private _builder;
+    private _changes;
+    private _firstWrites;
+    private _firstValue;
+    private _lastMajor;
+    private _lastMinor;
+    private _isValueAtLast;
+    private _hasValues;
+    private _majorMin;
+    private _majorMax;
+    private _minorMin;
+    private _minorMax;
+    private _generation;
+    constructor(ctx: CellBufferContext);
+    /** Whether any write is held. */
+    isHolding(): boolean;
+    /**
+     * Holds a write if it can be held.
+     *
+     * @returns `true` if the write is held; `false` if it is to be made as it comes.
+     */
+    hold(boundedTuples: Tuple.Region<ICell.Update> | null, options: ICellRange.UpdateCellsOptions | undefined, coordValidator: CoordUtils.CoordValidator | null | undefined, internalOptions: InternalTupleUpdate | null): boolean;
+    /**
+     * Holds a style set on one cell on its own, if it can be held.
+     *
+     * @param isLocal Whether the update changes only its cell - asked only once the rest allows the
+     * hold. A border changes the neighbor's edge and a continuous alignment is drawn across the
+     * neighbors, and a read of a neighbor does not see a held write.
+     * @returns `true` if the style is held; `false` if it is to be written as it comes.
+     */
+    holdStyle(rowIndex: number, colIndex: number, update: ICellStyle.Update, options: ICellStyle.UpdateOptions | undefined, isLocal: () => boolean): boolean;
+    private _holdIn;
+    /**
+     * The transaction the held writes are made into. While any is held it is the innermost one, and
+     * a read through it sees the sheet without them and does not make them.
+     */
+    getTransaction(): ITransaction | null;
+    /**
+     * What a read of a cell's value returns once the held writes are made, answered without making
+     * them.
+     *
+     * @remarks
+     * The answer is the value the scan stores: a number as the write normalizes it, text as the
+     * write coerced and cut it, `null` for a cleared cell - and for a formula, which has no value
+     * until it is calculated.
+     *
+     * @returns The value; {@link CellBuffer.NotHeld} if no held write is to the cell's value - none
+     * is to the cell, or it writes a style alone, or it is a merged cell other than its first - so
+     * the sheet as it is answers.
+     */
+    read(rowIndex: number, colIndex: number): Scalar | typeof CellBuffer.NotHeld;
+    /** {@link read}, at `major`/`minor` in the scan's orientation. */
+    private _valueAt;
+    /**
+     * What a held write leaves in its cell, answered without making the held writes.
+     *
+     * @returns The value, the formula text (`null` for none) and the style update; {@link
+     * CellBuffer.NotHeld} if no held write is to the cell; `undefined` if the held write has to be
+     * made to know - it clears the cell's style, link and comments.
+     */
+    readCell(rowIndex: number, colIndex: number): CellBuffer.HeldCell | typeof CellBuffer.NotHeld | undefined;
+    /**
+     * The style update a held write carries to its cell - an implied one included, such as the
+     * number format of text that reads as a date - or the styles set on it on their own, in order.
+     *
+     * @returns The update; `undefined` if the held writes leave the cell's style as it is.
+     */
+    readStyleUpdate(rowIndex: number, colIndex: number): ScanStyleUpdate | undefined;
+    /**
+     * Whether the run `generation` counted is still held: neither made nor dropped.
+     *
+     * @see {@link getGeneration}
+     */
+    isHeldGeneration(generation: number): boolean;
+    /** Identifies the run being held; see {@link isHeldGeneration}. */
+    getGeneration(): number;
+    /** Makes the held writes, as one. */
+    flush(): void;
+    /**
+     * Makes the held writes and closes the transaction they were held in, so what is written next is
+     * not nested in it. A transaction still open inside that one keeps it open.
+     */
+    release(): void;
+    /** Drops the held writes: the transaction they were made in rolled back, or the sheet closed. */
+    discard(): void;
+    private _toRange;
+    /**
+     * Whether a write at `major`/`minor`, in the sheet's orientation, continues the run held.
+     *
+     * @param isCell The kind of value write; `null` for a style set on its own, which may also be to
+     * the cell last written.
+     */
+    private _continues;
+    /** Begins a scan for the run. */
+    private _begin;
+    /** Scans one cell; `major`/`minor` in the scan's orientation. */
+    private _scanCell;
+    private _beginRun;
+    private _orientTo;
+    /**
+     * Scans and holds one write that continues the run, at `major`/`minor` in the sheet's
+     * orientation.
+     *
+     * @returns `false` if the scan refused it; it is not held then, and the run is as it was.
+     */
+    private _push;
+    /** Holds a style set on its own, continuing the run, at `major`/`minor` in the sheet's orientation. */
+    private _pushStyle;
+    /**
+     * The second cell written decides the run's order: the run's scan begins, over the whole sheet,
+     * and the writes to the first cell go through it again, in order.
+     */
+    private _orient;
+    private _clear;
+}
+/** @internal */
+export declare namespace CellBuffer {
+    /** {@link CellBuffer.read}: no held write is to the cell. */
+    const NotHeld: unique symbol;
+    /** {@link CellBuffer.readCell}: what the held writes leave in their cell. */
+    interface HeldCell {
+        /** The value written; `null` too when {@link isValueHeld} is `false`. */
+        value: Scalar;
+        /** `false` if no held write is to the cell's value: the sheet's stands. */
+        isValueHeld: boolean;
+        /** The run's formula imaged at the cell, without a leading `=`; `null` for none. */
+        formula: string | null;
+        /** The style updates held for the cell, an implied one included; `undefined` for none. */
+        style: ScanStyleUpdate | undefined;
+    }
+}
+//# sourceMappingURL=_CellBuffer.d.ts.map

package/types/src/sheet/_CopyUtils.d.ts

@@ -1,8 +1,8 @@
 import { IRange } from '@sheetxl/primitives';
 import { IMovable } from '../movable';
 import { ICellRange, ICellHeaderRange } from '../cellRange';
-import { ISheet } from './ISheet';
-import { Sheet } from './Sheet';
+import { IWorksheet } from './IWorksheet';
+import { Worksheet } from './Worksheet';
 /**
  * The pasted images of `areas` (absolute ranges within the marked source `coordFrom`):
  * each area's offset within the source, tiled across the fitted destination `rangeTo` with
@@ -15,19 +15,26 @@ import { Sheet } from './Sheet';
  * is already LCM-expanded or clipped, so tiling here is a pure function of the two ranges.
  */
 export declare function tileMarkedAreas(areas: readonly IRange.Coords[], coordFrom: Readonly<IRange.Coords>, rangeTo: Readonly<IRange.Coords>, transpose?: boolean): IRange.Coords[];
+/**
+ * Runs every part's `prepare`, and waits only when one of them has something to wait for: with
+ * nothing to prepare, the paste stays in its caller's synchronous extent.
+ */
+export declare function prepareParts<D, O>(parts: readonly {
+    prepare?(destination: D, options?: O): Promise<void> | void;
+}[], destination: D, options?: O): Promise<void> | void;
 /**
  * Converts a header snapshot to sheet.
  */
 export declare function headerToSheetSnapshot(rangeMark: ICellHeaderRange, coordMark: IRange.Coords, optionsMark: ICellHeaderRange.CopyOptions): Partial<ICellRange.ISnapshot>;
 /**
- * Wraps a copySheetTo function into a ISheet.ISnapshot.
+ * Wraps a copySheetTo function into a IWorksheet.ISnapshot.
  * * This will error if snapshot is a cut and called a second.
  * @internal
  */
-export declare function callbackToSheetSnapshot(sheetFrom: ISheet, sheetMark: ISheet, coordsFrom: readonly IRange.Coords[], description: string, optionsMark: ICellRange.CopyOptions, copySheetTo: (sheetRange: ICellRange, options?: ICellRange.CopyOptions) => Promise<IRange.Coords> | IRange.Coords): ICellRange.ISnapshot;
+export declare function callbackToSheetSnapshot(sheetFrom: IWorksheet, sheetMark: IWorksheet, coordsFrom: readonly IRange.Coords[], description: string, optionsMark: ICellRange.CopyOptions, copySheetTo: (sheetRange: ICellRange, options?: ICellRange.CopyOptions) => IRange.Coords): ICellRange.ISnapshot;
 /**
  * Converts an array of Snapshots into a single snapshot.
  */
-export declare function arrToSheetSnapshot(snapshots: Partial<ICellRange.ISnapshot>[], sheet: ISheet, sheetMark: ISheet, coordsMark: IRange.Coords, optionsMark: ICellRange.CopyOptions, descriptionMark: string, snapshotNative?: ICellRange.ISnapshot | null): ICellRange.ISnapshot;
-export declare function movablesToSheetSnapshot(sheetMark: Sheet, coordsMark: readonly IRange.Coords[], movablesSelectionMark: readonly IMovable[], markOptions: ICellRange.CopyOptions): ICellRange.ISnapshot<ISheet> | null;
+export declare function arrToSheetSnapshot(snapshots: Partial<ICellRange.ISnapshot>[], sheet: IWorksheet, sheetMark: IWorksheet, coordsMark: IRange.Coords, optionsMark: ICellRange.CopyOptions, descriptionMark: string, snapshotNative?: ICellRange.ISnapshot | null): ICellRange.ISnapshot;
+export declare function movablesToSheetSnapshot(sheetMark: Worksheet, coordsMark: readonly IRange.Coords[], movablesSelectionMark: readonly IMovable[], markOptions: ICellRange.CopyOptions): ICellRange.ISnapshot<IWorksheet> | null;
 //# sourceMappingURL=_CopyUtils.d.ts.map

package/types/src/sheet/_HeldFormula.d.ts

@@ -0,0 +1,69 @@
+import { IRange } from '@sheetxl/primitives';
+import { ITransaction } from '../transaction';
+import { ICellRanges, ICellRange } from '../cellRange';
+import { ICalculation } from '../calculation/ICalculation';
+import { FormulaHost } from '../calculation/grid';
+import { Formula, IFormulaBlockView } from '../calculation/formula';
+/**
+ * A formula a content names, as the engine holds it: a live view over the host's body.
+ *
+ * @remarks
+ * Every read goes to the host's grid in the snapshot the store is at, as a defined name's does
+ * (`NamedFormula`), so an insert, a sheet rename, a cut and an undo are all answered on the next
+ * read, with no delivery in between. The body is authored at the content's anchor
+ * ({@link getAnchor}), which is where a relative endpoint is read from.
+ *
+ * The host's grid can be gone — the content was deleted, or the commit that registered the
+ * watch was undone — and the formula then answers the last text the engine delivered for it,
+ * with no references: what a restore re-holds from.
+ *
+ * @internal
+ */
+export declare class HeldFormula extends Formula {
+    private readonly _host;
+    private _last;
+    /**
+     * @param host The host holding the body.
+     * @param origin Where the body is authored: the content's anchor.
+     * @param text The body's text as delivered, kept for when the grid is gone.
+     */
+    constructor(host: FormulaHost, origin: IRange.CellCoords, text: string, options: Formula.ConstructorOptions);
+    /** The body as the model's grid holds it now: the engine's text once answered, as written until then. */
+    protected get _block(): IFormulaBlockView;
+    private _view;
+    /** The id of the grid the body lives in, which a re-hold attaches to. @internal */
+    _getHostId(): string;
+    /** The text as the engine last delivered it, so the formula still answers once the grid is gone. @internal */
+    _setLast(text: string): void;
+    /** {@inheritDoc ICalculation.IFormula.isCompiled} */
+    isCompiled(): boolean;
+    /** {@inheritDoc ICalculation.IFormula.getCalculationStatus} */
+    getCalculationStatus(): ICalculation.ResultStatus;
+    /** {@inheritDoc ICalculation.IFormula.getExpression} */
+    getExpression(options?: ICalculation.FormulaTextOptions): string;
+    /** {@inheritDoc ICalculation.IFormula.getTokens} */
+    getTokens(evalIndex?: number): readonly ICalculation.FormulaToken[];
+    /** {@inheritDoc ICalculation.IFormula.isValid} */
+    isValid(): boolean;
+    /** {@inheritDoc ICalculation.IFormula.isReferenceOnly} */
+    isReferenceOnly(): boolean;
+    /** {@inheritDoc ICalculation.IFormula.getReferences} */
+    getReferences(): ICellRanges | null;
+    /** {@inheritDoc ICalculation.IFormula.hasRefError} */
+    hasRefError(): boolean;
+    /** A held formula is rewritten by the engine, never through this handle. */
+    setReferenceAt(_index: number, _reference: ICellRange.Address, _options?: string | ITransaction.OperationOptions): Promise<this>;
+    /** A held formula is rewritten by the engine, never through this handle. */
+    setReferenceModeAt(_index: number, _side?: ICalculation.ReferenceSide, _mode?: number, _options?: string | ITransaction.OperationOptions): Promise<this>;
+}
+/**
+ * The sheet a reference names and the rest of it, or `null` for an unqualified one. The engine
+ * names every sheet in a held formula's text; a content that writes a reference where the sheet
+ * is implied, or kept apart, splits it here.
+ * @internal
+ */
+export declare function splitSheetQualifier(text: string): {
+    sheet: string;
+    reference: string;
+} | null;
+//# sourceMappingURL=_HeldFormula.d.ts.map