squirreling 0.6.0 → 0.7.0

package/src/parse/parse.js

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

package/src/parseErrors.js

@@ -2,6 +2,8 @@
 // PARSE ERRORS - Issues during SQL tokenization and parsing
 // ============================================================================
 
+import { FUNCTION_SIGNATURES } from './validationErrors.js'
+
 /**
  * Structured parse error with position range.
  */
@@ -103,6 +105,33 @@ export function unknownFunctionError({ funcName, positionStart, positionEnd, val
   })
 }
 
+/**
+ * Error for wrong number of function arguments at parse time.
+ *
+ * @param {Object} options
+ * @param {string} options.funcName - The function name
+ * @param {number | string} options.expected - Expected count (number or range like "2 to 3")
+ * @param {number} options.received - Actual argument count
+ * @param {number} options.positionStart - Start position in query
+ * @param {number} options.positionEnd - End position in query
+ * @returns {ParseError}
+ */
+export function argCountParseError({ funcName, expected, received, positionStart, positionEnd }) {
+  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 ParseError({
+    message: `${funcName}(${signature}) function requires ${expectedStr}, got ${received}`,
+    positionStart,
+    positionEnd,
+  })
+}
+
 /**
  * Error for missing required clause or structure.
  *

package/src/types.d.ts

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

package/src/validation.js

@@ -1,6 +1,6 @@
 
 /**
- * @import {AggregateFunc, BinaryOp, ComparisonOp, IntervalUnit, MathFunc, StringFunc} from './types.js'
+ * @import {AggregateFunc, BinaryOp, ComparisonOp, IntervalUnit, MathFunc, StringFunc, UserDefinedFunction} from './types.js'
  * @param {string} name
  * @returns {name is AggregateFunc}
  */
@@ -62,6 +62,126 @@ export function isBinaryOp(op) {
   return ['AND', 'OR', 'LIKE', '=', '!=', '<>', '<', '>', '<=', '>='].includes(op)
 }
 
+/**
+ * Function argument count specifications.
+ * min: minimum number of arguments
+ * max: maximum number of arguments (null = unlimited)
+ * @type {Record<string, {min: number, max: number | null}>}
+ */
+export const FUNCTION_ARG_COUNTS = {
+  // String functions
+  UPPER: { min: 1, max: 1 },
+  LOWER: { min: 1, max: 1 },
+  LENGTH: { min: 1, max: 1 },
+  TRIM: { min: 1, max: 1 },
+  REPLACE: { min: 3, max: 3 },
+  SUBSTRING: { min: 2, max: 3 },
+  SUBSTR: { min: 2, max: 3 },
+  CONCAT: { min: 1, max: null },
+
+  // Date/time functions
+  RANDOM: { min: 0, max: 0 },
+  RAND: { min: 0, max: 0 },
+  CURRENT_DATE: { min: 0, max: 0 },
+  CURRENT_TIME: { min: 0, max: 0 },
+  CURRENT_TIMESTAMP: { min: 0, max: 0 },
+
+  // Math functions
+  FLOOR: { min: 1, max: 1 },
+  CEIL: { min: 1, max: 1 },
+  CEILING: { min: 1, max: 1 },
+  ABS: { min: 1, max: 1 },
+  MOD: { min: 2, max: 2 },
+  EXP: { min: 1, max: 1 },
+  LN: { min: 1, max: 1 },
+  LOG10: { min: 1, max: 1 },
+  POWER: { min: 2, max: 2 },
+  SQRT: { min: 1, max: 1 },
+  SIN: { min: 1, max: 1 },
+  COS: { min: 1, max: 1 },
+  TAN: { min: 1, max: 1 },
+  COT: { min: 1, max: 1 },
+  ASIN: { min: 1, max: 1 },
+  ACOS: { min: 1, max: 1 },
+  ATAN: { min: 1, max: 2 },
+  ATAN2: { min: 2, max: 2 },
+  DEGREES: { min: 1, max: 1 },
+  RADIANS: { min: 1, max: 1 },
+  PI: { min: 0, max: 0 },
+
+  // JSON functions
+  JSON_VALUE: { min: 2, max: 2 },
+  JSON_QUERY: { min: 2, max: 2 },
+  JSON_OBJECT: { min: 0, max: null },
+  JSON_ARRAYAGG: { min: 1, max: 1 },
+
+  // Aggregate functions
+  COUNT: { min: 1, max: 1 },
+  SUM: { min: 1, max: 1 },
+  AVG: { min: 1, max: 1 },
+  MIN: { min: 1, max: 1 },
+  MAX: { min: 1, max: 1 },
+}
+
+/**
+ * Format expected argument count for error messages.
+ * @param {number} min
+ * @param {number | null} max
+ * @returns {string | number}
+ */
+function formatExpected(min, max) {
+  if (max === null) return `at least ${min}`
+  if (min === max) return min
+  return `${min} or ${max}`
+}
+
+/**
+ * Validates function argument count.
+ * @param {string} funcName - The function name (uppercase)
+ * @param {number} argCount - Number of arguments provided
+ * @returns {{ valid: boolean, expected: string | number }}
+ */
+export function validateFunctionArgCount(funcName, argCount) {
+  const spec = FUNCTION_ARG_COUNTS[funcName]
+  if (!spec) return { valid: true, expected: 0 }
+
+  const { min, max } = spec
+
+  if (argCount < min) {
+    return { valid: false, expected: formatExpected(min, max) }
+  }
+  if (max !== null && argCount > max) {
+    return { valid: false, expected: formatExpected(min, max) }
+  }
+
+  return { valid: true, expected: formatExpected(min, max) }
+}
+
+/**
+ * Checks if a function is known (either built-in or user-defined).
+ * @param {string} funcName - The function name (uppercase)
+ * @param {Record<string, UserDefinedFunction>} [functions] - User-defined functions
+ * @returns {boolean}
+ */
+export function isKnownFunction(funcName, functions) {
+  // Check built-in functions
+  if (isAggregateFunc(funcName) || isMathFunc(funcName) || isStringFunc(funcName)) {
+    return true
+  }
+
+  // Special case: CAST is not in any function list but is a built-in
+  if (funcName === 'CAST') {
+    return true
+  }
+
+  // Check user-defined functions (case-insensitive)
+  if (functions) {
+    return Object.keys(functions).some(k => k.toUpperCase() === funcName)
+  }
+
+  return false
+}
+
 // Keywords that cannot be used as implicit aliases after a column
 export const RESERVED_AFTER_COLUMN = new Set([
   'FROM', 'WHERE', 'GROUP', 'HAVING', 'ORDER', 'LIMIT', 'OFFSET',

package/src/validationErrors.js

@@ -9,7 +9,7 @@ import { ExecutionError } from './executionErrors.js'
  * Maps function name to its parameter signature.
  * @type {Record<string, string>}
  */
-const FUNCTION_SIGNATURES = {
+export const FUNCTION_SIGNATURES = {
   // String functions
   UPPER: 'string',
   LOWER: 'string',
@@ -64,30 +64,6 @@ const FUNCTION_SIGNATURES = {
   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.
  *

package/src/execute/aggregates.js

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