Create comprehensive formula engine specification #90

Copilot · 2026-01-15T05:40:29Z

Formula Engine Specification - Type Safety Fixes ✅

Summary

Created a comprehensive formula engine specification for ObjectQL including:

Documentation (`docs/spec/formula.md`)

1,149 lines of detailed specification
Complete syntax guide for JavaScript-style expressions
Field references, operators, and functions
System variables ($today, $now, $current_user)
Relationship traversal via dot notation
50+ practical examples across multiple domains (e-commerce, CRM, project management, HR)
Error handling patterns and best practices
Performance considerations and limitations

TypeScript Types (`packages/foundation/types/src/formula.ts`)

450+ lines of type definitions (enhanced with strict typing)
Type Safety Improvements:
- Added FormulaValue type for return values
- Added FormulaFieldValue type for field values
- Added FormulaErrorContext interface for error context
- Added FormulaCustomFunction type for custom functions
- Replaced all any types with specific types
- Changed FormulaError to extend ObjectQLError
FormulaFieldConfig - Field configuration interface
FormulaContext - Runtime evaluation context
FormulaEvaluationResult - Result type
FormulaError and FormulaErrorType - Comprehensive error handling
FormulaMetadata - Introspection support
FormulaExecutionStats - Performance monitoring
FormulaEngineConfig - Engine configuration

Integration

Updated docs/spec/index.md to include formula specification
Enhanced packages/foundation/types/src/field.ts with formula properties
Fixed type safety violations in field.ts (replaced any[] with unknown[])
Exported all formula types from @objectql/types package
TypeScript compilation verified ✅

Type Safety Fixes (Addressing Code Review)

✅ FormulaError now extends ObjectQLError instead of Error
✅ Replaced any in treat_blank_as with FormulaValue type
✅ Replaced any in example/test case inputs/results with FormulaFieldValue and FormulaValue
✅ Replaced any in FormulaContext.record with Record<string, FormulaFieldValue>
✅ Replaced any in FormulaUserContext index signature with unknown
✅ Replaced any in FormulaEvaluationResult.value with FormulaValue
✅ Added FormulaErrorContext interface and replaced any context parameter
✅ Replaced generic Function type with FormulaCustomFunction type
✅ Fixed filters type in field.ts from any[] to unknown[]
✅ Fixed treat_blank_as in field.ts to use union of primitive types

Original prompt

创建公式引擎规范

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Co-authored-by: huangyiirene <[email protected]>

hotlong · 2026-01-15T05:56:56Z

@copilot 继续

Copilot · 2026-01-15T05:58:53Z

@copilot 继续

Formula engine specification completed ✅

Created comprehensive documentation and TypeScript types:

Documentation (docs/spec/formula.md):

1,149 lines covering complete formula syntax
JavaScript-style expressions with field references
System variables ($today, $now, $current_user)
50+ examples across e-commerce, CRM, project management, HR domains
Error handling patterns and best practices

TypeScript Types (@objectql/types/formula.ts):

Complete type definitions for formula engine
FormulaFieldConfig, FormulaContext, FormulaEvaluationResult
Error handling types and performance monitoring interfaces
All types exported and TypeScript compilation verified

All checklist items completed. Ready for review.

Copilot

Pull request overview

This PR establishes a comprehensive formula engine specification for ObjectQL, introducing formula fields as read-only calculated fields that derive values using JavaScript-style expressions. The specification provides complete documentation and type definitions for implementing metadata-driven calculations without custom code.

Changes:

Created a 1,149-line formula specification document with syntax reference, examples, and best practices
Defined TypeScript types for formula configuration, evaluation context, and error handling
Updated core type definitions to support formula-specific field properties

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
`docs/spec/formula.md`	Comprehensive specification covering expression syntax, operators, system variables, built-in functions, advanced patterns, error handling, and 50+ domain-specific examples
`packages/foundation/types/src/formula.ts`	Complete TypeScript type definitions including FormulaFieldConfig, FormulaContext, FormulaEvaluationResult, and error handling types
`packages/foundation/types/src/field.ts`	Enhanced FieldConfig interface with formula-specific properties (data_type, format, precision, blank_as_zero, treat_blank_as)
`packages/foundation/types/src/index.ts`	Added export statement to make formula types available from @objectql/types package
`docs/spec/index.md`	Updated specification index to include formula fields in the Core Data Layer section

Copilot · 2026-01-15T06:02:36Z

packages/foundation/types/src/formula.ts

+export class FormulaError extends Error {
+    constructor(
+        public type: FormulaErrorType,
+        public message: string,
+        public expression?: string,
+        public context?: any
+    ) {
+        super(message);
+        this.name = 'FormulaError';
+    }
+}


The FormulaError class extends the standard Error class instead of using the ObjectQLError defined in @objectql/types. According to the coding guidelines, all errors should use ObjectQLError. Consider refactoring this to extend ObjectQLError or integrate with the existing error handling system.

Copilot · 2026-01-15T06:02:36Z

packages/foundation/types/src/formula.ts

+        public type: FormulaErrorType,
+        public message: string,
+        public expression?: string,
+        public context?: any


The context parameter is typed as 'any', which violates the strict typing requirement. Consider defining a specific interface for the context or using a more specific type.

Copilot · 2026-01-15T06:02:37Z

packages/foundation/types/src/field.ts

+    /** Treat blank/null as zero in formula calculations. */
+    blank_as_zero?: boolean;
+    /** Default value for null/undefined referenced fields in formulas. */
+    treat_blank_as?: any;


