squirreling 0.4.8 → 0.6.0

package/README.md

@@ -40,7 +40,10 @@ const users = [
   // ...more rows
 ]
 
-type AsyncRow = Record<string, AsyncCell>
+interface AsyncRow {
+  columns: string[]
+  cells: Record<string, AsyncCell>
+}
 type AsyncCell = () => Promise<SqlPrimitive>
 
 // Returns an async iterable of rows with async cells
@@ -76,6 +79,7 @@ console.log(allUsers)
 - `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.4.8",
+  "version": "0.6.0",
   "description": "Squirreling SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -37,10 +37,10 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "24.10.1",
+    "@types/node": "24.10.2",
     "@vitest/coverage-v8": "4.0.15",
     "eslint": "9.39.1",
-    "eslint-plugin-jsdoc": "61.4.2",
+    "eslint-plugin-jsdoc": "61.5.0",
     "typescript": "5.9.3",
     "vitest": "4.0.15"
   }

package/src/backend/dataSource.js

@@ -1,5 +1,5 @@
 /**
- * @import { AsyncDataSource, AsyncRow, SqlPrimitive } from '../types.js'
+ * @import { AsyncCell, AsyncCells, AsyncDataSource, AsyncRow, SqlPrimitive } from '../types.js'
  */
 
 
@@ -11,7 +11,7 @@
  */
 export function generatorSource(gen) {
   return {
-    async *getRows() {
+    async *scan() {
       yield* gen
     },
   }
@@ -24,12 +24,12 @@ export function generatorSource(gen) {
  * @returns {AsyncRow} a row accessor interface
  */
 function asyncRow(obj) {
-  /** @type {AsyncRow} */
-  const row = {}
+  /** @type {AsyncCells} */
+  const cells = {}
   for (const [key, value] of Object.entries(obj)) {
-    row[key] = () => Promise.resolve(value)
+    cells[key] = () => Promise.resolve(value)
   }
-  return row
+  return { columns: Object.keys(obj), cells }
 }
 
 /**
@@ -40,7 +40,7 @@ function asyncRow(obj) {
  */
 export function memorySource(data) {
   return {
-    async *getRows() {
+    async *scan() {
       for (const item of data) {
         yield asyncRow(item)
       }
@@ -60,15 +60,16 @@ export function cachedDataSource(source) {
     /**
      * @yields {AsyncRow}
      */
-    async *getRows() {
+    async *scan() {
       let index = 0
-      for await (const row of source.getRows()) {
+      for await (const row of source.scan()) {
         const rowIndex = index
-        /** @type {AsyncRow} */
-        const out = {}
-        for (const [key, cell] of Object.entries(row)) {
+        /** @type {AsyncCells} */
+        const cells = {}
+        for (const key of row.columns) {
+          const cell = row.cells[key]
           // Wrap the cell to cache accesses
-          out[key] = () => {
+          cells[key] = () => {
             const cacheKey = `${rowIndex}:${key}`
             let value = cache.get(cacheKey)
             if (!value) {
@@ -78,7 +79,7 @@ export function cachedDataSource(source) {
             return value
           }
         }
-        yield out
+        yield { columns: row.columns, cells }
         index++
       }
     },

package/src/execute/aggregates.js

@@ -1,4 +1,5 @@
-import { aggregateError, unknownFunctionError } from '../errors.js'
+import { unknownFunctionError } from '../parseErrors.js'
+import { aggregateError } from '../validationErrors.js'
 import { evaluateExpr } from './expression.js'
 import { defaultDerivedAlias, stringify } from './utils.js'
 
@@ -39,7 +40,7 @@ export async function evaluateAggregate({ col, rows, tables }) {
 
   if (func === 'SUM' || func === 'AVG' || func === 'MIN' || func === 'MAX') {
     if (arg.kind === 'star') {
-      throw aggregateError(func, '(*) is not supported, use a column name')
+      throw aggregateError({ funcName: func, issue: '(*) is not supported, use a column name' })
     }
     let sum = 0
     let count = 0
@@ -73,7 +74,7 @@ export async function evaluateAggregate({ col, rows, tables }) {
 
   if (func === 'JSON_ARRAYAGG') {
     if (arg.kind === 'star') {
-      throw aggregateError('JSON_ARRAYAGG', '(*) is not supported, use a column name or expression')
+      throw aggregateError({ funcName: 'JSON_ARRAYAGG', issue: '(*) is not supported, use a column name or expression' })
     }
     /** @type {SqlPrimitive[]} */
     const values = []
@@ -96,7 +97,12 @@ export async function evaluateAggregate({ col, rows, tables }) {
     return values
   }
 
-  throw unknownFunctionError(func, undefined, 'COUNT, SUM, AVG, MIN, MAX, JSON_ARRAYAGG')
+  throw unknownFunctionError({
+    funcName: func,
+    positionStart: 0,
+    positionEnd: 0,
+    validFunctions: 'COUNT, SUM, AVG, MIN, MAX, JSON_ARRAYAGG',
+  })
 }
 
 /**

package/src/execute/execute.js

@@ -1,4 +1,5 @@
-import { missingClauseError, tableNotFoundError, unsupportedOperationError } from '../errors.js'
+import { missingClauseError } from '../parseErrors.js'
+import { tableNotFoundError, unsupportedOperationError } from '../executionErrors.js'
 import { generatorSource, memorySource } from '../backend/dataSource.js'
 import { parseSql } from '../parse/parse.js'
 import { defaultAggregateAlias, evaluateAggregate } from './aggregates.js'
@@ -9,7 +10,7 @@ import { executeJoins } from './join.js'
 import { compareForTerm, defaultDerivedAlias, stringify } from './utils.js'
 
 /**
- * @import { AsyncDataSource, AsyncRow, ExecuteSqlOptions, OrderByItem, QueryHints, SelectStatement, SqlPrimitive } from '../types.js'
+ * @import { AsyncCells, AsyncDataSource, AsyncRow, ExecuteSqlOptions, OrderByItem, QueryHints, SelectStatement, SqlPrimitive } from '../types.js'
  */
 
 /**
@@ -19,7 +20,7 @@ import { compareForTerm, defaultDerivedAlias, stringify } from './utils.js'
  * @yields {AsyncRow} async generator yielding result rows
  */
 export async function* executeSql({ tables, query }) {
-  const select = parseSql(query)
+  const select = typeof query === 'string' ? parseSql(query) : query
 
   // Check for unsupported operations
   if (!select.from) {
@@ -61,7 +62,7 @@ export async function* executeSelect(select, tables) {
     fromTableName = select.from.alias ?? select.from.table
     dataSource = tables[select.from.table]
     if (dataSource === undefined) {
-      throw tableNotFoundError(select.from.table)
+      throw tableNotFoundError({ tableName: select.from.table })
     }
   } else {
     // Nested subquery - recursively resolve
@@ -80,15 +81,15 @@ export async function* executeSelect(select, tables) {
 /**
  * Creates a stable string key for a row to enable deduplication
  *
- * @param {AsyncRow} row
+ * @param {AsyncCells} cells
  * @returns {Promise<string>} a stable string representation of the row
  */
-async function stableRowKey(row) {
-  const keys = Object.keys(row).sort()
+async function stableRowKey(cells) {
+  const keys = Object.keys(cells).sort()
   /** @type {string[]} */
   const parts = []
   for (const k of keys) {
-    const v = await row[k]()
+    const v = await cells[k]()
     parts.push(k + ':' + stringify(v))
   }
   return parts.join('|')
@@ -108,7 +109,7 @@ async function applyDistinct(rows, distinct) {
   /** @type {AsyncRow[]} */
   const result = []
   for (const row of rows) {
-    const key = await stableRowKey(row)
+    const key = await stableRowKey(row.cells)
     if (seen.has(key)) continue
     seen.add(key)
     result.push(row)
@@ -236,6 +237,7 @@ async function* evaluateSelectAst(select, dataSource, tables) {
 async function* evaluateStreaming(select, dataSource, tables) {
   let rowsYielded = 0
   let rowsSkipped = 0
+  let rowIndex = 0
   const offset = select.offset ?? 0
   const limit = select.limit ?? Infinity
   if (limit <= 0) return
@@ -253,10 +255,11 @@ async function* evaluateStreaming(select, dataSource, tables) {
     offset: select.offset,
   }
 
-  for await (const row of dataSource.getRows(hints)) {
+  for await (const row of dataSource.scan(hints)) {
+    rowIndex++
     // WHERE filter
     if (select.where) {
-      const pass = await evaluateExpr({ node: select.where, row, tables })
+      const pass = await evaluateExpr({ node: select.where, row, tables, rowIndex })
       if (!pass) continue
     }
 
@@ -267,16 +270,21 @@ async function* evaluateStreaming(select, dataSource, tables) {
     }
 
     // SELECT projection
-    /** @type {AsyncRow} */
-    const outRow = {}
+    /** @type {string[]} */
+    const columns = []
+    /** @type {AsyncCells} */
+    const cells = {}
+    const currentRowIndex = rowIndex
     for (const col of select.columns) {
       if (col.kind === 'star') {
-        for (const [key, cell] of Object.entries(row)) {
-          outRow[key] = cell
+        for (const key of row.columns) {
+          columns.push(key)
+          cells[key] = row.cells[key]
         }
       } else if (col.kind === 'derived') {
         const alias = col.alias ?? defaultDerivedAlias(col.expr)
-        outRow[alias] = () => evaluateExpr({ node: col.expr, row, tables })
+        columns.push(alias)
+        cells[alias] = () => evaluateExpr({ node: col.expr, row, tables, rowIndex: currentRowIndex })
       } else if (col.kind === 'aggregate') {
         throw new Error(
           'Aggregate functions require GROUP BY or will act on the whole dataset; add GROUP BY or remove aggregates'
@@ -286,7 +294,7 @@ async function* evaluateStreaming(select, dataSource, tables) {
 
     // DISTINCT: skip duplicate rows
     if (seen) {
-      const key = await stableRowKey(outRow)
+      const key = await stableRowKey(cells)
       if (seen.has(key)) continue
       seen.add(key)
       // OFFSET applies to distinct rows
@@ -296,7 +304,7 @@ async function* evaluateStreaming(select, dataSource, tables) {
       }
     }
 
-    yield outRow
+    yield { columns, cells }
     rowsYielded++
     if (rowsYielded >= limit) {
       break
@@ -326,7 +334,7 @@ async function* evaluateBuffered(select, dataSource, tables, hasAggregate, useGr
   // Step 1: Collect all rows from data source
   /** @type {AsyncRow[]} */
   const working = []
-  for await (const row of dataSource.getRows(hints)) {
+  for await (const row of dataSource.scan(hints)) {
     working.push(row)
   }
 
@@ -334,9 +342,11 @@ async function* evaluateBuffered(select, dataSource, tables, hasAggregate, useGr
   /** @type {AsyncRow[]} */
   const filtered = []
 
-  for (const row of working) {
+  for (let i = 0; i < working.length; i++) {
+    const row = working[i]
+    const rowIndex = i + 1 // 1-based
     if (select.where) {
-      const passes = await evaluateExpr({ node: select.where, row, tables })
+      const passes = await evaluateExpr({ node: select.where, row, tables, rowIndex })
 
       if (!passes) {
         continue
@@ -379,21 +389,23 @@ async function* evaluateBuffered(select, dataSource, tables, hasAggregate, useGr
 
     const hasStar = select.columns.some(col => col.kind === 'star')
     if (hasStar && hasAggregate) {
-      throw unsupportedOperationError(
-        'SELECT * with aggregate functions is not supported',
-        'Replace * with specific column names when using aggregate functions.'
-      )
+      throw unsupportedOperationError({
+        operation: 'SELECT * with aggregate functions is not supported',
+        hint: 'Replace * with specific column names when using aggregate functions.',
+      })
     }
 
     for (const group of groups) {
-      /** @type {AsyncRow} */
-      const resultRow = {}
+      const columns = []
+      /** @type {AsyncCells} */
+      const cells = {}
       for (const col of select.columns) {
         if (col.kind === 'star') {
           const firstRow = group[0]
           if (firstRow) {
-            for (const [key, cell] of Object.entries(firstRow)) {
-              resultRow[key] = cell
+            for (const key of firstRow.columns) {
+              columns.push(key)
+              cells[key] = firstRow.cells[key]
             }
           }
           continue
@@ -401,29 +413,32 @@ async function* evaluateBuffered(select, dataSource, tables, hasAggregate, useGr
 
         if (col.kind === 'derived') {
           const alias = col.alias ?? defaultDerivedAlias(col.expr)
+          columns.push(alias)
           if (group.length > 0) {
-            resultRow[alias] = () => evaluateExpr({ node: col.expr, row: group[0], tables })
+            cells[alias] = () => evaluateExpr({ node: col.expr, row: group[0], tables })
           } else {
-            delete resultRow[alias]
+            delete cells[alias]
           }
           continue
         }
 
         if (col.kind === 'aggregate') {
           const alias = col.alias ?? defaultAggregateAlias(col)
-          resultRow[alias] = () => evaluateAggregate({ col, rows: group, tables })
+          columns.push(alias)
+          cells[alias] = () => evaluateAggregate({ col, rows: group, tables })
           continue
         }
       }
+      const asyncRow = { columns, cells }
 
       // Apply HAVING filter before adding to projected results
       if (select.having) {
-        if (!await evaluateHavingExpr(select.having, resultRow, group, tables)) {
+        if (!await evaluateHavingExpr(select.having, asyncRow, group, tables)) {
           continue
         }
       }
 
-      projected.push(resultRow)
+      projected.push(asyncRow)
     }
   } else {
     // No grouping, simple projection
@@ -440,19 +455,22 @@ async function* evaluateBuffered(select, dataSource, tables, hasAggregate, useGr
     }
 
     for (const row of rowsToProject) {
-      /** @type {AsyncRow} */
-      const outRow = {}
+      const columns = []
+      /** @type {AsyncCells} */
+      const cells = {}
       for (const col of select.columns) {
         if (col.kind === 'star') {
-          for (const [key, cell] of Object.entries(row)) {
-            outRow[key] = cell
+          for (const key of row.columns) {
+            columns.push(key)
+            cells[key] = row.cells[key]
           }
         } else if (col.kind === 'derived') {
           const alias = col.alias ?? defaultDerivedAlias(col.expr)
-          outRow[alias] = () => evaluateExpr({ node: col.expr, row, tables })
+          columns.push(alias)
+          cells[alias] = () => evaluateExpr({ node: col.expr, row, tables })
         }
       }
-      projected.push(outRow)
+      projected.push({ columns, cells })
     }
   }