squirreling 0.4.8 → 0.5.0

package/src/execute/math.js

@@ -0,0 +1,165 @@
+/**
+ * @import { SqlPrimitive } from '../types.js'
+ */
+import { argCountError } from '../validationErrors.js'
+
+/**
+ * Evaluate a math function
+ *
+ * @param {Object} options
+ * @param {string} 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))
+  }
+
+  return undefined
+}

package/src/executionErrors.js

@@ -0,0 +1,62 @@
+// ============================================================================
+// EXECUTION ERRORS - Issues during query execution
+// ============================================================================
+
+/**
+ * Structured execution error with position range and optional row number.
+ */
+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
+   */
+  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(`${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'

package/src/parse/comparison.js

@@ -1,7 +1,7 @@
-import { syntaxError } from '../errors.js'
+import { syntaxError } from '../parseErrors.js'
 import { isBinaryOp } from '../validation.js'
 import { parseAdditive, parseExpression, parseSubquery } from './expression.js'
-import { consume, current, expect, match, peekToken } from './state.js'
+import { consume, current, expect, lastPosition, match, peekToken } from './state.js'
 
 /**
  * @import { ExprNode, ParserState } from '../types.js'
@@ -26,6 +26,8 @@ export function parseComparison(state) {
         type: 'unary',
         op: 'IS NOT NULL',
         argument: left,
+        positionStart: left.positionStart,
+        positionEnd: lastPosition(state),
       }
     }
     expect(state, 'keyword', 'NULL')
@@ -33,6 +35,8 @@ export function parseComparison(state) {
       type: 'unary',
       op: 'IS NULL',
       argument: left,
+      positionStart: left.positionStart,
+      positionEnd: lastPosition(state),
     }
   }
 
@@ -40,6 +44,7 @@ export function parseComparison(state) {
   if (tok.type === 'keyword' && tok.value === 'NOT') {
     const nextTok = peekToken(state, 1)
     if (nextTok.type === 'keyword' && nextTok.value === 'LIKE') {
+      const notPositionStart = tok.positionStart
       consume(state) // NOT
       consume(state) // LIKE
       const right = parseAdditive(state)
@@ -51,7 +56,11 @@ export function parseComparison(state) {
           op: 'LIKE',
           left,
           right,
+          positionStart: left.positionStart,
+          positionEnd: right.positionEnd,
         },
+        positionStart: notPositionStart,
+        positionEnd: right.positionEnd,
       }
     }
   }
@@ -64,6 +73,8 @@ export function parseComparison(state) {
       op: 'LIKE',
       left,
       right,
+      positionStart: left.positionStart,
+      positionEnd: right.positionEnd,
     }
   }
 
@@ -71,6 +82,7 @@ export function parseComparison(state) {
   if (tok.type === 'keyword' && tok.value === 'NOT') {
     const nextTok = peekToken(state, 1)
     if (nextTok.type === 'keyword' && nextTok.value === 'BETWEEN') {
+      const notPositionStart = tok.positionStart
       consume(state) // NOT
       consume(state) // BETWEEN
       const lower = parseAdditive(state)
@@ -80,8 +92,10 @@ export function parseComparison(state) {
       return {
         type: 'binary',
         op: 'OR',
-        left: { type: 'binary', op: '<', left, right: lower },
-        right: { type: 'binary', op: '>', left, right: upper },
+        left: { type: 'binary', op: '<', left, right: lower, positionStart: left.positionStart, positionEnd: lower.positionEnd },
+        right: { type: 'binary', op: '>', left, right: upper, positionStart: left.positionStart, positionEnd: upper.positionEnd },
+        positionStart: notPositionStart,
+        positionEnd: upper.positionEnd,
       }
     }
   }
@@ -95,8 +109,10 @@ export function parseComparison(state) {
     return {
       type: 'binary',
       op: 'AND',
-      left: { type: 'binary', op: '>=', left, right: lower },
-      right: { type: 'binary', op: '<=', left, right: upper },
+      left: { type: 'binary', op: '>=', left, right: lower, positionStart: left.positionStart, positionEnd: lower.positionEnd },
+      right: { type: 'binary', op: '<=', left, right: upper, positionStart: left.positionStart, positionEnd: upper.positionEnd },
+      positionStart: left.positionStart,
+      positionEnd: upper.positionEnd,
     }
   }
 
@@ -104,6 +120,7 @@ export function parseComparison(state) {
   if (tok.type === 'keyword' && tok.value === 'NOT') {
     const nextTok = peekToken(state, 1)
     if (nextTok.type === 'keyword' && nextTok.value === 'IN') {
+      const notPositionStart = tok.positionStart
       consume(state) // NOT
       consume(state) // IN
 
@@ -111,12 +128,13 @@ export function parseComparison(state) {
       // parseSubquery expects to consume the opening paren itself
       const parenTok = current(state)
       if (parenTok.type !== 'paren' || parenTok.value !== '(') {
-        throw syntaxError({ expected: '(', received: `"${parenTok.value}"`, position: parenTok.position, after: 'IN' })
+        throw syntaxError({ expected: '(', received: `"${parenTok.value}"`, positionStart: parenTok.positionStart, positionEnd: parenTok.positionEnd, after: 'IN' })
       }
       const peekTok = peekToken(state, 1)
       if (peekTok.type === 'keyword' && peekTok.value === 'SELECT') {
         // Subquery - let parseSubquery handle the parens
         const subquery = parseSubquery(state)
+        const positionEnd = lastPosition(state)
         return {
           type: 'unary',
           op: 'NOT',
@@ -124,7 +142,11 @@ export function parseComparison(state) {
             type: 'in',
             expr: left,
             subquery,
+            positionStart: left.positionStart,
+            positionEnd,
           },
+          positionStart: notPositionStart,
+          positionEnd,
         }
       } else {
         // Parse list of values - we handle the parens
@@ -136,6 +158,7 @@ export function parseComparison(state) {
           if (!match(state, 'comma')) break
         }
         expect(state, 'paren', ')')
+        const positionEnd = lastPosition(state)
         return {
           type: 'unary',
           op: 'NOT',
@@ -143,7 +166,11 @@ export function parseComparison(state) {
             type: 'in valuelist',
             expr: left,
             values,
+            positionStart: left.positionStart,
+            positionEnd,
           },
+          positionStart: notPositionStart,
+          positionEnd,
         }
       }
     }
@@ -156,7 +183,7 @@ export function parseComparison(state) {
     // parseSubquery expects to consume the opening paren itself
     const parenTok = current(state)
     if (parenTok.type !== 'paren' || parenTok.value !== '(') {
-      throw syntaxError({ expected: '(', received: `"${parenTok.value}"`, position: parenTok.position, after: 'IN' })
+      throw syntaxError({ expected: '(', received: `"${parenTok.value}"`, positionStart: parenTok.positionStart, positionEnd: parenTok.positionEnd, after: 'IN' })
     }
     const peekTok = peekToken(state, 1)
     if (peekTok.type === 'keyword' && peekTok.value === 'SELECT') {
@@ -166,6 +193,8 @@ export function parseComparison(state) {
         type: 'in',
         expr: left,
         subquery,
+        positionStart: left.positionStart,
+        positionEnd: lastPosition(state),
       }
     } else {
       // Parse list of values - we handle the parens
@@ -181,6 +210,8 @@ export function parseComparison(state) {
         type: 'in valuelist',
         expr: left,
         values,
+        positionStart: left.positionStart,
+        positionEnd: lastPosition(state),
       }
     }
   }
@@ -193,6 +224,8 @@ export function parseComparison(state) {
       op: tok.value,
       left,
       right,
+      positionStart: left.positionStart,
+      positionEnd: right.positionEnd,
     }
   }
 

package/src/parse/expression.js

@@ -3,11 +3,11 @@ import {
   missingClauseError,
   syntaxError,
   unknownFunctionError,
-} from '../errors.js'
-import { isAggregateFunc, isIntervalUnit, isStringFunc } from '../validation.js'
+} from '../parseErrors.js'
+import { isAggregateFunc, isIntervalUnit, isMathFunc, isStringFunc } from '../validation.js'
 import { parseComparison } from './comparison.js'
 import { parseSelectInternal } from './parse.js'
-import { consume, current, expect, expectIdentifier, match, peekToken } from './state.js'
+import { consume, current, expect, expectIdentifier, lastPosition, match, peekToken } from './state.js'
 
 /**
  * @import { ExprNode, IntervalNode, ParserState, SelectStatement, WhenClause } from '../types.js'
@@ -18,6 +18,7 @@ import { consume, current, expect, expectIdentifier, match, peekToken } from './
  * @returns {IntervalNode}
  */
 function parseInterval(state) {
+  const { positionStart } = current(state)
   consume(state) // INTERVAL
 
   // Handle optional negative sign
@@ -39,11 +40,11 @@ function parseInterval(state) {
     consume(state)
     const parsed = parseFloat(valueTok.value)
     if (isNaN(parsed)) {
-      throw invalidLiteralError({ type: 'interval value', value: valueTok.value, position: valueTok.position })
+      throw invalidLiteralError({ type: 'interval value', value: valueTok.value, positionStart: valueTok.positionStart, positionEnd: valueTok.positionEnd })
     }
     value = sign * parsed
   } else {
-    throw syntaxError({ expected: 'interval value (number)', received: `"${valueTok.value}"`, position: valueTok.position })
+    throw syntaxError({ expected: 'interval value (number)', received: `"${valueTok.value}"`, positionStart: valueTok.positionStart, positionEnd: valueTok.positionEnd })
   }
 
   // Get unit keyword
@@ -52,13 +53,14 @@ function parseInterval(state) {
     throw invalidLiteralError({
       type: 'interval unit',
       value: unitTok.value,
-      position: unitTok.position,
+      positionStart: unitTok.positionStart,
+      positionEnd: unitTok.positionEnd,
       validValues: 'DAY, MONTH, YEAR, HOUR, MINUTE, SECOND',
     })
   }
   consume(state)
 
-  return { type: 'interval', value, unit: unitTok.value }
+  return { type: 'interval', value, unit: unitTok.value, positionStart, positionEnd: lastPosition(state) }
 }
 
 /**
@@ -75,6 +77,7 @@ export function parseExpression(state) {
  */
 export function parsePrimary(state) {
   const tok = current(state)
+  const { positionStart } = tok
 
   if (tok.type === 'paren' && tok.value === '(') {
     // Peek ahead to see if this is a scalar subquery
@@ -85,6 +88,8 @@ export function parsePrimary(state) {
       return {
         type: 'subquery',
         subquery,
+        positionStart,
+        positionEnd: lastPosition(state),
       }
     }
     // Regular grouped expression
@@ -109,6 +114,8 @@ export function parsePrimary(state) {
         type: 'cast',
         expr,
         toType: typeTok.value,
+        positionStart,
+        positionEnd: lastPosition(state),
       }
     }
 
@@ -117,8 +124,8 @@ export function parsePrimary(state) {
       const funcName = tok.value
 
       // validate function names
-      if (!isStringFunc(funcName) && !isAggregateFunc(funcName)) {
-        throw unknownFunctionError(funcName, tok.position)
+      if (!isStringFunc(funcName) && !isAggregateFunc(funcName) && !isMathFunc(funcName)) {
+        throw unknownFunctionError({ funcName, positionStart: tok.positionStart, positionEnd: tok.positionEnd })
       }
 
       consume(state) // function name
@@ -131,10 +138,13 @@ export function parsePrimary(state) {
         while (true) {
           // Handle COUNT(*) - treat * as a special identifier
           if (current(state).type === 'operator' && current(state).value === '*') {
+            const starTok = current(state)
             consume(state)
             args.push({
               type: 'identifier',
               name: '*',
+              positionStart: starTok.positionStart,
+              positionEnd: lastPosition(state),
             })
           } else {
             const arg = parseExpression(state)
@@ -150,6 +160,8 @@ export function parsePrimary(state) {
         type: 'function',
         name: funcName,
         args,
+        positionStart,
+        positionEnd: lastPosition(state),
       }
     }
 
@@ -161,6 +173,8 @@ export function parsePrimary(state) {
         type: 'function',
         name: tok.value,
         args: [],
+        positionStart,
+        positionEnd: lastPosition(state),
       }
     }
 
@@ -177,6 +191,8 @@ export function parsePrimary(state) {
     return {
       type: 'identifier',
       name,
+      positionStart,
+      positionEnd: lastPosition(state),
     }
   }
 
@@ -185,6 +201,8 @@ export function parsePrimary(state) {
     return {
       type: 'literal',
       value: tok.numericValue ?? null,
+      positionStart,
+      positionEnd: lastPosition(state),
     }
   }
 
@@ -193,21 +211,23 @@ export function parsePrimary(state) {
     return {
       type: 'literal',
       value: tok.value,
+      positionStart,
+      positionEnd: lastPosition(state),
     }
   }
 
   if (tok.type === 'keyword') {
     if (tok.value === 'TRUE') {
       consume(state)
-      return { type: 'literal', value: true }
+      return { type: 'literal', value: true, positionStart, positionEnd: lastPosition(state) }
     }
     if (tok.value === 'FALSE') {
       consume(state)
-      return { type: 'literal', value: false }
+      return { type: 'literal', value: false, positionStart, positionEnd: lastPosition(state) }
     }
     if (tok.value === 'NULL') {
       consume(state)
-      return { type: 'literal', value: null }
+      return { type: 'literal', value: null, positionStart, positionEnd: lastPosition(state) }
     }
     if (tok.value === 'EXISTS') {
       consume(state) // EXISTS
@@ -215,6 +235,8 @@ export function parsePrimary(state) {
       return {
         type: 'exists',
         subquery,
+        positionStart,
+        positionEnd: lastPosition(state),
       }
     }
     if (tok.value === 'CASE') {
@@ -260,6 +282,8 @@ export function parsePrimary(state) {
         caseExpr,
         whenClauses,
         elseResult,
+        positionStart,
+        positionEnd: lastPosition(state),
       }
     }
     if (tok.value === 'INTERVAL') {
@@ -274,11 +298,13 @@ export function parsePrimary(state) {
       type: 'unary',
       op: '-',
       argument,
+      positionStart,
+      positionEnd: argument.positionEnd,
     }
   }
 
   const found = tok.type === 'eof' ? 'end of query' : `"${tok.originalValue ?? tok.value}"`
-  throw syntaxError({ expected: 'expression', received: found, position: tok.position })
+  throw syntaxError({ expected: 'expression', received: found, positionStart: tok.positionStart, positionEnd: tok.positionEnd })
 }
 
 /**
@@ -294,6 +320,8 @@ function parseOr(state) {
       op: 'OR',
       left: node,
       right,
+      positionStart: node.positionStart,
+      positionEnd: right.positionEnd,
     }
   }
   return node
@@ -312,6 +340,8 @@ function parseAnd(state) {
       op: 'AND',
       left: node,
       right,
+      positionStart: node.positionStart,
+      positionEnd: right.positionEnd,
     }
   }
   return node
@@ -322,7 +352,9 @@ function parseAnd(state) {
  * @returns {ExprNode}
  */
 function parseNot(state) {
+  const tok = current(state)
   if (match(state, 'keyword', 'NOT')) {
+    const { positionStart } = tok
     // Check for NOT EXISTS
     const nextTok = current(state)
     if (nextTok.type === 'keyword' && nextTok.value === 'EXISTS') {
@@ -331,6 +363,8 @@ function parseNot(state) {
       return {
         type: 'not exists',
         subquery,
+        positionStart,
+        positionEnd: lastPosition(state),
       }
     }
     const argument = parseNot(state)
@@ -338,6 +372,8 @@ function parseNot(state) {
       type: 'unary',
       op: 'NOT',
       argument,
+      positionStart,
+      positionEnd: argument.positionEnd,
     }
   }
   return parseComparison(state)
@@ -359,6 +395,8 @@ export function parseAdditive(state) {
         op: tok.value,
         left: node,
         right,
+        positionStart: node.positionStart,
+        positionEnd: right.positionEnd,
       }
     } else {
       break
@@ -383,6 +421,8 @@ function parseMultiplicative(state) {
         op: tok.value,
         left: node,
         right,
+        positionStart: node.positionStart,
+        positionEnd: right.positionEnd,
       }
     } else {
       break