squirreling 0.4.7 → 0.4.8

package/README.md

@@ -76,5 +76,6 @@ console.log(allUsers)
 - `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.7",
+  "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,3 +1,4 @@
+import { aggregateError, unknownFunctionError } from '../errors.js'
 import { evaluateExpr } from './expression.js'
 import { defaultDerivedAlias, stringify } from './utils.js'
 
@@ -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
@@ -72,7 +73,7 @@ export async function evaluateAggregate({ col, rows, tables }) {
 
   if (func === 'JSON_ARRAYAGG') {
     if (arg.kind === 'star') {
-      throw new Error('JSON_ARRAYAGG(*) is not supported, use a column name or expression')
+      throw aggregateError('JSON_ARRAYAGG', '(*) is not supported, use a column name or expression')
     }
     /** @type {SqlPrimitive[]} */
     const values = []
@@ -95,7 +96,7 @@ export async function evaluateAggregate({ col, rows, tables }) {
     return values
   }
 
-  throw new Error('Unsupported aggregate function ' + func)
+  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,3 +1,4 @@
+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'
@@ -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
@@ -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) {

package/src/execute/expression.js

@@ -1,8 +1,16 @@
+import {
+  argCountError,
+  argValueError,
+  castError,
+  invalidContextError,
+  unknownFunctionError,
+} from '../errors.js'
+import { applyIntervalToDate } from './date.js'
 import { executeSelect } from './execute.js'
 import { applyBinaryOp, stringify } from './utils.js'
 
 /**
- * @import { ExprNode, AsyncRow, SqlPrimitive, AsyncDataSource } from '../types.js'
+ * @import { ExprNode, AsyncRow, SqlPrimitive, AsyncDataSource, IntervalUnit } from '../types.js'
  */
 
 /**
@@ -31,7 +39,7 @@ export async function evaluateExpr({ node, row, tables }) {
         return row[colName]()
       }
     }
-    return undefined
+    return null
   }
 
   // Scalar subquery - returns a single value
@@ -66,6 +74,16 @@ export async function evaluateExpr({ node, row, tables }) {
 
   // Binary operators
   if (node.type === 'binary') {
+    // Handle date +/- interval at AST level
+    if ((node.op === '+' || node.op === '-') && node.right.type === 'interval') {
+      const dateVal = await evaluateExpr({ node: node.left, row, tables })
+      return applyIntervalToDate(dateVal, node.right.value, node.right.unit, node.op)
+    }
+    if (node.op === '+' && node.left.type === 'interval') {
+      const dateVal = await evaluateExpr({ node: node.right, row, tables })
+      return applyIntervalToDate(dateVal, node.left.value, node.left.unit, '+')
+    }
+
     const left = await evaluateExpr({ node: node.left, row, tables })
 
     // Short-circuit evaluation for AND and OR
@@ -87,31 +105,35 @@ export async function evaluateExpr({ node, row, tables }) {
     const args = await Promise.all(node.args.map(arg => evaluateExpr({ node: arg, row, tables })))
 
     if (funcName === 'UPPER') {
-      if (args.length !== 1) throw new Error('UPPER requires exactly 1 argument')
+      if (args.length !== 1) throw argCountError('UPPER', 1, args.length)
       const val = args[0]
       if (val == null) return null
       return String(val).toUpperCase()
     }
 
     if (funcName === 'LOWER') {
-      if (args.length !== 1) throw new Error('LOWER requires exactly 1 argument')
+      if (args.length !== 1) throw argCountError('LOWER', 1, args.length)
       const val = args[0]
       if (val == null) return null
       return String(val).toLowerCase()
     }
 
     if (funcName === 'CONCAT') {
-      if (args.length < 1) throw new Error('CONCAT requires at least 1 argument')
+      if (args.length < 1) throw argCountError('CONCAT', 'at least 1', args.length)
       // SQL CONCAT returns NULL if any argument is NULL
       if (args.some(a => a == null)) return null
       if (args.some(a => typeof a === 'object')) {
-        throw new Error('CONCAT does not support object arguments')
+        throw argValueError({
+          funcName: 'CONCAT',
+          message: 'does not support object arguments',
+          hint: 'Use CAST to convert objects to strings first.',
+        })
       }
       return args.map(a => String(a)).join('')
     }
 
     if (funcName === 'LENGTH') {
-      if (args.length !== 1) throw new Error('LENGTH requires exactly 1 argument')
+      if (args.length !== 1) throw argCountError('LENGTH', 1, args.length)
       const val = args[0]
       if (val == null) return null
       return String(val).length
@@ -119,21 +141,28 @@ export async function evaluateExpr({ node, row, tables }) {
 
     if (funcName === 'SUBSTRING' || funcName === 'SUBSTR') {
       if (args.length < 2 || args.length > 3) {
-        throw new Error(`${funcName} requires 2 or 3 arguments`)
+        throw argCountError(funcName, '2 or 3', args.length)
       }
       const str = args[0]
       if (str == null) return null
       const strVal = String(str)
       const start = Number(args[1])
       if (!Number.isInteger(start) || start < 1) {
-        throw new Error(`${funcName} start position must be a positive integer`)
+        throw argValueError({
+          funcName,
+          message: `start position must be a positive integer, got ${args[1]}`,
+          hint: 'SQL uses 1-based indexing.',
+        })
       }
       // SQL uses 1-based indexing
       const startIdx = start - 1
       if (args.length === 3) {
         const len = Number(args[2])
         if (!Number.isInteger(len) || len < 0) {
-          throw new Error(`${funcName} length must be a non-negative integer`)
+          throw argValueError({
+            funcName,
+            message: `length must be a non-negative integer, got ${args[2]}`,
+          })
         }
         return strVal.substring(startIdx, startIdx + len)
       }
@@ -141,14 +170,14 @@ export async function evaluateExpr({ node, row, tables }) {
     }
 
     if (funcName === 'TRIM') {
-      if (args.length !== 1) throw new Error('TRIM requires exactly 1 argument')
+      if (args.length !== 1) throw argCountError('TRIM', 1, args.length)
       const val = args[0]
       if (val == null) return null
       return String(val).trim()
     }
 
     if (funcName === 'REPLACE') {
-      if (args.length !== 3) throw new Error('REPLACE requires exactly 3 arguments')
+      if (args.length !== 3) throw argCountError('REPLACE', 3, args.length)
       const str = args[0]
       const searchStr = args[1]
       const replaceStr = args[2]
@@ -158,13 +187,28 @@ export async function evaluateExpr({ node, row, tables }) {
     }
 
     if (funcName === 'RANDOM' || funcName === 'RAND') {
-      if (args.length !== 0) throw new Error(`${funcName} takes no arguments`)
+      if (args.length !== 0) throw argCountError(funcName, 0, args.length)
       return Math.random()
     }
 
+    if (funcName === 'CURRENT_DATE') {
+      if (args.length !== 0) throw argCountError('CURRENT_DATE', 0, args.length)
+      return new Date().toISOString().split('T')[0]
+    }
+
+    if (funcName === 'CURRENT_TIME') {
+      if (args.length !== 0) throw argCountError('CURRENT_TIME', 0, args.length)
+      return new Date().toISOString().split('T')[1].replace('Z', '')
+    }
+
+    if (funcName === 'CURRENT_TIMESTAMP') {
+      if (args.length !== 0) throw argCountError('CURRENT_TIMESTAMP', 0, args.length)
+      return new Date().toISOString()
+    }
+
     if (funcName === 'JSON_OBJECT') {
       if (args.length % 2 !== 0) {
-        throw new Error('JSON_OBJECT requires an even number of arguments (key-value pairs)')
+        throw argCountError('JSON_OBJECT', 'even number', args.length)
       }
       /** @type {Record<string, SqlPrimitive>} */
       const result = {}
@@ -172,7 +216,11 @@ export async function evaluateExpr({ node, row, tables }) {
         const key = args[i]
         const value = args[i + 1]
         if (key == null) {
-          throw new Error('JSON_OBJECT: key cannot be null')
+          throw argValueError({
+            funcName: 'JSON_OBJECT',
+            message: 'key cannot be null',
+            hint: 'All keys must be non-null values.',
+          })
         }
         result[String(key)] = value
       }
@@ -180,7 +228,7 @@ export async function evaluateExpr({ node, row, tables }) {
     }
 
     if (funcName === 'JSON_VALUE' || funcName === 'JSON_QUERY') {
-      if (args.length !== 2) throw new Error(`${funcName} requires exactly 2 arguments`)
+      if (args.length !== 2) throw argCountError(funcName, 2, args.length)
       let jsonArg = args[0]
       const pathArg = args[1]
       if (jsonArg == null || pathArg == null) return null
@@ -190,11 +238,18 @@ export async function evaluateExpr({ node, row, tables }) {
         try {
           jsonArg = JSON.parse(jsonArg)
         } catch {
-          throw new Error(`${funcName}: invalid JSON string`)
+          throw argValueError({
+            funcName,
+            message: 'invalid JSON string',
+            hint: 'First argument must be valid JSON.',
+          })
         }
       }
-      if (typeof jsonArg !== 'object') {
-        throw new Error(`${funcName}: first argument must be JSON string or object`)
+      if (typeof jsonArg !== 'object' || jsonArg instanceof Date) {
+        throw argValueError({
+          funcName,
+          message: `first argument must be JSON string or object, got ${typeof jsonArg}`,
+        })
       }
 
       // Parse path ("$.foo.bar[0].baz" or "foo.bar[0]")
@@ -223,7 +278,7 @@ export async function evaluateExpr({ node, row, tables }) {
       return current
     }
 
-    throw new Error('Unsupported function ' + funcName)
+    throw unknownFunctionError(funcName)
   }
 
   if (node.type === 'cast') {
@@ -235,7 +290,7 @@ export async function evaluateExpr({ node, row, tables }) {
       return String(val)
     }
     // Can only cast primitives to other primitive types
-    if (typeof val === 'object') throw new Error(`Cannot CAST object to type ${node.toType}`)
+    if (typeof val === 'object') throw castError(node.toType, 'object')
     if (toType === 'INTEGER' || toType === 'INT') {
       const num = Number(val)
       if (isNaN(num)) return null
@@ -252,7 +307,7 @@ export async function evaluateExpr({ node, row, tables }) {
     if (toType === 'BOOLEAN' || toType === 'BOOL') {
       return Boolean(val)
     }
-    throw new Error('Unsupported CAST to type ' + node.toType)
+    throw castError(node.toType)
   }
 
   // IN and NOT IN with value lists
@@ -317,5 +372,14 @@ export async function evaluateExpr({ node, row, tables }) {
     return null
   }
 
-  throw new Error('Unknown expression node type ' + node.type)
+  // INTERVAL expressions should only appear as part of binary +/- operations
+  // which are handled above. A standalone interval is an error.
+  if (node.type === 'interval') {
+    throw invalidContextError({
+      item: 'INTERVAL',
+      validContext: 'date arithmetic (+ or -)',
+    })
+  }
+
+  throw new Error(`Unknown expression node type: ${node.type}. This is an internal error - the query may contain unsupported syntax.`)
 }

package/src/execute/having.js

@@ -1,3 +1,4 @@
+import { unknownFunctionError } from '../errors.js'
 import { isAggregateFunc } from '../validation.js'
 import { evaluateExpr } from './expression.js'
 import { applyBinaryOp } from './utils.js'
@@ -152,5 +153,5 @@ async function evaluateAggregateFunction(funcName, args, group, tables) {
     return max
   }
 
-  throw new Error('Unsupported aggregate function: ' + funcName)
+  throw unknownFunctionError(funcName, undefined, 'COUNT, SUM, AVG, MIN, MAX')
 }

package/src/execute/join.js

@@ -1,3 +1,4 @@
+import { missingClauseError, tableNotFoundError } from '../errors.js'
 import { evaluateExpr } from './expression.js'
 import { stringify } from './utils.js'
 
@@ -22,7 +23,7 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
     const join = joins[0]
     const rightSource = tables[join.table]
     if (rightSource === undefined) {
-      throw new Error(`Table "${join.table}" not found`)
+      throw tableNotFoundError(join.table)
     }
 
     // Buffer right rows for hash index (required for hash join)
@@ -62,7 +63,7 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
     const join = joins[i]
     const rightSource = tables[join.table]
     if (rightSource === undefined) {
-      throw new Error(`Table "${join.table}" not found`)
+      throw tableNotFoundError(join.table)
     }
 
     /** @type {AsyncRow[]} */
@@ -98,7 +99,7 @@ export async function executeJoins(leftSource, joins, leftTableName, tables) {
   const lastJoin = joins[joins.length - 1]
   const rightSource = tables[lastJoin.table]
   if (rightSource === undefined) {
-    throw new Error(`Table "${lastJoin.table}" not found`)
+    throw tableNotFoundError(lastJoin.table)
   }
 
   /** @type {AsyncRow[]} */
@@ -234,7 +235,10 @@ async function* hashJoin({ leftRows, rightRows, join, leftTable, rightTable, tab
   const { joinType, on: onCondition } = join
 
   if (!onCondition) {
-    throw new Error('JOIN requires ON condition')
+    throw missingClauseError({
+      missing: 'ON condition',
+      context: 'JOIN',
+    })
   }
 
   const keys = extractJoinKeys(onCondition, leftTable, rightTable)

package/src/execute/utils.js

@@ -134,6 +134,9 @@ export function defaultDerivedAlias(expr) {
   if (expr.type === 'function') {
     return expr.name.toLowerCase() + '_' + expr.args.map(defaultDerivedAlias).join('_')
   }
+  if (expr.type === 'interval') {
+    return `interval_${expr.value}_${expr.unit.toLowerCase()}`
+  }
   return 'expr'
 }
 

package/src/parse/comparison.js

@@ -1,3 +1,4 @@
+import { syntaxError } from '../errors.js'
 import { isBinaryOp } from '../validation.js'
 import { parseAdditive, parseExpression, parseSubquery } from './expression.js'
 import { consume, current, expect, match, peekToken } from './state.js'
@@ -110,7 +111,7 @@ export function parseComparison(state) {
       // parseSubquery expects to consume the opening paren itself
       const parenTok = current(state)
       if (parenTok.type !== 'paren' || parenTok.value !== '(') {
-        throw new Error('Expected ( after IN')
+        throw syntaxError({ expected: '(', received: `"${parenTok.value}"`, position: parenTok.position, after: 'IN' })
       }
       const peekTok = peekToken(state, 1)
       if (peekTok.type === 'keyword' && peekTok.value === 'SELECT') {
@@ -155,7 +156,7 @@ export function parseComparison(state) {
     // parseSubquery expects to consume the opening paren itself
     const parenTok = current(state)
     if (parenTok.type !== 'paren' || parenTok.value !== '(') {
-      throw new Error('Expected ( after IN')
+      throw syntaxError({ expected: '(', received: `"${parenTok.value}"`, position: parenTok.position, after: 'IN' })
     }
     const peekTok = peekToken(state, 1)
     if (peekTok.type === 'keyword' && peekTok.value === 'SELECT') {

package/src/parse/expression.js

@@ -1,12 +1,66 @@
-import { isAggregateFunc, isStringFunc } from '../validation.js'
+import {
+  invalidLiteralError,
+  missingClauseError,
+  syntaxError,
+  unknownFunctionError,
+} from '../errors.js'
+import { isAggregateFunc, isIntervalUnit, isStringFunc } from '../validation.js'
 import { parseComparison } from './comparison.js'
 import { parseSelectInternal } from './parse.js'
 import { consume, current, expect, expectIdentifier, match, peekToken } from './state.js'
 
 /**
- * @import { ExprNode, ParserState, SelectStatement, WhenClause } from '../types.js'
+ * @import { ExprNode, IntervalNode, ParserState, SelectStatement, WhenClause } from '../types.js'
  */
 
+/**
+ * @param {ParserState} state
+ * @returns {IntervalNode}
+ */
+function parseInterval(state) {
+  consume(state) // INTERVAL
+
+  // Handle optional negative sign
+  let sign = 1
+  const signTok = current(state)
+  if (signTok.type === 'operator' && signTok.value === '-') {
+    consume(state)
+    sign = -1
+  }
+
+  // Get value (number or quoted string)
+  const valueTok = current(state)
+  /** @type {number} */
+  let value
+  if (valueTok.type === 'number') {
+    consume(state)
+    value = sign * Number(valueTok.numericValue)
+  } else if (valueTok.type === 'string') {
+    consume(state)
+    const parsed = parseFloat(valueTok.value)
+    if (isNaN(parsed)) {
+      throw invalidLiteralError({ type: 'interval value', value: valueTok.value, position: valueTok.position })
+    }
+    value = sign * parsed
+  } else {
+    throw syntaxError({ expected: 'interval value (number)', received: `"${valueTok.value}"`, position: valueTok.position })
+  }
+
+  // Get unit keyword
+  const unitTok = current(state)
+  if (unitTok.type !== 'keyword' || !isIntervalUnit(unitTok.value)) {
+    throw invalidLiteralError({
+      type: 'interval unit',
+      value: unitTok.value,
+      position: unitTok.position,
+      validValues: 'DAY, MONTH, YEAR, HOUR, MINUTE, SECOND',
+    })
+  }
+  consume(state)
+
+  return { type: 'interval', value, unit: unitTok.value }
+}
+
 /**
  * @param {ParserState} state
  * @returns {ExprNode}
@@ -64,7 +118,7 @@ export function parsePrimary(state) {
 
       // validate function names
       if (!isStringFunc(funcName) && !isAggregateFunc(funcName)) {
-        throw new Error(`Unknown function "${funcName}" at position ${tok.position}`)
+        throw unknownFunctionError(funcName, tok.position)
       }
 
       consume(state) // function name
@@ -99,6 +153,17 @@ export function parsePrimary(state) {
       }
     }
 
+    // Niladic datetime functions (no parentheses required per ANSI SQL)
+    const niladicFuncs = ['CURRENT_DATE', 'CURRENT_TIME', 'CURRENT_TIMESTAMP']
+    if (niladicFuncs.includes(tok.value)) {
+      consume(state)
+      return {
+        type: 'function',
+        name: tok.value,
+        args: [],
+      }
+    }
+
     consume(state)
     let name = tok.value
 
@@ -175,7 +240,10 @@ export function parsePrimary(state) {
       }
 
       if (whenClauses.length === 0) {
-        throw new Error('CASE expression must have at least one WHEN clause')
+        throw missingClauseError({
+          missing: 'at least one WHEN clause',
+          context: 'CASE expression',
+        })
       }
 
       // Parse optional ELSE clause
@@ -194,6 +262,9 @@ export function parsePrimary(state) {
         elseResult,
       }
     }
+    if (tok.value === 'INTERVAL') {
+      return parseInterval(state)
+    }
   }
 
   if (tok.type === 'operator' && tok.value === '-') {
@@ -207,7 +278,7 @@ export function parsePrimary(state) {
   }
 
   const found = tok.type === 'eof' ? 'end of query' : `"${tok.originalValue ?? tok.value}"`
-  throw new Error(`Expected expression but found ${found} at position ${tok.position}`)
+  throw syntaxError({ expected: 'expression', received: found, position: tok.position })
 }
 
 /**

package/src/parse/parse.js

@@ -63,6 +63,11 @@ function parseSelectList(state) {
   return cols
 }
 
+// Keywords that can start a valid expression in SELECT
+const EXPRESSION_START_KEYWORDS = new Set([
+  'CASE', 'TRUE', 'FALSE', 'NULL', 'EXISTS', 'NOT', 'INTERVAL',
+])
+
 /**
  * @param {ParserState} state
  * @returns {SelectColumn}
@@ -70,7 +75,7 @@ function parseSelectList(state) {
 function parseSelectItem(state) {
   const tok = current(state)
 
-  if (tok.type === 'keyword' && tok.value !== 'CASE' || tok.type === 'eof') {
+  if (tok.type === 'keyword' && !EXPRESSION_START_KEYWORDS.has(tok.value) || tok.type === 'eof') {
     throw parseError(state, 'column name or expression')
   }
 

package/src/parse/state.js

@@ -1,3 +1,5 @@
+import { syntaxError } from '../errors.js'
+
 /**
  * @import { ParserState, Token, TokenType } from '../types.js'
  */
@@ -86,7 +88,7 @@ export function expectIdentifier(state) {
 export function parseError(state, expected) {
   const tok = current(state)
   const prevToken = state.tokens[state.pos - 1]
-  const after = prevToken ? ` after "${prevToken.originalValue ?? prevToken.value}"` : ''
-  const found = tok.type === 'eof' ? 'end of query' : `"${tok.originalValue ?? tok.value}"`
-  return new Error(`Expected ${expected}${after} but found ${found} at position ${tok.position}`)
+  const after = prevToken ? prevToken.originalValue ?? prevToken.value : undefined
+  const received = tok.type === 'eof' ? 'end of query' : `"${tok.originalValue ?? tok.value}"`
+  return syntaxError({ expected, received, position: tok.position, after })
 }

package/src/parse/tokenize.js

@@ -1,3 +1,9 @@
+import {
+  invalidLiteralError,
+  unexpectedCharError,
+  unterminatedError,
+} from '../errors.js'
+
 /**
  * @import { Token } from '../types.d.ts'
  */
@@ -41,6 +47,13 @@ const KEYWORDS = new Set([
   'FULL',
   'OUTER',
   'ON',
+  'INTERVAL',
+  'DAY',
+  'MONTH',
+  'YEAR',
+  'HOUR',
+  'MINUTE',
+  'SECOND',
 ])
 
 /**
@@ -71,6 +84,61 @@ export function tokenize(sql) {
     return ch
   }
 
+  /**
+   * @param {number} startPos
+   * @param {string} prefix
+   * @returns {Token}
+   */
+  function parseNumber(startPos, prefix = '') {
+    let text = prefix
+    while (isDigit(peek())) {
+      text += nextChar()
+    }
+    if (peek() === '.') {
+      text += nextChar()
+      while (isDigit(peek())) {
+        text += nextChar()
+      }
+    }
+    // exponent
+    if (peek() === 'e' || peek() === 'E') {
+      text += nextChar()
+      if (peek() === '+' || peek() === '-') {
+        text += nextChar()
+      }
+      while (isDigit(peek())) {
+        text += nextChar()
+      }
+    }
+    // bigint suffix
+    if (peek() === 'n') {
+      text += nextChar()
+      try {
+        return {
+          type: 'number',
+          value: text,
+          position: startPos,
+          numericValue: BigInt(text.slice(0, -1)),
+        }
+      } catch {
+        throw invalidLiteralError({ type: 'bigint', value: text.slice(0, -1), position: startPos })
+      }
+    }
+    if (isAlpha(peek())) {
+      throw invalidLiteralError({ type: 'number', value: text + peek(), position: startPos })
+    }
+    const num = parseFloat(text)
+    if (isNaN(num)) {
+      throw invalidLiteralError({ type: 'number', value: text, position: startPos })
+    }
+    return {
+      type: 'number',
+      value: text,
+      position: startPos,
+      numericValue: num,
+    }
+  }
+
   while (i < length) {
     const ch = peek()
 
@@ -102,41 +170,25 @@ export function tokenize(sql) {
 
     const pos = i
 
+    // negative numbers (when not subtraction)
+    if (ch === '-' && i + 1 < length && isDigit(sql[i + 1])) {
+      const lastToken = tokens[tokens.length - 1]
+      const isValueBefore = lastToken && (
+        lastToken.type === 'identifier' ||
+        lastToken.type === 'number' ||
+        lastToken.type === 'string' ||
+        lastToken.type === 'paren' && lastToken.value === ')'
+      )
+      if (!isValueBefore) {
+        nextChar() // consume '-'
+        tokens.push(parseNumber(pos, '-'))
+        continue
+      }
+    }
+
     // numbers
     if (isDigit(ch)) {
-      let text = ''
-      while (isDigit(peek())) {
-        text += nextChar()
-      }
-      if (peek() === '.') {
-        text += nextChar()
-        while (isDigit(peek())) {
-          text += nextChar()
-        }
-      }
-      // exponent
-      if (peek() === 'e' || peek() === 'E') {
-        text += nextChar()
-        if (peek() === '+' || peek() === '-') {
-          text += nextChar()
-        }
-        while (isDigit(peek())) {
-          text += nextChar()
-        }
-      }
-      if (isAlpha(peek())) {
-        throw new Error(`Invalid number at position ${pos}: ${text}${peek()}`)
-      }
-      const num = parseFloat(text)
-      if (isNaN(num)) {
-        throw new Error(`Invalid number at position ${pos}: ${text}`)
-      }
-      tokens.push({
-        type: 'number',
-        value: text,
-        position: pos,
-        numericValue: num,
-      })
+      tokens.push(parseNumber(pos))
       continue
     }
 
@@ -170,7 +222,7 @@ export function tokenize(sql) {
       let text = ''
       while (i <= length) {
         if (i === length) {
-          throw new Error(`Unterminated string literal starting at position ${pos}`)
+          throw unterminatedError('string', pos)
         }
         const c = nextChar()
         if (c === quote) {
@@ -198,7 +250,7 @@ export function tokenize(sql) {
       let text = ''
       while (i <= length) {
         if (i === length) {
-          throw new Error(`Unterminated identifier starting at position ${pos}`)
+          throw unterminatedError('identifier', pos)
         }
         const c = nextChar()
         if (c === quote) {
@@ -288,9 +340,9 @@ export function tokenize(sql) {
     }
 
     if (tokens.length === 0) {
-      throw new Error(`Expected SELECT but found "${ch}" at position ${pos}`)
+      throw unexpectedCharError(ch, pos, true)
     }
-    throw new Error(`Unexpected character "${ch}" at position ${pos}`)
+    throw unexpectedCharError(ch, pos)
   }
 
   tokens.push({

package/src/types.d.ts

@@ -27,7 +27,15 @@ export interface ExecuteSqlOptions {
   query: string
 }
 
-export type SqlPrimitive = string | number | bigint | boolean | SqlPrimitive[] | Record<string, any> | null
+export type SqlPrimitive =
+  | string
+  | number
+  | bigint
+  | boolean
+  | Date
+  | null
+  | SqlPrimitive[]
+  | Record<string, any>
 
 export interface SelectStatement {
   distinct: boolean
@@ -129,6 +137,14 @@ export interface SubqueryNode {
   subquery: SelectStatement
 }
 
+export type IntervalUnit = 'DAY' | 'MONTH' | 'YEAR' | 'HOUR' | 'MINUTE' | 'SECOND'
+
+export interface IntervalNode {
+  type: 'interval'
+  value: number
+  unit: IntervalUnit
+}
+
 export type ExprNode =
   | LiteralNode
   | IdentifierNode
@@ -141,6 +157,7 @@ export type ExprNode =
   | ExistsNode
   | CaseNode
   | SubqueryNode
+  | IntervalNode
 
 export interface StarColumn {
   kind: 'star'
@@ -162,6 +179,9 @@ export type StringFunc =
   | 'JSON_VALUE'
   | 'JSON_QUERY'
   | 'JSON_OBJECT'
+  | 'CURRENT_DATE'
+  | 'CURRENT_TIME'
+  | 'CURRENT_TIMESTAMP'
 
 export interface AggregateArgStar {
   kind: 'star'
@@ -227,6 +247,6 @@ export interface Token {
   type: TokenType
   value: string
   position: number
-  numericValue?: number
+  numericValue?: number | bigint
   originalValue?: string
 }

package/src/validation.js

@@ -1,6 +1,6 @@
 
 /**
- * @import {AggregateFunc, BinaryOp, ComparisonOp, StringFunc} from './types.js'
+ * @import {AggregateFunc, BinaryOp, ComparisonOp, IntervalUnit, StringFunc} from './types.js'
  * @param {string} name
  * @returns {name is AggregateFunc}
  */
@@ -8,6 +8,14 @@ export function isAggregateFunc(name) {
   return ['COUNT', 'SUM', 'AVG', 'MIN', 'MAX', 'JSON_ARRAYAGG'].includes(name)
 }
 
+/**
+ * @param {string} name
+ * @returns {name is IntervalUnit}
+ */
+export function isIntervalUnit(name) {
+  return ['DAY', 'MONTH', 'YEAR', 'HOUR', 'MINUTE', 'SECOND'].includes(name)
+}
+
 /**
  * @param {string} name
  * @returns {name is StringFunc}
@@ -27,6 +35,9 @@ export function isStringFunc(name) {
     'JSON_VALUE',
     'JSON_QUERY',
     'JSON_OBJECT',
+    'CURRENT_DATE',
+    'CURRENT_TIME',
+    'CURRENT_TIMESTAMP',
   ].includes(name)
 }