squirreling 0.7.8 → 0.7.10

package/README.md

@@ -104,4 +104,5 @@ Squirreling mostly follows the SQL standard. The following features are supporte
 - Date: `CURRENT_DATE`, `CURRENT_TIME`, `CURRENT_TIMESTAMP`, `INTERVAL`
 - Json: `JSON_VALUE`, `JSON_QUERY`, `JSON_OBJECT`
 - Regex: `REGEXP_SUBSTR`, `REGEXP_REPLACE`
+- Conditional: `COALESCE`, `NULLIF`
 - User-defined functions (UDFs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.7.8",
+  "version": "0.7.10",
   "description": "Squirreling SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -37,11 +37,11 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "25.0.9",
-    "@vitest/coverage-v8": "4.0.17",
+    "@types/node": "25.2.0",
+    "@vitest/coverage-v8": "4.0.18",
     "eslint": "9.39.2",
-    "eslint-plugin-jsdoc": "62.0.0",
+    "eslint-plugin-jsdoc": "62.5.0",
     "typescript": "5.9.3",
-    "vitest": "4.0.17"
+    "vitest": "4.0.18"
   }
 }

package/src/backend/dataSource.js

@@ -1,5 +1,5 @@
 /**
- * @import { AsyncCell, AsyncCells, AsyncDataSource, AsyncRow, ScanOptions, SqlPrimitive } from '../types.js'
+ * @import { AsyncCells, AsyncDataSource, AsyncRow, ScanOptions, SqlPrimitive } from '../types.js'
  */
 
 /**

package/src/execute/expression.js

@@ -123,10 +123,20 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
         })
       }
 
+      // Apply FILTER clause if present
+      let filteredRows = rows
+      if (node.filter) {
+        filteredRows = []
+        for (const row of rows) {
+          const passes = await evaluateExpr({ node: node.filter, row, tables, functions })
+          if (passes) filteredRows.push(row)
+        }
+      }
+
       // Check for star argument (COUNT(*))
       if (node.args.length === 1 && node.args[0].type === 'identifier' && node.args[0].name === '*') {
         if (funcName === 'COUNT') {
-          return rows.length
+          return filteredRows.length
         }
         throw aggregateError({
           funcName,
@@ -139,15 +149,15 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
       if (funcName === 'COUNT') {
         if (node.distinct) {
           const seen = new Set()
-          for (const r of rows) {
-            const v = await evaluateExpr({ node: argNode, row: r, tables, functions })
+          for (const row of filteredRows) {
+            const v = await evaluateExpr({ node: argNode, row, tables, functions })
             if (v != null) seen.add(v)
           }
           return seen.size
         }
         let count = 0
-        for (const r of rows) {
-          const v = await evaluateExpr({ node: argNode, row: r, tables, functions })
+        for (const row of filteredRows) {
+          const v = await evaluateExpr({ node: argNode, row, tables, functions })
           if (v != null) count++
         }
         return count
@@ -161,8 +171,8 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
         /** @type {number | null} */
         let max = null
 
