@veltra/sheet 2.0.1 → 2.2.0

package/src/core/formula/dependency-graph.ts

@@ -1,329 +0,0 @@
-import { cellKey, rangeContainsAddress, type CellAddress, type CellRange } from '../address'
-import type { CellData, CellType, CellValue } from '../cell-store'
-import type { CellPatch } from '../command/types'
-import type { Sheet } from '../sheet'
-import { collectReferences, type AstNode } from './ast'
-import { formulaError, isFormulaError, isFormulaErrorCode, type FormulaError } from './errors'
-import { evaluateAst, type ScalarValue } from './evaluator'
-import { invokeFormulaFunction } from './functions'
-import { parseFormula } from './parser'
-import { FormulaParseError } from './tokenizer'
-
-/**
- * 依赖图（工作簿级计算中枢）：
- * - sheet 注册表：跨表引用按名解析（不存在 → #REF!）
- * - 正向索引：公式格 → 引用格集合（节点 deps）；反向索引：引用格 → 依赖者
- *   （单格引用走 cellKey 精确索引 O(1)，区域引用走线性扫描）
- * - 变更时标脏（向上 BFS 收集全部依赖者）+ 拓扑序增量重算（递归向下，memo 去重）
- * - 循环引用检测：求值在途栈遇回边 → 环上所有格 #CYCLE!；依赖环外格只传播错误，
- *   打破循环（编辑环上格）后经标脏重算自动恢复
- *
- * 图状态与单元格存储严格同步：所有 f 变更（命令/undo/redo/rollback 回放）都经
- * Sheet.applyPatch → syncCell 维护节点；重算只发生在命令执行后（见 Sheet.executeCommand），
- * undo/redo 靠派生补丁精确回放缓存值，不重算。
- */
-
-/** 公式节点的一个依赖（sheet 名已补齐为具体值） */
-export interface FormulaDependency {
-  sheetName: string
-  range: CellRange
-}
-
-/** 公式节点（依赖图管理的公式格状态；依赖图外部只读使用） */
-export interface FormulaNode {
-  readonly sheetName: string
-  readonly addr: CellAddress
-  readonly formula: string
-  /** null = 解析失败（求值 #ERROR!，无依赖） */
-  readonly ast: AstNode | null
-  readonly deps: FormulaDependency[]
-  /** 反向索引清理器（removeNode 时执行） */
-  readonly cleanups: (() => void)[]
-}
-
-export class DependencyGraph {
-  private readonly sheets = new Map<string, Sheet>()
-  /** 正向索引宿主：sheetName → cellKey → 公式节点 */
-  private readonly nodes = new Map<string, Map<number, FormulaNode>>()
-  /** 反向索引（单格引用）：sheetName → cellKey → 依赖者集合 */
-  private readonly exact = new Map<string, Map<number, Set<FormulaNode>>>()
-  /** 反向索引（区域引用）：sheetName → { 区域, 依赖者 } 集合（线性扫描） */
-  private readonly ranged = new Map<string, Set<{ range: CellRange; node: FormulaNode }>>()
-
-  // ─── sheet 注册表 ─────────────────────────────────────────
-
-  registerSheet(sheet: Sheet): void {
-    this.sheets.set(sheet.name, sheet)
-  }
-
-  /** 注销 sheet 并移除其全部公式节点（引用它的公式在下次重算时得 #REF!） */
-  unregisterSheet(sheet: Sheet): void {
-    if (this.sheets.get(sheet.name) !== sheet) return
-    this.sheets.delete(sheet.name)
-    const sheetNodes = this.nodes.get(sheet.name)
-    if (sheetNodes) {
-      for (const node of sheetNodes.values()) this.removeNode(node)
-    }
-  }
-
-  getSheet(name: string): Sheet | undefined {
-    return this.sheets.get(name)
-  }
-
-  // ─── 节点查询 ─────────────────────────────────────────────
-
-  getNode(sheetName: string, addr: CellAddress): FormulaNode | undefined {
-    return this.nodes.get(sheetName)?.get(cellKey(addr))
-  }
-
-  /** 公式节点总数（测试/调试用） */
-  get nodeCount(): number {
-    let count = 0
-    for (const sheetNodes of this.nodes.values()) count += sheetNodes.size
-    return count
-  }
-
-  // ─── 图同步 ───────────────────────────────────────────────
-
-  /**
-   * 单元格补丁后的图同步：f 增/删/改 → 节点增/删/重建。
-   * 由 Sheet.applyPatch（唯一变更通道）调用，命令与 undo/redo 回放均覆盖。
-   */
-  syncCell(sheet: Sheet, addr: CellAddress, before?: CellData, after?: CellData): void {
-    const beforeF = before?.f
-    const afterF = after?.f
-    if (beforeF === afterF) return
-    const existing = this.getNode(sheet.name, addr)
-    if (existing) this.removeNode(existing)
-    if (afterF != null && afterF !== '') this.addNode(sheet, addr, afterF)
-  }
-
-  // ─── 增量重算 ─────────────────────────────────────────────
-
-  /**
-   * 变更集 → 标脏 + 拓扑序重算 → 派生补丁（未应用）。
-   * 调用方（Sheet.executeCommand）负责应用补丁并并入同一 undo 单元。
-   */
-  recalc(changed: readonly { sheet: Sheet; addr: CellAddress }[]): CellPatch[] {
-    // 1. 标脏：变更格自身（若是公式）+ 向上 BFS 全部传递依赖者
-    const dirty = new Set<FormulaNode>()
-    const queue: FormulaNode[] = []
-    const mark = (node: FormulaNode | undefined): void => {
-      if (node && !dirty.has(node)) {
-        dirty.add(node)
-        queue.push(node)
-      }
-    }
-    for (const { sheet, addr } of changed) {
-      mark(this.getNode(sheet.name, addr))
-      for (const dep of this.dependentsOf(sheet.name, addr)) mark(dep)
-    }
-    for (let i = 0; i < queue.length; i++) {
-      const node = queue[i]!
-      for (const dep of this.dependentsOf(node.sheetName, node.addr)) mark(dep)
-    }
-    if (dirty.size === 0) return []
-
-    // 2. 拓扑序求值：递归向下（依赖先于使用求值），memo 保证每格最多算一次；
-    //    在途栈遇回边 → 栈中自回边点起全部入环（#CYCLE!）
-    const passValues = new Map<FormulaNode, ScalarValue | FormulaError>()
-    const inProgress = new Set<FormulaNode>()
-    const stack: FormulaNode[] = []
-    const cycleMembers = new Set<FormulaNode>()
-    const cycleError = formulaError('#CYCLE!')
-
-    const evaluateNode = (node: FormulaNode): ScalarValue | FormulaError => {
-      const cached = passValues.get(node)
-      if (cached !== undefined) return cached
-      if (inProgress.has(node)) {
-        const start = stack.indexOf(node)
-        for (let i = start; i < stack.length; i++) cycleMembers.add(stack[i]!)
-        return cycleError
-      }
-      if (!node.ast) {
-        const error = formulaError('#ERROR!')
-        passValues.set(node, error)
-        return error
-      }
-      inProgress.add(node)
-      stack.push(node)
-      let value: ScalarValue | FormulaError | (ScalarValue | FormulaError)[]
-      try {
-        value = evaluateAst(node.ast, {
-          currentSheet: node.sheetName,
-          readCell,
-          readRange,
-          callFunction: invokeFormulaFunction
-        })
-      } catch {
-        // 求值期异常（如自定义函数抛错）不应击穿重算 → 记为 #ERROR!
-        value = formulaError('#ERROR!')
-      }
-      inProgress.delete(node)
-      stack.pop()
-      // 区域直接作为公式结果（'=A1:B2'）→ #VALUE!
-      if (Array.isArray(value)) value = formulaError('#VALUE!')
-      if (cycleMembers.has(node)) value = cycleError
-      passValues.set(node, value)
-      return value
-    }
-
-    const readCell = (sheetName: string, addr: CellAddress): ScalarValue | FormulaError => {
-      const sheet = this.sheets.get(sheetName)
-      if (!sheet) return formulaError('#REF!')
-      const dep = this.getNode(sheetName, addr)
-      if (dep && dirty.has(dep)) return evaluateNode(dep)
-      return cellDataToScalar(sheet.store.getCell(addr))
-    }
-
-    const readRange = (
-      sheetName: string,
-      range: CellRange
-    ): (ScalarValue | FormulaError)[] | FormulaError => {
-      const sheet = this.sheets.get(sheetName)
-      if (!sheet) return formulaError('#REF!')
-      const values: (ScalarValue | FormulaError)[] = []
-      // 只迭代稀疏存在的格
-      for (const [addr, data] of sheet.store.entriesInRange(range)) {
-        const dep = this.getNode(sheetName, addr)
-        values.push(dep && dirty.has(dep) ? evaluateNode(dep) : cellDataToScalar(data))
-      }
-      return values
-    }
-
-    for (const node of dirty) evaluateNode(node)
-
-    // 3. 派生补丁：缓存值与重算结果一致的跳过（收敛时不产生冗余变更）
-    const patches: CellPatch[] = []
-    for (const node of dirty) {
-      const value = passValues.get(node)!
-      const { v, t } = serializeResult(value)
-      const sheet = this.sheets.get(node.sheetName)
-      if (!sheet) continue
-      const before = sheet.store.getCell(node.addr)
-      if (before && before.f === node.formula && before.v === v && before.t === t) continue
-      patches.push({
-        kind: 'cell',
-        sheet,
-        addr: node.addr,
-        before,
-        after: { f: node.formula, v, t }
-      })
-    }
-    return patches
-  }
-
-  // ─── 内部 ─────────────────────────────────────────────────
-
-  private addNode(sheet: Sheet, addr: CellAddress, formula: string): void {
-    let ast: AstNode | null = null
-    try {
-      ast = parseFormula(formula)
-    } catch (error) {
-      if (!(error instanceof FormulaParseError)) throw error
-      // 解析失败：ast 保持 null（求值 #ERROR!，无依赖）
-    }
-    const deps: FormulaDependency[] = []
-    if (ast) {
-      const seen = new Set<string>()
-      for (const ref of collectReferences(ast)) {
-        const sheetName = ref.sheet ?? sheet.name
-        const { start, end } = ref.range
-        const key = `${sheetName}|${start.row},${start.col},${end.row},${end.col}`
-        if (seen.has(key)) continue
-        seen.add(key)
-        deps.push({ sheetName, range: ref.range })
-      }
-    }
-    const node: FormulaNode = {
-      sheetName: sheet.name,
-      addr: { ...addr },
-      formula,
-      ast,
-      deps,
-      cleanups: []
-    }
-    let sheetNodes = this.nodes.get(sheet.name)
-    if (!sheetNodes) {
-      sheetNodes = new Map()
-      this.nodes.set(sheet.name, sheetNodes)
-    }
-    sheetNodes.set(cellKey(addr), node)
-
-    for (const dep of deps) {
-      const isSingleCell =
-        dep.range.start.row === dep.range.end.row && dep.range.start.col === dep.range.end.col
-      if (isSingleCell) {
-        let sheetExact = this.exact.get(dep.sheetName)
-        if (!sheetExact) {
-          sheetExact = new Map()
-          this.exact.set(dep.sheetName, sheetExact)
-        }
-        const key = cellKey(dep.range.start)
-        let set = sheetExact.get(key)
-        if (!set) {
-          set = new Set()
-          sheetExact.set(key, set)
-        }
-        set.add(node)
-        node.cleanups.push(() => {
-          set.delete(node)
-          if (set.size === 0) sheetExact.delete(key)
-        })
-      } else {
-        let set = this.ranged.get(dep.sheetName)
-        if (!set) {
-          set = new Set()
-          this.ranged.set(dep.sheetName, set)
-        }
-        const entry = { range: dep.range, node }
-        set.add(entry)
-        node.cleanups.push(() => set.delete(entry))
-      }
-    }
-  }
-
-  private removeNode(node: FormulaNode): void {
-    for (const cleanup of node.cleanups) cleanup()
-    const sheetNodes = this.nodes.get(node.sheetName)
-    if (!sheetNodes) return
-    sheetNodes.delete(cellKey(node.addr))
-    if (sheetNodes.size === 0) this.nodes.delete(node.sheetName)
-  }
-
-  private dependentsOf(sheetName: string, addr: CellAddress): Set<FormulaNode> {
-    const result = new Set<FormulaNode>()
-    const exactSet = this.exact.get(sheetName)?.get(cellKey(addr))
-    if (exactSet) for (const node of exactSet) result.add(node)
-    const rangedSet = this.ranged.get(sheetName)
-    if (rangedSet) {
-      for (const entry of rangedSet) {
-        if (rangeContainsAddress(entry.range, addr)) result.add(entry.node)
-      }
-    }
-    return result
-  }
-}
-
-/** 单元格存储 → 求值标量（t='e' 还原为错误标记；空 → null） */
-function cellDataToScalar(data: CellData | undefined): ScalarValue | FormulaError {
-  if (!data || data.v == null) return null
-  if (data.t === 'e') {
-    return formulaError(isFormulaErrorCode(data.v) ? data.v : '#ERROR!')
-  }
-  return data.v
-}
-
-/** 求值结果 → 存储形态（str = 公式结果字符串，e = 错误；与决策 2 一致） */
-function serializeResult(value: ScalarValue | FormulaError): { v: CellValue; t: CellType } {
-  if (isFormulaError(value)) return { v: value.code, t: 'e' }
-  if (value === null) return { v: 0, t: 'n' } // 防御：公式结果不会是 null
-  switch (typeof value) {
-    case 'number':
-      return { v: value, t: 'n' }
-    case 'boolean':
-      return { v: value, t: 'b' }
-    default:
-      return { v: value, t: 'str' }
-  }
-}

