squirreling 0.9.1 → 0.9.3

package/README.md

@@ -47,8 +47,8 @@ const asyncRows: AsyncIterable<AsyncRow> = executeSql({
 })
 
 // Process rows as they arrive (streaming)
-for await (const { id, name } of asyncRows) {
-  console.log(`User id=${await id()}, name=${await name()}`)
+for await (const { cells } of asyncRows) {
+  console.log(`User id=${await cells.id()}, name=${await cells.name()}`)
 }
 ```
 
@@ -95,7 +95,7 @@ interface AsyncDataSource {
 }
 
 interface ScanOptions {
-  columns?: string[]
+  columns?: string[] // columns to scan (undefined means all)
   where?: ExprNode
   limit?: number
   offset?: number
@@ -128,11 +128,12 @@ const customSource: AsyncDataSource = {
 
 Squirreling mostly follows the SQL standard. The following features are supported:
 
-- `SELECT` statements with `WHERE`, `ORDER BY`, `LIMIT`, `OFFSET`
+- `SELECT` statements with `DISTINCT`, `WHERE`, `ORDER BY`, `LIMIT`, `OFFSET`
 - `WITH` clause for Common Table Expressions (CTEs)
 - Subqueries in `SELECT`, `FROM`, and `WHERE` clauses
-- `JOIN` operations: `INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN`, `FULL JOIN`, `POSITIONAL JOIN`
+- `JOIN` operations: `INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN`, `FULL JOIN`, `CROSS JOIN`, `POSITIONAL JOIN`
 - `GROUP BY` and `HAVING` clauses
+- Expressions: `CASE`, `CAST`, `BETWEEN`, `IN`, `LIKE`, `IS NULL`, `IS NOT NULL`
 
 ### Quoting
 
@@ -142,12 +143,14 @@ Squirreling mostly follows the SQL standard. The following features are supporte
 
 ### Functions
 
-- Aggregate: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `JSON_ARRAYAGG`
+- Aggregate: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `STDDEV_POP`, `STDDEV_SAMP`, `JSON_ARRAYAGG`
 - String: `CONCAT`, `SUBSTRING`, `REPLACE`, `LENGTH`, `UPPER`, `LOWER`, `TRIM`, `LEFT`, `RIGHT`, `INSTR`
 - Math: `ABS`, `SIGN`, `CEIL`, `FLOOR`, `ROUND`, `MOD`, `RAND`, `RANDOM`, `LN`, `LOG10`, `EXP`, `POWER`, `SQRT`
 - Trig: `SIN`, `COS`, `TAN`, `COT`, `ASIN`, `ACOS`, `ATAN`, `ATAN2`, `DEGREES`, `RADIANS`, `PI`
 - Date: `CURRENT_DATE`, `CURRENT_TIME`, `CURRENT_TIMESTAMP`, `INTERVAL`
 - Json: `JSON_VALUE`, `JSON_QUERY`, `JSON_OBJECT`
+- Array: `ARRAY_LENGTH`, `ARRAY_POSITION`, `ARRAY_SORT`, `CARDINALITY`
 - Regex: `REGEXP_SUBSTR`, `REGEXP_REPLACE`
+- Spatial: `ST_GeomFromText`, `ST_MakeEnvelope`, `ST_AsText`, `ST_Intersects`, `ST_Contains`, `ST_ContainsProperly`, `ST_Within`, `ST_Overlaps`, `ST_Touches`, `ST_Equals`, `ST_Crosses`, `ST_Covers`, `ST_CoveredBy`, `ST_DWithin`
 - Conditional: `COALESCE`, `NULLIF`
 - User-defined functions (UDFs)

package/package.json

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

package/src/backend/dataSource.js

@@ -1,5 +1,5 @@
 /**
- * @import { AsyncCells, AsyncDataSource, AsyncRow, ScanOptions, ScanResults, SqlPrimitive } from '../types.js'
+ * @import { AsyncCells, AsyncDataSource, AsyncRow, SqlPrimitive } from '../types.js'
  */
 
 /**
@@ -8,7 +8,7 @@
  * @param {Record<string, SqlPrimitive>} obj - the plain object
  * @returns {AsyncRow} a row accessor interface
  */
-function asyncRow(obj) {
+export function asyncRow(obj) {
   /** @type {AsyncCells} */
   const cells = {}
   for (const [key, value] of Object.entries(obj)) {
@@ -25,6 +25,7 @@ function asyncRow(obj) {
  */
 export function memorySource(data) {
   return {
+    numRows: data.length,
     scan({ where, limit, offset, signal }) {
       // Only apply offset and limit if no where clause
       const start = !where ? offset ?? 0 : 0

package/src/execute/execute.js

@@ -11,7 +11,7 @@ import { stableRowKey } from './utils.js'
 
 /**
  * @import { AsyncCells, AsyncDataSource, AsyncRow, ExecuteContext, ExecuteSqlOptions, ExprNode, SelectStatement } from '../types.js'
- * @import { DistinctNode, FilterNode, LimitNode, ProjectNode, QueryPlan, ScanNode } from '../plan/types.js'
+ * @import { CountNode, DistinctNode, FilterNode, LimitNode, ProjectNode, QueryPlan, ScanNode } from '../plan/types.js'
  */
 
 /**
@@ -61,6 +61,8 @@ export async function* executeSelect({ select, context }) {
 export async function* executePlan({ plan, context }) {
   if (plan.type === 'Scan') {
     yield* executeScan(plan, context)
+  } else if (plan.type === 'Count') {
+    yield* executeCount(plan, context)
   } else if (plan.type === 'Filter') {
     yield* executeFilter(plan, context)
   } else if (plan.type === 'Project') {
@@ -105,15 +107,15 @@ async function* executeScan(plan, context) {
   const { rows, appliedWhere, appliedLimitOffset } = scanResult
 
   // Applied limit/offset without applied where is invalid
-  const hasLimitOffset = plan.hints?.limit !== undefined || plan.hints?.offset // 0 offset is noop
-  if (!appliedWhere && appliedLimitOffset && plan.hints?.where && hasLimitOffset) {
+  const hasLimitOffset = plan.hints.limit !== undefined || plan.hints.offset // 0 offset is noop
+  if (!appliedWhere && appliedLimitOffset && plan.hints.where && hasLimitOffset) {
     throw new Error(`Data source "${plan.table}" applied limit/offset without applying where`)
   }
 
   let result = rows
 
   // Apply WHERE if data source did not
-  if (!appliedWhere && plan.hints?.where) {
+  if (!appliedWhere && plan.hints.where) {
     result = filterRows(result, plan.hints.where, context)
   }
 
@@ -125,6 +127,44 @@ async function* executeScan(plan, context) {
   yield* result
 }
 
+/**
+ * Executes a Count node using numRows when available, falling back to scan
+ *
+ * @param {CountNode} plan
+ * @param {ExecuteContext} context
+ * @yields {AsyncRow}
+ */
+async function* executeCount(plan, { tables, signal }) {
+  const dataSource = tables[plan.table]
+  if (dataSource === undefined) {
+    throw tableNotFoundError({ tableName: plan.table })
+  }
+
+  // Use source numRows if available
+  let count = dataSource.numRows
+  if (dataSource.numRows === undefined) {
+    // Fall back to counting rows via scan
+    count = 0
+    const { rows } = dataSource.scan({ signal })
+    // eslint-disable-next-line no-unused-vars
+    for await (const _ of rows) {
+      if (signal?.aborted) return
+      count++
+    }
+  }
+
+  /** @type {string[]} */
+  const columns = []
+  /** @type {AsyncCells} */
+  const cells = {}
+  for (const col of plan.columns) {
+    const alias = col.alias ?? derivedAlias(col.expr)
+    columns.push(alias)
+    cells[alias] = () => Promise.resolve(count)
+  }
+  yield { columns, cells }
+}
+
 /**
  * Filters rows by a condition
  *

package/src/expression/alias.js

@@ -30,7 +30,7 @@ export function derivedAlias(expr) {
   }
   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 === '*') {
+    if (expr.args.length === 1 && expr.args[0].type === 'star') {
       return expr.name.toLowerCase() + '_all'
     }
     return expr.name.toLowerCase() + '_' + expr.args.map(derivedAlias).join('_')

package/src/expression/evaluate.js

@@ -2,13 +2,14 @@ import { executeSelect } from '../execute/execute.js'
 import { stringify } from '../execute/utils.js'
 import { columnNotFoundError, invalidContextError } from '../executionErrors.js'
 import { unknownFunctionError } from '../parseErrors.js'
-import { isAggregateFunc, isMathFunc, isRegexpFunc, isStringFunc } from '../validation.js'
+import { isAggregateFunc, isMathFunc, isRegexpFunc, isSpatialFunc, isStringFunc } from '../validation.js'
 import { aggregateError, argValueError, castError } from '../validationErrors.js'
 import { derivedAlias } from './alias.js'
 import { applyBinaryOp } from './binary.js'
 import { applyIntervalToDate } from './date.js'
 import { evaluateMathFunc } from './math.js'
 import { evaluateRegexpFunc } from './regexp.js'
+import { evaluateSpatialFunc } from './spatial.js'
 import { evaluateStringFunc } from './strings.js'
 
 /**
@@ -127,14 +128,13 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
         }
       }
 
-      // Handle COUNT(*) special case
-      if (node.args.length === 1 && node.args[0].type === 'identifier' && funcName === 'COUNT' && node.args[0].name === '*') {
-        return filteredRows.length
-      }
-
       const argNode = node.args[0]
-
       if (funcName === 'COUNT') {
+        // COUNT(*) special case
+        if (argNode.type === 'star') {
+          return filteredRows.length
+        }
+
         if (node.distinct) {
           const seen = new Set()
           for (const row of filteredRows) {
@@ -251,6 +251,10 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       return evaluateMathFunc({ funcName, args })
     }
 
+    if (isSpatialFunc(funcName)) {
+      return evaluateSpatialFunc({ funcName, args })
+    }
+
     if (funcName === 'COALESCE') {
       // Short-circuit: evaluate args one at a time, return first non-null
       for (const arg of node.args) {
@@ -309,6 +313,32 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       return result
     }
 
+    if (funcName === 'ARRAY_LENGTH' || funcName === 'CARDINALITY') {
+      const arr = args[0]
+      if (!Array.isArray(arr)) return null
+      return arr.length
+    }
+
+    if (funcName === 'ARRAY_POSITION') {
+      const [arr, target] = args
+      if (!Array.isArray(arr)) return null
+      const index = arr.indexOf(target)
+      return index === -1 ? null : index + 1
+    }
+
+    if (funcName === 'ARRAY_SORT') {
+      const arr = args[0]
+      if (!Array.isArray(arr)) return null
+      return [...arr].sort((a, b) => {
+        if (a == null && b == null) return 0
+        if (a == null) return 1
+        if (b == null) return -1
+        if (a < b) return -1
+        if (a > b) return 1
+        return 0
+      })
+    }
+
     if (funcName === 'JSON_VALUE' || funcName === 'JSON_QUERY') {
       let jsonArg = args[0]
       const pathArg = args[1]

package/src/expression/regexp.js

@@ -10,8 +10,8 @@ import { argValueError } from '../validationErrors.js'
  * @param {Object} options
  * @param {string} options.funcName - Uppercase function name
  * @param {SqlPrimitive[]} options.args - Function arguments
- * @param {number} [options.positionStart] - Start position in SQL string for error reporting
- * @param {number} [options.positionEnd] - End position in SQL string for error reporting
+ * @param {number} options.positionStart - Start position in SQL string for error reporting
+ * @param {number} options.positionEnd - End position in SQL string for error reporting
  * @param {number} [options.rowIndex] - Row number for error reporting
  * @returns {SqlPrimitive}
  */