squirreling 0.12.7 → 0.12.8

package/README.md

@@ -154,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`, `STRING_AGG`
+- Aggregate: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `MEDIAN`, `PERCENTILE_CONT`, `APPROX_QUANTILE`, `STDDEV_POP`, `STDDEV_SAMP`, `ARRAY_AGG`, `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_ARRAY_LENGTH`
+- Json: `JSON_VALUE`, `JSON_QUERY`, `JSON_EXTRACT`, `JSON_OBJECT`, `JSON_ARRAY_LENGTH`, `JSON_VALID`, `JSON_TYPE`
 - Array: `ARRAY_LENGTH`, `ARRAY_POSITION`, `ARRAY_SORT`, `CARDINALITY`
-- Table functions: `UNNEST`
+- Table functions: `UNNEST`, `JSON_EACH`
 - 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`, `GREATEST`, `LEAST`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.12.7",
+  "version": "0.12.8",
   "description": "Squirreling Async SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",

package/src/ast.d.ts

@@ -65,7 +65,7 @@ export interface FromFunction extends AstBase {
   funcName: string
   args: ExprNode[]
   alias?: string
-  columnAlias?: string
+  columnAliases: string[]
 }
 
 export type ArithmeticOp = '+' | '-' | '*' | '/' | '%'

package/src/execute/execute.js