package/src/core/formula/errors.ts

@@ -1,41 +0,0 @@
-/**
- * 公式错误值体系。
- *
- * 求值器内部以 FormulaError 标记对象传递错误（随运算传播）；
- * 写入单元格时序列化为 `v = 错误码, t = 'e'`（决策 2 的 CellData 格式）。
- */
-
-/** 公式错误码（Excel 子集 + 解析失败 #ERROR!、循环引用 #CYCLE!） */
-export const FORMULA_ERROR_CODES = [
-  '#DIV/0!',
-  '#VALUE!',
-  '#NAME?',
-  '#REF!',
-  '#ERROR!',
-  '#CYCLE!'
-] as const
-
-export type FormulaErrorCode = (typeof FORMULA_ERROR_CODES)[number]
-
-const ERROR_BRAND: unique symbol = Symbol('veltra-sheet.formula-error')
-
-/** 求值过程中的错误标记（不参与普通值运算，遇运算即传播） */
-export interface FormulaError {
-  readonly [ERROR_BRAND]: true
-  readonly code: FormulaErrorCode
-}
-
-/** 构造错误标记 */
-export function formulaError(code: FormulaErrorCode): FormulaError {
-  return { [ERROR_BRAND]: true, code }
-}
-
-/** 判定错误标记 */
-export function isFormulaError(value: unknown): value is FormulaError {
-  return typeof value === 'object' && value !== null && ERROR_BRAND in value
-}
-
-/** 判定合法错误码（读取 t='e' 的单元格时校验） */
-export function isFormulaErrorCode(value: unknown): value is FormulaErrorCode {
-  return typeof value === 'string' && (FORMULA_ERROR_CODES as readonly string[]).includes(value)
-}

