@cellrune/node 0.1.0

package/index.d.ts

@@ -0,0 +1,326 @@
+import type { Buffer } from "node:buffer";
+
+export const SCHEMA_VERSION: number;
+
+export type CellRuneErrorKind =
+  | "input"
+  | "validation"
+  | "read"
+  | "write"
+  | "state";
+
+export interface ErrorDetails {
+  readonly sourceCode: string | null;
+  readonly sourceId: string | null;
+  readonly detail: string | null;
+}
+
+export class CellRuneError extends Error {
+  private constructor();
+  readonly code: string;
+  readonly kind: CellRuneErrorKind;
+  readonly details: ErrorDetails;
+}
+
+export type CellValue =
+  | { readonly kind: "blank" }
+  | { readonly kind: "number"; readonly value: number }
+  | { readonly kind: "text"; readonly value: string }
+  | { readonly kind: "logical"; readonly value: boolean }
+  | { readonly kind: "error"; readonly value: string }
+  | { readonly kind: "unsupported" };
+
+export type CalculationResult =
+  | { readonly kind: "value"; readonly value: CellValue }
+  | {
+      readonly kind: "unavailable";
+      readonly code: string;
+      readonly message: string;
+      readonly detail: string | null;
+    };
+
+export interface Cell {
+  readonly address: string;
+  readonly formula: string | null;
+  readonly sourceValue: CellValue;
+  readonly sourceValueState: "literal" | "saved" | "missing" | "invalid";
+  readonly calculated: CalculationResult | null;
+}
+
+export interface RangePage {
+  readonly schemaVersion: number;
+  readonly sheet: string;
+  readonly start: string;
+  readonly end: string;
+  readonly totalCells: number;
+  readonly offset: number;
+  readonly nextOffset: number | null;
+  readonly cells: readonly Cell[];
+}
+
+export interface SheetSummary {
+  readonly id: number;
+  readonly name: string;
+  readonly visibility: "visible" | "hidden" | "very_hidden";
+  readonly cellCount: number;
+  readonly usedRange: string | null;
+}
+
+export interface WorkbookSummary {
+  readonly schemaVersion: number;
+  readonly semanticRevision: bigint;
+  readonly documentBacked: boolean;
+  readonly documentKind: "xlsx" | "xlsm" | "new_xlsx" | "open_xml";
+  readonly dateSystem: "excel_1900" | "excel_1904";
+  readonly diagnosticCount: number;
+  readonly sheets: readonly SheetSummary[];
+}
+
+export interface CalculationOptions {
+  readonly todaySerial?: number;
+  readonly nowSerial?: number;
+}
+
+export interface CalculationReport {
+  readonly schemaVersion: number;
+  readonly semanticRevision: bigint;
+  readonly formulaCount: number;
+  readonly valueCount: number;
+  readonly unavailableCount: number;
+  readonly materializedCellCount: number;
+}
+
+export type RecalculationMode = "auto" | "incremental" | "full";
+export type CalculationExecutionMode = "incremental" | "full";
+export type CalculationDecisionReason =
+  | "initial_calculation"
+  | "full_requested"
+  | "incremental_requested"
+  | "dirty_subset"
+  | "no_dirty_formulas"
+  | "topology_changed"
+  | "options_changed"
+  | "dynamic_topology"
+  | "dirty_set_covers_workbook"
+  | "unknown";
+
+export interface RecalculationOptions extends CalculationOptions {
+  readonly mode?: RecalculationMode;
+}
+
+export interface CellReference {
+  readonly sheetId: number;
+  readonly sheetName: string;
+  readonly address: string;
+}
+
+export type WritableCellValue = Exclude<CellValue, { readonly kind: "unsupported" }>;
+
+export type NumberFormatKind =
+  | "general"
+  | "number"
+  | "date"
+  | "time"
+  | "date_time"
+  | "duration";
+
+export type SheetVisibility = "visible" | "hidden" | "very_hidden";
+
+export type WorkbookChange =
+  | {
+      readonly kind: "setValue";
+      readonly sheet: string;
+      readonly address: string;
+      readonly value: WritableCellValue;
+    }
+  | {
+      readonly kind: "setFormula";
+      readonly sheet: string;
+      readonly address: string;
+      readonly formula: string;
+      readonly dynamicRange?: string | null;
+    }
+  | {
+      readonly kind: "clearCell";
+      readonly sheet: string;
+      readonly address: string;
+    }
+  | {
+      readonly kind: "setNumberFormat";
+      readonly sheet: string;
+      readonly address: string;
+      readonly id: number;
+      readonly code?: string | null;
+      readonly formatKind: NumberFormatKind;
+    }
+  | { readonly kind: "addSheet"; readonly name: string }
+  | {
+      readonly kind: "renameSheet";
+      readonly sheet: string;
+      readonly newName: string;
+    }
+  | {
+      readonly kind: "setSheetVisibility";
+      readonly sheet: string;
+      readonly visibility: SheetVisibility;
+    }
+  | {
+      readonly kind: "setDefinedName";
+      readonly name: string;
+      readonly scopeSheet?: string | null;
+      readonly formula: string;
+      readonly hidden: boolean;
+    }
+  | {
+      readonly kind: "removeDefinedName";
+      readonly name: string;
+      readonly scopeSheet?: string | null;
+    }
+  | {
+      readonly kind: "setDateSystem";
+      readonly dateSystem: "excel_1900" | "excel_1904";
+    }
+  | {
+      readonly kind: "setCalculationHints";
+      readonly mode?:
+        | "automatic"
+        | "automatic_except_data_tables"
+        | "manual"
+        | null;
+      readonly calculationId?: number | null;
+      readonly fullCalculationOnLoad?: boolean | null;
+      readonly forceFullCalculation?: boolean | null;
+    };
+
+export interface EditReceipt {
+  readonly schemaVersion: number;
+  readonly baseRevision: bigint;
+  readonly resultRevision: bigint;
+  readonly appliedChangeCount: number;
+  readonly changedCells: readonly CellReference[];
+  readonly calculationChangedCells: readonly CellReference[];
+  readonly createdSheetIds: readonly number[];
+  readonly topologyChanged: boolean;
+  readonly calculationMetadataChanged: boolean;
+}
+
+export interface CalculationDeltaCell {
+  readonly cell: CellReference;
+  readonly origin:
+    | "direct_formula"
+    | "legacy_array"
+    | "dynamic_spill"
+    | "unknown";
+  readonly anchor: CellReference | null;
+  readonly range: string | null;
+  readonly result: CalculationResult;
+}
+
+export interface CalculationDelta {
+  readonly schemaVersion: number;
+  readonly cursor: bigint;
+  readonly baseRevision: bigint;
+  readonly resultRevision: bigint;
+  readonly mode: CalculationExecutionMode;
+  readonly reason: CalculationDecisionReason;
+  readonly dirtyCount: number;
+  readonly evaluatedCount: number;
+  readonly parsedFormulaCount: number;
+  readonly changedCells: readonly CalculationDeltaCell[];
+  readonly removedMaterializedCells: readonly CellReference[];
+}
+
+export interface CalculationDeltaPage {
+  readonly schemaVersion: number;
+  readonly requestedCursor: bigint;
+  readonly nextCursor: bigint | null;
+  readonly deltas: readonly CalculationDelta[];
+}
+
+export interface FunctionUsageEntry {
+  readonly name: string;
+  readonly supported: boolean;
+  readonly callCount: number;
+  readonly formulaCount: number;
+  readonly sampleCells: readonly CellReference[];
+}
+
+export interface FunctionUsageReport {
+  readonly schemaVersion: number;
+  readonly formulaCount: number;
+  readonly parsedFormulaCount: number;
+  readonly unparsedFormulaCount: number;
+  readonly entries: readonly FunctionUsageEntry[];
+}
+
+export interface WriteOptions {
+  readonly invalidateUnavailable?: boolean;
+}
+
+export interface SaveOptions extends WriteOptions {
+  readonly replaceExisting?: boolean;
+}
+
+export interface WriteReport {
+  readonly schemaVersion: number;
+  readonly complete: boolean;
+  readonly policy: "require_complete" | "invalidate_unavailable" | "unknown";
+  readonly materializedCount: number;
+  readonly invalidatedCells: readonly CellReference[];
+  readonly changedParts: readonly string[];
+  readonly removedParts: readonly string[];
+  readonly diagnosticCount: number;
+}
+
+export class Workbook {
+  private constructor();
+  static create(): Workbook;
+  static openPath(path: string): Promise<Workbook>;
+  static fromBytes(bytes: Buffer | Uint8Array): Promise<Workbook>;
+  get closed(): boolean;
+  close(): void;
+  summary(): WorkbookSummary;
+  readRange(
+    sheet: string,
+    start: string,
+    end: string,
+    options?: { readonly offset?: number; readonly limit?: number },
+  ): RangePage;
+  functionUsage(): FunctionUsageReport;
+  calculate(options?: CalculationOptions): Promise<CalculationReport>;
+  recalculate(options?: RecalculationOptions): Promise<CalculationDelta>;
+  applyChanges(
+    expectedRevision: bigint,
+    changes: readonly WorkbookChange[],
+  ): EditReceipt;
+  changesSince(
+    cursor?: bigint,
+    options?: { readonly limit?: number },
+  ): CalculationDeltaPage;
+  cancelCalculation(): boolean;
+  calculationActive(): boolean;
+  setBlank(sheet: string, address: string): void;
+  setNumber(sheet: string, address: string, value: number): void;
+  setText(sheet: string, address: string, value: string): void;
+  setLogical(sheet: string, address: string, value: boolean): void;
+  setError(sheet: string, address: string, value: string): void;
+  setFormula(
+    sheet: string,
+    address: string,
+    formula: string,
+    options?: { readonly dynamicRange?: string },
+  ): void;
+  clearCell(sheet: string, address: string): boolean;
+  addSheet(name: string): number;
+  renameSheet(currentName: string, newName: string): void;
+  toBytes(options?: WriteOptions): Promise<Buffer>;
+  save(path: string, options?: SaveOptions): Promise<WriteReport>;
+}
+
+declare const packageExports: {
+  readonly SCHEMA_VERSION: typeof SCHEMA_VERSION;
+  readonly CellRuneError: typeof CellRuneError;
+  readonly Workbook: typeof Workbook;
+};
+
+export default packageExports;

