@molecule/api-formula-engine 1.0.2 → 1.0.3

package/LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -34,21 +35,33 @@
 
       "Work" shall mean the work of authorship, whether in Source or
       Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work.
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
 
       "Derivative Works" shall mean any work, whether in Source or Object
       form, that is based on (or derived from) the Work and for which the
       editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship.
-
-      "Contribution" shall mean any work of authorship, including the
-      original version of the Work and any modifications or additions
-      to that Work, that is intentionally submitted to the Licensor for
-      inclusion in the Work by the copyright owner or by an individual or
-      Legal Entity authorized to submit on behalf of the copyright owner.
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
 
       "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by the Licensor and
+      on behalf of whom a Contribution has been received by Licensor and
       subsequently incorporated within the Work.
 
    2. Grant of Copyright License. Subject to the terms and conditions of
@@ -61,8 +74,18 @@
    3. Grant of Patent License. Subject to the terms and conditions of
       this License, each Contributor hereby grants to You a perpetual,
       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      patent license to make, have made, use, offer to sell, sell, import,
-      and otherwise transfer the Work.
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
 
    4. Redistribution. You may reproduce and distribute copies of the
       Work or Derivative Works thereof in any medium, with or without
@@ -84,23 +107,87 @@
       (d) If the Work includes a "NOTICE" text file as part of its
           distribution, then any Derivative Works that You distribute must
           include a readable copy of the attribution notices contained
-          within such NOTICE file.
-
-   5. Submission of Contributions.
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
 
    6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor.
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
 
    7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
-
-   8. Limitation of Liability. In no event and under no legal theory shall
-      any Contributor be liable to You for damages.
-
-   9. Accepting Warranty or Additional Liability.
-
-   Copyright 2026 Molecule Dev, Inc.
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -3,15 +3,11 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-08-04T00:36:31.815Z
+Generated: 2026-10-16T23:29:41.143Z
 -->
 
 # @molecule/api-formula-engine
 
-> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
-> It is written to be read by coding agents as much as by people, and is generated from this
-> package's source — edit `src/index.ts` JSDoc, not this file.
-
 Spreadsheet-style formula engine for molecule.dev.
 
 Pure-function parser + evaluator + dependency tracker for
@@ -45,6 +41,10 @@ stateless one-shot math.
 
 Pure functions, zero I/O, zero DB access, zero hardcoded UI text.
 
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
 ## Quick Start
 
 ```typescript
@@ -79,27 +79,30 @@ npm install @molecule/api-formula-engine
 
 ### Interfaces
 
-#### `BinaryOpNode`
+#### `Token`
 
-AST: binary operation.
+Lexical token. `value` is the raw source text; `op` carries the
+normalized operator string for `kind: 'op'` tokens.
 
 ```typescript
