squirreling 0.7.4 → 0.7.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "Squirreling SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -37,10 +37,10 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "25.0.3",
+    "@types/node": "25.0.6",
     "@vitest/coverage-v8": "4.0.16",
     "eslint": "9.39.2",
-    "eslint-plugin-jsdoc": "61.5.0",
+    "eslint-plugin-jsdoc": "62.0.0",
     "typescript": "5.9.3",
     "vitest": "4.0.16"
   }

package/src/execute/execute.js

@@ -10,7 +10,7 @@ import { resolveTableSource } from './tableSource.js'
 import { compareForTerm, defaultDerivedAlias, stringify } from './utils.js'
 
 /**
- * @import { AsyncCells, AsyncDataSource, AsyncRow, CTEDefinition, ExecuteSqlOptions, OrderByItem, QueryHints, SelectStatement, SqlPrimitive, UserDefinedFunction, WithClause } from '../types.js'
+ * @import { AsyncCells, AsyncDataSource, AsyncRow, ExecuteSqlOptions, ExprNode, OrderByItem, QueryHints, SelectColumn, SelectStatement, SqlPrimitive, UserDefinedFunction, WithClause } from '../types.js'
  */
 
 /**
@@ -143,9 +143,10 @@ async function applyDistinct(rows, distinct) {
  * @param {OrderByItem[]} options.orderBy - the sort specifications
  * @param {Record<string, AsyncDataSource>} options.tables
  * @param {Record<string, UserDefinedFunction>} [options.functions]
+ * @param {Map<string, ExprNode>} [options.aliases] - SELECT column aliases for ORDER BY resolution
  * @returns {Promise<AsyncRow[]>} the sorted rows
  */
-async function sortRows({ rows, orderBy, tables, functions }) {
+async function sortRows({ rows, orderBy, tables, functions, aliases }) {
   if (!orderBy.length) return rows
 
   // Cache for evaluated values: evaluatedValues[rowIdx][colIdx]
@@ -177,6 +178,7 @@ async function sortRows({ rows, orderBy, tables, functions }) {
             row: rows[idx],
             tables,
             functions,
+            aliases,
           })
         }
       }
