squirreling 0.7.0 → 0.7.2

package/README.md

@@ -10,7 +10,7 @@
 ![coverage](https://img.shields.io/badge/Coverage-95-darkred)
 [![dependencies](https://img.shields.io/badge/Dependencies-0-blueviolet)](https://www.npmjs.com/package/squirreling?activeTab=dependencies)
 
-Squirreling is a streaming async SQL engine for JavaScript. It is designed to provide efficient streaming of results from pluggable backends for highly efficient retrieval of data for browser applications.
+Squirreling is a streaming async SQL engine built for the web. It is designed to query over various data sources and provide efficient streaming of results. 100% JavaScript with zero dependencies.
 
 ## Features
 
@@ -79,11 +79,16 @@ console.log(`Collected rows:`, rows)
 
 - `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`
+- `JOIN` operations: `INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN`, `FULL JOIN`, `POSITIONAL JOIN`
 - `GROUP BY` and `HAVING` clauses
-- Aggregate functions: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `JSON_ARRAYAGG`
-- String functions: `CONCAT`, `SUBSTRING`, `LENGTH`, `UPPER`, `LOWER`
-- Math functions: `ABS`, `CEIL`, `FLOOR`, `ROUND`, `MOD`, `RAND`, `RANDOM`, `LN`, `LOG10`, `EXP`, `POWER`, `SQRT`, `SIN`, `COS`, `TAN`, `COT`, `ASIN`, `ACOS`, `ATAN`, `ATAN2`, `DEGREES`, `RADIANS`, `PI`
-- Date functions: `CURRENT_DATE`, `CURRENT_TIME`, `CURRENT_TIMESTAMP`, `INTERVAL`
-- Json functions: `JSON_VALUE`, `JSON_QUERY`, `JSON_OBJECT`
-- Basic expressions and arithmetic operations
+
+### Functions
+
+- Aggregate: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `JSON_ARRAYAGG`
+- String: `CONCAT`, `SUBSTRING`, `REPLACE`, `LENGTH`, `UPPER`, `LOWER`, `TRIM`, `LEFT`, `RIGHT`, `INSTR`
+- Math: `ABS`, `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`, `INTERVAL`
+- Json: `JSON_VALUE`, `JSON_QUERY`, `JSON_OBJECT`
+- Regex: `REGEXP_SUBSTR`, `REGEXP_REPLACE`
+- User-defined functions (UDFs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Squirreling SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -37,7 +37,7 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "24.10.4",
+    "@types/node": "25.0.3",
     "@vitest/coverage-v8": "4.0.16",
     "eslint": "9.39.2",
     "eslint-plugin-jsdoc": "61.5.0",

package/src/execute/expression.js

@@ -1,18 +1,16 @@
 import { unknownFunctionError } from '../parseErrors.js'
 import { invalidContextError } from '../executionErrors.js'
-import {
-  aggregateError,
-  argValueError,
-  castError,
-} from '../validationErrors.js'
-import { isAggregateFunc, isMathFunc } from '../validation.js'
+import { aggregateError, argValueError, castError } from '../validationErrors.js'
+import { isAggregateFunc, isMathFunc, isRegexpFunc, isStringFunc } from '../validation.js'
 import { applyIntervalToDate } from './date.js'
 import { executeSelect } from './execute.js'
 import { evaluateMathFunc } from './math.js'
+import { evaluateRegexpFunc } from './regexp.js'
+import { evaluateStringFunc } from './strings.js'
 import { applyBinaryOp, stringify } from './utils.js'
 
 /**
- * @import { ExprNode, AsyncRow, SqlPrimitive, AsyncDataSource, IntervalUnit, UserDefinedFunction } from '../types.js'
+ * @import { ExprNode, AsyncRow, SqlPrimitive, AsyncDataSource, UserDefinedFunction } from '../types.js'
  */
 
 /**
@@ -200,90 +198,33 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
     /** @type {SqlPrimitive[]} */
     const args = await Promise.all(node.args.map(arg => evaluateExpr({ node: arg, row, tables, functions, rowIndex, rows })))
 
-    if (funcName === 'UPPER') {
-      const val = args[0]
-      if (val == null) return null
-      return String(val).toUpperCase()
-    }
-
-    if (funcName === 'LOWER') {
-      const val = args[0]
-      if (val == null) return null
-      return String(val).toLowerCase()
-    }
-
-    if (funcName === 'CONCAT') {
-      // 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 argValueError({
-          funcName: 'CONCAT',
-          message: 'does not support object arguments',
-          positionStart: node.positionStart,
-          positionEnd: node.positionEnd,
-          hint: 'Use CAST to convert objects to strings first.',
-          rowNumber: rowIndex,
-        })
-      }
-      return args.map(a => String(a)).join('')
+    if (isStringFunc(funcName)) {
+      return evaluateStringFunc({
+        funcName,
+        args,
+        positionStart: node.positionStart,
+        positionEnd: node.positionEnd,
+        rowIndex,
+      })
     }
 
-    if (funcName === 'LENGTH') {
-      const val = args[0]
-      if (val == null) return null
-      return String(val).length
+    if (isRegexpFunc(funcName)) {
+      return evaluateRegexpFunc({
+        funcName,
+        args,
+        positionStart: node.positionStart,
+        positionEnd: node.positionEnd,
+        rowIndex,
+      })
     }
 
-    if (funcName === 'SUBSTRING' || funcName === 'SUBSTR') {
-      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 argValueError({
-          funcName,
-          message: `start position must be a positive integer, got ${args[1]}`,
-          positionStart: node.positionStart,
-          positionEnd: node.positionEnd,
-          hint: 'SQL uses 1-based indexing.',
-          rowNumber: rowIndex,
-        })
-      }
-      // 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 argValueError({
-            funcName,
-            message: `length must be a non-negative integer, got ${args[2]}`,
-            positionStart: node.positionStart,
-            positionEnd: node.positionEnd,
-            rowNumber: rowIndex,
-          })
-        }
-        return strVal.substring(startIdx, startIdx + len)
+    if (funcName === 'COALESCE') {
+      // Short-circuit: evaluate args one at a time, return first non-null
+      for (const arg of node.args) {
+        const val = await evaluateExpr({ node: arg, row, tables, functions, rowIndex, rows })
+        if (val != null) return val
       }
-      return strVal.substring(startIdx)
-    }
-
-    if (funcName === 'TRIM') {
-      const val = args[0]
-      if (val == null) return null
-      return String(val).trim()
-    }
-
-    if (funcName === 'REPLACE') {
-      const str = args[0]
-      const searchStr = args[1]
-      const replaceStr = args[2]
-      // SQL REPLACE returns NULL if any argument is NULL
-      if (str == null || searchStr == null || replaceStr == null) return null
-      return String(str).replaceAll(String(searchStr), String(replaceStr))
-    }
-
-    if (funcName === 'RANDOM' || funcName === 'RAND') {
-      return Math.random()
+      return null
     }
 
     if (funcName === 'CURRENT_DATE') {
@@ -392,7 +333,7 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
     if (functions) {
       const udfName = Object.keys(functions).find(k => k.toUpperCase() === funcName)
       if (udfName) {
-        return await functions[udfName](...args)
+        return await functions[udfName].apply(...args)
       }
     }
 

package/src/execute/join.js

@@ -43,16 +43,26 @@ export async function executeJoins({ leftSource, joins, leftTable, tables, funct
     return {
       async *scan(options) {
         const { signal } = options
-        yield* hashJoin({
-          leftRows: leftSource.scan(options), // Stream directly, not buffered
-          rightRows,
-          join,
-          leftTable: currentLeftTable,
-          rightTable,
-          tables,
-          functions,
-          signal,
-        })
+        if (join.joinType === 'POSITIONAL') {
+          yield* positionalJoin({
+            leftRows: leftSource.scan(options),
+            rightRows,
+            leftTable: currentLeftTable,
+            rightTable,
+            signal,
+          })
+        } else {
+          yield* hashJoin({
+            leftRows: leftSource.scan(options), // Stream directly, not buffered
+            rightRows,
+            join,
+            leftTable: currentLeftTable,
+            rightTable,
+            tables,
+            functions,
+            signal,
+          })
+        }
       },
     }
   }
@@ -84,15 +94,22 @@ export async function executeJoins({ leftSource, joins, leftTable, tables, funct
     // Collect intermediate results into array for next join
     /** @type {AsyncRow[]} */
     const newLeftRows = []
-    const joined = hashJoin({
-      leftRows,
-      rightRows,
-      join,
-      leftTable: currentLeftTable,
-      rightTable,
-      tables,
-      functions,
-    })
+    const joined = join.joinType === 'POSITIONAL'
+      ? positionalJoin({
+        leftRows,
+        rightRows,
+        leftTable: currentLeftTable,
+        rightTable,
+      })
+      : hashJoin({
+        leftRows,
+        rightRows,
+        join,
+        leftTable: currentLeftTable,
+        rightTable,
+        tables,
+        functions,
+      })
     for await (const row of joined) {
       newLeftRows.push(row)
     }
@@ -121,16 +138,26 @@ export async function executeJoins({ leftSource, joins, leftTable, tables, funct
   return {
     async *scan(options) {
       const { signal } = options
-      yield* hashJoin({
-        leftRows,
-        rightRows,
-        join,
-        leftTable: currentLeftTable,
-        rightTable,
-        tables,
-        functions,
-        signal,
-      })
+      if (join.joinType === 'POSITIONAL') {
+        yield* positionalJoin({
+          leftRows,
+          rightRows,
+          leftTable: currentLeftTable,
+          rightTable,
+          signal,
+        })
+      } else {
+        yield* hashJoin({
+          leftRows,
+          rightRows,
+          join,
+          leftTable: currentLeftTable,
+          rightTable,
+          tables,
+          functions,
+          signal,
+        })
+      }
     },
   }
 }
@@ -230,6 +257,48 @@ function mergeRows(leftRow, rightRow, leftTable, rightTable) {
   return { columns, cells }
 }
 
+/**
+ * Performs a positional join between left and right row sets.
+ * Matches rows by their index position (row 0 with row 0, row 1 with row 1, etc.).
+ * When tables have different lengths, the shorter table is padded with NULLs.
+ *
+ * @param {Object} params
+ * @param {AsyncIterable<AsyncRow>|AsyncRow[]} params.leftRows - rows from left table
+ * @param {AsyncRow[]} params.rightRows - rows from right table (must be buffered)
+ * @param {string} params.leftTable - name of left table (for column prefixing)
+ * @param {string} params.rightTable - name of right table (for column prefixing, may be alias)
+ * @param {AbortSignal} [params.signal] - abort signal for cancellation
+ * @yields {AsyncRow} joined rows
+ */
+async function* positionalJoin({ leftRows, rightRows, leftTable, rightTable, signal }) {
+  // Buffer left rows if streaming
+  /** @type {AsyncRow[]} */
+  const leftArr = []
+  for await (const row of leftRows) {
+    if (signal?.aborted) return
+    leftArr.push(row)
+  }
+
+  const maxLen = Math.max(leftArr.length, rightRows.length)
+
+  // Get column info for NULL row creation
+  const leftCols = leftArr[0]?.columns ?? []
+  const rightCols = rightRows[0]?.columns ?? []
+  const leftPrefixedCols = leftCols.flatMap(col =>
+    col.includes('.') ? [col] : [`${leftTable}.${col}`, col]
+  )
+  const rightPrefixedCols = rightCols.flatMap(col =>
+    col.includes('.') ? [col] : [`${rightTable}.${col}`, col]
+  )
+
+  for (let i = 0; i < maxLen; i++) {
+    if (signal?.aborted) return
+    const leftRow = leftArr[i] ?? createNullRow(leftPrefixedCols)
+    const rightRow = rightRows[i] ?? createNullRow(rightPrefixedCols)
+    yield mergeRows(leftRow, rightRow, leftTable, rightTable)
+  }
+}
+
 /**
  * Performs a hash join between left and right row sets (streaming).
  * Yields rows as they are found instead of buffering all results.

package/src/execute/math.js

@@ -6,9 +6,9 @@
  * Evaluate a math function
  *
  * @param {Object} options
- * @param {MathFunc} options.funcName - Uppercase function name
- * @param {SqlPrimitive[]} options.args - Function arguments
- * @returns {SqlPrimitive} Result
+ * @param {MathFunc} options.funcName
+ * @param {SqlPrimitive[]} options.args
+ * @returns {SqlPrimitive}
  */
 export function evaluateMathFunc({ funcName, args }) {
   if (funcName === 'FLOOR') {
@@ -138,4 +138,8 @@ export function evaluateMathFunc({ funcName, args }) {
   if (funcName === 'PI') {
     return Math.PI
   }
+
+  if (funcName === 'RAND' || funcName === 'RANDOM') {
+    return Math.random()
+  }
 }

package/src/execute/regexp.js

@@ -0,0 +1,159 @@
+import { argValueError } from '../validationErrors.js'
+
+/**
+ * @import { SqlPrimitive } from '../types.js'
+ */
+
+/**
+ * Evaluate a regexp function
+ *
+ * @param {Object} options
+ * @param {string} options.funcName - Uppercase function name
+ * @param {SqlPrimitive[]} options.args - Function arguments
+ * @param {number} [options.positionStart] - Start position in SQL string for error reporting
+ * @param {number} [options.positionEnd] - End position in SQL string for error reporting
+ * @param {number} [options.rowIndex] - Row number for error reporting
+ * @returns {SqlPrimitive} Result
+ */
+export function evaluateRegexpFunc({ funcName, args, positionStart, positionEnd, rowIndex }) {
+  if (funcName === 'REGEXP_SUBSTR') {
+    const str = args[0]
+    const pattern = args[1]
+    if (str == null || pattern == null) return null
+    const strVal = String(str)
+    const patternStr = String(pattern)
+
+    // Default position is 1 (1-based)
+    let position = 1
+    if (args.length >= 3 && args[2] != null) {
+      position = Number(args[2])
+      if (!Number.isInteger(position) || position < 1) {
+        throw argValueError({
+          funcName,
+          message: `position must be a positive integer, got ${args[2]}`,
+          positionStart,
+          positionEnd,
+          hint: 'SQL uses 1-based indexing.',
+          rowNumber: rowIndex,
+        })
+      }
+    }
+
+    // Default occurrence is 1
+    let occurrence = 1
+    if (args.length >= 4 && args[3] != null) {
+      occurrence = Number(args[3])
+      if (!Number.isInteger(occurrence) || occurrence < 1) {
+        throw argValueError({
+          funcName,
+          message: `occurrence must be a positive integer, got ${args[3]}`,
+          positionStart,
+          positionEnd,
+          rowNumber: rowIndex,
+        })
+      }
+    }
+
+    // Create regex
+    let regex
+    try {
+      regex = new RegExp(patternStr, 'g')
+    } catch (/** @type {any} */ error) {
+      throw argValueError({
+        funcName,
+        message: `invalid regex pattern: ${error.message}`,
+        positionStart,
+        positionEnd,
+        rowNumber: rowIndex,
+      })
+    }
+
+    // Search from position (convert to 0-based)
+    const searchStr = strVal.substring(position - 1)
+
+    // Find the nth occurrence
+    let match
+    let count = 0
+    while ((match = regex.exec(searchStr)) !== null) {
+      count++
+      if (count === occurrence) {
+        return match[0]
+      }
+    }
+
+    return null
+  }
+
+  if (funcName === 'REGEXP_REPLACE') {
+    const str = args[0]
+    const pattern = args[1]
+    const replacement = args[2]
+    if (str == null || pattern == null || replacement == null) return null
+    const strVal = String(str)
+    const patternStr = String(pattern)
+    const replacementStr = String(replacement)
+
+    // Default position is 1 (1-based)
+    let position = 1
+    if (args.length >= 4 && args[3] != null) {
+      position = Number(args[3])
+      if (!Number.isInteger(position) || position < 1) {
+        throw argValueError({
+          funcName,
+          message: `position must be a positive integer, got ${args[3]}`,
+          positionStart,
+          positionEnd,
+          hint: 'SQL uses 1-based indexing.',
+          rowNumber: rowIndex,
+        })
+      }
+    }
+
+    // Default occurrence is 0 (replace all)
+    let occurrence = 0
+    if (args.length >= 5 && args[4] != null) {
+      occurrence = Number(args[4])
+      if (!Number.isInteger(occurrence) || occurrence < 0) {
+        throw argValueError({
+          funcName,
+          message: `occurrence must be a non-negative integer, got ${args[4]}`,
+          positionStart,
+          positionEnd,
+          hint: 'Use 0 to replace all occurrences.',
+          rowNumber: rowIndex,
+        })
+      }
+    }
+
+    // Create regex
+    let regex
+    try {
+      regex = new RegExp(patternStr, 'g')
+    } catch (/** @type {any} */ error) {
+      throw argValueError({
+        funcName,
+        message: `invalid regex pattern: ${error.message}`,
+        positionStart,
+        positionEnd,
+        rowNumber: rowIndex,
+      })
+    }
+
+    // If position > 1, preserve the prefix
+    const prefix = strVal.substring(0, position - 1)
+    const searchStr = strVal.substring(position - 1)
+
+    if (occurrence === 0) {
+      // Replace all occurrences
+      return prefix + searchStr.replace(regex, replacementStr)
+    }
+
+    // Replace only the nth occurrence
+    let count = 0
+    const result = searchStr.replace(regex, (match) => {
+      count++
+      return count === occurrence ? replacementStr : match
+    })
+    return prefix + result
+  }
+}

package/src/execute/strings.js

@@ -0,0 +1,145 @@
+/**
+ * @import { SqlPrimitive, StringFunc } from '../types.js'
+ */
+
+import { argValueError } from '../validationErrors.js'
+
+/**
+ * Evaluate a string function
+ *
+ * @param {Object} options
+ * @param {StringFunc} options.funcName - Uppercase function name
+ * @param {SqlPrimitive[]} options.args - Function arguments
+ * @param {number} [options.positionStart] - Start position for error reporting
+ * @param {number} [options.positionEnd] - End position for error reporting
+ * @param {number} [options.rowIndex] - Row index for error reporting
+ * @returns {SqlPrimitive} Result
+ */
+export function evaluateStringFunc({ funcName, args, positionStart, positionEnd, rowIndex }) {
+  if (funcName === 'UPPER') {
+    const val = args[0]
+    if (val == null) return null
+    return String(val).toUpperCase()
+  }
+
+  if (funcName === 'LOWER') {
+    const val = args[0]
+    if (val == null) return null
+    return String(val).toLowerCase()
+  }
+
+  if (funcName === 'CONCAT') {
+    // 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 argValueError({
+        funcName: 'CONCAT',
+        message: 'does not support object arguments',
+        positionStart,
+        positionEnd,
+        hint: 'Use CAST to convert objects to strings first.',
+        rowNumber: rowIndex,
+      })
+    }
+    return args.map(a => String(a)).join('')
+  }
+
+  if (funcName === 'LENGTH') {
+    const val = args[0]
+    if (val == null) return null
+    return String(val).length
+  }
+
+  if (funcName === 'SUBSTRING' || funcName === 'SUBSTR') {
+    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 argValueError({
+        funcName,
+        message: `start position must be a positive integer, got ${args[1]}`,
+        positionStart,
+        positionEnd,
+        hint: 'SQL uses 1-based indexing.',
+        rowNumber: rowIndex,
+      })
+    }
+    // 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 argValueError({
+          funcName,
+          message: `length must be a non-negative integer, got ${args[2]}`,
+          positionStart,
+          positionEnd,
+          rowNumber: rowIndex,
+        })
+      }
+      return strVal.substring(startIdx, startIdx + len)
+    }
+    return strVal.substring(startIdx)
+  }
+
+  if (funcName === 'TRIM') {
+    const val = args[0]
+    if (val == null) return null
+    return String(val).trim()
+  }
+
+  if (funcName === 'REPLACE') {
+    const str = args[0]
+    const searchStr = args[1]
+    const replaceStr = args[2]
+    // SQL REPLACE returns NULL if any argument is NULL
+    if (str == null || searchStr == null || replaceStr == null) return null
+    return String(str).replaceAll(String(searchStr), String(replaceStr))
+  }
+
+  if (funcName === 'LEFT') {
+    const str = args[0]
+    const n = args[1]
+    if (str == null || n == null) return null
+    const len = Number(n)
+    if (!Number.isInteger(len) || len < 0) {
+      throw argValueError({
+        funcName,
+        message: `length must be a non-negative integer, got ${n}`,
+        positionStart,
+        positionEnd,
+        rowNumber: rowIndex,
+      })
+    }
+    return String(str).substring(0, len)
+  }
+
+  if (funcName === 'RIGHT') {
+    const str = args[0]
+    const n = args[1]
+    if (str == null || n == null) return null
+    const len = Number(n)
+    if (!Number.isInteger(len) || len < 0) {
+      throw argValueError({
+        funcName,
+        message: `length must be a non-negative integer, got ${n}`,
+        positionStart,
+        positionEnd,
+        rowNumber: rowIndex,
+      })
+    }
+    const strVal = String(str)
+    if (len >= strVal.length) return strVal
+    return strVal.substring(strVal.length - len)
+  }
+
+  if (funcName === 'INSTR') {
+    const str = args[0]
+    const search = args[1]
+    if (str == null || search == null) return null
+    // INSTR returns 1-based position, 0 if not found
+    const pos = String(str).indexOf(String(search))
+    return pos === -1 ? 0 : pos + 1
+  }
+}