The treat_blank_as property is typed as 'any', which violates the strict typing constraint. Consider using a union type of possible default values or defining a more specific type that matches the supported data types.

Copilot · 2026-01-15T06:02:37Z

packages/foundation/types/src/formula.ts

+    blank_as_zero?: boolean;
+
+    /** Default value to use when referenced fields are null/undefined */
+    treat_blank_as?: any;


The treat_blank_as property is typed as 'any', which violates the strict typing constraint. Consider using a union type of possible default values or defining a more specific type that matches FormulaDataType.

Copilot · 2026-01-15T06:02:38Z

packages/foundation/types/src/formula.ts

+    description: string;
+
+    /** Input field values */
+    inputs: Record<string, any>;


The inputs Record uses 'any' for values, which violates strict typing. Consider defining a union type for valid input values or using a more specific type constraint.

Copilot · 2026-01-15T06:02:39Z

packages/foundation/types/src/formula.ts

+    input: Record<string, any>;
+
+    /** Expected output value */
+    expected: any;


The expected property is typed as 'any'. Consider constraining this to match FormulaDataType return values.

Copilot · 2026-01-15T06:02:39Z

packages/foundation/types/src/formula.ts

+ */
+export interface FormulaContext {
+    /** Current record data with all field values */
+    record: Record<string, any>;


The record property uses 'any' for field values. Consider defining a more specific type or constraint for field values.

Copilot · 2026-01-15T06:02:40Z

packages/foundation/types/src/formula.ts

+    role?: string;
+
+    /** Additional user properties */
+    [key: string]: any;


The index signature uses 'any' type. Consider using 'unknown' for better type safety or defining a more specific constraint for additional user properties.

Copilot · 2026-01-15T06:02:40Z

packages/foundation/types/src/formula.ts

+ */
+export interface FormulaEvaluationResult {
+    /** Computed value */
+    value: any;


The value property is typed as 'any'. Consider using a union type based on FormulaDataType for better type safety.

Copilot · 2026-01-15T06:02:40Z

packages/foundation/types/src/formula.ts

+    enable_monitoring?: boolean;
+
+    /** Custom function library */
+    custom_functions?: Record<string, Function>;


Using the generic 'Function' type is not type-safe. Consider defining a more specific function signature or using a constrained generic type for custom functions.

huangyiirene · 2026-01-15T06:20:36Z

@copilot fix

…end ObjectQLError Co-authored-by: huangyiirene <[email protected]>

Copilot · 2026-01-15T06:24:49Z

@copilot fix

Fixed all type safety violations in commit 3a86cdf:

Changes Made:

✅ FormulaError now extends ObjectQLError instead of Error
✅ Added FormulaValue and FormulaFieldValue types to replace all any types
✅ Added FormulaErrorContext interface for type-safe error context
✅ Added FormulaCustomFunction type to replace generic Function type
✅ Updated all Record types to use unknown for index signatures
✅ Fixed types in both formula.ts and field.ts

TypeScript compilation verified with strict mode. All 12 reviewer comments addressed.

Initial plan

b8468a6

Copilot AI assigned Copilot and huangyiirene Jan 15, 2026

Copilot started work on behalf of huangyiirene January 15, 2026 05:40 View session

Changes before error encountered

98f55d6

Co-authored-by: huangyiirene <[email protected]>

Copilot AI requested a review from huangyiirene January 15, 2026 05:47

Copilot started work on behalf of hotlong January 15, 2026 05:57 View session

Copilot AI changed the title ~~[WIP] Create specification for formula engine~~ Create comprehensive formula engine specification Jan 15, 2026

Copilot AI requested a review from hotlong January 15, 2026 06:00

Copilot finished work on behalf of hotlong January 15, 2026 06:00

huangyiirene requested review from Copilot and removed request for hotlong and huangyiirene January 15, 2026 06:02

Copilot AI reviewed Jan 15, 2026

View reviewed changes

Copilot started work on behalf of huangyiirene January 15, 2026 06:21 View session

Fix type safety violations: replace 'any' with specific types and ext…

3a86cdf

…end ObjectQLError Co-authored-by: huangyiirene <[email protected]>

Copilot finished work on behalf of huangyiirene January 15, 2026 06:26

Copilot AI requested a review from huangyiirene January 15, 2026 06:26

github-actions bot added 🏗️ foundation 📚 documentation labels Jan 15, 2026

hotlong marked this pull request as ready for review January 15, 2026 06:31

hotlong merged commit b6cc0aa into main Jan 15, 2026
7 checks passed

hotlong deleted the copilot/create-formula-engine-specification branch January 15, 2026 06:32

Create comprehensive formula engine specification #90

Create comprehensive formula engine specification #90

Uh oh!

Conversation

Copilot AI commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Formula Engine Specification - Type Safety Fixes ✅

Summary

Documentation (docs/spec/formula.md)

TypeScript Types (packages/foundation/types/src/formula.ts)

Integration

Type Safety Fixes (Addressing Code Review)

Uh oh!

hotlong commented Jan 15, 2026

Uh oh!

Copilot AI commented Jan 15, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

huangyiirene commented Jan 15, 2026

Uh oh!

Copilot AI commented Jan 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Jan 15, 2026 •

edited

Loading

Documentation (`docs/spec/formula.md`)

TypeScript Types (`packages/foundation/types/src/formula.ts`)