@veltra/sheet 2.0.1 → 2.2.0

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

package/src/core/formula/tokenizer.ts

@@ -1,160 +0,0 @@
-/**
- * 公式分词器：数字 / 字符串 / 布尔 / 标识符（函数名、引用、表名）/ 带引号表名 / 运算符。
- *
- * 不做语义消歧：`A1`（引用）、`SUM`（函数名）、`Sheet2`（表名）统一产出 ident，
- * 由 parser 依据后随 token（`(` / `!` / `:` / 运算位）判定。
- */
-
-/** 解析失败异常（Sheet 层捕获 → 单元格记为 #ERROR!） */
-export class FormulaParseError extends Error {
-  constructor(message: string) {
-    super(message)
-    this.name = 'FormulaParseError'
-  }
-}
-
-export type FormulaOperator =
-  | '+'
-  | '-'
-  | '*'
-  | '/'
-  | '^'
-  | '&'
-  | '%'
-  | '('
-  | ')'
-  | ','
-  | '!'
-  | ':'
-  | '='
-  | '<>'
-  | '<'
-  | '<='
-  | '>'
-  | '>='
-
-export type FormulaToken =
-  | { type: 'number'; value: number }
-  | { type: 'string'; value: string }
-  /** 标识符：函数名 / 单元格引用形态 / 裸表名（含 $ 绝对引用写法）；TRUE/FALSE 由 parser 归约为布尔 */
-  | { type: 'ident'; name: string }
-  /** 带单引号的表名（'' 转义为字面单引号） */
-  | { type: 'quoted-name'; name: string }
-  | { type: 'op'; op: FormulaOperator }
-
-const NUMBER_RE = /^(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?/
-
-/** 标识符首字符：字母 / _ / $ / 非 ASCII（中文表名等） */
-function isIdentStart(ch: string): boolean {
-  return /[A-Za-z_$]/.test(ch) || ch.charCodeAt(0) >= 0x80
-}
-
-/** 标识符后续字符：首字符集 + 数字 + . */
-function isIdentPart(ch: string): boolean {
-  return /[A-Za-z0-9_.$]/.test(ch) || ch.charCodeAt(0) >= 0x80
-}
-
-const TWO_CHAR_OPS = ['<>', '<=', '>='] as const
-const ONE_CHAR_OPS = [
-  '+',
-  '-',
-  '*',
-  '/',
-  '^',
-  '&',
-  '%',
-  '(',
-  ')',
-  ',',
-  '!',
-  ':',
-  '=',
-  '<',
-  '>'
-] as const
-
-/** 公式文本（不含 '='）→ token 序列；非法输入抛 FormulaParseError */
-export function tokenizeFormula(text: string): FormulaToken[] {
-  const tokens: FormulaToken[] = []
-  let i = 0
-  while (i < text.length) {
-    const ch = text[i]!
-    // 空白忽略（不支持 Excel 的空格交集运算符）
-    if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
-      i++
-      continue
-    }
-    // 数字
-    if ((ch >= '0' && ch <= '9') || (ch === '.' && text[i + 1]! >= '0' && text[i + 1]! <= '9')) {
-      const match = NUMBER_RE.exec(text.slice(i))
-      if (!match) throw new FormulaParseError(`非法数字（位置 ${i + 1}）`)
-      tokens.push({ type: 'number', value: Number.parseFloat(match[0]) })
-      i += match[0].length
-      continue
-    }
-    // 字符串字面量（"..."，"" 转义）
-    if (ch === '"') {
-      let value = ''
-      let j = i + 1
-      for (;;) {
-        if (j >= text.length) throw new FormulaParseError('字符串缺少结束引号')
-        if (text[j] === '"') {
-          if (text[j + 1] === '"') {
-            value += '"'
-            j += 2
-            continue
-          }
-          break
-        }
-        value += text[j]
-        j++
-      }
-      tokens.push({ type: 'string', value })
-      i = j + 1
-      continue
-    }
-    // 带引号表名（'...'，'' 转义）
-    if (ch === "'") {
-      let name = ''
-      let j = i + 1
-      for (;;) {
-        if (j >= text.length) throw new FormulaParseError('表名缺少结束引号')
-        if (text[j] === "'") {
-          if (text[j + 1] === "'") {
-            name += "'"
-            j += 2
-            continue
-          }
-          break
-        }
-        name += text[j]
-        j++
-      }
-      tokens.push({ type: 'quoted-name', name })
-      i = j + 1
-      continue
-    }
-    // 标识符（函数名 / 引用 / 裸表名）
-    if (isIdentStart(ch)) {
-      let j = i + 1
-      while (j < text.length && isIdentPart(text[j]!)) j++
-      tokens.push({ type: 'ident', name: text.slice(i, j) })
-      i = j
-      continue
-    }
-    // 双字符运算符优先
-    const two = text.slice(i, i + 2)
-    if ((TWO_CHAR_OPS as readonly string[]).includes(two)) {
-      tokens.push({ type: 'op', op: two as FormulaOperator })
-      i += 2
-      continue
-    }
-    if ((ONE_CHAR_OPS as readonly string[]).includes(ch)) {
-      tokens.push({ type: 'op', op: ch as FormulaOperator })
-      i++
-      continue
-    }
-    throw new FormulaParseError(`无法识别的字符 "${ch}"（位置 ${i + 1}）`)
-  }
-  return tokens
-}