squirreling 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+The MIT License (MIT)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# Squirreling SQL Engine
+
+[![mit license](https://img.shields.io/badge/License-MIT-orange.svg)](https://opensource.org/licenses/MIT)
+
+Squirreling is a lightweight SQL engine for JavaScript applications, designed to provide efficient and easy-to-use database functionalities in the browser.
+
+## Features
+
+- Lightweight and fast
+- Easy to integrate with JavaScript applications
+- Supports standard SQL queries
+- In-memory database for quick data access
+- Robust error handling and validation
+
+## Usage
+
+```javascript
+import { executeSql } from 'squirreling'
+
+const data = [
+  { id: 1, name: 'Alice' },
+  { id: 2, name: 'Bob' },
+]
+
+const result = executeSql(data, 'SELECT UPPER(name) AS name_upper FROM users')
+console.log(result)
+// Output: [ { name_upper: 'ALICE' }, { name_upper: 'BOB' } ]
+```

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "squirreling",
+  "version": "0.1.0",
+  "author": "Hyperparam",
+  "homepage": "https://hyperparam.app",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hyparam/squirrel.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "types": "src/index.d.ts",
+  "main": "src/index.js",
+  "export": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "coverage": "vitest run --coverage --coverage.include=src",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.1",
+    "@vitest/coverage-v8": "4.0.13",
+    "eslint": "9.39.1",
+    "eslint-plugin-jsdoc": "61.4.0",
+    "typescript": "5.9.3",
+    "vitest": "4.0.13"
+  }
+}

package/src/execute/aggregates.js

@@ -0,0 +1,73 @@
+
+/**
+ * Evaluates an aggregate function over a set of rows
+ *
+ * @import { AggregateColumn, Row } from '../types.js'
+ * @param {AggregateColumn} col - aggregate column definition
+ * @param {Row[]} rows - rows to aggregate
+ * @returns {number | null} aggregated result
+ */
+export function evaluateAggregate(col, rows) {
+  const { arg, func } = col
+
+  if (func === 'COUNT') {
+    if (arg.kind === 'star') return rows.length
+    const field = arg.column
+    let count = 0
+    for (let i = 0; i < rows.length; i += 1) {
+      const v = rows[i][field]
+      if (v !== null && v !== undefined) {
+        count += 1
+      }
+    }
+    return count
+  }
+
+  if (func === 'SUM' || func === 'AVG' || func === 'MIN' || func === 'MAX') {
+    if (arg.kind === 'star') {
+      throw new Error(func + '(*) is not supported, use a column name')
+    }
+    const field = arg.column
+    let sum = 0
+    let count = 0
+    /** @type {number | null} */
+    let min = null
+    /** @type {number | null} */
+    let max = null
+
+    for (let i = 0; i < rows.length; i += 1) {
+      const raw = rows[i][field]
+      if (raw == null) continue
+      const num = Number(raw)
+      if (!Number.isFinite(num)) continue
+
+      if (count === 0) {
+        min = num
+        max = num
+      } else {
+        if (min == null || num < min) min = num
+        if (max == null || num > max) max = num
+      }
+      sum += num
+      count += 1
+    }
+
+    if (func === 'SUM') return sum
+    if (func === 'AVG') return count === 0 ? null : sum / count
+    if (func === 'MIN') return min
+    if (func === 'MAX') return max
+  }
+
+  throw new Error('Unsupported aggregate function ' + func)
+}
+
+/**
+ * Generates a default alias name for an aggregate function
+ * @param {AggregateColumn} col - The aggregate column definition
+ * @returns {string} The generated alias (e.g., "count_all", "sum_amount")
+ */
+export function defaultAggregateAlias(col) {
+  const base = col.func.toLowerCase()
+  if (col.arg.kind === 'star') return base + '_all'
+  return base + '_' + col.arg.column
+}

package/src/execute/execute.js

