squirreling 0.5.0 → 0.6.0

package/README.md

@@ -40,7 +40,10 @@ const users = [
   // ...more rows
 ]
 
-type AsyncRow = Record<string, AsyncCell>
+interface AsyncRow {
+  columns: string[]
+  cells: Record<string, AsyncCell>
+}
 type AsyncCell = () => Promise<SqlPrimitive>
 
 // Returns an async iterable of rows with async cells
@@ -76,6 +79,7 @@ console.log(allUsers)
 - `GROUP BY` and `HAVING` clauses
 - Aggregate functions: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `JSON_ARRAYAGG`
 - String functions: `CONCAT`, `SUBSTRING`, `LENGTH`, `UPPER`, `LOWER`
+- Math functions: `ABS`, `CEIL`, `FLOOR`, `ROUND`, `MOD`, `RAND`, `RANDOM`, `LN`, `LOG10`, `EXP`, `POWER`, `SQRT`, `SIN`, `COS`, `TAN`, `COT`, `ASIN`, `ACOS`, `ATAN`, `ATAN2`, `DEGREES`, `RADIANS`, `PI`
 - Date functions: `CURRENT_DATE`, `CURRENT_TIME`, `CURRENT_TIMESTAMP`, `INTERVAL`
 - Json functions: `JSON_VALUE`, `JSON_QUERY`, `JSON_OBJECT`
 - Basic expressions and arithmetic operations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Squirreling SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",

package/src/backend/dataSource.js

@@ -1,5 +1,5 @@
 /**
- * @import { AsyncDataSource, AsyncRow, SqlPrimitive } from '../types.js'
+ * @import { AsyncCell, AsyncCells, AsyncDataSource, AsyncRow, SqlPrimitive } from '../types.js'
  */
 
 