-interface BinaryOpNode {
-  readonly kind: 'binary'
-  readonly op: BinaryOperator
-  readonly left: AstNode
-  readonly right: AstNode
+interface Token {
+  readonly kind: TokenKind
+  readonly value: string
+  readonly position: number
+  readonly errorCode?: FormulaErrorCode
 }
 ```
 
-#### `BooleanLiteralNode`
+#### `FormulaError`
 
-AST: boolean literal (TRUE / FALSE).
+Spreadsheet error value. Returned (never thrown) by `evaluate`/`getValue`
+to allow downstream cells to propagate it like Excel.
 
 ```typescript
-interface BooleanLiteralNode {
-  readonly kind: 'boolean'
-  readonly value: boolean
+interface FormulaError {
+  readonly type: 'error'
+  readonly code: FormulaErrorCode
+  readonly message?: string
 }
 ```
 
@@ -126,6 +129,39 @@ interface CellRange {
 }
 ```
 
+#### `NumberLiteralNode`
+
+AST: numeric literal.
+
+```typescript
+interface NumberLiteralNode {
+  readonly kind: 'number'
+  readonly value: number
+}
+```
+
+#### `StringLiteralNode`
+
+AST: string literal (double-quoted).
+
+```typescript
+interface StringLiteralNode {
+  readonly kind: 'string'
+  readonly value: string
+}
+```
+
+#### `BooleanLiteralNode`
+
+AST: boolean literal (TRUE / FALSE).
+
+```typescript
+interface BooleanLiteralNode {
+  readonly kind: 'boolean'
+  readonly value: boolean
+}
+```
+
 #### `ErrorLiteralNode`
 
 AST: error literal (`#DIV/0!`, etc.).
@@ -137,27 +173,53 @@ interface ErrorLiteralNode {
 }
 ```
 
-#### `EvaluateOptions`
+#### `ReferenceNode`
 
-Options shared by `evaluate` and the `Sheet.recompute` family.
+AST: cell reference (e.g. `A1`, `$A$1`).
 
 ```typescript
-interface EvaluateOptions {
-  /** Override the clock used by `TODAY()` / `NOW()`. Defaults to `Date.now()`. */
-  readonly now?: () => Date
+interface ReferenceNode {
+  readonly kind: 'reference'
+  readonly coord: CellCoord
+  /** Original textual representation, preserved for diagnostics. */
+  readonly text: string
 }
 ```
 
-#### `FormulaError`
+#### `RangeNode`
 
-Spreadsheet error value. Returned (never thrown) by `evaluate`/`getValue`
-to allow downstream cells to propagate it like Excel.
+AST: cell range (e.g. `A1:B5`).
 
 ```typescript
-interface FormulaError {
-  readonly type: 'error'
-  readonly code: FormulaErrorCode
-  readonly message?: string
+interface RangeNode {
+  readonly kind: 'range'
+  readonly range: CellRange
+  readonly text: string
+}
+```
+
+#### `UnaryOpNode`
+
+AST: unary operation (e.g. `-A1`, `A1%`).
+
+```typescript
+interface UnaryOpNode {
+  readonly kind: 'unary'
+  readonly op: UnaryOperator
+  readonly operand: AstNode
+}
+```
+
+#### `BinaryOpNode`
+
+AST: binary operation.
+
+```typescript
+interface BinaryOpNode {
+  readonly kind: 'binary'
+  readonly op: BinaryOperator
+  readonly left: AstNode
+  readonly right: AstNode
 }
 ```
 
@@ -186,39 +248,14 @@ interface FunctionContext {
 }
 ```
 
-#### `NumberLiteralNode`
-
-AST: numeric literal.
-
-```typescript
-interface NumberLiteralNode {
-  readonly kind: 'number'
-  readonly value: number
-}
-```
-
-#### `RangeNode`
-
-AST: cell range (e.g. `A1:B5`).
-
-```typescript
-interface RangeNode {
-  readonly kind: 'range'
-  readonly range: CellRange
-  readonly text: string
-}
-```
-
-#### `ReferenceNode`
+#### `EvaluateOptions`
 
-AST: cell reference (e.g. `A1`, `$A$1`).
+Options shared by `evaluate` and the `Sheet.recompute` family.
 
 ```typescript
-interface ReferenceNode {
-  readonly kind: 'reference'
-  readonly coord: CellCoord
-  /** Original textual representation, preserved for diagnostics. */
-  readonly text: string
+interface EvaluateOptions {
+  /** Override the clock used by `TODAY()` / `NOW()`. Defaults to `Date.now()`. */
+  readonly now?: () => Date
 }
 ```
 
@@ -237,44 +274,57 @@ interface SheetConfig {
 }
 ```
 
-#### `StringLiteralNode`
+### Types
 
-AST: string literal (double-quoted).
+#### `ResolveCell`
+
+Function used to resolve a cell coordinate to its value. Returns
+`null` for empty cells. Implementations may evaluate dependent
+formulas (in which case they should detect cycles and return a
+`#CIRC!` error to the caller).
 
 ```typescript
-interface StringLiteralNode {
-  readonly kind: 'string'
-  readonly value: string
-}
+type ResolveCell = (coord: CellCoord) => CellValue
 ```
 
-#### `Token`
+#### `TokenKind`
 
-Lexical token. `value` is the raw source text; `op` carries the
-normalized operator string for `kind: 'op'` tokens.
+Lexical token kinds.
 
 ```typescript
-interface Token {
-  readonly kind: TokenKind
-  readonly value: string
-  readonly position: number
-  readonly errorCode?: FormulaErrorCode
-}
+type TokenKind =
+  | 'number'
+  | 'string'
+  | 'boolean'
+  | 'error'
+  | 'identifier'
+  | 'reference'
+  | 'range'
+  | 'op'
+  | 'lparen'
+  | 'rparen'
+  | 'comma'
 ```
 
-#### `UnaryOpNode`
+#### `FormulaErrorCode`
 
-AST: unary operation (e.g. `-A1`, `A1%`).
+Spreadsheet error codes. Errors propagate through expressions: any
+arithmetic or function call involving a `FormulaError` returns the
+left-most error unchanged (Excel-compatible semantics).
 
 ```typescript
-interface UnaryOpNode {
-  readonly kind: 'unary'
-  readonly op: UnaryOperator
-  readonly operand: AstNode
-}
+type FormulaErrorCode = '#DIV/0!' | '#VALUE!' | '#REF!' | '#NAME?' | '#NUM!' | '#N/A' | '#CIRC!'
 ```
 
-### Types
+#### `CellValue`
+
+Possible cell values. `null` represents an empty cell; numbers, strings,
+booleans, and `Date`s are all valid scalar values. `FormulaError`
+represents a propagating error.
+
+```typescript
+type CellValue = number | string | boolean | Date | null | FormulaError
+```
 
 #### `AstNode`
 
@@ -293,33 +343,21 @@ type AstNode =
   | FunctionCallNode
 ```
 
-#### `BinaryOperator`
-
-Binary operators. `^` = power, `&` = string concat,
-`=`/`<>` = equality, `<`/`<=`/`>`/`>=` = ordering.
-
-```typescript
-type BinaryOperator = '+' | '-' | '*' | '/' | '^' | '&' | '=' | '<>' | '<' | '<=' | '>' | '>='
-```
-
-#### `CellValue`
+#### `UnaryOperator`
 
-Possible cell values. `null` represents an empty cell; numbers, strings,
-booleans, and `Date`s are all valid scalar values. `FormulaError`
-represents a propagating error.
+Unary operators supported by the parser.
 
 ```typescript
-type CellValue = number | string | boolean | Date | null | FormulaError
+type UnaryOperator = '+' | '-' | '%'
 ```
 
-#### `FormulaErrorCode`
+#### `BinaryOperator`
 
-Spreadsheet error codes. Errors propagate through expressions: any
-arithmetic or function call involving a `FormulaError` returns the
-left-most error unchanged (Excel-compatible semantics).
+Binary operators. `^` = power, `&` = string concat,
+`=`/`<>` = equality, `<`/`<=`/`>`/`>=` = ordering.
 
 ```typescript
-type FormulaErrorCode = '#DIV/0!' | '#VALUE!' | '#REF!' | '#NAME?' | '#NUM!' | '#N/A' | '#CIRC!'
+type BinaryOperator = '+' | '-' | '*' | '/' | '^' | '&' | '=' | '<>' | '<' | '<=' | '>' | '>='
 ```
 
 #### `FormulaFunction`
@@ -336,77 +374,327 @@ type FormulaFunction = (
 ) => CellValue
 ```
 
-#### `ResolveCell`
+### Classes
 
-Function used to resolve a cell coordinate to its value. Returns
-`null` for empty cells. Implementations may evaluate dependent
-formulas (in which case they should detect cycles and return a
-`#CIRC!` error to the caller).
+#### `Sheet`
+
+In-memory single-sheet engine. References use A1 notation (`A1`,
+`$A$1`, `BC42`).
 
 ```typescript
-type ResolveCell = (coord: CellCoord) => CellValue
+class Sheet {
+  private readonly cells = new Map<string, CellRecord>()
+  /** dependent-of[key] = set of cells that reference `key`. */
+  private readonly dependents = new Map<string, Set<string>>()
+  private readonly config: Required<SheetConfig>
+
+  /**
+   * Create a new Sheet with optional dimension limits.
+   *
+   * @param config - Sheet configuration.
+   */
+  constructor(config: SheetConfig = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config }
+  }
+
+  /**
+   * Set a literal value at a cell.
+   *
+   * @param ref - A1-style cell reference (e.g. `A1`, `$B$3`).
+   * @param value - Literal value (number, string, boolean, Date, or null).
+   * @param options - Evaluation options forwarded to recompute.
+   */
+  setValue(ref: string, value: CellValue, options: EvaluateOptions = {}): void {
+    const coord = this.refToCoord(ref)
+    this.assignCell(coord, value, null, null, options)
+  }
+
+  /**
+   * Set a formula at a cell. The formula text may include or omit the
+   * leading `=`. The formula is parsed eagerly and `#NAME?` /
+   * `#VALUE!` errors caused by parser failures are stored as the
+   * cell's value.
+   *
+   * @param ref - A1-style cell reference.
+   * @param formula - Formula text (e.g. `=SUM(A1:A10)` or `SUM(A1:A10)`).
+   * @param options - Evaluation options forwarded to recompute.
+   */
+  setFormula(ref: string, formula: string, options: EvaluateOptions = {}): void {
+    const coord = this.refToCoord(ref)
+    let ast: AstNode | null = null
+    let parseError: CellValue | null = null
+    try {
+      ast = parseFormula(formula)
+    } catch (e) {
+      parseError = makeError('#VALUE!', (e as Error).message)
+    }
+    if (parseError) {
+      this.assignCell(coord, parseError, null, formula, options)
+      return
+    }
+    this.assignCell(coord, null, ast, formula, options)
+  }
+
+  /**
+   * Clear a cell (remove value, formula, and dependency edges).
+   *
+   * @param ref - A1-style cell reference.
+   * @param options - Evaluation options forwarded to recompute.
+   */
+  clear(ref: string, options: EvaluateOptions = {}): void {
+    const coord = this.refToCoord(ref)
+    const key = coordKey(coord)
+    const existing = this.cells.get(key)
+    if (existing) {
+      for (const dep of existing.precedents) {
+        this.dependents.get(dep)?.delete(key)
+      }
+    }
+    this.cells.delete(key)
+    this.recomputeDownstream(key, options)
+  }
+
+  /**
+   * Read the most recently computed value for a cell.
+   *
+   * @param ref - A1-style cell reference.
+   * @returns Cell value (`null` if the cell is empty).
+   */
+  getValue(ref: string): CellValue {
+    const coord = this.refToCoord(ref)
+    const key = coordKey(coord)
+    const cell = this.cells.get(key)
+    return cell ? cell.computed : null
+  }
+
+  /**
+   * Return the formula text for a cell, or `null` if the cell holds a
+   * literal value or is empty.
+   *
+   * @param ref - A1-style cell reference.
+   * @returns Formula text (with leading `=`) or `null`.
+   */
+  getFormula(ref: string): string | null {
+    const coord = this.refToCoord(ref)
+    const key = coordKey(coord)
+    return this.cells.get(key)?.formula ?? null
+  }
+
+  /**
+   * Recompute every formula cell. Useful after bulk edits or when
+   * `now()` semantics change.
+   *
+   * @param options - Evaluation options.
+   */
+  recomputeAll(options: EvaluateOptions = {}): void {
+    const keys = [...this.cells.keys()]
+    const { order, cycle } = topologicalSort(this.dependents, keys)
+    for (const k of order) this.evaluateKey(k, options, cycle)
+    for (const k of cycle) {
+      const cell = this.cells.get(k)
+      if (!cell) continue
+      cell.computed = makeError('#CIRC!')
+    }
+  }
+
+  /**
+   * Evaluate a free-standing formula string against this sheet's data.
+   * Does NOT mutate the sheet. Useful for ad-hoc evaluations such as
+   * invoice line-item totals or computed-column previews.
+   *
+   * @param formula - Formula text.
+   * @param options - Evaluation options.
+   * @returns Evaluated cell value.
+   */
+  evaluateFormula(formula: string, options: EvaluateOptions = {}): CellValue {
+    let ast: AstNode
+    try {
+      ast = parseFormula(formula)
+    } catch (e) {
+      return makeError('#VALUE!', (e as Error).message)
+    }
+    return evaluate(ast, (coord) => this.cells.get(coordKey(coord))?.computed ?? null, options)
+  }
+
+  // --- Internals ---
+
+  /**
+   * Parse an A1-style reference string into a validated CellCoord.
+   */
+  private refToCoord(ref: string): CellCoord {
+    const coord = parseCellReference(ref)
+    if (!coord) throw new Error(`Invalid cell reference: ${ref}`)
+    if (coord.col >= this.config.numCols || coord.row >= this.config.numRows) {
+      throw new Error(`Reference out of bounds: ${ref}`)
+    }
+    return coord
+  }
+
+  /**
+   * Write a cell record, rewire dependency edges, and trigger downstream recompute.
+   */
+  private assignCell(
+    coord: CellCoord,
+    value: CellValue,
+    ast: AstNode | null,
+    formula: string | null,
+    options: EvaluateOptions,
+  ): void {
+    const key = coordKey(coord)
+    const existing = this.cells.get(key)
+    if (existing) {
+      for (const dep of existing.precedents) {
+        this.dependents.get(dep)?.delete(key)
+      }
+    }
+    const precedents = new Set<string>()
+    if (ast) {
+      for (const c of collectReferences(ast)) {
+        const k = coordKey(c)
+        precedents.add(k)
+        let set = this.dependents.get(k)
+        if (!set) {
+          set = new Set()
+          this.dependents.set(k, set)
+        }
+        set.add(key)
+      }
+    }
+    const record: CellRecord = {
+      value,
+      ast,
+      formula,
+      precedents,
+      computed: value,
+    }
+    this.cells.set(key, record)
+    if (ast) this.evaluateKey(key, options, new Set())
+    this.recomputeDownstream(key, options)
+  }
+
+  /**
+   * Recompute all formula cells that transitively depend on the given key.
+   */
+  private recomputeDownstream(rootKey: string, options: EvaluateOptions): void {
+    // Find every transitive dependent of the changed cell.
+    const affected = new Set<string>()
+    const stack = [rootKey]
+    while (stack.length > 0) {
+      const k = stack.pop()!
+      const outs = this.dependents.get(k)
+      if (!outs) continue
+      for (const t of outs) {
+        if (!affected.has(t)) {
+          affected.add(t)
+          stack.push(t)
+        }
+      }
+    }
+    if (affected.size === 0) return
+    const keys = [...affected]
+    const { order, cycle } = topologicalSort(this.dependents, keys)
+    for (const k of order) this.evaluateKey(k, options, cycle)
+    for (const k of cycle) {
+      const cell = this.cells.get(k)
+      if (!cell) continue
+      cell.computed = makeError('#CIRC!')
+    }
+  }
+
+  /**
+   * Evaluate (or propagate) the computed value for a single cell key.
+   */
+  private evaluateKey(key: string, options: EvaluateOptions, cycleSet: ReadonlySet<string>): void {
+    const cell = this.cells.get(key)
+    if (!cell) return
+    if (cycleSet.has(key)) {
+      cell.computed = makeError('#CIRC!')
+      return
+    }
+    if (!cell.ast) {
+      cell.computed = cell.value
+      return
+    }
+    const value = evaluate(
+      cell.ast,
+      (coord) => {
+        const k = coordKey(coord)
+        if (cycleSet.has(k)) return makeError('#CIRC!')
+        const target = this.cells.get(k)
+        return target ? target.computed : null
+      },
+      options,
+    )
+    cell.computed = value
+    if (isError(value)) {
+      cell.value = value
+    }
+  }
+}
 ```
 
-#### `TokenKind`
+### Functions
 
-Lexical token kinds.
+#### `collectReferences(node)`
 
-```typescript
-type TokenKind =
-  | 'number'
-  | 'string'
-  | 'boolean'
-  | 'error'
-  | 'identifier'
-  | 'reference'
-  | 'range'
-  | 'op'
-  | 'lparen'
-  | 'rparen'
-  | 'comma'
+Walk an AST and collect every coordinate it references (single
+references and every cell inside ranges).
+
+```typescript
+function collectReferences(node: AstNode): CellCoord[]
 ```
 
-#### `UnaryOperator`
+- `node` — Root AST node.
 
-Unary operators supported by the parser.
+**Returns:** Flat list of referenced coordinates (may contain duplicates).
 
-```typescript
-type UnaryOperator = '+' | '-' | '%'
-```
+#### `topologicalSort(dependents, keys)`
 
-### Classes
+Topologically sort a set of coordinate keys by their dependency graph
+such that, for any edge `a → b` (b depends on a), `a` precedes `b`
+in the result.
 
-#### `Sheet`
+Uses Kahn's algorithm. If a cycle is detected, the cycle members are
+returned in `cycle` and excluded from `order` — callers typically
+mark cycle members with a `#CIRC!` error.
 
-In-memory single-sheet engine. References use A1 notation (`A1`,
-`$A$1`, `BC42`).
+```typescript
+function topologicalSort(
+  dependents: ReadonlyMap<string, ReadonlySet<string>>,
+  keys: readonly string[],
+): { order: string[]; cycle: Set<string> }
+```
 
-### Functions
+- `dependents` — Map from a key to the set of keys that depend on it. (i.e. forward edges in the recompute order.)
+- `keys` — Keys to sort.
 
-#### `collectReferences(node)`
+**Returns:** `{ order, cycle }` — `order` is the topological order; `cycle` is the set of keys participating in (or downstream of) a cycle.
 
-Walk an AST and collect every coordinate it references (single
-references and every cell inside ranges).
+#### `evaluate(node, resolveCell, options)`
+
+Evaluate an AST in the context of a cell-resolution function.
 
 ```typescript
-function collectReferences(node: AstNode): CellCoord[]
+function evaluate(node: AstNode, resolveCell: ResolveCell, options?: EvaluateOptions): CellValue
 ```
 
 - `node` — Root AST node.
+- `resolveCell` — Function returning the value of a referenced cell.
+- `options` — Evaluation options.
 
-**Returns:** Flat list of referenced coordinates (may contain duplicates).
+**Returns:** Evaluated cell value (errors are returned, not thrown).
 
-#### `columnIndexToLetters(index)`
+#### `parseFormula(input)`
 
-Convert a 0-indexed column to letters (`0`→`A`, `25`→`Z`, `26`→`AA`).
+Parse a formula string into an AST.
 
 ```typescript
-function columnIndexToLetters(index: number): string
+function parseFormula(input: string): AstNode
 ```
 
-- `index` — 0-indexed column.
+- `input` — Formula text (with or without a leading `=`).
 
-**Returns:** Column letters (uppercase).
+**Returns:** Root AST node.
 
 #### `columnLettersToIndex(letters)`
 
@@ -420,103 +708,102 @@ function columnLettersToIndex(letters: string): number
 
 **Returns:** 0-indexed column number.
 
-#### `compareValues(left, right)`
+#### `columnIndexToLetters(index)`
 
-Compare two scalar cell values (Excel ordering: number < string,
-boolean compared as 0/1 within numbers).
+Convert a 0-indexed column to letters (`0`→`A`, `25`→`Z`, `26`→`AA`).
 
 ```typescript
-function compareValues(left: CellValue, right: CellValue): number | FormulaError
+function columnIndexToLetters(index: number): string
 ```
 
-- `left` — Left operand.
-- `right` — Right operand.
+- `index` — 0-indexed column.
 
-**Returns:** -1, 0, 1, or `FormulaError` if uncomparable.
+**Returns:** Column letters (uppercase).
 
-#### `coordKey(coord)`
+#### `parseCellReference(ref)`
 
-Encode a coordinate to a cache-friendly string key (`"col,row"`).
+Parse a single cell reference (e.g. `A1`, `$A$1`, `BC42`).
 
 ```typescript
-function coordKey(coord: CellCoord): string
+function parseCellReference(ref: string): CellCoord | null
 ```
 
-- `coord` — Cell coordinate.
+- `ref` — Reference text.
 
-**Returns:** Stable string key.
+**Returns:** Parsed cell coordinate, or `null` if invalid.
 
-#### `dateToSerial(date)`
+#### `parseCellRange(ref)`
 
-Convert a `Date` to an Excel serial number (days since 1899-12-30).
+Parse a cell range (e.g. `A1:B5`). Normalizes so `start` is top-left
+and `end` is bottom-right regardless of input ordering.
 
 ```typescript
-function dateToSerial(date: Date): number
+function parseCellRange(ref: string): CellRange | null
 ```
 
-- `date` — Date instance.
+- `ref` — Range text.
 
-**Returns:** Excel serial date.
+**Returns:** Parsed range, or `null` if invalid.
 
-#### `evaluate(node, resolveCell, options)`
+#### `formatCellReference(coord)`
 
-Evaluate an AST in the context of a cell-resolution function.
+Format a cell coordinate as A1-style text (`{col:0,row:0}` → `A1`).
 
 ```typescript
-function evaluate(node: AstNode, resolveCell: ResolveCell, options?: EvaluateOptions): CellValue
+function formatCellReference(coord: CellCoord): string
 ```
 
-- `node` — Root AST node.
-- `resolveCell` — Function returning the value of a referenced cell.
-- `options` — Evaluation options.
+- `coord` — Cell coordinate.
 
-**Returns:** Evaluated cell value (errors are returned, not thrown).
+**Returns:** A1-style reference text.
 
-#### `firstError(values)`
+#### `iterateRange(range)`
 
-Returns the first error encountered in a flat list, or `null` if none.
+Iterate every coordinate in a range. Yields top-to-bottom, left-to-right.
 
 ```typescript
-function firstError(values: readonly CellValue[]): FormulaError | null
+function iterateRange(range: CellRange): Generator<CellCoord, any, any>
 ```
 
-- `values` — Cell values to scan.
-
-**Returns:** The first error value, or `null`.
+- `range` — Cell range.
 
-#### `formatCellReference(coord)`
+#### `coordKey(coord)`
 
-Format a cell coordinate as A1-style text (`{col:0,row:0}` → `A1`).
+Encode a coordinate to a cache-friendly string key (`"col,row"`).
 
 ```typescript
-function formatCellReference(coord: CellCoord): string
+function coordKey(coord: CellCoord): string
 ```
 
 - `coord` — Cell coordinate.
 
-**Returns:** A1-style reference text.
+**Returns:** Stable string key.
 
-#### `isError(value)`
+#### `refOf(coord)`
 
-Type-guard for `FormulaError`.
+Reformat a cell coordinate as A1-style text. Re-exported for
+convenience.
 
 ```typescript
-function isError(value: unknown): boolean
+function refOf(coord: CellCoord): string
 ```
 
-- `value` — Cell value to inspect.
+- `coord` — Cell coordinate.
 
-**Returns:** `true` if the value is a propagating error.
+**Returns:** A1-style reference text.
 
-#### `iterateRange(range)`
+#### `tokenize(input)`
 
-Iterate every coordinate in a range. Yields top-to-bottom, left-to-right.
+Tokenize a formula string. The leading `=` (if present) is stripped
+by the caller — pass the _body_ of the formula here.
 
 ```typescript
-function iterateRange(range: CellRange): Generator<CellCoord, any, any>
+function tokenize(input: string): Token[]
 ```
 
-- `range` — Cell range.
+- `input` — Raw formula text (no leading `=`).
+
+**Returns:** Flat token list.
 
 #### `makeError(code, message)`
 
@@ -531,67 +818,59 @@ function makeError(code: FormulaErrorCode, message?: string): FormulaError
 
 **Returns:** The error value.
 
-#### `parseCellRange(ref)`
+#### `isError(value)`
 
-Parse a cell range (e.g. `A1:B5`). Normalizes so `start` is top-left
-and `end` is bottom-right regardless of input ordering.
+Type-guard for `FormulaError`.
 
 ```typescript
-function parseCellRange(ref: string): CellRange | null
+function isError(value: unknown): boolean
 ```
 
-- `ref` — Range text.
+- `value` — Cell value to inspect.
 
-**Returns:** Parsed range, or `null` if invalid.
+**Returns:** `true` if the value is a propagating error.
 
-#### `parseCellReference(ref)`
+#### `firstError(values)`
 
-Parse a single cell reference (e.g. `A1`, `$A$1`, `BC42`).
+Returns the first error encountered in a flat list, or `null` if none.
 
 ```typescript
-function parseCellReference(ref: string): CellCoord | null
+function firstError(values: readonly CellValue[]): FormulaError | null
 ```
 
-- `ref` — Reference text.
-
-**Returns:** Parsed cell coordinate, or `null` if invalid.
-
-#### `parseFormula(input)`
-
-Parse a formula string into an AST.
-
-```typescript
-function parseFormula(input: string): AstNode
-```
+- `values` — Cell values to scan.
 
-- `input` — Formula text (with or without a leading `=`).
+**Returns:** The first error value, or `null`.
 
-**Returns:** Root AST node.
+#### `toNumber(value)`
 
-#### `refOf(coord)`
+Coerce a cell value to a number (Excel-compatible).
 
-Reformat a cell coordinate as A1-style text. Re-exported for
-convenience.
+- `null` → 0
+- boolean → 0/1
+- `Date` → days since 1899-12-30 (Excel's epoch)
+- string → parsed as number, `#VALUE!` if not parseable
+- error → propagated unchanged
 
 ```typescript
-function refOf(coord: CellCoord): string
+function toNumber(value: CellValue): number | FormulaError
 ```
 
-- `coord` — Cell coordinate.
+- `value` — Cell value.
 
-**Returns:** A1-style reference text.
+**Returns:** Number, or `FormulaError` on failure.
 
-#### `serialToDate(serial)`
+#### `toStringValue(value)`
 
-Convert an Excel serial number to a `Date` (UTC).
+Coerce a cell value to a string for display / `&` concatenation.
 
 ```typescript
-function serialToDate(serial: number): Date
+function toStringValue(value: CellValue): string | FormulaError
 ```
 
-- `serial` — Excel serial date.
+- `value` — Cell value.
 
-**Returns:** Date instance.
+**Returns:** String, or `FormulaError` for propagating errors.
 
 #### `toBoolean(value)`
 
@@ -605,70 +884,43 @@ function toBoolean(value: CellValue): boolean | FormulaError
 
 **Returns:** Boolean, or `FormulaError` on failure.
 
-#### `tokenize(input)`
-
-Tokenize a formula string. The leading `=` (if present) is stripped
-by the caller — pass the _body_ of the formula here.
-
-```typescript
-function tokenize(input: string): Token[]
-```
-
-- `input` — Raw formula text (no leading `=`).
-
-**Returns:** Flat token list.
-
-#### `toNumber(value)`
-
-Coerce a cell value to a number (Excel-compatible).
+#### `dateToSerial(date)`
 
-- `null` → 0
-- boolean → 0/1
-- `Date` → days since 1899-12-30 (Excel's epoch)
-- string → parsed as number, `#VALUE!` if not parseable
-- error → propagated unchanged
+Convert a `Date` to an Excel serial number (days since 1899-12-30).
 
 ```typescript
-function toNumber(value: CellValue): number | FormulaError
+function dateToSerial(date: Date): number
 ```
 
-- `value` — Cell value.
-
-**Returns:** Number, or `FormulaError` on failure.
+- `date` — Date instance.
 
-#### `topologicalSort(dependents, keys)`
+**Returns:** Excel serial date.
 
-Topologically sort a set of coordinate keys by their dependency graph
-such that, for any edge `a → b` (b depends on a), `a` precedes `b`
-in the result.
+#### `serialToDate(serial)`
 
-Uses Kahn's algorithm. If a cycle is detected, the cycle members are
-returned in `cycle` and excluded from `order` — callers typically
-mark cycle members with a `#CIRC!` error.
+Convert an Excel serial number to a `Date` (UTC).
 
 ```typescript
-function topologicalSort(
-  dependents: ReadonlyMap<string, ReadonlySet<string>>,
-  keys: readonly string[],
-): { order: string[]; cycle: Set<string> }
+function serialToDate(serial: number): Date
 ```
 
-- `dependents` — Map from a key to the set of keys that depend on it. (i.e. forward edges in the recompute order.)
-- `keys` — Keys to sort.
+- `serial` — Excel serial date.
 
-**Returns:** `{ order, cycle }` — `order` is the topological order; `cycle` is the set of keys participating in (or downstream of) a cycle.
+**Returns:** Date instance.
 
-#### `toStringValue(value)`
+#### `compareValues(left, right)`
 
-Coerce a cell value to a string for display / `&` concatenation.
+Compare two scalar cell values (Excel ordering: number < string,
+boolean compared as 0/1 within numbers).
 
 ```typescript
-function toStringValue(value: CellValue): string | FormulaError
+function compareValues(left: CellValue, right: CellValue): number | FormulaError
 ```
 
-- `value` — Cell value.
+- `left` — Left operand.
+- `right` — Right operand.
 
-**Returns:** String, or `FormulaError` for propagating errors.
+**Returns:** -1, 0, 1, or `FormulaError` if uncomparable.
 
 ### Constants
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-formula-engine",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Spreadsheet-style formula evaluator: parser, evaluator, dependency tracker for cell graphs with arithmetic, comparison, string ops, references, aggregations, conditionals, date/text functions, and circular-ref detection.",
   "homepage": "https://www.molecule.dev/packages/api-formula-engine",
   "type": "module",
@@ -33,8 +33,8 @@
     "directory": "packages/api/utilities/formula-engine"
   },
   "devDependencies": {
-    "@types/node": "26.1.2",
+    "@types/node": "26.6.5",
     "typescript": "6.0.3",
-    "vitest": "4.1.11"
+    "vitest": "4.1.12"
   }
 }