squirreling 0.4.8 → 0.6.0

package/src/parseErrors.js

@@ -0,0 +1,118 @@
+// ============================================================================
+// PARSE ERRORS - Issues during SQL tokenization and parsing
+// ============================================================================
+
+/**
+ * Structured parse error with position range.
+ */
+export class ParseError 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)
+   */
+  constructor({ message, positionStart, positionEnd }) {
+    super(message)
+    this.name = 'ParseError'
+    this.positionStart = positionStart
+    this.positionEnd = positionEnd
+  }
+}
+
+/**
+ * General syntax error for unexpected tokens.
+ *
+ * @param {Object} options
+ * @param {string} options.expected - Description of what was expected
+ * @param {string} options.received - What was actually found
+ * @param {number} options.positionStart - Start character position in query
+ * @param {number} options.positionEnd - End character position in query
+ * @param {string} [options.after] - What token came before (for context)
+ * @returns {ParseError}
+ */
+export function syntaxError({ expected, received, positionStart, positionEnd, after }) {
+  const afterClause = after ? ` after "${after}"` : ''
+  return new ParseError({ message: `Expected ${expected}${afterClause} but found ${received} at position ${positionStart}`, positionStart, positionEnd })
+}
+
+/**
+ * Error for unterminated literals (strings, identifiers).
+ *
+ * @param {'string' | 'identifier'} type - Type of unterminated literal
+ * @param {number} positionStart - Starting position
+ * @param {number} positionEnd - End position
+ * @returns {ParseError}
+ */
+export function unterminatedError(type, positionStart, positionEnd) {
+  const name = type === 'string' ? 'string literal' : 'identifier'
+  return new ParseError({ message: `Unterminated ${name} starting at position ${positionStart}`, positionStart, positionEnd })
+}
+
+/**
+ * Error for invalid literals (numbers, intervals, etc).
+ *
+ * @param {Object} options
+ * @param {string} options.type - Type of invalid literal (e.g., 'number', 'interval value', 'interval unit')
+ * @param {string} options.value - The invalid value
+ * @param {number} options.positionStart - Start position in query
+ * @param {number} options.positionEnd - End position in query
+ * @param {string} [options.validValues] - List of valid values (for enums like interval units)
+ * @returns {ParseError}
+ */
+export function invalidLiteralError({ type, value, positionStart, positionEnd, validValues }) {
+  const suffix = validValues ? `. Valid values: ${validValues}` : ''
+  return new ParseError({ message: `Invalid ${type} ${value} at position ${positionStart}${suffix}`, positionStart, positionEnd })
+}
+
+/**
+ * Error for unexpected characters during tokenization.
+ *
+ * @param {Object} options
+ * @param {string} options.char - The unexpected character
+ * @param {number} options.positionStart - Position in query
+ * @param {boolean} [options.expectsSelect=false] - Whether SELECT was expected (first token)
+ * @returns {ParseError}
+ */
+export function unexpectedCharError({ char, positionStart, expectsSelect = false }) {
+  const positionEnd = positionStart + 1
+  if (expectsSelect) {
+    return new ParseError({ message: `Expected SELECT but found "${char}" at position ${positionStart}. Queries must start with SELECT.`, positionStart, positionEnd })
+  }
+  return new ParseError({ message: `Unexpected character "${char}" at position ${positionStart}`, positionStart, positionEnd })
+}
+
+/**
+ * Error for unknown/unsupported functions.
+ *
+ * @param {Object} options
+ * @param {string} options.funcName - The unknown function name
+ * @param {number} options.positionStart - Start position in query
+ * @param {number} options.positionEnd - End position in query
+ * @param {string} [options.validFunctions] - List of valid functions
+ * @returns {ParseError}
+ */
+export function unknownFunctionError({ funcName, positionStart, positionEnd, validFunctions }) {
+  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({
+    message: `Unknown function "${funcName}" at position ${positionStart}. Supported: ${supported}`,
+    positionStart,
+    positionEnd,
+  })
+}
+
+/**
+ * Error for missing required clause or structure.
+ *
+ * @param {Object} options
+ * @param {string} options.missing - What is missing (e.g., 'WHEN clause', 'FROM clause', 'ON condition')
+ * @param {string} options.context - Where it's missing from (e.g., 'CASE expression', 'SELECT statement', 'JOIN')
+ * @param {number} [options.positionStart] - Start position in query
+ * @param {number} [options.positionEnd] - End position in query
+ * @returns {ParseError}
+ */
+export function missingClauseError({ missing, context, positionStart, positionEnd }) {
+  return new ParseError({ message: `${context} requires ${missing}`, positionStart: positionStart ?? 0, positionEnd: positionEnd ?? 0 })
+}

