@veltra/sheet 2.0.0 → 2.1.1

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

package/src/core/formula/functions.ts

@@ -1,266 +0,0 @@
-import type { AstNode } from './ast'
-import { formulaError, isFormulaError, type FormulaError } from './errors'
-import {
-  coerceToBoolean,
-  coerceToNumber,
-  coerceToText,
-  type EvalValue,
-  type ScalarValue
-} from './evaluator'
-
-/**
- * 函数注册表（可扩展）+ 基础函数集。
- *
- * 参数形态约定：区域引用求值为数组（只含稀疏存在的格），直接参数为标量。
- * 聚合函数据此区分 Excel 语义：区域内的文本/布尔被忽略，直接参数则强转（非法 → #VALUE!）。
- * lazy 函数自行求值参数（IF 的短路分支，未选分支的副作用/错误不产生）。
- */
-
-export type FormulaFunction =
-  | { kind?: 'normal'; minArgs?: number; maxArgs?: number; impl: (args: EvalValue[]) => EvalValue }
-  | {
-      kind: 'lazy'
-      minArgs?: number
-      maxArgs?: number
-      impl: (nodes: AstNode[], evalNode: (node: AstNode) => EvalValue) => EvalValue
-    }
-
-const registry = new Map<string, FormulaFunction>()
-
-/** 注册函数（名称大小写不敏感；同名覆盖，供扩展/自定义函数） */
-export function registerFormulaFunction(name: string, def: FormulaFunction): void {
-  registry.set(name.toUpperCase(), def)
-}
-
-/** 查询函数（大小写不敏感） */
-export function getFormulaFunction(name: string): FormulaFunction | undefined {
-  return registry.get(name.toUpperCase())
-}
-
-/** 求值器回调：名称解析 + 参数个数校验 + 按 kind 分发 */
-export function invokeFormulaFunction(
-  name: string,
-  nodes: AstNode[],
-  evalNode: (node: AstNode) => EvalValue
-): EvalValue {
-  const def = getFormulaFunction(name)
-  if (!def) return formulaError('#NAME?')
-  if (def.minArgs !== undefined && nodes.length < def.minArgs) return formulaError('#VALUE!')
-  if (def.maxArgs !== undefined && nodes.length > def.maxArgs) return formulaError('#VALUE!')
-  if (def.kind === 'lazy') return def.impl(nodes, evalNode)
-  return def.impl(nodes.map(evalNode))
-}
-
-// ─── 内部工具 ────────────────────────────────────────────────
-
-interface FlatArg {
-  value: ScalarValue | FormulaError
-  /** 来自区域展开（区别于直接参数：区域内文本/布尔被聚合函数忽略） */
-  fromRange: boolean
-}
-
-function flattenArgs(args: EvalValue[]): FlatArg[] {
-  const out: FlatArg[] = []
-  for (const arg of args) {
-    if (Array.isArray(arg)) {
-      for (const value of arg) out.push({ value, fromRange: true })
-    } else {
-      out.push({ value: arg, fromRange: false })
-    }
-  }
-  return out
-}
-
-/** 收集数字：区域内只取数字格；直接参数强转（非法/错误 → 传播） */
-function collectNumbers(args: EvalValue[]): number[] | FormulaError {
-  const numbers: number[] = []
-  for (const { value, fromRange } of flattenArgs(args)) {
-    if (isFormulaError(value)) return value
-    if (fromRange) {
-      if (typeof value === 'number') numbers.push(value)
-      continue
-    }
-    const n = coerceToNumber(value)
-    if (isFormulaError(n)) return n
-    numbers.push(n)
-  }
-  return numbers
-}
-
-/** 收集布尔：区域内只取布尔格；直接参数强转（非法文本/错误 → 传播）；空值跳过 */
-function collectBooleans(args: EvalValue[]): boolean[] | FormulaError {
-  const booleans: boolean[] = []
-  for (const { value, fromRange } of flattenArgs(args)) {
-    if (isFormulaError(value)) return value
-    if (fromRange) {
-      if (typeof value === 'boolean') booleans.push(value)
-      continue
-    }
-    if (value === null) continue
-    const b = coerceToBoolean(value)
-    if (isFormulaError(b)) return b
-    booleans.push(b)
-  }
-  return booleans
-}
-
-// ─── 基础函数集 ─────────────────────────────────────────────
-
-registerFormulaFunction('SUM', {
-  minArgs: 1,
-  impl(args) {
-    const numbers = collectNumbers(args)
-    if (isFormulaError(numbers)) return numbers
-    let sum = 0
-    for (const n of numbers) sum += n
-    return sum
-  }
-})
-
-registerFormulaFunction('AVERAGE', {
-  minArgs: 1,
-  impl(args) {
-    const numbers = collectNumbers(args)
-    if (isFormulaError(numbers)) return numbers
-    if (numbers.length === 0) return formulaError('#DIV/0!')
-    let sum = 0
-    for (const n of numbers) sum += n
-    return sum / numbers.length
-  }
-})
-
-registerFormulaFunction('MAX', {
-  minArgs: 1,
-  impl(args) {
-    const numbers = collectNumbers(args)
-    if (isFormulaError(numbers)) return numbers
-    return numbers.length === 0 ? 0 : Math.max(...numbers)
-  }
-})
-
-registerFormulaFunction('MIN', {
-  minArgs: 1,
-  impl(args) {
-    const numbers = collectNumbers(args)
-    if (isFormulaError(numbers)) return numbers
-    return numbers.length === 0 ? 0 : Math.min(...numbers)
-  }
-})
-
-registerFormulaFunction('COUNT', {
-  minArgs: 1,
-  impl(args) {
-    let count = 0
-    for (const { value, fromRange } of flattenArgs(args)) {
-      if (isFormulaError(value)) return value
-      if (fromRange) {
-        if (typeof value === 'number') count++
-        continue
-      }
-      // 直接参数：可强转为数字即计数（含 TRUE/FALSE、数字文本）
-      if (!isFormulaError(coerceToNumber(value))) count++
-    }
-    return count
-  }
-})
-
-registerFormulaFunction('COUNTA', {
-  minArgs: 1,
-  impl(args) {
-    let count = 0
-    for (const { value, fromRange } of flattenArgs(args)) {
-      // 直接错误参数传播；区域内的错误格照常计数
-      if (!fromRange && isFormulaError(value)) return value
-      if (value === null) continue
-      count++
-    }
-    return count
-  }
-})
-
-registerFormulaFunction('IF', {
-  kind: 'lazy',
-  minArgs: 2,
-  maxArgs: 3,
-  impl(nodes, evalNode) {
-    const cond = coerceToBoolean(evalNode(nodes[0]!))
-    if (isFormulaError(cond)) return cond
-    if (cond) return evalNode(nodes[1]!)
-    return nodes[2] ? evalNode(nodes[2]) : false
-  }
-})
-
-registerFormulaFunction('AND', {
-  minArgs: 1,
-  impl(args) {
-    const booleans = collectBooleans(args)
-    if (isFormulaError(booleans)) return booleans
-    if (booleans.length === 0) return formulaError('#VALUE!')
-    return booleans.every(Boolean)
-  }
-})
-
-registerFormulaFunction('OR', {
-  minArgs: 1,
-  impl(args) {
-    const booleans = collectBooleans(args)
-    if (isFormulaError(booleans)) return booleans
-    if (booleans.length === 0) return formulaError('#VALUE!')
-    return booleans.some(Boolean)
-  }
-})
-
-registerFormulaFunction('NOT', {
-  minArgs: 1,
-  maxArgs: 1,
-  impl(args) {
-    const b = coerceToBoolean(args[0]!)
-    if (isFormulaError(b)) return b
-    return !b
-  }
-})
-
-registerFormulaFunction('ROUND', {
-  minArgs: 2,
-  maxArgs: 2,
-  impl(args) {
-    const n = coerceToNumber(args[0]!)
-    if (isFormulaError(n)) return n
-    const d = coerceToNumber(args[1]!)
-    if (isFormulaError(d)) return d
-    const factor = 10 ** Math.trunc(d)
-    // 位数超出 double 精度时四舍五入是恒等/归零
-    if (!Number.isFinite(factor)) return n
-    if (factor === 0) return 0
-    // 远离零方向取整；1e-12 补偿浮点表示误差（如 2.675 存为 2.67499…）
-    const shifted = n * factor
-    const rounded = Math.sign(shifted) * Math.round(Math.abs(shifted) + 1e-12)
-    return rounded / factor
-  }
-})
-
-registerFormulaFunction('ABS', {
-  minArgs: 1,
-  maxArgs: 1,
-  impl(args) {
-    const n = coerceToNumber(args[0]!)
-    if (isFormulaError(n)) return n
-    return Math.abs(n)
-  }
-})
-
-registerFormulaFunction('CONCATENATE', {
-  minArgs: 1,
-  impl(args) {
-    let text = ''
-    for (const arg of args) {
-      const values = Array.isArray(arg) ? arg : [arg]
-      for (const value of values) {
-        const piece = coerceToText(value)
-        if (isFormulaError(piece)) return piece
-        text += piece
-      }
-    }
-    return text
-  }
-})

