squirreling 0.4.0 → 0.4.1

package/README.md

@@ -7,7 +7,7 @@
 [![minzipped](https://img.shields.io/bundlephobia/minzip/squirreling)](https://www.npmjs.com/package/squirreling)
 [![workflow status](https://github.com/hyparam/squirreling/actions/workflows/ci.yml/badge.svg)](https://github.com/hyparam/squirreling/actions)
 [![mit license](https://img.shields.io/badge/License-MIT-orange.svg)](https://opensource.org/licenses/MIT)
-![coverage](https://img.shields.io/badge/Coverage-93-darkred)
+![coverage](https://img.shields.io/badge/Coverage-95-darkred)
 [![dependencies](https://img.shields.io/badge/Dependencies-0-blueviolet)](https://www.npmjs.com/package/squirreling?activeTab=dependencies)
 
 Squirreling is a streaming async SQL engine for JavaScript. It is designed to provide efficient streaming of results from pluggable backends for highly efficient retrieval of data for browser applications.
@@ -22,8 +22,8 @@ Squirreling is a streaming async SQL engine for JavaScript. It is designed to pr
 - Constant memory usage for simple queries with LIMIT
 - Robust error handling and validation designed for LLM tool use
 - In-memory data option for simple use cases
+- Late materialization for efficiency
 - Select only
-- No joins (yet)
 
 ## Usage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Squirreling SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",

package/src/backend/dataSource.js

@@ -58,7 +58,7 @@ export function cachedDataSource(source) {
   const cache = new Map()
   return {
     /**
-     * @returns {AsyncGenerator<AsyncRow>}
+     * @yields {AsyncRow}
      */
     async *getRows() {
       let index = 0

package/src/execute/aggregates.js

@@ -1,4 +1,5 @@
 import { evaluateExpr } from './expression.js'
+import { defaultDerivedAlias } from './utils.js'
 
 /**
  * Evaluates an aggregate function over a set of rows
@@ -72,27 +73,5 @@ export async function evaluateAggregate({ col, rows, tables }) {
 export function defaultAggregateAlias(col) {
   const base = col.func.toLowerCase()
   if (col.arg.kind === 'star') return base + '_all'
-  return base + '_' + defaultAggregateAliasExpr(col.arg.expr)
-}
-
-/**
- * @param {ExprNode} expr
- * @returns {string}
- */
-export function defaultAggregateAliasExpr(expr) {
-  if (expr.type === 'identifier') {
-    return expr.name
-  } else if (expr.type === 'literal') {
-    return String(expr.value)
-  } else if (expr.type === 'cast') {
-    return defaultAggregateAliasExpr(expr.expr) + '_as_' + expr.toType
-  } else if (expr.type === 'unary') {
-    return expr.op + '_' + defaultAggregateAliasExpr(expr.argument)
-  } else if (expr.type === 'binary') {
-    return defaultAggregateAliasExpr(expr.left) + '_' + expr.op + '_' + defaultAggregateAliasExpr(expr.right)
-  } else if (expr.type === 'function') {
-    return expr.name.toLowerCase() + '_' + expr.args.map(defaultAggregateAliasExpr).join('_')
-  } else {
-    return 'expr'
-  }
+  return base + '_' + defaultDerivedAlias(col.arg.expr)
 }

package/src/execute/execute.js

@@ -1,8 +1,10 @@
-import { evaluateExpr } from './expression.js'
-import { parseSql } from '../parse/parse.js'
 import { generatorSource, memorySource } from '../backend/dataSource.js'
+import { parseSql } from '../parse/parse.js'
 import { defaultAggregateAlias, evaluateAggregate } from './aggregates.js'
+import { evaluateExpr } from './expression.js'
 import { evaluateHavingExpr } from './having.js'
+import { executeJoins } from './join.js'
+import { defaultDerivedAlias } from './utils.js'
 
 /**
  * @import { AsyncDataSource, ExecuteSqlOptions, ExprNode, OrderByItem, AsyncRow, SelectStatement, SqlPrimitive } from '../types.js'
@@ -12,15 +14,12 @@ import { evaluateHavingExpr } from './having.js'
  * Executes a SQL SELECT query against named data sources
  *
  * @param {ExecuteSqlOptions} options - the execution options
- * @returns {AsyncGenerator<AsyncRow>} async generator yielding result rows
+ * @yields {AsyncRow} async generator yielding result rows
  */
 export async function* executeSql({ tables, query }) {
   const select = parseSql(query)
 
   // Check for unsupported operations
-  if (select.joins.length) {
-    throw new Error('JOIN is not supported')
-  }
   if (!select.from) {
     throw new Error('FROM clause is required')
   }
@@ -44,53 +43,33 @@ export async function* executeSql({ tables, query }) {
  *
  * @param {SelectStatement} select
  * @param {Record<string, AsyncDataSource>} tables
- * @returns {AsyncGenerator<AsyncRow>}
+ * @yields {AsyncRow}
  */
 export async function* executeSelect(select, tables) {
   /** @type {AsyncDataSource} */
   let dataSource
-
-  if (typeof select.from === 'string') {
-    const table = tables[select.from]
-    if (table === undefined) {
-      throw new Error(`Table "${select.from}" not found`)
+  /** @type {string} */
+  let fromTableName
+
+  if (select.from.kind === 'table') {
+    // Use alias for column prefixing, but look up the actual table name
+    fromTableName = select.from.alias ?? select.from.table
+    dataSource = tables[select.from.table]
+    if (dataSource === undefined) {
+      throw new Error(`Table "${select.from.table}" not found`)
     }
-
-    dataSource = table
   } else {
     // Nested subquery - recursively resolve
+    fromTableName = select.from.alias
     dataSource = generatorSource(executeSelect(select.from.query, tables))
   }
 
-  yield* evaluateSelectAst(select, dataSource, tables)
-}
-
-/**
- * Generates a default alias for a derived column expression
- *
- * @param {ExprNode} expr - the expression node
- * @returns {string} the generated alias
- */
-function defaultDerivedAlias(expr) {
-  if (expr.type === 'identifier') {
-    return expr.name
-  }
-  if (expr.type === 'function') {
-    const base = expr.name.toLowerCase()
-    // Try to extract column names from identifier arguments
-    const columnNames = expr.args
-      .filter(arg => arg.type === 'identifier')
-      .map(arg => arg.name)
-    if (columnNames.length > 0) {
-      return base + '_' + columnNames.join('_')
-    }
-    return base
-  }
-  if (expr.type === 'cast') return 'cast_expr'
-  if (expr.type === 'unary' && expr.argument.type === 'identifier') {
-    return expr.op === '-' ? 'neg_' + expr.argument.name : 'expr'
+  // Execute JOINs if present
+  if (select.joins.length) {
+    dataSource = await executeJoins(dataSource, select.joins, fromTableName, tables)
   }
-  return 'expr'
+
+  yield* evaluateSelectAst(select, dataSource, tables)
 }
 
 /**
@@ -128,10 +107,10 @@ function compareValues(a, b) {
     return 0
   }
 
-  const as = String(a)
-  const bs = String(b)
-  if (as < bs) return -1
-  if (as > bs) return 1
+  const aa = String(a)
+  const bb = String(b)
+  if (aa < bb) return -1
+  if (aa > bb) return 1
   return 0
 }
 
@@ -285,7 +264,7 @@ async function applyOrderBy(rows, orderBy, tables) {
  * @param {SelectStatement} select
  * @param {AsyncDataSource} dataSource
  * @param {Record<string, AsyncDataSource>} tables
- * @returns {AsyncGenerator<AsyncRow>}
+ * @yields {AsyncRow}
  */
 async function* evaluateSelectAst(select, dataSource, tables) {
   // SQL priority: from, where, group by, having, select, order by, offset, limit
@@ -310,7 +289,7 @@ async function* evaluateSelectAst(select, dataSource, tables) {
  * @param {SelectStatement} select
  * @param {AsyncDataSource} dataSource
  * @param {Record<string, AsyncDataSource>} tables
- * @returns {AsyncGenerator<AsyncRow>}
+ * @yields {AsyncRow}
  */
 async function* evaluateStreaming(select, dataSource, tables) {
   let rowsYielded = 0
@@ -382,7 +361,7 @@ async function* evaluateStreaming(select, dataSource, tables) {
  * @param {Record<string, AsyncDataSource>} tables
  * @param {boolean} hasAggregate
  * @param {boolean} useGrouping
- * @returns {AsyncGenerator<AsyncRow>}
+ * @yields {AsyncRow}
  */
 async function* evaluateBuffered(select, dataSource, tables, hasAggregate, useGrouping) {
   // Step 1: Collect all rows from data source

package/src/execute/expression.js

@@ -19,15 +19,26 @@ export async function evaluateExpr({ node, row, tables }) {
   }
 
   if (node.type === 'identifier') {
-    return row[node.name]?.()
+    // Try exact match first (handles both qualified and unqualified names)
+    if (row[node.name]) {
+      return row[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[colName]) {
+        return row[colName]()
+      }
+    }
+    return undefined
   }
 
   // Scalar subquery - returns a single value
   if (node.type === 'subquery') {
     const gen = executeSelect(node.subquery, tables)
     const first = await gen.next() // Start the generator
-    gen.return() // Stop further execution
-    if (first.done) return null
+    gen.return(undefined) // Stop further execution
+    if (!first.value) return null
     /** @type {AsyncRow} */
     const firstRow = first.value
     const firstKey = Object.keys(firstRow)[0]
@@ -275,7 +286,7 @@ export async function evaluateExpr({ node, row, tables }) {
   // CASE expressions
   if (node.type === 'case') {
     // For simple CASE: evaluate the case expression once
-    const caseValue = node.caseExpr ? await evaluateExpr({ node: node.caseExpr, row, tables }) : undefined
+    const caseValue = node.caseExpr && await evaluateExpr({ node: node.caseExpr, row, tables })
 
     // Iterate through WHEN clauses
     for (const whenClause of node.whenClauses) {

package/src/execute/having.js

@@ -1,26 +1,9 @@
-/**
- * @import { AggregateFunc, AsyncDataSource, ExprNode, AsyncRow, SqlPrimitive } from '../types.js'
- */
-
 import { isAggregateFunc } from '../validation.js'
 import { evaluateExpr } from './expression.js'
 
 /**
- * Creates a context for evaluating HAVING expressions
- *
- * @param {AsyncRow} resultRow - the aggregated result row
- * @param {AsyncRow[]} group - the group of rows
- * @returns {AsyncRow} a context row for HAVING evaluation
+ * @import { AggregateFunc, AsyncDataSource, ExprNode, AsyncRow, SqlPrimitive } from '../types.js'
  */
-function createHavingContext(resultRow, group) {
-  // Include the first row of the group (for GROUP BY columns)
-  const firstRow = group[0]
-  if (firstRow) {
-    return { ...firstRow, ...resultRow }
-  } else {
-    return resultRow
-  }
-}
 
 /**
  * Evaluates a HAVING expression with support for aggregate functions
@@ -32,7 +15,8 @@ function createHavingContext(resultRow, group) {
  * @returns {Promise<boolean>} whether the HAVING condition is satisfied
  */
 export async function evaluateHavingExpr(expr, row, group, tables) {
-  const context = createHavingContext(row, group)
+  // Having context
+  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/join.js

@@ -0,0 +1,357 @@
+import { evaluateExpr } from './expression.js'
+
+/**
+ * @import { AsyncRow, AsyncDataSource, JoinClause, ExprNode } from '../types.js'
+ */
+
+/**
+ * Executes JOIN operations against a base data source
+ *
+ * @param {AsyncDataSource} leftSource - the left side of the join (FROM table)
+ * @param {JoinClause[]} joins - array of join clauses to execute
+ * @param {string} leftTableName - name of the left table (for column prefixing)
+ * @param {Record<string, AsyncDataSource>} tables - all available tables
+ * @returns {Promise<AsyncDataSource>} data source yielding joined rows
+ */
+export async function executeJoins(leftSource, joins, leftTableName, tables) {
+  let currentLeftTable = leftTableName
+
+  // Single join optimization: stream left rows without buffering
+  if (joins.length === 1) {
+    const join = joins[0]
+    const rightSource = tables[join.table]
+    if (rightSource === undefined) {
+      throw new Error(`Table "${join.table}" not found`)
+    }
+
+    // Buffer right rows for hash index (required for hash join)
+    /** @type {AsyncRow[]} */
+    const rightRows = []
+    for await (const row of rightSource.getRows()) {
+      rightRows.push(row)
+    }
+
+    // Use alias for column prefixing if present
+    const rightTableName = join.alias ?? join.table
+
+    // Return streaming data source - left rows stream through without buffering
+    return {
+      async *getRows() {
+        yield* hashJoin({
+          leftRows: leftSource.getRows(), // Stream directly, not buffered
+          rightRows,
+          join,
+          leftTable: currentLeftTable,
+          rightTable: rightTableName,
+          tables,
+        })
+      },
+    }
+  }
+
+  // Multiple joins: buffer intermediate results, stream final join
+  /** @type {AsyncRow[]} */
+  let leftRows = []
+  for await (const row of leftSource.getRows()) {
+    leftRows.push(row)
+  }
+
+  // Process all but the last join, buffering intermediate results
+  for (let i = 0; i < joins.length - 1; i++) {
+    const join = joins[i]
+    const rightSource = tables[join.table]
+    if (rightSource === undefined) {
+      throw new Error(`Table "${join.table}" not found`)
+    }
+
+    /** @type {AsyncRow[]} */
+    const rightRows = []
+    for await (const row of rightSource.getRows()) {
+      rightRows.push(row)
+    }
+
+    // Use alias for column prefixing if present
+    const rightTableName = join.alias ?? join.table
+
+    // Collect intermediate results into array for next join
+    /** @type {AsyncRow[]} */
+    const newLeftRows = []
+    const joined = hashJoin({
+      leftRows,
+      rightRows,
+      join,
+      leftTable: currentLeftTable,
+      rightTable: rightTableName,
+      tables,
+    })
+    for await (const row of joined) {
+      newLeftRows.push(row)
+    }
+    leftRows = newLeftRows
+
+    // After join, the "left" table for the next join includes all joined tables
+    currentLeftTable = `${currentLeftTable}_${rightTableName}`
+  }
+
+  // Final join: stream the results
+  const lastJoin = joins[joins.length - 1]
+  const rightSource = tables[lastJoin.table]
+  if (rightSource === undefined) {
+    throw new Error(`Table "${lastJoin.table}" not found`)
+  }
+
+  /** @type {AsyncRow[]} */
+  const rightRows = []
+  for await (const row of rightSource.getRows()) {
+    rightRows.push(row)
+  }
+
+  // Use alias for column prefixing if present
+  const lastRightTableName = lastJoin.alias ?? lastJoin.table
+
+  return {
+    async *getRows() {
+      yield* hashJoin({
+        leftRows,
+        rightRows,
+        join: lastJoin,
+        leftTable: currentLeftTable,
+        rightTable: lastRightTableName,
+        tables,
+      })
+    },
+  }
+}
+
+/**
+ * Checks if an expression references a specific table.
+ * Returns true if the expression is an identifier prefixed with the table name.
+ *
+ * @param {ExprNode} expr
+ * @param {string} tableName
+ * @returns {boolean}
+ */
+function exprReferencesTable(expr, tableName) {
+  return expr.type === 'identifier' && expr.name.startsWith(`${tableName}.`)
+}
+
+/**
+ * Extracts the join key expressions from an ON condition.
+ * Handles both `left.col = right.col` and `right.col = left.col` orderings.
+ *
+ * @param {ExprNode} onCondition
+ * @param {string} leftTable
+ * @param {string} rightTable
+ * @returns {{ leftKey: ExprNode, rightKey: ExprNode } | undefined}
+ */
+function extractJoinKeys(onCondition, leftTable, rightTable) {
+  if (onCondition.type === 'binary' && onCondition.op === '=') {
+    const { left, right } = onCondition
+
+    // Check if keys are swapped (right table referenced in left position)
+    const leftRefsRight = exprReferencesTable(left, rightTable)
+    const rightRefsLeft = exprReferencesTable(right, leftTable)
+
+    if (leftRefsRight && rightRefsLeft) {
+      // Keys are swapped, return them in correct order
+      return { leftKey: right, rightKey: left }
+    }
+
+    // Default: assume left operand is for left table
+    return { leftKey: left, rightKey: right }
+  }
+}
+
+/**
+ * Creates a NULL-filled row with the given column names
+ *
+ * @param {string[]} columnNames
+ * @returns {AsyncRow}
+ */
+function createNullRow(columnNames) {
+  /** @type {AsyncRow} */
+  const row = {}
+  for (const col of columnNames) {
+    row[col] = () => Promise.resolve(null)
+  }
+  return row
+}
+
+/**
+ * Merges two rows into one, prefixing columns with table names
+ *
+ * @param {AsyncRow} leftRow
+ * @param {AsyncRow} rightRow
+ * @param {string} leftTable
+ * @param {string} rightTable
+ * @returns {AsyncRow}
+ */
+function mergeRows(leftRow, rightRow, leftTable, rightTable) {
+  /** @type {AsyncRow} */
+  const merged = {}
+
+  // Add left table columns with prefix
+  for (const [key, cell] of Object.entries(leftRow)) {
+    // Skip already-prefixed keys (from previous joins)
+    if (!key.includes('.')) {
+      merged[`${leftTable}.${key}`] = cell
+    } else {
+      merged[key] = cell
+    }
+    // Also keep unqualified name for convenience (may be overwritten if ambiguous)
+    merged[key] = cell
+  }
+
+  // Add right table columns with prefix
+  for (const [key, cell] of Object.entries(rightRow)) {
+    if (!key.includes('.')) {
+      merged[`${rightTable}.${key}`] = cell
+    } else {
+      merged[key] = cell
+    }
+    // Unqualified name (overwrites if same name exists in left table)
+    merged[key] = cell
+  }
+
+  return merged
+}
+
+/**
+ * Performs a hash join between left and right row sets (streaming).
+ * Yields rows as they are found instead of buffering all results.
+ *
+ * @param {Object} params
+ * @param {AsyncIterable<AsyncRow>|AsyncRow[]} params.leftRows - rows from left table (can stream)
+ * @param {AsyncRow[]} params.rightRows - rows from right table (must be buffered for hash index)
+ * @param {JoinClause} params.join - join specification
+ * @param {string} params.leftTable - name of left table (for column prefixing)
+ * @param {string} params.rightTable - name of right table (for column prefixing, may be alias)
+ * @param {Record<string, AsyncDataSource>} params.tables - all tables for expression evaluation
+ * @yields {AsyncRow} joined rows
+ */
+async function* hashJoin({ leftRows, rightRows, join, leftTable, rightTable, tables }) {
+  const { joinType, on: onCondition } = join
+
+  if (!onCondition) {
+    throw new Error('JOIN requires ON condition')
+  }
+
+  const keys = extractJoinKeys(onCondition, leftTable, rightTable)
+
+  // Get column names for NULL row generation (right side is always buffered)
+  const rightCols = rightRows.length ? Object.keys(rightRows[0]) : []
+  const rightPrefixedCols = rightCols.flatMap(col =>
+    col.includes('.') ? [col] : [`${rightTable}.${col}`, col]
+  )
+
+  // Track left column info - captured from first row during iteration
+  /** @type {string[]|null} */
+  let leftPrefixedCols = null
+
+  if (keys) {
+    // Hash join: build hash map on right table
+    /** @type {Map<string, AsyncRow[]>} */
+    const hashMap = new Map()
+
+    // BUILD PHASE: Index right rows by join key
+    // Skip null keys - SQL semantics: NULL != NULL
+    for (const rightRow of rightRows) {
+      const keyValue = await evaluateExpr({ node: keys.rightKey, row: rightRow, tables })
+      if (keyValue == null) continue // NULL keys never match
+      const keyStr = JSON.stringify(keyValue)
+
+      let bucket = hashMap.get(keyStr)
+      if (!bucket) {
+        bucket = []
+        hashMap.set(keyStr, bucket)
+      }
+      bucket.push(rightRow)
+    }
+
+    // Track which right rows matched (only needed for RIGHT/FULL joins)
+    /** @type {Set<AsyncRow>|null} */
+    const matchedRightRows = joinType === 'RIGHT' || joinType === 'FULL' ? new Set() : null
+
+    // PROBE PHASE: Stream through left rows, yield matches immediately
+    for await (const leftRow of leftRows) {
+      // Capture left column info from first row (for NULL row generation)
+      if (!leftPrefixedCols) {
+        const leftCols = Object.keys(leftRow)
+        leftPrefixedCols = leftCols.flatMap(col =>
+          col.includes('.') ? [col] : [`${leftTable}.${col}`, col]
+        )
+      }
+
+      const keyValue = await evaluateExpr({ node: keys.leftKey, row: leftRow, tables })
+      const keyStr = JSON.stringify(keyValue)
+
+      const matchingRightRows = hashMap.get(keyStr)
+
+      if (matchingRightRows && matchingRightRows.length > 0) {
+        for (const rightRow of matchingRightRows) {
+          if (matchedRightRows) matchedRightRows.add(rightRow)
+          yield mergeRows(leftRow, rightRow, leftTable, rightTable)
+        }
+      } else if (joinType === 'LEFT' || joinType === 'FULL') {
+        const nullRight = createNullRow(rightPrefixedCols)
+        yield mergeRows(leftRow, nullRight, leftTable, rightTable)
+      }
+      // INNER join with no match: don't yield anything
+    }
+
+    // UNMATCHED PHASE: Handle unmatched right rows for RIGHT/FULL joins
+    if (matchedRightRows) {
+      for (const rightRow of rightRows) {
+        if (!matchedRightRows.has(rightRow)) {
+          // Use empty array if left table was empty (no rows to derive columns from)
+          const nullLeft = createNullRow(leftPrefixedCols || [])
+          yield mergeRows(nullLeft, rightRow, leftTable, rightTable)
+        }
+      }
+    }
+  } else {
+    // Fallback to nested loop for complex ON conditions
+    // Left rows stream through, right rows are iterated for each left row
+    /** @type {Set<AsyncRow>|null} */
+    const matchedRightRows = joinType === 'RIGHT' || joinType === 'FULL' ? new Set() : null
+
+    for await (const leftRow of leftRows) {
+      // Capture left column info from first row (for NULL row generation)
+      if (!leftPrefixedCols) {
+        const leftCols = Object.keys(leftRow)
+        leftPrefixedCols = leftCols.flatMap(col =>
+          col.includes('.') ? [col] : [`${leftTable}.${col}`, col]
+        )
+      }
+
+      let hasMatch = false
+
+      for (const rightRow of rightRows) {
+        const tempMerged = mergeRows(leftRow, rightRow, leftTable, rightTable)
+        const matches = await evaluateExpr({ node: onCondition, row: tempMerged, tables })
+
+        if (matches) {
+          hasMatch = true
+          if (matchedRightRows) matchedRightRows.add(rightRow)
+          yield tempMerged
+        }
+      }
+
+      if (!hasMatch && (joinType === 'LEFT' || joinType === 'FULL')) {
+        const nullRight = createNullRow(rightPrefixedCols)
+        yield mergeRows(leftRow, nullRight, leftTable, rightTable)
+      }
+    }
+
+    // Handle unmatched right rows for RIGHT/FULL joins
+    if (matchedRightRows) {
+      for (const rightRow of rightRows) {
+        if (!matchedRightRows.has(rightRow)) {
+          // Use empty array if left table was empty (no rows to derive columns from)
+          const nullLeft = createNullRow(leftPrefixedCols || [])
+          yield mergeRows(nullLeft, rightRow, leftTable, rightTable)
+        }
+      }
+    }
+  }
+}

package/src/execute/utils.js

@@ -1,7 +1,7 @@
 /**
  * Collects and materialize all results from an async row generator into an array
  *
- * @import {AsyncRow, SqlPrimitive} from '../types.js'
+ * @import {AsyncRow, ExprNode, SqlPrimitive} from '../types.js'
  * @param {AsyncGenerator<AsyncRow>} asyncRows
  * @returns {Promise<Record<string, SqlPrimitive>[]>} array of all yielded values
  */
@@ -18,3 +18,35 @@ 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') {
+    return expr.name.toLowerCase() + '_' + expr.args.map(defaultDerivedAlias).join('_')
+  }
+  return 'expr'
+}

package/src/parse/expression.js

@@ -1,7 +1,7 @@
 import { isAggregateFunc, isStringFunc } from '../validation.js'
 
 /**
- * @import { ExprCursor, ExprNode, BinaryOp } from '../types.js'
+ * @import { BinaryOp, ExprCursor, ExprNode, WhenClause } from '../types.js'
  */
 
 /**
@@ -153,7 +153,7 @@ function parsePrimary(c) {
       c.consume() // CASE
 
       // Check if it's simple CASE (CASE expr WHEN ...) or searched CASE (CASE WHEN ...)
-      /** @type {import('../types.js').ExprNode | undefined} */
+      /** @type {ExprNode | undefined} */
       let caseExpr
       const nextTok = c.current()
       if (nextTok.type !== 'keyword' || nextTok.value !== 'WHEN') {
@@ -162,7 +162,7 @@ function parsePrimary(c) {
       }
 
       // Parse WHEN clauses
-      /** @type {import('../types.js').WhenClause[]} */
+      /** @type {WhenClause[]} */
       const whenClauses = []
       while (c.match('keyword', 'WHEN')) {
         const condition = parseExpression(c)
@@ -176,7 +176,7 @@ function parsePrimary(c) {
       }
 
       // Parse optional ELSE clause
-      /** @type {import('../types.js').ExprNode | undefined} */
+      /** @type {ExprNode | undefined} */
       let elseResult
       if (c.match('keyword', 'ELSE')) {
         elseResult = parseExpression(c)

package/src/parse/parse.js

@@ -3,7 +3,7 @@ import { parseExpression } from './expression.js'
 import { isAggregateFunc } from '../validation.js'
 
 /**
- * @import { AggregateColumn, AggregateArg, AggregateFunc, ExprCursor, ExprNode, FromSubquery, JoinClause, JoinType, OrderByItem, ParserState, SelectStatement, SelectColumn, Token, TokenType } from '../types.js'
+ * @import { AggregateColumn, AggregateArg, AggregateFunc, ExprCursor, ExprNode, FromSubquery, FromTable, JoinClause, JoinType, OrderByItem, ParserState, SelectStatement, SelectColumn, Token, TokenType } from '../types.js'
  */
 
 // Keywords that cannot be used as implicit aliases after a column
@@ -17,6 +17,23 @@ const RESERVED_AFTER_COLUMN = new Set([
   'OFFSET',
 ])
 
+// Keywords that cannot be used as table aliases
+const RESERVED_AFTER_TABLE = new Set([
+  'WHERE',
+  'GROUP',
+  'HAVING',
+  'ORDER',
+  'LIMIT',
+  'OFFSET',
+  'JOIN',
+  'INNER',
+  'LEFT',
+  'RIGHT',
+  'FULL',
+  'CROSS',
+  'ON',
+])
+
 /**
  * @param {string} query
  * @returns {SelectStatement}
@@ -219,17 +236,24 @@ function parseAggregateItem(state, func) {
     const cursor = createExprCursor(state)
     const expr = parseExpression(cursor)
     expect(state, 'keyword', 'AS')
-    const typeTok = expectIdentifier(state)
+    const toType = expectIdentifier(state).value
     expect(state, 'paren', ')')
     arg = {
       kind: 'expression',
-      expr: { type: 'cast', expr, toType: typeTok.value },
+      expr: { type: 'cast', expr, toType },
     }
   } else {
-    const colTok = expectIdentifier(state)
+    // column name
+    let name = expectIdentifier(state).value
+    // Handle qualified column names like orders.amount
+    if (current(state).type === 'dot') {
+      consume(state) // consume dot
+      const qualifiedPart = expectIdentifier(state)
+      name = `${name}.${qualifiedPart.value}`
+    }
     arg = {
       kind: 'expression',
-      expr: { type: 'identifier', name: colTok.value },
+      expr: { type: 'identifier', name },
     }
   }
 
@@ -240,6 +264,25 @@ function parseAggregateItem(state, func) {
   return { kind: 'aggregate', func, arg, alias }
 }
 
+/**
+ * Parses an optional table alias (e.g., "FROM users u" or "FROM users AS u")
+ * @param {ParserState} state
+ * @returns {string | undefined}
+ */
+function parseTableAlias(state) {
+  // Check for explicit AS keyword
+  if (match(state, 'keyword', 'AS')) {
+    const aliasTok = expectIdentifier(state)
+    return aliasTok.value
+  }
+  // Check for implicit alias (identifier not in reserved list)
+  const maybeAlias = current(state)
+  if (maybeAlias.type === 'identifier' && !RESERVED_AFTER_TABLE.has(maybeAlias.value.toUpperCase())) {
+    consume(state)
+    return maybeAlias.value
+  }
+}
+
 /**
  * @param {ParserState} state
  * @returns {string | undefined}
@@ -322,9 +365,9 @@ function parseJoins(state) {
       break
     }
 
-    // Parse table name
-    const tableTok = expectIdentifier(state)
-    const tableName = tableTok.value
+    // Parse table name and optional alias
+    const tableName = expectIdentifier(state).value
+    const tableAlias = parseTableAlias(state)
 
     // Parse ON condition
     expect(state, 'keyword', 'ON')
@@ -332,8 +375,9 @@ function parseJoins(state) {
     const condition = parseExpression(cursor)
 
     joins.push({
-      type: joinType,
+      joinType,
       table: tableName,
+      alias: tableAlias,
       on: condition,
     })
   }
@@ -351,12 +395,8 @@ function parseSubquery(state) {
   const query = parseSelectInternal(state)
   expect(state, 'paren', ')')
   expect(state, 'keyword', 'AS')
-  const aliasTok = expectIdentifier(state)
-  return {
-    kind: 'subquery',
-    query,
-    alias: aliasTok.value,
-  }
+  const alias = expectIdentifier(state).value
+  return { kind: 'subquery', query, alias }
 }
 
 /**
@@ -376,6 +416,7 @@ function parseSelectInternal(state) {
   expect(state, 'keyword', 'FROM')
 
   // Check if it's a subquery or table name
+  /** @type {FromTable | FromSubquery} */
   let from
   const tok = current(state)
   if (tok.type === 'paren' && tok.value === '(') {
@@ -383,7 +424,9 @@ function parseSelectInternal(state) {
     from = parseSubquery(state)
   } else {
     // Simple table name: SELECT * FROM users
-    from = expectIdentifier(state).value
+    const table = expectIdentifier(state).value
+    const alias = parseTableAlias(state)
+    from = { kind: 'table', table, alias }
   }
 
   // Parse JOIN clauses

package/src/types.d.ts

@@ -21,7 +21,7 @@ export type SqlPrimitive = string | number | bigint | boolean | null
 export interface SelectStatement {
   distinct: boolean
   columns: SelectColumn[]
-  from: string | FromSubquery
+  from: FromTable | FromSubquery
   joins: JoinClause[]
   where?: ExprNode
   groupBy: ExprNode[]
@@ -31,6 +31,12 @@ export interface SelectStatement {
   offset?: number
 }
 
+export interface FromTable {
+  kind: 'table'
+  table: string
+  alias?: string
+}
+
 export interface FromSubquery {
   kind: 'subquery'
   query: SelectStatement
@@ -184,8 +190,9 @@ export interface OrderByItem {
 export type JoinType = 'INNER' | 'LEFT' | 'RIGHT' | 'FULL' | 'CROSS'
 
 export interface JoinClause {
-  type: JoinType
+  joinType: JoinType
   table: string
+  alias?: string
   on?: ExprNode
 }