@truecalc/workbook 8.2.0 → 8.2.1

package/README.md

@@ -215,6 +215,80 @@ const result = wb.resolved('Sheet1', 'A2');
 // => { type: 'number', value: 20 }
 ```
 
+### `wb.precedentsOf(sheet, cell, maxDepth?, maxNodes?)`
+
+What a cell **reads** — the answer to "where does this number come from?".
+
+- `sheet` — sheet name
+- `cell` — A1-style cell reference
+- `maxDepth` — how many levels to follow. Default `1` (direct precedents only),
+  clamped to `64`.
+- `maxNodes` — cap on the number of precedents returned. Default `1000`,
+  clamped to `10000`.
+
+Returns `{ cell, precedents, truncated, truncatedBy? }`. Each precedent is
+`{ depth, reference }`, where `reference` is a discriminated union tagged by
+`kind`:
+
+| `kind`       | Shape                                                             |
+|--------------|-------------------------------------------------------------------|
+| `cell`       | `{ kind: 'cell', sheet: 'Inputs', a1: 'A1' }`                     |
+| `range`      | `{ kind: 'range', sheet: 'Inputs', range: 'A1:A20' }`             |
+| `name`       | `{ kind: 'name', name: 'TaxRate', target: { kind: 'cell', ... } }`|
+| `unresolved` | `{ kind: 'unresolved', text: 'Nope!A1' }`                         |
+
+A range is one node, never expanded into its member cells. Every `cell` and
+`range` carries its own `sheet`, so cross-sheet precedents stay cross-sheet.
+`precedents` is always an array — a literal, an empty cell and a constant
+formula all return `[]`.
+
+```js
+wb.addSheet('Inputs');
+wb.addSheet('Report');
+wb.set('Inputs', 'A1', '10');
+wb.set('Report', 'B1', '=Inputs!A1 * 2');
+
+wb.precedentsOf('Report', 'B1');
+// => { cell: { sheet: 'Report', a1: 'B1' },
+//      precedents: [ { depth: 1, reference: { kind: 'cell', sheet: 'Inputs', a1: 'A1' } } ],
+//      truncated: false }
+```
+
+### `wb.dependentsOf(sheet, cell, maxDepth?, maxNodes?)`
+
+What **reads** a cell — the answer to "what breaks if I change this?".
+Same arguments and bounds as `precedentsOf`.
+
+Returns `{ cell, dependents, truncated, truncatedBy? }`, where each dependent is
+`{ depth, sheet, a1 }`. Dependents are always concrete formula cells, and
+include cells that reach this one through a range containing it or a named range
+targeting it. `dependents` is always an array; `[]` means nothing reads the cell.
+
+```js
+wb.dependentsOf('Inputs', 'A1');
+// => { cell: { sheet: 'Inputs', a1: 'A1' },
+//      dependents: [ { depth: 1, sheet: 'Report', a1: 'B1' } ],
+//      truncated: false }
+```
+
+### Bounds and freshness
+
+Every dependency query is bounded on both depth and node count and **always
+reports whether it stopped early**: `truncated` is `true` and `truncatedBy` is
+`'maxDepth'` or `'maxNodes'`. Branch on `truncated` — it is always present;
+`truncatedBy` appears only when truncated. A request above the ceilings is
+clamped, which is safe precisely because the clamp still sets `truncated`.
+
+The queries read the workbook's **current** formulas, named ranges and sheet
+names on every call. They need no `recalc()`, they reflect every `set` /
+`clear` / `defineName` since the last one, and they can never return a stale
+graph. The trade is cost: each call rebuilds the graph, `O(formula cells)` —
+an upper bound expected to improve, not a fixed contract — and `dependentsOf`
+additionally costs `O(distinct range nodes + names)` per node it walks, since
+finding what reads a cell means testing every range and every name against
+it. Neither call is a cheap accessor; a host driving these from the UI should
+debounce rather than call on every selection change.
+
 ### `wb.toJSON()`
 
 Serializes the entire workbook state (sheets, cell values, formulas, named ranges)

package/package.json

@@ -2,7 +2,7 @@
   "name": "@truecalc/workbook",
   "type": "module",
   "description": "Spreadsheet workbook for the browser — full Workbook API compiled to WebAssembly",
-  "version": "8.2.0",
+  "version": "8.2.1",
   "license": "MIT",
   "repository": {
     "type": "git",

package/truecalc_wasm_workbook.d.ts

@@ -1,5 +1,128 @@
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * A cell identified the way a JavaScript caller addresses one: the sheet name
+ * **as written in the workbook** (original case, not the case-folded key the
+ * graph indexes by) plus a plain A1 address.
+ */
+export interface CellNode {
+    /**
+     * Sheet name in the workbook\'s own casing — pass it straight back to
+     * `get`, `set` or another dependency query.
+     */
+    sheet: string;
+    /**
+     * Plain uppercase A1 address (`A1`, `BC42`) within `sheet`.
+     */
+    a1: string;
+}
+
+/**
+ * Answer to: what breaks if I change this cell?
+ */
+export interface DependentsResult {
+    /**
+     * The cell that was queried, echoed back in canonical form.
+     */
+    cell: CellNode;
+    /**
+     * The formula cells that would have to recalculate, nearest depth first.
+     * **Always present**, empty when nothing reads the cell.
+     */
+    dependents: DependentNode[];
+    /**
+     * `true` when the walk stopped before exhausting the graph.
+     */
+    truncated: boolean;
+    /**
+     * Which bound stopped the walk. Present exactly when `truncated` is
+     * `true`. As with [`PrecedentsResult::truncated_by`], reports
+     * `maxNodes` only when the node cap actually blocked an available
+     * dependent from being emitted, not merely because the emitted count
+     * happens to equal `maxNodes`.
+     */
+    truncatedBy?: "maxNodes" | "maxDepth";
+}
+
+/**
+ * Answer to: what does this cell read?
+ */
+export interface PrecedentsResult {
+    /**
+     * The cell that was queried, echoed back in canonical form.
+     */
+    cell: CellNode;
+    /**
+     * The precedents found, nearest depth first. **Always present**: a
+     * literal cell, an empty cell and a formula with no references all
+     * return an empty array — never a missing field — so absence of
+     * precedents is never confused with absence of an answer.
+     */
+    precedents: PrecedentNode[];
+    /**
+     * `true` when the walk stopped before exhausting the graph, i.e. the
+     * array above is a prefix of the real answer, not the whole of it.
+     */
+    truncated: boolean;
+    /**
+     * Which bound stopped the walk. Present exactly when `truncated` is
+     * `true` — branch on `truncated`, which is always present; this is the
+     * detail, not the signal. Reports `maxNodes` only when the node cap
+     * actually blocked an available precedent from being emitted; if depth
+     * is what kept the walk from going further — even when the emitted
+     * count happens to equal `maxNodes` — this reports `maxDepth`, the
+     * bound that actually ended the walk.
+     */
+    truncatedBy?: "maxNodes" | "maxDepth";
+}
+
+/**
+ * One dependent, with how far it sits from the queried cell. Dependents are
+ * always concrete formula cells — only a formula can read something.
+ */
+export interface DependentNode {
+    /**
+     * `1` = reads the queried cell directly (as a cell, through a range that
+     * contains it, or through a named range whose target contains it), `2` =
+     * reads something that reads it, and so on. Always the shortest distance.
+     */
+    depth: number;
+    /**
+     * Sheet name in the workbook\'s own casing.
+     */
+    sheet: string;
+    /**
+     * Plain uppercase A1 address within `sheet`.
+     */
+    a1: string;
+}
+
+/**
+ * One precedent, with how far it sits from the queried cell.
+ */
+export interface PrecedentNode {
+    /**
+     * `1` = read directly by the queried cell, `2` = read by something the
+     * queried cell reads, and so on. Always the **shortest** distance: a
+     * precedent reachable by several paths is reported once, at its nearest
+     * depth.
+     */
+    depth: number;
+    /**
+     * What is read.
+     */
+    reference: PrecedentRef;
+}
+
+/**
+ * One thing a formula reads, after sheet and name resolution.
+ *
+ * A range is reported as a **single** range node, never expanded into its
+ * cells: `SUM(A1:A100000)` is one precedent, which is what keeps the answer
+ * bounded and is also how the engine itself stores the edge.
+ */
+export type PrecedentRef = { kind: "cell"; sheet: string; a1: string } | { kind: "range"; sheet: string; range: string } | { kind: "name"; name: string; target: NameTargetRef } | { kind: "unresolved"; text: string };
+
 /**
  * Result of [`translate_formula`]: either the rewritten `formula` text or an
  * `error` message (mutually exclusive). Mirrors the `TranslateResult` shape
@@ -11,6 +134,12 @@ export interface TranslateResult {
     error?: string;
 }
 
+/**
+ * What a named range currently points at, carried alongside the name so a
+ * caller never has to resolve the indirection itself.
+ */
+export type NameTargetRef = { kind: "cell"; sheet: string; a1: string } | { kind: "range"; sheet: string; range: string } | { kind: "unresolved" };
+
 
 /**
  * A spreadsheet workbook exposed to JavaScript.
@@ -40,6 +169,29 @@ export class JsWorkbook {
      * (current-row) structured references against it.
      */
     defineTable(name: string, ref_str: string): void;
+    /**
+     * What **reads** the cell at `a1` on `sheet` — its dependents, i.e. what
+     * would have to recalculate (and could visibly change) if you edited it.
+     *
+     * Returns `{ cell, dependents: [{ depth, sheet, a1 }], truncated,
+     * truncatedBy? }`. Dependents are always concrete formula cells and
+     * include cells that reach this one through a range that contains it or
+     * through a named range whose target contains it — the caller never has
+     * to reason about range compression or name indirection.
+     *
+     * `dependents` is always an array; `[]` means nothing reads the cell.
+     *
+     * Bounds, truncation reporting and freshness are exactly as for
+     * [`precedentsOf`](Self::precedents_of), with one addition: finding what
+     * reads a cell means testing every distinct range node and every name
+     * against it, so each emitted (or expanded) node costs `O(distinct
+     * ranges + names)` on top of the `O(formula cells)` graph build — a
+     * workbook with many named ranges or range formulas makes this call
+     * noticeably more expensive than `precedentsOf` at the same size.
+     *
+     * Throws on an unknown sheet or a malformed A1 address.
+     */
+    dependentsOf(sheet: string, a1: string, max_depth?: number | null, max_nodes?: number | null): DependentsResult;
     /**
      * Deserializes a workbook from its canonical JSON string.
      */
@@ -51,6 +203,36 @@ export class JsWorkbook {
      * string (e.g. `"excel"`) for Excel-compatible behavior.
      */
     constructor(engine: string);
+    /**
+     * What the cell at `a1` on `sheet` **reads** — its precedents.
+     *
+     * Answers: where does this number come from? Returns
+     * `{ cell, precedents: [{ depth, reference }], truncated, truncatedBy? }`.
+     * Each `reference` is a tagged union: `cell`, `range` (never expanded into
+     * its members), `name` (carrying what the name currently targets), or
+     * `unresolved` (a dangling sheet or name, the reason the cell will show
+     * `#REF!` / `#NAME?`). Every `cell` / `range` carries its own `sheet`, so
+     * a cross-sheet precedent stays cross-sheet.
+     *
+     * `precedents` is always an array: a literal, an empty cell and a
+     * constant formula all return `[]`.
+     *
+     * `maxDepth` defaults to `1` (direct precedents only) and is clamped to
+     * `1..=64`; `maxNodes` defaults to `1000` and is clamped to `10000`.
+     * **If the walk stops at either bound, `truncated` is `true` and
+     * `truncatedBy` says which one** — the returned array is then a prefix of
+     * the answer, not the answer. `truncated` is always present; branch on
+     * it, not on `truncatedBy`.
+     *
+     * The graph is rebuilt from the workbook's current formulas on every
+     * call, so the result is never stale: it reflects every `set` / `clear` /
+     * `defineName` since the last `recalc`, and is meaningful before any
+     * `recalc` at all. Building the graph costs `O(formula cells)` per call —
+     * an upper bound expected to improve, not a fixed contract.
+     *
+     * Throws on an unknown sheet or a malformed A1 address.
+     */
+    precedentsOf(sheet: string, a1: string, max_depth?: number | null, max_nodes?: number | null): PrecedentsResult;
     /**
      * Runs a full recalculation against the given context JSON.
      *
@@ -134,8 +316,10 @@ export interface InitOutput {
     readonly jsworkbook_clear: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly jsworkbook_defineName: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly jsworkbook_defineTable: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly jsworkbook_dependentsOf: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
     readonly jsworkbook_fromJSON: (a: number, b: number, c: number) => void;
     readonly jsworkbook_new: (a: number, b: number) => number;
+    readonly jsworkbook_precedentsOf: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
     readonly jsworkbook_recalc: (a: number, b: number, c: number, d: number) => void;
     readonly jsworkbook_redefineName: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly jsworkbook_redefineTable: (a: number, b: number, c: number, d: number, e: number, f: number) => void;

package/truecalc_wasm_workbook.js

@@ -102,6 +102,52 @@ export class JsWorkbook {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * What **reads** the cell at `a1` on `sheet` — its dependents, i.e. what
+     * would have to recalculate (and could visibly change) if you edited it.
+     *
+     * Returns `{ cell, dependents: [{ depth, sheet, a1 }], truncated,
+     * truncatedBy? }`. Dependents are always concrete formula cells and
+     * include cells that reach this one through a range that contains it or
+     * through a named range whose target contains it — the caller never has
+     * to reason about range compression or name indirection.
+     *
+     * `dependents` is always an array; `[]` means nothing reads the cell.
+     *
+     * Bounds, truncation reporting and freshness are exactly as for
+     * [`precedentsOf`](Self::precedents_of), with one addition: finding what
+     * reads a cell means testing every distinct range node and every name
+     * against it, so each emitted (or expanded) node costs `O(distinct
+     * ranges + names)` on top of the `O(formula cells)` graph build — a
+     * workbook with many named ranges or range formulas makes this call
+     * noticeably more expensive than `precedentsOf` at the same size.
+     *
+     * Throws on an unknown sheet or a malformed A1 address.
+     * @param {string} sheet
+     * @param {string} a1
+     * @param {number | null} [max_depth]
+     * @param {number | null} [max_nodes]
+     * @returns {DependentsResult}
+     */
+    dependentsOf(sheet, a1, max_depth, max_nodes) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(sheet, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            const ptr1 = passStringToWasm0(a1, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len1 = WASM_VECTOR_LEN;
+            wasm.jsworkbook_dependentsOf(retptr, this.__wbg_ptr, ptr0, len0, ptr1, len1, isLikeNone(max_depth) ? 0x100000001 : (max_depth) >>> 0, isLikeNone(max_nodes) ? 0x100000001 : (max_nodes) >>> 0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return takeObject(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * Deserializes a workbook from its canonical JSON string.
      * @param {string} s
@@ -139,6 +185,59 @@ export class JsWorkbook {
         JsWorkbookFinalization.register(this, this.__wbg_ptr, this);
         return this;
     }
+    /**
+     * What the cell at `a1` on `sheet` **reads** — its precedents.
+     *
+     * Answers: where does this number come from? Returns
+     * `{ cell, precedents: [{ depth, reference }], truncated, truncatedBy? }`.
+     * Each `reference` is a tagged union: `cell`, `range` (never expanded into
+     * its members), `name` (carrying what the name currently targets), or
+     * `unresolved` (a dangling sheet or name, the reason the cell will show
+     * `#REF!` / `#NAME?`). Every `cell` / `range` carries its own `sheet`, so
+     * a cross-sheet precedent stays cross-sheet.
+     *
+     * `precedents` is always an array: a literal, an empty cell and a
+     * constant formula all return `[]`.
+     *
+     * `maxDepth` defaults to `1` (direct precedents only) and is clamped to
+     * `1..=64`; `maxNodes` defaults to `1000` and is clamped to `10000`.
+     * **If the walk stops at either bound, `truncated` is `true` and
+     * `truncatedBy` says which one** — the returned array is then a prefix of
+     * the answer, not the answer. `truncated` is always present; branch on
+     * it, not on `truncatedBy`.
+     *
+     * The graph is rebuilt from the workbook's current formulas on every
+     * call, so the result is never stale: it reflects every `set` / `clear` /
+     * `defineName` since the last `recalc`, and is meaningful before any
+     * `recalc` at all. Building the graph costs `O(formula cells)` per call —
+     * an upper bound expected to improve, not a fixed contract.
+     *
+     * Throws on an unknown sheet or a malformed A1 address.
+     * @param {string} sheet
+     * @param {string} a1
+     * @param {number | null} [max_depth]
+     * @param {number | null} [max_nodes]
+     * @returns {PrecedentsResult}
+     */
+    precedentsOf(sheet, a1, max_depth, max_nodes) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(sheet, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            const ptr1 = passStringToWasm0(a1, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len1 = WASM_VECTOR_LEN;
+            wasm.jsworkbook_precedentsOf(retptr, this.__wbg_ptr, ptr0, len0, ptr1, len1, isLikeNone(max_depth) ? 0x100000001 : (max_depth) >>> 0, isLikeNone(max_nodes) ? 0x100000001 : (max_nodes) >>> 0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return takeObject(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * Runs a full recalculation against the given context JSON.
      *
@@ -387,14 +486,26 @@ function __wbg_get_imports() {
         __wbg___wbindgen_throw_6b64449b9b9ed33c: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
+        __wbg_new_682678e2f47e32bc: function() {
+            const ret = new Array();
+            return addHeapObject(ret);
+        },
         __wbg_new_aa8d0fa9762c29bd: function() {
             const ret = new Object();
             return addHeapObject(ret);
         },
+        __wbg_set_3bf1de9fab0cd644: function(arg0, arg1, arg2) {
+            getObject(arg0)[arg1 >>> 0] = takeObject(arg2);
+        },
         __wbg_set_6be42768c690e380: function(arg0, arg1, arg2) {
             getObject(arg0)[takeObject(arg1)] = takeObject(arg2);
         },
-        __wbindgen_cast_0000000000000001: function(arg0, arg1) {
+        __wbindgen_cast_0000000000000001: function(arg0) {
+            // Cast intrinsic for `F64 -> Externref`.
+            const ret = arg0;
+            return addHeapObject(ret);
+        },
+        __wbindgen_cast_0000000000000002: function(arg0, arg1) {
             // Cast intrinsic for `Ref(String) -> Externref`.
             const ret = getStringFromWasm0(arg0, arg1);
             return addHeapObject(ret);
@@ -460,6 +571,10 @@ heap.push(undefined, null, true, false);
 
 let heap_next = heap.length;
 
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
 function passStringToWasm0(arg, malloc, realloc) {
     if (realloc === undefined) {
         const buf = cachedTextEncoder.encode(arg);