squirreling 0.12.0 → 0.12.2

package/README.md

@@ -35,7 +35,10 @@ const users = [
 
 // Squirreling return types
 interface QueryResults {
-  rows: () => AsyncGenerator<AsyncRow>
+  columns: string[]
+  numRows?: number
+  maxRows?: number
+  rows(): AsyncGenerator<AsyncRow>
 }
 interface AsyncRow {
   columns: string[]
@@ -151,14 +154,14 @@ Squirreling mostly follows the SQL standard. The following features are supporte
 
 ### Functions
 
-- Aggregate: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `MEDIAN`, `PERCENTILE_CONT`, `APPROX_QUANTILE`, `STDDEV_POP`, `STDDEV_SAMP`, `JSON_ARRAYAGG`
+- Aggregate: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `MEDIAN`, `PERCENTILE_CONT`, `APPROX_QUANTILE`, `STDDEV_POP`, `STDDEV_SAMP`, `JSON_ARRAYAGG`, `STRING_AGG`
 - String: `CONCAT`, `SUBSTRING`, `REPLACE`, `LENGTH`, `UPPER`, `LOWER`, `TRIM`, `LEFT`, `RIGHT`, `INSTR`, `POSITION`, `STRPOS`
 - 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`, `DATE_PART`, `DATE_TRUNC`, `EXTRACT`, `INTERVAL`
-- Json: `JSON_VALUE`, `JSON_QUERY`, `JSON_EXTRACT`, `JSON_OBJECT`
+- Json: `JSON_VALUE`, `JSON_QUERY`, `JSON_EXTRACT`, `JSON_OBJECT`, `JSON_ARRAY_LENGTH`
 - Array: `ARRAY_LENGTH`, `ARRAY_POSITION`, `ARRAY_SORT`, `CARDINALITY`
-- Regex: `REGEXP_SUBSTR`, `REGEXP_EXTRACT`, `REGEXP_REPLACE`
+- Regex: `REGEXP_SUBSTR`, `REGEXP_EXTRACT`, `REGEXP_REPLACE`, `REGEXP_MATCHES`
 - 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`
+- Conditional: `COALESCE`, `NULLIF`, `GREATEST`, `LEAST`
 - User-defined functions (UDFs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Squirreling Async SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -39,11 +39,11 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "25.5.0",
-    "@vitest/coverage-v8": "4.1.2",
+    "@types/node": "25.6.0",
+    "@vitest/coverage-v8": "4.1.4",
     "eslint": "9.39.2",
     "eslint-plugin-jsdoc": "62.9.0",
     "typescript": "6.0.2",
-    "vitest": "4.1.2"
+    "vitest": "4.1.4"
   }
 }

package/src/backend/dataSource.js

@@ -15,7 +15,7 @@ export function asyncRow(obj, columns) {
   for (const key of columns) {
     cells[key] = () => Promise.resolve(obj[key])
   }
-  return { columns, cells }
+  return { columns, cells, resolved: obj }
 }
 
 /**
@@ -34,13 +34,14 @@ export function memorySource({ data, columns }) {
     }
     const firstColumns = Object.keys(data[0])
     // Check first 1000 rows for consistent columns
+    const firstColSet = new Set(firstColumns)
     for (let i = 1; i < data.length && i < 1000; i++) {
       const rowColumns = Object.keys(data[i])
       const missing = firstColumns.find(col => !rowColumns.includes(col))
       if (missing) {
         throw new Error(`Inconsistent data, column "${missing}" not found in row ${i}`)
       }
-      const extra = rowColumns.find(col => !firstColumns.includes(col))
+      const extra = rowColumns.find(col => !firstColSet.has(col))
       if (extra) {
         throw new Error(`Inconsistent data, unexpected column "${extra}" found in row ${i}`)
       }
@@ -54,11 +55,12 @@ export function memorySource({ data, columns }) {
       // Only apply offset and limit if no where clause
       const start = !where ? offset ?? 0 : 0
       const end = !where && limit !== undefined ? start + limit : data.length
+      const rowColumns = scanColumns ?? columns
       return {
         async *rows() {
           for (let i = start; i < end && i < data.length; i++) {
             if (signal?.aborted) break
-            yield asyncRow(data[i], scanColumns ?? columns)
+            yield asyncRow(data[i], rowColumns)
           }
         },
         appliedWhere: false,

package/src/execute/aggregates.js

@@ -1,6 +1,6 @@
 import { derivedAlias } from '../expression/alias.js'
 import { evaluateExpr } from '../expression/evaluate.js'
-import { executePlan } from './execute.js'
+import { executePlan, selectColumnNames } from './execute.js'
 import { keyify } from './utils.js'
 
 /**
@@ -60,8 +60,9 @@ function projectAggregateColumns(selectColumns, group, context) {
 export function executeHashAggregate(plan, context) {
   const child = executePlan({ plan: plan.child, context })
   return {
+    columns: selectColumnNames(plan.columns, child.columns),
     maxRows: child.maxRows,
-    async *rows () {
+    async *rows() {
       // Collect all rows
       /** @type {AsyncRow[]} */
       const allRows = []
@@ -119,9 +120,11 @@ export function executeHashAggregate(plan, context) {
  */
 export function executeScalarAggregate(plan, context) {
   // Fast path: use scanColumn when available
+  const scalarColumns = selectColumnNames(plan.columns, [])
   const fast = tryColumnScanAggregate(plan, context)
   if (fast) {
     return {
+      columns: scalarColumns,
       numRows: 1,
       maxRows: 1,
       rows: fast,
@@ -130,9 +133,10 @@ export function executeScalarAggregate(plan, context) {
 
   const child = executePlan({ plan: plan.child, context })
   return {
+    columns: selectColumnNames(plan.columns, child.columns),
     numRows: plan.having ? undefined : 1,
     maxRows: 1,
-    async *rows () {
+    async *rows() {
       // Collect all rows into single group
       /** @type {AsyncRow[]} */
       const group = []

package/src/execute/execute.js

@@ -10,7 +10,7 @@ import { executeSort } from './sort.js'
 import { addBounds, minBounds, stableRowKey } from './utils.js'
 
 /**
- * @import { AsyncCells, AsyncDataSource, AsyncRow, ExecuteContext, ExecuteSqlOptions, ExprNode, QueryResults, Statement } from '../types.js'
+ * @import { AsyncCells, AsyncDataSource, AsyncRow, DerivedColumn, ExecuteContext, ExecuteSqlOptions, ExprNode, IdentifierNode, QueryResults, SelectColumn, SqlPrimitive, Statement } from '../types.js'
  * @import { CountNode, DistinctNode, FilterNode, LimitNode, ProjectNode, QueryPlan, ScanNode, SetOperationNode } from '../plan/types.js'
  */
 
@@ -24,14 +24,27 @@ export function executeSql({ tables, query, functions, signal }) {
   const parsed = typeof query === 'string' ? parseSql({ query, functions }) : query
 
   // Normalize tables: convert arrays to AsyncDataSource
+  // Fast path: skip normalization when no arrays are present
+  let needsNormalization = false
+  const tableKeys = Object.keys(tables)
+  for (let i = 0; i < tableKeys.length; i++) {
+    if (Array.isArray(tables[tableKeys[i]])) {
+      needsNormalization = true
+      break
+    }
+  }
+
   /** @type {Record<string, AsyncDataSource>} */
-  const normalizedTables = {}
-  for (const [name, data] of Object.entries(tables)) {
-    if (Array.isArray(data)) {
-      normalizedTables[name] = memorySource({ data })
-    } else {
-      normalizedTables[name] = data
+  let normalizedTables
+  if (needsNormalization) {
+    normalizedTables = {}
+    for (let i = 0; i < tableKeys.length; i++) {
+      const name = tableKeys[i]
+      const data = tables[name]
+      normalizedTables[name] = Array.isArray(data) ? memorySource({ data }) : data
     }
+  } else {
+    normalizedTables = /** @type {Record<string, AsyncDataSource>} */ (tables)
   }
 
   const context = { tables: normalizedTables, functions, signal }
@@ -88,7 +101,33 @@ export function executePlan({ plan, context }) {
   } else if (plan.type === 'SetOperation') {
     return executeSetOperation(plan, context)
   }
-  return { async *rows () {} }
+  return { columns: [], async *rows() {} }
+}
+
+/**
+ * Derives output column names from SELECT columns and available child columns.
+ *
+ * @param {SelectColumn[]} selectColumns
+ * @param {string[]} childColumns
+ * @returns {string[]}
+ */
+export function selectColumnNames(selectColumns, childColumns) {
+  /** @type {string[]} */
+  const result = []
+  for (const col of selectColumns) {
+    if (col.type === 'star') {
+      const prefix = col.table ? `${col.table}.` : undefined
+      for (const key of childColumns) {
+        if (prefix && !key.startsWith(prefix)) continue
+        const dotIndex = key.indexOf('.')
+        const outputKey = prefix ? key.substring(prefix.length) : dotIndex >= 0 ? key.substring(dotIndex + 1) : key
+        result.push(outputKey)
+      }
+    } else {
+      result.push(col.alias ?? derivedAlias(col.expr))
+    }
+  }
+  return result
 }
 
 /**
@@ -113,9 +152,10 @@ function executeScan(plan, context) {
     })
     const scanRows = computeScanRows(table.numRows, plan.hints.limit, plan.hints.offset)
     return {
+      columns: [column],
       numRows: scanRows,
       maxRows: scanRows,
-      async *rows () {
+      async *rows() {
         const columns = [column]
         for await (const chunk of chunks) {
           if (signal?.aborted) return
@@ -142,9 +182,10 @@ function executeScan(plan, context) {
 
   const scanRows = computeScanRows(table.numRows, plan.hints.limit, plan.hints.offset)
   return {
+    columns: plan.hints.columns ?? table.columns,
     numRows: !plan.hints.where ? scanRows : undefined,
     maxRows: scanRows,
-    async *rows () {
+    async *rows() {
       let result = scanResult.rows()
 
       // Apply WHERE if data source did not
@@ -174,9 +215,10 @@ function executeCount(plan, context) {
   const table = validateTable({ ...plan, tables })
 
   return {
+    columns: plan.columns.map(col => col.alias ?? derivedAlias(col.expr)),
     numRows: 1,
     maxRows: 1,
-    async *rows () {
+    async *rows() {
       // Use source numRows if available
       let count = table.numRows
       if (count === undefined) {
@@ -300,6 +342,7 @@ async function* limitRows(rows, limit, offset, signal) {
 function executeFilter(plan, context) {
   const child = executePlan({ plan: plan.child, context })
   return {
+    columns: child.columns,
     maxRows: child.maxRows,
     rows: () => filterRows(child.rows(), plan.condition, context),
   }
@@ -314,36 +357,86 @@ function executeFilter(plan, context) {
  */
 function executeProject(plan, context) {
   const child = executePlan({ plan: plan.child, context })
+
+  // Pre-compute column names for derived columns (avoids per-row derivedAlias calls)
+  const hasStar = plan.columns.some(col => col.type === 'star')
+
+  /** @type {string[] | undefined} */
+  let staticColumns
+  /** @type {{ alias: string, sourceName: string }[] | undefined} */
+  let identifierMap
+  if (!hasStar) {
+    const derived = /** @type {DerivedColumn[]} */ (plan.columns)
+    staticColumns = derived.map(col => col.alias ?? derivedAlias(col.expr))
+    const allIdentifiers = derived.every(col =>
+      col.expr.type === 'identifier' && !col.expr.prefix
+    )
+    if (allIdentifiers) {
+      identifierMap = derived.map((col, i) => ({
+        alias: staticColumns[i],
+        sourceName: /** @type {IdentifierNode} */ (col.expr).name,
+      }))
+    }
+  }
+
   return {
+    columns: selectColumnNames(plan.columns, child.columns),
     numRows: child.numRows,
     maxRows: child.maxRows,
-    async *rows () {
+    async *rows() {
       let rowIndex = 0
+      let identifierMapValidated = false
 
       for await (const row of child.rows()) {
         if (context.signal?.aborted) return
         rowIndex++
+
+        // Validate identifier fast path on first row (may fail for JOINs with prefixed columns)
+        if (identifierMap && !identifierMapValidated) {
+          identifierMapValidated = true
+          if (!identifierMap.every(m => m.sourceName in row.cells)) {
+            identifierMap = undefined
+          }
+        }
+
+        // Fast path: all columns are simple identifier references
+        if (identifierMap) {
+          /** @type {AsyncCells} */
+          const cells = {}
+          const source = row.resolved
+          /** @type {Record<string, SqlPrimitive> | undefined} */
+          const resolved = source ? {} : undefined
+          for (const { alias, sourceName } of identifierMap) {
+            cells[alias] = row.cells[sourceName]
+            if (resolved && source) resolved[alias] = source[sourceName]
+          }
+          yield resolved
+            ? { columns: staticColumns, cells, resolved }
+            : { columns: staticColumns, cells }
+          continue
+        }
+
         const currentRowIndex = rowIndex
 
         /** @type {string[]} */
-        const columns = []
+        const columns = staticColumns ?? []
         /** @type {AsyncCells} */
         const cells = {}
 
-        for (const col of plan.columns) {
+        for (let i = 0; i < plan.columns.length; i++) {
+          const col = plan.columns[i]
           if (col.type === 'star') {
             const prefix = col.table ? `${col.table}.` : undefined
             for (const key of row.columns) {
               if (prefix && !key.startsWith(prefix)) continue
-              // Strip table prefix for output column names
               const dotIndex = key.indexOf('.')
               const outputKey = prefix ? key.substring(prefix.length) : dotIndex >= 0 ? key.substring(dotIndex + 1) : key
               columns.push(outputKey)
               cells[outputKey] = row.cells[key]
             }
           } else {
-            const alias = col.alias ?? derivedAlias(col.expr)
-            columns.push(alias)
+            const alias = staticColumns ? staticColumns[i] : (col.alias ?? derivedAlias(col.expr))
+            if (!staticColumns) columns.push(alias)
             cells[alias] = () => evaluateExpr({
               node: col.expr,
               row,
@@ -369,8 +462,9 @@ function executeProject(plan, context) {
 function executeDistinct(plan, context) {
   const child = executePlan({ plan: plan.child, context })
   return {
+    columns: child.columns,
     maxRows: child.maxRows,
-    async *rows () {
+    async *rows() {
       const { signal } = context
       const MAX_CHUNK = 256
 
@@ -421,6 +515,7 @@ function executeDistinct(plan, context) {
 function executeLimit(plan, context) {
   const child = executePlan({ plan: plan.child, context })
   return {
+    columns: child.columns,
     numRows: computeScanRows(child.numRows, plan.limit, plan.offset),
     maxRows: computeScanRows(child.maxRows, plan.limit, plan.offset),
     rows: () => limitRows(child.rows(), plan.limit, plan.offset, context.signal),
@@ -442,9 +537,10 @@ function executeSetOperation(plan, context) {
       const left = executePlan({ plan: plan.left, context })
       const right = executePlan({ plan: plan.right, context })
       return {
+        columns: left.columns,
         numRows: addBounds(left.numRows, right.numRows),
         maxRows: addBounds(left.maxRows, right.maxRows),
-        async *rows () {
+        async *rows() {
           // UNION ALL: yield all rows from both sides
           yield* left.rows()
           yield* right.rows()
@@ -454,8 +550,9 @@ function executeSetOperation(plan, context) {
       const left = executePlan({ plan: plan.left, context })
       const right = executePlan({ plan: plan.right, context })
       return {
+        columns: left.columns,
         maxRows: addBounds(left.maxRows, right.maxRows),
-        async *rows () {
+        async *rows() {
           // UNION: yield deduplicated rows from both sides
           const seen = new Set()
           for await (const row of left.rows()) {
@@ -481,8 +578,9 @@ function executeSetOperation(plan, context) {
     const left = executePlan({ plan: plan.left, context })
     const right = executePlan({ plan: plan.right, context })
     return {
+      columns: left.columns,
       maxRows: minBounds(left.maxRows, right.maxRows),
-      async *rows () {
+      async *rows() {
         // Materialize right side keys
         /** @type {Map<any, number>} */
         const rightKeys = new Map()
@@ -522,8 +620,9 @@ function executeSetOperation(plan, context) {
     const left = executePlan({ plan: plan.left, context })
     const right = executePlan({ plan: plan.right, context })
     return {
+      columns: left.columns,
       maxRows: left.maxRows,
-      async *rows () {
+      async *rows() {
         // Materialize right side keys
         /** @type {Map<any, number>} */
         const rightKeys = new Map()

package/src/execute/join.js

@@ -18,7 +18,8 @@ export function executeNestedLoopJoin(plan, context) {
   const left = executePlan({ plan: plan.left, context })
   const right = executePlan({ plan: plan.right, context })
   return {
-    async *rows () {
+    columns: mergeColumnNames(left.columns, right.columns, plan.leftAlias, plan.rightAlias),
+    async *rows() {
       const leftTable = plan.leftAlias
       const rightTable = plan.rightAlias
 
@@ -93,9 +94,10 @@ export function executePositionalJoin(plan, context) {
   const numRows = left.numRows !== undefined && right.numRows !== undefined
     ? Math.max(left.numRows, right.numRows) : undefined
   return {
+    columns: mergeColumnNames(left.columns, right.columns, plan.leftAlias, plan.rightAlias),
     numRows,
     maxRows: maxBounds(left.maxRows, right.maxRows),
-    async *rows () {
+    async *rows() {
       const { signal } = context
       const leftTable = plan.leftAlias
       const rightTable = plan.rightAlias
@@ -140,7 +142,8 @@ export function executeHashJoin(plan, context) {
   const left = executePlan({ plan: plan.left, context })
   const right = executePlan({ plan: plan.right, context })
   return {
-    async *rows () {
+    columns: mergeColumnNames(left.columns, right.columns, plan.leftAlias, plan.rightAlias),
+    async *rows() {
       const leftTable = plan.leftAlias
       const rightTable = plan.rightAlias
 
@@ -233,6 +236,22 @@ function createNullRow(columns) {
   return { columns, cells }
 }
 
+/**
+ * Merges column name arrays with table prefixes, matching mergeRows logic.
+ *
+ * @param {string[]} leftColumns
+ * @param {string[]} rightColumns
+ * @param {string} leftTable
+ * @param {string} rightTable
+ * @returns {string[]}
+ */
+function mergeColumnNames(leftColumns, rightColumns, leftTable, rightTable) {
+  return [
+    ...leftColumns.map(c => c.includes('.') ? c : `${leftTable}.${c}`),
+    ...rightColumns.map(c => c.includes('.') ? c : `${rightTable}.${c}`),
+  ]
+}
+
 /**
  * Merges two rows into one, prefixing columns with table names
  *

package/src/execute/sort.js

@@ -17,9 +17,10 @@ import { compareForTerm } from './utils.js'
 export function executeSort(plan, context) {
   const child = executePlan({ plan: plan.child, context })
   return {
+    columns: child.columns,
     numRows: child.numRows,
     maxRows: child.maxRows,
-    async *rows () {
+    async *rows() {
       // Buffer all rows
       /** @type {AsyncRow[]} */
       const rows = []

package/src/execute/utils.js

@@ -2,6 +2,8 @@
  * @import { AsyncRow, OrderByItem, QueryResults, SqlPrimitive } from '../types.js'
  */
 
+const primitiveTypes = new Set(['number', 'bigint', 'boolean', 'string'])
+
 /**
  * Compares two values for a single ORDER BY term, handling nulls and direction
  *
@@ -24,10 +26,9 @@ export function compareForTerm(a, b, term) {
   // Compare non-null values
   if (a == b) return 0
 
-  const primitives = ['number', 'bigint', 'boolean', 'string']
   let cmp
-  if (primitives.includes(typeof a) && primitives.includes(typeof b)) {
-    cmp = a < b ? -1 : a > b ? 1 : 0
+  if (primitiveTypes.has(typeof a) && primitiveTypes.has(typeof b)) {
+    cmp = a < b ? -1 : 1
   } else {
     const aa = String(a)
     const bb = String(b)
@@ -51,6 +52,29 @@ export async function collect(results) {
   for await (const asyncRow of results.rows()) {
     rows.push(asyncRow)
   }
+
+  // Fast path: if all rows have pre-materialized data, skip Promise overhead
+  let allMaterialized = rows.length > 0
+  for (let i = 0; i < rows.length; i++) {
+    if (!rows[i].resolved) {
+      allMaterialized = false
+      break
+    }
+  }
+  if (allMaterialized) {
+    const result = new Array(rows.length)
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i]
+      /** @type {Record<string, SqlPrimitive>} */
+      const item = {}
+      for (const col of row.columns) {
+        item[col] = row.resolved[col]
+      }
+      result[i] = item
+    }
+    return result
+  }
+
   return Promise.all(rows.map(async asyncRow => {
     const values = await Promise.all(asyncRow.columns.map(k => asyncRow.cells[k]()))
     /** @type {Record<string, SqlPrimitive>} */

package/src/expression/evaluate.js

@@ -272,6 +272,32 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
           ))
         }
       }
+
+      if (funcName === 'STRING_AGG') {
+        const separatorNode = node.args[1]
+        const separator = String(await evaluateExpr({ node: separatorNode, row: filteredRows[0] ?? { columns: [], cells: {} }, context }))
+        /** @type {string[]} */
+        const values = []
+        if (node.distinct) {
+          const seen = new Set()
+          for (const row of filteredRows) {
+            const v = await evaluateExpr({ node: argNode, row, context })
+            if (v == null) continue
+            const str = String(v)
+            const key = keyify(str)
+            if (!seen.has(key)) {
+              seen.add(key)
+              values.push(str)
+            }
+          }
+        } else {
+          for (const row of filteredRows) {
+            const v = await evaluateExpr({ node: argNode, row, context })
+            if (v != null) values.push(String(v))
+          }
+        }
+        return values.length === 0 ? null : values.join(separator)
+      }
     }
 
     /** @type {SqlPrimitive[]} */
@@ -311,6 +337,20 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       return val1 == await val2 ? null : val1
     }
 
+    if (funcName === 'GREATEST' || funcName === 'LEAST') {
+      // Skip nulls; return null if all inputs are null
+      const isGreatest = funcName === 'GREATEST'
+      /** @type {SqlPrimitive} */
+      let best = null
+      for (const arg of args) {
+        if (arg == null) continue
+        if (best == null || (isGreatest ? arg > best : arg < best)) {
+          best = arg
+        }
+      }
+      return best
+    }
+
     if (funcName === 'DATE_TRUNC') {
       return dateTrunc(args[0], args[1])
     }
@@ -357,6 +397,25 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       return result
     }
 
+    if (funcName === 'JSON_ARRAY_LENGTH') {
+      let arr = args[0]
+      if (arr == null) return null
+      if (typeof arr === 'string') {
+        try {
+          arr = JSON.parse(arr)
+        } catch {
+          throw new ArgValueError({
+            ...node,
+            message: 'invalid JSON string',
+            hint: 'Argument must be valid JSON.',
+            rowIndex,
+          })
+        }
+      }
+      if (!Array.isArray(arr)) return null
+      return arr.length
+    }
+
     if (funcName === 'ARRAY_LENGTH' || funcName === 'CARDINALITY') {
       const arr = args[0]
       if (!Array.isArray(arr)) return null

package/src/expression/regexp.js

@@ -78,6 +78,27 @@ export function evaluateRegexpFunc({ funcName, node, args, rowIndex }) {
     return null
   }
 
+  if (funcName === 'REGEXP_MATCHES') {
+    const str = args[0]
+    const pattern = args[1]
+    if (str == null || pattern == null) return null
+    const strVal = String(str)
+    const patternStr = String(pattern)
+
+    let regex
+    try {
+      regex = new RegExp(patternStr)
+    } catch (/** @type {any} */ error) {
+      throw new ArgValueError({
+        ...node,
+        message: `invalid regex pattern: ${error.message}`,
+        rowIndex,
+      })
+    }
+
+    return regex.test(strVal)
+  }
+
   if (funcName === 'REGEXP_REPLACE') {
     const str = args[0]
     const pattern = args[1]

package/src/types.d.ts

@@ -8,6 +8,7 @@ export { QueryPlan } from './plan/types.js'
  * Result of executing a SQL query.
  */
 export interface QueryResults {
+  columns: string[]
   rows(): AsyncGenerator<AsyncRow>
   numRows?: number
   maxRows?: number
@@ -45,6 +46,9 @@ export interface ExecuteContext {
 export interface AsyncRow {
   columns: string[]
   cells: AsyncCells
+  // Optional pre-materialized row values keyed by output column name.
+  // When present, consumers can skip the AsyncCell Promise roundtrip.
+  resolved?: Record<string, SqlPrimitive>
 }
 export type AsyncCells = Record<string, AsyncCell>
 export type AsyncCell = () => Promise<SqlPrimitive>
@@ -68,7 +72,6 @@ export interface AsyncDataSource {
  */
 export interface ScanResults {
   rows(): AsyncIterable<AsyncRow>
-  numRows?: number // exact row count if known
   appliedWhere: boolean // WHERE filter applied at scan time?
   appliedLimitOffset: boolean // LIMIT and OFFSET applied at scan time?
 }
@@ -110,9 +113,9 @@ export interface UserDefinedFunction {
   arguments: FunctionSignature
 }
 
-export type AggregateFunc = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'JSON_ARRAYAGG' | 'STDDEV_SAMP' | 'STDDEV_POP' | 'MEDIAN' | 'PERCENTILE_CONT' | 'APPROX_QUANTILE'
+export type AggregateFunc = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'JSON_ARRAYAGG' | 'STDDEV_SAMP' | 'STDDEV_POP' | 'MEDIAN' | 'PERCENTILE_CONT' | 'APPROX_QUANTILE' | 'STRING_AGG'
 
-export type RegExpFunction = 'REGEXP_SUBSTR' | 'REGEXP_EXTRACT' | 'REGEXP_REPLACE'
+export type RegExpFunction = 'REGEXP_SUBSTR' | 'REGEXP_EXTRACT' | 'REGEXP_REPLACE' | 'REGEXP_MATCHES'
 
 export type MathFunc =
   | 'FLOOR'

package/src/validation/functions.js

@@ -11,7 +11,7 @@ export const niladicFuncs = ['CURRENT_DATE', 'CURRENT_TIME', 'CURRENT_TIMESTAMP'
  * @returns {name is AggregateFunc}
  */
 export function isAggregateFunc(name) {
-  return ['COUNT', 'SUM', 'AVG', 'MIN', 'MAX', 'JSON_ARRAYAGG', 'STDDEV_SAMP', 'STDDEV_POP', 'MEDIAN', 'PERCENTILE_CONT', 'APPROX_QUANTILE'].includes(name)
+  return ['COUNT', 'SUM', 'AVG', 'MIN', 'MAX', 'JSON_ARRAYAGG', 'STDDEV_SAMP', 'STDDEV_POP', 'MEDIAN', 'PERCENTILE_CONT', 'APPROX_QUANTILE', 'STRING_AGG'].includes(name)
 }
 
 /**
@@ -31,7 +31,7 @@ export function isMathFunc(name) {
  * @returns {name is RegExpFunction}
  */
 export function isRegexpFunc(name) {
-  return ['REGEXP_SUBSTR', 'REGEXP_EXTRACT', 'REGEXP_REPLACE'].includes(name)
+  return ['REGEXP_SUBSTR', 'REGEXP_EXTRACT', 'REGEXP_REPLACE', 'REGEXP_MATCHES'].includes(name)
 }
 
 /**
@@ -112,6 +112,7 @@ export const FUNCTION_SIGNATURES = {
   REGEXP_SUBSTR: { min: 2, max: 4, signature: 'string, pattern[, position[, occurrence]]' },
   REGEXP_EXTRACT: { min: 2, max: 4, signature: 'string, pattern[, position[, occurrence]]' },
   REGEXP_REPLACE: { min: 3, max: 5, signature: 'string, pattern, replacement[, position[, occurrence]]' },
+  REGEXP_MATCHES: { min: 2, max: 2, signature: 'string, pattern' },
 
   // Date/time functions
   RANDOM: { min: 0, max: 0, signature: '' },
@@ -154,6 +155,7 @@ export const FUNCTION_SIGNATURES = {
   JSON_QUERY: { min: 2, max: 2, signature: 'expression, path' },
   JSON_EXTRACT: { min: 2, max: 2, signature: 'expression, path' },
   JSON_OBJECT: { min: 0, signature: 'key1, value1[, ...]' },
+  JSON_ARRAY_LENGTH: { min: 1, max: 1, signature: 'array' },
   JSON_ARRAYAGG: { min: 1, max: 1, signature: 'expression' },
 
   // Array functions
@@ -165,6 +167,8 @@ export const FUNCTION_SIGNATURES = {
   // Conditional functions
   COALESCE: { min: 1, signature: 'value1, value2[, ...]' },
   NULLIF: { min: 2, max: 2, signature: 'value1, value2' },
+  GREATEST: { min: 1, signature: 'value1[, value2, ...]' },
+  LEAST: { min: 1, signature: 'value1[, value2, ...]' },
 
   // Aggregate functions
   COUNT: { min: 1, max: 1, signature: 'expression' },
@@ -177,6 +181,7 @@ export const FUNCTION_SIGNATURES = {
   MEDIAN: { min: 1, max: 1, signature: 'expression' },
   PERCENTILE_CONT: { min: 2, max: 2, signature: 'fraction, expression' },
   APPROX_QUANTILE: { min: 2, max: 2, signature: 'expression, fraction' },
+  STRING_AGG: { min: 2, max: 2, signature: 'expression, separator' },
 
   // Spatial functions
   ST_INTERSECTS: { min: 2, max: 2, signature: 'geometry, geometry' },