package/index.mjs

@@ -0,0 +1,6 @@
+import packageExports from "./wrapper.js";
+
+export const SCHEMA_VERSION = packageExports.SCHEMA_VERSION;
+export const CellRuneError = packageExports.CellRuneError;
+export const Workbook = packageExports.Workbook;
+export default packageExports;

package/lib/changes.js

@@ -0,0 +1,176 @@
+"use strict";
+
+const { inputError } = require("./errors.js");
+const {
+  requireFinite,
+  requireNonNegativeInteger,
+  requireOptionalBoolean,
+  requireOptions,
+  requireString,
+} = require("./validation.js");
+
+function serializeWorkbookChange(change, index) {
+  requireOptions(change);
+  requireString(change.kind, `changes[${index}].kind`);
+  switch (change.kind) {
+    case "setValue":
+      return {
+        kind: "set_value",
+        sheet: requiredChangeString(change.sheet, index, "sheet"),
+        address: requiredChangeString(change.address, index, "address"),
+        value: serializeCellValue(change.value, index),
+      };
+    case "setFormula":
+      if (
+        change.dynamicRange !== undefined &&
+        change.dynamicRange !== null
+      ) {
+        requireString(change.dynamicRange, `changes[${index}].dynamicRange`);
+      }
+      return {
+        kind: "set_formula",
+        sheet: requiredChangeString(change.sheet, index, "sheet"),
+        address: requiredChangeString(change.address, index, "address"),
+        formula: requiredChangeString(change.formula, index, "formula"),
+        dynamic_range: change.dynamicRange ?? null,
+      };
+    case "clearCell":
+      return {
+        kind: "clear_cell",
+        sheet: requiredChangeString(change.sheet, index, "sheet"),
+        address: requiredChangeString(change.address, index, "address"),
+      };
+    case "setNumberFormat":
+      requireNonNegativeInteger(change.id, `changes[${index}].id`);
+      if (change.code !== undefined && change.code !== null) {
+        requireString(change.code, `changes[${index}].code`);
+      }
+      return {
+        kind: "set_number_format",
+        sheet: requiredChangeString(change.sheet, index, "sheet"),
+        address: requiredChangeString(change.address, index, "address"),
+        id: change.id,
+        code: change.code ?? null,
+        format_kind: requiredChangeString(
+          change.formatKind,
+          index,
+          "formatKind",
+        ),
+      };
+    case "addSheet":
+      return {
+        kind: "add_sheet",
+        name: requiredChangeString(change.name, index, "name"),
+      };
+    case "renameSheet":
+      return {
+        kind: "rename_sheet",
+        sheet: requiredChangeString(change.sheet, index, "sheet"),
+        new_name: requiredChangeString(change.newName, index, "newName"),
+      };
+    case "setSheetVisibility":
+      return {
+        kind: "set_sheet_visibility",
+        sheet: requiredChangeString(change.sheet, index, "sheet"),
+        visibility: requiredChangeString(
+          change.visibility,
+          index,
+          "visibility",
+        ),
+      };
+    case "setDefinedName":
+      if (change.scopeSheet !== undefined && change.scopeSheet !== null) {
+        requireString(change.scopeSheet, `changes[${index}].scopeSheet`);
+      }
+      if (typeof change.hidden !== "boolean") {
+        throw inputError(`changes[${index}].hidden must be a boolean`);
+      }
+      return {
+        kind: "set_defined_name",
+        name: requiredChangeString(change.name, index, "name"),
+        scope_sheet: change.scopeSheet ?? null,
+        formula: requiredChangeString(change.formula, index, "formula"),
+        hidden: change.hidden,
+      };
+    case "removeDefinedName":
+      if (change.scopeSheet !== undefined && change.scopeSheet !== null) {
+        requireString(change.scopeSheet, `changes[${index}].scopeSheet`);
+      }
+      return {
+        kind: "remove_defined_name",
+        name: requiredChangeString(change.name, index, "name"),
+        scope_sheet: change.scopeSheet ?? null,
+      };
+    case "setDateSystem":
+      return {
+        kind: "set_date_system",
+        date_system: requiredChangeString(
+          change.dateSystem,
+          index,
+          "dateSystem",
+        ),
+      };
+    case "setCalculationHints":
+      if (change.mode !== undefined && change.mode !== null) {
+        requireString(change.mode, `changes[${index}].mode`);
+      }
+      if (
+        change.calculationId !== undefined &&
+        change.calculationId !== null
+      ) {
+        requireNonNegativeInteger(
+          change.calculationId,
+          `changes[${index}].calculationId`,
+        );
+      }
+      requireOptionalBoolean(
+        change.fullCalculationOnLoad,
+        `changes[${index}].fullCalculationOnLoad`,
+      );
+      requireOptionalBoolean(
+        change.forceFullCalculation,
+        `changes[${index}].forceFullCalculation`,
+      );
+      return {
+        kind: "set_calculation_hints",
+        mode: change.mode ?? null,
+        calculation_id: change.calculationId ?? null,
+        full_calculation_on_load: change.fullCalculationOnLoad ?? null,
+        force_full_calculation: change.forceFullCalculation ?? null,
+      };
+    default:
+      throw inputError(`changes[${index}].kind is not recognized`);
+  }
+}
+
+function serializeCellValue(value, index) {
+  requireOptions(value);
+  requireString(value.kind, `changes[${index}].value.kind`);
+  switch (value.kind) {
+    case "blank":
+      return { kind: "blank" };
+    case "number":
+      requireFinite(value.value, `changes[${index}].value.value`);
+      return { kind: "number", value: value.value };
+    case "text":
+      requireString(value.value, `changes[${index}].value.value`);
+      return { kind: "text", value: value.value };
+    case "logical":
+      if (typeof value.value !== "boolean") {
+        throw inputError(`changes[${index}].value.value must be a boolean`);
+      }
+      return { kind: "logical", value: value.value };
+    case "error":
+      requireString(value.value, `changes[${index}].value.value`);
+      return { kind: "error", value: value.value };
+    default:
+      throw inputError(`changes[${index}].value.kind is not writable`);
+  }
+}
+
+function requiredChangeString(value, index, name) {
+  requireString(value, `changes[${index}].${name}`);
+  return value;
+}
+
+module.exports = { serializeWorkbookChange };