@@ -11,7 +11,7 @@
  */
 export function generatorSource(gen) {
   return {
-    async *getRows() {
+    async *scan() {
       yield* gen
     },
   }
@@ -24,12 +24,12 @@ export function generatorSource(gen) {
  * @returns {AsyncRow} a row accessor interface
  */
 function asyncRow(obj) {
-  /** @type {AsyncRow} */
-  const row = {}
+  /** @type {AsyncCells} */
+  const cells = {}
   for (const [key, value] of Object.entries(obj)) {
-    row[key] = () => Promise.resolve(value)
+    cells[key] = () => Promise.resolve(value)
   }
-  return row
+  return { columns: Object.keys(obj), cells }
 }
 
 /**
@@ -40,7 +40,7 @@ function asyncRow(obj) {
  */
 export function memorySource(data) {
   return {
-    async *getRows() {
+    async *scan() {
       for (const item of data) {
         yield asyncRow(item)
       }
@@ -60,15 +60,16 @@ export function cachedDataSource(source) {
     /**
      * @yields {AsyncRow}
      */
-    async *getRows() {
+    async *scan() {
       let index = 0
-      for await (const row of source.getRows()) {
+      for await (const row of source.scan()) {
         const rowIndex = index
-        /** @type {AsyncRow} */
-        const out = {}
-        for (const [key, cell] of Object.entries(row)) {
+        /** @type {AsyncCells} */
+        const cells = {}
+        for (const key of row.columns) {
+          const cell = row.cells[key]
           // Wrap the cell to cache accesses
-          out[key] = () => {
+          cells[key] = () => {
             const cacheKey = `${rowIndex}:${key}`
             let value = cache.get(cacheKey)
             if (!value) {
@@ -78,7 +79,7 @@ export function cachedDataSource(source) {
             return value
           }
         }
-        yield out
+        yield { columns: row.columns, cells }
         index++
       }
     },

package/src/execute/execute.js

@@ -10,7 +10,7 @@ import { executeJoins } from './join.js'
 import { compareForTerm, defaultDerivedAlias, stringify } from './utils.js'
 
 /**
- * @import { AsyncDataSource, AsyncRow, ExecuteSqlOptions, OrderByItem, QueryHints, SelectStatement, SqlPrimitive } from '../types.js'
+ * @import { AsyncCells, AsyncDataSource, AsyncRow, ExecuteSqlOptions, OrderByItem, QueryHints, SelectStatement, SqlPrimitive } from '../types.js'
  */
 
 /**
@@ -20,7 +20,7 @@ import { compareForTerm, defaultDerivedAlias, stringify } from './utils.js'
  * @yields {AsyncRow} async generator yielding result rows
  */
 export async function* executeSql({ tables, query }) {
-  const select = parseSql(query)
+  const select = typeof query === 'string' ? parseSql(query) : query
 
   // Check for unsupported operations
   if (!select.from) {
@@ -81,15 +81,15 @@ export async function* executeSelect(select, tables) {
 /**
  * Creates a stable string key for a row to enable deduplication
  *
- * @param {AsyncRow} row
+ * @param {AsyncCells} cells
  * @returns {Promise<string>} a stable string representation of the row
  */
-async function stableRowKey(row) {
-  const keys = Object.keys(row).sort()
+async function stableRowKey(cells) {
+  const keys = Object.keys(cells).sort()
   /** @type {string[]} */
   const parts = []
   for (const k of keys) {
-    const v = await row[k]()
+    const v = await cells[k]()
     parts.push(k + ':' + stringify(v))
   }
   return parts.join('|')
@@ -109,7 +109,7 @@ async function applyDistinct(rows, distinct) {
   /** @type {AsyncRow[]} */
   const result = []
   for (const row of rows) {
-    const key = await stableRowKey(row)
+    const key = await stableRowKey(row.cells)
     if (seen.has(key)) continue
     seen.add(key)
     result.push(row)
@@ -255,7 +255,7 @@ async function* evaluateStreaming(select, dataSource, tables) {
     offset: select.offset,
   }
 
-  for await (const row of dataSource.getRows(hints)) {
+  for await (const row of dataSource.scan(hints)) {
     rowIndex++
     // WHERE filter
     if (select.where) {
@@ -270,17 +270,21 @@ async function* evaluateStreaming(select, dataSource, tables) {
     }
 
     // SELECT projection
-    /** @type {AsyncRow} */
-    const outRow = {}
+    /** @type {string[]} */
+    const columns = []
+    /** @type {AsyncCells} */
+    const cells = {}
     const currentRowIndex = rowIndex
     for (const col of select.columns) {
       if (col.kind === 'star') {
-        for (const [key, cell] of Object.entries(row)) {
-          outRow[key] = cell
+        for (const key of row.columns) {
+          columns.push(key)
+          cells[key] = row.cells[key]
         }
       } else if (col.kind === 'derived') {
         const alias = col.alias ?? defaultDerivedAlias(col.expr)
-        outRow[alias] = () => evaluateExpr({ node: col.expr, row, tables, rowIndex: currentRowIndex })
+        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'
@@ -290,7 +294,7 @@ async function* evaluateStreaming(select, dataSource, tables) {
 
     // DISTINCT: skip duplicate rows
     if (seen) {
-      const key = await stableRowKey(outRow)
+      const key = await stableRowKey(cells)
       if (seen.has(key)) continue
       seen.add(key)
       // OFFSET applies to distinct rows
@@ -300,7 +304,7 @@ async function* evaluateStreaming(select, dataSource, tables) {
       }
     }
 
-    yield outRow
+    yield { columns, cells }
     rowsYielded++
     if (rowsYielded >= limit) {
       break
@@ -330,7 +334,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.getRows(hints)) {
+  for await (const row of dataSource.scan(hints)) {
     working.push(row)
   }
 
@@ -392,14 +396,16 @@ async function* evaluateBuffered(select, dataSource, tables, hasAggregate, useGr
     }
 
     for (const group of groups) {
-      /** @type {AsyncRow} */
-      const resultRow = {}
+      const columns = []
+      /** @type {AsyncCells} */
+      const cells = {}
       for (const col of select.columns) {
         if (col.kind === 'star') {
           const firstRow = group[0]
           if (firstRow) {
-            for (const [key, cell] of Object.entries(firstRow)) {
-              resultRow[key] = cell
+            for (const key of firstRow.columns) {
+              columns.push(key)
+              cells[key] = firstRow.cells[key]
             }
           }
           continue
@@ -407,29 +413,32 @@ 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) {
-            resultRow[alias] = () => evaluateExpr({ node: col.expr, row: group[0], tables })
+            cells[alias] = () => evaluateExpr({ node: col.expr, row: group[0], tables })
           } else {
-            delete resultRow[alias]
+            delete cells[alias]
           }
           continue
         }
 
         if (col.kind === 'aggregate') {
           const alias = col.alias ?? defaultAggregateAlias(col)
-          resultRow[alias] = () => evaluateAggregate({ col, rows: group, tables })
+          columns.push(alias)
+          cells[alias] = () => evaluateAggregate({ col, rows: group, tables })
           continue
         }
       }
+      const asyncRow = { columns, cells }
 
       // Apply HAVING filter before adding to projected results
       if (select.having) {
-        if (!await evaluateHavingExpr(select.having, resultRow, group, tables)) {
+        if (!await evaluateHavingExpr(select.having, asyncRow, group, tables)) {
           continue
         }
       }
 
-      projected.push(resultRow)
+      projected.push(asyncRow)
     }
   } else {
     // No grouping, simple projection
@@ -446,19 +455,22 @@ async function* evaluateBuffered(select, dataSource, tables, hasAggregate, useGr
     }
 
     for (const row of rowsToProject) {
-      /** @type {AsyncRow} */
-      const outRow = {}
+      const columns = []
+      /** @type {AsyncCells} */
+      const cells = {}
       for (const col of select.columns) {
         if (col.kind === 'star') {
-          for (const [key, cell] of Object.entries(row)) {
-            outRow[key] = cell
+          for (const key of row.columns) {
+            columns.push(key)
+            cells[key] = row.cells[key]
           }
         } else if (col.kind === 'derived') {
           const alias = col.alias ?? defaultDerivedAlias(col.expr)
-          outRow[alias] = () => evaluateExpr({ node: col.expr, row, tables })
+          columns.push(alias)
+          cells[alias] = () => evaluateExpr({ node: col.expr, row, tables })
         }
       }
-      projected.push(outRow)
+      projected.push({ columns, cells })
     }
   }
 

package/src/execute/expression.js

@@ -32,14 +32,14 @@ export async function evaluateExpr({ node, row, tables, rowIndex }) {
 
   if (node.type === 'identifier') {
     // Try exact match first (handles both qualified and unqualified names)
-    if (row[node.name]) {
-      return row[node.name]()
+    if (row.cells[node.name]) {
+      return row.cells[node.name]()
     }
     // For qualified names like 'users.id', also try just the column part
     if (node.name.includes('.')) {
       const colName = node.name.split('.').pop()
-      if (colName && row[colName]) {
-        return row[colName]()
+      if (colName && row.cells[colName]) {
+        return row.cells[colName]()
       }
     }
     return null
@@ -48,13 +48,10 @@ 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 first = await gen.next() // Start the generator
+    const { value } = await gen.next() // Start the generator
     gen.return(undefined) // Stop further execution
-    if (!first.value) return null
-    /** @type {AsyncRow} */
-    const firstRow = first.value
-    const firstKey = Object.keys(firstRow)[0]
-    return firstRow[firstKey]()
+    if (!value) return null
+    return value.cells[value.columns[0]]()
   }
 
   // Unary operators
@@ -484,14 +481,11 @@ export async function evaluateExpr({ node, row, tables, rowIndex }) {
   if (node.type === 'in') {
     const exprVal = await evaluateExpr({ node: node.expr, row, tables, rowIndex })
     const results = executeSelect(node.subquery, tables)
-    /** @type {SqlPrimitive[]} */
-    const values = []
     for await (const resRow of results) {
-      const firstKey = Object.keys(resRow)[0]
-      const val = await resRow[firstKey]()
-      values.push(val)
+      const value = await resRow.cells[resRow.columns[0]]()
+      if (exprVal === value) return true
     }
-    return values.includes(exprVal)
+    return false
   }
 
   // EXISTS and NOT EXISTS with subqueries

package/src/execute/join.js

@@ -4,7 +4,7 @@ import { evaluateExpr } from './expression.js'
 import { stringify } from './utils.js'
 
 /**
- * @import { AsyncRow, AsyncDataSource, JoinClause, ExprNode } from '../types.js'
+ * @import { AsyncRow, AsyncDataSource, JoinClause, ExprNode, AsyncCells } from '../types.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.getRows()) {
+    for await (const row of rightSource.scan()) {
       rightRows.push(row)
     }
 
@@ -39,9 +39,9 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
 
     // Return streaming data source - left rows stream through without buffering
     return {
-      async *getRows() {
+      async *scan() {
         yield* hashJoin({
-          leftRows: leftSource.getRows(), // Stream directly, not buffered
+          leftRows: leftSource.scan(), // Stream directly, not buffered
           rightRows,
           join,
           leftTable: currentLeftTable,
@@ -55,7 +55,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.getRows()) {
+  for await (const row of leftSource.scan()) {
     leftRows.push(row)
   }
 
@@ -69,7 +69,7 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
 
     /** @type {AsyncRow[]} */
     const rightRows = []
-    for await (const row of rightSource.getRows()) {
+    for await (const row of rightSource.scan()) {
       rightRows.push(row)
     }
 
@@ -105,7 +105,7 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
 
   /** @type {AsyncRow[]} */
   const rightRows = []
-  for await (const row of rightSource.getRows()) {
+  for await (const row of rightSource.scan()) {
     rightRows.push(row)
   }
 
@@ -113,7 +113,7 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
   const lastRightTableName = lastJoin.alias ?? lastJoin.table
 
   return {
-    async *getRows() {
+    async *scan() {
       yield* hashJoin({
         leftRows,
         rightRows,
@@ -172,12 +172,12 @@ function extractJoinKeys(onCondition, leftTable, rightTable) {
  * @returns {AsyncRow}
  */
 function createNullRow(columnNames) {
-  /** @type {AsyncRow} */
-  const row = {}
+  /** @type {AsyncCells} */
+  const cells = {}
   for (const col of columnNames) {
-    row[col] = () => Promise.resolve(null)
+    cells[col] = () => Promise.resolve(null)
   }
-  return row
+  return { columns: columnNames, cells }
 }
 
 /**
@@ -190,33 +190,35 @@ function createNullRow(columnNames) {
  * @returns {AsyncRow}
  */
 function mergeRows(leftRow, rightRow, leftTable, rightTable) {
-  /** @type {AsyncRow} */
-  const merged = {}
+  const columns = []
+  /** @type {AsyncCells} */
+  const cells = {}
 
   // Add left table columns with prefix
-  for (const [key, cell] of Object.entries(leftRow)) {
+  for (const [key, cell] of Object.entries(leftRow.cells)) {
     // Skip already-prefixed keys (from previous joins)
     if (!key.includes('.')) {
-      merged[`${leftTable}.${key}`] = cell
-    } else {
-      merged[key] = cell
+      const alias = `${leftTable}.${key}`
+      cells[alias] = cell
     }
-    // Also keep unqualified name for convenience (may be overwritten if ambiguous)
-    merged[key] = cell
+    // Also keep unqualified name for convenience
+    columns.push(key)
+    cells[key] = cell
   }
 
   // Add right table columns with prefix
-  for (const [key, cell] of Object.entries(rightRow)) {
+  for (const [key, cell] of Object.entries(rightRow.cells)) {
     if (!key.includes('.')) {
-      merged[`${rightTable}.${key}`] = cell
+      cells[`${rightTable}.${key}`] = cell
     } else {
-      merged[key] = cell
+      cells[key] = cell
     }
     // Unqualified name (overwrites if same name exists in left table)
-    merged[key] = cell
+    columns.push(key)
+    cells[key] = cell
   }
 
-  return merged
+  return { columns, cells }
 }
 
 /**
@@ -245,7 +247,7 @@ async function* hashJoin({ leftRows, rightRows, join, leftTable, rightTable, tab
   const keys = extractJoinKeys(onCondition, leftTable, rightTable)
 
   // Get column names for NULL row generation (right side is always buffered)
-  const rightCols = rightRows.length ? Object.keys(rightRows[0]) : []
+  const rightCols = rightRows.length ? rightRows[0].columns : []
   const rightPrefixedCols = rightCols.flatMap(col =>
     col.includes('.') ? [col] : [`${rightTable}.${col}`, col]
   )
@@ -281,8 +283,7 @@ async function* hashJoin({ leftRows, rightRows, join, leftTable, rightTable, tab
     for await (const leftRow of leftRows) {
       // Capture left column info from first row (for NULL row generation)
       if (!leftPrefixedCols) {
-        const leftCols = Object.keys(leftRow)
-        leftPrefixedCols = leftCols.flatMap(col =>
+        leftPrefixedCols = leftRow.columns.flatMap(col =>
           col.includes('.') ? [col] : [`${leftTable}.${col}`, col]
         )
       }
@@ -323,8 +324,7 @@ async function* hashJoin({ leftRows, rightRows, join, leftTable, rightTable, tab
     for await (const leftRow of leftRows) {
       // Capture left column info from first row (for NULL row generation)
       if (!leftPrefixedCols) {
-        const leftCols = Object.keys(leftRow)
-        leftPrefixedCols = leftCols.flatMap(col =>
+        leftPrefixedCols = leftRow.columns.flatMap(col =>
           col.includes('.') ? [col] : [`${leftTable}.${col}`, col]
         )
       }

package/src/execute/math.js

@@ -1,5 +1,5 @@
 /**
- * @import { SqlPrimitive } from '../types.js'
+ * @import { MathFunc, SqlPrimitive } from '../types.js'
  */
 import { argCountError } from '../validationErrors.js'
 
@@ -7,7 +7,7 @@ import { argCountError } from '../validationErrors.js'
  * Evaluate a math function
  *
  * @param {Object} options
- * @param {string} options.funcName - Uppercase function name
+ * @param {MathFunc} options.funcName - Uppercase function name
  * @param {SqlPrimitive[]} options.args - Function arguments
  * @param {number} options.positionStart - Start position in query
  * @param {number} options.positionEnd - End position in query
@@ -161,5 +161,180 @@ export function evaluateMathFunc({ funcName, args, positionStart, positionEnd, r
     return Math.sqrt(Number(val))
   }
 
-  return undefined
+  if (funcName === 'SIN') {
+    if (args.length !== 1) {
+      throw argCountError({
+        funcName: 'SIN',
+        expected: 1,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const val = args[0]
+    if (val == null) return null
+    return Math.sin(Number(val))
+  }
+
+  if (funcName === 'COS') {
+    if (args.length !== 1) {
+      throw argCountError({
+        funcName: 'COS',
+        expected: 1,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const val = args[0]
+    if (val == null) return null
+    return Math.cos(Number(val))
+  }
+
+  if (funcName === 'TAN') {
+    if (args.length !== 1) {
+      throw argCountError({
+        funcName: 'TAN',
+        expected: 1,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const val = args[0]
+    if (val == null) return null
+    return Math.tan(Number(val))
+  }
+
+  if (funcName === 'COT') {
+    if (args.length !== 1) {
+      throw argCountError({
+        funcName: 'COT',
+        expected: 1,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const val = args[0]
+    if (val == null) return null
+    return 1 / Math.tan(Number(val))
+  }
+
+  if (funcName === 'ASIN') {
+    if (args.length !== 1) {
+      throw argCountError({
+        funcName: 'ASIN',
+        expected: 1,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const val = args[0]
+    if (val == null) return null
+    return Math.asin(Number(val))
+  }
+
+  if (funcName === 'ACOS') {
+    if (args.length !== 1) {
+      throw argCountError({
+        funcName: 'ACOS',
+        expected: 1,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const val = args[0]
+    if (val == null) return null
+    return Math.acos(Number(val))
+  }
+
+  if (funcName === 'ATAN') {
+    if (args.length !== 1) {
+      throw argCountError({
+        funcName: 'ATAN',
+        expected: 1,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const val = args[0]
+    if (val == null) return null
+    return Math.atan(Number(val))
+  }
+
+  if (funcName === 'ATAN2') {
+    if (args.length !== 2) {
+      throw argCountError({
+        funcName: 'ATAN2',
+        expected: 2,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const y = args[0]
+    const x = args[1]
+    if (y == null || x == null) return null
+    return Math.atan2(Number(y), Number(x))
+  }
+
+  if (funcName === 'DEGREES') {
+    if (args.length !== 1) {
+      throw argCountError({
+        funcName: 'DEGREES',
+        expected: 1,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const val = args[0]
+    if (val == null) return null
+    return Number(val) * 180 / Math.PI
+  }
+
+  if (funcName === 'RADIANS') {
+    if (args.length !== 1) {
+      throw argCountError({
+        funcName: 'RADIANS',
+        expected: 1,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const val = args[0]
+    if (val == null) return null
+    return Number(val) * Math.PI / 180
+  }
+
+  if (funcName === 'PI') {
+    if (args.length !== 0) {
+      throw argCountError({
+        funcName: 'PI',
+        expected: 0,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    return Math.PI
+  }
+
+  return null
 }

package/src/execute/utils.js

@@ -97,8 +97,8 @@ export async function collect(asyncRows) {
   for await (const asyncRow of asyncRows) {
     /** @type {Record<string, SqlPrimitive>} */
     const item = {}
-    for (const [key, cell] of Object.entries(asyncRow)) {
-      item[key] = await cell()
+    for (const key of asyncRow.columns) {
+      item[key] = await asyncRow.cells[key]()
     }
     results.push(item)
   }

package/src/executionErrors.js

@@ -7,12 +7,13 @@
  */
 export class ExecutionError extends Error {
   /**
-   * @param {string} message - Human-readable error message
-   * @param {number} positionStart - Start position (0-based character offset)
-   * @param {number} positionEnd - End position (exclusive, 0-based character offset)
-   * @param {number} [rowNumber] - 1-based row number where error occurred
+   * @param {Object} options
+   * @param {string} options.message - Human-readable error message
+   * @param {number} options.positionStart - Start position (0-based character offset)
+   * @param {number} options.positionEnd - End position (exclusive, 0-based character offset)
+   * @param {number} [options.rowNumber] - 1-based row number where error occurred
    */
-  constructor(message, positionStart, positionEnd, rowNumber) {
+  constructor({ message, positionStart, positionEnd, rowNumber }) {
     const rowSuffix = rowNumber != null ? ` (row ${rowNumber})` : ''
     super(message + rowSuffix)
     this.name = 'ExecutionError'
@@ -45,7 +46,7 @@ export function tableNotFoundError({ tableName }) {
  * @returns {ExecutionError}
  */
 export function invalidContextError({ item, validContext, positionStart, positionEnd, rowNumber }) {
-  return new ExecutionError(`${item} can only be used with ${validContext}`, positionStart, positionEnd, rowNumber)
+  return new ExecutionError({ message: `${item} can only be used with ${validContext}`, positionStart, positionEnd, rowNumber })
 }
 
 /**

package/src/parseErrors.js

@@ -7,11 +7,12 @@
  */
 export class ParseError extends Error {
   /**
-   * @param {string} message - Human-readable error message
-   * @param {number} positionStart - Start position (0-based character offset)
-   * @param {number} positionEnd - End position (exclusive, 0-based character offset)
+   * @param {Object} options
+   * @param {string} options.message - Human-readable error message
+   * @param {number} options.positionStart - Start position (0-based character offset)
+   * @param {number} options.positionEnd - End position (exclusive, 0-based character offset)
    */
-  constructor(message, positionStart, positionEnd) {
+  constructor({ message, positionStart, positionEnd }) {
     super(message)
     this.name = 'ParseError'
     this.positionStart = positionStart
@@ -32,7 +33,7 @@ export class ParseError extends Error {
  */
 export function syntaxError({ expected, received, positionStart, positionEnd, after }) {
   const afterClause = after ? ` after "${after}"` : ''
-  return new ParseError(`Expected ${expected}${afterClause} but found ${received} at position ${positionStart}`, positionStart, positionEnd)
+  return new ParseError({ message: `Expected ${expected}${afterClause} but found ${received} at position ${positionStart}`, positionStart, positionEnd })
 }
 
 /**
@@ -45,7 +46,7 @@ export function syntaxError({ expected, received, positionStart, positionEnd, af
  */
 export function unterminatedError(type, positionStart, positionEnd) {
   const name = type === 'string' ? 'string literal' : 'identifier'
-  return new ParseError(`Unterminated ${name} starting at position ${positionStart}`, positionStart, positionEnd)
+  return new ParseError({ message: `Unterminated ${name} starting at position ${positionStart}`, positionStart, positionEnd })
 }
 
 /**
@@ -61,7 +62,7 @@ export function unterminatedError(type, positionStart, positionEnd) {
  */
 export function invalidLiteralError({ type, value, positionStart, positionEnd, validValues }) {
   const suffix = validValues ? `. Valid values: ${validValues}` : ''
-  return new ParseError(`Invalid ${type} ${value} at position ${positionStart}${suffix}`, positionStart, positionEnd)
+  return new ParseError({ message: `Invalid ${type} ${value} at position ${positionStart}${suffix}`, positionStart, positionEnd })
 }
 
 /**
@@ -76,9 +77,9 @@ export function invalidLiteralError({ type, value, positionStart, positionEnd, v
 export function unexpectedCharError({ char, positionStart, expectsSelect = false }) {
   const positionEnd = positionStart + 1
   if (expectsSelect) {
-    return new ParseError(`Expected SELECT but found "${char}" at position ${positionStart}. Queries must start with SELECT.`, positionStart, positionEnd)
+    return new ParseError({ message: `Expected SELECT but found "${char}" at position ${positionStart}. Queries must start with SELECT.`, positionStart, positionEnd })
   }
-  return new ParseError(`Unexpected character "${char}" at position ${positionStart}`, positionStart, positionEnd)
+  return new ParseError({ message: `Unexpected character "${char}" at position ${positionStart}`, positionStart, positionEnd })
 }
 
 /**
@@ -95,11 +96,11 @@ export function unknownFunctionError({ funcName, positionStart, positionEnd, val
   const supported = validFunctions ||
     'COUNT, SUM, AVG, MIN, MAX, UPPER, LOWER, CONCAT, LENGTH, SUBSTRING, TRIM, REPLACE, FLOOR, CEIL, ABS, MOD, EXP, LN, LOG10, POWER, SQRT, JSON_OBJECT, JSON_VALUE, JSON_QUERY, JSON_ARRAYAGG'
 
-  return new ParseError(
-    `Unknown function "${funcName}" at position ${positionStart}. Supported: ${supported}`,
+  return new ParseError({
+    message: `Unknown function "${funcName}" at position ${positionStart}. Supported: ${supported}`,
     positionStart,
-    positionEnd
-  )
+    positionEnd,
+  })
 }
 
 /**
@@ -113,5 +114,5 @@ export function unknownFunctionError({ funcName, positionStart, positionEnd, val
  * @returns {ParseError}
  */
 export function missingClauseError({ missing, context, positionStart, positionEnd }) {
-  return new ParseError(`${context} requires ${missing}`, positionStart ?? 0, positionEnd ?? 0)
+  return new ParseError({ message: `${context} requires ${missing}`, positionStart: positionStart ?? 0, positionEnd: positionEnd ?? 0 })
 }

package/src/types.d.ts

@@ -20,16 +20,20 @@ export interface QueryHints {
  * Provides an async iterator over rows.
  */
 export interface AsyncDataSource {
-  getRows(hints?: QueryHints): AsyncIterable<AsyncRow>
+  scan(hints?: QueryHints): AsyncIterable<AsyncRow>
 }
-export type AsyncRow = Record<string, AsyncCell>
+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
+  query: string | SelectStatement
 }
 
 export type SqlPrimitive =
@@ -188,6 +192,17 @@ export type MathFunc =
   | 'LOG10'
   | 'POWER'
   | 'SQRT'
+  | 'SIN'
+  | 'COS'
+  | 'TAN'
+  | 'COT'
+  | 'ASIN'
+  | 'ACOS'
+  | 'ATAN'
+  | 'ATAN2'
+  | 'DEGREES'
+  | 'RADIANS'
+  | 'PI'
 
 export type StringFunc =
   | 'UPPER'

package/src/validation.js

@@ -16,6 +16,8 @@ export function isMathFunc(name) {
   return [
     'FLOOR', 'CEIL', 'CEILING', 'ABS', 'MOD',
     'EXP', 'LN', 'LOG10', 'POWER', 'SQRT',
+    'SIN', 'COS', 'TAN', 'COT', 'ASIN', 'ACOS', 'ATAN', 'ATAN2',
+    'DEGREES', 'RADIANS', 'PI',
   ].includes(name)
 }
 

package/src/validationErrors.js

@@ -38,6 +38,17 @@ const FUNCTION_SIGNATURES = {
   LOG10: 'number',
   POWER: 'base, exponent',
   SQRT: 'number',
+  SIN: 'radians',
+  COS: 'radians',
+  TAN: 'radians',
+  COT: 'radians',
+  ASIN: 'number',
+  ACOS: 'number',
+  ATAN: 'number',
+  ATAN2: 'y, x',
+  DEGREES: 'radians',
+  RADIANS: 'degrees',
+  PI: '',
 
   // JSON functions
   JSON_VALUE: 'expression, path',
@@ -74,7 +85,7 @@ export function argCountError({ funcName, expected, received, positionStart, pos
     expectedStr = `${expected} argument`
   }
 
-  return new ExecutionError(`${funcName}(${signature}) function requires ${expectedStr}, got ${received}`, positionStart, positionEnd, rowNumber)
+  return new ExecutionError({ message: `${funcName}(${signature}) function requires ${expectedStr}, got ${received}`, positionStart, positionEnd, rowNumber })
 }
 
 /**
@@ -92,7 +103,7 @@ export function argCountError({ funcName, expected, received, positionStart, pos
 export function argValueError({ funcName, message, positionStart, positionEnd, hint, rowNumber }) {
   const signature = FUNCTION_SIGNATURES[funcName] ?? ''
   const suffix = hint ? `. ${hint}` : ''
-  return new ExecutionError(`${funcName}(${signature}): ${message}${suffix}`, positionStart, positionEnd, rowNumber)
+  return new ExecutionError({ message: `${funcName}(${signature}): ${message}${suffix}`, positionStart, positionEnd, rowNumber })
 }
 
 /**
@@ -123,5 +134,5 @@ export function castError({ toType, positionStart, positionEnd, fromType, rowNum
     ? `Cannot CAST ${fromType} to ${toType}`
     : `Unsupported CAST to type ${toType}`
 
-  return new ExecutionError(`${message}. Supported types: TEXT, VARCHAR, INTEGER, INT, BIGINT, FLOAT, REAL, DOUBLE, BOOLEAN`, positionStart, positionEnd, rowNumber)
+  return new ExecutionError({ message: `${message}. Supported types: TEXT, VARCHAR, INTEGER, INT, BIGINT, FLOAT, REAL, DOUBLE, BOOLEAN`, positionStart, positionEnd, rowNumber })
 }