squirreling 0.8.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Squirreling Async SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -37,10 +37,10 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "25.2.2",
+    "@types/node": "25.2.3",
     "@vitest/coverage-v8": "4.0.18",
     "eslint": "9.39.2",
-    "eslint-plugin-jsdoc": "62.5.4",
+    "eslint-plugin-jsdoc": "62.6.0",
     "typescript": "5.9.3",
     "vitest": "4.0.18"
   }

package/src/execute/aggregates.js

@@ -1,10 +1,11 @@
+import { derivedAlias } from '../expression/alias.js'
 import { evaluateExpr } from '../expression/evaluate.js'
-import { defaultDerivedAlias, stringify } from './utils.js'
 import { executePlan } from './execute.js'
+import { stringify } from './utils.js'
 
 /**
- * @import { AsyncCells, AsyncDataSource, AsyncRow, SelectColumn, UserDefinedFunction } from '../types.js'
- * @import { ExecuteContext, HashAggregateNode, ScalarAggregateNode } from '../plan/types.js'
+ * @import { AsyncCells, AsyncRow, ExecuteContext, SelectColumn } from '../types.js'
+ * @import { HashAggregateNode, ScalarAggregateNode } from '../plan/types.js'
  */
 
 /**
@@ -12,12 +13,10 @@ import { executePlan } from './execute.js'
  *
  * @param {SelectColumn[]} selectColumns
  * @param {AsyncRow[]} group
- * @param {Record<string, AsyncDataSource>} tables
- * @param {Record<string, UserDefinedFunction>} [functions]
- * @param {AbortSignal} [signal]
+ * @param {ExecuteContext} context
  * @returns {AsyncRow}
  */
-function projectAggregateColumns(selectColumns, group, tables, functions, signal) {
+function projectAggregateColumns(selectColumns, group, context) {
   /** @type {string[]} */
   const columns = []
   /** @type {AsyncCells} */
@@ -33,15 +32,13 @@ function projectAggregateColumns(selectColumns, group, tables, functions, signal
         }
       }
     } else if (col.kind === 'derived') {
-      const alias = col.alias ?? defaultDerivedAlias(col.expr)
+      const alias = col.alias ?? derivedAlias(col.expr)
       columns.push(alias)
       cells[alias] = () => evaluateExpr({
         node: col.expr,
         row: group[0] ?? { columns: [], cells: {} },
-        tables,
-        functions,
         rows: group,
-        signal,
+        context,
       })
     }
   }
