squirreling 0.10.0 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Squirreling Async SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -10,7 +10,9 @@
     "dataset",
     "hyperparam",
     "hyparquet",
-    "parquet"
+    "parquet",
+    "query",
+    "relational"
   ],
   "license": "MIT",
   "repository": {
@@ -37,7 +39,7 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "25.3.5",
+    "@types/node": "25.4.0",
     "@vitest/coverage-v8": "4.0.18",
     "eslint": "9.39.2",
     "eslint-plugin-jsdoc": "62.7.1",

package/src/ast.d.ts

@@ -0,0 +1,184 @@
+export type SqlPrimitive =
+  | string
+  | number
+  | bigint
+  | boolean
+  | Date
+  | null
+  | SqlPrimitive[]
+  | Record<string, any>
+
+export interface SelectStatement {
+  with?: WithClause
+  distinct: boolean
+  columns: SelectColumn[]
+  from: FromTable | FromSubquery
+  joins: JoinClause[]
+  where?: ExprNode
+  groupBy: ExprNode[]
+  having?: ExprNode
+  orderBy: OrderByItem[]
+  limit?: number
+  offset?: number
+}
+
+export interface WithClause {
+  ctes: CTEDefinition[]
+}
+
+export interface CTEDefinition {
+  name: string
+  query: SelectStatement
+}
+
+export interface FromTable extends AstBase {
+  kind: 'table'
+  table: string
+  alias?: string
+}
+
+export interface FromSubquery {
+  kind: 'subquery'
+  query: SelectStatement
+  alias: string
+}
+
+export type ArithmeticOp = '+' | '-' | '*' | '/' | '%'
+
+export type BinaryOp = 'AND' | 'OR' | 'LIKE' | ComparisonOp | ArithmeticOp
+
+export type ComparisonOp = '=' | '!=' | '<>' | '<' | '>' | '<=' | '>='
+
+export interface LiteralNode extends AstBase {
+  type: 'literal'
+  value: SqlPrimitive
+}
+
+export interface IdentifierNode extends AstBase {
+  type: 'identifier'
+  name: string
+}
+
+export interface UnaryNode extends AstBase {
+  type: 'unary'
+  op: 'NOT' | 'IS NULL' | 'IS NOT NULL' | '-'
+  argument: ExprNode
+}
+
+export interface BinaryNode extends AstBase {
+  type: 'binary'
+  op: BinaryOp
+  left: ExprNode
+  right: ExprNode
+}
+
+export interface FunctionNode extends AstBase {
+  type: 'function'
+  funcName: string
+  args: ExprNode[]
+  distinct?: boolean
+  filter?: ExprNode
+}
+
+export type CastType = 'TEXT' | 'STRING' | 'VARCHAR' | 'INTEGER' | 'INT' | 'BIGINT' | 'FLOAT' | 'REAL' | 'DOUBLE' | 'BOOLEAN' | 'BOOL'
+
+export interface CastNode extends AstBase {
+  type: 'cast'
+  expr: ExprNode
+  toType: CastType
+}
+
+export interface InSubqueryNode extends AstBase {
+  type: 'in'
+  expr: ExprNode
+  subquery: SelectStatement
+}
+
+export interface InValuesNode extends AstBase {
+  type: 'in valuelist'
+  expr: ExprNode
+  values: ExprNode[]
+}
+
+export interface ExistsNode extends AstBase {
+  type: 'exists' | 'not exists'
+  subquery: SelectStatement
+}
+
+export interface WhenClause extends AstBase {
+  condition: ExprNode
+  result: ExprNode
+}
+
+export interface CaseNode extends AstBase {
+  type: 'case'
+  caseExpr?: ExprNode
+  whenClauses: WhenClause[]
+  elseResult?: ExprNode
+}
+
+export interface SubqueryNode extends AstBase {
+  type: 'subquery'
+  subquery: SelectStatement
+}
+
+export type IntervalUnit = 'DAY' | 'MONTH' | 'YEAR' | 'HOUR' | 'MINUTE' | 'SECOND'
+
+export interface IntervalNode extends AstBase {
+  type: 'interval'
+  value: number
+  unit: IntervalUnit
+}
+
+export interface StarNode extends AstBase {
+  type: 'star'
+}
+
+export type ExprNode =
+  | LiteralNode
+  | IdentifierNode
+  | UnaryNode
+  | BinaryNode
+  | FunctionNode
+  | CastNode
+  | InSubqueryNode
+  | InValuesNode
+  | ExistsNode
+  | CaseNode
+  | SubqueryNode
+  | IntervalNode
+  | StarNode
+
+export interface StarColumn {
+  kind: 'star'
+  table?: string
+}
+
+export interface DerivedColumn {
+  kind: 'derived'
+  expr: ExprNode
+  alias?: string
+}
+
+export type SelectColumn = StarColumn | DerivedColumn
+
+export interface OrderByItem {
+  expr: ExprNode
+  direction: 'ASC' | 'DESC'
+  nulls?: 'FIRST' | 'LAST'
+}
+
+export type JoinType = 'INNER' | 'LEFT' | 'RIGHT' | 'FULL' | 'CROSS' | 'POSITIONAL'
+
+export interface JoinClause extends AstBase {
+  joinType: JoinType
+  table: string
+  alias?: string
+  on?: ExprNode
+}
+
+// All AST node derive from this base, which includes position info for error reporting and other purposes
+interface AstBase {
+  positionStart: number // start position in query (0-based, inclusive)
+  positionEnd: number // end position in query (0-based, exclusive)
+}

package/src/execute/execute.js

@@ -1,9 +1,9 @@
 import { memorySource } from '../backend/dataSource.js'
-import { tableNotFoundError } from '../executionErrors.js'
 import { derivedAlias } from '../expression/alias.js'
 import { evaluateExpr } from '../expression/evaluate.js'
 import { parseSql } from '../parse/parse.js'
 import { planSql } from '../plan/plan.js'
+import { tableNotFoundError } from '../validation/planErrors.js'
 import { executeHashAggregate, executeScalarAggregate } from './aggregates.js'
 import { executeHashJoin, executeNestedLoopJoin, executePositionalJoin } from './join.js'
 import { executeSort } from './sort.js'
@@ -46,7 +46,7 @@ export async function* executeSql({ tables, query, functions, signal }) {
  * @yields {AsyncRow}
  */
 export async function* executeSelect({ select, context }) {
-  const plan = planSql({ query: select, functions: context.functions })
+  const plan = planSql({ query: select, functions: context.functions, tables: context.tables })
   yield* executePlan({ plan, context })
 }
 
@@ -98,7 +98,7 @@ async function* executeScan(plan, context) {
   // check table
   const table = tables[plan.table]
   if (!table) {
-    throw tableNotFoundError({ tableName: plan.table })
+    throw tableNotFoundError({ table: plan.table, tables })
   }
   // check columns
   const missingColumn = plan.hints.columns?.find(col => !table.columns.includes(col))
@@ -140,7 +140,7 @@ async function* executeScan(plan, context) {
 async function* executeCount(plan, { tables, signal }) {
   const table = tables[plan.table]
   if (!table) {
-    throw tableNotFoundError({ tableName: plan.table })
+    throw tableNotFoundError({ table: plan.table, tables })
   }
 
   // Use source numRows if available

package/src/expression/alias.js

@@ -31,9 +31,9 @@ export function derivedAlias(expr) {
   if (expr.type === 'function') {
     // Handle aggregate functions with star (COUNT(*) -> count_all)
     if (expr.args.length === 1 && expr.args[0].type === 'star') {
-      return expr.name.toLowerCase() + '_all'
+      return expr.funcName.toLowerCase() + '_all'
     }
-    return expr.name.toLowerCase() + '_' + expr.args.map(derivedAlias).join('_')
+    return expr.funcName.toLowerCase() + '_' + expr.args.map(derivedAlias).join('_')
   }
   if (expr.type === 'interval') {
     return `interval_${expr.value}_${expr.unit.toLowerCase()}`

package/src/expression/evaluate.js

@@ -1,9 +1,10 @@
 import { executeSelect } from '../execute/execute.js'
 import { stringify } from '../execute/utils.js'
-import { columnNotFoundError, invalidContextError } from '../executionErrors.js'
-import { unknownFunctionError } from '../parseErrors.js'
-import { isAggregateFunc, isMathFunc, isRegexpFunc, isSpatialFunc, isStringFunc } from '../validation.js'
-import { aggregateError, argValueError, castError } from '../validationErrors.js'
+import { invalidContextError } from '../validation/executionErrors.js'
+import { aggregateError, argValueError, castError } from '../validation/expressionErrors.js'
+import { isAggregateFunc, isMathFunc, isRegexpFunc, isSpatialFunc, isStringFunc } from '../validation/functions.js'
+import { unknownFunctionError } from '../validation/parseErrors.js'
+import { columnNotFoundError } from '../validation/planErrors.js'
 import { derivedAlias } from './alias.js'
 import { applyBinaryOp } from './binary.js'
 import { applyIntervalToDate, dateTrunc, extractField } from './date.js'
@@ -99,7 +100,7 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
 
   // Function calls
   if (node.type === 'function') {
-    const funcName = node.name.toUpperCase()
+    const funcName = node.funcName.toUpperCase()
 
     // Handle aggregate functions
     if (isAggregateFunc(funcName)) {
@@ -110,11 +111,7 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
         if (row.columns.includes(alias)) {
           return row.cells[alias]()
         } else {
-          throw aggregateError({
-            funcName,
-            positionStart: node.positionStart,
-            positionEnd: node.positionEnd,
-          })
+          throw aggregateError(node)
         }
       }
 
@@ -230,23 +227,11 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       : await Promise.all(node.args.map(arg => evaluateExpr({ node: arg, row, rowIndex, rows, context })))
 
     if (isStringFunc(funcName)) {
-      return evaluateStringFunc({
-        funcName,
-        args,
-        positionStart: node.positionStart,
-        positionEnd: node.positionEnd,
-        rowIndex,
-      })
+      return evaluateStringFunc({ funcName, node, args, rowIndex })
     }
 
     if (isRegexpFunc(funcName)) {
-      return evaluateRegexpFunc({
-        funcName,
-        args,
-        positionStart: node.positionStart,
-        positionEnd: node.positionEnd,
-        rowIndex,
-      })
+      return evaluateRegexpFunc({ funcName, node, args, rowIndex })
     }
 
     if (isMathFunc(funcName)) {
@@ -296,10 +281,8 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
     if (funcName === 'JSON_OBJECT') {
       if (args.length % 2 !== 0) {
         throw argValueError({
-          funcName: 'JSON_OBJECT',
+          ...node,
           message: 'requires an even number of arguments (key-value pairs)',
-          positionStart: node.positionStart,
-          positionEnd: node.positionEnd,
           rowIndex,
         })
       }
@@ -310,10 +293,8 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
         const value = args[i + 1]
         if (key == null) {
           throw argValueError({
-            funcName: 'JSON_OBJECT',
+            ...node,
             message: 'key cannot be null',
-            positionStart: node.positionStart,
-            positionEnd: node.positionEnd,
             hint: 'All keys must be non-null values.',
             rowIndex,
           })
@@ -360,10 +341,8 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
           jsonArg = JSON.parse(jsonArg)
         } catch {
           throw argValueError({
-            funcName,
+            ...node,
             message: 'invalid JSON string',
-            positionStart: node.positionStart,
-            positionEnd: node.positionEnd,
             hint: 'First argument must be valid JSON.',
             rowIndex,
           })
@@ -371,10 +350,8 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       }
       if (typeof jsonArg !== 'object' || jsonArg instanceof Date) {
         throw argValueError({
-          funcName,
+          ...node,
           message: `first argument must be JSON string or object, got ${typeof jsonArg}`,
-          positionStart: node.positionStart,
-          positionEnd: node.positionEnd,
           rowIndex,
         })
       }
@@ -414,30 +391,20 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       }
     }
 
-    throw unknownFunctionError({
-      funcName,
-      positionStart: node.positionStart,
-      positionEnd: node.positionEnd,
-    })
+    throw unknownFunctionError(node)
   }
 
   if (node.type === 'cast') {
     const val = await evaluateExpr({ node: node.expr, row, rowIndex, rows, context })
     if (val == null) return null
-    const toType = node.toType.toUpperCase()
+    const { toType } = node
     if (toType === 'TEXT' || toType === 'STRING' || toType === 'VARCHAR') {
       if (typeof val === 'object') return stringify(val)
       return String(val)
     }
     // Can only cast primitives to other primitive types
     if (typeof val === 'object') {
-      throw castError({
-        toType: node.toType,
-        positionStart: node.positionStart,
-        positionEnd: node.positionEnd,
-        fromType: 'object',
-        rowIndex,
-      })
+      throw castError({ ...node, fromType: 'object', rowIndex })
     }
     if (toType === 'INTEGER' || toType === 'INT') {
       const num = Number(val)
@@ -455,12 +422,7 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
     if (toType === 'BOOLEAN' || toType === 'BOOL') {
       return Boolean(val)
     }
-    throw castError({
-      toType: node.toType,
-      positionStart: node.positionStart,
-      positionEnd: node.positionEnd,
-      rowIndex,
-    })
+    throw castError({ ...node, rowIndex })
   }
 
   // IN and NOT IN with value lists

package/src/expression/regexp.js

@@ -1,21 +1,20 @@
-import { argValueError } from '../validationErrors.js'
+import { argValueError } from '../validation/expressionErrors.js'
 
 /**
- * @import { SqlPrimitive } from '../types.js'
+ * @import { FunctionNode, RegExpFunction, SqlPrimitive } from '../types.js'
  */
 
 /**
  * Evaluate a regexp function
  *
  * @param {Object} options
- * @param {string} options.funcName - Uppercase function name
+ * @param {RegExpFunction} options.funcName
+ * @param {FunctionNode} options.node
  * @param {SqlPrimitive[]} options.args - Function arguments
- * @param {number} options.positionStart - Start position in SQL string for error reporting
- * @param {number} options.positionEnd - End position in SQL string for error reporting
- * @param {number} [options.rowIndex] - Row number for error reporting
+ * @param {number} options.rowIndex - Row index for error reporting
  * @returns {SqlPrimitive}
  */
-export function evaluateRegexpFunc({ funcName, args, positionStart, positionEnd, rowIndex }) {
+export function evaluateRegexpFunc({ funcName, node, args, rowIndex }) {
   if (funcName === 'REGEXP_SUBSTR') {
     const str = args[0]
     const pattern = args[1]
@@ -29,10 +28,8 @@ export function evaluateRegexpFunc({ funcName, args, positionStart, positionEnd,
       position = Number(args[2])
       if (!Number.isInteger(position) || position < 1) {
         throw argValueError({
-          funcName,
+          ...node,
           message: `position must be a positive integer, got ${args[2]}`,
-          positionStart,
-          positionEnd,
           hint: 'SQL uses 1-based indexing.',
           rowIndex,
         })
@@ -45,10 +42,9 @@ export function evaluateRegexpFunc({ funcName, args, positionStart, positionEnd,
       occurrence = Number(args[3])
       if (!Number.isInteger(occurrence) || occurrence < 1) {
         throw argValueError({
-          funcName,
+          ...node,
           message: `occurrence must be a positive integer, got ${args[3]}`,
-          positionStart,
-          positionEnd,
+          hint: 'SQL uses 1-based indexing.',
           rowIndex,
         })
       }
@@ -60,10 +56,8 @@ export function evaluateRegexpFunc({ funcName, args, positionStart, positionEnd,
       regex = new RegExp(patternStr, 'g')
     } catch (/** @type {any} */ error) {
       throw argValueError({
-        funcName,
+        ...node,
         message: `invalid regex pattern: ${error.message}`,
-        positionStart,
-        positionEnd,
         rowIndex,
       })
     }
@@ -99,10 +93,8 @@ export function evaluateRegexpFunc({ funcName, args, positionStart, positionEnd,
       position = Number(args[3])
       if (!Number.isInteger(position) || position < 1) {
         throw argValueError({
-          funcName,
+          ...node,
           message: `position must be a positive integer, got ${args[3]}`,
-          positionStart,
-          positionEnd,
           hint: 'SQL uses 1-based indexing.',
           rowIndex,
         })
@@ -115,10 +107,8 @@ export function evaluateRegexpFunc({ funcName, args, positionStart, positionEnd,
       occurrence = Number(args[4])
       if (!Number.isInteger(occurrence) || occurrence < 0) {
         throw argValueError({
-          funcName,
+          ...node,
           message: `occurrence must be a non-negative integer, got ${args[4]}`,
-          positionStart,
-          positionEnd,
           hint: 'Use 0 to replace all occurrences.',
           rowIndex,
         })
@@ -131,10 +121,8 @@ export function evaluateRegexpFunc({ funcName, args, positionStart, positionEnd,
       regex = new RegExp(patternStr, 'g')
     } catch (/** @type {any} */ error) {
       throw argValueError({
-        funcName,
+        ...node,
         message: `invalid regex pattern: ${error.message}`,
-        positionStart,
-        positionEnd,
         rowIndex,
       })
     }

package/src/expression/strings.js

@@ -1,30 +1,27 @@
 /**
- * @import { SqlPrimitive, StringFunc } from '../types.js'
+ * @import { FunctionNode, SqlPrimitive, StringFunc } from '../types.js'
  */
 
-import { argValueError } from '../validationErrors.js'
+import { argValueError } from '../validation/expressionErrors.js'
 
 /**
  * Evaluate a string function
  *
  * @param {Object} options
- * @param {StringFunc} options.funcName - Uppercase function name
+ * @param {StringFunc} options.funcName
+ * @param {FunctionNode} options.node
  * @param {SqlPrimitive[]} options.args - Function arguments
- * @param {number} options.positionStart - Start position for error reporting
- * @param {number} options.positionEnd - End position for error reporting
- * @param {number} [options.rowIndex] - Row index for error reporting
+ * @param {number} options.rowIndex - Row index for error reporting
  * @returns {SqlPrimitive}
  */
-export function evaluateStringFunc({ funcName, args, positionStart, positionEnd, rowIndex }) {
+export function evaluateStringFunc({ funcName, node, args, rowIndex }) {
   if (funcName === 'CONCAT') {
     // Returns NULL if any argument is NULL
     if (args.some(a => a == null)) return null
     if (args.some(a => typeof a === 'object')) {
       throw argValueError({
-        funcName: 'CONCAT',
+        ...node,
         message: 'does not support object arguments',
-        positionStart,
-        positionEnd,
         hint: 'Use CAST to convert objects to strings first.',
         rowIndex,
       })
@@ -53,10 +50,8 @@ export function evaluateStringFunc({ funcName, args, positionStart, positionEnd,
     const start = Number(args[1])
     if (!Number.isInteger(start) || start < 1) {
       throw argValueError({
-        funcName,
+        ...node,
         message: `start position must be a positive integer, got ${args[1]}`,
-        positionStart,
-        positionEnd,
         hint: 'SQL uses 1-based indexing.',
         rowIndex,
       })
@@ -67,10 +62,9 @@ export function evaluateStringFunc({ funcName, args, positionStart, positionEnd,
       const len = Number(args[2])
       if (!Number.isInteger(len) || len < 0) {
         throw argValueError({
-          funcName,
+          ...node,
           message: `length must be a non-negative integer, got ${args[2]}`,
-          positionStart,
-          positionEnd,
+          hint: 'SQL uses 1-based indexing.',
           rowIndex,
         })
       }
@@ -97,10 +91,9 @@ export function evaluateStringFunc({ funcName, args, positionStart, positionEnd,
     const len = Number(n)
     if (!Number.isInteger(len) || len < 0) {
       throw argValueError({
-        funcName,
+        ...node,
         message: `length must be a non-negative integer, got ${n}`,
-        positionStart,
-        positionEnd,
+        hint: 'SQL uses 1-based indexing.',
         rowIndex,
       })
     }
@@ -113,10 +106,9 @@ export function evaluateStringFunc({ funcName, args, positionStart, positionEnd,
     const len = Number(n)
     if (!Number.isInteger(len) || len < 0) {
       throw argValueError({
-        funcName,
+        ...node,
         message: `length must be a non-negative integer, got ${n}`,
-        positionStart,
-        positionEnd,
+        hint: 'SQL uses 1-based indexing.',
         rowIndex,
       })
     }

package/src/index.d.ts

@@ -55,6 +55,7 @@ export function parseSql(options: ParseSqlOptions): SelectStatement
  * @param options
  * @param options.query - SQL query string or parsed SelectStatement
  * @param options.functions - user-defined functions available in the SQL context
+ * @param options.tables - optional table metadata for planning
  * @returns the root of the query plan tree
  */
 export function planSql(options: PlanSqlOptions): QueryPlan

package/src/parse/comparison.js

@@ -1,5 +1,5 @@
-import { syntaxError } from '../parseErrors.js'
-import { isBinaryOp } from '../validation.js'
+import { isBinaryOp } from '../validation/functions.js'
+import { syntaxError } from '../validation/parseErrors.js'
 import { parseAdditive, parseExpression, parseSubquery } from './expression.js'
 import { consume, current, expect, match, peekToken } from './state.js'