squirreling 0.4.6 → 0.4.8

package/README.md

@@ -67,3 +67,15 @@ const allUsers: Record<string, SqlPrimitive>[] = await collect(executeSql({
 }))
 console.log(allUsers)
 ```
+
+## Supported SQL Features
+
+- `SELECT` statements with `WHERE`, `ORDER BY`, `LIMIT`, `OFFSET`
+- Subqueries in `SELECT`, `FROM`, and `WHERE` clauses
+- `JOIN` operations: `INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN`, `FULL JOIN`
+- `GROUP BY` and `HAVING` clauses
+- Aggregate functions: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `JSON_ARRAYAGG`
+- String functions: `CONCAT`, `SUBSTRING`, `LENGTH`, `UPPER`, `LOWER`
+- Date functions: `CURRENT_DATE`, `CURRENT_TIME`, `CURRENT_TIMESTAMP`, `INTERVAL`
+- Json functions: `JSON_VALUE`, `JSON_QUERY`, `JSON_OBJECT`
+- Basic expressions and arithmetic operations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Squirreling SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -40,7 +40,7 @@
     "@types/node": "24.10.1",
     "@vitest/coverage-v8": "4.0.15",
     "eslint": "9.39.1",
-    "eslint-plugin-jsdoc": "61.4.1",
+    "eslint-plugin-jsdoc": "61.4.2",
     "typescript": "5.9.3",
     "vitest": "4.0.15"
   }

package/src/errors.js

@@ -0,0 +1,230 @@
+// ============================================================================
+// PARSE ERRORS - Issues during SQL tokenization and parsing
+// ============================================================================
+
+/**
+ * General syntax error for unexpected tokens.
+ *
+ * @param {Object} options
+ * @param {string} options.expected - Description of what was expected
+ * @param {string} options.received - What was actually found
+ * @param {number} options.position - Character position in query
+ * @param {string} [options.after] - What token came before (for context)
+ * @returns {Error}
+ */
+export function syntaxError({ expected, received, position, after }) {
+  const afterClause = after ? ` after "${after}"` : ''
+  return new Error(`Expected ${expected}${afterClause} but found ${received} at position ${position}`)
+}
+
+/**
+ * Error for unterminated literals (strings, identifiers).
+ *
+ * @param {'string' | 'identifier'} type - Type of unterminated literal
+ * @param {number} position - Starting position
+ * @returns {Error}
+ */
+export function unterminatedError(type, position) {
+  const name = type === 'string' ? 'string literal' : 'identifier'
+  return new Error(`Unterminated ${name} starting at position ${position}`)
+}
+
+/**
+ * Error for invalid literals (numbers, intervals, etc).
+ *
+ * @param {Object} options
+ * @param {string} options.type - Type of invalid literal (e.g., 'number', 'interval value', 'interval unit')
+ * @param {string} options.value - The invalid value
+ * @param {number} options.position - Position in query
+ * @param {string} [options.validValues] - List of valid values (for enums like interval units)
+ * @returns {Error}
+ */
+export function invalidLiteralError({ type, value, position, validValues }) {
+  const suffix = validValues ? `. Valid values: ${validValues}` : ''
+  return new Error(`Invalid ${type} ${value} at position ${position}${suffix}`)
+}
+
+/**
+ * Error for unexpected characters during tokenization.
+ *
+ * @param {string} char - The unexpected character
+ * @param {number} position - Position in query
+ * @param {boolean} [expectsSelect=false] - Whether SELECT was expected (first token)
+ * @returns {Error}
+ */
+export function unexpectedCharError(char, position, expectsSelect = false) {
+  if (expectsSelect) {
+    return new Error(`Expected SELECT but found "${char}" at position ${position}. Queries must start with SELECT.`)
+  }
+  return new Error(`Unexpected character "${char}" at position ${position}`)
+}
+
+/**
+ * Error for unknown/unsupported functions.
+ *
+ * @param {string} funcName - The unknown function name
+ * @param {number} [position] - Position in query (for parse errors)
+ * @param {string} [validFunctions] - List of valid functions
+ * @returns {Error}
+ */
+export function unknownFunctionError(funcName, position, validFunctions) {
+  const supported = validFunctions ||
+    'COUNT, SUM, AVG, MIN, MAX, UPPER, LOWER, CONCAT, LENGTH, SUBSTRING, TRIM, REPLACE, JSON_OBJECT, JSON_VALUE, JSON_QUERY, JSON_ARRAYAGG'
+
+  if (position !== undefined) {
+    return new Error(`Unknown function "${funcName}" at position ${position}. Supported: ${supported}`)
+  }
+  return new Error(`Unsupported function: ${funcName}. Supported: ${supported}`)
+}
+
+/**
+ * Error for missing required clause or structure.
+ *
+ * @param {Object} options
+ * @param {string} options.missing - What is missing (e.g., 'WHEN clause', 'FROM clause', 'ON condition')
+ * @param {string} options.context - Where it's missing from (e.g., 'CASE expression', 'SELECT statement', 'JOIN')
+ * @returns {Error}
+ */
+export function missingClauseError({ missing, context }) {
+  return new Error(`${context} requires ${missing}`)
+}
+
+// ============================================================================
+// EXECUTION ERRORS - Issues during query execution
+// ============================================================================
+
+/**
+ * Error for missing table.
+ *
+ * @param {string} tableName - The missing table name
+ * @returns {Error}
+ */
+export function tableNotFoundError(tableName) {
+  return new Error(`Table "${tableName}" not found. Check spelling or add it to the tables parameter.`)
+}
+
+/**
+ * Error for invalid context (e.g., INTERVAL without date arithmetic).
+ *
+ * @param {Object} options
+ * @param {string} options.item - What was used incorrectly
+ * @param {string} options.validContext - Where it can be used
+ * @returns {Error}
+ */
+export function invalidContextError({ item, validContext }) {
+  return new Error(`${item} can only be used with ${validContext}`)
+}
+
+/**
+ * Error for unsupported operation combinations.
+ *
+ * @param {string} operation - The unsupported operation
+ * @param {string} [hint] - How to fix it
+ * @returns {Error}
+ */
+export function unsupportedOperationError(operation, hint) {
+  const suffix = hint ? `. ${hint}` : ''
+  return new Error(`${operation}${suffix}`)
+}
+
+// ============================================================================
+// VALIDATION ERRORS - Function argument and type validation
+// ============================================================================
+
+/**
+ * Function signatures for helpful error messages.
+ * Maps function name to its parameter signature.
+ * @type {Record<string, string>}
+ */
+const FUNCTION_SIGNATURES = {
+  // String functions
+  UPPER: 'string',
+  LOWER: 'string',
+  LENGTH: 'string',
+  TRIM: 'string',
+  REPLACE: 'string, search, replacement',
+  SUBSTRING: 'string, start[, length]',
+  SUBSTR: 'string, start[, length]',
+  CONCAT: 'value1, value2[, ...]',
+
+  // Date/time functions
+  RANDOM: '',
+  RAND: '',
+  CURRENT_DATE: '',
+  CURRENT_TIME: '',
+  CURRENT_TIMESTAMP: '',
+
+  // JSON functions
+  JSON_VALUE: 'expression, path',
+  JSON_QUERY: 'expression, path',
+  JSON_OBJECT: 'key1, value1[, ...]',
+  JSON_ARRAYAGG: 'expression',
+
+  // Aggregate functions
+  COUNT: 'expression',
+  SUM: 'expression',
+  AVG: 'expression',
+  MIN: 'expression',
+  MAX: 'expression',
+}
+
+/**
+ * Error for wrong number of function arguments.
+ *
+ * @param {string} funcName - The function name
+ * @param {number | string} expected - Expected count (number or range like "2 or 3")
+ * @param {number} received - Actual argument count
+ * @returns {Error}
+ */
+export function argCountError(funcName, expected, received) {
+  const signature = FUNCTION_SIGNATURES[funcName] ?? ''
+  let expectedStr = `${expected} arguments`
+  if (expected === 0) expectedStr = 'no arguments'
+  if (expected === 1) expectedStr = '1 argument'
+  if (typeof expected === 'string' && expected.endsWith(' 1')) {
+    expectedStr = `${expected} argument`
+  }
+
+  return new Error(`${funcName}(${signature}) function requires ${expectedStr}, got ${received}`)
+}
+
+/**
+ * Error for invalid argument type or value.
+ *
+ * @param {Object} options
+ * @param {string} options.funcName - The function name
+ * @param {string} options.message - Specific error message
+ * @param {string} [options.hint] - Recovery hint
+ * @returns {Error}
+ */
+export function argValueError({ funcName, message, hint }) {
+  const signature = FUNCTION_SIGNATURES[funcName] ?? ''
+  const suffix = hint ? `. ${hint}` : ''
+  return new Error(`${funcName}(${signature}): ${message}${suffix}`)
+}
+
+/**
+ * Error for aggregate function misuse (e.g., SUM(*)).
+ *
+ * @param {string} funcName - The aggregate function
+ * @param {string} issue - What's wrong (e.g., "(*) is not supported")
+ * @returns {Error}
+ */
+export function aggregateError(funcName, issue) {
+  return new Error(`${funcName}${issue}. Only COUNT supports *. Use a column name for ${funcName}.`)
+}
+
+/**
+ * Error for unsupported CAST type.
+ *
+ * @param {string} toType - The unsupported target type
+ * @param {string} [fromType] - The source type (optional)
+ * @returns {Error}
+ */
+export function castError(toType, fromType) {
+  const message = fromType
+    ? `Cannot CAST ${fromType} to ${toType}`
+    : `Unsupported CAST to type ${toType}`
+
+  return new Error(`${message}. Supported types: TEXT, VARCHAR, INTEGER, INT, BIGINT, FLOAT, REAL, DOUBLE, BOOLEAN`)
+}

package/src/execute/aggregates.js

@@ -1,15 +1,16 @@
+import { aggregateError, unknownFunctionError } from '../errors.js'
 import { evaluateExpr } from './expression.js'
-import { defaultDerivedAlias } from './utils.js'
+import { defaultDerivedAlias, stringify } from './utils.js'
 
 /**
  * Evaluates an aggregate function over a set of rows
  *
- * @import { AggregateColumn, AsyncDataSource, ExprNode, AsyncRow } from '../types.js'
+ * @import { AggregateColumn, AsyncDataSource, AsyncRow, SqlPrimitive } from '../types.js'
  * @param {Object} options
  * @param {AggregateColumn} options.col - aggregate column definition
  * @param {AsyncRow[]} options.rows - rows to aggregate
  * @param {Record<string, AsyncDataSource>} options.tables
- * @returns {Promise<number | null>} aggregated result
+ * @returns {Promise<SqlPrimitive>} aggregated result
  */
 export async function evaluateAggregate({ col, rows, tables }) {
   const { arg, func } = col
@@ -20,7 +21,7 @@ export async function evaluateAggregate({ col, rows, tables }) {
       const seen = new Set()
       for (const row of rows) {
         const v = await evaluateExpr({ node: arg.expr, row, tables })
-        if (v !== null && v !== undefined) {
+        if (v != null) {
           seen.add(v)
         }
       }
@@ -29,7 +30,7 @@ export async function evaluateAggregate({ col, rows, tables }) {
     let count = 0
     for (const row of rows) {
       const v = await evaluateExpr({ node: arg.expr, row, tables })
-      if (v !== null && v !== undefined) {
+      if (v != null) {
         count += 1
       }
     }
@@ -38,7 +39,7 @@ export async function evaluateAggregate({ col, rows, tables }) {
 
   if (func === 'SUM' || func === 'AVG' || func === 'MIN' || func === 'MAX') {
     if (arg.kind === 'star') {
-      throw new Error(func + '(*) is not supported, use a column name')
+      throw aggregateError(func, '(*) is not supported, use a column name')
     }
     let sum = 0
     let count = 0
@@ -70,7 +71,32 @@ export async function evaluateAggregate({ col, rows, tables }) {
     if (func === 'MAX') return max
   }
 
-  throw new Error('Unsupported aggregate function ' + func)
+  if (func === 'JSON_ARRAYAGG') {
+    if (arg.kind === 'star') {
+      throw aggregateError('JSON_ARRAYAGG', '(*) is not supported, use a column name or expression')
+    }
+    /** @type {SqlPrimitive[]} */
+    const values = []
+    if (arg.quantifier === 'distinct') {
+      const seen = new Set()
+      for (const row of rows) {
+        const v = await evaluateExpr({ node: arg.expr, row, tables })
+        const key = stringify(v)
+        if (!seen.has(key)) {
+          seen.add(key)
+          values.push(v)
+        }
+      }
+    } else {
+      for (const row of rows) {
+        const v = await evaluateExpr({ node: arg.expr, row, tables })
+        values.push(v)
+      }
+    }
+    return values
+  }
+
+  throw unknownFunctionError(func, undefined, 'COUNT, SUM, AVG, MIN, MAX, JSON_ARRAYAGG')
 }
 
 /**

package/src/execute/date.js

@@ -0,0 +1,57 @@
+/**
+ * @import { SqlPrimitive, IntervalUnit } from '../types.js'
+ */
+
+/**
+ * @param {SqlPrimitive} val
+ * @returns {Date | null}
+ */
+function toDate(val) {
+  if (val instanceof Date) return val
+  const dateOrTime = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2})?/
+  if (typeof val === 'string' && dateOrTime.test(val)) {
+    const date = new Date(val)
+    if (!isNaN(date.getTime())) {
+      return date
+    }
+  }
+  return null
+}
+
+/**
+ * Apply an interval to a date
+ * @param {SqlPrimitive} dateVal
+ * @param {number} value
+ * @param {IntervalUnit} unit
+ * @param {'+' | '-'} op
+ * @returns {string | null}
+ */
+export function applyIntervalToDate(dateVal, value, unit, op) {
+  const date = toDate(dateVal)
+  if (date == null) return null
+
+  const multiplier = op === '+' ? 1 : -1
+  const adjusted = value * multiplier
+
+  if (unit === 'SECOND') {
+    date.setUTCSeconds(date.getUTCSeconds() + adjusted)
+  } else if (unit === 'MINUTE') {
+    date.setUTCMinutes(date.getUTCMinutes() + adjusted)
+  } else if (unit === 'HOUR') {
+    date.setUTCHours(date.getUTCHours() + adjusted)
+  } else if (unit === 'DAY') {
+    date.setUTCDate(date.getUTCDate() + adjusted)
+  } else if (unit === 'MONTH') {
+    date.setUTCMonth(date.getUTCMonth() + adjusted)
+  } else if (unit === 'YEAR') {
+    date.setUTCFullYear(date.getUTCFullYear() + adjusted)
+  }
+
+  // Return in same format as input
+  if (dateVal instanceof Date) return date.toISOString()
+  if (String(dateVal).includes('T')) {
+    return date.toISOString()
+  } else {
+    return date.toISOString().split('T')[0]
+  }
+}

package/src/execute/execute.js

@@ -1,14 +1,15 @@
+import { missingClauseError, tableNotFoundError, unsupportedOperationError } from '../errors.js'
 import { generatorSource, memorySource } from '../backend/dataSource.js'
 import { parseSql } from '../parse/parse.js'
 import { defaultAggregateAlias, evaluateAggregate } from './aggregates.js'
+import { extractColumns } from './columns.js'
 import { evaluateExpr } from './expression.js'
 import { evaluateHavingExpr } from './having.js'
 import { executeJoins } from './join.js'
-import { compareForTerm, defaultDerivedAlias } from './utils.js'
-import { extractColumns } from './columns.js'
+import { compareForTerm, defaultDerivedAlias, stringify } from './utils.js'
 
 /**
- * @import { AsyncDataSource, AsyncRow, ExecuteSqlOptions, ExprNode, OrderByItem, QueryHints, SelectStatement, SqlPrimitive } from '../types.js'
+ * @import { AsyncDataSource, AsyncRow, ExecuteSqlOptions, OrderByItem, QueryHints, SelectStatement, SqlPrimitive } from '../types.js'
  */
 
 /**
@@ -22,7 +23,10 @@ export async function* executeSql({ tables, query }) {
 
   // Check for unsupported operations
   if (!select.from) {
-    throw new Error('FROM clause is required')
+    throw missingClauseError({
+      missing: 'FROM clause',
+      context: 'SELECT statement',
+    })
   }
 
   // Normalize tables: convert arrays to AsyncDataSource
@@ -57,7 +61,7 @@ export async function* executeSelect(select, tables) {
     fromTableName = select.from.alias ?? select.from.table
     dataSource = tables[select.from.table]
     if (dataSource === undefined) {
-      throw new Error(`Table "${select.from.table}" not found`)
+      throw tableNotFoundError(select.from.table)
     }
   } else {
     // Nested subquery - recursively resolve
@@ -85,7 +89,7 @@ async function stableRowKey(row) {
   const parts = []
   for (const k of keys) {
     const v = await row[k]()
-    parts.push(k + ':' + JSON.stringify(v))
+    parts.push(k + ':' + stringify(v))
   }
   return parts.join('|')
 }
@@ -358,7 +362,7 @@ async function* evaluateBuffered(select, dataSource, tables, hasAggregate, useGr
         const keyParts = []
         for (const expr of select.groupBy) {
           const v = await evaluateExpr({ node: expr, row, tables })
-          keyParts.push(JSON.stringify(v))
+          keyParts.push(stringify(v))
         }
         const key = keyParts.join('|')
         let group = map.get(key)
@@ -375,7 +379,10 @@ async function* evaluateBuffered(select, dataSource, tables, hasAggregate, useGr
 
     const hasStar = select.columns.some(col => col.kind === 'star')
     if (hasStar && hasAggregate) {
-      throw new Error('SELECT * with aggregate functions is not supported in this implementation')
+      throw unsupportedOperationError(
+        'SELECT * with aggregate functions is not supported',
+        'Replace * with specific column names when using aggregate functions.'
+      )
     }
 
     for (const group of groups) {