@@ -57,13 +54,11 @@ function projectAggregateColumns(selectColumns, group, tables, functions, signal
  * @yields {AsyncRow}
  */
 export async function* executeHashAggregate(plan, context) {
-  const { tables, functions, signal } = context
-
   // Collect all rows
   /** @type {AsyncRow[]} */
   const allRows = []
-  for await (const row of executePlan(plan.child, context)) {
-    if (signal?.aborted) return
+  for await (const row of executePlan({ plan: plan.child, context })) {
+    if (context.signal?.aborted) return
     allRows.push(row)
   }
 
@@ -77,7 +72,7 @@ export async function* executeHashAggregate(plan, context) {
     /** @type {string[]} */
     const keyParts = []
     for (const expr of plan.groupBy) {
-      const v = await evaluateExpr({ node: expr, row, tables, functions, signal })
+      const v = await evaluateExpr({ node: expr, row, context })
       keyParts.push(stringify(v))
     }
     const key = keyParts.join('|')
@@ -92,18 +87,16 @@ export async function* executeHashAggregate(plan, context) {
 
   // Yield one row per group
   for (const group of groups) {
-    const asyncRow = projectAggregateColumns(plan.columns, group, tables, functions, signal)
+    const asyncRow = projectAggregateColumns(plan.columns, group, context)
 
     // Apply HAVING filter
     if (plan.having) {
-      const context = { ...group[0], ...asyncRow }
+      const havingRow = { ...group[0], ...asyncRow }
       const passes = await evaluateExpr({
         node: plan.having,
-        row: context,
+        row: havingRow,
         rows: group,
-        tables,
-        functions,
-        signal,
+        context,
       })
       if (!passes) continue
     }
@@ -120,28 +113,24 @@ export async function* executeHashAggregate(plan, context) {
  * @yields {AsyncRow}
  */
 export async function* executeScalarAggregate(plan, context) {
-  const { tables, functions, signal } = context
-
   // Collect all rows into single group
   /** @type {AsyncRow[]} */
   const group = []
-  for await (const row of executePlan(plan.child, context)) {
-    if (signal?.aborted) return
+  for await (const row of executePlan({ plan: plan.child, context })) {
+    if (context.signal?.aborted) return
     group.push(row)
   }
 
-  const asyncRow = projectAggregateColumns(plan.columns, group, tables, functions, signal)
+  const asyncRow = projectAggregateColumns(plan.columns, group, context)
 
   // Apply HAVING filter
   if (plan.having) {
-    const context = { ...group[0], ...asyncRow }
+    const havingRow = { ...group[0], ...asyncRow }
     const passes = await evaluateExpr({
       node: plan.having,
-      row: context,
+      row: havingRow,
       rows: group,
-      tables,
-      functions,
-      signal,
+      context,
     })
     if (!passes) return
   }

package/src/execute/execute.js

@@ -1,36 +1,28 @@
 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 { missingClauseError } from '../parseErrors.js'
-import { queryPlan } from '../plan/plan.js'
+import { planSql } from '../plan/plan.js'
 import { executeHashAggregate, executeScalarAggregate } from './aggregates.js'
 import { executeHashJoin, executeNestedLoopJoin, executePositionalJoin } from './join.js'
 import { executeSort } from './sort.js'
-import { defaultDerivedAlias, stableRowKey } from './utils.js'
+import { stableRowKey } from './utils.js'
 
 /**
- * @import { AsyncCells, AsyncDataSource, AsyncRow, ExecuteSqlOptions, ExprNode, SelectStatement, UserDefinedFunction } from '../types.js'
- * @import { DistinctNode, ExecuteContext, FilterNode, LimitNode, ProjectNode, QueryPlan, ScanNode } from '../plan/types.js'
+ * @import { AsyncCells, AsyncDataSource, AsyncRow, ExecuteContext, ExecuteSqlOptions, ExprNode, SelectStatement } from '../types.js'
+ * @import { DistinctNode, FilterNode, LimitNode, ProjectNode, QueryPlan, ScanNode } from '../plan/types.js'
  */
 
 /**
- * Executes a SQL SELECT query against named data sources
+ * Executes a SQL SELECT query against tables
  *
- * @param {ExecuteSqlOptions} options - the execution options
- * @yields {AsyncRow} async generator yielding result rows
+ * @param {ExecuteSqlOptions} options
+ * @yields {AsyncRow}
  */
 export async function* executeSql({ tables, query, functions, signal }) {
   const select = typeof query === 'string' ? parseSql({ query, functions }) : query
 
-  // Check for unsupported operations
-  if (!select.from) {
-    throw missingClauseError({
-      missing: 'FROM clause',
-      context: 'SELECT statement',
-    })
-  }
-
   // Normalize tables: convert arrays to AsyncDataSource
   /** @type {Record<string, AsyncDataSource>} */
   const normalizedTables = {}
@@ -42,7 +34,7 @@ export async function* executeSql({ tables, query, functions, signal }) {
     }
   }
 
-  yield* executeSelect({ select, tables: normalizedTables, functions, signal })
+  yield* executeSelect({ select, context: { tables: normalizedTables, functions, signal } })
 }
 
 /**
@@ -50,24 +42,23 @@ export async function* executeSql({ tables, query, functions, signal }) {
  *
  * @param {Object} options
  * @param {SelectStatement} options.select
- * @param {Record<string, AsyncDataSource>} options.tables
- * @param {Record<string, UserDefinedFunction>} [options.functions]
- * @param {AbortSignal} [options.signal]
+ * @param {ExecuteContext} options.context
  * @yields {AsyncRow}
  */
-export async function* executeSelect({ select, tables, functions, signal }) {
-  const plan = queryPlan(select)
-  yield* executePlan(plan, { tables, functions, signal })
+export async function* executeSelect({ select, context }) {
+  const plan = planSql({ query: select, functions: context.functions })
+  yield* executePlan({ plan, context })
 }
 
 /**
  * Executes a query plan and yields result rows
  *
- * @param {QueryPlan} plan - the query plan to execute
- * @param {ExecuteContext} context - execution context
+ * @param {Object} options
+ * @param {QueryPlan} options.plan - the query plan to execute
+ * @param {ExecuteContext} options.context - execution context
  * @returns {AsyncGenerator<AsyncRow>}
  */
-export async function* executePlan(plan, context) {
+export async function* executePlan({ plan, context }) {
   if (plan.type === 'Scan') {
     yield* executeScan(plan, context)
   } else if (plan.type === 'Filter') {
@@ -147,7 +138,7 @@ async function* filterRows(rows, condition, context) {
   for await (const row of rows) {
     if (context.signal?.aborted) return
     rowIndex++
-    const pass = await evaluateExpr({ node: condition, row, rowIndex, ...context })
+    const pass = await evaluateExpr({ node: condition, row, rowIndex, context })
     if (pass) yield row
   }
 }
@@ -187,7 +178,7 @@ async function* limitRows(rows, limit, offset, signal) {
  * @yields {AsyncRow}
  */
 async function* executeFilter(plan, context) {
-  yield* filterRows(executePlan(plan.child, context), plan.condition, context)
+  yield* filterRows(executePlan({ plan: plan.child, context }), plan.condition, context)
 }
 
 /**
@@ -198,11 +189,10 @@ async function* executeFilter(plan, context) {
  * @yields {AsyncRow}
  */
 async function* executeProject(plan, context) {
-  const { tables, functions, signal } = context
   let rowIndex = 0
 
-  for await (const row of executePlan(plan.child, context)) {
-    if (signal?.aborted) return
+  for await (const row of executePlan({ plan: plan.child, context })) {
+    if (context.signal?.aborted) return
     rowIndex++
     const currentRowIndex = rowIndex
 
@@ -218,15 +208,13 @@ async function* executeProject(plan, context) {
           cells[key] = row.cells[key]
         }
       } else if (col.kind === 'derived') {
-        const alias = col.alias ?? defaultDerivedAlias(col.expr)
+        const alias = col.alias ?? derivedAlias(col.expr)
         columns.push(alias)
         cells[alias] = () => evaluateExpr({
           node: col.expr,
           row,
-          tables,
-          functions,
           rowIndex: currentRowIndex,
-          signal,
+          context,
         })
       }
     }
@@ -248,7 +236,7 @@ async function* executeDistinct(plan, context) {
   /** @type {Set<string>} */
   const seen = new Set()
 
-  for await (const row of executePlan(plan.child, context)) {
+  for await (const row of executePlan({ plan: plan.child, context })) {
     if (signal?.aborted) return
 
     const key = await stableRowKey(row.cells)
@@ -267,5 +255,5 @@ async function* executeDistinct(plan, context) {
  * @yields {AsyncRow}
  */
 async function* executeLimit(plan, context) {
-  yield* limitRows(executePlan(plan.child, context), plan.limit, plan.offset, context.signal)
+  yield* limitRows(executePlan({ plan: plan.child, context }), plan.limit, plan.offset, context.signal)
 }

package/src/execute/join.js

@@ -1,11 +1,10 @@
 import { evaluateExpr } from '../expression/evaluate.js'
-import { missingClauseError } from '../parseErrors.js'
 import { stringify } from './utils.js'
 import { executePlan } from './execute.js'
 
 /**
- * @import { AsyncCells, AsyncRow } from '../types.js'
- * @import { ExecuteContext, HashJoinNode, NestedLoopJoinNode, PositionalJoinNode } from '../plan/types.js'
+ * @import { AsyncCells, AsyncRow, ExecuteContext } from '../types.js'
+ * @import { HashJoinNode, NestedLoopJoinNode, PositionalJoinNode } from '../plan/types.js'
  */
 
 /**
@@ -16,22 +15,14 @@ import { executePlan } from './execute.js'
  * @yields {AsyncRow}
  */
 export async function* executeNestedLoopJoin(plan, context) {
-  const { tables, functions, signal } = context
   const leftTable = plan.leftAlias
   const rightTable = plan.rightAlias
 
-  if (!plan.condition) {
-    throw missingClauseError({
-      missing: 'ON condition',
-      context: 'JOIN',
-    })
-  }
-
   // Buffer right rows
   /** @type {AsyncRow[]} */
   const rightRows = []
-  for await (const row of executePlan(plan.right, context)) {
-    if (signal?.aborted) return
+  for await (const row of executePlan({ plan: plan.right, context })) {
+    if (context.signal?.aborted) return
     rightRows.push(row)
   }
 
@@ -43,8 +34,8 @@ export async function* executeNestedLoopJoin(plan, context) {
   /** @type {Set<AsyncRow> | null} */
   const matchedRightRows = plan.joinType === 'RIGHT' || plan.joinType === 'FULL' ? new Set() : null
 
-  for await (const leftRow of executePlan(plan.left, context)) {
-    if (signal?.aborted) break
+  for await (const leftRow of executePlan({ plan: plan.left, context })) {
+    if (context.signal?.aborted) break
 
     if (!leftPrefixedCols) {
       leftPrefixedCols = prefixColumns(leftRow.columns, leftTable)
@@ -57,9 +48,7 @@ export async function* executeNestedLoopJoin(plan, context) {
       const matches = await evaluateExpr({
         node: plan.condition,
         row: tempMerged,
-        tables,
-        functions,
-        signal,
+        context,
       })
 
       if (matches) {
@@ -101,14 +90,14 @@ export async function* executePositionalJoin(plan, context) {
   // Buffer both sides (required for positional join)
   /** @type {AsyncRow[]} */
   const leftRows = []
-  for await (const row of executePlan(plan.left, context)) {
+  for await (const row of executePlan({ plan: plan.left, context })) {
     if (signal?.aborted) return
     leftRows.push(row)
   }
 
   /** @type {AsyncRow[]} */
   const rightRows = []
-  for await (const row of executePlan(plan.right, context)) {
+  for await (const row of executePlan({ plan: plan.right, context })) {
     if (signal?.aborted) return
     rightRows.push(row)
   }
@@ -135,15 +124,14 @@ export async function* executePositionalJoin(plan, context) {
  * @yields {AsyncRow}
  */
 export async function* executeHashJoin(plan, context) {
-  const { tables, functions, signal } = context
   const leftTable = plan.leftAlias
   const rightTable = plan.rightAlias
 
   // Buffer right rows and build hash map
   /** @type {AsyncRow[]} */
   const rightRows = []
-  for await (const row of executePlan(plan.right, context)) {
-    if (signal?.aborted) return
+  for await (const row of executePlan({ plan: plan.right, context })) {
+    if (context.signal?.aborted) return
     rightRows.push(row)
   }
 
@@ -153,9 +141,7 @@ export async function* executeHashJoin(plan, context) {
     const keyValue = await evaluateExpr({
       node: plan.rightKey,
       row: rightRow,
-      tables,
-      functions,
-      signal,
+      context,
     })
     if (keyValue == null) continue
     const keyStr = stringify(keyValue)
@@ -177,8 +163,8 @@ export async function* executeHashJoin(plan, context) {
   const matchedRightRows = plan.joinType === 'RIGHT' || plan.joinType === 'FULL' ? new Set() : null
 
   // Probe phase: stream left rows
-  for await (const leftRow of executePlan(plan.left, context)) {
-    if (signal?.aborted) break
+  for await (const leftRow of executePlan({ plan: plan.left, context })) {
+    if (context.signal?.aborted) break
 
     if (!leftPrefixedCols) {
       leftPrefixedCols = prefixColumns(leftRow.columns, leftTable)
@@ -187,9 +173,7 @@ export async function* executeHashJoin(plan, context) {
     const keyValue = await evaluateExpr({
       node: plan.leftKey,
       row: leftRow,
-      tables,
-      functions,
-      signal,
+      context,
     })
     const keyStr = stringify(keyValue)
     const matchingRightRows = hashMap.get(keyStr)

package/src/execute/sort.js

@@ -3,8 +3,8 @@ import { executePlan } from './execute.js'
 import { compareForTerm } from './utils.js'
 
 /**
- * @import { AsyncRow, SqlPrimitive } from '../types.js'
- * @import { ExecuteContext, SortNode } from '../plan/types.js'
+ * @import { AsyncRow, ExecuteContext, SqlPrimitive } from '../types.js'
+ * @import { SortNode } from '../plan/types.js'
  */
 
 /**
@@ -15,13 +15,11 @@ import { compareForTerm } from './utils.js'
  * @yields {AsyncRow}
  */
 export async function* executeSort(plan, context) {
-  const { tables, functions, signal } = context
-
   // Buffer all rows
   /** @type {AsyncRow[]} */
   const rows = []
-  for await (const row of executePlan(plan.child, context)) {
-    if (signal?.aborted) return
+  for await (const row of executePlan({ plan: plan.child, context })) {
+    if (context.signal?.aborted) return
     rows.push(row)
   }
 
@@ -51,10 +49,7 @@ export async function* executeSort(plan, context) {
           evaluatedValues[idx][orderByIdx] = await evaluateExpr({
             node: term.expr,
             row: rows[idx],
-            tables,
-            functions,
-            aliases: plan.aliases,
-            signal,
+            context,
           })
         }
       }

package/src/execute/utils.js

@@ -1,5 +1,5 @@
 /**
- * @import { AsyncCells, AsyncRow, ExprNode, OrderByItem, SqlPrimitive } from '../types.js'
+ * @import { AsyncCells, AsyncRow, OrderByItem, SqlPrimitive } from '../types.js'
  */
 
 /**
@@ -57,45 +57,6 @@ export async function collect(asyncRows) {
   return results
 }
 
-/**
- * Generates a default alias for a derived column expression
- *
- * @param {ExprNode} expr - the expression node
- * @returns {string} the generated alias
- */
-export function defaultDerivedAlias(expr) {
-  if (expr.type === 'identifier') {
-    // For qualified names like 'users.name', use just the column part as alias
-    if (expr.name.includes('.')) {
-      return expr.name.split('.').pop()
-    }
-    return expr.name
-  }
-  if (expr.type === 'literal') {
-    return String(expr.value)
-  }
-  if (expr.type === 'cast') {
-    return defaultDerivedAlias(expr.expr) + '_as_' + expr.toType
-  }
-  if (expr.type === 'unary') {
-    return expr.op + '_' + defaultDerivedAlias(expr.argument)
-  }
-  if (expr.type === 'binary') {
-    return defaultDerivedAlias(expr.left) + '_' + expr.op + '_' + defaultDerivedAlias(expr.right)
-  }
-  if (expr.type === 'function') {
-    // Handle aggregate functions with star (COUNT(*) -> count_all)
-    if (expr.args.length === 1 && expr.args[0].type === 'identifier' && expr.args[0].name === '*') {
-      return expr.name.toLowerCase() + '_all'
-    }
-    return expr.name.toLowerCase() + '_' + expr.args.map(defaultDerivedAlias).join('_')
-  }
-  if (expr.type === 'interval') {
-    return `interval_${expr.value}_${expr.unit.toLowerCase()}`
-  }
-  return 'expr'
-}
-
 /**
  * @param {SqlPrimitive} value
  * @returns {string}

package/src/expression/alias.js

@@ -0,0 +1,42 @@
+/**
+ * @import { ExprNode } from '../types.js'
+ */
+
+/**
+ * Generates a default alias for a derived column expression
+ *
+ * @param {ExprNode} expr - the expression node
+ * @returns {string} the generated alias
+ */
+export function derivedAlias(expr) {
+  if (expr.type === 'identifier') {
+    // For qualified names like 'users.name', use just the column part as alias
+    if (expr.name.includes('.')) {
+      return expr.name.split('.').pop()
+    }
+    return expr.name
+  }
+  if (expr.type === 'literal') {
+    return String(expr.value)
+  }
+  if (expr.type === 'cast') {
+    return derivedAlias(expr.expr) + '_as_' + expr.toType
+  }
+  if (expr.type === 'unary') {
+    return expr.op + '_' + derivedAlias(expr.argument)
+  }
+  if (expr.type === 'binary') {
+    return derivedAlias(expr.left) + '_' + expr.op + '_' + derivedAlias(expr.right)
+  }
+  if (expr.type === 'function') {
+    // Handle aggregate functions with star (COUNT(*) -> count_all)
+    if (expr.args.length === 1 && expr.args[0].type === 'identifier' && expr.args[0].name === '*') {
+      return expr.name.toLowerCase() + '_all'
+    }
+    return expr.name.toLowerCase() + '_' + expr.args.map(derivedAlias).join('_')
+  }
+  if (expr.type === 'interval') {
+    return `interval_${expr.value}_${expr.unit.toLowerCase()}`
+  }
+  return 'expr'
+}