Query Protocol: Add comprehensive test coverage and documentation for aggregations, joins, and window functions

[Copilot]

Implements Week 1-2 roadmap: comprehensive testing and documentation for ObjectQL query capabilities (aggregations, joins, window functions, subqueries).

Changes

Test Coverage (query.test.ts)

Expanded from 28 to 85 tests covering:

• Aggregations (24 tests): COUNT/SUM/AVG/MIN/MAX, COUNT DISTINCT, GROUP BY (single/multiple fields), HAVING clauses
• Joins (27 tests): INNER/LEFT/RIGHT/FULL OUTER, multi-table joins, self-joins, subquery joins
• Window Functions (25 tests): ROW_NUMBER, RANK, DENSE_RANK, LAG/LEAD, aggregate window functions, frame specifications (ROWS/RANGE)

Documentation (query.zod.ts)

Enhanced JSDoc with SQL/SOQL comparison examples and performance considerations:

/**
 * Aggregation Function Enum
 * 
 * Performance Considerations:
 * - COUNT(*) is typically faster than COUNT(field) as it doesn't check for nulls
 * - COUNT DISTINCT may require additional memory for tracking unique values
 * - Window aggregates (with OVER clause) can be more efficient than subqueries
 * 
 * @example
 * // SQL: SELECT region, SUM(amount) FROM sales GROUP BY region
 * {
 *   object: 'sales',
 *   aggregations: [{ function: 'sum', field: 'amount', alias: 'total_sales' }],
 *   groupBy: ['region']
 * }
 */

Reference Guide (QUERY_PROTOCOL_GUIDE.md)

Complete guide with 50+ examples demonstrating:

• Aggregation patterns with SQL equivalents
• Join strategies with SOQL comparisons
• Window function use cases (ranking, time-series analysis, running totals)
• Subquery patterns in joins and filters

Example Usage

// Customer lifetime value with rankings
{
  object: 'customer',
  joins: [{ type: 'left', object: 'order', on: ['customer.id', '=', 'order.customer_id'] }],
  aggregations: [
    { function: 'count', field: 'order.id', alias: 'order_count' },
    { function: 'sum', field: 'order.amount', alias: 'lifetime_value' }
  ],
  groupBy: ['customer.id'],
  windowFunctions: [{
    function: 'rank',
    alias: 'customer_rank',
    over: { orderBy: [{ field: 'lifetime_value', order: 'desc' }] }
  }]
}

Notes

• Driver capability flags (queryAggregations, queryWindowFunctions, querySubqueries, joins) already present in driver.zod.ts
• All schemas existed; enhancements are documentation and test coverage only

Original prompt

Week 1-2: Query Protocol Enhancement

Day 1-3: Aggregation Support

Define AggregationSchema in query.zod.ts
Add support for: COUNT, SUM, AVG, MIN, MAX, GROUP BY, HAVING
Write 20+ tests for aggregation scenarios
Document with SQL comparison examples
Day 4-7: Join Support

Define JoinSchema in query.zod.ts
Add support for: INNER, LEFT, RIGHT, FULL OUTER joins
Write 25+ tests for join scenarios
Document with Salesforce SOQL comparison examples
Day 8-10: Subqueries & Window Functions

Define SubquerySchema in query.zod.ts
Add window function support (ROW_NUMBER, RANK, LAG, LEAD)
Write 20+ tests
Update driver.zod.ts to reflect capability flags

---

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

[vercel]

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

Project	Deployment	Review	Updated (UTC)
spec	Error		Jan 21, 2026 1:06pm

[github-actions]

This PR is very large. Consider breaking it into smaller PRs for easier review.