squirreling 0.7.5 → 0.7.7

package/README.md

@@ -10,22 +10,13 @@
 ![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 built for the web. It is designed to query over various data sources and provide efficient streaming of results. 100% JavaScript with zero dependencies.
-
-## Features
-
-- Lightweight and fast
-- Easy to integrate with frontend applications
-- Lets you move query execution closer to your users
-- Supports standard SQL queries
-- Async streaming for large datasets
-- Native javascript Promises, AsyncGenerators, AbortSignals
-- Async user-defined functions (UDFs)
-- 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
+Squirreling is a streaming async SQL engine in pure JavaScript. Built for the browser from the ground up: streaming input and output, pluggable data sources, and lazy async cell evaluation. This makes Squirreling ideal for querying data from network sources, APIs, or LLMs where latency and cost matter.
+
+- **Standard SQL**: Full SQL support for querying data (read-only)
+- **Async UDFs**: User-defined functions can call APIs or models
+- **Tiny**: 13 kb bundle, zero dependencies, instant startup
+
+The key idea is **cell-level lazy evaluation**: rows are native AsyncGenerators and cells are async thunks `() => Promise<T>`. This means expensive operations only execute for cells that actually appear in your query results. Unlike WebAssembly databases, Squirreling is fully async with true streaming during network fetches.
 
 ## Usage
 
@@ -75,7 +66,28 @@ console.log(`Collected rows:`, rows)
 // Collected rows: [ { active: true, cnt: 2 }, { active: false, cnt: 1 } ]
 ```
 
-## Supported SQL Features
+### User-Defined Functions
+
+Pass custom functions via the `functions` option. UDFs can be sync or async, making them ideal for calling APIs, models, or other external services:
+
+```javascript
+const rows = await collect(executeSql({
+  tables: { products },
+  query: 'SELECT name,AI_SCORE(description) AS score FROM products',
+  functions: {
+    AI_SCORE: {
+      apply: async (text) => completions(`Rate the following product description from 1 to 10: ${text}`),
+      arguments: { min: 1, max: 1 },
+    },
+  },
+}))
+```
+
+Because Squirreling uses lazy cell evaluation, the `AI_SCORE` function only executes for cells that are actually materialized. Combined with `LIMIT` or `WHERE`, you can efficiently query expensive operations.
+
+## Supported SQL Syntax
+
+Squirreling mostly follows the SQL standard. The following features are supported:
 
 - `SELECT` statements with `WHERE`, `ORDER BY`, `LIMIT`, `OFFSET`
 - `WITH` clause for Common Table Expressions (CTEs)

package/package.json

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

package/src/execute/execute.js

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

package/src/execute/expression.js

@@ -23,9 +23,10 @@ import { applyBinaryOp, stringify } from './utils.js'
  * @param {Record<string, UserDefinedFunction>} [params.functions] - User-defined functions
  * @param {number} [params.rowIndex] - 1-based row index for error reporting
  * @param {AsyncRow[]} [params.rows] - Group of rows for aggregate functions
+ * @param {Map<string, ExprNode>} [params.aliases] - SELECT column aliases for ORDER BY resolution
  * @returns {Promise<SqlPrimitive>} The result of the evaluation
  */
-export async function evaluateExpr({ node, row, tables, functions, rowIndex, rows }) {
+export async function evaluateExpr({ node, row, tables, functions, rowIndex, rows, aliases }) {
   if (node.type === 'literal') {
     return node.value
   }
@@ -42,6 +43,11 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
         return row.cells[colName]()
       }
     }
+    // Check if it's a SELECT alias (for ORDER BY)
+    if (aliases?.has(node.name)) {
+      return evaluateExpr({ node: aliases.get(node.name), row, tables, functions, rowIndex, rows, aliases })
+    }
+    // Unknown identifier
     throw columnNotFoundError({
       columnName: node.name,
       availableColumns: Object.keys(row.cells),
@@ -63,16 +69,16 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
   // Unary operators
   if (node.type === 'unary') {
     if (node.op === 'NOT') {
-      return !await evaluateExpr({ node: node.argument, row, tables, functions, rowIndex, rows })
+      return !await evaluateExpr({ node: node.argument, row, tables, functions, rowIndex, rows, aliases })
     }
     if (node.op === 'IS NULL') {
-      return await evaluateExpr({ node: node.argument, row, tables, functions, rowIndex, rows }) == null
+      return await evaluateExpr({ node: node.argument, row, tables, functions, rowIndex, rows, aliases }) == null
     }
     if (node.op === 'IS NOT NULL') {
-      return await evaluateExpr({ node: node.argument, row, tables, functions, rowIndex, rows }) != null
+      return await evaluateExpr({ node: node.argument, row, tables, functions, rowIndex, rows, aliases }) != null
     }
     if (node.op === '-') {
-      const val = await evaluateExpr({ node: node.argument, row, tables, functions, rowIndex, rows })
+      const val = await evaluateExpr({ node: node.argument, row, tables, functions, rowIndex, rows, aliases })
       if (val == null) return null
       return -val
     }
@@ -82,15 +88,15 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
   if (node.type === 'binary') {
     // Handle date +/- interval at AST level
     if ((node.op === '+' || node.op === '-') && node.right.type === 'interval') {
-      const dateVal = await evaluateExpr({ node: node.left, row, tables, functions, rowIndex, rows })
+      const dateVal = await evaluateExpr({ node: node.left, row, tables, functions, rowIndex, rows, aliases })
       return applyIntervalToDate(dateVal, node.right.value, node.right.unit, node.op)
     }
     if (node.op === '+' && node.left.type === 'interval') {
-      const dateVal = await evaluateExpr({ node: node.right, row, tables, functions, rowIndex, rows })
+      const dateVal = await evaluateExpr({ node: node.right, row, tables, functions, rowIndex, rows, aliases })
       return applyIntervalToDate(dateVal, node.left.value, node.left.unit, '+')
     }
 
-    const left = await evaluateExpr({ node: node.left, row, tables, functions, rowIndex, rows })
+    const left = await evaluateExpr({ node: node.left, row, tables, functions, rowIndex, rows, aliases })
 
     // Short-circuit evaluation for AND and OR
     if (node.op === 'AND') {
@@ -100,7 +106,7 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
       if (left) return true
     }
 
-    const right = await evaluateExpr({ node: node.right, row, tables, functions, rowIndex, rows })
+    const right = await evaluateExpr({ node: node.right, row, tables, functions, rowIndex, rows, aliases })
     return applyBinaryOp(node.op, left, right)
   }
 
@@ -172,7 +178,7 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
           count++
         }
 
-        if (funcName === 'SUM') return sum
+        if (funcName === 'SUM') return count === 0 ? null : sum
         if (funcName === 'AVG') return count === 0 ? null : sum / count
         if (funcName === 'MIN') return min
         if (funcName === 'MAX') return max
@@ -202,7 +208,7 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
     }
 
     /** @type {SqlPrimitive[]} */
-    const args = await Promise.all(node.args.map(arg => evaluateExpr({ node: arg, row, tables, functions, rowIndex, rows })))
+    const args = await Promise.all(node.args.map(arg => evaluateExpr({ node: arg, row, tables, functions, rowIndex, rows, aliases })))
 
     if (isStringFunc(funcName)) {
       return evaluateStringFunc({
@@ -397,7 +403,7 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
     const exprVal = await evaluateExpr({ node: node.expr, row, tables, functions, rowIndex, rows })
     for (const valueNode of node.values) {
       const val = await evaluateExpr({ node: valueNode, row, tables, functions, rowIndex, rows })
-      if (exprVal === val) return true
+      if (exprVal == val) return true
     }
     return false
   }
@@ -407,7 +413,7 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
     const results = executeSelect({ select: node.subquery, tables })
     for await (const resRow of results) {
       const value = await resRow.cells[resRow.columns[0]]()
-      if (exprVal === value) return true
+      if (exprVal == value) return true
     }
     return false
   }
@@ -433,7 +439,7 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
       if (caseValue !== undefined) {
         // Simple CASE: compare caseValue with condition
         const whenValue = await evaluateExpr({ node: whenClause.condition, row, tables, functions, rowIndex, rows })
-        conditionResult = caseValue === whenValue
+        conditionResult = caseValue == whenValue
       } else {
         // Searched CASE: evaluate condition as boolean
         conditionResult = await evaluateExpr({ node: whenClause.condition, row, tables, functions, rowIndex, rows })

package/src/execute/having.js

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

package/src/execute/utils.js

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

package/src/validation.js

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