squirreling 0.12.17 → 0.12.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.12.17",
+  "version": "0.12.19",
   "description": "Squirreling Async SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -39,7 +39,7 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "25.6.0",
+    "@types/node": "25.6.2",
     "@vitest/coverage-v8": "4.1.5",
     "eslint": "9.39.4",
     "eslint-plugin-jsdoc": "62.9.0",

package/src/ast.d.ts

@@ -12,7 +12,7 @@ export interface SelectStatement extends AstBase {
   type: 'select'
   distinct: boolean
   columns: SelectColumn[]
-  from: FromTable | FromSubquery | FromFunction
+  from?: FromTable | FromSubquery | FromFunction
   joins: JoinClause[]
   where?: ExprNode
   groupBy: ExprNode[]

package/src/execute/execute.js

@@ -83,6 +83,8 @@ export function executeStatement({ query, context, outerScope }) {
 export function executePlan({ plan, context }) {
   if (plan.type === 'Scan') {
     return executeScan(plan, context)
+  } else if (plan.type === 'SingleRow') {
+    return executeSingleRow()
   } else if (plan.type === 'Count') {
     return executeCount(plan, context)
   } else if (plan.type === 'Filter') {
@@ -117,6 +119,23 @@ export function executePlan({ plan, context }) {
   return { columns: [], async *rows() {} }
 }
 
+/**
+ * Yields exactly one empty row. Used for FROM-less SELECT like `SELECT 1`,
+ * where the projection produces the output from constant expressions.
+ *
+ * @returns {QueryResults}
+ */
+function executeSingleRow() {
+  return {
+    columns: [],
+    numRows: 1,
+    maxRows: 1,
+    async *rows() {
+      yield { columns: [], cells: {} }
+    },
+  }
+}
+
 /**
  * Executes a table-valued function (e.g. UNNEST, JSON_EACH).
  * Evaluates the argument once against the outer row (for lateral joins) or an

package/src/index.d.ts

@@ -53,6 +53,18 @@ export function executePlan(options: { plan: QueryPlan, context: ExecuteContext
  */
 export function parseSql(options: ParseSqlOptions): Statement
 
+/**
+ * Collects every external table referenced from FROM and JOIN clauses in a
+ * parsed statement, descending into subqueries (IN, EXISTS, derived tables,
+ * scalar subqueries) and the branches of compound queries. CTE names defined
+ * by an enclosing WITH are skipped. Returned in first-seen order with
+ * duplicates removed.
+ *
+ * @param statement - parsed SQL statement (output of `parseSql`)
+ * @returns table names referenced in the query, excluding CTE aliases
+ */
+export function extractTables(statement: Statement): string[]
+
 /**
  * Builds a query plan from a SQL query string or AST
  *

package/src/index.js

@@ -1,4 +1,5 @@
 export { executePlan, executeSql } from './execute/execute.js'
+export { extractTables } from './parse/extractTables.js'
 export { parseSql } from './parse/parse.js'
 export { planSql } from './plan/plan.js'
 export { tokenizeSql } from './parse/tokenize.js'

package/src/parse/extractTables.js

@@ -0,0 +1,127 @@
+/**
+ * @import { ExprNode, Statement } from '../types.js'
+ */
+
+/**
+ * Collect every external table referenced from FROM and JOIN clauses in a
+ * parsed statement, including those inside subqueries (IN, EXISTS, derived
+ * tables, scalar subqueries) and the branches of compound (UNION /
+ * INTERSECT / EXCEPT) queries. CTE names defined by an enclosing WITH are
+ * skipped, including across sibling CTEs and nested WITHs. The result is
+ * the set of names a caller would need to provide as `tables` to
+ * `executeSql`.
+ *
+ * Returned in first-seen order with duplicates removed. Names are returned
+ * in the original case they were written in the query.
+ *
+ * @param {Statement} statement
+ * @returns {string[]}
+ */
+export function extractTables(statement) {
+  /** @type {Set<string>} */
+  const refs = new Set()
+  walkStatement(statement, new Set(), refs)
+  return [...refs]
+}
+
+/**
+ * @param {Statement} stmt
+ * @param {Set<string>} cteScope - lowercased CTE names visible at this point
+ * @param {Set<string>} refs
+ * @returns {void}
+ */
+function walkStatement(stmt, cteScope, refs) {
+  if (stmt.type === 'with') {
+    const scope = new Set(cteScope)
+    for (const cte of stmt.ctes) {
+      walkStatement(cte.query, scope, refs)
+      scope.add(cte.name.toLowerCase())
+    }
+    walkStatement(stmt.query, scope, refs)
+    return
+  }
+  if (stmt.type === 'compound') {
+    walkStatement(stmt.left, cteScope, refs)
+    walkStatement(stmt.right, cteScope, refs)
+    for (const o of stmt.orderBy) walkExpr(o.expr, cteScope, refs)
+    return
+  }
+  // select
+  if (!stmt.from) {
+    // FROM-less SELECT (e.g. `SELECT 1`), no source tables
+  } else if (stmt.from.type === 'table') {
+    if (!cteScope.has(stmt.from.table.toLowerCase())) refs.add(stmt.from.table)
+  } else if (stmt.from.type === 'subquery') {
+    walkStatement(stmt.from.query, cteScope, refs)
+  } else {
+    for (const a of stmt.from.args) walkExpr(a, cteScope, refs)
+  }
+  for (const j of stmt.joins) {
+    if (j.fromFunction) {
+      for (const a of j.fromFunction.args) walkExpr(a, cteScope, refs)
+    } else if (!cteScope.has(j.table.toLowerCase())) {
+      refs.add(j.table)
+    }
+    if (j.on) walkExpr(j.on, cteScope, refs)
+  }
+  for (const c of stmt.columns) {
+    if (c.type === 'derived') walkExpr(c.expr, cteScope, refs)
+  }
+  if (stmt.where) walkExpr(stmt.where, cteScope, refs)
+  for (const g of stmt.groupBy) walkExpr(g, cteScope, refs)
+  if (stmt.having) walkExpr(stmt.having, cteScope, refs)
+  for (const o of stmt.orderBy) walkExpr(o.expr, cteScope, refs)
+}
+
+/**
+ * @param {ExprNode} expr
+ * @param {Set<string>} cteScope
+ * @param {Set<string>} refs
+ * @returns {void}
+ */
+function walkExpr(expr, cteScope, refs) {
+  switch (expr.type) {
+  case 'unary':
+    walkExpr(expr.argument, cteScope, refs)
+    return
+  case 'binary':
+    walkExpr(expr.left, cteScope, refs)
+    walkExpr(expr.right, cteScope, refs)
+    return
+  case 'function':
+    for (const a of expr.args) walkExpr(a, cteScope, refs)
+    if (expr.filter) walkExpr(expr.filter, cteScope, refs)
+    return
+  case 'window':
+    for (const a of expr.args) walkExpr(a, cteScope, refs)
+    for (const p of expr.partitionBy) walkExpr(p, cteScope, refs)
+    for (const o of expr.orderBy) walkExpr(o.expr, cteScope, refs)
+    return
+  case 'cast':
+    walkExpr(expr.expr, cteScope, refs)
+    return
+  case 'in':
+    walkExpr(expr.expr, cteScope, refs)
+    walkStatement(expr.subquery, cteScope, refs)
+    return
+  case 'in valuelist':
+    walkExpr(expr.expr, cteScope, refs)
+    for (const v of expr.values) walkExpr(v, cteScope, refs)
+    return
+  case 'exists':
+  case 'not exists':
+    walkStatement(expr.subquery, cteScope, refs)
+    return
+  case 'case':
+    if (expr.caseExpr) walkExpr(expr.caseExpr, cteScope, refs)
+    for (const w of expr.whenClauses) {
+      walkExpr(w.condition, cteScope, refs)
+      walkExpr(w.result, cteScope, refs)
+    }
+    if (expr.elseResult) walkExpr(expr.elseResult, cteScope, refs)
+    return
+  case 'subquery':
+    walkStatement(expr.subquery, cteScope, refs)
+  }
+  // 'literal' / 'identifier' / 'interval' / 'star' are leaves with no children.
+}

package/src/parse/joins.js

@@ -6,7 +6,7 @@ import { isTableFunctionStart, parseFromFunction, parseTableAlias, tableFunction
 import { consume, current, expect, match } from './state.js'
 
 /**
- * @import { ExprNode, JoinClause, JoinType, ParserState } from '../types.js'
+ * @import { ExprNode, FromFunction, JoinClause, JoinType, ParserState } from '../types.js'
  */
 
 /**
@@ -80,7 +80,7 @@ export function parseJoins(state) {
         })
       }
 
-      /** @type {import('../ast.js').FromFunction} */
+      /** @type {FromFunction} */
       const fromFunction = {
         type: 'function',
         funcName,

package/src/parse/parse.js

@@ -12,6 +12,13 @@ import { tokenizeSql } from './tokenize.js'
  * @import { CTEDefinition, ExprNode, FromFunction, FromSubquery, FromTable, OrderByItem, ParseSqlOptions, ParserState, SelectColumn, SelectStatement, SetOperationStatement, SetOperator, Statement } from '../types.js'
  */
 
+// Keywords that may legitimately follow the SELECT column list in place of FROM.
+// Anything else is a hint that the user forgot the FROM keyword.
+const CONTINUATION_KEYWORDS = new Set([
+  'WHERE', 'GROUP', 'HAVING', 'ORDER', 'LIMIT', 'OFFSET',
+  'UNION', 'INTERSECT', 'EXCEPT',
+])
+
 /**
  * @param {ParseSqlOptions} options
  * @returns {Statement}
@@ -176,20 +183,38 @@ function parseSelect(state) {
   let distinct = false
 
   // Support duckdb-style shorthand "FROM table"
+  let hasFrom = true
   if (match(state, 'keyword', 'FROM')) {
     columns = [{ type: 'star', positionStart, positionEnd: positionStart }]
   } else {
     expect(state, 'keyword', 'SELECT')
     distinct = match(state, 'keyword', 'DISTINCT')
     columns = parseSelectList(state)
-    expect(state, 'keyword', 'FROM')
+    hasFrom = !!match(state, 'keyword', 'FROM')
+    // After the column list, if FROM is missing and the next token isn't a
+    // valid continuation (clause keyword, set operator, terminator), the user
+    // likely forgot a FROM keyword. Report that rather than letting parsing
+    // throw a less-specific end-of-query error.
+    if (!hasFrom) {
+      const tok = current(state)
+      const isContinuation = tok.type === 'eof' ||
+        tok.type === 'semicolon' ||
+        tok.type === 'paren' && tok.value === ')' ||
+        tok.type === 'keyword' && CONTINUATION_KEYWORDS.has(tok.value)
+      if (!isContinuation) {
+        throw parseError(state, 'FROM')
+      }
+    }
   }
 
   // Check if it's a subquery, table function, or table name
-  /** @type {FromTable | FromSubquery | FromFunction} */
+  /** @type {FromTable | FromSubquery | FromFunction | undefined} */
   let from
   const fromTok = current(state)
-  if (fromTok.type === 'paren' && fromTok.value === '(') {
+  if (!hasFrom) {
+    // No FROM clause: constant SELECT like "SELECT 1"
+    from = undefined
+  } else if (fromTok.type === 'paren' && fromTok.value === '(') {
     // Subquery: SELECT * FROM (SELECT ...) AS alias
     expect(state, 'paren', '(')
     const query = parseStatement(state)

package/src/parse/tokenize.js

@@ -2,7 +2,7 @@ import { KEYWORDS } from '../validation/keywords.js'
 import { InvalidLiteralError, ParseError, UnexpectedCharError } from '../validation/parseErrors.js'
 
 /**
- * @import { Token } from '../types.d.ts'
+ * @import { Token } from '../types.js'
  */
 
 const NUMBER_REGEX = /^-?(?:\d+n|(?:\d+\.?\d*|\d*\.\d+)(?:[eE][+-]?\d+)?)/

package/src/plan/columns.js

@@ -6,10 +6,11 @@ import { derivedAlias } from '../expression/alias.js'
  */
 
 /**
- * @param {FromTable | FromSubquery | FromFunction} from
- * @returns {string}
+ * @param {FromTable | FromSubquery | FromFunction | undefined} from
+ * @returns {string | undefined}
  */
 export function fromAlias(from) {
+  if (!from) return undefined
   if (from.alias) return from.alias
   if (from.type === 'table') return from.table
   if (from.type === 'function') return from.funcName.toLowerCase()
@@ -31,7 +32,9 @@ export function fromAlias(from) {
 export function statementScope(stmt) {
   if (stmt.type === 'with') return statementScope(stmt.query)
   if (stmt.type === 'compound') return undefined
-  return [fromAlias(stmt.from), ...stmt.joins.map(j => j.alias ?? j.table)]
+  const alias = fromAlias(stmt.from)
+  const joins = stmt.joins.map(j => j.alias ?? j.table)
+  return alias === undefined ? joins : [alias, ...joins]
 }
 
 /**
@@ -64,7 +67,10 @@ export function extractColumns({ select, parentColumns }) {
   const result = new Map()
 
   // Build alias list from FROM + JOINs
-  const aliases = [fromAlias(select.from)]
+  /** @type {string[]} */
+  const aliases = []
+  const sourceAlias = fromAlias(select.from)
+  if (sourceAlias !== undefined) aliases.push(sourceAlias)
   for (const join of select.joins) {
     aliases.push(join.alias ?? join.table)
   }
@@ -142,7 +148,9 @@ export function extractColumns({ select, parentColumns }) {
     collectColumnsFromExpr(expr, identifiers, selectAliases)
   }
   collectColumnsFromExpr(select.having, identifiers, selectAliases)
-  const visibleLateralAliases = [fromAlias(select.from)]
+  /** @type {string[]} */
+  const visibleLateralAliases = []
+  if (sourceAlias !== undefined) visibleLateralAliases.push(sourceAlias)
   for (const join of select.joins) {
     collectColumnsFromExpr(join.on, identifiers)
     const joinAlias = join.alias ?? join.table
@@ -298,7 +306,7 @@ function collectColumnsFromStatement(stmt, columns) {
     if (col.type === 'derived') collectColumnsFromExpr(col.expr, columns)
   }
   collectColumnsFromExpr(stmt.where, columns)
-  if (stmt.from?.type === 'subquery') {
+  if (stmt.from && stmt.from.type === 'subquery') {
     collectColumnsFromStatement(stmt.from.query, columns)
   }
   for (const join of stmt.joins) {
@@ -384,6 +392,7 @@ export function inferStatementColumns({ stmt, cteColumns, tables }) {
  * @returns {string[]}
  */
 export function inferSelectSourceColumns({ select, cteColumns, tables }) {
+  if (!select.from) return []
   if (select.from.type === 'subquery') {
     return inferStatementColumns({ stmt: select.from.query, cteColumns, tables })
   }

package/src/plan/plan.js

@@ -7,8 +7,8 @@ import { validateNoIdentifiers, validateScan, validateTableRefs } from '../valid
 import { collectScopeColumns, extractColumns, fromAlias, inferSelectSourceColumns, inferStatementColumns, statementScope, tableFunctionColumnNames } from './columns.js'
 
 /**
- * @import { AsyncDataSource, ExprNode, DerivedColumn, IdentifierNode, JoinClause, OrderByItem, PlanSqlOptions, ScanOptions, SelectColumn, SelectStatement, SetOperationStatement, Statement, WindowFunctionNode } from '../types.js'
- * @import { QueryPlan, WindowSpec } from './types.d.ts'
+ * @import { AsyncDataSource, DerivedColumn, ExprNode, FromFunction, IdentifierNode, JoinClause, OrderByItem, PlanSqlOptions, ScanOptions, SelectColumn, SelectStatement, SetOperationStatement, Statement, WindowFunctionNode } from '../types.js'
+ * @import { HashJoinNode, QueryPlan, TableFunctionNode, WindowSpec } from './types.js'
  */
 
 /**
@@ -153,12 +153,17 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outer
   const bufferingWindows = windows.some(w => w.partitionBy.length > 0 || w.orderBy.length > 0)
   const needsBuffering = useGrouping || select.orderBy.length > 0 || bufferingWindows
 
-  // Source alias for FROM clause
+  // Source alias for FROM clause (undefined for FROM-less SELECT)
   const sourceAlias = fromAlias(select.from)
 
   // Resolve aliases (and validate qualified references)
   // Include outerScope aliases so correlated references pass validation
-  const scopeTables = Object.fromEntries([sourceAlias, ...select.joins.map(j => j.alias ?? j.table), ...outerScope ?? []].map(a => [a, true]))
+  const scopeAliases = [
+    ...sourceAlias !== undefined ? [sourceAlias] : [],
+    ...select.joins.map(j => j.alias ?? j.table),
+    ...outerScope ?? [],
+  ]
+  const scopeTables = Object.fromEntries(scopeAliases.map(a => [a, true]))
   // Bare column names in scope, so the validator can recognize struct-field
   // dot access on a column (e.g. `item.name` where `item` is an unnested
   // struct column) rather than rejecting `item` as an unknown table.
@@ -201,10 +206,10 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outer
   /** @type {ScanOptions} */
   const hints = {}
   const perTableColumns = extractColumns({ select: originalSelect, parentColumns })
-  hints.columns = perTableColumns.get(sourceAlias)
+  if (sourceAlias !== undefined) hints.columns = perTableColumns.get(sourceAlias)
   // Empty columns array means no columns were referenced, but a FROM subquery
   // still needs its own columns (e.g. for DISTINCT). Treat empty as unrestricted.
-  if (hints.columns?.length === 0 && select.from.type === 'subquery') {
+  if (hints.columns?.length === 0 && select.from?.type === 'subquery') {
     hints.columns = undefined
   }
   if (!select.joins.length) {
@@ -334,6 +339,9 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outer
  * @returns {QueryPlan}
  */
 function planFrom({ select, ctePlans, cteColumns, hints, tables, outerScope }) {
+  if (!select.from) {
+    return { type: 'SingleRow' }
+  }
   if (select.from.type === 'table') {
     const ctePlan = ctePlans?.get(select.from.table.toLowerCase())
     if (ctePlan) {
@@ -378,8 +386,8 @@ function planFrom({ select, ctePlans, cteColumns, hints, tables, outerScope }) {
 /**
  * Builds a TableFunction plan node for a FromFunction AST.
  *
- * @param {import('../types.js').FromFunction} from
- * @returns {import('./types.d.ts').TableFunctionNode}
+ * @param {FromFunction} from
+ * @returns {TableFunctionNode}
  */
 function planTableFunction(from) {
   return {
@@ -457,7 +465,7 @@ function planJoin({ left, joins, leftTable, ctePlans, cteColumns, perTableColumn
     } else {
       const keys = join.on && extractEquiKeys({ condition: join.on, leftTable: currentLeftTable, rightTable })
       if (keys) {
-        /** @type {import('./types.d.ts').HashJoinNode} */
+        /** @type {HashJoinNode} */
         const hashJoin = {
           type: 'HashJoin',
           joinType: join.joinType,

package/src/plan/types.d.ts

@@ -2,6 +2,7 @@ import { DerivedColumn, ExprNode, JoinType, OrderByItem, ScanOptions, SelectColu
 
 export type QueryPlan =
   | ScanNode
+  | SingleRowNode
   | CountNode
   | FilterNode
   | ProjectNode
@@ -25,6 +26,11 @@ export interface ScanNode {
   hints: ScanOptions
 }
 
+// Source for FROM-less SELECT like `SELECT 1`. Yields exactly one empty row.
+export interface SingleRowNode {
+  type: 'SingleRow'
+}
+
 // Count node for COUNT(*) optimization
 export interface CountNode {
   type: 'Count'