Add formula function library documentation

[Copilot]

Formula fields existed with expression: z.string() but lacked function reference documentation, making them unusable without implementation knowledge.

Changes

Created /packages/spec/docs/formula-functions.md documenting 20 formula functions across 4 categories:

• Text Functions (5): UPPER, LOWER, CONCATENATE, TEXT, LEN
• Math Functions (5): SUM, AVERAGE, ROUND, CEILING, FLOOR
• Date Functions (6): TODAY, NOW, YEAR, MONTH, DAY, ADDDAYS
• Logical Functions (4): IF, AND, OR, NOT, ISBLANK

Each function includes:

• Parameter types and return values
• Multiple practical examples
• Type compatibility matrix
• Real-world use cases (price calculations, conditional logic, date arithmetic)

Usage

import { Field } from '@objectstack/spec/data';

const totalPrice = Field.formula({
  name: 'total_price',
  expression: 'ROUND(unit_price * quantity, 2)'
});

const discountedPrice = Field.formula({
  name: 'discounted_price',
  expression: 'IF(quantity >= 100, ROUND(price * 0.85, 2), price)'
});

Aligns with industry standards (Salesforce: 100+ functions, ServiceNow: 50+ functions).

Original prompt

2. Formula Function Library Undocumented (field.zod.ts)

Current State:

Formula fields exist with expression: z.string() but no function reference
No documentation of available functions (SUM, AVG, TEXT, DATE, etc.)
Missing:

Function signature documentation
Data type compatibility matrix
Example formulas
Industry Comparison:

Salesforce: 100+ formula functions documented (TEXT, DATE, MATH, LOGICAL, ADVANCED)
ServiceNow: 50+ GlideSystem functions
Recommendation: Create packages/spec/docs/formula-functions.md with complete function library:

Formula Function Library

Text Functions

• UPPER(text) - Converts to uppercase
• LOWER(text) - Converts to lowercase
• CONCATENATE(text1, text2, ...) - Joins text strings
• TEXT(number) - Converts number to text
• LEN(text) - Returns text length

Math Functions

• SUM(field1, field2, ...) - Adds numbers
• AVERAGE(field1, field2, ...) - Calculates average
• ROUND(number, decimals) - Rounds to decimal places
• CEILING(number) - Rounds up to integer
• FLOOR(number) - Rounds down to integer

Date Functions

• TODAY() - Current date
• NOW() - Current date/time
• YEAR(date) - Extract year
• MONTH(date) - Extract month
• DAY(date) - Extract day
• ADDDAYS(date, days) - Add days to date

Logical Functions

• IF(condition, true_value, false_value) - Conditional logic
• AND(condition1, condition2, ...) - Logical AND
• OR(condition1, condition2, ...) - Logical OR
• NOT(condition) - Logical NOT
• ISBLANK(field) - Check if field is null/empty

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
spec	Ready	Preview, Comment	Jan 23, 2026 10:59am

[Copilot]

Pull request overview

This PR adds comprehensive documentation for the formula function library, addressing the gap where formula fields existed (expression: z.string()) but lacked reference documentation about available functions.

Changes:

• Created /packages/spec/docs/formula-functions.md with detailed documentation for 20 formula functions across 4 categories (Text, Math, Date, and Logical)
• Added usage examples, parameter specifications, return types, and real-world use cases for each function
• Included type compatibility matrix and best practices guidance