@veltra/sheet 2.0.0 → 2.1.1

package/src/core/command/set-cell-value.ts

@@ -1,38 +0,0 @@
-import type { CellAddress } from '../address'
-import { cellDataEqual, isEmptyCellData, type CellData } from '../cell-store'
-import type { CellPatch, Command, CommandResult } from './types'
-
-/** SetCellValueCommand 的批量写入项 */
-export interface SetCellValueItem {
-  addr: CellAddress
-  /** 目标数据；空数据（无公式且 v 为 null/undefined/''）= 清除 */
-  data?: CellData
-}
-
-export interface SetCellValueParams {
-  /** 批量写入（供粘贴/填充复用）；一次调用 = 一个 undo 单元 */
-  items: SetCellValueItem[]
-}
-
-/**
- * 单元格写入命令：逐项解析锚点、捕获 before/after 差量并立即应用。
- * 与 before 相等的项跳过（不产生补丁）；全部无变化时不入历史。
- */
-export const SetCellValueCommand: Command<SetCellValueParams> = {
-  id: 'sheet.command.set-cell-value',
-
-  handler(ctx, params): CommandResult {
-    const patches: CellPatch[] = []
-    for (const item of params.items) {
-      const anchor = ctx.sheet.merges.resolveAnchor(item.addr)
-      const before = ctx.sheet.store.getCell(anchor)
-      const after = isEmptyCellData(item.data) ? undefined : item.data
-      if (cellDataEqual(before, after)) continue
-      const patch: CellPatch = { kind: 'cell', addr: anchor, before, after }
-      ctx.applyPatch(patch, 'redo')
-      patches.push(patch)
-    }
-    if (patches.length === 0) return { mutations: [] }
-    return { mutations: [{ redo: patches, undo: [...patches].reverse() }] }
-  }
-}

package/src/core/command/types.ts

@@ -1,73 +0,0 @@
-import type { CellAddress, CellRange } from '../address'
-import type { CellData } from '../cell-store'
-import type { Sheet } from '../sheet'
-
-/**
- * 命令系统类型定义（决策 5：命令 + 逆操作补丁）。
- *
- * - 一切模型变更都是 Command，执行时产出 Mutation
- * - Patch 是受影响单元格 / 合并记录的 before/after 差量，不是全量快照
- * - 同一批 Patch 双向回放：redo 方向应用 after，undo 方向应用 before
- */
-
-/** 补丁回放方向 */
-export type PatchDirection = 'undo' | 'redo'
-
-/** 单元格数据差量补丁（原始存储语义；undefined = 该侧无此格） */
-export interface CellPatch {
-  kind: 'cell'
-  addr: CellAddress
-  /**
-   * 目标 sheet（跨表公式重算的派生补丁会落在其它 sheet 上）；
-   * 缺省 = 命令所在 sheet。回放时按此字段路由到目标 sheet 的变更通道。
-   */
-  sheet?: Sheet
-  /** 变更前的数据（undefined = 原本为空格） */
-  before?: CellData
-  /** 变更后的数据（undefined = 变更后为空格） */
-  after?: CellData
-}
-
-/** 合并记录差量补丁（before/after = 该侧是否存在此合并） */
-export interface MergePatch {
-  kind: 'merge'
-  range: CellRange
-  before: boolean
-  after: boolean
-}
-
-export type Patch = CellPatch | MergePatch
-
-/**
- * 一次命令执行产生的变更单元。
- * `redo` 按列表顺序应用；`undo` 取同一批补丁的逆序（命令实现负责构造，
- * 保证 undo 先撤销后登记的副作用，例如先移除新合并再恢复旧合并）。
- */
-export interface Mutation {
-  redo: Patch[]
-  undo: Patch[]
-}
-
-/** 命令执行结果 */
-export interface CommandResult<R = unknown> {
-  /** 产生的 mutation 列表（空数组 = 无实际变更，不入历史） */
-  mutations: Mutation[]
-  /** 命令附带返回值（如 MergeCellsCommand 返回最终生效区域） */
-  result?: R
-}
-
-/** 命令执行上下文 */
-export interface CommandContext {
-  sheet: Sheet
-  /**
-   * 应用单个补丁。命令 handler 执行时对 redo 补丁逐项调用；
-   * HistoryManager 回放 undo/redo 亦走此路径，保证只有一条变更通道。
-   */
-  applyPatch(patch: Patch, direction: PatchDirection): void
-}
-
-/** 命令：id + handler */
-export interface Command<P = unknown, R = unknown> {
-  readonly id: string
-  handler(ctx: CommandContext, params: P): CommandResult<R> | undefined
-}

