@cellrune/node 0.1.0

package/lib/normalization.js

@@ -0,0 +1,212 @@
+"use strict";
+
+const { protocolError } = require("./errors.js");
+const {
+  requireObject,
+  requireProtocolFinite,
+  requireProtocolString,
+} = require("./validation.js");
+
+function normalizeValue(value) {
+  requireObject(value, "cell value");
+  switch (value.kind) {
+    case "blank":
+    case "unsupported":
+      return { kind: value.kind };
+    case "number":
+      requireProtocolFinite(value.numberValue, "native number value");
+      return { kind: "number", value: value.numberValue };
+    case "text":
+      requireProtocolString(value.textValue, "native text value");
+      return { kind: "text", value: value.textValue };
+    case "logical":
+      if (typeof value.logicalValue !== "boolean") {
+        throw protocolError("native logical value is missing");
+      }
+      return { kind: "logical", value: value.logicalValue };
+    case "error":
+      requireProtocolString(value.errorValue, "native error value");
+      return { kind: "error", value: value.errorValue };
+    default:
+      throw protocolError("native cell value kind is unknown");
+  }
+}
+
+function normalizeResult(result) {
+  if (result === null || result === undefined) {
+    return null;
+  }
+  requireObject(result, "calculation result");
+  if (result.kind === "value" && result.value) {
+    return { kind: "value", value: normalizeValue(result.value) };
+  }
+  if (
+    result.kind === "unavailable" &&
+    typeof result.code === "string" &&
+    typeof result.message === "string"
+  ) {
+    return {
+      kind: "unavailable",
+      code: result.code,
+      message: result.message,
+      detail: result.detail ?? null,
+    };
+  }
+  throw protocolError("native calculation result is malformed");
+}
+
+function normalizeRangePage(page) {
+  requireObject(page, "range page");
+  return {
+    schemaVersion: page.schemaVersion,
+    sheet: page.sheet,
+    start: page.start,
+    end: page.end,
+    totalCells: page.totalCells,
+    offset: page.offset,
+    nextOffset: page.nextOffset ?? null,
+    cells: page.cells.map((cell) => ({
+      address: cell.address,
+      formula: cell.formula ?? null,
+      sourceValue: normalizeValue(cell.sourceValue),
+      sourceValueState: cell.sourceValueState,
+      calculated: normalizeResult(cell.calculated),
+    })),
+  };
+}
+
+function normalizeSummary(summary) {
+  requireObject(summary, "workbook summary");
+  return {
+    schemaVersion: summary.schemaVersion,
+    semanticRevision: BigInt(summary.semanticRevision),
+    documentBacked: summary.documentBacked,
+    documentKind: summary.documentKind,
+    dateSystem: summary.dateSystem,
+    diagnosticCount: summary.diagnosticCount,
+    sheets: summary.sheets.map((sheet) => ({
+      id: sheet.id,
+      name: sheet.name,
+      visibility: sheet.visibility,
+      cellCount: sheet.cellCount,
+      usedRange: sheet.usedRange ?? null,
+    })),
+  };
+}
+
+function normalizeCalculationReport(report) {
+  return {
+    schemaVersion: report.schemaVersion,
+    semanticRevision: BigInt(report.semanticRevision),
+    formulaCount: report.formulaCount,
+    valueCount: report.valueCount,
+    unavailableCount: report.unavailableCount,
+    materializedCellCount: report.materializedCellCount,
+  };
+}
+
+function normalizeCalculationDelta(delta) {
+  requireObject(delta, "calculation delta");
+  return {
+    schemaVersion: delta.schemaVersion,
+    cursor: BigInt(delta.cursor),
+    baseRevision: BigInt(delta.baseRevision),
+    resultRevision: BigInt(delta.resultRevision),
+    mode: delta.mode,
+    reason: delta.reason,
+    dirtyCount: delta.dirtyCount,
+    evaluatedCount: delta.evaluatedCount,
+    parsedFormulaCount: delta.parsedFormulaCount,
+    changedCells: delta.changedCells.map((change) => ({
+      cell: normalizeCellReference(change.cell),
+      origin: change.origin,
+      anchor:
+        change.anchor === null || change.anchor === undefined
+          ? null
+          : normalizeCellReference(change.anchor),
+      range: change.range ?? null,
+      result: normalizeResult(change.result),
+    })),
+    removedMaterializedCells: delta.removedMaterializedCells.map(
+      normalizeCellReference,
+    ),
+  };
+}
+
+function normalizeCalculationDeltaPage(page) {
+  requireObject(page, "calculation delta page");
+  return {
+    schemaVersion: page.schemaVersion,
+    requestedCursor: BigInt(page.requestedCursor),
+    nextCursor:
+      page.nextCursor === null || page.nextCursor === undefined
+        ? null
+        : BigInt(page.nextCursor),
+    deltas: page.deltas.map(normalizeCalculationDelta),
+  };
+}
+
+function normalizeEditReceipt(receipt) {
+  requireObject(receipt, "edit receipt");
+  return {
+    schemaVersion: receipt.schemaVersion,
+    baseRevision: BigInt(receipt.baseRevision),
+    resultRevision: BigInt(receipt.resultRevision),
+    appliedChangeCount: receipt.appliedChangeCount,
+    changedCells: receipt.changedCells.map(normalizeCellReference),
+    calculationChangedCells: receipt.calculationChangedCells.map(
+      normalizeCellReference,
+    ),
+    createdSheetIds: receipt.createdSheetIds,
+    topologyChanged: receipt.topologyChanged,
+    calculationMetadataChanged: receipt.calculationMetadataChanged,
+  };
+}
+
+function normalizeFunctionUsage(report) {
+  return {
+    schemaVersion: report.schemaVersion,
+    formulaCount: report.formulaCount,
+    parsedFormulaCount: report.parsedFormulaCount,
+    unparsedFormulaCount: report.unparsedFormulaCount,
+    entries: report.entries.map((entry) => ({
+      name: entry.name,
+      supported: entry.supported,
+      callCount: entry.callCount,
+      formulaCount: entry.formulaCount,
+      sampleCells: entry.sampleCells.map(normalizeCellReference),
+    })),
+  };
+}
+
+function normalizeWriteReport(report) {
+  return {
+    schemaVersion: report.schemaVersion,
+    complete: report.complete,
+    policy: report.policy,
+    materializedCount: report.materializedCount,
+    invalidatedCells: report.invalidatedCells.map(normalizeCellReference),
+    changedParts: report.changedParts,
+    removedParts: report.removedParts,
+    diagnosticCount: report.diagnosticCount,
+  };
+}
+
+function normalizeCellReference(cell) {
+  return {
+    sheetId: cell.sheetId,
+    sheetName: cell.sheetName,
+    address: cell.address,
+  };
+}
+
+module.exports = {
+  normalizeCalculationDelta,
+  normalizeCalculationDeltaPage,
+  normalizeCalculationReport,
+  normalizeEditReceipt,
+  normalizeFunctionUsage,
+  normalizeRangePage,
+  normalizeSummary,
+  normalizeWriteReport,
+};