@@ -0,0 +1,282 @@
+/**
+ * @import { FunctionColumn, FunctionNode, OrderByItem, Row, SelectStatement, SqlPrimitive } from '../types.js'
+ */
+
+import { defaultAggregateAlias, evaluateAggregate } from './aggregates.js'
+import { evaluateExpr } from './expression.js'
+import { parseSql } from '../parse/parse.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
+ */
+export function executeSql(rows, sql) {
+  const select = parseSql(sql)
+  return evaluateSelectAst(select, rows)
+}
+
+/**
+ * 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")
+ */
+function defaultFunctionAlias(col) {
+  const base = col.func.toLowerCase()
+  // Try to extract column names from identifier arguments
+  const columnNames = col.args
+    .filter(arg => arg.type === 'identifier')
+    .map(arg => arg.name)
+  if (columnNames.length > 0) {
+    return base + '_' + columnNames.join('_')
+  }
+  return base
+}
+
+/**
+ * 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
+ */
+function stableRowKey(row) {
+  const keys = Object.keys(row).sort()
+  /** @type {string[]} */
+  const parts = []
+  for (const k of keys) {
+    const v = row[k]
+    parts.push(k + ':' + JSON.stringify(v))
+  }
+  return parts.join('|')
+}
+
+/**
+ * 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
+ */
+function compareValues(a, b) {
+  if (a === b) return 0
+  if (a == null) return -1
+  if (b == null) return 1
+
+  if (typeof a === 'number' && typeof b === 'number') {
+    if (a < b) return -1
+    if (a > b) return 1
+    return 0
+  }
+
+  const as = String(a)
+  const bs = String(b)
+  if (as < bs) return -1
+  if (as > bs) return 1
+  return 0
+}
+
+/**
+ * Applies DISTINCT filtering to remove duplicate rows
+ * @param {Row[]} rows - The input rows
+ * @param {boolean} distinct - Whether to apply deduplication
+ * @returns {Row[]} The deduplicated rows
+ */
+function applyDistinct(rows, distinct) {
+  if (!distinct) return rows
+  /** @type {Set<string>} */
+  const seen = new Set()
+  /** @type {Row[]} */
+  const result = []
+  for (const row of rows) {
+    const key = stableRowKey(row)
+    if (seen.has(key)) continue
+    seen.add(key)
+    result.push(row)
+  }
+  return result
+}
+
+/**
+ * Applies ORDER BY sorting to rows
+ * @param {Row[]} rows - The input rows
+ * @param {OrderByItem[]} orderBy - The sort specifications
+ * @returns {Row[]} The sorted rows
+ */
+function applyOrderBy(rows, orderBy) {
+  if (!orderBy || orderBy.length === 0) 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 cmp = compareValues(av, bv)
+      if (cmp !== 0) {
+        return dir === 'DESC' ? -cmp : cmp
+      }
+    }
+    return 0
+  })
+
+  return sorted
+}
+
+/**
+ * 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
+ */
+function evaluateSelectAst(select, rows) {
+  // 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)
+      }
+    }
+    working = filtered
+  }
+
+  const hasAggregate = select.columns.some(col => col.kind === 'aggregate')
+  const useGrouping = hasAggregate || select.groupBy?.length > 0
+
+  /** @type {Row[]} */
+  const projected = []
+
+  if (useGrouping) {
+    /** @type {Row[][]} */
+    const groups = []
+
+    if (select.groupBy?.length) {
+      /** @type {Map<string, Row[]>} */
+      const map = new Map()
+      for (const row of working) {
+        /** @type {string[]} */
+        const keyParts = []
+        for (const expr of select.groupBy) {
+          const v = evaluateExpr(expr, row)
+          keyParts.push(JSON.stringify(v))
+        }
+        const key = keyParts.join('|')
+        let group = map.get(key)
+        if (!group) {
+          group = []
+          map.set(key, group)
+          groups.push(group)
+        }
+        group.push(row)
+      }
+    } else {
+      groups.push(working)
+    }
+
+    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')
+    }
+
+    for (const group of groups) {
+      /** @type {Row} */
+      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]
+          }
+          continue
+        }
+
+        if (col.kind === 'column') {
+          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
+          continue
+        }
+
+        if (col.kind === 'function') {
+          // Evaluate function on the first row of the group
+          /** @type {FunctionNode} */
+          const funcNode = { type: 'function', name: col.func, args: col.args }
+          const alias = col.alias ?? defaultFunctionAlias(col)
+          const value = group.length > 0 ? evaluateExpr(funcNode, group[0]) : undefined
+          resultRow[alias] = value
+          continue
+        }
+
+        if (col.kind === 'aggregate') {
+          const alias = col.alias ?? defaultAggregateAlias(col)
+          const value = evaluateAggregate(col, group)
+          resultRow[alias] = value
+          continue
+        }
+
+        if (col.kind === 'operation') {
+          const alias = col.alias ?? 'expr'
+          const value = group.length > 0 ? evaluateExpr(col.expr, group[0]) : undefined
+          resultRow[alias] = value
+          continue
+        }
+      }
+      projected.push(resultRow)
+    }
+  } else {
+    for (const row of working) {
+      /** @type {Row} */
+      const outRow = {}
+      for (const col of select.columns) {
+        if (col.kind === 'star') {
+          const keys = Object.keys(row)
+          for (const key of keys) {
+            outRow[key] = row[key]
+          }
+        } else if (col.kind === 'column') {
+          const name = col.column
+          const alias = col.alias ?? name
+          outRow[alias] = row[name]
+        } else if (col.kind === 'function') {
+          /** @type {FunctionNode} */
+          const funcNode = { type: 'function', name: col.func, args: col.args }
+          const value = evaluateExpr(funcNode, row)
+          const alias = col.alias ?? defaultFunctionAlias(col)
+          outRow[alias] = value
+        } else if (col.kind === 'operation') {
+          const alias = col.alias ?? 'expr'
+          const value = evaluateExpr(col.expr, row)
+          outRow[alias] = value
+        } 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'
+          )
+        }
+      }
+      projected.push(outRow)
+    }
+  }
+
+  let result = projected
+
+  result = applyDistinct(result, select.distinct)
+  result = applyOrderBy(result, select.orderBy)
+
+  if (typeof select.offset === 'number' && select.offset > 0) {
+    result = result.slice(select.offset)
+  }
+  if (typeof select.limit === 'number') {
+    result = result.slice(0, select.limit)
+  }
+
+  return result
+}