@@ -459,7 +461,16 @@ async function* evaluateBuffered({ select, dataSource, tables, functions, hasAgg
   } else {
     // No grouping, simple projection
     // Sort before projection so ORDER BY can access columns not in SELECT
-    const sorted = await sortRows({ rows: filtered, orderBy: select.orderBy, tables, functions })
+
+    // Pass aliases so ORDER BY can reference SELECT column aliases
+    /** @type {Map<string, ExprNode>} */
+    const aliases = new Map()
+    for (const col of select.columns) {
+      if (col.kind === 'derived' && col.alias) {
+        aliases.set(col.alias, col.expr)
+      }
+    }
+    const sorted = await sortRows({ rows: filtered, orderBy: select.orderBy, tables, functions, aliases })
 
     // OPTIMIZATION: For non-DISTINCT queries, apply OFFSET/LIMIT before projection
     // to avoid reading expensive cells for rows that won't be in the final result

package/src/execute/expression.js

@@ -1,5 +1,5 @@
 import { unknownFunctionError } from '../parseErrors.js'
-import { invalidContextError } from '../executionErrors.js'
+import { columnNotFoundError, invalidContextError } from '../executionErrors.js'
 import { aggregateError, argValueError, castError } from '../validationErrors.js'
 import { isAggregateFunc, isMathFunc, isRegexpFunc, isStringFunc } from '../validation.js'
 import { applyIntervalToDate } from './date.js'
@@ -23,26 +23,38 @@ import { applyBinaryOp, stringify } from './utils.js'
  * @param {Record<string, UserDefinedFunction>} [params.functions] - User-defined functions
  * @param {number} [params.rowIndex] - 1-based row index for error reporting
  * @param {AsyncRow[]} [params.rows] - Group of rows for aggregate functions
+ * @param {Map<string, ExprNode>} [params.aliases] - SELECT column aliases for ORDER BY resolution
  * @returns {Promise<SqlPrimitive>} The result of the evaluation
  */
-export async function evaluateExpr({ node, row, tables, functions, rowIndex, rows }) {
+export async function evaluateExpr({ node, row, tables, functions, rowIndex, rows, aliases }) {
   if (node.type === 'literal') {
     return node.value
   }
 
   if (node.type === 'identifier') {
     // Try exact match first (handles both qualified and unqualified names)
-    if (row.cells[node.name]) {
+    if (node.name in row.cells) {
       return row.cells[node.name]()
     }
     // For qualified names like 'users.id', also try just the column part
     if (node.name.includes('.')) {
       const colName = node.name.split('.').pop()
-      if (colName && row.cells[colName]) {
+      if (colName && colName in row.cells) {
         return row.cells[colName]()
       }
     }
-    return null
+    // Check if it's a SELECT alias (for ORDER BY)
+    if (aliases?.has(node.name)) {
+      return evaluateExpr({ node: aliases.get(node.name), row, tables, functions, rowIndex, rows, aliases })
+    }
+    // Unknown identifier
+    throw columnNotFoundError({
+      columnName: node.name,
+      availableColumns: Object.keys(row.cells),
+      positionStart: node.positionStart,
+      positionEnd: node.positionEnd,
+      rowNumber: rowIndex,
+    })
   }
 
   // Scalar subquery - returns a single value
@@ -57,16 +69,16 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
   // Unary operators
   if (node.type === 'unary') {
     if (node.op === 'NOT') {
-      return !await evaluateExpr({ node: node.argument, row, tables, functions, rowIndex, rows })
+      return !await evaluateExpr({ node: node.argument, row, tables, functions, rowIndex, rows, aliases })
     }
     if (node.op === 'IS NULL') {
-      return await evaluateExpr({ node: node.argument, row, tables, functions, rowIndex, rows }) == null
+      return await evaluateExpr({ node: node.argument, row, tables, functions, rowIndex, rows, aliases }) == null
     }
     if (node.op === 'IS NOT NULL') {
-      return await evaluateExpr({ node: node.argument, row, tables, functions, rowIndex, rows }) != null
+      return await evaluateExpr({ node: node.argument, row, tables, functions, rowIndex, rows, aliases }) != null
     }
     if (node.op === '-') {
-      const val = await evaluateExpr({ node: node.argument, row, tables, functions, rowIndex, rows })
+      const val = await evaluateExpr({ node: node.argument, row, tables, functions, rowIndex, rows, aliases })
       if (val == null) return null
       return -val
     }
@@ -76,15 +88,15 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
   if (node.type === 'binary') {
     // Handle date +/- interval at AST level
     if ((node.op === '+' || node.op === '-') && node.right.type === 'interval') {
-      const dateVal = await evaluateExpr({ node: node.left, row, tables, functions, rowIndex, rows })
+      const dateVal = await evaluateExpr({ node: node.left, row, tables, functions, rowIndex, rows, aliases })
       return applyIntervalToDate(dateVal, node.right.value, node.right.unit, node.op)
     }
     if (node.op === '+' && node.left.type === 'interval') {
-      const dateVal = await evaluateExpr({ node: node.right, row, tables, functions, rowIndex, rows })
+      const dateVal = await evaluateExpr({ node: node.right, row, tables, functions, rowIndex, rows, aliases })
       return applyIntervalToDate(dateVal, node.left.value, node.left.unit, '+')
     }
 
-    const left = await evaluateExpr({ node: node.left, row, tables, functions, rowIndex, rows })
+    const left = await evaluateExpr({ node: node.left, row, tables, functions, rowIndex, rows, aliases })
 
     // Short-circuit evaluation for AND and OR
     if (node.op === 'AND') {
@@ -94,7 +106,7 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
       if (left) return true
     }
 
-    const right = await evaluateExpr({ node: node.right, row, tables, functions, rowIndex, rows })
+    const right = await evaluateExpr({ node: node.right, row, tables, functions, rowIndex, rows, aliases })
     return applyBinaryOp(node.op, left, right)
   }
 
@@ -196,7 +208,7 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
     }
 
     /** @type {SqlPrimitive[]} */
-    const args = await Promise.all(node.args.map(arg => evaluateExpr({ node: arg, row, tables, functions, rowIndex, rows })))
+    const args = await Promise.all(node.args.map(arg => evaluateExpr({ node: arg, row, tables, functions, rowIndex, rows, aliases })))
 
     if (isStringFunc(funcName)) {
       return evaluateStringFunc({

package/src/execute/having.js

@@ -20,7 +20,7 @@ import { applyBinaryOp } from './utils.js'
  */
 export async function evaluateHavingExpr({ expr, row, group, tables, functions }) {
   // Having context
-  const context = { ...group[0] ?? {}, ...row }
+  const context = { ...group[0], ...row }
 
   // For HAVING, we need special handling of aggregate functions
   // They need to be re-evaluated against the group

package/src/execute/utils.js

@@ -1,5 +1,5 @@
 /**
- * @import {AsyncRow, BinaryOp, ExprNode, OrderByItem, SqlPrimitive} from '../types.js'
+ * @import { AsyncRow, BinaryOp, ExprNode, OrderByItem, SqlPrimitive } from '../types.js'
  */
 
 /**

package/src/executionErrors.js

@@ -24,8 +24,6 @@ export class ExecutionError extends Error {
 }
 
 /**
- * Error for missing table.
- *
  * @param {Object} options
  * @param {string} options.tableName - The missing table name
  * @returns {Error}
@@ -50,8 +48,6 @@ export function invalidContextError({ item, validContext, positionStart, positio
 }
 
 /**
- * Error for unsupported operation combinations.
- *
  * @param {Object} options
  * @param {string} options.operation - The unsupported operation
  * @param {string} [options.hint] - How to fix it
@@ -61,3 +57,24 @@ export function unsupportedOperationError({ operation, hint }) {
   const suffix = hint ? `. ${hint}` : ''
   return new Error(`${operation}${suffix}`)
 }
+
+/**
+ * @param {Object} options
+ * @param {string} options.columnName - The missing column name
+ * @param {string[]} options.availableColumns - List of available column names
+ * @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 columnNotFoundError({ columnName, availableColumns, positionStart, positionEnd, rowNumber }) {
+  const available = availableColumns.length > 0
+    ? `. Available columns: ${availableColumns.join(', ')}`
+    : ''
+  return new ExecutionError({
+    message: `Column "${columnName}" not found${available}`,
+    positionStart,
+    positionEnd,
+    rowNumber,
+  })
+}

package/src/parse/parse.js

@@ -97,29 +97,32 @@ export function parseSql({ query, functions }) {
 function parseSelectList(state) {
   /** @type {SelectColumn[]} */
   const cols = []
-  const tok = current(state)
 
-  // Check for qualified asterisk (table.*)
-  if (tok.type === 'identifier') {
-    const next = peekToken(state, 1)
-    const nextNext = peekToken(state, 2)
-    if (next.type === 'dot' && nextNext.type === 'operator' && nextNext.value === '*') {
-      const tableTok = consume(state) // consume table name
-      consume(state) // consume dot
-      consume(state) // consume asterisk
-      cols.push({ kind: 'star', table: tableTok.value })
-      return cols
+  while (true) {
+    const tok = current(state)
+
+    // Check for qualified asterisk (table.*)
+    if (tok.type === 'identifier') {
+      const next = peekToken(state, 1)
+      const nextNext = peekToken(state, 2)
+      if (next.type === 'dot' && nextNext.type === 'operator' && nextNext.value === '*') {
+        const tableTok = consume(state) // consume table name
+        consume(state) // consume dot
+        consume(state) // consume asterisk
+        cols.push({ kind: 'star', table: tableTok.value })
+        if (!match(state, 'comma')) break
+        continue
+      }
     }
-  }
 
-  // Check for unqualified asterisk (*)
-  if (tok.type === 'operator' && tok.value === '*') {
-    consume(state)
-    cols.push({ kind: 'star' })
-    return cols
-  }
+    // Check for unqualified asterisk (*)
+    if (tok.type === 'operator' && tok.value === '*') {
+      consume(state)
+      cols.push({ kind: 'star' })
+      if (!match(state, 'comma')) break
+      continue
+    }
 
-  while (true) {
     cols.push(parseSelectItem(state))
     if (!match(state, 'comma')) break
   }

package/src/types.d.ts

@@ -38,7 +38,7 @@ export interface ScanOptions {
  * All hints are optional and "best effort" - sources may ignore them.
  */
 export interface QueryHints {
-  columns?: string[] // columns needed
+  columns?: string[] // columns needed (undefined means all columns)
   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

package/src/validation.js

@@ -1,6 +1,6 @@
 
 /**
- * @import {AggregateFunc, BinaryOp, ComparisonOp, IntervalUnit, MathFunc, StringFunc, UserDefinedFunction} from './types.js'
+ * @import { AggregateFunc, BinaryOp, IntervalUnit, MathFunc, StringFunc, UserDefinedFunction } from './types.js'
  * @param {string} name
  * @returns {name is AggregateFunc}
  */