@sixb/core 0.1.20 → 0.1.22

package/src/artifacts/formula/check.ts

@@ -0,0 +1,171 @@
+import type { FormulaNode } from "./parser"
+
+/**
+ * What a formula yields, as far as its operands say: a date is a number of days that reads as a
+ * date, and `any` is a value whose kind depends on the row, such as an IF's two kinds of branch.
+ */
+export type FormulaType = "number" | "date" | "text" | "boolean" | "any"
+
+/** Every function a formula may call, with how many arguments it takes. */
+export const FORMULA_FUNCTIONS: Readonly<
+  Record<string, { readonly min: number; readonly max: number }>
+> = {
+  IF: { min: 2, max: 3 },
+  IFERROR: { min: 2, max: 2 },
+  AND: { min: 1, max: 30 },
+  OR: { min: 1, max: 30 },
+  NOT: { min: 1, max: 1 },
+  ISBLANK: { min: 1, max: 1 },
+  ROUND: { min: 2, max: 2 },
+  ABS: { min: 1, max: 1 },
+  MIN: { min: 1, max: 30 },
+  MAX: { min: 1, max: 30 },
+  SUM: { min: 1, max: 30 },
+  AVERAGE: { min: 1, max: 30 },
+  COUNT: { min: 1, max: 30 },
+  LEN: { min: 1, max: 1 },
+  LOWER: { min: 1, max: 1 },
+  UPPER: { min: 1, max: 1 },
+  CONCAT: { min: 1, max: 30 },
+  YEAR: { min: 1, max: 1 },
+  MONTH: { min: 1, max: 1 },
+  DAYS: { min: 2, max: 2 },
+}
+
+/** The functions that read a whole column, `[Name]`, and reduce it to one value. */
+export const AGGREGATE_FUNCTIONS: ReadonlySet<string> = new Set([
+  "SUM",
+  "AVERAGE",
+  "MIN",
+  "MAX",
+  "COUNT",
+])
+
+/**
+ * Checks a formula against the columns its sheet has, each by what its values are: what it yields,
+ * or what is wrong with it, in words an author can act on. Text where a number is needed is
+ * refused here rather than computed to `#VALUE!` in every row.
+ */
+export function checkFormula(
+  node: FormulaNode,
+  columns: ReadonlyMap<string, FormulaType>
+): { readonly type: FormulaType } | { readonly error: string } {
+  try {
+    return { type: typeOf(node, columns, false) }
+  } catch (error) {
+    if (error instanceof FormulaCheckError) return { error: error.message }
+    throw error
+  }
+}
+
+class FormulaCheckError extends Error {}
+
+const numeric = (type: FormulaType) => type !== "text"
+
+function typeOf(
+  node: FormulaNode,
+  columns: ReadonlyMap<string, FormulaType>,
+  inAggregate: boolean
+): FormulaType {
+  switch (node.kind) {
+    case "number":
+      return "number"
+    case "text":
+      return "text"
+    case "boolean":
+      return "boolean"
+    case "ref":
+    case "columnRef": {
+      const type = columns.get(node.column)
+      if (type === undefined) {
+        throw new FormulaCheckError(
+          `it reads column '${node.column}', which the sheet does not have`
+        )
+      }
+      if (node.kind === "columnRef" && !inAggregate) {
+        throw new FormulaCheckError(
+          `[${node.column}] is the whole column, which only ${[...AGGREGATE_FUNCTIONS].join(", ")} take; this row's value is [@${node.column}]`
+        )
+      }
+      return type
+    }
+    case "unary": {
+      const type = typeOf(node.operand, columns, false)
+      if (!numeric(type)) throw new FormulaCheckError(`'${node.op}' needs a number, not text`)
+      return "number"
+    }
+    case "binary": {
+      const left = typeOf(node.left, columns, false)
+      const right = typeOf(node.right, columns, false)
+      switch (node.op) {
+        case "&":
+          return "text"
+        case "=":
+        case "<>":
+        case "<":
+        case "<=":
+        case ">":
+        case ">=":
+          return "boolean"
+        default: {
+          if (!numeric(left) || !numeric(right)) {
+            throw new FormulaCheckError(`'${node.op}' needs numbers on both sides, not text`)
+          }
+          // A date and a number of days make a date; two dates make the days between them.
+          if (node.op === "+" && (left === "date") !== (right === "date")) return "date"
+          if (node.op === "-" && left === "date" && right !== "date") return "date"
+          return "number"
+        }
+      }
+    }
+    case "call": {
+      const shape = FORMULA_FUNCTIONS[node.name]
+      if (!shape) {
+        throw new FormulaCheckError(
+          `${node.name} is not a function a sheet computes; use one of ${Object.keys(FORMULA_FUNCTIONS).join(", ")}`
+        )
+      }
+      if (node.args.length < shape.min || node.args.length > shape.max) {
+        const count =
+          shape.min === shape.max
+            ? `${shape.min}`
+            : shape.max === 30
+              ? `at least ${shape.min}`
+              : `${shape.min} or ${shape.max}`
+        throw new FormulaCheckError(
+          `${node.name} takes ${count} ${shape.max === 1 ? "argument" : "arguments"}, not ${node.args.length}`
+        )
+      }
+      const aggregate = AGGREGATE_FUNCTIONS.has(node.name)
+      const args = node.args.map((arg) => typeOf(arg, columns, aggregate))
+      switch (node.name) {
+        case "IF": {
+          const [, then = "boolean", otherwise = "boolean"] = args
+          return then === otherwise ? then : "any"
+        }
+        case "IFERROR": {
+          const [value = "any", fallback = "any"] = args
+          return value === fallback ? value : "any"
+        }
+        case "AND":
+        case "OR":
+        case "NOT":
+        case "ISBLANK":
+          return "boolean"
+        case "LOWER":
+        case "UPPER":
+        case "CONCAT":
+          return "text"
+        default:
+          for (const [index, type] of args.entries()) {
+            if (node.name !== "LEN" && !aggregate && !numeric(type)) {
+              throw new FormulaCheckError(
+                `${node.name}'s argument ${index + 1} needs a number, not text`
+              )
+            }
+          }
+          return "number"
+      }
+    }
+  }
+}