package/src/execute/expression.js

@@ -0,0 +1,177 @@
+
+/**
+ * Evaluates an expression node against a row of data
+ *
+ * @import { ExprNode, Row, SqlPrimitive } from '../types.js'
+ * @param {ExprNode} node - The expression node to evaluate
+ * @param {Row} row - The data row to evaluate against
+ * @returns {SqlPrimitive} The result of the evaluation
+ */
+export function evaluateExpr(node, row) {
+  if (node.type === 'literal') {
+    return node.value
+  }
+
+  if (node.type === 'identifier') {
+    return row[node.name]
+  }
+
+  if (node.type === 'unary') {
+    if (node.op === 'NOT') {
+      return !evaluateExpr(node.argument, row)
+    }
+    if (node.op === 'IS NULL') {
+      return evaluateExpr(node.argument, row) == null
+    }
+    if (node.op === 'IS NOT NULL') {
+      return evaluateExpr(node.argument, row) != null
+    }
+    if (node.op === '-') {
+      const val = evaluateExpr(node.argument, row)
+      if (val == null) return null
+      return -Number(val)
+    }
+  }
+
+  if (node.type === 'binary') {
+    if (node.op === 'AND') {
+      const leftVal = evaluateExpr(node.left, row)
+      if (!leftVal) return false
+      return Boolean(evaluateExpr(node.right, row))
+    }
+
+    if (node.op === 'OR') {
+      const leftVal = evaluateExpr(node.left, row)
+      if (leftVal) return true
+      return Boolean(evaluateExpr(node.right, row))
+    }
+
+    const left = evaluateExpr(node.left, row)
+    const right = evaluateExpr(node.right, row)
+
+    // In SQL, NULL comparisons with =, !=, <> always return false (unknown)
+    // You must use IS NULL or IS NOT NULL to check for NULL
+    if (left == null || right == null) {
+      if (node.op === '=' || node.op === '!=' || node.op === '<>') {
+        return false
+      }
+    }
+
+    if (node.op === '=') return left === right
+    if (node.op === '!=' || node.op === '<>') return left !== right
+    if (node.op === '<') return left < right
+    if (node.op === '>') return left > right
+    if (node.op === '<=') return left <= right
+    if (node.op === '>=') return left >= right
+
+    if (node.op === 'LIKE') {
+      const str = String(left)
+      const pattern = String(right)
+      // Convert SQL LIKE pattern to regex
+      // % matches zero or more characters
+      // _ matches exactly one character
+      const regexPattern = pattern
+        .replace(/[.*+?^${}()|[\]\\]/g, '\\$&') // Escape regex special chars
+        .replace(/%/g, '.*') // Replace % with .*
+        .replace(/_/g, '.') // Replace _ with .
+      const regex = new RegExp('^' + regexPattern + '$', 'i')
+      return regex.test(str)
+    }
+  }
+
+  // Function calls
+  if (node.type === 'function') {
+    const funcName = node.name.toUpperCase()
+    const args = node.args.map(arg => evaluateExpr(arg, row))
+
+    if (funcName === 'UPPER') {
+      if (args.length !== 1) throw new Error('UPPER requires exactly 1 argument')
+      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')
+      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')
+      // SQL CONCAT returns NULL if any argument is NULL
+      for (let i = 0; i < args.length; i += 1) {
+        if (args[i] == null) return null
+      }
+      return args.map(a => String(a)).join('')
+    }
+
+    if (funcName === 'LENGTH') {
+      if (args.length !== 1) throw new Error('LENGTH requires exactly 1 argument')
+      const val = args[0]
+      if (val == null) return null
+      return String(val).length
+    }
+
+    if (funcName === 'SUBSTRING') {
+      if (args.length < 2 || args.length > 3) {
+        throw new Error('SUBSTRING requires 2 or 3 arguments')
+      }
+      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('SUBSTRING start position must be a positive integer')
+      }
+      // 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('SUBSTRING length must be a non-negative integer')
+        }
+        return strVal.substring(startIdx, startIdx + len)
+      }
+      return strVal.substring(startIdx)
+    }
+
+    if (funcName === 'TRIM') {
+      if (args.length !== 1) throw new Error('TRIM requires exactly 1 argument')
+      const val = args[0]
+      if (val == null) return null
+      return String(val).trim()
+    }
+
+    throw new Error('Unsupported function ' + funcName)
+  }
+
+  if (node.type === 'cast') {
+    const val = evaluateExpr(node.expr, row)
+    if (val == null) return null
+    const toType = node.toType.toUpperCase()
+    if (toType === 'INTEGER' || toType === 'INT') {
+      const num = Number(val)
+      if (isNaN(num)) return null
+      return Math.trunc(num)
+    }
+    if (toType === 'BIGINT') {
+      return BigInt(val)
+    }
+    if (toType === 'FLOAT' || toType === 'REAL' || toType === 'DOUBLE') {
+      const num = Number(val)
+      if (isNaN(num)) return null
+      return num
+    }
+    if (toType === 'TEXT' || toType === 'STRING') {
+      return String(val)
+    }
+    if (toType === 'BOOLEAN' || toType === 'BOOL') {
+      return Boolean(val)
+    }
+    throw new Error('Unsupported CAST to type ' + node.toType)
+  }
+
+  throw new Error('Unknown expression node type ' + node.type)
+}

package/src/index.d.ts

@@ -0,0 +1,18 @@
+import type { Row, SelectStatement } from './types.js'
+
+/**
+ * Executes a SQL SELECT query against an array of data rows
+ *
+ * @param rows - data rows to query as a list of objects
+ * @param sql - SQL query string
+ * @returns rows matching the query
+ */
+export function executeSql(rows: Row[], sql: string): Row[]
+
+/**
+ * Parses a SQL query string into an abstract syntax tree
+ *
+ * @param sql - SQL query string to parse
+ * @returns parsed SQL select statement
+ */
+export function parseSql(sql: string): SelectStatement

package/src/index.js

@@ -0,0 +1,2 @@
+export { executeSql } from './execute/execute.js'
+export { parseSql } from './parse/parse.js'