package/src/core/formula/index.ts

@@ -1,7 +0,0 @@
-export * from './errors'
-export * from './ast'
-export * from './tokenizer'
-export * from './parser'
-export * from './evaluator'
-export * from './functions'
-export * from './dependency-graph'

package/src/core/formula/parser.ts

@@ -1,198 +0,0 @@
-import { createRange, parseAddress, type CellAddress } from '../address'
-import type { AstNode, BinaryOperator } from './ast'
-import { FormulaParseError, tokenizeFormula, type FormulaToken } from './tokenizer'
-
-/**
- * Pratt parser：token 序列 → AST。
- *
- * 优先级（同 Excel，低到高）：比较运算 < `&` < `+ -` < `* /` < 一元 `+ -` < `^`（右结合）< `%`。
- * 一元运算紧于幂次是 Excel 的特有行为：-2^2 = (-2)^2 = 4。
- * 引用消歧：ident 后随 `(` → 函数调用；后随 `!` → 表名前缀；匹配单元格形态 → 引用；
- * TRUE/FALSE → 布尔字面量；其余 → 未知名称节点（求值 #NAME?）。
- */
-
-/** 中缀运算符绑定力 [左, 右]；右结合运算符右绑定力 = 左 - 1 */
-const INFIX_BP: Record<string, readonly [number, number]> = {
-  '=': [1, 1],
-  '<>': [1, 1],
-  '<': [1, 1],
-  '<=': [1, 1],
-  '>': [1, 1],
-  '>=': [1, 1],
-  '&': [2, 2],
-  '+': [3, 3],
-  '-': [3, 3],
-  '*': [4, 4],
-  '/': [4, 4],
-  '^': [6, 5]
-}
-/** 百分号后缀绑定力（最高） */
-const PERCENT_BP = 7
-/** 一元 +/- 操作数的绑定力：紧于 ^（6），松于 %（7） */
-const UNARY_OPERAND_BP = 6
-
-/** 单元格引用形态（列限 3 字母；超出按未知名称处理，如 Sheet2） */
-const CELL_REF_RE = /^\$?[A-Za-z]{1,3}\$?[1-9]\d*$/
-
-class Parser {
-  private pos = 0
-
-  constructor(private readonly tokens: FormulaToken[]) {}
-
-  parse(): AstNode {
-    const node = this.parseExpression(0)
-    if (this.pos < this.tokens.length) {
-      throw new FormulaParseError(`意外的多余输入: ${describeToken(this.tokens[this.pos]!)}`)
-    }
-    return node
-  }
-
-  private peek(): FormulaToken | undefined {
-    return this.tokens[this.pos]
-  }
-
-  private next(): FormulaToken | undefined {
-    return this.tokens[this.pos++]
-  }
-
-  private peekOp(op: string): boolean {
-    const token = this.peek()
-    return token?.type === 'op' && token.op === op
-  }
-
-  private expectOp(op: string): void {
-    if (!this.peekOp(op)) {
-      throw new FormulaParseError(`期望 "${op}"，得到 ${describeToken(this.peek())}`)
-    }
-    this.pos++
-  }
-
-  private parseExpression(minBp: number): AstNode {
-    let left = this.parsePrimary()
-    for (;;) {
-      const token = this.peek()
-      if (token?.type !== 'op') break
-      // 百分号后缀
-      if (token.op === '%') {
-        if (PERCENT_BP <= minBp) break
-        this.pos++
-        left = { kind: 'percent', operand: left }
-        continue
-      }
-      const bp = INFIX_BP[token.op]
-      if (!bp || bp[0] <= minBp) break
-      this.pos++
-      const right = this.parseExpression(bp[1])
-      left = { kind: 'binary', op: token.op as BinaryOperator, left, right }
-    }
-    return left
-  }
-
-  private parsePrimary(): AstNode {
-    const token = this.next()
-    if (!token) throw new FormulaParseError('表达式不完整')
-
-    if (token.type === 'number') return { kind: 'number', value: token.value }
-    if (token.type === 'string') return { kind: 'string', value: token.value }
-
-    if (token.type === 'quoted-name') {
-      // 带引号表名只能作为跨表引用前缀
-      this.expectOp('!')
-      return this.parseCellRefOrRange(token.name)
-    }
-
-    if (token.type === 'ident') {
-      const name = token.name
-      if (this.peekOp('(')) return this.parseCall(name)
-      if (this.peekOp('!')) {
-        this.pos++
-        return this.parseCellRefOrRange(name)
-      }
-      const addr = parseCellRef(name)
-      if (addr) return this.parseRangeTail({ sheet: undefined, addr })
-      if (name.toUpperCase() === 'TRUE') return { kind: 'boolean', value: true }
-      if (name.toUpperCase() === 'FALSE') return { kind: 'boolean', value: false }
-      return { kind: 'name', name }
-    }
-
-    // 运算符位置：括号 / 一元 +-
-    if (token.type === 'op') {
-      if (token.op === '(') {
-        const inner = this.parseExpression(0)
-        this.expectOp(')')
-        return inner
-      }
-      if (token.op === '-' || token.op === '+') {
-        return { kind: 'unary', op: token.op, operand: this.parseExpression(UNARY_OPERAND_BP) }
-      }
-    }
-    throw new FormulaParseError(`意外的 ${describeToken(token)}`)
-  }
-
-  /** 函数调用：ident 已消费，当前 token 为 '(' */
-  private parseCall(name: string): AstNode {
-    this.pos++ // 消费 '('
-    const args: AstNode[] = []
-    if (!this.peekOp(')')) {
-      for (;;) {
-        args.push(this.parseExpression(0))
-        if (this.peekOp(',')) {
-          this.pos++
-          continue
-        }
-        break
-      }
-    }
-    this.expectOp(')')
-    return { kind: 'call', name, args }
-  }
-
-  /** 表名前缀（Sheet2! / 'My Sheet'!）之后的单元格或区域引用 */
-  private parseCellRefOrRange(sheet: string): AstNode {
-    const token = this.next()
-    const addr = token?.type === 'ident' ? parseCellRef(token.name) : null
-    if (!addr) {
-      throw new FormulaParseError(`表名 "${sheet}" 后应为单元格引用，得到 ${describeToken(token)}`)
-    }
-    return this.parseRangeTail({ sheet, addr })
-  }
-
-  /** 单元格引用之后的可选区域后缀（:B9） */
-  private parseRangeTail(ref: { sheet: string | undefined; addr: CellAddress }): AstNode {
-    if (!this.peekOp(':')) return { kind: 'cell', sheet: ref.sheet, addr: ref.addr }
-    this.pos++
-    const token = this.next()
-    const end = token?.type === 'ident' ? parseCellRef(token.name) : null
-    if (!end) {
-      throw new FormulaParseError(`区域 ":" 后应为单元格引用，得到 ${describeToken(token)}`)
-    }
-    return { kind: 'range', sheet: ref.sheet, range: createRange(ref.addr, end) }
-  }
-}
-
-/** 按单元格引用形态解析（列限 3 字母）；不匹配返回 null */
-function parseCellRef(name: string): CellAddress | null {
-  if (!CELL_REF_RE.test(name)) return null
-  return parseAddress(name)
-}
-
-function describeToken(token: FormulaToken | undefined): string {
-  if (!token) return '输入末尾'
-  switch (token.type) {
-    case 'number':
-      return `数字 ${token.value}`
-    case 'string':
-      return `字符串 "${token.value}"`
-    case 'ident':
-      return `名称 "${token.name}"`
-    case 'quoted-name':
-      return `表名 '${token.name}'`
-    case 'op':
-      return `"${token.op}"`
-  }
-}
-
-/** 解析公式文本（不含 '='）→ AST；非法输入抛 FormulaParseError */
-export function parseFormula(text: string): AstNode {
-  return new Parser(tokenizeFormula(text)).parse()
-}