Add formula engine tutorial and examples

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

examples/tutorials/tutorial-formulas/README.md

@@ -0,0 +1,86 @@
+# Formula Engine Tutorial
+
+This tutorial demonstrates the Formula Engine capabilities in ObjectQL. Formulas are read-only calculated fields that automatically derive their values from other fields, related records, or system variables.
+
+## Quick Start
+
+```bash
+npm install
+npm run dev
+```
+
+## What You'll Learn
+
+1. Basic formula expressions (arithmetic, string concatenation)
+2. Conditional logic in formulas
+3. System variables ($today, $current_user)
+4. Complex business logic
+5. Error handling
+
+## Example Objects
+
+### 1. E-commerce Order
+
+Demonstrates:
+- Price calculations with discounts and tax
+- Stock status logic
+- Risk assessment
+
+### 2. CRM Contact
+
+Demonstrates:
+- String concatenation (full name)
+- Relationship traversal
+- User ownership checks
+
+### 3. Project Management
+
+Demonstrates:
+- Date calculations
+- Progress tracking
+- Health scores
+
+## Running the Examples
+
+```bash
+npm run dev
+```
+
+This will:
+1. Initialize the ObjectQL engine
+2. Register objects with formulas
+3. Create sample records
+4. Query and display formula results
+
+## Key Concepts
+
+### Formula Field Definition
+
+```yaml
+full_name:
+  type: formula
+  formula: "first_name + ' ' + last_name"
+  data_type: text
+  label: Full Name
+```
+
+### System Variables
+
+- `$today` - Current date
+- `$now` - Current timestamp
+- `$current_user.id` - Current user ID
+- `$year`, `$month`, `$day` - Date components
+
+### Supported Operations
+
+- Arithmetic: `+`, `-`, `*`, `/`, `%`, `**`
+- Comparison: `===`, `!==`, `>`, `<`, `>=`, `<=`
+- Logical: `&&`, `||`, `!`
+- Conditional: Ternary operator, if/else blocks
+- String methods: `.toUpperCase()`, `.toLowerCase()`, `.trim()`, etc.
+- Math functions: `Math.round()`, `Math.max()`, etc.
+
+## See Also
+
+- [Formula Specification](../../docs/spec/formula.md)
+- [Formulas & Rules Guide](../../docs/guide/formulas-and-rules.md)

examples/tutorials/tutorial-formulas/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@objectql/tutorial-formulas",
+  "version": "1.8.4",
+  "private": true,
+  "description": "Tutorial demonstrating Formula Engine in ObjectQL",
+  "main": "src/index.ts",
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@objectql/core": "workspace:*",
+    "@objectql/types": "workspace:*",
+    "@objectql/driver-sql": "workspace:*",
+    "sqlite3": "^5.1.7"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.28",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}

examples/tutorials/tutorial-formulas/src/index.ts

@@ -0,0 +1,82 @@
+/**
+ * Formula Engine Tutorial
+ * 
+ * This tutorial demonstrates the formula engine capabilities in ObjectQL.
+ * Run with: npm run dev
+ */
+
+import { ObjectQL } from '@objectql/core';
+import { SqlDriver } from '@objectql/driver-sql';
+
+async function main() {
+  console.log('🚀 ObjectQL Formula Engine Tutorial\n');
+
+  // Initialize ObjectQL with in-memory SQLite
+  const driver = new SqlDriver({
+    client: 'sqlite3',
+    connection: { filename: ':memory:' },
+    useNullAsDefault: true,
+  });
+
+  const app = new ObjectQL({
+    datasources: { default: driver },
+  });
+
+  // E-COMMERCE ORDER EXAMPLE
+  console.log('📦 Example 1: E-commerce Order with Price Calculations\n');
+
+  app.registerObject({
+    name: 'order',
+    fields: {
+      product_name: { type: 'text', required: true },
+      quantity: { type: 'number', required: true },
+      unit_price: { type: 'currency', required: true },
+      discount_rate: { type: 'percent', defaultValue: 0 },
+      tax_rate: { type: 'percent', defaultValue: 8 },
+      
+      // Formula fields
+      subtotal: {
+        type: 'formula',
+        formula: 'quantity * unit_price',
+        data_type: 'currency',
+        label: 'Subtotal',
+      },
+      final_price: {
+        type: 'formula',
+        formula: 'quantity * unit_price * (1 - discount_rate / 100) * (1 + tax_rate / 100)',
+        data_type: 'currency',
+        label: 'Final Price',
+      },
+      discount_amount: {
+        type: 'formula',
+        formula: 'quantity * unit_price * (discount_rate / 100)',
+        data_type: 'currency',
+        label: 'You Save',
+      },
+    },
+  });
+
+  await app.init();
+
+  const ctx = app.createContext({ isSystem: true });
+
+  // Create sample order
+  const order = await ctx.object('order').create({
+    product_name: 'Premium Laptop',
+    quantity: 2,
+    unit_price: 1299.99,
+    discount_rate: 15,
+    tax_rate: 8,
+  });
+
+  console.log('📦 Order Created:');
+  console.log('  Subtotal: $' + order.subtotal?.toFixed(2));
+  console.log('  You Save: $' + order.discount_amount?.toFixed(2));
+  console.log('  Final Price: $' + order.final_price?.toFixed(2));
+
+  console.log('\n✅ Tutorial complete!\n');
+
+  await app.close();
+}
+
+main().catch(console.error);

examples/tutorials/tutorial-formulas/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"]
+}