@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.10

package/types/src/calculation/grid/_CalcRequest.d.ts

@@ -0,0 +1,289 @@
+import { Scalar, IRange } from '@sheetxl/primitives';
+import { RunCoords } from '@sheetxl/utils';
+import { ISpatialMap, Tuple } from '../../collections';
+import { FormulaRecord, FormulaImager } from '../formula';
+import { ICalculation } from '../ICalculation';
+import { NamedReference } from '../Types';
+import { ICalcGrid } from './ICalcGrid';
+/**
+ * A call on a grid, as the service's channel holds it while the engine is `Starting`
+ * (DESIGN-CALC-SERVICE §4, §7.2): the verb and its arguments, applied in send order once the
+ * engine is up. The snapshot it was made at rides in its options (`commitId`, `cloneKey`).
+ *
+ * @remarks
+ * Not part of {@link ICalcGrid}: a caller sees the verbs and their promises. This is what the
+ * in-process channel holds in place of a worker port's queue, and what the clone boundary audits
+ * (plan step 6): a held call carries what the verb's arguments carry, which is what a proxy
+ * would post.
+ *
+ * @internal Deliberately not exported from the barrel.
+ */
+export type CalcRequest = 
+/**
+ * Make the engine's grid for a model grid, from what the model says it is. The grid's first
+ * request; an `Off` engine holds no grids, and a start sends one for every model grid.
+ */
+{
+    type: 'create';
+    spec: CalcGridSpec;
+}
+/** The grid's size changed: a sheet's, resized. */
+ | {
+    type: 'resize';
+    entireCoords: IRange.Coords;
+    options?: ICalcGrid.RequestOptions;
+}
+/**
+ * The rows or columns the grid's owner hides changed: every run as it is now, ascending and
+ * disjoint, empty for none. What the functions that skip hidden cells read (`SUBTOTAL` 101-111,
+ * `AGGREGATE`'s ignore-hidden options); the formulas that call them are recalculated.
+ */
+ | {
+    type: 'hidden';
+    axis: IRange.Axis;
+    runs: readonly RunCoords[];
+    options?: ICalcGrid.RequestOptions;
+}
+/**
+ * Whether the grid's owner is filtered changed: some AutoFilter or table on it holds a
+ * condition, or none does any more. What `SUBTOTAL` 1-11 read to decide whether hidden rows
+ * count; the formulas that call the total functions are recalculated.
+ */
+ | {
+    type: 'filtered';
+    filtered: boolean;
+    options?: ICalcGrid.RequestOptions;
+} | {
+    type: 'seed';
+    json: ICalcGrid.JSON;
+    options?: ICalcGrid.SeedOptions;
+} | {
+    type: 'setInputs';
+    values: Tuple.Region<Scalar> | null;
+    formulas: readonly ISpatialMap.Entry<string>[] | null;
+    deleteRange?: IRange.Coords;
+    options?: ICalcGrid.SetInputsOptions;
+} | {
+    type: 'shift';
+    options: ICalcGrid.ShiftOptions;
+} | {
+    type: 'autoFill';
+    template: IRange.Coords;
+    destination: IRange.Coords;
+    commitId?: string;
+}
+/** Capture this grid as it is at this point of the channel, for a copy or a move to read ({@link ICalcGrid.getSnapshot}). */
+ | {
+    type: 'snapshot';
+    snapshotId: string;
+}
+/**
+ * A copy or a move from a capture taken on `sourceGridId`. The three option fields the engine
+ * reads ride the record by name rather than a caller's options object: `ICellRange.CopyOptions`
+ * carries model objects (an `ICellRange` for the undo selection) and callbacks that are the
+ * sheet's business and cannot cross.
+ */
+ | {
+    type: 'copyTo';
+    sourceGridId: string;
+    snapshotId: string;
+    coords: IRange.Coords;
+    destination: IRange.Coords;
+    isCut?: boolean;
+    fitDestination?: boolean;
+    transpose?: boolean;
+    commitId?: string;
+} | {
+    type: 'delete';
+    options?: ICalcGrid.RequestOptions;
+}
+/** Ask for a pass: the engine's reactive pass, seeded from this grid (`full` for every formula). */
+ | {
+    type: 'calculate';
+    full?: boolean;
+}
+/** Cells to recalculate on the next pass. */
+ | {
+    type: 'markDirty';
+    coords: readonly IRange.Coords[];
+}
+/**
+ * The model restored to `options.commitId`: the engine restores its own history there and re-vends
+ * what changed. Only a `Running` engine acts on it - see `Calculation._sendRequestNow`.
+ */
+ | {
+    type: 'revert';
+    options: ICalcGrid.RevertOptions;
+}
+/** The grid's owner released it: the engine takes it out of the graph. Not undoable (`delete` is). */
+ | {
+    type: 'close';
+}
+/**
+ * Point the reference at `index` in the formula at the cell somewhere else, and write the formula
+ * that makes. `'#REF!'` for a reference to nothing. Refused - the response rejects - where there
+ * is no formula.
+ */
+ | {
+    type: 'setReference';
+    row: number;
+    column: number;
+    index: number;
+    precedent: IRange.FixableCoords | IRange.FixableCellCoords | NamedReference | '#REF!';
+}
+/** Cycle the reference at `index` through its `$` styles, as `ICalcGrid.setReferenceModeAt`. */
+ | {
+    type: 'setReferenceMode';
+    row: number;
+    column: number;
+    index: number;
+    side: ICalculation.ReferenceSide;
+    mode?: number;
+}
+/** The grid's content as the engine holds it, answered in the response (`ICalcGrid.toJSON`). A question: it writes nothing. */
+ | {
+    type: 'toJSON';
+    options?: ICalcGrid.ToJSONOptions;
+}
+/**
+ * The value of the formula at a cell, answered in the response (`ICalcGrid.evaluateAt`). A
+ * question. `coerce: 'scalar'` answers one scalar, as a defined name's `evaluate()` does.
+ */
+ | {
+    type: 'evaluate';
+    row: number;
+    column: number;
+    evalIndex?: number;
+    coerce?: 'scalar';
+}
+/**
+ * The graph around cells of this grid, answered in the response (`ICalcGrid.GraphNeighbors`,
+ * cells in calc currency). A question. `asName` walks the defined name this grid holds the body
+ * of instead: its own precedents or dependents, cells and names.
+ */
+ | {
+    type: 'graph';
+    kind: 'precedents' | 'dependents';
+    direct: boolean;
+    coords?: IRange.Coords;
+    asName?: boolean;
+}
+/** Whether the formula at a cell is volatile, answered in the response. A question. */
+ | {
+    type: 'isVolatile';
+    row: number;
+    column: number;
+}
+/** A body written as authored, which the engine anchors (`ICalcGrid.BodyOptions`). */
+ | {
+    type: 'setBody';
+    body: ICalcGrid.BodyOptions;
+}
+/**
+ * The sheet list as its owner holds it when the message is sent - every sheet's grid id and
+ * name, in tab order - for the engine's replica (DESIGN-CALC-SERVICE §8). A message of the
+ * service, not of a grid: the channel holds it in order with the grids' requests, which is what
+ * lets a seed sent before a rename compile against the names it was sent under. The owner tells
+ * a sheet before any grid that names it seeds (`Calculation._setSheets`).
+ */
+ | {
+    type: 'sheets';
+    sheets: readonly (readonly [id: string, name: string | null])[];
+    options?: ICalcGrid.RequestOptions;
+}
+/**
+ * Tables changed at the moment the message is sent - each by id, with its name and columns as
+ * they are now, or `null` for one removed - for the engine's replica, in order with the grids'
+ * requests as `sheets` is.
+ */
+ | {
+    type: 'tables';
+    changes: readonly (readonly [id: string, table: TableSymbols | null])[];
+    options?: ICalcGrid.RequestOptions;
+}
+/** Defined names changed at the moment the message is sent, as `tables` carries tables. */
+ | {
+    type: 'names';
+    changes: readonly (readonly [id: string, name: NameSymbols | null])[];
+    options?: ICalcGrid.RequestOptions;
+}
+/**
+ * A nested savepoint of the model rolled back inside an operation that goes on: what the requests
+ * made under it did goes with it. After them in the channel, so it undoes exactly those.
+ */
+ | {
+    type: 'rollback';
+    savepointId: string;
+}
+/**
+ * Owe a pass seeded from the grid, run once the current flush is over (`FormulaHost.requestPass`).
+ * The service's bookkeeping, not the grid's: an `Off` engine records it for the pass its start
+ * runs.
+ */
+ | {
+    type: 'requestPass';
+};
+/**
+ * What a grid is, as the model says so to the engine: plain data, the whole of what
+ * {@link CalcRequest} `create` carries.
+ */
+export interface CalcGridSpec {
+    /** The grid's id: a sheet's stable id, or a host's. */
+    id: string;
+    /** See `CalcGridBackend.ConstructorOptions.shadowOf`. */
+    shadowOf?: string;
+    /** See `CalcGridBackend.ConstructorOptions.unanchored`. */
+    unanchored?: boolean;
+    /** See `CalcGridBackend.ConstructorOptions.arrayFirstCell`. */
+    arrayFirstCell?: boolean;
+    /** The grid's size, fixed: a name's. A sheet's is its seed's. */
+    entireCoords?: IRange.Coords;
+    /** The grid whose size this one has, whatever it is then: a body on a sheet. */
+    sizeOf?: string;
+}
+/** A table as the engine's replica holds it: its name, and its columns' ids and names in order. */
+export type TableSymbols = readonly [name: string, columns: readonly (readonly [id: string, name: string])[]];
+/** A defined name as the engine's replica holds it: its name, and the id of the sheet it is scoped to. */
+export type NameSymbols = readonly [name: string, scopeId: string | null];
+/**
+ * What crosses back (DESIGN-CALC-SERVICE §8): {@link ICalcGrid.Results} with the formula half as
+ * records - data, since only data crosses. The facade images each record into the
+ * {@link IFormulaBlockView} the model reads ({@link imageResponse}) before the results reach it.
+ *
+ * @internal Deliberately not exported from the barrel.
+ */
+export type CalcResponse = Omit<ICalcGrid.Results, 'formulaInserts'> & {
+    formulaInserts?: ISpatialMap.Entry<FormulaRecord>[];
+    /**
+     * What a question answers (`toJSON`, `evaluate`). An evaluation's value crosses as it is - a run
+     * instance in an array, a `FormulaError` - until the lists have a way across (the clone audit
+     * lists it).
+     */
+    answer?: unknown;
+};
+/** The answer a question's response carries (see {@link CalcResponse.answer}). */
+export declare const answerOf: <T>(results: ICalcGrid.Results) => T | undefined;
+/**
+ * The facade's side of the formula half: every record in a response becomes a view over the
+ * model's symbols. What the clone boundary audits is the response; what the model holds is this.
+ */
+export declare const imageResponse: (response: CalcResponse, imager: FormulaImager) => ICalcGrid.Results;
+/** The grid id a message of the service itself is sent under: no grid. */
+export declare const ServiceRequestGridId = "";
+/** A request a grid applies: every kind but the service's own. */
+export type GridRequest = Exclude<CalcRequest, {
+    type: 'sheets';
+} | {
+    type: 'tables';
+} | {
+    type: 'names';
+} | {
+    type: 'rollback';
+} | {
+    type: 'create';
+} | {
+    type: 'requestPass';
+}>;
+/** The model snapshot a request was made at, from wherever its kind carries it. */
+export declare const requestCommitId: (request: CalcRequest) => string | undefined;
+//# sourceMappingURL=_CalcRequest.d.ts.map

