squirreling 0.1.1 → 0.2.0

package/README.md

@@ -1,11 +1,14 @@
 # Squirreling SQL Engine
 
+![squirreling engine](squirreling.jpg)
+
 [![npm](https://img.shields.io/npm/v/squirreling)](https://www.npmjs.com/package/squirreling)
 [![downloads](https://img.shields.io/npm/dt/squirreling)](https://www.npmjs.com/package/squirreling)
 [![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)
 [![dependencies](https://img.shields.io/badge/Dependencies-0-blueviolet)](https://www.npmjs.com/package/squirreling?activeTab=dependencies)
+
 Squirreling is a lightweight SQL engine for JavaScript applications, designed to provide efficient and easy-to-use database functionalities in the browser.
 
 ## Features
@@ -21,12 +24,12 @@ Squirreling is a lightweight SQL engine for JavaScript applications, designed to
 ```javascript
 import { executeSql } from 'squirreling'
 
-const data = [
+const source = [
   { id: 1, name: 'Alice' },
   { id: 2, name: 'Bob' },
 ]
 
-const result = executeSql(data, 'SELECT UPPER(name) AS name_upper FROM users')
+const result = executeSql({ source, sql: 'SELECT UPPER(name) AS name_upper FROM users' })
 console.log(result)
 // Output: [ { name_upper: 'ALICE' }, { name_upper: 'BOB' } ]
 ```

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "squirreling",
-  "version": "0.1.1",
+  "version": "0.2.0",
+  "description": "",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
+  "keywords": [
+    "sql",
+    "data",
+    "dataset",
+    "hyperparam",
+    "hyparquet",
+    "parquet"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/backend/memory.js

@@ -0,0 +1,37 @@
+/**
+ * @import { DataSource, RowSource } from '../types.js'
+ */
+
+/**
+ * Creates a row accessor that wraps a plain JavaScript object
+ *
+ * @param {Record<string, any>} obj - the plain object
+ * @returns {RowSource} a row accessor interface
+ */
+export function createRowAccessor(obj) {
+  return {
+    getCell(name) {
+      return obj[name]
+    },
+    getKeys() {
+      return Object.keys(obj)
+    },
+  }
+}
+
+/**
+ * Creates a memory-backed data source from an array of plain objects
+ *
+ * @param {Record<string, any>[]} data - array of plain objects
+ * @returns {DataSource} a data source interface
+ */
+export function createMemorySource(data) {
+  return {
+    getNumRows() {
+      return data.length
+    },
+    getRow(index) {
+      return createRowAccessor(data[index])
+    },
+  }
+}

package/src/execute/aggregates.js

@@ -3,9 +3,9 @@ import { evaluateExpr } from './expression.js'
 /**
  * Evaluates an aggregate function over a set of rows
  *
- * @import { AggregateColumn, ExprNode, Row } from '../types.js'
+ * @import { AggregateColumn, ExprNode, RowSource } from '../types.js'
  * @param {AggregateColumn} col - aggregate column definition
- * @param {Row[]} rows - rows to aggregate
+ * @param {RowSource[]} rows - rows to aggregate
  * @returns {number | null} aggregated result
  */
 export function evaluateAggregate(col, rows) {
@@ -77,8 +77,7 @@ export function defaultAggregateAlias(col) {
  * @param {ExprNode} expr
  * @returns {string}
  */
-export
-function defaultAggregateAliasExpr(expr) {
+export function defaultAggregateAliasExpr(expr) {
   if (expr.type === 'identifier') {
     return expr.name
   }

package/src/execute/execute.js

@@ -1,26 +1,30 @@
 /**
- * @import { FunctionColumn, FunctionNode, OrderByItem, Row, SelectStatement, SqlPrimitive } from '../types.js'
+ * @import { DataSource, ExecuteSqlOptions, FunctionColumn, FunctionNode, OrderByItem, RowSource, SelectStatement, SqlPrimitive } from '../types.js'
  */
 
 import { defaultAggregateAlias, evaluateAggregate } from './aggregates.js'
 import { evaluateExpr } from './expression.js'
+import { createHavingContext, evaluateHavingExpr } from './having.js'
 import { parseSql } from '../parse/parse.js'
+import { createMemorySource, createRowAccessor } from '../backend/memory.js'
 
 /**
- * Executes a SQL SELECT query against an array of data rows
- * @param {Row[]} rows - The data rows to query
- * @param {string} sql - The SQL query string
- * @returns {Row[]} The result rows matching the query
+ * Executes a SQL SELECT query against a data source
+ *
+ * @param {ExecuteSqlOptions} options - the execution options
+ * @returns {Record<string, any>[]} the result rows matching the query
  */
-export function executeSql(rows, sql) {
+export function executeSql({ source, sql }) {
   const select = parseSql(sql)
-  return evaluateSelectAst(select, rows)
+  const dataSource = Array.isArray(source) ? createMemorySource(source) : source
+  return evaluateSelectAst(select, dataSource)
 }
 
 /**
  * Generates a default alias name for a string function
- * @param {FunctionColumn} col - The function column definition
- * @returns {string} The generated alias (e.g., "upper_name", "concat_a_b")
+ *
+ * @param {FunctionColumn} col - the function column definition
+ * @returns {string} the generated alias (e.g., "upper_name", "concat_a_b")
  */
 function defaultFunctionAlias(col) {
   const base = col.func.toLowerCase()
@@ -36,8 +40,9 @@ function defaultFunctionAlias(col) {
 
 /**
  * Creates a stable string key for a row to enable deduplication
- * @param {Row} row - The data row
- * @returns {string} A stable string representation of the row
+ *
+ * @param {Record<string, any>} row
+ * @returns {string} a stable string representation of the row
  */
 function stableRowKey(row) {
   const keys = Object.keys(row).sort()
@@ -52,9 +57,10 @@ function stableRowKey(row) {
 
 /**
  * Compares two SQL values for sorting
- * @param {SqlPrimitive} a - First value to compare
- * @param {SqlPrimitive} b - Second value to compare
- * @returns {number} Negative if a < b, positive if a > b, 0 if equal
+ *
+ * @param {SqlPrimitive} a
+ * @param {SqlPrimitive} b
+ * @returns {number} negative if a < b, positive if a > b, 0 if equal
  */
 function compareValues(a, b) {
   if (a === b) return 0
@@ -76,15 +82,16 @@ function compareValues(a, b) {
 
 /**
  * Applies DISTINCT filtering to remove duplicate rows
- * @param {Row[]} rows - The input rows
+ *
+ * @param {Record<string, any>[]} rows - The input rows
  * @param {boolean} distinct - Whether to apply deduplication
- * @returns {Row[]} The deduplicated rows
+ * @returns {Record<string, any>[]} The deduplicated rows
  */
 function applyDistinct(rows, distinct) {
   if (!distinct) return rows
   /** @type {Set<string>} */
   const seen = new Set()
-  /** @type {Row[]} */
+  /** @type {Record<string, any>[]} */
   const result = []
   for (const row of rows) {
     const key = stableRowKey(row)
@@ -97,20 +104,20 @@ function applyDistinct(rows, distinct) {
 
 /**
  * Applies ORDER BY sorting to rows
- * @param {Row[]} rows - The input rows
- * @param {OrderByItem[]} orderBy - The sort specifications
- * @returns {Row[]} The sorted rows
+ *
+ * @param {Record<string, any>[]} rows - the input rows
+ * @param {OrderByItem[]} orderBy - the sort specifications
+ * @returns {Record<string, any>[]} the sorted rows
  */
 function applyOrderBy(rows, orderBy) {
-  if (!orderBy || orderBy.length === 0) return rows
+  if (!orderBy?.length) return rows
 
   const sorted = rows.slice()
-
   sorted.sort((a, b) => {
     for (const term of orderBy) {
       const dir = term.direction
-      const av = evaluateExpr(term.expr, a)
-      const bv = evaluateExpr(term.expr, b)
+      const av = evaluateExpr(term.expr, createRowAccessor(a))
+      const bv = evaluateExpr(term.expr, createRowAccessor(b))
       const cmp = compareValues(av, bv)
       if (cmp !== 0) {
         return dir === 'DESC' ? -cmp : cmp
@@ -124,41 +131,41 @@ function applyOrderBy(rows, orderBy) {
 
 /**
  * Evaluates a parsed SELECT AST against data rows
- * @param {SelectStatement} select - The parsed SQL AST
- * @param {Row[]} rows - The data rows
- * @returns {Row[]} The filtered, projected, and sorted result rows
+ *
+ * @param {SelectStatement} select - the parsed SQL AST
+ * @param {DataSource} dataSource - the data source
+ * @returns {Record<string, any>[]} the filtered, projected, and sorted result rows
  */
-function evaluateSelectAst(select, rows) {
+function evaluateSelectAst(select, dataSource) {
   // Check for unsupported JOIN operations
   if (select.joins.length) {
     throw new Error('JOIN is not supported')
   }
 
-  // WHERE
-  let working = rows
-  if (select.where) {
-    /** @type {Row[]} */
-    const filtered = []
-    for (const row of rows) {
-      if (evaluateExpr(select.where, row)) {
-        filtered.push(row)
-      }
+  // WHERE clause filtering
+  /** @type {RowSource[]} */
+  const working = []
+  const length = dataSource.getNumRows()
+  for (let i = 0; i < length; i++) {
+    const row = dataSource.getRow(i)
+    if (!select.where || evaluateExpr(select.where, row)) {
+      working.push(row)
     }
-    working = filtered
   }
 
   const hasAggregate = select.columns.some(col => col.kind === 'aggregate')
   const useGrouping = hasAggregate || select.groupBy?.length > 0
 
-  /** @type {Row[]} */
+  /** @type {Record<string, any>[]} */
   const projected = []
 
   if (useGrouping) {
-    /** @type {Row[][]} */
+    // Grouping due to GROUP BY or aggregate functions
+    /** @type {RowSource[][]} */
     const groups = []
 
     if (select.groupBy?.length) {
-      /** @type {Map<string, Row[]>} */
+      /** @type {Map<string, RowSource[]>} */
       const map = new Map()
       for (const row of working) {
         /** @type {string[]} */
@@ -186,14 +193,16 @@ function evaluateSelectAst(select, rows) {
     }
 
     for (const group of groups) {
-      /** @type {Row} */
+      /** @type {Record<string, any>} */
       const resultRow = {}
       for (const col of select.columns) {
         if (col.kind === 'star') {
-          const firstRow = group[0] || {}
-          const keys = Object.keys(firstRow)
-          for (const key of keys) {
-            resultRow[key] = firstRow[key]
+          const firstRow = group[0]
+          if (firstRow) {
+            const keys = firstRow.getKeys()
+            for (const key of keys) {
+              resultRow[key] = firstRow.getCell(key)
+            }
           }
           continue
         }
@@ -202,7 +211,7 @@ function evaluateSelectAst(select, rows) {
           const name = col.column
           const alias = col.alias ?? name
           // Evaluate on first row of group (all rows have same value for GROUP BY columns)
-          resultRow[alias] = group.length > 0 ? group[0][name] : undefined
+          resultRow[alias] = group[0]?.getCell(name)
           continue
         }
 
@@ -230,22 +239,34 @@ function evaluateSelectAst(select, rows) {
           continue
         }
       }
+
+      // Apply HAVING filter before adding to projected results
+      if (select.having) {
+        // For HAVING, we need to evaluate aggregates in the context of the group
+        // Create a special row context that includes both the group data and aggregate values
+        const havingContext = createHavingContext(resultRow, group)
+        if (!evaluateHavingExpr(select.having, havingContext, group)) {
+          continue
+        }
+      }
+
       projected.push(resultRow)
     }
   } else {
+    // No grouping, simple projection
     for (const row of working) {
-      /** @type {Row} */
+      /** @type {Record<string, any>} */
       const outRow = {}
       for (const col of select.columns) {
         if (col.kind === 'star') {
-          const keys = Object.keys(row)
+          const keys = row.getKeys()
           for (const key of keys) {
-            outRow[key] = row[key]
+            outRow[key] = row.getCell(key)
           }
         } else if (col.kind === 'column') {
           const name = col.column
           const alias = col.alias ?? name
-          outRow[alias] = row[name]
+          outRow[alias] = row.getCell(name)
         } else if (col.kind === 'function') {
           /** @type {FunctionNode} */
           const funcNode = { type: 'function', name: col.func, args: col.args }

package/src/execute/expression.js

@@ -2,9 +2,9 @@
 /**
  * Evaluates an expression node against a row of data
  *
- * @import { ExprNode, Row, SqlPrimitive } from '../types.js'
+ * @import { ExprNode, RowSource, SqlPrimitive } from '../types.js'
  * @param {ExprNode} node - The expression node to evaluate
- * @param {Row} row - The data row to evaluate against
+ * @param {RowSource} row - The data row to evaluate against
  * @returns {SqlPrimitive} The result of the evaluation
  */
 export function evaluateExpr(node, row) {
@@ -13,9 +13,10 @@ export function evaluateExpr(node, row) {
   }
 
   if (node.type === 'identifier') {
-    return row[node.name]
+    return row.getCell(node.name)
   }
 
+  // Unary operators
   if (node.type === 'unary') {
     if (node.op === 'NOT') {
       return !evaluateExpr(node.argument, row)
@@ -33,6 +34,7 @@ export function evaluateExpr(node, row) {
     }
   }
 
+  // Binary operators
   if (node.type === 'binary') {
     if (node.op === 'AND') {
       const leftVal = evaluateExpr(node.left, row)
@@ -79,6 +81,21 @@ export function evaluateExpr(node, row) {
     }
   }
 
+  // BETWEEN and NOT BETWEEN
+  if (node.type === 'between' || node.type === 'not between') {
+    const expr = evaluateExpr(node.expr, row)
+    const lower = evaluateExpr(node.lower, row)
+    const upper = evaluateExpr(node.upper, row)
+
+    // If any value is NULL, return false (SQL behavior)
+    if (expr == null || lower == null || upper == null) {
+      return false
+    }
+
+    const isBetween = expr >= lower && expr <= upper
+    return node.type === 'between' ? isBetween : !isBetween
+  }
+
   // Function calls
   if (node.type === 'function') {
     const funcName = node.name.toUpperCase()

package/src/execute/having.js

@@ -0,0 +1,216 @@
+/**
+ * @import { AggregateFunc, ExprNode, RowSource, SqlPrimitive } from '../types.js'
+ */
+
+import { isAggregateFunc } from '../validation.js'
+import { evaluateExpr } from './expression.js'
+
+/**
+ * Creates a context for evaluating HAVING expressions
+ *
+ * @param {Record<string, any>} resultRow - the aggregated result row
+ * @param {RowSource[]} group - the group of rows
+ * @returns {RowSource} a context row for HAVING evaluation
+ */
+export function createHavingContext(resultRow, group) {
+  // Include the first row of the group (for GROUP BY columns)
+  const firstRow = group[0]
+  /** @type {Record<string, any>} */
+  const context = {}
+  if (firstRow) {
+    const keys = firstRow.getKeys()
+    for (const key of keys) {
+      context[key] = firstRow.getCell(key)
+    }
+  }
+  // Merge with result row (which has aggregates computed)
+  Object.assign(context, resultRow)
+
+  // Return a Row accessor wrapping the context
+  return {
+    getCell(name) {
+      return context[name]
+    },
+    getKeys() {
+      return Object.keys(context)
+    },
+  }
+}
+
+/**
+ * Evaluates a HAVING expression with support for aggregate functions
+ *
+ * @param {ExprNode} expr - the HAVING expression
+ * @param {RowSource} context - the context row with aggregated values
+ * @param {RowSource[]} group - the group of rows for re-evaluating aggregates
+ * @returns {boolean} whether the HAVING condition is satisfied
+ */
+export function evaluateHavingExpr(expr, context, group) {
+  // For HAVING, we need special handling of aggregate functions
+  // They need to be re-evaluated against the group
+  if (expr.type === 'function') {
+    const funcName = expr.name.toUpperCase()
+    if (isAggregateFunc(funcName)) {
+      // Evaluate aggregate function on the group
+      return Boolean(evaluateAggregateFunction(funcName, expr.args, group))
+    }
+  }
+
+  if (expr.type === 'binary') {
+    const left = evaluateHavingValue(expr.left, context, group)
+    const right = evaluateHavingValue(expr.right, context, group)
+
+    if (expr.op === 'AND') {
+      return Boolean(left && right)
+    }
+    if (expr.op === 'OR') {
+      return Boolean(left || right)
+    }
+
+    // Handle NULL comparisons
+    if (left == null || right == null) {
+      if (expr.op === '=' || expr.op === '!=' || expr.op === '<>') {
+        return false
+      }
+    }
+
+    if (expr.op === '=') return left === right
+    if (expr.op === '!=' || expr.op === '<>') return left !== right
+    if (expr.op === '<') return left < right
+    if (expr.op === '>') return left > right
+    if (expr.op === '<=') return left <= right
+    if (expr.op === '>=') return left >= right
+    if (expr.op === 'LIKE') {
+      const str = String(left)
+      const pattern = String(right)
+      const regexPattern = pattern
+        .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        .replace(/%/g, '.*')
+        .replace(/_/g, '.')
+      const regex = new RegExp('^' + regexPattern + '$', 'i')
+      return regex.test(str)
+    }
+  }
+
+  if (expr.type === 'unary') {
+    if (expr.op === 'NOT') {
+      return !evaluateHavingExpr(expr.argument, context, group)
+    }
+    if (expr.op === 'IS NULL') {
+      return evaluateHavingValue(expr.argument, context, group) == null
+    }
+    if (expr.op === 'IS NOT NULL') {
+      return evaluateHavingValue(expr.argument, context, group) != null
+    }
+  }
+
+  if (expr.type === 'between' || expr.type === 'not between') {
+    const exprVal = evaluateHavingValue(expr.expr, context, group)
+    const lower = evaluateHavingValue(expr.lower, context, group)
+    const upper = evaluateHavingValue(expr.upper, context, group)
+
+    // If any value is NULL, return false (SQL behavior)
+    if (exprVal == null || lower == null || upper == null) {
+      return false
+    }
+
+    const isBetween = exprVal >= lower && exprVal <= upper
+    return expr.type === 'between' ? isBetween : !isBetween
+  }
+
+  // For other expression types, use the context row
+  return Boolean(evaluateExpr(expr, context))
+}
+
+/**
+ * Evaluates a value in a HAVING expression
+ *
+ * @param {ExprNode} expr
+ * @param {RowSource} context - the context row
+ * @param {RowSource[]} group - the group of rows
+ * @returns {SqlPrimitive} the evaluated value
+ */
+function evaluateHavingValue(expr, context, group) {
+  if (expr.type === 'function') {
+    const funcName = expr.name.toUpperCase()
+    if (isAggregateFunc(funcName)) {
+      return evaluateAggregateFunction(funcName, expr.args, group)
+    }
+  }
+
+  // For binary expressions, we need to use evaluateHavingExpr to properly handle aggregates
+  if (expr.type === 'binary' || expr.type === 'unary' || expr.type === 'between' || expr.type === 'not between') {
+    return evaluateHavingExpr(expr, context, group)
+  }
+
+  return evaluateExpr(expr, context)
+}
+
+/**
+ * Evaluates an aggregate function on a group
+ *
+ * @param {AggregateFunc} funcName - aggregate function name
+ * @param {ExprNode[]} args - function arguments
+ * @param {RowSource[]} group - the group of rows
+ * @returns {SqlPrimitive} the aggregate result
+ */
+function evaluateAggregateFunction(funcName, args, group) {
+  if (funcName === 'COUNT') {
+    if (args.length === 1 && args[0].type === 'identifier' && args[0].name === '*') {
+      return group.length
+    }
+    // COUNT(column) - count non-null values
+    let count = 0
+    for (const row of group) {
+      const val = evaluateExpr(args[0], row)
+      if (val != null) count++
+    }
+    return count
+  }
+
+  if (funcName === 'SUM') {
+    let sum = 0
+    for (const row of group) {
+      const val = evaluateExpr(args[0], row)
+      if (val != null) sum += Number(val)
+    }
+    return sum
+  }
+
+  if (funcName === 'AVG') {
+    let sum = 0
+    let count = 0
+    for (const row of group) {
+      const val = evaluateExpr(args[0], row)
+      if (val != null) {
+        sum += Number(val)
+        count++
+      }
+    }
+    return count > 0 ? sum / count : null
+  }
+
+  if (funcName === 'MIN') {
+    let min = null
+    for (const row of group) {
+      const val = evaluateExpr(args[0], row)
+      if (val != null && (min == null || val < min)) {
+        min = val
+      }
+    }
+    return min
+  }
+
+  if (funcName === 'MAX') {
+    let max = null
+    for (const row of group) {
+      const val = evaluateExpr(args[0], row)
+      if (val != null && (max == null || val > max)) {
+        max = val
+      }
+    }
+    return max
+  }
+
+  throw new Error('Unsupported aggregate function: ' + funcName)
+}

package/src/index.d.ts

@@ -1,4 +1,4 @@
-import type { Row, SelectStatement } from './types.js'
+import type { RowSource, SelectStatement } from './types.js'
 
 /**
  * Executes a SQL SELECT query against an array of data rows
@@ -7,7 +7,7 @@ import type { Row, SelectStatement } from './types.js'
  * @param sql - SQL query string
  * @returns rows matching the query
  */
-export function executeSql(rows: Row[], sql: string): Row[]
+export function executeSql(rows: RowSource[], sql: string): RowSource[]
 
 /**
  * Parses a SQL query string into an abstract syntax tree

package/src/parse/expression.js

@@ -42,8 +42,17 @@ export function parsePrimary(c) {
 
       if (c.current().type !== 'paren' || c.current().value !== ')') {
         while (true) {
-          const arg = parseExpression(c)
-          args.push(arg)
+          // Handle COUNT(*) - treat * as a special identifier
+          if (c.current().type === 'operator' && c.current().value === '*') {
+            c.consume()
+            args.push({
+              type: 'identifier',
+              name: '*',
+            })
+          } else {
+            const arg = parseExpression(c)
+            args.push(arg)
+          }
           if (!c.match('comma')) break
         }
       }
@@ -217,6 +226,37 @@ function parseComparison(c) {
     }
   }
 
+  // [NOT] BETWEEN
+  if (tok.type === 'keyword' && tok.value === 'NOT') {
+    const nextTok = c.peek(1)
+    if (nextTok.type === 'keyword' && nextTok.value === 'BETWEEN') {
+      c.consume() // NOT
+      c.consume() // BETWEEN
+      const lower = parsePrimary(c)
+      c.expect('keyword', 'AND')
+      const upper = parsePrimary(c)
+      return {
+        type: 'not between',
+        expr: left,
+        lower,
+        upper,
+      }
+    }
+  }
+
+  if (tok.type === 'keyword' && tok.value === 'BETWEEN') {
+    c.consume()
+    const lower = parsePrimary(c)
+    c.expect('keyword', 'AND')
+    const upper = parsePrimary(c)
+    return {
+      type: 'between',
+      expr: left,
+      lower,
+      upper,
+    }
+  }
+
   if (tok.type === 'operator' && isComparisonOperator(tok.value)) {
     c.consume()
     const right = parsePrimary(c)

package/src/parse/parse.js

@@ -4,6 +4,7 @@
 
 import { tokenize } from './tokenize.js'
 import { parseExpression, parsePrimary } from './expression.js'
+import { isAggregateFunc, isStringFunc } from '../validation.js'
 
 // Keywords that cannot be used as implicit aliases after a column
 const RESERVED_AFTER_COLUMN = new Set([
@@ -407,6 +408,8 @@ function parseSelectInternal(state) {
   let where
   /** @type {ExprNode[]} */
   const groupBy = []
+  /** @type {ExprNode | undefined} */
+  let having
   /** @type {OrderByItem[]} */
   const orderBy = []
   /** @type {number | undefined} */
@@ -429,6 +432,10 @@ function parseSelectInternal(state) {
     }
   }
 
+  if (match(state, 'keyword', 'HAVING')) {
+    having = parseExpression(cursor)
+  }
+
   if (match(state, 'keyword', 'ORDER')) {
     expect(state, 'keyword', 'BY')
     while (true) {
@@ -497,6 +504,7 @@ function parseSelectInternal(state) {
     joins,
     where,
     groupBy,
+    having,
     orderBy,
     limit,
     offset,
@@ -515,19 +523,3 @@ function parseError(state, expected) {
   const after = prevToken ? ` after "${prevToken.originalValue ?? prevToken.value}"` : ''
   return new Error(`Expected ${expected}${after} at position ${tok.position}`)
 }
-
-/**
- * @param {string} name
- * @returns {name is AggregateFunc}
- */
-function isAggregateFunc(name) {
-  return ['COUNT', 'SUM', 'AVG', 'MIN', 'MAX'].includes(name)
-}
-
-/**
- * @param {string} name
- * @returns {name is StringFunc}
- */
-function isStringFunc(name) {
-  return ['UPPER', 'LOWER', 'CONCAT', 'LENGTH', 'SUBSTRING', 'TRIM'].includes(name)
-}

package/src/types.d.ts

@@ -1,4 +1,17 @@
-export type Row = Record<string, any>
+export interface RowSource {
+  getCell(name: string): any
+  getKeys(): string[]
+}
+
+export interface DataSource {
+  getNumRows(): number
+  getRow(index: number): RowSource
+}
+
+export interface ExecuteSqlOptions {
+  source: Record<string, any>[] | DataSource
+  sql: string
+}
 
 export type SqlPrimitive = string | number | bigint | boolean | null
 
@@ -9,6 +22,7 @@ export interface SelectStatement {
   joins: JoinClause[]
   where?: ExprNode
   groupBy: ExprNode[]
+  having?: ExprNode
   orderBy: OrderByItem[]
   limit?: number
   offset?: number
@@ -81,7 +95,21 @@ export interface CastNode {
   toType: string
 }
 
-export type ExprNode = LiteralNode | IdentifierNode | UnaryNode | BinaryNode | FunctionNode | CastNode
+export interface BetweenNode {
+  type: 'between' | 'not between'
+  expr: ExprNode
+  lower: ExprNode
+  upper: ExprNode
+}
+
+export type ExprNode =
+  | LiteralNode
+  | IdentifierNode
+  | UnaryNode
+  | BinaryNode
+  | FunctionNode
+  | CastNode
+  | BetweenNode
 
 export interface StarColumn {
   kind: 'star'

package/src/validation.js

@@ -0,0 +1,17 @@
+
+/**
+ * @import {AggregateFunc, StringFunc} from './types.js'
+ * @param {string} name
+ * @returns {name is AggregateFunc}
+ */
+export function isAggregateFunc(name) {
+  return ['COUNT', 'SUM', 'AVG', 'MIN', 'MAX'].includes(name)
+}
+
+/**
+ * @param {string} name
+ * @returns {name is StringFunc}
+ */
+export function isStringFunc(name) {
+  return ['UPPER', 'LOWER', 'CONCAT', 'LENGTH', 'SUBSTRING', 'TRIM'].includes(name)
+}