package/lib/errors.js

@@ -0,0 +1,95 @@
+"use strict";
+
+const ERROR_PREFIX = "CELLRUNE_ERROR:";
+const ERROR = Object.freeze({
+  CLOSED: ["interop.session.closed", "workbook session is closed"],
+  ARGUMENT: ["interop.input.invalid", "argument failed runtime validation"],
+  PROTOCOL: [
+    "interop.binding.protocol",
+    "native binding returned an invalid typed value",
+  ],
+});
+
+class CellRuneError extends Error {
+  constructor(message, code, kind, details = {}) {
+    super(message);
+    this.name = "CellRuneError";
+    this.code = code;
+    this.kind = kind;
+    this.details = {
+      sourceCode: details.sourceCode ?? null,
+      sourceId: details.sourceId ?? null,
+      detail: details.detail ?? null,
+    };
+  }
+}
+
+function withSyncErrors(operation) {
+  try {
+    return operation();
+  } catch (error) {
+    throw convertError(error);
+  }
+}
+
+async function withErrors(promise) {
+  try {
+    return await promise;
+  } catch (error) {
+    throw convertError(error);
+  }
+}
+
+function convertError(error) {
+  if (error instanceof CellRuneError) {
+    return error;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  const marker = message.indexOf(ERROR_PREFIX);
+  if (marker >= 0) {
+    try {
+      const payload = JSON.parse(message.slice(marker + ERROR_PREFIX.length));
+      if (
+        typeof payload.code === "string" &&
+        typeof payload.kind === "string" &&
+        typeof payload.message === "string" &&
+        payload.details &&
+        typeof payload.details === "object"
+      ) {
+        return new CellRuneError(payload.message, payload.code, payload.kind, {
+          sourceCode: payload.details.source_code,
+          sourceId: payload.details.source_id,
+          detail: payload.details.detail,
+        });
+      }
+    } catch {
+      return protocolError("native error payload is malformed");
+    }
+  }
+  return error instanceof Error ? error : new Error(message);
+}
+
+function closedError() {
+  return new CellRuneError(ERROR.CLOSED[1], ERROR.CLOSED[0], "state");
+}
+
+function inputError(detail) {
+  return new CellRuneError(ERROR.ARGUMENT[1], ERROR.ARGUMENT[0], "input", {
+    detail,
+  });
+}
+
+function protocolError(detail) {
+  return new CellRuneError(ERROR.PROTOCOL[1], ERROR.PROTOCOL[0], "state", {
+    detail,
+  });
+}
+
+module.exports = {
+  CellRuneError,
+  closedError,
+  inputError,
+  protocolError,
+  withErrors,
+  withSyncErrors,
+};