package/src/artifacts/formula/evaluate.ts

@@ -0,0 +1,288 @@
+import { AGGREGATE_FUNCTIONS } from "./check"
+import type { FormulaNode } from "./parser"
+
+/** What a cell computes to when it can't: a division by zero, or a value of the wrong kind. */
+export const FORMULA_ERRORS = ["#DIV/0!", "#VALUE!"] as const
+export type FormulaErrorCode = (typeof FORMULA_ERRORS)[number]
+
+/**
+ * A value as a formula sees it: a number (a date is its day count, as in Excel), text, a boolean,
+ * a blank, or an error that passes through everything but IFERROR.
+ */
+export type FormulaValue = number | string | boolean | null | { readonly error: FormulaErrorCode }
+
+/** The values a formula reads: this row's in a column, or a whole column's. */
+export interface FormulaScope {
+  readonly cell: (column: string) => FormulaValue
+  readonly column: (column: string) => readonly FormulaValue[]
+}
+
+const isError = (value: FormulaValue): value is { readonly error: FormulaErrorCode } =>
+  typeof value === "object" && value !== null
+const fault = (error: FormulaErrorCode) => ({ error }) as const
+
+/**
+ * Evaluates a formula for one row, with Excel's rules: a blank reads as 0 in arithmetic and as
+ * empty text in `&`; booleans count as 1 and 0; text that reads as a number is one; text compares
+ * without regard to case, and number < text < boolean across kinds. An aggregate over whole
+ * columns is the same for every row, so `memo` keeps it once computed.
+ */
+export function evaluateFormula(
+  node: FormulaNode,
+  scope: FormulaScope,
+  memo: Map<FormulaNode, FormulaValue> = new Map()
+): FormulaValue {
+  const value = (current: FormulaNode): FormulaValue => {
+    switch (current.kind) {
+      case "number":
+      case "text":
+      case "boolean":
+        return current.value
+      case "ref":
+        return scope.cell(current.column)
+      case "columnRef":
+        // The checker allows a whole column only inside an aggregate, which reads it itself.
+        return fault("#VALUE!")
+      case "unary": {
+        const operand = number(value(current.operand))
+        if (isError(operand)) return operand
+        return current.op === "-" ? -operand : operand
+      }
+      case "binary":
+        return binary(current.op, value(current.left), value(current.right))
+      case "call": {
+        const constant = AGGREGATE_FUNCTIONS.has(current.name) && current.args.every(isConstant)
+        if (constant && memo.has(current)) return memo.get(current) as FormulaValue
+        const result = call(current.name, current.args, value, scope)
+        if (constant) memo.set(current, result)
+        return result
+      }
+    }
+  }
+  return value(node)
+}
+
+/** A literal, or a whole column: the same in every row. */
+function isConstant(node: FormulaNode): boolean {
+  return node.kind === "columnRef" || node.kind === "number" || node.kind === "text"
+}
+
+function number(value: FormulaValue): number | { readonly error: FormulaErrorCode } {
+  if (isError(value)) return value
+  if (value === null) return 0
+  if (typeof value === "boolean") return value ? 1 : 0
+  if (typeof value === "number") return value
+  const trimmed = value.trim()
+  const parsed = trimmed ? Number(trimmed) : Number.NaN
+  return /^[-+]?(\d+\.?\d*|\.\d+)(e[-+]?\d+)?$/i.test(trimmed) && Number.isFinite(parsed)
+    ? parsed
+    : fault("#VALUE!")
+}
+
+/** A value as text: a number as Excel's General format writes it, a boolean as TRUE or FALSE. */
+export function formulaText(value: Exclude<FormulaValue, { error: unknown }>): string {
+  if (value === null) return ""
+  if (typeof value === "boolean") return value ? "TRUE" : "FALSE"
+  if (typeof value === "number") return String(Number(value.toPrecision(15)))
+  return value
+}
+
+function truth(value: FormulaValue): boolean | { readonly error: FormulaErrorCode } {
+  if (isError(value)) return value
+  if (value === null) return false
+  if (typeof value === "boolean") return value
+  if (typeof value === "number") return value !== 0
+  const word = value.trim().toUpperCase()
+  return word === "TRUE" ? true : word === "FALSE" ? false : fault("#VALUE!")
+}
+
+const finite = (result: number) => (Number.isFinite(result) ? result : fault("#VALUE!"))
+
+function binary(
+  op: Extract<FormulaNode, { kind: "binary" }>["op"],
+  left: FormulaValue,
+  right: FormulaValue
+): FormulaValue {
+  if (isError(left)) return left
+  if (isError(right)) return right
+  if (op === "&") return formulaText(left) + formulaText(right)
+  if (op === "=" || op === "<>" || op === "<" || op === "<=" || op === ">" || op === ">=") {
+    const order = compare(left, right)
+    return {
+      "=": order === 0,
+      "<>": order !== 0,
+      "<": order < 0,
+      "<=": order <= 0,
+      ">": order > 0,
+      ">=": order >= 0,
+    }[op]
+  }
+  const a = number(left)
+  const b = number(right)
+  if (isError(a)) return a
+  if (isError(b)) return b
+  switch (op) {
+    case "+":
+      return finite(a + b)
+    case "-":
+      return finite(a - b)
+    case "*":
+      return finite(a * b)
+    case "/":
+      return b === 0 ? fault("#DIV/0!") : finite(a / b)
+    case "^":
+      return a === 0 && b < 0 ? fault("#DIV/0!") : finite(a ** b)
+  }
+}
+
+/** Excel's order: a blank takes the other side's kind, then number < text < boolean. */
+function compare(
+  left: Exclude<FormulaValue, { error: unknown }>,
+  right: Exclude<FormulaValue, { error: unknown }>
+): number {
+  const blank = (other: typeof left) =>
+    typeof other === "number" ? 0 : typeof other === "boolean" ? false : ""
+  const a = left === null ? blank(right) : left
+  const b = right === null ? blank(left) : right
+  const rank = (value: typeof a) =>
+    typeof value === "number" ? 0 : typeof value === "string" ? 1 : 2
+  if (rank(a) !== rank(b)) return rank(a) - rank(b)
+  if (typeof a === "string" && typeof b === "string") {
+    const x = a.toLowerCase()
+    const y = b.toLowerCase()
+    return x < y ? -1 : x > y ? 1 : 0
+  }
+  return Number(a) - Number(b)
+}
+
+/** Days from Excel's day zero, 1899-12-30, to 1970-01-01. */
+const EPOCH_SERIAL = 25569
+const DAY_MS = 86_400_000
+
+/** A date as Excel's day count. */
+export function dateSerial(date: Date): number {
+  return date.getTime() / DAY_MS + EPOCH_SERIAL
+}
+
+/** A day count as the date it is: `2026-09-30`, or with its time when it has one. */
+export function serialDate(serial: number): string {
+  const date = new Date(Math.round((serial - EPOCH_SERIAL) * DAY_MS))
+  const iso = date.toISOString()
+  return Number.isInteger(serial) ? iso.slice(0, 10) : `${iso.slice(0, 19)}Z`
+}
+
+function call(
+  name: string,
+  args: readonly FormulaNode[],
+  value: (node: FormulaNode) => FormulaValue,
+  scope: FormulaScope
+): FormulaValue {
+  const at = (index: number) => value(args[index] as FormulaNode)
+  switch (name) {
+    case "IF": {
+      const condition = truth(at(0))
+      if (isError(condition)) return condition
+      if (condition) return at(1)
+      return args.length > 2 ? at(2) : false
+    }
+    case "IFERROR": {
+      const result = at(0)
+      return isError(result) ? at(1) : result
+    }
+    case "AND":
+    case "OR": {
+      const values = args.map((_, index) => at(index)).filter((entry) => entry !== null)
+      if (values.length === 0) return fault("#VALUE!")
+      let result = name === "AND"
+      for (const entry of values) {
+        const flag = truth(entry)
+        if (isError(flag)) return flag
+        result = name === "AND" ? result && flag : result || flag
+      }
+      return result
+    }
+    case "NOT": {
+      const flag = truth(at(0))
+      return isError(flag) ? flag : !flag
+    }
+    case "ISBLANK":
+      return at(0) === null
+    case "ROUND": {
+      const x = number(at(0))
+      const digits = number(at(1))
+      if (isError(x)) return x
+      if (isError(digits)) return digits
+      // Half away from zero, as Excel rounds, past the float error of the scaled value.
+      const scale = 10 ** Math.trunc(digits)
+      return (Math.sign(x) * Math.round(Number((Math.abs(x) * scale).toPrecision(15)))) / scale
+    }
+    case "ABS": {
+      const x = number(at(0))
+      return isError(x) ? x : Math.abs(x)
+    }
+    case "LEN":
+    case "LOWER":
+    case "UPPER": {
+      const text = at(0)
+      if (isError(text)) return text
+      const written = formulaText(text)
+      return name === "LEN"
+        ? written.length
+        : name === "LOWER"
+          ? written.toLowerCase()
+          : written.toUpperCase()
+    }
+    case "CONCAT": {
+      let text = ""
+      for (const index of args.keys()) {
+        const part = at(index)
+        if (isError(part)) return part
+        text += formulaText(part)
+      }
+      return text
+    }
+    case "YEAR":
+    case "MONTH": {
+      const serial = number(at(0))
+      if (isError(serial)) return serial
+      if (serial < 0) return fault("#VALUE!")
+      const date = new Date((Math.floor(serial) - EPOCH_SERIAL) * DAY_MS)
+      return name === "YEAR" ? date.getUTCFullYear() : date.getUTCMonth() + 1
+    }
+    case "DAYS": {
+      const end = number(at(0))
+      const start = number(at(1))
+      if (isError(end)) return end
+      if (isError(start)) return start
+      return Math.floor(end) - Math.floor(start)
+    }
+    default: {
+      // SUM, AVERAGE, MIN, MAX, COUNT: the numbers among their arguments, whole columns included;
+      // text, booleans, and blanks are passed over, as a range's are in Excel.
+      const numbers: number[] = []
+      for (const [index, arg] of args.entries()) {
+        const values = arg.kind === "columnRef" ? scope.column(arg.column) : [at(index)]
+        for (const entry of values) {
+          if (isError(entry)) return entry
+          if (typeof entry === "number") numbers.push(entry)
+        }
+      }
+      switch (name) {
+        case "COUNT":
+          return numbers.length
+        case "SUM":
+          return numbers.reduce((sum, entry) => sum + entry, 0)
+        case "AVERAGE":
+          return numbers.length === 0
+            ? fault("#DIV/0!")
+            : numbers.reduce((sum, entry) => sum + entry, 0) / numbers.length
+        case "MIN":
+          return numbers.length === 0 ? 0 : numbers.reduce((min, entry) => Math.min(min, entry))
+        case "MAX":
+          return numbers.length === 0 ? 0 : numbers.reduce((max, entry) => Math.max(max, entry))
+        default:
+          return fault("#VALUE!")
+      }
+    }
+  }
+}