package/types/src/calculation/grid/index.d.ts

@@ -1,3 +1,7 @@
 export * from './ICalcGrid';
+export * from './CalcGridProxy';
+export * from './CalcGridBackend';
 export * from './CalcGrid';
+export * from './FormulaEntry';
+export * from './FormulaHost';
 //# sourceMappingURL=index.d.ts.map

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

@@ -2,4 +2,6 @@ export * from './ICalculation';
 export * from './INamedFormulasCollection';
 export * from './builtInNames';
 export * from './FormulaLiterals';
+export * from './FormulaText';
+export * from './functions/FunctionDeclarations';
 //# sourceMappingURL=index.d.ts.map

package/types/src/calculation/spatial/ContentfulSpatialValue.d.ts

@@ -18,8 +18,12 @@ export declare class ContentfulSpatialValue {
     getState(): IRange.Coords;
 }
 /**
- * Wraps each value in a ContentfulSpatialValue
+ * Wraps each run of `gridTuples` in a {@link ContentfulSpatialValue}: the contentful index of a
+ * set of written values.
+ *
+ * @param scope The grid the coords belong to, for an index the engine keeps across grids. The
+ * model's own index is unscoped.
  */
-export declare function tuplesToContentfulEntries2(gridTuples: Tuple.GridTuple<Scalar>, scope: string, isColumn: boolean): ISpatialMap.Entry<ContentfulSpatialValue>[];
+export declare function tuplesToContentfulEntries(gridTuples: Tuple.GridTuple<Scalar>, isColumn: boolean, scope?: string): ISpatialMap.Entry<ContentfulSpatialValue>[];
 export declare function rangeToContentfulEntries(entries: readonly ISpatialMap.Entry[], isColumn: boolean): ISpatialMap.Entry<ContentfulSpatialValue>[];
 //# sourceMappingURL=ContentfulSpatialValue.d.ts.map