squirreling 0.6.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Squirreling SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -37,11 +37,11 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "24.10.2",
-    "@vitest/coverage-v8": "4.0.15",
-    "eslint": "9.39.1",
+    "@types/node": "24.10.4",
+    "@vitest/coverage-v8": "4.0.16",
+    "eslint": "9.39.2",
     "eslint-plugin-jsdoc": "61.5.0",
     "typescript": "5.9.3",
-    "vitest": "4.0.15"
+    "vitest": "4.0.16"
   }
 }

package/src/backend/dataSource.js

@@ -1,8 +1,7 @@
 /**
- * @import { AsyncCell, AsyncCells, AsyncDataSource, AsyncRow, SqlPrimitive } from '../types.js'
+ * @import { AsyncCell, AsyncCells, AsyncDataSource, AsyncRow, ScanOptions, SqlPrimitive } from '../types.js'
  */
 
-
 /**
  * Wraps an async generator of plain objects into an AsyncDataSource
  *
@@ -11,8 +10,11 @@
  */
 export function generatorSource(gen) {
   return {
-    async *scan() {
-      yield* gen
+    async *scan({ signal }) {
+      for await (const row of gen) {
+        if (signal?.aborted) break
+        yield row
+      }
     },
   }
 }
@@ -40,8 +42,9 @@ function asyncRow(obj) {
  */
 export function memorySource(data) {
   return {
-    async *scan() {
+    async *scan({ signal }) {
       for (const item of data) {
+        if (signal?.aborted) break
         yield asyncRow(item)
       }
     },
@@ -58,11 +61,14 @@ export function cachedDataSource(source) {
   const cache = new Map()
   return {
     /**
+     * @param {ScanOptions} options
      * @yields {AsyncRow}
      */
-    async *scan() {
+    async *scan(options) {
+      const { signal } = options
       let index = 0
-      for await (const row of source.scan()) {
+      for await (const row of source.scan(options)) {
+        if (signal?.aborted) break
         const rowIndex = index
         /** @type {AsyncCells} */
         const cells = {}

package/src/execute/columns.js

@@ -1,7 +1,46 @@
+import { isAggregateFunc } from '../validation.js'
+
 /**
  * @import { ExprNode, SelectStatement, SelectColumn } from '../types.js'
  */
 
+/**
+ * Checks if an expression contains any aggregate function calls
+ *
+ * @param {ExprNode | undefined} expr
+ * @returns {boolean}
+ */
+export function containsAggregate(expr) {
+  if (!expr) return false
+  if (expr.type === 'function' && isAggregateFunc(expr.name.toUpperCase())) {
+    return true
+  }
+  if (expr.type === 'binary') {
+    return containsAggregate(expr.left) || containsAggregate(expr.right)
+  }
+  if (expr.type === 'unary') {
+    return containsAggregate(expr.argument)
+  }
+  if (expr.type === 'cast') {
+    return containsAggregate(expr.expr)
+  }
+  if (expr.type === 'case') {
+    if (expr.caseExpr && containsAggregate(expr.caseExpr)) return true
+    for (const when of expr.whenClauses) {
+      if (containsAggregate(when.condition) || containsAggregate(when.result)) return true
+    }
+    if (containsAggregate(expr.elseResult)) return true
+  }
+  if (expr.type === 'in valuelist') {
+    if (containsAggregate(expr.expr)) return true
+    for (const val of expr.values) {
+      if (containsAggregate(val)) return true
+    }
+  }
+  // Note: Don't recurse into subqueries - they have their own aggregate scope
+  return false
+}
+
 /**
  * Extracts column names needed from a SELECT statement.
  *
@@ -50,11 +89,6 @@ export function extractColumns(select) {
 function collectColumnsFromSelectColumn(col, columns) {
   if (col.kind === 'derived') {
     collectColumnsFromExpr(col.expr, columns)
-  } else if (col.kind === 'aggregate') {
-    if (col.arg.kind === 'expression') {
-      collectColumnsFromExpr(col.arg.expr, columns)
-    }
-    // 'star' aggregate (COUNT(*)) doesn't reference specific columns
   }
   // 'star' columns handled separately (returns undefined for all columns)
 }

package/src/execute/execute.js

@@ -2,8 +2,7 @@ import { missingClauseError } from '../parseErrors.js'
 import { tableNotFoundError, unsupportedOperationError } from '../executionErrors.js'
 import { generatorSource, memorySource } from '../backend/dataSource.js'
 import { parseSql } from '../parse/parse.js'
-import { defaultAggregateAlias, evaluateAggregate } from './aggregates.js'
-import { extractColumns } from './columns.js'
+import { containsAggregate, extractColumns } from './columns.js'
 import { evaluateExpr } from './expression.js'
 import { evaluateHavingExpr } from './having.js'
 import { executeJoins } from './join.js'
@@ -19,7 +18,7 @@ import { compareForTerm, defaultDerivedAlias, stringify } from './utils.js'
  * @param {ExecuteSqlOptions} options - the execution options
  * @yields {AsyncRow} async generator yielding result rows
  */
-export async function* executeSql({ tables, query }) {
+export async function* executeSql({ tables, query, signal }) {
   const select = typeof query === 'string' ? parseSql(query) : query
 
   // Check for unsupported operations
@@ -41,17 +40,23 @@ export async function* executeSql({ tables, query }) {
     }
   }
 
-  yield* executeSelect(select, normalizedTables)
+  yield* executeSelect({ select, tables: normalizedTables, signal })
 }
 
+/**
+ * @typedef {Object} ExecuteSelectOptions
+ * @property {SelectStatement} select
+ * @property {Record<string, AsyncDataSource>} tables
+ * @property {AbortSignal} [signal]
+ */
+
 /**
  * Executes a SELECT query against the provided tables
  *
- * @param {SelectStatement} select
- * @param {Record<string, AsyncDataSource>} tables
+ * @param {ExecuteSelectOptions} options
  * @yields {AsyncRow}
  */
-export async function* executeSelect(select, tables) {
+export async function* executeSelect({ select, tables, signal }) {
   /** @type {AsyncDataSource} */
   let dataSource
   /** @type {string} */
@@ -67,7 +72,7 @@ export async function* executeSelect(select, tables) {
   } else {
     // Nested subquery - recursively resolve
     fromTableName = select.from.alias
-    dataSource = generatorSource(executeSelect(select.from.query, tables))
+    dataSource = generatorSource(executeSelect({ select: select.from.query, tables, signal }))
   }
 
   // Execute JOINs if present
@@ -75,7 +80,7 @@ export async function* executeSelect(select, tables) {
     dataSource = await executeJoins(dataSource, select.joins, fromTableName, tables)
   }
 
-  yield* evaluateSelectAst(select, dataSource, tables)
+  yield* evaluateSelectAst({ select, dataSource, tables, signal })
 }
 
 /**
@@ -201,40 +206,52 @@ async function sortRows(rows, orderBy, tables) {
   return groups.flat().map(i => rows[i])
 }
 
+/**
+ * @typedef {Object} EvaluateSelectAstOptions
+ * @property {SelectStatement} select
+ * @property {AsyncDataSource} dataSource
+ * @property {Record<string, AsyncDataSource>} tables
+ * @property {AbortSignal} [signal]
+ */
+
 /**
  * Evaluates a select with a resolved FROM data source
  *
- * @param {SelectStatement} select
- * @param {AsyncDataSource} dataSource
- * @param {Record<string, AsyncDataSource>} tables
+ * @param {EvaluateSelectAstOptions} options
  * @yields {AsyncRow}
  */
-async function* evaluateSelectAst(select, dataSource, tables) {
+async function* evaluateSelectAst({ select, dataSource, tables, signal }) {
   // SQL priority: from, where, group by, having, select, order by, offset, limit
 
-  const hasAggregate = select.columns.some(col => col.kind === 'aggregate')
+  const hasAggregate = select.columns.some(col => col.kind === 'derived' && containsAggregate(col.expr))
   const useGrouping = hasAggregate || select.groupBy.length > 0
   const needsBuffering = useGrouping || select.orderBy.length > 0
 
   if (needsBuffering) {
     // BUFFERING PATH: Collect all rows, process, then yield
-    yield* evaluateBuffered(select, dataSource, tables, hasAggregate, useGrouping)
+    yield* evaluateBuffered({ select, dataSource, tables, hasAggregate, useGrouping, signal })
   } else {
     // STREAMING PATH: Yield rows one by one
-    yield* evaluateStreaming(select, dataSource, tables)
+    yield* evaluateStreaming({ select, dataSource, tables, signal })
   }
 }
 
+/**
+ * @typedef {Object} EvaluateStreamingOptions
+ * @property {SelectStatement} select
+ * @property {AsyncDataSource} dataSource
+ * @property {Record<string, AsyncDataSource>} tables
+ * @property {AbortSignal} [signal]
+ */
+
 /**
  * Streaming evaluation for simple queries (no ORDER BY or GROUP BY)
  * Supports DISTINCT by tracking seen row keys without buffering full rows
  *
- * @param {SelectStatement} select
- * @param {AsyncDataSource} dataSource
- * @param {Record<string, AsyncDataSource>} tables
+ * @param {EvaluateStreamingOptions} options
  * @yields {AsyncRow}
  */
-async function* evaluateStreaming(select, dataSource, tables) {
+async function* evaluateStreaming({ select, dataSource, tables, signal }) {
   let rowsYielded = 0
   let rowsSkipped = 0
   let rowIndex = 0
@@ -255,7 +272,7 @@ async function* evaluateStreaming(select, dataSource, tables) {
     offset: select.offset,
   }
 
-  for await (const row of dataSource.scan(hints)) {
+  for await (const row of dataSource.scan({ hints, signal })) {
     rowIndex++
     // WHERE filter
     if (select.where) {
@@ -285,10 +302,6 @@ async function* evaluateStreaming(select, dataSource, tables) {
         const alias = col.alias ?? defaultDerivedAlias(col.expr)
         columns.push(alias)
         cells[alias] = () => evaluateExpr({ node: col.expr, row, tables, rowIndex: currentRowIndex })
-      } else if (col.kind === 'aggregate') {
-        throw new Error(
-          'Aggregate functions require GROUP BY or will act on the whole dataset; add GROUP BY or remove aggregates'
-        )
       }
     }
 
@@ -312,17 +325,23 @@ async function* evaluateStreaming(select, dataSource, tables) {
   }
 }
 
+/**
+ * @typedef {Object} EvaluateBufferedOptions
+ * @property {SelectStatement} select
+ * @property {AsyncDataSource} dataSource
+ * @property {Record<string, AsyncDataSource>} tables
+ * @property {boolean} hasAggregate
+ * @property {boolean} useGrouping
+ * @property {AbortSignal} [signal]
+ */
+
 /**
  * Buffered evaluation for complex queries (with ORDER BY or GROUP BY)
  *
- * @param {SelectStatement} select
- * @param {AsyncDataSource} dataSource
- * @param {Record<string, AsyncDataSource>} tables
- * @param {boolean} hasAggregate
- * @param {boolean} useGrouping
+ * @param {EvaluateBufferedOptions} options
  * @yields {AsyncRow}
  */
-async function* evaluateBuffered(select, dataSource, tables, hasAggregate, useGrouping) {
+async function* evaluateBuffered({ select, dataSource, tables, hasAggregate, useGrouping, signal }) {
   // Build hints for data source optimization
   // Note: limit/offset not passed here since buffering needs all rows for sorting/grouping
   /** @type {QueryHints} */
@@ -334,7 +353,7 @@ async function* evaluateBuffered(select, dataSource, tables, hasAggregate, useGr
   // Step 1: Collect all rows from data source
   /** @type {AsyncRow[]} */
   const working = []
-  for await (const row of dataSource.scan(hints)) {
+  for await (const row of dataSource.scan({ hints, signal })) {
     working.push(row)
   }
 
@@ -414,18 +433,9 @@ async function* evaluateBuffered(select, dataSource, tables, hasAggregate, useGr
         if (col.kind === 'derived') {
           const alias = col.alias ?? defaultDerivedAlias(col.expr)
           columns.push(alias)
-          if (group.length > 0) {
-            cells[alias] = () => evaluateExpr({ node: col.expr, row: group[0], tables })
-          } else {
-            delete cells[alias]
-          }
-          continue
-        }
-
-        if (col.kind === 'aggregate') {
-          const alias = col.alias ?? defaultAggregateAlias(col)
-          columns.push(alias)
-          cells[alias] = () => evaluateAggregate({ col, rows: group, tables })
+          // Pass group to evaluateExpr so it can handle aggregate functions within expressions
+          // For empty groups, still provide an empty row context for aggregates to return appropriate values
+          cells[alias] = () => evaluateExpr({ node: col.expr, row: group[0] ?? { columns: [], cells: {} }, tables, rows: group })
           continue
         }
       }

package/src/execute/expression.js

@@ -1,11 +1,12 @@
 import { unknownFunctionError } from '../parseErrors.js'
 import { invalidContextError } from '../executionErrors.js'
 import {
+  aggregateError,
   argCountError,
   argValueError,
   castError,
 } from '../validationErrors.js'
-import { isMathFunc } from '../validation.js'
+import { isAggregateFunc, isMathFunc } from '../validation.js'
 import { applyIntervalToDate } from './date.js'
 import { executeSelect } from './execute.js'
 import { evaluateMathFunc } from './math.js'
@@ -23,9 +24,10 @@ import { applyBinaryOp, stringify } from './utils.js'
  * @param {AsyncRow} params.row - The data row to evaluate against
  * @param {Record<string, AsyncDataSource>} params.tables
  * @param {number} [params.rowIndex] - 1-based row index for error reporting
+ * @param {AsyncRow[]} [params.rows] - Group of rows for aggregate functions
  * @returns {Promise<SqlPrimitive>} The result of the evaluation
  */
-export async function evaluateExpr({ node, row, tables, rowIndex }) {
+export async function evaluateExpr({ node, row, tables, rowIndex, rows }) {
   if (node.type === 'literal') {
     return node.value
   }
@@ -47,7 +49,7 @@ export async function evaluateExpr({ node, row, tables, rowIndex }) {
 
   // Scalar subquery - returns a single value
   if (node.type === 'subquery') {
-    const gen = executeSelect(node.subquery, tables)
+    const gen = executeSelect({ select: node.subquery, tables })
     const { value } = await gen.next() // Start the generator
     gen.return(undefined) // Stop further execution
     if (!value) return null
@@ -57,16 +59,16 @@ export async function evaluateExpr({ node, row, tables, rowIndex }) {
   // Unary operators
   if (node.type === 'unary') {
     if (node.op === 'NOT') {
-      return !await evaluateExpr({ node: node.argument, row, tables, rowIndex })
+      return !await evaluateExpr({ node: node.argument, row, tables, rowIndex, rows })
     }
     if (node.op === 'IS NULL') {
-      return await evaluateExpr({ node: node.argument, row, tables, rowIndex }) == null
+      return await evaluateExpr({ node: node.argument, row, tables, rowIndex, rows }) == null
     }
     if (node.op === 'IS NOT NULL') {
-      return await evaluateExpr({ node: node.argument, row, tables, rowIndex }) != null
+      return await evaluateExpr({ node: node.argument, row, tables, rowIndex, rows }) != null
     }
     if (node.op === '-') {
-      const val = await evaluateExpr({ node: node.argument, row, tables, rowIndex })
+      const val = await evaluateExpr({ node: node.argument, row, tables, rowIndex, rows })
       if (val == null) return null
       return -val
     }
@@ -76,15 +78,15 @@ export async function evaluateExpr({ node, row, tables, rowIndex }) {
   if (node.type === 'binary') {
     // Handle date +/- interval at AST level
     if ((node.op === '+' || node.op === '-') && node.right.type === 'interval') {
-      const dateVal = await evaluateExpr({ node: node.left, row, tables, rowIndex })
+      const dateVal = await evaluateExpr({ node: node.left, row, tables, rowIndex, rows })
       return applyIntervalToDate(dateVal, node.right.value, node.right.unit, node.op)
     }
     if (node.op === '+' && node.left.type === 'interval') {
-      const dateVal = await evaluateExpr({ node: node.right, row, tables, rowIndex })
+      const dateVal = await evaluateExpr({ node: node.right, row, tables, rowIndex, rows })
       return applyIntervalToDate(dateVal, node.left.value, node.left.unit, '+')
     }
 
-    const left = await evaluateExpr({ node: node.left, row, tables, rowIndex })
+    const left = await evaluateExpr({ node: node.left, row, tables, rowIndex, rows })
 
     // Short-circuit evaluation for AND and OR
     if (node.op === 'AND') {
@@ -94,15 +96,120 @@ export async function evaluateExpr({ node, row, tables, rowIndex }) {
       if (left) return true
     }
 
-    const right = await evaluateExpr({ node: node.right, row, tables, rowIndex })
+    const right = await evaluateExpr({ node: node.right, row, tables, rowIndex, rows })
     return applyBinaryOp(node.op, left, right)
   }
 
   // Function calls
   if (node.type === 'function') {
     const funcName = node.name.toUpperCase()
+
+    // Handle aggregate functions
+    if (isAggregateFunc(funcName)) {
+      if (!rows) {
+        throw aggregateError({
+          funcName,
+          issue: 'requires GROUP BY or will act on the whole dataset',
+        })
+      }
+
+      // Check for star argument (COUNT(*))
+      if (node.args.length === 1 && node.args[0].type === 'identifier' && node.args[0].name === '*') {
+        if (funcName === 'COUNT') {
+          return rows.length
+        }
+        throw aggregateError({
+          funcName,
+          issue: '(*) is not supported, use a column name',
+        })
+      }
+
+      if (node.args.length !== 1) {
+        throw argCountError({
+          funcName,
+          expected: 1,
+          received: node.args.length,
+          positionStart: node.positionStart,
+          positionEnd: node.positionEnd,
+          rowNumber: rowIndex,
+        })
+      }
+
+      const argNode = node.args[0]
+
+      if (funcName === 'COUNT') {
+        if (node.distinct) {
+          const seen = new Set()
+          for (const r of rows) {
+            const v = await evaluateExpr({ node: argNode, row: r, tables })
+            if (v != null) seen.add(v)
+          }
+          return seen.size
+        }
+        let count = 0
+        for (const r of rows) {
+          const v = await evaluateExpr({ node: argNode, row: r, tables })
+          if (v != null) count++
+        }
+        return count
+      }
+
+      if (funcName === 'SUM' || funcName === 'AVG' || funcName === 'MIN' || funcName === 'MAX') {
+        let sum = 0
+        let count = 0
+        /** @type {number | null} */
+        let min = null
+        /** @type {number | null} */
+        let max = null
+
+        for (const r of rows) {
+          const raw = await evaluateExpr({ node: argNode, row: r, tables })
+          if (raw == null) continue
+          const num = Number(raw)
+          if (!Number.isFinite(num)) continue
+
+          if (count === 0) {
+            min = num
+            max = num
+          } else {
+            if (min == null || num < min) min = num
+            if (max == null || num > max) max = num
+          }
+          sum += num
+          count++
+        }
+
+        if (funcName === 'SUM') return sum
+        if (funcName === 'AVG') return count === 0 ? null : sum / count
+        if (funcName === 'MIN') return min
+        if (funcName === 'MAX') return max
+      }
+
+      if (funcName === 'JSON_ARRAYAGG') {
+        /** @type {SqlPrimitive[]} */
+        const values = []
+        if (node.distinct) {
+          const seen = new Set()
+          for (const r of rows) {
+            const v = await evaluateExpr({ node: argNode, row: r, tables })
+            const key = stringify(v)
+            if (!seen.has(key)) {
+              seen.add(key)
+              values.push(v)
+            }
+          }
+        } else {
+          for (const r of rows) {
+            const v = await evaluateExpr({ node: argNode, row: r, tables })
+            values.push(v)
+          }
+        }
+        return values
+      }
+    }
+
     /** @type {SqlPrimitive[]} */
-    const args = await Promise.all(node.args.map(arg => evaluateExpr({ node: arg, row, tables, rowIndex })))
+    const args = await Promise.all(node.args.map(arg => evaluateExpr({ node: arg, row, tables, rowIndex, rows })))
 
     if (funcName === 'UPPER') {
       if (args.length !== 1) {
@@ -427,7 +534,7 @@ export async function evaluateExpr({ node, row, tables, rowIndex }) {
   }
 
   if (node.type === 'cast') {
-    const val = await evaluateExpr({ node: node.expr, row, tables, rowIndex })
+    const val = await evaluateExpr({ node: node.expr, row, tables, rowIndex, rows })
     if (val == null) return null
     const toType = node.toType.toUpperCase()
     if (toType === 'TEXT' || toType === 'STRING' || toType === 'VARCHAR') {
@@ -470,17 +577,17 @@ export async function evaluateExpr({ node, row, tables, rowIndex }) {
 
   // IN and NOT IN with value lists
   if (node.type === 'in valuelist') {
-    const exprVal = await evaluateExpr({ node: node.expr, row, tables, rowIndex })
+    const exprVal = await evaluateExpr({ node: node.expr, row, tables, rowIndex, rows })
     for (const valueNode of node.values) {
-      const val = await evaluateExpr({ node: valueNode, row, tables, rowIndex })
+      const val = await evaluateExpr({ node: valueNode, row, tables, rowIndex, rows })
       if (exprVal === val) return true
     }
     return false
   }
   // IN with subqueries
   if (node.type === 'in') {
-    const exprVal = await evaluateExpr({ node: node.expr, row, tables, rowIndex })
-    const results = executeSelect(node.subquery, tables)
+    const exprVal = await evaluateExpr({ node: node.expr, row, tables, rowIndex, rows })
+    const results = executeSelect({ select: node.subquery, tables })
     for await (const resRow of results) {
       const value = await resRow.cells[resRow.columns[0]]()
       if (exprVal === value) return true
@@ -490,39 +597,39 @@ export async function evaluateExpr({ node, row, tables, rowIndex }) {
 
   // EXISTS and NOT EXISTS with subqueries
   if (node.type === 'exists') {
-    const results = await executeSelect(node.subquery, tables).next()
+    const results = await executeSelect({ select: node.subquery, tables }).next()
     return results.done === false
   }
   if (node.type === 'not exists') {
-    const results = await executeSelect(node.subquery, tables).next()
+    const results = await executeSelect({ select: node.subquery, tables }).next()
     return results.done === true
   }
 
   // CASE expressions
   if (node.type === 'case') {
     // For simple CASE: evaluate the case expression once
-    const caseValue = node.caseExpr && await evaluateExpr({ node: node.caseExpr, row, tables, rowIndex })
+    const caseValue = node.caseExpr && await evaluateExpr({ node: node.caseExpr, row, tables, rowIndex, rows })
 
     // Iterate through WHEN clauses
     for (const whenClause of node.whenClauses) {
       let conditionResult
       if (caseValue !== undefined) {
         // Simple CASE: compare caseValue with condition
-        const whenValue = await evaluateExpr({ node: whenClause.condition, row, tables, rowIndex })
+        const whenValue = await evaluateExpr({ node: whenClause.condition, row, tables, rowIndex, rows })
         conditionResult = caseValue === whenValue
       } else {
         // Searched CASE: evaluate condition as boolean
-        conditionResult = await evaluateExpr({ node: whenClause.condition, row, tables, rowIndex })
+        conditionResult = await evaluateExpr({ node: whenClause.condition, row, tables, rowIndex, rows })
       }
 
       if (conditionResult) {
-        return evaluateExpr({ node: whenClause.result, row, tables, rowIndex })
+        return evaluateExpr({ node: whenClause.result, row, tables, rowIndex, rows })
       }
     }
 
     // No WHEN clause matched, return ELSE result or NULL
     if (node.elseResult) {
-      return evaluateExpr({ node: node.elseResult, row, tables, rowIndex })
+      return evaluateExpr({ node: node.elseResult, row, tables, rowIndex, rows })
     }
     return null
   }

package/src/execute/join.js

@@ -30,7 +30,7 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
     // Buffer right rows for hash index (required for hash join)
     /** @type {AsyncRow[]} */
     const rightRows = []
-    for await (const row of rightSource.scan()) {
+    for await (const row of rightSource.scan({})) {
       rightRows.push(row)
     }
 
@@ -39,14 +39,16 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
 
     // Return streaming data source - left rows stream through without buffering
     return {
-      async *scan() {
+      async *scan(options) {
+        const { signal } = options
         yield* hashJoin({
-          leftRows: leftSource.scan(), // Stream directly, not buffered
+          leftRows: leftSource.scan(options), // Stream directly, not buffered
           rightRows,
           join,
           leftTable: currentLeftTable,
           rightTable: rightTableName,
           tables,
+          signal,
         })
       },
     }
@@ -55,7 +57,7 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
   // Multiple joins: buffer intermediate results, stream final join
   /** @type {AsyncRow[]} */
   let leftRows = []
-  for await (const row of leftSource.scan()) {
+  for await (const row of leftSource.scan({})) {
     leftRows.push(row)
   }
 
@@ -69,7 +71,7 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
 
     /** @type {AsyncRow[]} */
     const rightRows = []
-    for await (const row of rightSource.scan()) {
+    for await (const row of rightSource.scan({})) {
       rightRows.push(row)
     }
 
@@ -105,7 +107,7 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
 
   /** @type {AsyncRow[]} */
   const rightRows = []
-  for await (const row of rightSource.scan()) {
+  for await (const row of rightSource.scan({})) {
     rightRows.push(row)
   }
 
@@ -113,7 +115,8 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
   const lastRightTableName = lastJoin.alias ?? lastJoin.table
 
   return {
-    async *scan() {
+    async *scan(options) {
+      const { signal } = options
       yield* hashJoin({
         leftRows,
         rightRows,
@@ -121,6 +124,7 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
         leftTable: currentLeftTable,
         rightTable: lastRightTableName,
         tables,
+        signal,
       })
     },
   }
@@ -232,9 +236,10 @@ function mergeRows(leftRow, rightRow, leftTable, rightTable) {
  * @param {string} params.leftTable - name of left table (for column prefixing)
  * @param {string} params.rightTable - name of right table (for column prefixing, may be alias)
  * @param {Record<string, AsyncDataSource>} params.tables - all tables for expression evaluation
+ * @param {AbortSignal} [params.signal] - abort signal for cancellation
  * @yields {AsyncRow} joined rows
  */
-async function* hashJoin({ leftRows, rightRows, join, leftTable, rightTable, tables }) {
+async function* hashJoin({ leftRows, rightRows, join, leftTable, rightTable, tables, signal }) {
   const { joinType, on: onCondition } = join
 
   if (!onCondition) {
@@ -281,6 +286,7 @@ async function* hashJoin({ leftRows, rightRows, join, leftTable, rightTable, tab
 
     // PROBE PHASE: Stream through left rows, yield matches immediately
     for await (const leftRow of leftRows) {
+      if (signal?.aborted) break
       // Capture left column info from first row (for NULL row generation)
       if (!leftPrefixedCols) {
         leftPrefixedCols = leftRow.columns.flatMap(col =>
@@ -322,6 +328,7 @@ async function* hashJoin({ leftRows, rightRows, join, leftTable, rightTable, tab
     const matchedRightRows = joinType === 'RIGHT' || joinType === 'FULL' ? new Set() : null
 
     for await (const leftRow of leftRows) {
+      if (signal?.aborted) break
       // Capture left column info from first row (for NULL row generation)
       if (!leftPrefixedCols) {
         leftPrefixedCols = leftRow.columns.flatMap(col =>

package/src/execute/utils.js

@@ -132,6 +132,10 @@ export function defaultDerivedAlias(expr) {
     return defaultDerivedAlias(expr.left) + '_' + expr.op + '_' + defaultDerivedAlias(expr.right)
   }
   if (expr.type === 'function') {
+    // Handle aggregate functions with star (COUNT(*) -> count_all)
+    if (expr.args.length === 1 && expr.args[0].type === 'identifier' && expr.args[0].name === '*') {
+      return expr.name.toLowerCase() + '_all'
+    }
     return expr.name.toLowerCase() + '_' + expr.args.map(defaultDerivedAlias).join('_')
   }
   if (expr.type === 'interval') {

package/src/parse/expression.js

@@ -133,6 +133,15 @@ export function parsePrimary(state) {
 
       /** @type {ExprNode[]} */
       const args = []
+      let distinct = false
+
+      // Check for DISTINCT or ALL keyword (for aggregate functions like COUNT(DISTINCT x))
+      if (current(state).type === 'keyword' && current(state).value === 'DISTINCT') {
+        consume(state) // consume DISTINCT
+        distinct = true
+      } else if (current(state).type === 'keyword' && current(state).value === 'ALL') {
+        consume(state) // consume ALL (default behavior, just consume it)
+      }
 
       if (current(state).type !== 'paren' || current(state).value !== ')') {
         while (true) {
@@ -156,10 +165,21 @@ export function parsePrimary(state) {
 
       expect(state, 'paren', ')')
 
+      // Aggregate functions require at least one argument
+      if (isAggregateFunc(funcName) && args.length === 0) {
+        throw syntaxError({
+          expected: 'expression',
+          received: '")"',
+          positionStart: positionStart + funcName.length + 1, // position after opening paren
+          positionEnd: lastPosition(state),
+        })
+      }
+
       return {
         type: 'function',
         name: funcName,
         args,
+        distinct: distinct || undefined,
         positionStart,
         positionEnd: lastPosition(state),
       }

package/src/parse/parse.js

@@ -1,11 +1,11 @@
 import { tokenize } from './tokenize.js'
 import { parseExpression } from './expression.js'
-import { RESERVED_AFTER_COLUMN, RESERVED_AFTER_TABLE, isAggregateFunc } from '../validation.js'
+import { RESERVED_AFTER_COLUMN, RESERVED_AFTER_TABLE } from '../validation.js'
 import { consume, current, expect, expectIdentifier, match, parseError, peekToken } from './state.js'
 import { parseJoins } from './joins.js'
 
 /**
- * @import { AggregateColumn, AggregateArg, AggregateFunc, ExprNode, FromSubquery, FromTable, OrderByItem, ParserState, SelectStatement, SelectColumn } from '../types.js'
+ * @import { ExprNode, FromSubquery, FromTable, OrderByItem, ParserState, SelectStatement, SelectColumn } from '../types.js'
  */
 
 /**
@@ -79,61 +79,12 @@ function parseSelectItem(state) {
     throw parseError(state, 'column name or expression')
   }
 
-  const next = peekToken(state, 1)
-  if (next.type === 'paren' && next.value === '(') {
-    const upper = tok.value.toUpperCase()
-    if (isAggregateFunc(upper)) {
-      expectIdentifier(state) // consume function name
-      return parseAggregateItem(state, upper)
-    }
-  }
-
-  // Delegate to expression parser
+  // Delegate to expression parser (handles all expressions including aggregates)
   const expr = parseExpression(state)
   const alias = parseAs(state)
   return { kind: 'derived', expr, alias }
 }
 
-/**
- * @param {ParserState} state
- * @param {AggregateFunc} func
- * @returns {AggregateColumn}
- */
-function parseAggregateItem(state, func) {
-  expect(state, 'paren', '(')
-
-  /** @type {AggregateArg} */
-  let arg
-
-  const cur = current(state)
-  if (cur.type === 'operator' && cur.value === '*') {
-    consume(state)
-    arg = { kind: 'star' }
-  } else {
-    /** @type {'all' | 'distinct'} */
-    let quantifier = 'all'
-    if (cur.type === 'keyword' && cur.value === 'ALL') {
-      consume(state) // consume ALL
-    } else if (cur.type === 'keyword' && cur.value === 'DISTINCT') {
-      consume(state)
-      quantifier = 'distinct'
-    }
-
-    const expr = parseExpression(state)
-    arg = {
-      kind: 'expression',
-      expr,
-      quantifier,
-    }
-  }
-
-  expect(state, 'paren', ')')
-
-  const alias = parseAs(state)
-
-  return { kind: 'aggregate', func, arg, alias }
-}
-
 /**
  * Parses an optional table alias (e.g., "FROM users u" or "FROM users AS u")
  * @param {ParserState} state

package/src/types.d.ts

@@ -1,4 +1,31 @@
+// executeSql(options)
+export interface ExecuteSqlOptions {
+  tables: Record<string, Row | AsyncDataSource>
+  query: string | SelectStatement
+  signal?: AbortSignal
+}
+
+// AsyncRow represents a row with async cell values
+export interface AsyncRow {
+  columns: string[]
+  cells: AsyncCells
+}
+export type AsyncCells = Record<string, AsyncCell>
+export type AsyncCell = () => Promise<SqlPrimitive>
+
+export type Row = Record<string, SqlPrimitive>[]
 
+/**
+ * Async data source for streaming SQL execution.
+ * Provides an async iterator over rows.
+ */
+export interface AsyncDataSource {
+  scan(options: ScanOptions): AsyncIterable<AsyncRow>
+}
+export interface ScanOptions {
+  hints?: QueryHints
+  signal?: AbortSignal
+}
 /**
  * Hints passed to data sources for query optimization.
  * All hints are optional and "best effort" - sources may ignore them.
@@ -15,27 +42,6 @@ export interface QueryHints {
   offset?: number
 }
 
-/**
- * Async data source for streaming SQL execution.
- * Provides an async iterator over rows.
- */
-export interface AsyncDataSource {
-  scan(hints?: QueryHints): AsyncIterable<AsyncRow>
-}
-export interface AsyncRow {
-  columns: string[]
-  cells: AsyncCells
-}
-export type AsyncCells = Record<string, AsyncCell>
-export type AsyncCell = () => Promise<SqlPrimitive>
-
-export type Row = Record<string, SqlPrimitive>[]
-
-export interface ExecuteSqlOptions {
-  tables: Record<string, Row | AsyncDataSource>
-  query: string | SelectStatement
-}
-
 export type SqlPrimitive =
   | string
   | number
@@ -109,6 +115,7 @@ export interface FunctionNode extends ExprNodeBase {
   type: 'function'
   name: string
   args: ExprNode[]
+  distinct?: boolean
 }
 
 export interface CastNode extends ExprNodeBase {
@@ -220,32 +227,13 @@ export type StringFunc =
   | 'CURRENT_TIME'
   | 'CURRENT_TIMESTAMP'
 
-export interface AggregateArgStar {
-  kind: 'star'
-}
-
-export interface AggregateArgExpression {
-  kind: 'expression'
-  expr: ExprNode
-  quantifier: 'all' | 'distinct'
-}
-
-export type AggregateArg = AggregateArgStar | AggregateArgExpression
-
-export interface AggregateColumn {
-  kind: 'aggregate'
-  func: AggregateFunc
-  arg: AggregateArg
-  alias?: string
-}
-
 export interface DerivedColumn {
   kind: 'derived'
   expr: ExprNode
   alias?: string
 }
 
-export type SelectColumn = StarColumn | AggregateColumn | DerivedColumn
+export type SelectColumn = StarColumn | DerivedColumn
 
 export interface OrderByItem {
   expr: ExprNode

package/src/execute/aggregates.js

@@ -1,119 +0,0 @@
-import { unknownFunctionError } from '../parseErrors.js'
-import { aggregateError } from '../validationErrors.js'
-import { evaluateExpr } from './expression.js'
-import { defaultDerivedAlias, stringify } from './utils.js'
-
-/**
- * Evaluates an aggregate function over a set of rows
- *
- * @import { AggregateColumn, AsyncDataSource, AsyncRow, SqlPrimitive } from '../types.js'
- * @param {Object} options
- * @param {AggregateColumn} options.col - aggregate column definition
- * @param {AsyncRow[]} options.rows - rows to aggregate
- * @param {Record<string, AsyncDataSource>} options.tables
- * @returns {Promise<SqlPrimitive>} aggregated result
- */
-export async function evaluateAggregate({ col, rows, tables }) {
-  const { arg, func } = col
-
-  if (func === 'COUNT') {
-    if (arg.kind === 'star') return rows.length
-    if (arg.quantifier === 'distinct') {
-      const seen = new Set()
-      for (const row of rows) {
-        const v = await evaluateExpr({ node: arg.expr, row, tables })
-        if (v != null) {
-          seen.add(v)
-        }
-      }
-      return seen.size
-    }
-    let count = 0
-    for (const row of rows) {
-      const v = await evaluateExpr({ node: arg.expr, row, tables })
-      if (v != null) {
-        count += 1
-      }
-    }
-    return count
-  }
-
-  if (func === 'SUM' || func === 'AVG' || func === 'MIN' || func === 'MAX') {
-    if (arg.kind === 'star') {
-      throw aggregateError({ funcName: func, issue: '(*) is not supported, use a column name' })
-    }
-    let sum = 0
-    let count = 0
-    /** @type {number | null} */
-    let min = null
-    /** @type {number | null} */
-    let max = null
-
-    for (const row of rows) {
-      const raw = await evaluateExpr({ node: arg.expr, row, tables })
-      if (raw == null) continue
-      const num = Number(raw)
-      if (!Number.isFinite(num)) continue
-
-      if (count === 0) {
-        min = num
-        max = num
-      } else {
-        if (min == null || num < min) min = num
-        if (max == null || num > max) max = num
-      }
-      sum += num
-      count += 1
-    }
-
-    if (func === 'SUM') return sum
-    if (func === 'AVG') return count === 0 ? null : sum / count
-    if (func === 'MIN') return min
-    if (func === 'MAX') return max
-  }
-
-  if (func === 'JSON_ARRAYAGG') {
-    if (arg.kind === 'star') {
-      throw aggregateError({ funcName: 'JSON_ARRAYAGG', issue: '(*) is not supported, use a column name or expression' })
-    }
-    /** @type {SqlPrimitive[]} */
-    const values = []
-    if (arg.quantifier === 'distinct') {
-      const seen = new Set()
-      for (const row of rows) {
-        const v = await evaluateExpr({ node: arg.expr, row, tables })
-        const key = stringify(v)
-        if (!seen.has(key)) {
-          seen.add(key)
-          values.push(v)
-        }
-      }
-    } else {
-      for (const row of rows) {
-        const v = await evaluateExpr({ node: arg.expr, row, tables })
-        values.push(v)
-      }
-    }
-    return values
-  }
-
-  throw unknownFunctionError({
-    funcName: func,
-    positionStart: 0,
-    positionEnd: 0,
-    validFunctions: 'COUNT, SUM, AVG, MIN, MAX, JSON_ARRAYAGG',
-  })
-}
-
-/**
- * Generates a default alias name for an aggregate function
- * (e.g., "count_all", "sum_amount")
- *
- * @param {AggregateColumn} col
- * @returns {string}
- */
-export function defaultAggregateAlias(col) {
-  const base = col.func.toLowerCase()
-  if (col.arg.kind === 'star') return base + '_all'
-  return base + '_' + defaultDerivedAlias(col.arg.expr)
-}