package/src/index.d.ts

@@ -1,5 +1,5 @@
-import type { AsyncDataSource, AsyncRow, ExecuteSqlOptions, SelectStatement, SqlPrimitive } from './types.js'
-export type { AsyncDataSource, AsyncRow, SqlPrimitive } from './types.js'
+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'
 
 /**
  * Executes a SQL SELECT query against an array of data rows
@@ -7,6 +7,8 @@ export type { AsyncDataSource, AsyncRow, SqlPrimitive } from './types.js'
  * @param options
  * @param options.tables - source data as a list of objects or an AsyncDataSource
  * @param options.query - SQL query string
+ * @param options.functions - user-defined functions available in the SQL context
+ * @param options.signal - AbortSignal to cancel the query
  * @returns async generator yielding rows matching the query
  */
 export function executeSql(options: ExecuteSqlOptions): AsyncGenerator<AsyncRow>
@@ -16,9 +18,18 @@ export function executeSql(options: ExecuteSqlOptions): AsyncGenerator<AsyncRow>
  *
  * @param options
  * @param options.query - SQL query string to parse
+ * @param options.functions - user-defined functions available in the SQL context
  * @returns parsed SQL select statement
  */
-export function parseSql(options: { query: string }): SelectStatement
+export function parseSql(options: ParseSqlOptions): SelectStatement
+
+/**
+ * Tokenizes a SQL query string into an array of tokens
+ *
+ * @param sql - SQL query string to tokenize
+ * @returns array of tokens
+ */
+export function tokenizeSql(sql: string): Token[]
 
 /**
  * Collects all results from an async generator into an array

package/src/index.js

@@ -1,5 +1,6 @@
 export { executeSql } from './execute/execute.js'
 export { parseSql } from './parse/parse.js'
+export { tokenizeSql } from './parse/tokenize.js'
 export { collect } from './execute/utils.js'
 export { cachedDataSource } from './backend/dataSource.js'
 export { ParseError } from './parseErrors.js'

package/src/parse/expression.js

@@ -1,12 +1,12 @@
 import {
-  argCountParseError,
   invalidLiteralError,
   missingClauseError,
   syntaxError,
   unknownFunctionError,
 } from '../parseErrors.js'
-import { isIntervalUnit, isKnownFunction, validateFunctionArgCount } from '../validation.js'
+import { isIntervalUnit, isKnownFunction } from '../validation.js'
 import { parseComparison } from './comparison.js'
+import { parseFunctionCall } from './functions.js'
 import { parseSelectInternal } from './parse.js'
 import { consume, current, expect, expectIdentifier, lastPosition, match, peekToken } from './state.js'
 
@@ -123,10 +123,9 @@ export function parsePrimary(state) {
     // function call
     if (next.type === 'paren' && next.value === '(') {
       const funcName = tok.value
-      const funcNameUpper = funcName.toUpperCase()
 
       // Validate function existence early for better error messages
-      if (!isKnownFunction(funcNameUpper, state.functions)) {
+      if (!isKnownFunction(funcName.toUpperCase(), state.functions)) {
         throw unknownFunctionError({
           funcName,
           positionStart,
@@ -135,62 +134,7 @@ export function parsePrimary(state) {
       }
 
       consume(state) // function name
-      consume(state) // '('
-
-      /** @type {ExprNode[]} */
-      const args = []
-      let distinct = false
-
-      // Check for DISTINCT or ALL keyword (for aggregate functions like COUNT(DISTINCT x))
-      if (current(state).type === 'keyword' && current(state).value === 'DISTINCT') {
-        consume(state) // consume DISTINCT
-        distinct = true
-      } else if (current(state).type === 'keyword' && current(state).value === 'ALL') {
-        consume(state) // consume ALL (default behavior, just consume it)
-      }
-
-      if (current(state).type !== 'paren' || current(state).value !== ')') {
-        while (true) {
-          // Handle COUNT(*) - treat * as a special identifier
-          if (current(state).type === 'operator' && current(state).value === '*') {
-            const starTok = current(state)
-            consume(state)
-            args.push({
-              type: 'identifier',
-              name: '*',
-              positionStart: starTok.positionStart,
-              positionEnd: lastPosition(state),
-            })
-          } else {
-            const arg = parseExpression(state)
-            args.push(arg)
-          }
-          if (!match(state, 'comma')) break
-        }
-      }
-
-      expect(state, 'paren', ')')
-
-      // Validate argument count at parse time
-      const validation = validateFunctionArgCount(funcNameUpper, args.length)
-      if (!validation.valid) {
-        throw argCountParseError({
-          funcName,
-          expected: validation.expected,
-          received: args.length,
-          positionStart,
-          positionEnd: lastPosition(state),
-        })
-      }
-
-      return {
-        type: 'function',
-        name: funcName,
-        args,
-        distinct: distinct || undefined,
-        positionStart,
-        positionEnd: lastPosition(state),
-      }
+      return parseFunctionCall(state, funcName, positionStart)
     }
 
     // Niladic datetime functions (no parentheses required per ANSI SQL)