package/src/artifacts/formula/index.ts

@@ -0,0 +1,199 @@
+import type { CsvTable } from "../csv"
+import {
+  NUMERIC_COLUMN_TYPES,
+  parseSheetDate,
+  parseSheetNumber,
+  type SheetColumnType,
+  type WorkbookSheet,
+} from "../workbook"
+import type { FormulaType } from "./check"
+import {
+  dateSerial,
+  evaluateFormula,
+  type FormulaErrorCode,
+  type FormulaValue,
+  formulaText,
+  serialDate,
+} from "./evaluate"
+import { type FormulaNode, formulaDependencies, parseFormula } from "./parser"
+
+export {
+  AGGREGATE_FUNCTIONS,
+  checkFormula,
+  FORMULA_FUNCTIONS,
+  type FormulaType,
+} from "./check"
+export {
+  FORMULA_ERRORS,
+  type FormulaErrorCode,
+  type FormulaValue,
+} from "./evaluate"
+export {
+  type FormulaNode,
+  type FormulaOperator,
+  FormulaSyntaxError,
+  formulaDependencies,
+  formulaReferences,
+  parseFormula,
+  renameColumnReferences,
+} from "./parser"
+
+/** What a column's values are, as a formula reads them. */
+export function columnFormulaType(type: SheetColumnType): FormulaType {
+  if (NUMERIC_COLUMN_TYPES.includes(type)) return "number"
+  if (type === "date" || type === "boolean") return type
+  return "text"
+}
+
+/**
+ * Whether what a formula yields can fill a column of a type: numbers in a number, currency, or
+ * percent column, dates in a date column, booleans in a boolean one, anything in text or a tag.
+ * A value whose kind depends on the row fits anywhere, and is `#VALUE!` where it doesn't.
+ */
+export function formulaFitsColumn(result: FormulaType, type: SheetColumnType): boolean {
+  if (result === "any" || type === "text" || type === "tag") return true
+  if (NUMERIC_COLUMN_TYPES.includes(type)) return result === "number"
+  if (type === "date") return result === "date"
+  if (type === "boolean") return result === "boolean"
+  return false
+}
+
+/** Computed columns that read each other in a ring, so none can be computed first. */
+export class FormulaCycleError extends Error {
+  constructor(readonly columns: readonly string[]) {
+    super(`columns ${columns.map((column) => `'${column}'`).join(" → ")} compute from each other`)
+    this.name = "FormulaCycleError"
+  }
+}
+
+/** Where a computed column computes to an error: how many rows, and the first. */
+export interface ComputedColumnErrors {
+  readonly count: number
+  /** The first row, as the data row's index from 0. */
+  readonly firstRow: number
+  readonly code: FormulaErrorCode
+}
+
+/**
+ * A sheet's table with its computed columns filled in, each in an order that computes what it
+ * reads first, its values written as the column's type stores them. Throws a
+ * {@link FormulaCycleError} for columns that read each other; publishing has refused those, and
+ * every formula that doesn't parse or check.
+ */
+export function evaluateComputedColumns(
+  sheet: Pick<WorkbookSheet, "columns">,
+  table: CsvTable
+): { readonly table: CsvTable; readonly errors: ReadonlyMap<string, ComputedColumnErrors> } {
+  const computed = table.header.filter((name) => sheet.columns[name]?.formula !== undefined)
+  if (computed.length === 0) return { table, errors: new Map() }
+  const formulas = new Map(
+    computed.map((name) => [name, parseFormula(sheet.columns[name]?.formula ?? "")])
+  )
+  const indexOf = new Map(table.header.map((name, index) => [name, index]))
+  const typeOf = (name: string) => sheet.columns[name]?.type ?? "text"
+
+  // Each column's values as a formula reads them, read once and filled as columns compute.
+  const values = new Map<string, FormulaValue[]>()
+  const columnValues = (name: string): FormulaValue[] => {
+    let column = values.get(name)
+    if (!column) {
+      const index = indexOf.get(name) ?? -1
+      const type = typeOf(name)
+      column = table.rows.map((row) => readCell(row[index] ?? "", type))
+      values.set(name, column)
+    }
+    return column
+  }
+
+  const rows = table.rows.map((row) => {
+    const copy = [...row]
+    while (copy.length < table.header.length) copy.push("")
+    return copy
+  })
+  const errors = new Map<string, ComputedColumnErrors>()
+  for (const name of computeOrder(formulas)) {
+    const formula = formulas.get(name) as FormulaNode
+    const index = indexOf.get(name) as number
+    const type = typeOf(name)
+    const results: FormulaValue[] = []
+    const memo = new Map<FormulaNode, FormulaValue>()
+    for (const [rowIndex, row] of rows.entries()) {
+      const result = evaluateFormula(
+        formula,
+        {
+          cell: (column) => columnValues(column)[rowIndex] ?? null,
+          column: (column) => columnValues(column),
+        },
+        memo
+      )
+      const cell = writeCell(result, type)
+      results.push(typeof cell === "object" ? cell : result)
+      row[index] = typeof cell === "object" ? cell.error : cell
+      if (typeof cell === "object") {
+        const known = errors.get(name)
+        errors.set(name, {
+          count: (known?.count ?? 0) + 1,
+          firstRow: known?.firstRow ?? rowIndex,
+          code: known?.code ?? cell.error,
+        })
+      }
+    }
+    values.set(name, results)
+  }
+  return { table: { header: table.header, rows }, errors }
+}
+
+/** The order to compute in: each column after those it reads. */
+function computeOrder(formulas: ReadonlyMap<string, FormulaNode>): string[] {
+  const order: string[] = []
+  const state = new Map<string, "visiting" | "done">()
+  const visit = (name: string, path: string[]) => {
+    if (state.get(name) === "done") return
+    if (state.get(name) === "visiting") {
+      throw new FormulaCycleError([...path.slice(path.indexOf(name)), name])
+    }
+    state.set(name, "visiting")
+    for (const dependency of formulaDependencies(formulas.get(name) as FormulaNode)) {
+      if (formulas.has(dependency)) visit(dependency, [...path, name])
+    }
+    state.set(name, "done")
+    order.push(name)
+  }
+  for (const name of formulas.keys()) visit(name, [])
+  return order
+}
+
+/** A stored cell as a formula reads it: a blank, its type's value, or its text as written. */
+function readCell(raw: string, type: SheetColumnType): FormulaValue {
+  if (!raw.trim()) return null
+  if (NUMERIC_COLUMN_TYPES.includes(type)) return parseSheetNumber(raw) ?? raw
+  if (type === "date") {
+    const date = parseSheetDate(raw)
+    return date ? dateSerial(date) : raw
+  }
+  if (type === "boolean") {
+    const word = raw.trim().toLowerCase()
+    return word === "true" ? true : word === "false" ? false : raw
+  }
+  return raw
+}
+
+/** A computed value as its column stores it, or the error it is where it doesn't fit. */
+function writeCell(
+  value: FormulaValue,
+  type: SheetColumnType
+): string | { readonly error: FormulaErrorCode } {
+  if (typeof value === "object" && value !== null) return value
+  if (value === null) return ""
+  if (type === "text" || type === "tag") return formulaText(value)
+  if (NUMERIC_COLUMN_TYPES.includes(type)) {
+    return typeof value === "number" ? formulaText(value) : { error: "#VALUE!" }
+  }
+  if (type === "date") {
+    return typeof value === "number" ? serialDate(value) : { error: "#VALUE!" }
+  }
+  if (type === "boolean") {
+    return typeof value === "boolean" ? String(value) : { error: "#VALUE!" }
+  }
+  return { error: "#VALUE!" }
+}