package/src/core/formula/evaluator.ts

@@ -1,219 +0,0 @@
-import type { CellAddress, CellRange } from '../address'
-import type { AstNode, BinaryOperator } from './ast'
-import { formulaError, isFormulaError, type FormulaError } from './errors'
-
-/**
- * AST 求值器（纯函数，不持有状态；单元格读取经 FormulaEvalContext 注入）。
- *
- * 空格（null）参与运算的规则同 Excel：
- * - 数字上下文按 0（空单元格 +1 = 1）；空字符串字面量参与算术 → #VALUE!
- * - 文本上下文按 ''；布尔上下文按 FALSE
- * - 比较时空格归一为对方类型的零值
- * 错误值遇运算即传播（左操作数优先）。
- */
-
-/** 标量值（单元格/字面量可取的全集；null = 空单元格） */
-export type ScalarValue = number | string | boolean | null
-
-/** 求值结果：标量 / 错误 / 区域展开数组（数组仅作为函数参数形态出现） */
-export type EvalValue = ScalarValue | FormulaError | (ScalarValue | FormulaError)[]
-
-/** 求值上下文（由依赖图按公式节点注入） */
-export interface FormulaEvalContext {
-  /** 当前公式所在 sheet（裸引用缺省表） */
-  readonly currentSheet: string
-  /** 读取单格（原始存储语义；表不存在 → #REF!） */
-  readCell(sheet: string, addr: CellAddress): ScalarValue | FormulaError
-  /** 读取区域（只含稀疏存在的格；表不存在 → #REF!） */
-  readRange(sheet: string, range: CellRange): (ScalarValue | FormulaError)[] | FormulaError
-  /** 调用函数（名称未知 → #NAME?；参数个数非法 → #VALUE!） */
-  callFunction(name: string, nodes: AstNode[], evalNode: (node: AstNode) => EvalValue): EvalValue
-}
-
-const NUMERIC_TEXT_RE = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/
-
-/** 强转数字：null→0，布尔→1/0，数字文本→数字，其余文本→#VALUE!，错误传播 */
-export function coerceToNumber(value: EvalValue): number | FormulaError {
-  if (isFormulaError(value)) return value
-  if (Array.isArray(value)) return formulaError('#VALUE!')
-  if (value === null) return 0
-  switch (typeof value) {
-    case 'number':
-      return value
-    case 'boolean':
-      return value ? 1 : 0
-    case 'string': {
-      const text = value.trim()
-      if (text === '') return formulaError('#VALUE!')
-      if (text.toUpperCase() === 'TRUE') return 1
-      if (text.toUpperCase() === 'FALSE') return 0
-      if (NUMERIC_TEXT_RE.test(text)) return Number.parseFloat(text)
-      return formulaError('#VALUE!')
-    }
-  }
-}
-
-/** 强转文本：null→''，布尔→TRUE/FALSE，错误传播 */
-export function coerceToText(value: EvalValue): string | FormulaError {
-  if (isFormulaError(value)) return value
-  if (Array.isArray(value)) return formulaError('#VALUE!')
-  if (value === null) return ''
-  switch (typeof value) {
-    case 'string':
-      return value
-    case 'number':
-      return String(value)
-    case 'boolean':
-      return value ? 'TRUE' : 'FALSE'
-  }
-}
-
-/** 强转布尔：null→FALSE，数字≠0，TRUE/FALSE 文本，其余文本→#VALUE!，错误传播 */
-export function coerceToBoolean(value: EvalValue): boolean | FormulaError {
-  if (isFormulaError(value)) return value
-  if (Array.isArray(value)) return formulaError('#VALUE!')
-  if (value === null) return false
-  switch (typeof value) {
-    case 'boolean':
-      return value
-    case 'number':
-      return value !== 0
-    case 'string': {
-      const text = value.trim().toUpperCase()
-      if (text === 'TRUE') return true
-      if (text === 'FALSE') return false
-      return formulaError('#VALUE!')
-    }
-  }
-}
-
-/** 比较：同类型按类型规则（文本大小写不敏感）；混合类型 数字 < 文本 < 布尔；null 归一为对方零值 */
-export function compareScalars(left: ScalarValue, right: ScalarValue): number {
-  if (left === null || right === null) {
-    if (left === null && right === null) return 0
-    if (left === null) return compareScalars(zeroLike(right), right)
-    return compareScalars(left, zeroLike(left))
-  }
-  const leftType = typeof left
-  const rightType = typeof right
-  if (leftType === 'number' && rightType === 'number') {
-    return left < right ? -1 : left > right ? 1 : 0
-  }
-  if (leftType === 'string' && rightType === 'string') {
-    const a = (left as string).toUpperCase()
-    const b = (right as string).toUpperCase()
-    return a < b ? -1 : a > b ? 1 : 0
-  }
-  if (leftType === 'boolean' && rightType === 'boolean') {
-    return left === right ? 0 : left ? 1 : -1
-  }
-  return typeRank(leftType) - typeRank(rightType)
-}
-
-function zeroLike(value: ScalarValue): ScalarValue {
-  if (typeof value === 'number') return 0
-  if (typeof value === 'string') return ''
-  return false
-}
-
-function typeRank(type: string): number {
-  if (type === 'number') return 0
-  if (type === 'string') return 1
-  return 2
-}
-
-const COMPARISON_OPS = new Set(['=', '<>', '<', '<=', '>', '>='])
-
-/** AST 求值 */
-export function evaluateAst(node: AstNode, ctx: FormulaEvalContext): EvalValue {
-  switch (node.kind) {
-    case 'number':
-    case 'string':
-    case 'boolean':
-      return node.value
-    case 'name':
-      return formulaError('#NAME?')
-    case 'cell':
-      return ctx.readCell(node.sheet ?? ctx.currentSheet, node.addr)
-    case 'range':
-      return ctx.readRange(node.sheet ?? ctx.currentSheet, node.range)
-    case 'unary': {
-      const n = coerceToNumber(evaluateAst(node.operand, ctx))
-      if (isFormulaError(n)) return n
-      return node.op === '-' ? -n : n
-    }
-    case 'percent': {
-      const n = coerceToNumber(evaluateAst(node.operand, ctx))
-      if (isFormulaError(n)) return n
-      return n / 100
-    }
-    case 'binary':
-      return evaluateBinary(node.op, node.left, node.right, ctx)
-    case 'call':
-      return ctx.callFunction(node.name, node.args, (arg) => evaluateAst(arg, ctx))
-  }
-}
-
-function evaluateBinary(
-  op: BinaryOperator,
-  leftNode: AstNode,
-  rightNode: AstNode,
-  ctx: FormulaEvalContext
-): EvalValue {
-  const left = evaluateAst(leftNode, ctx)
-  if (isFormulaError(left)) return left
-  const right = evaluateAst(rightNode, ctx)
-  if (isFormulaError(right)) return right
-
-  if (op === '&') {
-    const l = coerceToText(left)
-    if (isFormulaError(l)) return l
-    const r = coerceToText(right)
-    if (isFormulaError(r)) return r
-    return l + r
-  }
-
-  if (COMPARISON_OPS.has(op)) {
-    if (Array.isArray(left) || Array.isArray(right)) return formulaError('#VALUE!')
-    const cmp = compareScalars(left, right)
-    switch (op) {
-      case '=':
-        return cmp === 0
-      case '<>':
-        return cmp !== 0
-      case '<':
-        return cmp < 0
-      case '<=':
-        return cmp <= 0
-      case '>':
-        return cmp > 0
-      default:
-        return cmp >= 0
-    }
-  }
-
-  const l = coerceToNumber(left)
-  if (isFormulaError(l)) return l
-  const r = coerceToNumber(right)
-  if (isFormulaError(r)) return r
-
-  switch (op) {
-    case '+':
-      return l + r
-    case '-':
-      return l - r
-    case '*':
-      return l * r
-    case '/':
-      if (r === 0) return formulaError('#DIV/0!')
-      return l / r
-    case '^': {
-      if (l === 0 && r < 0) return formulaError('#DIV/0!')
-      const value = Math.pow(l, r)
-      return Number.isFinite(value) ? value : formulaError('#VALUE!')
-    }
-    // & 与比较运算已在上方提前返回
-    default:
-      return formulaError('#ERROR!')
-  }
-}