squirreling 0.4.8 → 0.6.0

package/src/execute/join.js

@@ -1,9 +1,10 @@
-import { missingClauseError, tableNotFoundError } from '../errors.js'
+import { missingClauseError } from '../parseErrors.js'
+import { tableNotFoundError } from '../executionErrors.js'
 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'
  */
 
 /**
@@ -23,13 +24,13 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
     const join = joins[0]
     const rightSource = tables[join.table]
     if (rightSource === undefined) {
-      throw tableNotFoundError(join.table)
+      throw tableNotFoundError({ tableName: join.table })
     }
 
     // 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)
     }
 
@@ -38,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,
@@ -54,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)
   }
 
@@ -63,12 +64,12 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
     const join = joins[i]
     const rightSource = tables[join.table]
     if (rightSource === undefined) {
-      throw tableNotFoundError(join.table)
+      throw tableNotFoundError({ tableName: join.table })
     }
 
     /** @type {AsyncRow[]} */
     const rightRows = []
-    for await (const row of rightSource.getRows()) {
+    for await (const row of rightSource.scan()) {
       rightRows.push(row)
     }
 
@@ -99,12 +100,12 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
   const lastJoin = joins[joins.length - 1]
   const rightSource = tables[lastJoin.table]
   if (rightSource === undefined) {
-    throw tableNotFoundError(lastJoin.table)
+    throw tableNotFoundError({ tableName: lastJoin.table })
   }
 
   /** @type {AsyncRow[]} */
   const rightRows = []
-  for await (const row of rightSource.getRows()) {
+  for await (const row of rightSource.scan()) {
     rightRows.push(row)
   }
 
@@ -112,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,
@@ -171,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 }
 }
 
 /**
@@ -189,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 }
 }
 
 /**
@@ -244,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]
   )
@@ -280,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]
         )
       }
@@ -322,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

@@ -0,0 +1,340 @@
+/**
+ * @import { MathFunc, SqlPrimitive } from '../types.js'
+ */
+import { argCountError } from '../validationErrors.js'
+
+/**
+ * Evaluate a math function
+ *
+ * @param {Object} options
+ * @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
+ * @param {number} [options.rowNumber] - 1-based row number for error reporting
+ * @returns {SqlPrimitive} Result
+ */
+export function evaluateMathFunc({ funcName, args, positionStart, positionEnd, rowNumber }) {
+  if (funcName === 'FLOOR') {
+    if (args.length !== 1) {
+      throw argCountError({
+        funcName: 'FLOOR',
+        expected: 1,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const val = args[0]
+    if (val == null) return null
+    return Math.floor(Number(val))
+  }
+
+  if (funcName === 'CEIL' || funcName === 'CEILING') {
+    if (args.length !== 1) {
+      throw argCountError({
+        funcName,
+        expected: 1,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const val = args[0]
+    if (val == null) return null
+    return Math.ceil(Number(val))
+  }
+
+  if (funcName === 'ABS') {
+    if (args.length !== 1) {
+      throw argCountError({
+        funcName: 'ABS',
+        expected: 1,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const val = args[0]
+    if (val == null) return null
+    return Math.abs(Number(val))
+  }
+
+  if (funcName === 'MOD') {
+    if (args.length !== 2) {
+      throw argCountError({
+        funcName: 'MOD',
+        expected: 2,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const dividend = args[0]
+    const divisor = args[1]
+    if (dividend == null || divisor == null) return null
+    return Number(dividend) % Number(divisor)
+  }
+
+  if (funcName === 'EXP') {
+    if (args.length !== 1) {
+      throw argCountError({
+        funcName: 'EXP',
+        expected: 1,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const val = args[0]
+    if (val == null) return null
+    return Math.exp(Number(val))
+  }
+
+  if (funcName === 'LN') {
+    if (args.length !== 1) {
+      throw argCountError({
+        funcName: 'LN',
+        expected: 1,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const val = args[0]
+    if (val == null) return null
+    return Math.log(Number(val))
+  }
+
+  if (funcName === 'LOG10') {
+    if (args.length !== 1) {
+      throw argCountError({
+        funcName: 'LOG10',
+        expected: 1,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const val = args[0]
+    if (val == null) return null
+    return Math.log10(Number(val))
+  }
+
+  if (funcName === 'POWER') {
+    if (args.length !== 2) {
+      throw argCountError({
+        funcName: 'POWER',
+        expected: 2,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const base = args[0]
+    const exponent = args[1]
+    if (base == null || exponent == null) return null
+    return Number(base) ** Number(exponent)
+  }
+
+  if (funcName === 'SQRT') {
+    if (args.length !== 1) {
+      throw argCountError({
+        funcName: 'SQRT',
+        expected: 1,
+        received: args.length,
+        positionStart,
+        positionEnd,
+        rowNumber,
+      })
+    }
+    const val = args[0]
+    if (val == null) return null
+    return Math.sqrt(Number(val))
+  }
+
+  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

@@ -0,0 +1,63 @@
+// ============================================================================
+// EXECUTION ERRORS - Issues during query execution
+// ============================================================================
+
+/**
+ * Structured execution error with position range and optional row number.
+ */
+export class ExecutionError extends Error {
+  /**
+   * @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 }) {
+    const rowSuffix = rowNumber != null ? ` (row ${rowNumber})` : ''
+    super(message + rowSuffix)
+    this.name = 'ExecutionError'
+    this.positionStart = positionStart
+    this.positionEnd = positionEnd
+    this.rowNumber = rowNumber
+  }
+}
+
+/**
+ * Error for missing table.
+ *
+ * @param {Object} options
+ * @param {string} options.tableName - The missing table name
+ * @returns {Error}
+ */
+export function tableNotFoundError({ tableName }) {
+  return new Error(`Table "${tableName}" not found. Check spelling or add it to the tables parameter.`)
+}
+
+/**
+ * Error for invalid context (e.g., INTERVAL without date arithmetic).
+ *
+ * @param {Object} options
+ * @param {string} options.item - What was used incorrectly
+ * @param {string} options.validContext - Where it can be used
+ * @param {number} options.positionStart - Start position in query
+ * @param {number} options.positionEnd - End position in query
+ * @param {number} [options.rowNumber] - 1-based row number where error occurred
+ * @returns {ExecutionError}
+ */
+export function invalidContextError({ item, validContext, positionStart, positionEnd, rowNumber }) {
+  return new ExecutionError({ message: `${item} can only be used with ${validContext}`, positionStart, positionEnd, rowNumber })
+}
+
+/**
+ * Error for unsupported operation combinations.
+ *
+ * @param {Object} options
+ * @param {string} options.operation - The unsupported operation
+ * @param {string} [options.hint] - How to fix it
+ * @returns {Error}
+ */
+export function unsupportedOperationError({ operation, hint }) {
+  const suffix = hint ? `. ${hint}` : ''
+  return new Error(`${operation}${suffix}`)
+}

package/src/index.js

@@ -2,3 +2,4 @@ export { executeSql } from './execute/execute.js'
 export { parseSql } from './parse/parse.js'
 export { collect } from './execute/utils.js'
 export { cachedDataSource } from './backend/dataSource.js'
+export { ParseError } from './parseErrors.js'