@@ -244,7 +188,14 @@ export function parsePrimary(state) {
     }
   }
 
+  // Keywords that can be used as function names (e.g., LEFT, RIGHT)
   if (tok.type === 'keyword') {
+    const next = peekToken(state, 1)
+    if (next.type === 'paren' && next.value === '(' && isKnownFunction(tok.value, state.functions)) {
+      consume(state) // function name
+      return parseFunctionCall(state, tok.value, positionStart)
+    }
+
     if (tok.value === 'TRUE') {
       consume(state)
       return { type: 'literal', value: true, positionStart, positionEnd: lastPosition(state) }

package/src/parse/functions.js

@@ -0,0 +1,76 @@
+import { argCountParseError } from '../parseErrors.js'
+import { validateFunctionArgCount } from '../validation.js'
+import { parseExpression } from './expression.js'
+import { consume, current, expect, lastPosition, match } from './state.js'
+
+/**
+ * @import { ExprNode, ParserState } from '../types.js'
+ */
+
+/**
+ * Parses a function call after the function name has been identified.
+ * Expects the current token to be '('.
+ *
+ * @param {ParserState} state
+ * @param {string} funcName - The function name
+ * @param {number} positionStart - Start position of the function name
+ * @returns {ExprNode}
+ */
+export function parseFunctionCall(state, funcName, positionStart) {
+  consume(state) // '('
+
+  /** @type {ExprNode[]} */
+  const args = []
+  let distinct = false
+
+  // Check for DISTINCT or ALL keyword (for aggregate functions like COUNT(DISTINCT x))
+  if (current(state).type === 'keyword' && current(state).value === 'DISTINCT') {
+    consume(state)
+    distinct = true
+  } else if (current(state).type === 'keyword' && current(state).value === 'ALL') {
+    consume(state)
+  }
+
+  if (current(state).type !== 'paren' || current(state).value !== ')') {
+    while (true) {
+      // Handle COUNT(*) - treat * as a special identifier
+      if (current(state).type === 'operator' && current(state).value === '*') {
+        const starTok = current(state)
+        consume(state)
+        args.push({
+          type: 'identifier',
+          name: '*',
+          positionStart: starTok.positionStart,
+          positionEnd: lastPosition(state),
+        })
+      } else {
+        args.push(parseExpression(state))
+      }
+      if (!match(state, 'comma')) break
+    }
+  }
+
+  expect(state, 'paren', ')')
+
+  // Validate argument count at parse time
+  const funcNameUpper = funcName.toUpperCase()
+  const validation = validateFunctionArgCount(funcNameUpper, args.length, state.functions)
+  if (!validation.valid) {
+    throw argCountParseError({
+      funcName,
+      expected: validation.expected,
+      received: args.length,
+      positionStart,
+      positionEnd: lastPosition(state),
+    })
+  }
+
+  return {
+    type: 'function',
+    name: funcName,
+    args,
+    distinct: distinct || undefined,
+    positionStart,
+    positionEnd: lastPosition(state),
+  }
+}

package/src/parse/joins.js

@@ -40,6 +40,9 @@ export function parseJoins(state) {
           // FULL OUTER JOIN
         }
         joinType = 'FULL'
+      } else if (tok.value === 'POSITIONAL') {
+        consume(state)
+        joinType = 'POSITIONAL'
       } else if (tok.value === 'JOIN') {
         // Just JOIN (defaults to INNER)
         consume(state)
@@ -61,9 +64,13 @@ export function parseJoins(state) {
     const tableName = expectIdentifier(state).value
     const tableAlias = parseTableAlias(state)
 
-    // Parse ON condition
-    expect(state, 'keyword', 'ON')
-    const condition = parseExpression(state)
+    // Parse ON condition (not for POSITIONAL joins)
+    /** @type {import('../types.js').ExprNode | undefined} */
+    let condition
+    if (joinType !== 'POSITIONAL') {
+      expect(state, 'keyword', 'ON')
+      condition = parseExpression(state)
+    }
 
     joins.push({
       joinType,

package/src/parse/parse.js

@@ -1,19 +1,19 @@
-import { tokenize } from './tokenize.js'
+import { tokenizeSql } from './tokenize.js'
 import { parseExpression } from './expression.js'
-import { RESERVED_AFTER_COLUMN, RESERVED_AFTER_TABLE } from '../validation.js'
+import { RESERVED_AFTER_COLUMN, RESERVED_AFTER_TABLE, isKnownFunction } from '../validation.js'
 import { consume, current, expect, expectIdentifier, match, parseError, peekToken } from './state.js'
 import { parseJoins } from './joins.js'
 
 /**
- * @import { ExprNode, FromSubquery, FromTable, OrderByItem, ParserState, SelectStatement, SelectColumn, UserDefinedFunction } from '../types.js'
+ * @import { ExprNode, FromSubquery, FromTable, OrderByItem, ParseSqlOptions, ParserState, SelectStatement, SelectColumn } from '../types.js'
  */
 
 /**
- * @param {{ query: string, functions?: Record<string, UserDefinedFunction> }} options
+ * @param {ParseSqlOptions} options
  * @returns {SelectStatement}
  */
 export function parseSql({ query, functions }) {
-  const tokens = tokenize(query)
+  const tokens = tokenizeSql(query)
   /** @type {ParserState} */
   const state = { tokens, pos: 0, functions }
   const select = parseSelectInternal(state)
@@ -75,7 +75,13 @@ const EXPRESSION_START_KEYWORDS = new Set([
 function parseSelectItem(state) {
   const tok = current(state)
 
-  if (tok.type === 'keyword' && !EXPRESSION_START_KEYWORDS.has(tok.value) || tok.type === 'eof') {
+  // Check if keyword followed by ( is a known function (e.g., LEFT, RIGHT)
+  const isKeywordFunction = tok.type === 'keyword' &&
+    peekToken(state, 1).type === 'paren' &&
+    peekToken(state, 1).value === '(' &&
+    isKnownFunction(tok.value, state.functions)
+
+  if (tok.type === 'keyword' && !EXPRESSION_START_KEYWORDS.has(tok.value) && !isKeywordFunction || tok.type === 'eof') {
     throw parseError(state, 'column name or expression')
   }
 

package/src/parse/tokenize.js

@@ -46,6 +46,7 @@ const KEYWORDS = new Set([
   'RIGHT',
   'FULL',
   'OUTER',
+  'POSITIONAL',
   'ON',
   'INTERVAL',
   'DAY',
@@ -60,7 +61,7 @@ const KEYWORDS = new Set([
  * @param {string} sql
  * @returns {Token[]}
  */
-export function tokenize(sql) {
+export function tokenizeSql(sql) {
   /** @type {Token[]} */
   const tokens = []
   const { length } = sql

package/src/types.d.ts

@@ -1,5 +1,8 @@
-// User-defined function type
-export type UserDefinedFunction = (...args: SqlPrimitive[]) => SqlPrimitive | Promise<SqlPrimitive>
+// parseSql(options)
+export interface ParseSqlOptions {
+  query: string
+  functions?: Record<string, UserDefinedFunction>
+}
 
 // executeSql(options)
 export interface ExecuteSqlOptions {
@@ -56,6 +59,14 @@ export type SqlPrimitive =
   | SqlPrimitive[]
   | Record<string, any>
 
+export interface UserDefinedFunction {
+  apply: (...args: SqlPrimitive[]) => SqlPrimitive | Promise<SqlPrimitive>
+  arguments: {
+    min: number
+    max?: number
+  }
+}
+
 export interface SelectStatement {
   distinct: boolean
   columns: SelectColumn[]
@@ -214,6 +225,8 @@ export type MathFunc =
   | 'DEGREES'
   | 'RADIANS'
   | 'PI'
+  | 'RAND'
+  | 'RANDOM'
 
 export type StringFunc =
   | 'UPPER'
@@ -224,12 +237,9 @@ export type StringFunc =
   | 'SUBSTR'
   | 'TRIM'
   | 'REPLACE'
-  | 'JSON_VALUE'
-  | 'JSON_QUERY'
-  | 'JSON_OBJECT'
-  | 'CURRENT_DATE'
-  | 'CURRENT_TIME'
-  | 'CURRENT_TIMESTAMP'
+  | 'LEFT'
+  | 'RIGHT'
+  | 'INSTR'
 
 export interface DerivedColumn {
   kind: 'derived'
@@ -245,7 +255,7 @@ export interface OrderByItem {
   nulls?: 'FIRST' | 'LAST'
 }
 
-export type JoinType = 'INNER' | 'LEFT' | 'RIGHT' | 'FULL' | 'CROSS'
+export type JoinType = 'INNER' | 'LEFT' | 'RIGHT' | 'FULL' | 'CROSS' | 'POSITIONAL'
 
 export interface JoinClause {
   joinType: JoinType

package/src/validation.js

@@ -8,16 +8,23 @@ export function isAggregateFunc(name) {
   return ['COUNT', 'SUM', 'AVG', 'MIN', 'MAX', 'JSON_ARRAYAGG'].includes(name)
 }
 
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isRegexpFunc(name) {
+  return ['REGEXP_SUBSTR', 'REGEXP_REPLACE'].includes(name)
+}
+
 /**
  * @param {string} name
  * @returns {name is MathFunc}
  */
 export function isMathFunc(name) {
   return [
-    'FLOOR', 'CEIL', 'CEILING', 'ABS', 'MOD',
-    'EXP', 'LN', 'LOG10', 'POWER', 'SQRT',
-    'SIN', 'COS', 'TAN', 'COT', 'ASIN', 'ACOS', 'ATAN', 'ATAN2',
-    'DEGREES', 'RADIANS', 'PI',
+    'FLOOR', 'CEIL', 'CEILING', 'ABS', 'MOD', 'EXP', 'LN', 'LOG10', 'POWER', 'SQRT',
+    'SIN', 'COS', 'TAN', 'COT', 'ASIN', 'ACOS', 'ATAN', 'ATAN2', 'DEGREES', 'RADIANS', 'PI',
+    'RAND', 'RANDOM',
   ].includes(name)
 }
 
@@ -35,22 +42,8 @@ export function isIntervalUnit(name) {
  */
 export function isStringFunc(name) {
   return [
-    'UPPER',
-    'LOWER',
-    'CONCAT',
-    'LENGTH',
-    'SUBSTRING',
-    'SUBSTR',
-    'TRIM',
-    'REPLACE',
-    'RANDOM',
-    'RAND',
-    'JSON_VALUE',
-    'JSON_QUERY',
-    'JSON_OBJECT',
-    'CURRENT_DATE',
-    'CURRENT_TIME',
-    'CURRENT_TIMESTAMP',
+    'UPPER', 'LOWER', 'CONCAT', 'LENGTH', 'SUBSTRING', 'SUBSTR', 'TRIM',
+    'REPLACE', 'LEFT', 'RIGHT', 'INSTR',
   ].includes(name)
 }
 
@@ -65,8 +58,8 @@ export function isBinaryOp(op) {
 /**
  * Function argument count specifications.
  * min: minimum number of arguments
- * max: maximum number of arguments (null = unlimited)
- * @type {Record<string, {min: number, max: number | null}>}
+ * max: maximum number of arguments
+ * @type {Record<string, {min: number, max?: number}>}
  */
 export const FUNCTION_ARG_COUNTS = {
   // String functions
@@ -77,7 +70,12 @@ export const FUNCTION_ARG_COUNTS = {
   REPLACE: { min: 3, max: 3 },
   SUBSTRING: { min: 2, max: 3 },
   SUBSTR: { min: 2, max: 3 },
-  CONCAT: { min: 1, max: null },
+  CONCAT: { min: 1 },
+  LEFT: { min: 2, max: 2 },
+  RIGHT: { min: 2, max: 2 },
+  INSTR: { min: 2, max: 2 },
+  REGEXP_SUBSTR: { min: 2, max: 4 },
+  REGEXP_REPLACE: { min: 3, max: 5 },
 
   // Date/time functions
   RANDOM: { min: 0, max: 0 },
@@ -112,9 +110,12 @@ export const FUNCTION_ARG_COUNTS = {
   // JSON functions
   JSON_VALUE: { min: 2, max: 2 },
   JSON_QUERY: { min: 2, max: 2 },
-  JSON_OBJECT: { min: 0, max: null },
+  JSON_OBJECT: { min: 0 },
   JSON_ARRAYAGG: { min: 1, max: 1 },
 
+  // Conditional functions
+  COALESCE: { min: 1 },
+
   // Aggregate functions
   COUNT: { min: 1, max: 1 },
   SUM: { min: 1, max: 1 },
@@ -126,11 +127,11 @@ export const FUNCTION_ARG_COUNTS = {
 /**
  * Format expected argument count for error messages.
  * @param {number} min
- * @param {number | null} max
+ * @param {number | undefined} max
  * @returns {string | number}
  */
 function formatExpected(min, max) {
-  if (max === null) return `at least ${min}`
+  if (max == null) return `at least ${min}`
   if (min === max) return min
   return `${min} or ${max}`
 }
@@ -139,10 +140,21 @@ function formatExpected(min, max) {
  * Validates function argument count.
  * @param {string} funcName - The function name (uppercase)
  * @param {number} argCount - Number of arguments provided
+ * @param {Record<string, UserDefinedFunction>} [functions] - User-defined functions
  * @returns {{ valid: boolean, expected: string | number }}
  */
-export function validateFunctionArgCount(funcName, argCount) {
-  const spec = FUNCTION_ARG_COUNTS[funcName]
+export function validateFunctionArgCount(funcName, argCount, functions) {
+  // Check built-in functions
+  let spec = FUNCTION_ARG_COUNTS[funcName]
+
+  // Check user-defined functions (case-insensitive)
+  if (!spec && functions) {
+    const udfName = Object.keys(functions).find(k => k.toUpperCase() === funcName)
+    if (udfName) {
+      spec = functions[udfName].arguments
+    }
+  }
+
   if (!spec) return { valid: true, expected: 0 }
 
   const { min, max } = spec
@@ -150,7 +162,7 @@ export function validateFunctionArgCount(funcName, argCount) {
   if (argCount < min) {
     return { valid: false, expected: formatExpected(min, max) }
   }
-  if (max !== null && argCount > max) {
+  if (max != null && argCount > max) {
     return { valid: false, expected: formatExpected(min, max) }
   }
 
@@ -165,12 +177,21 @@ export function validateFunctionArgCount(funcName, argCount) {
  */
 export function isKnownFunction(funcName, functions) {
   // Check built-in functions
-  if (isAggregateFunc(funcName) || isMathFunc(funcName) || isStringFunc(funcName)) {
+  if (
+    isAggregateFunc(funcName) ||
+    isMathFunc(funcName) ||
+    isStringFunc(funcName) ||
+    isRegexpFunc(funcName)
+  ) {
     return true
   }
 
-  // Special case: CAST is not in any function list but is a built-in
-  if (funcName === 'CAST') {
+  // Date/time, JSON, conditional, and CAST functions
+  if ([
+    'CURRENT_DATE', 'CURRENT_TIME', 'CURRENT_TIMESTAMP',
+    'JSON_VALUE', 'JSON_QUERY', 'JSON_OBJECT',
+    'COALESCE', 'CAST',
+  ].includes(funcName)) {
     return true
   }
 
@@ -190,5 +211,5 @@ export const RESERVED_AFTER_COLUMN = new Set([
 // Keywords that cannot be used as table aliases
 export const RESERVED_AFTER_TABLE = new Set([
   'WHERE', 'GROUP', 'HAVING', 'ORDER', 'LIMIT', 'OFFSET', 'JOIN', 'INNER',
-  'LEFT', 'RIGHT', 'FULL', 'CROSS', 'ON',
+  'LEFT', 'RIGHT', 'FULL', 'CROSS', 'ON', 'POSITIONAL',
 ])

package/src/validationErrors.js

@@ -19,6 +19,9 @@ export const FUNCTION_SIGNATURES = {
   SUBSTRING: 'string, start[, length]',
   SUBSTR: 'string, start[, length]',
   CONCAT: 'value1, value2[, ...]',
+  LEFT: 'string, length',
+  RIGHT: 'string, length',
+  INSTR: 'string, substring',
 
   // Date/time functions
   RANDOM: '',