Formula Properties

Description

Formula Properties calculate row-local values from other properties through a purpose-built parser, checker, evaluator, and write-time refresh behavior.

A formula definition is parsed into a constrained expression tree, checked against live property references and result expectations, and rejected when invalid or cyclic. When source values change, computed refresh evaluates affected formulas and materializes their results through ordinary typed updates. This keeps calculation deterministic and available to queries without permitting general JavaScript execution.

User Story

As an operator, I define a margin or completion formula once and trust every row to stay current. I reference supported properties in a schema-level expression and save it only after validation succeeds. Each relevant row mutation triggers refresh, so views and filters read the materialized result without repeating client logic. I walk away with one governed calculation rather than several inconsistent spreadsheet formulas.

Extension Surface

Configurable: users author supported expressions and references; the formula language and function catalog are platform-controlled.

packages/dotabases/src/properties/formula/parser.ts proves the bounded extension surface: users supply expressions in the shipped grammar. They cannot call arbitrary runtime functions or access data outside the current row through a formula.

Capabilities & Limits

• Capability: Executes the scoped workflow described above through the cited live implementation paths.
• Capability: Preserves typed validation and applicable tenant, schema, lifecycle, or service boundaries.
• Limit: Formulas are synchronous and row-local. Cross-row aggregation belongs to Rollup Properties. The feature supports deterministic parsing, type-aware reference validation, cycle rejection, evaluation, and refresh after source changes. It cannot perform network calls, arbitrary code execution, or cross-row lookup. Unsupported functions and incompatible result types fail validation rather than being interpreted loosely.

Implementation Map

• packages/dotabases/src/properties/formula/parser.ts
• packages/dotabases/src/properties/formula/evaluator.ts
• packages/dotabases/src/behaviors/computed-refresh/index.ts

Related Features

Part of Typed Property System and evaluated again after Rollup Properties refresh.

Operationally, these relationships preserve a clear ownership boundary around Formula Properties. Neighboring features can invoke, supply, or consume its results, but `packages/dotabases/src/properties/formula/parser.ts` remains the grounded implementation authority for this capability. That distinction prevents the catalog claim from widening into adjacent rendering, transport, or governance work. Teams can therefore combine the feature with the named dependencies while still diagnosing configuration, validation, and lifecycle behavior at the package boundary that owns it.