logisheets 1.15.0 → 1.16.0

package/dist/src/bindings/rpc_workbook_methods.d.ts

@@ -23,6 +23,7 @@ import { CheckFieldValidationParams } from './check_field_validation_params';
 import { CheckFormulaParams } from './rpc_check_formula_params';
 import { CheckpointMetaDto } from './checkpoint_meta';
 import { Comment } from './comment';
+import { DefinedNameInfo } from './defined_name_info';
 import { DeleteCheckpointParams } from './rpc_delete_checkpoint_params';
 import { DependentCell } from './dependent_cell';
 import { DisplayWindow } from './display_window';
@@ -146,6 +147,7 @@ export interface WorkbookMethods {
     getAllBlockFields(bookId?: number): Promise<readonly BlockField[] | ErrorMessage>;
     duplicateBlockKeys(bookId?: number): Promise<readonly DuplicateBlockKey[] | ErrorMessage>;
     getEnumSets(bookId?: number): Promise<readonly EnumSetInfo[] | ErrorMessage>;
+    getDefinedNames(bookId?: number): Promise<readonly DefinedNameInfo[] | ErrorMessage>;
     getBlockOpForPayloads(bookId?: number): Promise<readonly BlockOpForPayload[] | ErrorMessage>;
     getBlockOpPolicies(params: GetBlockOpPoliciesParams, bookId?: number): Promise<readonly BlockOpPolicy[] | ErrorMessage>;
     getAllBlocks(params: GetAllBlocksParams, bookId?: number): Promise<readonly BlockInfo[] | ErrorMessage>;
@@ -169,7 +171,7 @@ export interface WorkbookMethods {
     cleanHistory(bookId?: number): Promise<void | ErrorMessage>;
     toggleStatus(params: ToggleStatusParams, bookId?: number): Promise<void | ErrorMessage>;
     cleanupTempStatus(bookId?: number): Promise<void | ErrorMessage>;
-    commitTempStatus(bookId?: number): Promise<ActionEffect | ErrorMessage>;
+    commitTempStatus(bookId?: number): Promise<void | ErrorMessage>;
     loadWorkbook(params: LoadWorkbookParams, bookId?: number): Promise<void | ErrorMessage>;
     save(params: SaveParams, bookId?: number): Promise<SaveFileResult | ErrorMessage>;
     getAppData(bookId?: number): Promise<readonly AppData[] | ErrorMessage>;

package/dist/src/bindings/save_file_result.d.ts

@@ -1,4 +1,3 @@
 export interface SaveFileResult {
     data: Uint8Array;
-    code: number;
 }

package/dist/src/client.d.ts

@@ -1,16 +1,49 @@
 import type { ErrorMessage, ActionEffect, SheetCellId, WorkbookMethods, HandleTransactionParams } from './bindings';
 import type { CustomFunc } from './api';
+/** An async engine reply: the value, or an {@link ErrorMessage} on failure. */
 export type Resp<T> = Promise<T | ErrorMessage>;
 /**
- * The client is the interface for the workbook. This is used when the workbook
- * is wrapped by a server.
+ * The async engine contract shared logic codes against. Every method of the
+ * generated {@link WorkbookMethods} is `method(params) => Promise<T |
+ * ErrorMessage>`, bound to one workbook.
+ *
+ * Implementations: logisheets-engine's worker-backed `WorkbookClient` in the
+ * browser, and logisheets-runtime's `handle()` proxy on Node. The
+ * `register*` members below are host-side subscriptions; the Node proxy does
+ * not implement them, so code that must run headless should not rely on them.
+ *
+ * Failure contract (holds for every implementation):
+ *  - Methods never reject for an engine-level failure; they resolve an
+ *    `ErrorMessage` (check with `isErrorMessage`).
+ *  - `handleTransaction` does NOT resolve an `ErrorMessage` when the engine
+ *    refuses the edit. It resolves an `ActionEffect` whose
+ *    `status.type === 'err'`, with the reason in `errorMessage`, and nothing
+ *    is applied. A caller that needs the write to land must check `status`.
  */
 export interface Client extends WorkbookMethods {
+    /** Resolves once the engine can serve calls (the browser worker has
+     *  loaded its WASM). Await it before the first call. */
     isReady(): Promise<void>;
+    /**
+     * `handleTransaction` without the host's per-cell change notifications.
+     * Same failure contract: a rejection is `status.type === 'err'`.
+     */
     handleTransactionWithoutEvents(params: HandleTransactionParams): Resp<ActionEffect>;
+    /** Register a custom formula function. Not implemented by the browser
+     *  worker client. */
     registerCustomFunc(f: CustomFunc): void;
+    /** Fires after a transaction the engine reports as changing cells
+     *  (status `cell` / `sheetAndCell`). */
     registerCellUpdatedCallback(f: () => void): void;
+    /** Fires after a transaction the engine reports as changing sheet-level
+     *  state (status `sheet` / `sheetAndCell`). */
     registerSheetUpdatedCallback(f: () => void): void;
+    /**
+     * Subscribe to value changes of the cell currently at (sheetIdx, rowIdx,
+     * colIdx), all 0-based. The coordinate is resolved to a stable cell id
+     * once, so the subscription follows the cell if rows/cols move. Resolves
+     * an `ErrorMessage` if the coordinate cannot be resolved.
+     */
     registerCellValueChangedCallback(sheetIdx: number, rowIdx: number, colIdx: number, callback: () => void): Resp<void>;
     /**
      * Like {@link registerCellValueChangedCallback} but takes a
@@ -20,6 +53,10 @@ export interface Client extends WorkbookMethods {
      * round-trip.
      */
     registerCellValueChangedByCellId(cellId: SheetCellId, callback: () => void): void;
+    /** Like {@link registerCellValueChangedCallback}, but fires when the cell
+     *  is removed (its row/col deleted). */
     registerCellRemovedCallback(sheetIdx: number, rowIdx: number, colIdx: number, callback: () => void): Resp<void>;
+    /** Subscribe to a cell's shadow (validation) cell. Not implemented by the
+     *  browser worker client. */
     registerShadowCellValueChangedCallback(sheetIdx: number, rowIdx: number, colIdx: number, callback: () => void): Resp<number>;
 }

package/dist/src/layout.d.ts

@@ -1,3 +1,5 @@
+/** A per-cell overlay (marker colour, tooltip) a craft asks the host to draw
+ *  via `window.setCellLayouts`. Row and column are 0-based sheet coordinates. */
 export interface CellLayout {
     readonly sheetIdx: number;
     readonly row: number;

package/dist/src/types.d.ts

@@ -1,10 +1,15 @@
 import { CellCoordinate } from './bindings';
+/** Stable ids of a block's lines; they survive inserts and reorders, unlike
+ *  indexes. See `Workbook.getBlockRowId` / `getBlockColId`. */
 export type RowId = number;
 export type ColId = number;
+/** What the user has selected on one sheet (0-based indexes). */
 export interface Selection {
     readonly sheetIdx: number;
     readonly data: SelectedData;
 }
+/** Either whole rows/columns or a cell rectangle; `data` is absent when
+ *  nothing is selected. */
 export interface SelectedData {
     readonly data?: {
         ty: 'line';
@@ -15,6 +20,7 @@ export interface SelectedData {
     };
     readonly source: 'editbar' | 'none';
 }
+/** A cell rectangle; both bounds inclusive. */
 export interface SelectedCellRange {
     readonly startRow: number;
     readonly endRow: number;
@@ -26,6 +32,8 @@ export interface SelectedLines {
     readonly end: number;
     readonly type: 'row' | 'col';
 }
+/** Top-left cell of the selection (`y` = row, `x` = column). Throws when
+ *  nothing is selected. */
 export declare function getFirstCell(v: SelectedData): CellCoordinate;
 export declare function getSelectedCellRange(v: SelectedData): SelectedCellRange | undefined;
 export declare function getSelectedLines(v: SelectedData): SelectedLines | undefined;

package/dist/src/types.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getFirstCell = getFirstCell;
 exports.getSelectedCellRange = getSelectedCellRange;
 exports.getSelectedLines = getSelectedLines;
+/** Top-left cell of the selection (`y` = row, `x` = column). Throws when
+ *  nothing is selected. */
 function getFirstCell(v) {
     const r = getSelectedCellRange(v);
     if (r)

package/dist/src/utils.d.ts

@@ -1 +1,5 @@
+/**
+ * A 0-based column index as A1 column letters: 0 -> `A`, 25 -> `Z`,
+ * 26 -> `AA`. Throws for a negative or non-integer index.
+ */
 export declare function toA1notation(index: number): string;

package/dist/src/utils.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toA1notation = toA1notation;
+/**
+ * A 0-based column index as A1 column letters: 0 -> `A`, 25 -> `Z`,
+ * 26 -> `AA`. Throws for a negative or non-integer index.
+ */
 function toA1notation(index) {
     /**
      * The algorithm employed here is the same as converting numbers between

package/dist/wasm/logisheets_wasm_server.d.ts

@@ -1,6 +1,18 @@
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * The single RPC entry point. `msg` is a [`Message`] as JS (a bare method
+ * name for a unit variant, otherwise `{method, value}`); `book_id` names the
+ * workbook and is required by everything except `newWorkbook`, which returns
+ * the id to use. Answers the method's result or an `ErrorMessage`, told apart
+ * by shape on the JS side.
+ */
 export function handle(msg: any, book_id?: number | null): any;
+/**
+ * Render a text value with an Excel number-format code (for the `@` text
+ * section). Falls back to the text itself on an unsupported format.
+ */
+export function format_text(fmt: string, text: string): string;
 /**
  * Render a number with an Excel number-format code, natively via `ssf-rs`
  * (the Rust port of SheetJS `ssf`). Replaces the browser's old dependency on
@@ -9,12 +21,8 @@ export function handle(msg: any, book_id?: number | null): any;
  */
 export function format_number(fmt: string, value: number): string;
 /**
- * Render a text value with an Excel number-format code (for the `@` text
- * section). Falls back to the text itself on an unsupported format.
- */
-export function format_text(fmt: string, text: string): string;
-/**
- * Input: AsyncFuncResult
- * Output: ActionAffect
+ * Deliver the values the host computed for this workbook's async functions:
+ * an `AsyncFuncResult` in, an `ActionEffect` or an `ErrorMessage` out. Like
+ * `rpc::handle`, this must never panic.
  */
 export function input_async_result(id: number, result: any): any;

package/dist/wasm/logisheets_wasm_server.js

@@ -171,6 +171,11 @@ function debugString(val) {
     return className;
 }
 /**
+ * The single RPC entry point. `msg` is a [`Message`] as JS (a bare method
+ * name for a unit variant, otherwise `{method, value}`); `book_id` names the
+ * workbook and is required by everything except `newWorkbook`, which returns
+ * the id to use. Answers the method's result or an `ErrorMessage`, told apart
+ * by shape on the JS side.
  * @param {any} msg
  * @param {number | null} [book_id]
  * @returns {any}
@@ -180,30 +185,6 @@ module.exports.handle = function(msg, book_id) {
     return ret;
 };
 
-/**
- * Render a number with an Excel number-format code, natively via `ssf-rs`
- * (the Rust port of SheetJS `ssf`). Replaces the browser's old dependency on
- * the `ssf` npm package. On an unsupported/invalid format it falls back to the
- * JavaScript `String(value)` representation, matching the previous behavior.
- * @param {string} fmt
- * @param {number} value
- * @returns {string}
- */
-module.exports.format_number = function(fmt, value) {
-    let deferred2_0;
-    let deferred2_1;
-    try {
-        const ptr0 = passStringToWasm0(fmt, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-        const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.format_number(ptr0, len0, value);
-        deferred2_0 = ret[0];
-        deferred2_1 = ret[1];
-        return getStringFromWasm0(ret[0], ret[1]);
-    } finally {
-        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
-    }
-};
-
 /**
  * Render a text value with an Excel number-format code (for the `@` text
  * section). Falls back to the text itself on an unsupported format.
@@ -229,8 +210,33 @@ module.exports.format_text = function(fmt, text) {
 };
 
 /**
- * Input: AsyncFuncResult
- * Output: ActionAffect
+ * Render a number with an Excel number-format code, natively via `ssf-rs`
+ * (the Rust port of SheetJS `ssf`). Replaces the browser's old dependency on
+ * the `ssf` npm package. On an unsupported/invalid format it falls back to the
+ * JavaScript `String(value)` representation, matching the previous behavior.
+ * @param {string} fmt
+ * @param {number} value
+ * @returns {string}
+ */
+module.exports.format_number = function(fmt, value) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ptr0 = passStringToWasm0(fmt, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.format_number(ptr0, len0, value);
+        deferred2_0 = ret[0];
+        deferred2_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+};
+
+/**
+ * Deliver the values the host computed for this workbook's async functions:
+ * an `AsyncFuncResult` in, an `ActionEffect` or an `ErrorMessage` out. Like
+ * `rpc::handle`, this must never panic.
  * @param {number} id
  * @param {any} result
  * @returns {any}

package/dist/wasm/package.json

@@ -3,7 +3,7 @@
   "collaborators": [
     "JeremyHe <yiliang.he@qq.com>"
   ],
-  "version": "1.15.0",
+  "version": "1.16.0",
   "files": [
     "logisheets_wasm_server_bg.wasm",
     "logisheets_wasm_server.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "logisheets",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Node.js bindings for LogiSheets — a Rust + WebAssembly spreadsheet engine that reads, edits, and writes real .xlsx (Excel) files (formulas, styles, and structure preserved) with no browser required.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/wasm/logisheets_wasm_server.d.ts

@@ -1,6 +1,18 @@
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * The single RPC entry point. `msg` is a [`Message`] as JS (a bare method
+ * name for a unit variant, otherwise `{method, value}`); `book_id` names the
+ * workbook and is required by everything except `newWorkbook`, which returns
+ * the id to use. Answers the method's result or an `ErrorMessage`, told apart
+ * by shape on the JS side.
+ */
 export function handle(msg: any, book_id?: number | null): any;
+/**
+ * Render a text value with an Excel number-format code (for the `@` text
+ * section). Falls back to the text itself on an unsupported format.
+ */
+export function format_text(fmt: string, text: string): string;
 /**
  * Render a number with an Excel number-format code, natively via `ssf-rs`
  * (the Rust port of SheetJS `ssf`). Replaces the browser's old dependency on
@@ -9,12 +21,8 @@ export function handle(msg: any, book_id?: number | null): any;
  */
 export function format_number(fmt: string, value: number): string;
 /**
- * Render a text value with an Excel number-format code (for the `@` text
- * section). Falls back to the text itself on an unsupported format.
- */
-export function format_text(fmt: string, text: string): string;
-/**
- * Input: AsyncFuncResult
- * Output: ActionAffect
+ * Deliver the values the host computed for this workbook's async functions:
+ * an `AsyncFuncResult` in, an `ActionEffect` or an `ErrorMessage` out. Like
+ * `rpc::handle`, this must never panic.
  */
 export function input_async_result(id: number, result: any): any;

package/wasm/logisheets_wasm_server.js

@@ -171,6 +171,11 @@ function debugString(val) {
     return className;
 }
 /**
+ * The single RPC entry point. `msg` is a [`Message`] as JS (a bare method
+ * name for a unit variant, otherwise `{method, value}`); `book_id` names the
+ * workbook and is required by everything except `newWorkbook`, which returns
+ * the id to use. Answers the method's result or an `ErrorMessage`, told apart
+ * by shape on the JS side.
  * @param {any} msg
  * @param {number | null} [book_id]
  * @returns {any}
@@ -180,30 +185,6 @@ module.exports.handle = function(msg, book_id) {
     return ret;
 };
 
-/**
- * Render a number with an Excel number-format code, natively via `ssf-rs`
- * (the Rust port of SheetJS `ssf`). Replaces the browser's old dependency on
- * the `ssf` npm package. On an unsupported/invalid format it falls back to the
- * JavaScript `String(value)` representation, matching the previous behavior.
- * @param {string} fmt
- * @param {number} value
- * @returns {string}
- */
-module.exports.format_number = function(fmt, value) {
-    let deferred2_0;
-    let deferred2_1;
-    try {
-        const ptr0 = passStringToWasm0(fmt, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-        const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.format_number(ptr0, len0, value);
-        deferred2_0 = ret[0];
-        deferred2_1 = ret[1];
-        return getStringFromWasm0(ret[0], ret[1]);
-    } finally {
-        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
-    }
-};
-
 /**
  * Render a text value with an Excel number-format code (for the `@` text
  * section). Falls back to the text itself on an unsupported format.
@@ -229,8 +210,33 @@ module.exports.format_text = function(fmt, text) {
 };
 
 /**
- * Input: AsyncFuncResult
- * Output: ActionAffect
+ * Render a number with an Excel number-format code, natively via `ssf-rs`
+ * (the Rust port of SheetJS `ssf`). Replaces the browser's old dependency on
+ * the `ssf` npm package. On an unsupported/invalid format it falls back to the
+ * JavaScript `String(value)` representation, matching the previous behavior.
+ * @param {string} fmt
+ * @param {number} value
+ * @returns {string}
+ */
+module.exports.format_number = function(fmt, value) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ptr0 = passStringToWasm0(fmt, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.format_number(ptr0, len0, value);
+        deferred2_0 = ret[0];
+        deferred2_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+};
+
+/**
+ * Deliver the values the host computed for this workbook's async functions:
+ * an `AsyncFuncResult` in, an `ActionEffect` or an `ErrorMessage` out. Like
+ * `rpc::handle`, this must never panic.
  * @param {number} id
  * @param {any} result
  * @returns {any}

package/wasm/package.json

@@ -3,7 +3,7 @@
   "collaborators": [
     "JeremyHe <yiliang.he@qq.com>"
   ],
-  "version": "1.15.0",
+  "version": "1.16.0",
   "files": [
     "logisheets_wasm_server_bg.wasm",
     "logisheets_wasm_server.js",