-        for (const r of rows) {
-          const raw = await evaluateExpr({ node: argNode, row: r, tables, functions })
+        for (const row of filteredRows) {
+          const raw = await evaluateExpr({ node: argNode, row, tables, functions })
           if (raw == null) continue
           const num = Number(raw)
           if (!Number.isFinite(num)) continue
@@ -184,13 +194,32 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
         if (funcName === 'MAX') return max
       }
 
+      if (funcName === 'STDDEV_SAMP' || funcName === 'STDDEV_POP') {
+        const values = []
+        for (const row of filteredRows) {
+          const raw = await evaluateExpr({ node: argNode, row, tables, functions })
+          if (raw == null) continue
+          const num = Number(raw)
+          if (!Number.isFinite(num)) continue
+          values.push(num)
+        }
+        const n = values.length
+        if (n === 0) return null
+        if (funcName === 'STDDEV_SAMP' && n === 1) return null
+
+        const mean = values.reduce((a, b) => a + b, 0) / n
+        const squaredDiffs = values.reduce((acc, val) => acc + (val - mean) ** 2, 0)
+        const divisor = funcName === 'STDDEV_SAMP' ? n - 1 : n
+        return Math.sqrt(squaredDiffs / divisor)
+      }
+
       if (funcName === 'JSON_ARRAYAGG') {
         /** @type {SqlPrimitive[]} */
         const values = []
         if (node.distinct) {
           const seen = new Set()
-          for (const r of rows) {
-            const v = await evaluateExpr({ node: argNode, row: r, tables, functions })
+          for (const row of filteredRows) {
+            const v = await evaluateExpr({ node: argNode, row, tables, functions })
             const key = stringify(v)
             if (!seen.has(key)) {
               seen.add(key)
@@ -198,8 +227,8 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
             }
           }
         } else {
-          for (const r of rows) {
-            const v = await evaluateExpr({ node: argNode, row: r, tables, functions })
+          for (const row of filteredRows) {
+            const v = await evaluateExpr({ node: argNode, row, tables, functions })
             values.push(v)
           }
         }
@@ -239,6 +268,13 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
       return null
     }
 
+    if (funcName === 'NULLIF') {
+      // NULLIF(a, b) returns null if a = b, otherwise returns a
+      const val1 = await evaluateExpr({ node: node.args[0], row, tables, functions, rowIndex, rows })
+      const val2 = await evaluateExpr({ node: node.args[1], row, tables, functions, rowIndex, rows })
+      return val1 == val2 ? null : val1
+    }
+
     if (funcName === 'CURRENT_DATE') {
       return new Date().toISOString().split('T')[0]
     }

package/src/execute/having.js

@@ -28,7 +28,7 @@ export async function evaluateHavingExpr({ expr, row, group, tables, functions }
     const funcName = expr.name.toUpperCase()
     if (isAggregateFunc(funcName)) {
       // Evaluate aggregate function on the group
-      return Boolean(await evaluateAggregateFunction({ funcName, args: expr.args, group, tables, functions }))
+      return Boolean(await evaluateAggregateFunction({ funcName, args: expr.args, filter: expr.filter, group, tables, functions }))
     }
   }
 
@@ -78,7 +78,7 @@ function evaluateHavingValue({ expr, context, group, tables, functions }) {
   if (expr.type === 'function') {
     const funcName = expr.name.toUpperCase()
     if (isAggregateFunc(funcName)) {
-      return evaluateAggregateFunction({ funcName, args: expr.args, group, tables, functions })
+      return evaluateAggregateFunction({ funcName, args: expr.args, filter: expr.filter, group, tables, functions })
     }
   }
 
@@ -96,19 +96,30 @@ function evaluateHavingValue({ expr, context, group, tables, functions }) {
  * @param {Object} options
  * @param {AggregateFunc} options.funcName - aggregate function name
  * @param {ExprNode[]} options.args - function arguments
+ * @param {ExprNode} [options.filter] - optional FILTER clause expression
  * @param {AsyncRow[]} options.group - the group of rows
  * @param {Record<string, AsyncDataSource>} options.tables
  * @param {Record<string, UserDefinedFunction>} [options.functions]
  * @returns {Promise<SqlPrimitive>} the aggregate result
  */
-async function evaluateAggregateFunction({ funcName, args, group, tables, functions }) {
+async function evaluateAggregateFunction({ funcName, args, filter, group, tables, functions }) {
+  // Apply FILTER clause if present
+  let filteredGroup = group
+  if (filter) {
+    filteredGroup = []
+    for (const row of group) {
+      const passes = await evaluateExpr({ node: filter, row, tables, functions })
+      if (passes) filteredGroup.push(row)
+    }
+  }
+
   if (funcName === 'COUNT') {
     if (args.length === 1 && args[0].type === 'identifier' && args[0].name === '*') {
-      return group.length
+      return filteredGroup.length
     }
     // COUNT(column) - count non-null values
     let count = 0
-    for (const row of group) {
+    for (const row of filteredGroup) {
       const val = await evaluateExpr({ node: args[0], row, tables, functions })
       if (val != null) count++
     }
@@ -117,17 +128,21 @@ async function evaluateAggregateFunction({ funcName, args, group, tables, functi
 
   if (funcName === 'SUM') {
     let sum = 0
-    for (const row of group) {
+    let hasValue = false
+    for (const row of filteredGroup) {
       const val = await evaluateExpr({ node: args[0], row, tables, functions })
-      if (val != null) sum += Number(val)
+      if (val != null) {
+        sum += Number(val)
+        hasValue = true
+      }
     }
-    return sum
+    return hasValue ? sum : null
   }
 
   if (funcName === 'AVG') {
     let sum = 0
     let count = 0
-    for (const row of group) {
+    for (const row of filteredGroup) {
       const val = await evaluateExpr({ node: args[0], row, tables, functions })
       if (val != null) {
         sum += Number(val)
@@ -139,7 +154,7 @@ async function evaluateAggregateFunction({ funcName, args, group, tables, functi
 
   if (funcName === 'MIN') {
     let min = null
-    for (const row of group) {
+    for (const row of filteredGroup) {
       const val = await evaluateExpr({ node: args[0], row, tables, functions })
       if (val != null && (min == null || val < min)) {
         min = val
@@ -150,7 +165,7 @@ async function evaluateAggregateFunction({ funcName, args, group, tables, functi
 
   if (funcName === 'MAX') {
     let max = null
-    for (const row of group) {
+    for (const row of filteredGroup) {
       const val = await evaluateExpr({ node: args[0], row, tables, functions })
       if (val != null && (max == null || val > max)) {
         max = val
@@ -159,10 +174,29 @@ async function evaluateAggregateFunction({ funcName, args, group, tables, functi
     return max
   }
 
+  if (funcName === 'STDDEV_SAMP' || funcName === 'STDDEV_POP') {
+    const values = []
+    for (const row of filteredGroup) {
+      const val = await evaluateExpr({ node: args[0], row, tables, functions })
+      if (val == null) continue
+      const num = Number(val)
+      if (!Number.isFinite(num)) continue
+      values.push(num)
+    }
+    const n = values.length
+    if (n === 0) return null
+    if (funcName === 'STDDEV_SAMP' && n === 1) return null
+
+    const mean = values.reduce((a, b) => a + b, 0) / n
+    const squaredDiffs = values.reduce((acc, val) => acc + (val - mean) ** 2, 0)
+    const divisor = funcName === 'STDDEV_SAMP' ? n - 1 : n
+    return Math.sqrt(squaredDiffs / divisor)
+  }
+
   throw unknownFunctionError({
     funcName,
     positionStart: 0,
     positionEnd: 0,
-    validFunctions: 'COUNT, SUM, AVG, MIN, MAX',
+    validFunctions: 'COUNT, SUM, AVG, MIN, MAX, STDDEV_SAMP, STDDEV_POP',
   })
 }

package/src/index.d.ts

@@ -1,5 +1,18 @@
 import type { AsyncDataSource, AsyncRow, ExecuteSqlOptions, ParseSqlOptions, SelectStatement, SqlPrimitive, Token } from './types.js'
-export type { AsyncCells, AsyncDataSource, AsyncRow, ExprNode, ParseSqlOptions, SelectStatement, SqlPrimitive, Token, UserDefinedFunction } from './types.js'
+export type {
+  AsyncCells,
+  AsyncDataSource,
+  AsyncRow,
+  ExecuteSqlOptions,
+  ExprNode,
+  ParseSqlOptions,
+  QueryHints,
+  ScanOptions,
+  SelectStatement,
+  SqlPrimitive,
+  Token,
+  UserDefinedFunction,
+} from './types.js'
 
 /**
  * Executes a SQL SELECT query against an array of data rows

package/src/parse/functions.js

@@ -1,5 +1,5 @@
-import { argCountParseError } from '../parseErrors.js'
-import { validateFunctionArgCount } from '../validation.js'
+import { argCountParseError, syntaxError } from '../parseErrors.js'
+import { isAggregateFunc, validateFunctionArgCount } from '../validation.js'
 import { parseExpression } from './expression.js'
 import { consume, current, expect, lastPosition, match } from './state.js'
 
@@ -52,6 +52,26 @@ export function parseFunctionCall(state, funcName, positionStart) {
 
   expect(state, 'paren', ')')
 
+  // Check for FILTER clause (only valid for aggregate functions)
+  /** @type {ExprNode | undefined} */
+  let filter
+  if (current(state).type === 'keyword' && current(state).value === 'FILTER') {
+    const funcNameUpper = funcName.toUpperCase()
+    if (!isAggregateFunc(funcNameUpper)) {
+      throw syntaxError({
+        expected: 'aggregate function for FILTER clause',
+        received: `FILTER on non-aggregate function "${funcName}"`,
+        positionStart: current(state).positionStart,
+        positionEnd: current(state).positionEnd,
+      })
+    }
+    consume(state) // FILTER
+    expect(state, 'paren', '(')
+    expect(state, 'keyword', 'WHERE')
+    filter = parseExpression(state)
+    expect(state, 'paren', ')')
+  }
+
   // Validate argument count at parse time
   const funcNameUpper = funcName.toUpperCase()
   const validation = validateFunctionArgCount(funcNameUpper, args.length, state.functions)
@@ -70,6 +90,7 @@ export function parseFunctionCall(state, funcName, positionStart) {
     name: funcName,
     args,
     distinct: distinct || undefined,
+    filter,
     positionStart,
     positionEnd: lastPosition(state),
   }

package/src/parse/joins.js

@@ -24,21 +24,15 @@ export function parseJoins(state) {
         joinType = 'INNER'
       } else if (tok.value === 'LEFT') {
         consume(state)
-        if (match(state, 'keyword', 'OUTER')) {
-          // LEFT OUTER JOIN
-        }
+        match(state, 'keyword', 'OUTER') // LEFT OUTER JOIN
         joinType = 'LEFT'
       } else if (tok.value === 'RIGHT') {
         consume(state)
-        if (match(state, 'keyword', 'OUTER')) {
-          // RIGHT OUTER JOIN
-        }
+        match(state, 'keyword', 'OUTER') // RIGHT OUTER JOIN
         joinType = 'RIGHT'
       } else if (tok.value === 'FULL') {
         consume(state)
-        if (match(state, 'keyword', 'OUTER')) {
-          // FULL OUTER JOIN
-        }
+        match(state, 'keyword', 'OUTER') // FULL OUTER JOIN
         joinType = 'FULL'
       } else if (tok.value === 'POSITIONAL') {
         consume(state)

package/src/parse/tokenize.js

@@ -56,6 +56,7 @@ const KEYWORDS = new Set([
   'HOUR',
   'MINUTE',
   'SECOND',
+  'FILTER',
 ])
 
 /**

package/src/types.d.ts

@@ -141,6 +141,7 @@ export interface FunctionNode extends ExprNodeBase {
   name: string
   args: ExprNode[]
   distinct?: boolean
+  filter?: ExprNode
 }
 
 export interface CastNode extends ExprNodeBase {
@@ -211,7 +212,7 @@ export interface StarColumn {
   alias?: string
 }
 
-export type AggregateFunc = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'JSON_ARRAYAGG'
+export type AggregateFunc = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'JSON_ARRAYAGG' | 'STDDEV_SAMP' | 'STDDEV_POP'
 
 export type MathFunc =
   | 'FLOOR'

package/src/validation.js

@@ -5,7 +5,7 @@
  * @returns {name is AggregateFunc}
  */
 export function isAggregateFunc(name) {
-  return ['COUNT', 'SUM', 'AVG', 'MIN', 'MAX', 'JSON_ARRAYAGG'].includes(name)
+  return ['COUNT', 'SUM', 'AVG', 'MIN', 'MAX', 'JSON_ARRAYAGG', 'STDDEV_SAMP', 'STDDEV_POP'].includes(name)
 }
 
 /**
@@ -117,6 +117,7 @@ export const FUNCTION_ARG_COUNTS = {
 
   // Conditional functions
   COALESCE: { min: 1 },
+  NULLIF: { min: 2, max: 2 },
 
   // Aggregate functions
   COUNT: { min: 1, max: 1 },
@@ -124,6 +125,8 @@ export const FUNCTION_ARG_COUNTS = {
   AVG: { min: 1, max: 1 },
   MIN: { min: 1, max: 1 },
   MAX: { min: 1, max: 1 },
+  STDDEV_SAMP: { min: 1, max: 1 },
+  STDDEV_POP: { min: 1, max: 1 },
 }
 
 /**
@@ -192,7 +195,7 @@ export function isKnownFunction(funcName, functions) {
   if ([
     'CURRENT_DATE', 'CURRENT_TIME', 'CURRENT_TIMESTAMP',
     'JSON_VALUE', 'JSON_QUERY', 'JSON_OBJECT',
-    'COALESCE', 'CAST',
+    'COALESCE', 'NULLIF', 'CAST',
   ].includes(funcName)) {
     return true
   }

package/src/validationErrors.js

@@ -66,6 +66,8 @@ export const FUNCTION_SIGNATURES = {
   AVG: 'expression',
   MIN: 'expression',
   MAX: 'expression',
+  STDDEV_SAMP: 'expression',
+  STDDEV_POP: 'expression',
 }
 
 /**