package/src/types.d.ts

@@ -6,6 +6,11 @@
 export interface QueryHints {
   columns?: string[] // columns needed
   where?: ExprNode // where clause
+  // important: only apply limit/offset if where is fully applied by the data source
+  // otherwise, the data source must return at least enough rows to ensure the engine
+  // can apply limit/offset correctly after filtering
+  // even with offset, the datasource must return rows starting from offset 0
+  // but doesn't need to resolve async rows before the offset
   limit?: number
   offset?: number
 }
@@ -15,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 =
@@ -68,54 +77,59 @@ export type BinaryOp = 'AND' | 'OR' | 'LIKE' | ComparisonOp | ArithmeticOp
 
 export type ComparisonOp = '=' | '!=' | '<>' | '<' | '>' | '<=' | '>='
 
-export interface LiteralNode {
+export interface ExprNodeBase {
+  positionStart: number
+  positionEnd: number
+}
+
+export interface LiteralNode extends ExprNodeBase {
   type: 'literal'
   value: SqlPrimitive
 }
 
-export interface IdentifierNode {
+export interface IdentifierNode extends ExprNodeBase {
   type: 'identifier'
   name: string
 }
 
-export interface UnaryNode {
+export interface UnaryNode extends ExprNodeBase {
   type: 'unary'
   op: 'NOT' | 'IS NULL' | 'IS NOT NULL' | '-'
   argument: ExprNode
 }
 
-export interface BinaryNode {
+export interface BinaryNode extends ExprNodeBase {
   type: 'binary'
   op: BinaryOp
   left: ExprNode
   right: ExprNode
 }
 
-export interface FunctionNode {
+export interface FunctionNode extends ExprNodeBase {
   type: 'function'
   name: string
   args: ExprNode[]
 }
 
-export interface CastNode {
+export interface CastNode extends ExprNodeBase {
   type: 'cast'
   expr: ExprNode
   toType: string
 }
 
-export interface InSubqueryNode {
+export interface InSubqueryNode extends ExprNodeBase {
   type: 'in'
   expr: ExprNode
   subquery: SelectStatement
 }
 
-export interface InValuesNode {
+export interface InValuesNode extends ExprNodeBase {
   type: 'in valuelist'
   expr: ExprNode
   values: ExprNode[]
 }
 
-export interface ExistsNode {
+export interface ExistsNode extends ExprNodeBase {
   type: 'exists' | 'not exists'
   subquery: SelectStatement
 }
@@ -125,21 +139,21 @@ export interface WhenClause {
   result: ExprNode
 }
 
-export interface CaseNode {
+export interface CaseNode extends ExprNodeBase {
   type: 'case'
   caseExpr?: ExprNode
   whenClauses: WhenClause[]
   elseResult?: ExprNode
 }
 
-export interface SubqueryNode {
+export interface SubqueryNode extends ExprNodeBase {
   type: 'subquery'
   subquery: SelectStatement
 }
 
 export type IntervalUnit = 'DAY' | 'MONTH' | 'YEAR' | 'HOUR' | 'MINUTE' | 'SECOND'
 
-export interface IntervalNode {
+export interface IntervalNode extends ExprNodeBase {
   type: 'interval'
   value: number
   unit: IntervalUnit
@@ -167,6 +181,29 @@ export interface StarColumn {
 
 export type AggregateFunc = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'JSON_ARRAYAGG'
 
+export type MathFunc =
+  | 'FLOOR'
+  | 'CEIL'
+  | 'CEILING'
+  | 'ABS'
+  | 'MOD'
+  | 'EXP'
+  | 'LN'
+  | 'LOG10'
+  | 'POWER'
+  | 'SQRT'
+  | 'SIN'
+  | 'COS'
+  | 'TAN'
+  | 'COT'
+  | 'ASIN'
+  | 'ACOS'
+  | 'ATAN'
+  | 'ATAN2'
+  | 'DEGREES'
+  | 'RADIANS'
+  | 'PI'
+
 export type StringFunc =
   | 'UPPER'
   | 'LOWER'
@@ -228,6 +265,7 @@ export interface JoinClause {
 export interface ParserState {
   tokens: Token[]
   pos: number
+  lastPos?: number
 }
 
 // Tokenizer types
@@ -246,7 +284,8 @@ export type TokenType =
 export interface Token {
   type: TokenType
   value: string
-  position: number
+  positionStart: number
+  positionEnd: number
   numericValue?: number | bigint
   originalValue?: string
 }

package/src/validation.js

@@ -1,6 +1,6 @@
 
 /**
- * @import {AggregateFunc, BinaryOp, ComparisonOp, IntervalUnit, StringFunc} from './types.js'
+ * @import {AggregateFunc, BinaryOp, ComparisonOp, IntervalUnit, MathFunc, StringFunc} from './types.js'
  * @param {string} name
  * @returns {name is AggregateFunc}
  */
@@ -8,6 +8,19 @@ export function isAggregateFunc(name) {
   return ['COUNT', 'SUM', 'AVG', 'MIN', 'MAX', 'JSON_ARRAYAGG'].includes(name)
 }
 
+/**
+ * @param {string} name
+ * @returns {name is MathFunc}
+ */
+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)
+}
+
 /**
  * @param {string} name
  * @returns {name is IntervalUnit}

package/src/validationErrors.js

@@ -0,0 +1,138 @@
+import { ExecutionError } from './executionErrors.js'
+
+// ============================================================================
+// VALIDATION ERRORS - Function argument and type validation
+// ============================================================================
+
+/**
+ * Function signatures for helpful error messages.
+ * Maps function name to its parameter signature.
+ * @type {Record<string, string>}
+ */
+const FUNCTION_SIGNATURES = {
+  // String functions
+  UPPER: 'string',
+  LOWER: 'string',
+  LENGTH: 'string',
+  TRIM: 'string',
+  REPLACE: 'string, search, replacement',
+  SUBSTRING: 'string, start[, length]',
+  SUBSTR: 'string, start[, length]',
+  CONCAT: 'value1, value2[, ...]',
+
+  // Date/time functions
+  RANDOM: '',
+  RAND: '',
+  CURRENT_DATE: '',
+  CURRENT_TIME: '',
+  CURRENT_TIMESTAMP: '',
+
+  // Math functions
+  FLOOR: 'number',
+  CEIL: 'number',
+  CEILING: 'number',
+  ABS: 'number',
+  MOD: 'dividend, divisor',
+  EXP: 'number',
+  LN: 'number',
+  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',
+  JSON_QUERY: 'expression, path',
+  JSON_OBJECT: 'key1, value1[, ...]',
+  JSON_ARRAYAGG: 'expression',
+
+  // Aggregate functions
+  COUNT: 'expression',
+  SUM: 'expression',
+  AVG: 'expression',
+  MIN: 'expression',
+  MAX: 'expression',
+}
+
+/**
+ * Error for wrong number of function arguments.
+ *
+ * @param {Object} options
+ * @param {string} options.funcName - The function name
+ * @param {number | string} options.expected - Expected count (number or range like "2 or 3")
+ * @param {number} options.received - Actual argument count
+ * @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 argCountError({ funcName, expected, received, positionStart, positionEnd, rowNumber }) {
+  const signature = FUNCTION_SIGNATURES[funcName] ?? ''
+  let expectedStr = `${expected} arguments`
+  if (expected === 0) expectedStr = 'no arguments'
+  if (expected === 1) expectedStr = '1 argument'
+  if (typeof expected === 'string' && expected.endsWith(' 1')) {
+    expectedStr = `${expected} argument`
+  }
+
+  return new ExecutionError({ message: `${funcName}(${signature}) function requires ${expectedStr}, got ${received}`, positionStart, positionEnd, rowNumber })
+}
+
+/**
+ * Error for invalid argument type or value.
+ *
+ * @param {Object} options
+ * @param {string} options.funcName - The function name
+ * @param {string} options.message - Specific error message
+ * @param {number} options.positionStart - Start position in query
+ * @param {number} options.positionEnd - End position in query
+ * @param {string} [options.hint] - Recovery hint
+ * @param {number} [options.rowNumber] - 1-based row number where error occurred
+ * @returns {ExecutionError}
+ */
+export function argValueError({ funcName, message, positionStart, positionEnd, hint, rowNumber }) {
+  const signature = FUNCTION_SIGNATURES[funcName] ?? ''
+  const suffix = hint ? `. ${hint}` : ''
+  return new ExecutionError({ message: `${funcName}(${signature}): ${message}${suffix}`, positionStart, positionEnd, rowNumber })
+}
+
+/**
+ * Error for aggregate function misuse (e.g., SUM(*)).
+ *
+ * @param {Object} options
+ * @param {string} options.funcName - The aggregate function
+ * @param {string} options.issue - What's wrong (e.g., "(*) is not supported")
+ * @returns {Error}
+ */
+export function aggregateError({ funcName, issue }) {
+  return new Error(`${funcName}${issue}. Only COUNT supports *. Use a column name for ${funcName}.`)
+}
+
+/**
+ * Error for unsupported CAST type.
+ *
+ * @param {Object} options
+ * @param {string} options.toType - The unsupported target type
+ * @param {number} options.positionStart - Start position in query
+ * @param {number} options.positionEnd - End position in query
+ * @param {string} [options.fromType] - The source type (optional)
+ * @param {number} [options.rowNumber] - 1-based row number where error occurred
+ * @returns {ExecutionError}
+ */
+export function castError({ toType, positionStart, positionEnd, fromType, rowNumber }) {
+  const message = fromType
+    ? `Cannot CAST ${fromType} to ${toType}`
+    : `Unsupported CAST to type ${toType}`
+
+  return new ExecutionError({ message: `${message}. Supported types: TEXT, VARCHAR, INTEGER, INT, BIGINT, FLOAT, REAL, DOUBLE, BOOLEAN`, positionStart, positionEnd, rowNumber })
+}

package/src/errors.js

@@ -1,230 +0,0 @@
-// ============================================================================
-// PARSE ERRORS - Issues during SQL tokenization and parsing
-// ============================================================================
-
-/**
- * General syntax error for unexpected tokens.
- *
- * @param {Object} options
- * @param {string} options.expected - Description of what was expected
- * @param {string} options.received - What was actually found
- * @param {number} options.position - Character position in query
- * @param {string} [options.after] - What token came before (for context)
- * @returns {Error}
- */
-export function syntaxError({ expected, received, position, after }) {
-  const afterClause = after ? ` after "${after}"` : ''
-  return new Error(`Expected ${expected}${afterClause} but found ${received} at position ${position}`)
-}
-
-/**
- * Error for unterminated literals (strings, identifiers).
- *
- * @param {'string' | 'identifier'} type - Type of unterminated literal
- * @param {number} position - Starting position
- * @returns {Error}
- */
-export function unterminatedError(type, position) {
-  const name = type === 'string' ? 'string literal' : 'identifier'
-  return new Error(`Unterminated ${name} starting at position ${position}`)
-}
-
-/**
- * Error for invalid literals (numbers, intervals, etc).
- *
- * @param {Object} options
- * @param {string} options.type - Type of invalid literal (e.g., 'number', 'interval value', 'interval unit')
- * @param {string} options.value - The invalid value
- * @param {number} options.position - Position in query
- * @param {string} [options.validValues] - List of valid values (for enums like interval units)
- * @returns {Error}
- */
-export function invalidLiteralError({ type, value, position, validValues }) {
-  const suffix = validValues ? `. Valid values: ${validValues}` : ''
-  return new Error(`Invalid ${type} ${value} at position ${position}${suffix}`)
-}
-
-/**
- * Error for unexpected characters during tokenization.
- *
- * @param {string} char - The unexpected character
- * @param {number} position - Position in query
- * @param {boolean} [expectsSelect=false] - Whether SELECT was expected (first token)
- * @returns {Error}
- */
-export function unexpectedCharError(char, position, expectsSelect = false) {
-  if (expectsSelect) {
-    return new Error(`Expected SELECT but found "${char}" at position ${position}. Queries must start with SELECT.`)
-  }
-  return new Error(`Unexpected character "${char}" at position ${position}`)
-}
-
-/**
- * Error for unknown/unsupported functions.
- *
- * @param {string} funcName - The unknown function name
- * @param {number} [position] - Position in query (for parse errors)
- * @param {string} [validFunctions] - List of valid functions
- * @returns {Error}
- */
-export function unknownFunctionError(funcName, position, validFunctions) {
-  const supported = validFunctions ||
-    'COUNT, SUM, AVG, MIN, MAX, UPPER, LOWER, CONCAT, LENGTH, SUBSTRING, TRIM, REPLACE, JSON_OBJECT, JSON_VALUE, JSON_QUERY, JSON_ARRAYAGG'
-
-  if (position !== undefined) {
-    return new Error(`Unknown function "${funcName}" at position ${position}. Supported: ${supported}`)
-  }
-  return new Error(`Unsupported function: ${funcName}. Supported: ${supported}`)
-}
-
-/**
- * Error for missing required clause or structure.
- *
- * @param {Object} options
- * @param {string} options.missing - What is missing (e.g., 'WHEN clause', 'FROM clause', 'ON condition')
- * @param {string} options.context - Where it's missing from (e.g., 'CASE expression', 'SELECT statement', 'JOIN')
- * @returns {Error}
- */
-export function missingClauseError({ missing, context }) {
-  return new Error(`${context} requires ${missing}`)
-}
-
-// ============================================================================
-// EXECUTION ERRORS - Issues during query execution
-// ============================================================================
-
-/**
- * Error for missing table.
- *
- * @param {string} 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
- * @returns {Error}
- */
-export function invalidContextError({ item, validContext }) {
-  return new Error(`${item} can only be used with ${validContext}`)
-}
-
-/**
- * Error for unsupported operation combinations.
- *
- * @param {string} operation - The unsupported operation
- * @param {string} [hint] - How to fix it
- * @returns {Error}
- */
-export function unsupportedOperationError(operation, hint) {
-  const suffix = hint ? `. ${hint}` : ''
-  return new Error(`${operation}${suffix}`)
-}
-
-// ============================================================================
-// VALIDATION ERRORS - Function argument and type validation
-// ============================================================================
-
-/**
- * Function signatures for helpful error messages.
- * Maps function name to its parameter signature.
- * @type {Record<string, string>}
- */
-const FUNCTION_SIGNATURES = {
-  // String functions
-  UPPER: 'string',
-  LOWER: 'string',
-  LENGTH: 'string',
-  TRIM: 'string',
-  REPLACE: 'string, search, replacement',
-  SUBSTRING: 'string, start[, length]',
-  SUBSTR: 'string, start[, length]',
-  CONCAT: 'value1, value2[, ...]',
-
-  // Date/time functions
-  RANDOM: '',
-  RAND: '',
-  CURRENT_DATE: '',
-  CURRENT_TIME: '',
-  CURRENT_TIMESTAMP: '',
-
-  // JSON functions
-  JSON_VALUE: 'expression, path',
-  JSON_QUERY: 'expression, path',
-  JSON_OBJECT: 'key1, value1[, ...]',
-  JSON_ARRAYAGG: 'expression',
-
-  // Aggregate functions
-  COUNT: 'expression',
-  SUM: 'expression',
-  AVG: 'expression',
-  MIN: 'expression',
-  MAX: 'expression',
-}
-
-/**
- * Error for wrong number of function arguments.
- *
- * @param {string} funcName - The function name
- * @param {number | string} expected - Expected count (number or range like "2 or 3")
- * @param {number} received - Actual argument count
- * @returns {Error}
- */
-export function argCountError(funcName, expected, received) {
-  const signature = FUNCTION_SIGNATURES[funcName] ?? ''
-  let expectedStr = `${expected} arguments`
-  if (expected === 0) expectedStr = 'no arguments'
-  if (expected === 1) expectedStr = '1 argument'
-  if (typeof expected === 'string' && expected.endsWith(' 1')) {
-    expectedStr = `${expected} argument`
-  }
-
-  return new Error(`${funcName}(${signature}) function requires ${expectedStr}, got ${received}`)
-}
-
-/**
- * Error for invalid argument type or value.
- *
- * @param {Object} options
- * @param {string} options.funcName - The function name
- * @param {string} options.message - Specific error message
- * @param {string} [options.hint] - Recovery hint
- * @returns {Error}
- */
-export function argValueError({ funcName, message, hint }) {
-  const signature = FUNCTION_SIGNATURES[funcName] ?? ''
-  const suffix = hint ? `. ${hint}` : ''
-  return new Error(`${funcName}(${signature}): ${message}${suffix}`)
-}
-
-/**
- * Error for aggregate function misuse (e.g., SUM(*)).
- *
- * @param {string} funcName - The aggregate function
- * @param {string} issue - What's wrong (e.g., "(*) is not supported")
- * @returns {Error}
- */
-export function aggregateError(funcName, issue) {
-  return new Error(`${funcName}${issue}. Only COUNT supports *. Use a column name for ${funcName}.`)
-}
-
-/**
- * Error for unsupported CAST type.
- *
- * @param {string} toType - The unsupported target type
- * @param {string} [fromType] - The source type (optional)
- * @returns {Error}
- */
-export function castError(toType, fromType) {
-  const message = fromType
-    ? `Cannot CAST ${fromType} to ${toType}`
-    : `Unsupported CAST to type ${toType}`
-
-  return new Error(`${message}. Supported types: TEXT, VARCHAR, INTEGER, INT, BIGINT, FLOAT, REAL, DOUBLE, BOOLEAN`)
-}