package/lib/validation.js

@@ -0,0 +1,84 @@
+"use strict";
+
+const { inputError, protocolError } = require("./errors.js");
+
+function requireObject(value, name) {
+  if (value === null || typeof value !== "object") {
+    throw protocolError(`${name} must be an object`);
+  }
+}
+
+function requireString(value, name) {
+  if (typeof value !== "string") {
+    throw inputError(`${name} must be a string`);
+  }
+}
+
+function requireFinite(value, name) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw inputError(`${name} must be a finite number`);
+  }
+}
+
+function requireProtocolFinite(value, name) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw protocolError(`${name} must be a finite number`);
+  }
+}
+
+function requireProtocolString(value, name) {
+  if (typeof value !== "string") {
+    throw protocolError(`${name} must be a string`);
+  }
+}
+
+function requireOptionalFinite(value, name) {
+  if (value !== undefined) {
+    requireFinite(value, name);
+  }
+}
+
+function requireOptionalBoolean(value, name) {
+  if (value !== undefined && typeof value !== "boolean") {
+    throw inputError(`${name} must be a boolean`);
+  }
+}
+
+function requireNonNegativeInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw inputError(`${name} must be a non-negative safe integer`);
+  }
+}
+
+function requireU64BigInt(value, name) {
+  if (
+    typeof value !== "bigint" ||
+    value < 0n ||
+    value > 18446744073709551615n
+  ) {
+    throw inputError(`${name} must be an unsigned 64-bit bigint`);
+  }
+}
+
+function requireOptions(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw inputError("options must be an object");
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw inputError("options must be a plain object");
+  }
+}
+
+module.exports = {
+  requireFinite,
+  requireNonNegativeInteger,
+  requireObject,
+  requireOptionalBoolean,
+  requireOptionalFinite,
+  requireOptions,
+  requireProtocolFinite,
+  requireProtocolString,
+  requireString,
+  requireU64BigInt,
+};

package/native.d.ts

