squirreling 0.1.2 → 0.2.0

package/README.md

@@ -24,12 +24,12 @@ Squirreling is a lightweight SQL engine for JavaScript applications, designed to
 ```javascript
 import { executeSql } from 'squirreling'
 
-const data = [
+const source = [
   { id: 1, name: 'Alice' },
   { id: 2, name: 'Bob' },
 ]
 
-const result = executeSql(data, 'SELECT UPPER(name) AS name_upper FROM users')
+const result = executeSql({ source, sql: 'SELECT UPPER(name) AS name_upper FROM users' })
 console.log(result)
 // Output: [ { name_upper: 'ALICE' }, { name_upper: 'BOB' } ]
 ```

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "squirreling",
-  "version": "0.1.2",
+  "version": "0.2.0",
+  "description": "",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
+  "keywords": [
+    "sql",
+    "data",
+    "dataset",
+    "hyperparam",
+    "hyparquet",
+    "parquet"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/backend/memory.js

@@ -0,0 +1,37 @@
+/**
+ * @import { DataSource, RowSource } from '../types.js'
+ */
+
+/**
+ * Creates a row accessor that wraps a plain JavaScript object
+ *
+ * @param {Record<string, any>} obj - the plain object
+ * @returns {RowSource} a row accessor interface
+ */
+export function createRowAccessor(obj) {
+  return {
+    getCell(name) {
+      return obj[name]
+    },
+    getKeys() {
+      return Object.keys(obj)
+    },
+  }
+}
+
+/**
+ * Creates a memory-backed data source from an array of plain objects
+ *
+ * @param {Record<string, any>[]} data - array of plain objects
+ * @returns {DataSource} a data source interface
+ */
+export function createMemorySource(data) {
+  return {
+    getNumRows() {
+      return data.length
+    },
+    getRow(index) {
+      return createRowAccessor(data[index])
+    },
+  }
+}

package/src/execute/aggregates.js

@@ -3,9 +3,9 @@ import { evaluateExpr } from './expression.js'
 /**
  * Evaluates an aggregate function over a set of rows
  *
- * @import { AggregateColumn, ExprNode, Row } from '../types.js'
+ * @import { AggregateColumn, ExprNode, RowSource } from '../types.js'
  * @param {AggregateColumn} col - aggregate column definition
- * @param {Row[]} rows - rows to aggregate
+ * @param {RowSource[]} rows - rows to aggregate
  * @returns {number | null} aggregated result
  */
 export function evaluateAggregate(col, rows) {
@@ -77,8 +77,7 @@ export function defaultAggregateAlias(col) {
  * @param {ExprNode} expr
  * @returns {string}
  */
-export
-function defaultAggregateAliasExpr(expr) {
+export function defaultAggregateAliasExpr(expr) {
   if (expr.type === 'identifier') {
     return expr.name
   }

package/src/execute/execute.js

@@ -1,27 +1,30 @@
 /**
- * @import { FunctionColumn, FunctionNode, OrderByItem, Row, SelectStatement, SqlPrimitive } from '../types.js'
+ * @import { DataSource, ExecuteSqlOptions, FunctionColumn, FunctionNode, OrderByItem, RowSource, SelectStatement, SqlPrimitive } from '../types.js'
  */
 
 import { defaultAggregateAlias, evaluateAggregate } from './aggregates.js'
 import { evaluateExpr } from './expression.js'
 import { createHavingContext, evaluateHavingExpr } from './having.js'
 import { parseSql } from '../parse/parse.js'
+import { createMemorySource, createRowAccessor } from '../backend/memory.js'
 
 /**
- * Executes a SQL SELECT query against an array of data rows
- * @param {Row[]} rows - The data rows to query
- * @param {string} sql - The SQL query string
- * @returns {Row[]} The result rows matching the query
+ * Executes a SQL SELECT query against a data source
+ *
+ * @param {ExecuteSqlOptions} options - the execution options
+ * @returns {Record<string, any>[]} the result rows matching the query
  */
-export function executeSql(rows, sql) {
+export function executeSql({ source, sql }) {
   const select = parseSql(sql)
-  return evaluateSelectAst(select, rows)
+  const dataSource = Array.isArray(source) ? createMemorySource(source) : source
+  return evaluateSelectAst(select, dataSource)
 }
 
 /**
  * Generates a default alias name for a string function
- * @param {FunctionColumn} col - The function column definition
- * @returns {string} The generated alias (e.g., "upper_name", "concat_a_b")
+ *
+ * @param {FunctionColumn} col - the function column definition
+ * @returns {string} the generated alias (e.g., "upper_name", "concat_a_b")
  */
 function defaultFunctionAlias(col) {
   const base = col.func.toLowerCase()
@@ -37,8 +40,9 @@ function defaultFunctionAlias(col) {
 
 /**
  * Creates a stable string key for a row to enable deduplication
- * @param {Row} row - The data row
- * @returns {string} A stable string representation of the row
+ *
+ * @param {Record<string, any>} row
+ * @returns {string} a stable string representation of the row
  */
 function stableRowKey(row) {
   const keys = Object.keys(row).sort()
@@ -53,9 +57,10 @@ function stableRowKey(row) {
 
 /**
  * Compares two SQL values for sorting
- * @param {SqlPrimitive} a - First value to compare
- * @param {SqlPrimitive} b - Second value to compare
- * @returns {number} Negative if a < b, positive if a > b, 0 if equal
+ *
+ * @param {SqlPrimitive} a
+ * @param {SqlPrimitive} b
+ * @returns {number} negative if a < b, positive if a > b, 0 if equal
  */
 function compareValues(a, b) {
   if (a === b) return 0
@@ -77,15 +82,16 @@ function compareValues(a, b) {
 
 /**
  * Applies DISTINCT filtering to remove duplicate rows
- * @param {Row[]} rows - The input rows
+ *
+ * @param {Record<string, any>[]} rows - The input rows
  * @param {boolean} distinct - Whether to apply deduplication
- * @returns {Row[]} The deduplicated rows
+ * @returns {Record<string, any>[]} The deduplicated rows
  */
 function applyDistinct(rows, distinct) {
   if (!distinct) return rows
   /** @type {Set<string>} */
   const seen = new Set()
-  /** @type {Row[]} */
+  /** @type {Record<string, any>[]} */
   const result = []
   for (const row of rows) {
     const key = stableRowKey(row)
@@ -98,20 +104,20 @@ function applyDistinct(rows, distinct) {
 
 /**
  * Applies ORDER BY sorting to rows
- * @param {Row[]} rows - The input rows
- * @param {OrderByItem[]} orderBy - The sort specifications
- * @returns {Row[]} The sorted rows
+ *
+ * @param {Record<string, any>[]} rows - the input rows
+ * @param {OrderByItem[]} orderBy - the sort specifications
+ * @returns {Record<string, any>[]} the sorted rows
  */
 function applyOrderBy(rows, orderBy) {
-  if (!orderBy || orderBy.length === 0) return rows
+  if (!orderBy?.length) return rows
 
   const sorted = rows.slice()
-
   sorted.sort((a, b) => {
     for (const term of orderBy) {
       const dir = term.direction
-      const av = evaluateExpr(term.expr, a)
-      const bv = evaluateExpr(term.expr, b)
+      const av = evaluateExpr(term.expr, createRowAccessor(a))
+      const bv = evaluateExpr(term.expr, createRowAccessor(b))
       const cmp = compareValues(av, bv)
       if (cmp !== 0) {
         return dir === 'DESC' ? -cmp : cmp
@@ -125,41 +131,41 @@ function applyOrderBy(rows, orderBy) {
 
 /**
  * Evaluates a parsed SELECT AST against data rows
- * @param {SelectStatement} select - The parsed SQL AST
- * @param {Row[]} rows - The data rows
- * @returns {Row[]} The filtered, projected, and sorted result rows
+ *
+ * @param {SelectStatement} select - the parsed SQL AST
+ * @param {DataSource} dataSource - the data source
+ * @returns {Record<string, any>[]} the filtered, projected, and sorted result rows
  */
-function evaluateSelectAst(select, rows) {
+function evaluateSelectAst(select, dataSource) {
   // Check for unsupported JOIN operations
   if (select.joins.length) {
     throw new Error('JOIN is not supported')
   }
 
-  // WHERE
-  let working = rows
-  if (select.where) {
-    /** @type {Row[]} */
-    const filtered = []
-    for (const row of rows) {
-      if (evaluateExpr(select.where, row)) {
-        filtered.push(row)
-      }
+  // WHERE clause filtering
+  /** @type {RowSource[]} */
+  const working = []
+  const length = dataSource.getNumRows()
+  for (let i = 0; i < length; i++) {
+    const row = dataSource.getRow(i)
+    if (!select.where || evaluateExpr(select.where, row)) {
+      working.push(row)
     }
-    working = filtered
   }
 
   const hasAggregate = select.columns.some(col => col.kind === 'aggregate')
   const useGrouping = hasAggregate || select.groupBy?.length > 0
 
-  /** @type {Row[]} */
+  /** @type {Record<string, any>[]} */
   const projected = []
 
   if (useGrouping) {
-    /** @type {Row[][]} */
+    // Grouping due to GROUP BY or aggregate functions
+    /** @type {RowSource[][]} */
     const groups = []
 
     if (select.groupBy?.length) {
-      /** @type {Map<string, Row[]>} */
+      /** @type {Map<string, RowSource[]>} */
       const map = new Map()
       for (const row of working) {
         /** @type {string[]} */
@@ -187,14 +193,16 @@ function evaluateSelectAst(select, rows) {
     }
 
     for (const group of groups) {
-      /** @type {Row} */
+      /** @type {Record<string, any>} */
       const resultRow = {}
       for (const col of select.columns) {
         if (col.kind === 'star') {
-          const firstRow = group[0] || {}
-          const keys = Object.keys(firstRow)
-          for (const key of keys) {
-            resultRow[key] = firstRow[key]
+          const firstRow = group[0]
+          if (firstRow) {
+            const keys = firstRow.getKeys()
+            for (const key of keys) {
+              resultRow[key] = firstRow.getCell(key)
+            }
           }
           continue
         }
@@ -203,7 +211,7 @@ function evaluateSelectAst(select, rows) {
           const name = col.column
           const alias = col.alias ?? name
           // Evaluate on first row of group (all rows have same value for GROUP BY columns)
-          resultRow[alias] = group.length > 0 ? group[0][name] : undefined
+          resultRow[alias] = group[0]?.getCell(name)
           continue
         }
 
@@ -245,19 +253,20 @@ function evaluateSelectAst(select, rows) {
       projected.push(resultRow)
     }
   } else {
+    // No grouping, simple projection
     for (const row of working) {
-      /** @type {Row} */
+      /** @type {Record<string, any>} */
       const outRow = {}
       for (const col of select.columns) {
         if (col.kind === 'star') {
-          const keys = Object.keys(row)
+          const keys = row.getKeys()
           for (const key of keys) {
-            outRow[key] = row[key]
+            outRow[key] = row.getCell(key)
           }
         } else if (col.kind === 'column') {
           const name = col.column
           const alias = col.alias ?? name
-          outRow[alias] = row[name]
+          outRow[alias] = row.getCell(name)
         } else if (col.kind === 'function') {
           /** @type {FunctionNode} */
           const funcNode = { type: 'function', name: col.func, args: col.args }

package/src/execute/expression.js

@@ -2,9 +2,9 @@
 /**
  * Evaluates an expression node against a row of data
  *
- * @import { ExprNode, Row, SqlPrimitive } from '../types.js'
+ * @import { ExprNode, RowSource, SqlPrimitive } from '../types.js'
  * @param {ExprNode} node - The expression node to evaluate
- * @param {Row} row - The data row to evaluate against
+ * @param {RowSource} row - The data row to evaluate against
  * @returns {SqlPrimitive} The result of the evaluation
  */
 export function evaluateExpr(node, row) {
@@ -13,9 +13,10 @@ export function evaluateExpr(node, row) {
   }
 
   if (node.type === 'identifier') {
-    return row[node.name]
+    return row.getCell(node.name)
   }
 
+  // Unary operators
   if (node.type === 'unary') {
     if (node.op === 'NOT') {
       return !evaluateExpr(node.argument, row)
@@ -33,6 +34,7 @@ export function evaluateExpr(node, row) {
     }
   }
 
+  // Binary operators
   if (node.type === 'binary') {
     if (node.op === 'AND') {
       const leftVal = evaluateExpr(node.left, row)

package/src/execute/having.js

@@ -1,35 +1,56 @@
 /**
- * @import { ExprNode, Row, SqlPrimitive } from '../types.js'
+ * @import { AggregateFunc, ExprNode, RowSource, SqlPrimitive } from '../types.js'
  */
 
+import { isAggregateFunc } from '../validation.js'
 import { evaluateExpr } from './expression.js'
 
 /**
  * Creates a context for evaluating HAVING expressions
- * @param {Row} resultRow - The aggregated result row
- * @param {Row[]} group - The group of rows
- * @returns {Row} A context row for HAVING evaluation
+ *
+ * @param {Record<string, any>} resultRow - the aggregated result row
+ * @param {RowSource[]} group - the group of rows
+ * @returns {RowSource} a context row for HAVING evaluation
  */
 export function createHavingContext(resultRow, group) {
   // Include the first row of the group (for GROUP BY columns)
-  const firstRow = group[0] || {}
+  const firstRow = group[0]
+  /** @type {Record<string, any>} */
+  const context = {}
+  if (firstRow) {
+    const keys = firstRow.getKeys()
+    for (const key of keys) {
+      context[key] = firstRow.getCell(key)
+    }
+  }
   // Merge with result row (which has aggregates computed)
-  return { ...firstRow, ...resultRow }
+  Object.assign(context, resultRow)
+
+  // Return a Row accessor wrapping the context
+  return {
+    getCell(name) {
+      return context[name]
+    },
+    getKeys() {
+      return Object.keys(context)
+    },
+  }
 }
 
 /**
  * Evaluates a HAVING expression with support for aggregate functions
- * @param {ExprNode} expr - The HAVING expression
- * @param {Row} context - The context row with aggregated values
- * @param {Row[]} group - The group of rows for re-evaluating aggregates
- * @returns {boolean} Whether the HAVING condition is satisfied
+ *
+ * @param {ExprNode} expr - the HAVING expression
+ * @param {RowSource} context - the context row with aggregated values
+ * @param {RowSource[]} group - the group of rows for re-evaluating aggregates
+ * @returns {boolean} whether the HAVING condition is satisfied
  */
 export function evaluateHavingExpr(expr, context, group) {
   // For HAVING, we need special handling of aggregate functions
   // They need to be re-evaluated against the group
   if (expr.type === 'function') {
     const funcName = expr.name.toUpperCase()
-    if (['COUNT', 'SUM', 'AVG', 'MIN', 'MAX'].includes(funcName)) {
+    if (isAggregateFunc(funcName)) {
       // Evaluate aggregate function on the group
       return Boolean(evaluateAggregateFunction(funcName, expr.args, group))
     }
@@ -103,15 +124,16 @@ export function evaluateHavingExpr(expr, context, group) {
 
 /**
  * Evaluates a value in a HAVING expression
- * @param {ExprNode} expr - The expression
- * @param {Row} context - The context row
- * @param {Row[]} group - The group of rows
- * @returns {SqlPrimitive} The evaluated value
+ *
+ * @param {ExprNode} expr
+ * @param {RowSource} context - the context row
+ * @param {RowSource[]} group - the group of rows
+ * @returns {SqlPrimitive} the evaluated value
  */
 function evaluateHavingValue(expr, context, group) {
   if (expr.type === 'function') {
     const funcName = expr.name.toUpperCase()
-    if (['COUNT', 'SUM', 'AVG', 'MIN', 'MAX'].includes(funcName)) {
+    if (isAggregateFunc(funcName)) {
       return evaluateAggregateFunction(funcName, expr.args, group)
     }
   }
@@ -126,10 +148,11 @@ function evaluateHavingValue(expr, context, group) {
 
 /**
  * Evaluates an aggregate function on a group
- * @param {string} funcName - The aggregate function name
- * @param {ExprNode[]} args - The function arguments
- * @param {Row[]} group - The group of rows
- * @returns {SqlPrimitive} The aggregate result
+ *
+ * @param {AggregateFunc} funcName - aggregate function name
+ * @param {ExprNode[]} args - function arguments
+ * @param {RowSource[]} group - the group of rows
+ * @returns {SqlPrimitive} the aggregate result
  */
 function evaluateAggregateFunction(funcName, args, group) {
   if (funcName === 'COUNT') {

package/src/index.d.ts

@@ -1,4 +1,4 @@
-import type { Row, SelectStatement } from './types.js'
+import type { RowSource, SelectStatement } from './types.js'
 
 /**
  * Executes a SQL SELECT query against an array of data rows
@@ -7,7 +7,7 @@ import type { Row, SelectStatement } from './types.js'
  * @param sql - SQL query string
  * @returns rows matching the query
  */
-export function executeSql(rows: Row[], sql: string): Row[]
+export function executeSql(rows: RowSource[], sql: string): RowSource[]
 
 /**
  * Parses a SQL query string into an abstract syntax tree

package/src/parse/parse.js

@@ -4,6 +4,7 @@
 
 import { tokenize } from './tokenize.js'
 import { parseExpression, parsePrimary } from './expression.js'
+import { isAggregateFunc, isStringFunc } from '../validation.js'
 
 // Keywords that cannot be used as implicit aliases after a column
 const RESERVED_AFTER_COLUMN = new Set([
@@ -522,19 +523,3 @@ function parseError(state, expected) {
   const after = prevToken ? ` after "${prevToken.originalValue ?? prevToken.value}"` : ''
   return new Error(`Expected ${expected}${after} at position ${tok.position}`)
 }
-
-/**
- * @param {string} name
- * @returns {name is AggregateFunc}
- */
-function isAggregateFunc(name) {
-  return ['COUNT', 'SUM', 'AVG', 'MIN', 'MAX'].includes(name)
-}
-
-/**
- * @param {string} name
- * @returns {name is StringFunc}
- */
-function isStringFunc(name) {
-  return ['UPPER', 'LOWER', 'CONCAT', 'LENGTH', 'SUBSTRING', 'TRIM'].includes(name)
-}

package/src/types.d.ts

@@ -1,4 +1,17 @@
-export type Row = Record<string, any>
+export interface RowSource {
+  getCell(name: string): any
+  getKeys(): string[]
+}
+
+export interface DataSource {
+  getNumRows(): number
+  getRow(index: number): RowSource
+}
+
+export interface ExecuteSqlOptions {
+  source: Record<string, any>[] | DataSource
+  sql: string
+}
 
 export type SqlPrimitive = string | number | bigint | boolean | null
 

package/src/validation.js

@@ -0,0 +1,17 @@
+
+/**
+ * @import {AggregateFunc, StringFunc} from './types.js'
+ * @param {string} name
+ * @returns {name is AggregateFunc}
+ */
+export function isAggregateFunc(name) {
+  return ['COUNT', 'SUM', 'AVG', 'MIN', 'MAX'].includes(name)
+}
+
+/**
+ * @param {string} name
+ * @returns {name is StringFunc}
+ */
+export function isStringFunc(name) {
+  return ['UPPER', 'LOWER', 'CONCAT', 'LENGTH', 'SUBSTRING', 'TRIM'].includes(name)
+}