package/src/core/events.ts

@@ -1,37 +0,0 @@
-/**
- * 包内轻量类型化事件发射器（core 内部基建，不对外导出实现细节）。
- */
-
-export type EventHandler<T> = (payload: T) => void
-
-export class TypedEventEmitter<EventMap extends Record<string, unknown>> {
-  private handlers = new Map<keyof EventMap, Set<EventHandler<EventMap[keyof EventMap]>>>()
-
-  /** 订阅事件，返回取消订阅函数 */
-  on<K extends keyof EventMap>(type: K, handler: EventHandler<EventMap[K]>): () => void {
-    let set = this.handlers.get(type)
-    if (!set) {
-      set = new Set()
-      this.handlers.set(type, set)
-    }
-    set.add(handler as EventHandler<EventMap[keyof EventMap]>)
-    return () => this.off(type, handler)
-  }
-
-  off<K extends keyof EventMap>(type: K, handler: EventHandler<EventMap[K]>): void {
-    this.handlers.get(type)?.delete(handler as EventHandler<EventMap[keyof EventMap]>)
-  }
-
-  emit<K extends keyof EventMap>(type: K, payload: EventMap[K]): void {
-    const set = this.handlers.get(type)
-    if (!set) return
-    // Set 迭代天然容忍遍历中取消订阅
-    for (const handler of set) {
-      ;(handler as EventHandler<EventMap[K]>)(payload)
-    }
-  }
-
-  clear(): void {
-    this.handlers.clear()
-  }
-}

package/src/core/formula/ast.ts

@@ -1,66 +0,0 @@
-import type { CellAddress, CellRange } from '../address'
-
-/**
- * 公式 AST 节点。
- * 引用节点携带可选 sheet 名（跨表引用）；缺省 = 公式所在 sheet。
- */
-
-export type BinaryOperator =
-  | '+'
-  | '-'
-  | '*'
-  | '/'
-  | '^'
-  | '&'
-  | '='
-  | '<>'
-  | '<'
-  | '<='
-  | '>'
-  | '>='
-
-export type AstNode =
-  | { kind: 'number'; value: number }
-  | { kind: 'string'; value: string }
-  | { kind: 'boolean'; value: boolean }
-  /** 未知名称（如裸写的 Sheet2 / 未定义命名）；求值为 #NAME? */
-  | { kind: 'name'; name: string }
-  | { kind: 'cell'; sheet?: string; addr: CellAddress }
-  | { kind: 'range'; sheet?: string; range: CellRange }
-  | { kind: 'unary'; op: '-' | '+'; operand: AstNode }
-  /** 百分号后缀运算（除以 100） */
-  | { kind: 'percent'; operand: AstNode }
-  | { kind: 'binary'; op: BinaryOperator; left: AstNode; right: AstNode }
-  | { kind: 'call'; name: string; args: AstNode[] }
-
-/** 公式中的引用（依赖图提取用）：sheet 缺省由所属公式节点补齐 */
-export interface AstReference {
-  sheet?: string
-  range: CellRange
-}
-
-/** 遍历 AST，收集全部引用（单格视为 1×1 区域） */
-export function collectReferences(node: AstNode, out: AstReference[] = []): AstReference[] {
-  switch (node.kind) {
-    case 'cell':
-      out.push({ sheet: node.sheet, range: { start: node.addr, end: node.addr } })
-      break
-    case 'range':
-      out.push({ sheet: node.sheet, range: node.range })
-      break
-    case 'unary':
-    case 'percent':
-      collectReferences(node.operand, out)
-      break
-    case 'binary':
-      collectReferences(node.left, out)
-      collectReferences(node.right, out)
-      break
-    case 'call':
-      for (const arg of node.args) collectReferences(arg, out)
-      break
-    default:
-      break
-  }
-  return out
-}

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)
-}