@@ -0,0 +1,170 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+export declare class NativeWorkbook {
+  get closed(): boolean
+  close(): void
+  summary(): NativeWorkbookSummary
+  readRange(sheet: string, start: string, end: string, offset: number, limit: number): NativeRangePage
+  functionUsage(): NativeFunctionUsageReport
+  calculate(todaySerial?: number | undefined | null, nowSerial?: number | undefined | null): Promise<NativeCalculationReport>
+  recalculate(mode: string, todaySerial?: number | undefined | null, nowSerial?: number | undefined | null): Promise<NativeCalculationDelta>
+  applyChanges(expectedRevision: string, batchJson: string): NativeEditReceipt
+  changesSince(cursor: string, limit: number): NativeCalculationDeltaPage
+  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, dynamicRange?: string | undefined | null): void
+  clearCell(sheet: string, address: string): boolean
+  addSheet(name: string): number
+  renameSheet(currentName: string, newName: string): void
+  toBytes(invalidateUnavailable: boolean): Promise<Buffer>
+  savePath(path: string, invalidateUnavailable: boolean, replaceExisting: boolean): Promise<NativeWriteReport>
+}
+
+export declare function createWorkbook(): NativeWorkbook
+
+export interface NativeCalculationDelta {
+  schemaVersion: number
+  cursor: string
+  baseRevision: string
+  resultRevision: string
+  mode: string
+  reason: string
+  dirtyCount: number
+  evaluatedCount: number
+  parsedFormulaCount: number
+  changedCells: Array<NativeCalculationDeltaCell>
+  removedMaterializedCells: Array<NativeCellReference>
+}
+
+export interface NativeCalculationDeltaCell {
+  cell: NativeCellReference
+  origin: string
+  anchor?: NativeCellReference
+  range?: string
+  result: NativeCalculationResult
+}
+
+export interface NativeCalculationDeltaPage {
+  schemaVersion: number
+  requestedCursor: string
+  nextCursor?: string
+  deltas: Array<NativeCalculationDelta>
+}
+
+export interface NativeCalculationReport {
+  schemaVersion: number
+  semanticRevision: string
+  formulaCount: number
+  valueCount: number
+  unavailableCount: number
+  materializedCellCount: number
+}
+
+export interface NativeCalculationResult {
+  kind: string
+  value?: NativeCellValue
+  code?: string
+  message?: string
+  detail?: string
+}
+
+export interface NativeCell {
+  address: string
+  formula?: string
+  sourceValue: NativeCellValue
+  sourceValueState: string
+  calculated?: NativeCalculationResult
+}
+
+export interface NativeCellReference {
+  sheetId: number
+  sheetName: string
+  address: string
+}
+
+export interface NativeCellValue {
+  kind: string
+  numberValue?: number
+  textValue?: string
+  logicalValue?: boolean
+  errorValue?: string
+}
+
+export interface NativeEditReceipt {
+  schemaVersion: number
+  baseRevision: string
+  resultRevision: string
+  appliedChangeCount: number
+  changedCells: Array<NativeCellReference>
+  calculationChangedCells: Array<NativeCellReference>
+  createdSheetIds: Array<number>
+  topologyChanged: boolean
+  calculationMetadataChanged: boolean
+}
+
+export interface NativeFunctionUsageEntry {
+  name: string
+  supported: boolean
+  callCount: number
+  formulaCount: number
+  sampleCells: Array<NativeCellReference>
+}
+
+export interface NativeFunctionUsageReport {
+  schemaVersion: number
+  formulaCount: number
+  parsedFormulaCount: number
+  unparsedFormulaCount: number
+  entries: Array<NativeFunctionUsageEntry>
+}
+
+export interface NativeRangePage {
+  schemaVersion: number
+  sheet: string
+  start: string
+  end: string
+  totalCells: number
+  offset: number
+  nextOffset?: number
+  cells: Array<NativeCell>
+}
+
+export interface NativeSheetSummary {
+  id: number
+  name: string
+  visibility: string
+  cellCount: number
+  usedRange?: string
+}
+
+export interface NativeWorkbookSummary {
+  schemaVersion: number
+  semanticRevision: string
+  documentBacked: boolean
+  documentKind: string
+  dateSystem: string
+  diagnosticCount: number
+  sheets: Array<NativeSheetSummary>
+}
+
+export interface NativeWriteReport {
+  schemaVersion: number
+  complete: boolean
+  policy: string
+  materializedCount: number
+  invalidatedCells: Array<NativeCellReference>
+  changedParts: Array<string>
+  removedParts: Array<string>
+  diagnosticCount: number
+}
+
+export declare function openWorkbookBytes(bytes: Buffer): Promise<NativeWorkbook>
+
+export declare function openWorkbookPath(path: string): Promise<NativeWorkbook>
+
+export declare function schemaVersion(): number