@@ -125,19 +125,31 @@ export function executePlan({ plan, context }) {
 }
 
 /**
- * Executes a table-valued function (e.g. UNNEST).
- * Evaluates the argument once against an empty row and yields one row per
- * element of the resulting array. Null or non-array input yields zero rows.
+ * Executes a table-valued function (e.g. UNNEST, JSON_EACH).
+ * Evaluates the argument once against the outer row (for lateral joins) or an
+ * empty row, then yields rows derived from the resulting value.
  *
  * @param {TableFunctionNode} plan
  * @param {ExecuteContext} context
  * @returns {QueryResults}
  */
 function executeTableFunction(plan, context) {
-  if (plan.funcName !== 'UNNEST') {
-    throw new Error(`Unsupported table function: ${plan.funcName}`)
+  if (plan.funcName === 'UNNEST') {
+    return executeUnnest(plan, context)
+  } else if (plan.funcName === 'JSON_EACH') {
+    return executeJsonEach(plan, context)
   }
-  const columns = [plan.columnName]
+  throw new Error(`Unsupported table function: ${plan.funcName}`)
+}
+
+/**
+ * @param {TableFunctionNode} plan
+ * @param {ExecuteContext} context
+ * @returns {QueryResults}
+ */
+function executeUnnest(plan, context) {
+  const columns = plan.columnNames
+  const [columnName] = columns
   return {
     columns,
     async *rows() {
@@ -149,9 +161,65 @@ function executeTableFunction(plan, context) {
         if (context.signal?.aborted) return
         yield {
           columns,
-          cells: { [plan.columnName]: () => Promise.resolve(element) },
+          cells: { [columnName]: () => Promise.resolve(element) },
+        }
+      }
+    },
+  }
+}
+
+/**
+ * @param {TableFunctionNode} plan
+ * @param {ExecuteContext} context
+ * @returns {QueryResults}
+ */
+function executeJsonEach(plan, context) {
+  const columns = plan.columnNames
+  const [keyCol, valueCol] = columns
+  return {
+    columns,
+    async *rows() {
+      /** @type {AsyncRow} */
+      const row = context.outerRow ?? { columns: [], cells: {} }
+      const value = await evaluateExpr({ node: plan.args[0], row, rowIndex: 1, context })
+      if (value == null) return
+      let parsed = value
+      if (typeof value === 'string') {
+        try {
+          parsed = JSON.parse(value)
+        } catch {
+          throw new Error('JSON_EACH(value): invalid JSON string. Argument must be valid JSON.')
+        }
+      }
+      if (Array.isArray(parsed)) {
+        for (let i = 0; i < parsed.length; i++) {
+          if (context.signal?.aborted) return
+          const k = i
+          const v = parsed[i]
+          yield {
+            columns,
+            cells: {
+              [keyCol]: () => Promise.resolve(k),
+              [valueCol]: () => Promise.resolve(v),
+            },
+          }
+        }
+        return
+      }
+      if (typeof parsed === 'object' && parsed !== null) {
+        for (const [k, v] of Object.entries(parsed)) {
+          if (context.signal?.aborted) return
+          yield {
+            columns,
+            cells: {
+              [keyCol]: () => Promise.resolve(k),
+              [valueCol]: () => Promise.resolve(v),
+            },
+          }
         }
+        return
       }
+      throw new Error('JSON_EACH(value): argument must be a JSON object or array')
     },
   }
 }

package/src/execute/join.js

@@ -95,7 +95,7 @@ export function executeNestedLoopJoin(plan, context) {
 function executeLateralJoin(plan, context) {
   const left = executePlan({ plan: plan.left, context })
   // Right columns are known statically for table functions (the common case).
-  const rightCols = plan.right.type === 'TableFunction' ? [plan.right.columnName] : []
+  const rightCols = plan.right.type === 'TableFunction' ? plan.right.columnNames : []
   return {
     columns: mergeColumnNames(left.columns, rightCols, plan.leftAlias, plan.rightAlias),
     async *rows() {

package/src/expression/evaluate.js

@@ -272,7 +272,7 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
         return values[lower] + (values[upper] - values[lower]) * (pos - lower)
       }
 
-      if (funcName === 'JSON_ARRAYAGG') {
+      if (funcName === 'JSON_ARRAYAGG' || funcName === 'ARRAY_AGG') {
         if (node.distinct) {
           /** @type {SqlPrimitive[]} */
           const values = []
@@ -417,6 +417,40 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       return result
     }
 
+    if (funcName === 'JSON_VALID') {
+      const value = args[0]
+      if (value == null) return null
+      if (typeof value !== 'string') return false
+      try {
+        JSON.parse(value)
+        return true
+      } catch {
+        return false
+      }
+    }
+
+    if (funcName === 'JSON_TYPE') {
+      let value = args[0]
+      if (value == null) return null
+      if (typeof value === 'string') {
+        try {
+          value = JSON.parse(value)
+        } catch {
+          throw new ArgValueError({
+            ...node,
+            message: 'invalid JSON string',
+            hint: 'Argument must be valid JSON.',
+            rowIndex,
+          })
+        }
+      }
+      if (value === null) return 'null'
+      if (Array.isArray(value)) return 'array'
+      if (value instanceof Date) return 'string'
+      if (typeof value === 'bigint') return 'number'
+      return typeof value
+    }
+
     if (funcName === 'JSON_ARRAY_LENGTH') {
       let arr = args[0]
       if (arr == null) return null

package/src/parse/functions.js

@@ -84,6 +84,30 @@ export function parseFunctionCall(state, positionStart) {
     })
   }
 
+  // Check for WITHIN GROUP (ORDER BY expr) clause — standard SQL ordered-set aggregate syntax.
+  // Supported for PERCENTILE_CONT: PERCENTILE_CONT(fraction) WITHIN GROUP (ORDER BY expr)
+  const withinTok = current(state)
+  if (match(state, 'keyword', 'WITHIN')) {
+    if (funcNameUpper !== 'PERCENTILE_CONT') {
+      throw new ParseError({
+        message: `WITHIN GROUP is only supported for PERCENTILE_CONT, not "${funcName}"`,
+        ...withinTok,
+      })
+    }
+    if (args.length !== 1) {
+      throw new ParseError({
+        message: `${funcName}: cannot combine WITHIN GROUP with a value argument`,
+        ...withinTok,
+      })
+    }
+    expect(state, 'keyword', 'GROUP')
+    expect(state, 'paren', '(')
+    expect(state, 'keyword', 'ORDER')
+    expect(state, 'keyword', 'BY')
+    args.push(parseExpression(state))
+    expect(state, 'paren', ')')
+  }
+
   // Validate argument count at parse time
   validateFunctionArgs(funcNameUpper, args.length, positionStart, state.lastPos, state.functions)
 

package/src/parse/parse.js

@@ -468,15 +468,22 @@ export function parseFromFunction(state) {
   validateFunctionArgs(funcName, args.length, positionStart, state.lastPos, state.functions)
 
   const alias = parseTableAlias(state)
-  /** @type {string | undefined} */
-  let columnAlias
+  /** @type {string[]} */
+  const columnAliases = []
   if (alias && match(state, 'paren', '(')) {
     const colStart = state.lastPos
-    const colTok = expect(state, 'identifier')
-    columnAlias = colTok.value
-    if (match(state, 'comma')) {
+    while (true) {
+      const colTok = expect(state, 'identifier')
+      columnAliases.push(colTok.value)
+      if (!match(state, 'comma')) break
+    }
+    const maxCols = tableFunctionColumnCount(funcName)
+    if (columnAliases.length > maxCols) {
+      const colLabels = tableFunctionDefaultColumns(funcName).join(', ')
       throw new ParseError({
-        message: `${funcName} produces a single column; only one column alias is allowed`,
+        message: maxCols === 1
+          ? `${funcName} produces a single column; only one column alias is allowed`
+          : `${funcName} produces at most ${maxCols} columns (${colLabels}); too many column aliases`,
         positionStart: colStart,
         positionEnd: state.lastPos,
       })
@@ -489,12 +496,31 @@ export function parseFromFunction(state) {
     funcName,
     args,
     alias,
-    columnAlias,
+    columnAliases,
     positionStart,
     positionEnd: state.lastPos,
   }
 }
 
+/**
+ * Default column names produced by a table-valued function.
+ * @param {string} funcName
+ * @returns {string[]}
+ */
+export function tableFunctionDefaultColumns(funcName) {
+  if (funcName === 'JSON_EACH') return ['key', 'value']
+  return [funcName.toLowerCase()]
+}
+
+/**
+ * Maximum number of output columns a table-valued function can produce.
+ * @param {string} funcName
+ * @returns {number}
+ */
+export function tableFunctionColumnCount(funcName) {
+  return tableFunctionDefaultColumns(funcName).length
+}
+
 /**
  * Parses an optional table alias (e.g., "FROM users u" or "FROM users AS u")
  * @param {ParserState} state

package/src/plan/columns.js

@@ -1,3 +1,4 @@
+import { tableFunctionDefaultColumns } from '../parse/parse.js'
 import { derivedAlias } from '../expression/alias.js'
 
 /**
@@ -18,13 +19,19 @@ export function fromAlias(from) {
 }
 
 /**
- * Returns the single output column name for a FROM table function.
+ * Returns the output column names for a FROM table function, applying any
+ * column aliases over the function's default column names.
  *
  * @param {FromFunction} from
- * @returns {string}
+ * @returns {string[]}
  */
-export function tableFunctionColumnName(from) {
-  return from.columnAlias ?? from.funcName.toLowerCase()
+export function tableFunctionColumnNames(from) {
+  const defaults = tableFunctionDefaultColumns(from.funcName)
+  const result = []
+  for (let i = 0; i < defaults.length; i++) {
+    result.push(from.columnAliases[i] ?? defaults[i])
+  }
+  return result
 }
 
 /**
@@ -330,18 +337,21 @@ export function inferSelectSourceColumns({ select, cteColumns, tables }) {
   }
 
   if (select.from.type === 'function') {
-    // Table functions currently produce a single column
     if (!select.joins.length) {
-      return [tableFunctionColumnName(select.from)]
+      return tableFunctionColumnNames(select.from)
     }
     /** @type {string[]} */
     const result = []
     const alias = fromAlias(select.from)
-    result.push(`${alias}.${tableFunctionColumnName(select.from)}`)
+    for (const col of tableFunctionColumnNames(select.from)) {
+      result.push(`${alias}.${col}`)
+    }
     for (const join of select.joins) {
       const joinAlias = join.alias ?? join.table
       if (join.fromFunction) {
-        result.push(`${joinAlias}.${tableFunctionColumnName(join.fromFunction)}`)
+        for (const col of tableFunctionColumnNames(join.fromFunction)) {
+          result.push(`${joinAlias}.${col}`)
+        }
       } else {
         for (const col of lookupTableColumns(join.table, cteColumns, tables)) {
           result.push(`${joinAlias}.${col}`)
@@ -365,7 +375,9 @@ export function inferSelectSourceColumns({ select, cteColumns, tables }) {
   for (const join of select.joins) {
     const joinAlias = join.alias ?? join.table
     if (join.fromFunction) {
-      result.push(`${joinAlias}.${tableFunctionColumnName(join.fromFunction)}`)
+      for (const col of tableFunctionColumnNames(join.fromFunction)) {
+        result.push(`${joinAlias}.${col}`)
+      }
     } else {
       for (const col of lookupTableColumns(join.table, cteColumns, tables)) {
         result.push(`${joinAlias}.${col}`)

package/src/plan/plan.js

@@ -3,7 +3,7 @@ import { parseSql } from '../parse/parse.js'
 import { findAggregate } from '../validation/aggregates.js'
 import { ColumnNotFoundError, TableNotFoundError } from '../validation/tables.js'
 import { validateNoIdentifiers, validateScan, validateTableRefs } from '../validation/tables.js'
-import { extractColumns, fromAlias, inferSelectSourceColumns, inferStatementColumns, tableFunctionColumnName } from './columns.js'
+import { extractColumns, fromAlias, inferSelectSourceColumns, inferStatementColumns, tableFunctionColumnNames } from './columns.js'
 
 /**
  * @import { AsyncDataSource, ExprNode, DerivedColumn, IdentifierNode, JoinClause, PlanSqlOptions, ScanOptions, SelectColumn, SelectStatement, SetOperationStatement, Statement } from '../types.js'
@@ -321,7 +321,7 @@ function planTableFunction(from) {
     type: 'TableFunction',
     funcName: from.funcName,
     args: from.args,
-    columnName: tableFunctionColumnName(from),
+    columnNames: tableFunctionColumnNames(from),
   }
 }
 

package/src/plan/types.d.ts

@@ -122,5 +122,5 @@ export interface TableFunctionNode {
   type: 'TableFunction'
   funcName: string
   args: ExprNode[]
-  columnName: string
+  columnNames: string[]
 }

package/src/types.d.ts

@@ -129,7 +129,7 @@ export interface UserDefinedFunction {
   arguments: FunctionSignature
 }
 
-export type AggregateFunc = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'JSON_ARRAYAGG' | 'STDDEV_SAMP' | 'STDDEV_POP' | 'MEDIAN' | 'PERCENTILE_CONT' | 'APPROX_QUANTILE' | 'STRING_AGG'
+export type AggregateFunc = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'ARRAY_AGG' | 'JSON_ARRAYAGG' | 'STDDEV_SAMP' | 'STDDEV_POP' | 'MEDIAN' | 'PERCENTILE_CONT' | 'APPROX_QUANTILE' | 'STRING_AGG'
 
 export type RegExpFunction = 'REGEXP_SUBSTR' | 'REGEXP_EXTRACT' | 'REGEXP_REPLACE' | 'REGEXP_MATCHES'
 

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', 'STRING_AGG'].includes(name)
+  return ['COUNT', 'SUM', 'AVG', 'MIN', 'MAX', 'ARRAY_AGG', 'JSON_ARRAYAGG', 'STDDEV_SAMP', 'STDDEV_POP', 'MEDIAN', 'PERCENTILE_CONT', 'APPROX_QUANTILE', 'STRING_AGG'].includes(name)
 }
 
 /**
@@ -41,7 +41,7 @@ export function isRegexpFunc(name) {
  * @returns {boolean}
  */
 export function isTableFunction(name) {
-  return ['UNNEST'].includes(name)
+  return ['UNNEST', 'JSON_EACH'].includes(name)
 }
 
 /**
@@ -166,7 +166,10 @@ export const FUNCTION_SIGNATURES = {
   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_VALID: { min: 1, max: 1, signature: 'value' },
+  JSON_TYPE: { min: 1, max: 1, signature: 'value' },
   JSON_ARRAYAGG: { min: 1, max: 1, signature: 'expression' },
+  ARRAY_AGG: { min: 1, max: 1, signature: 'expression' },
 
   // Array functions
   ARRAY_LENGTH: { min: 1, max: 1, signature: 'array' },
@@ -176,6 +179,7 @@ export const FUNCTION_SIGNATURES = {
 
   // Table functions (used in FROM clause)
   UNNEST: { min: 1, max: 1, signature: 'array' },
+  JSON_EACH: { min: 1, max: 1, signature: 'value' },
 
   // Conditional functions
   COALESCE: { min: 1, signature: 'value1, value2[, ...]' },

package/src/validation/keywords.js

@@ -4,7 +4,7 @@ export const KEYWORDS = new Set([
   'DISTINCT', 'TRUE', 'FALSE', 'NULL', 'LIKE', 'IN', 'EXISTS', 'BETWEEN',
   'CASE', 'WHEN', 'THEN', 'ELSE', 'END', 'JOIN', 'INNER', 'LEFT', 'RIGHT',
   'FULL', 'OUTER', 'CROSS', 'POSITIONAL', 'LATERAL', 'ON', 'INTERVAL', 'DAY', 'MONTH', 'YEAR',
-  'HOUR', 'MINUTE', 'SECOND', 'FILTER',
+  'HOUR', 'MINUTE', 'SECOND', 'FILTER', 'WITHIN',
   'UNION', 'INTERSECT', 'EXCEPT',
 ])