squirreling 0.7.6 → 0.7.8

package/README.md

@@ -10,22 +10,13 @@
 ![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 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
-
-- Lightweight and fast
-- Easy to integrate with frontend applications
-- Lets you move query execution closer to your users
-- Supports standard SQL queries
-- Async streaming for large datasets
-- Native javascript Promises, AsyncGenerators, AbortSignals
-- Async user-defined functions (UDFs)
-- Constant memory usage for simple queries with LIMIT
-- Robust error handling and validation designed for LLM tool use
-- In-memory data option for simple use cases
-- Late materialization for efficiency
-- Select only
+Squirreling is a streaming async SQL engine in pure JavaScript. Built for the browser from the ground up: streaming input and output, pluggable data sources, and lazy async cell evaluation. This makes Squirreling ideal for querying data from network sources, APIs, or LLMs where latency and cost matter.
+
+- **Standard SQL**: Full SQL support for querying data (read-only)
+- **Async UDFs**: User-defined functions can call APIs or models
+- **Tiny**: 13 kb bundle, zero dependencies, instant startup
+
+The key idea is **cell-level lazy evaluation**: rows are native AsyncGenerators and cells are async thunks `() => Promise<T>`. This means expensive operations only execute for cells that actually appear in your query results. Unlike WebAssembly databases, Squirreling is fully async with true streaming during network fetches.
 
 ## Usage
 
@@ -75,7 +66,28 @@ console.log(`Collected rows:`, rows)
 // Collected rows: [ { active: true, cnt: 2 }, { active: false, cnt: 1 } ]
 ```
 
-## Supported SQL Features
+### User-Defined Functions
+
+Pass custom functions via the `functions` option. UDFs can be sync or async, making them ideal for calling APIs, models, or other external services:
+
+```javascript
+const rows = await collect(executeSql({
+  tables: { products },
+  query: 'SELECT name,AI_SCORE(description) AS score FROM products',
+  functions: {
+    AI_SCORE: {
+      apply: async (text) => completions(`Rate the following product description from 1 to 10: ${text}`),
+      arguments: { min: 1, max: 1 },
+    },
+  },
+}))
+```
+
+Because Squirreling uses lazy cell evaluation, the `AI_SCORE` function only executes for cells that are actually materialized. Combined with `LIMIT` or `WHERE`, you can efficiently query expensive operations.
+
+## Supported SQL Syntax
+
+Squirreling mostly follows the SQL standard. The following features are supported:
 
 - `SELECT` statements with `WHERE`, `ORDER BY`, `LIMIT`, `OFFSET`
 - `WITH` clause for Common Table Expressions (CTEs)
@@ -87,7 +99,7 @@ console.log(`Collected rows:`, rows)
 
 - 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`
+- Math: `ABS`, `SIGN`, `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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "description": "Squirreling SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -37,11 +37,11 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "25.0.6",
-    "@vitest/coverage-v8": "4.0.16",
+    "@types/node": "25.0.9",
+    "@vitest/coverage-v8": "4.0.17",
     "eslint": "9.39.2",
     "eslint-plugin-jsdoc": "62.0.0",
     "typescript": "5.9.3",
-    "vitest": "4.0.16"
+    "vitest": "4.0.17"
   }
 }

package/src/execute/expression.js

@@ -178,7 +178,7 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
           count++
         }
 
-        if (funcName === 'SUM') return sum
+        if (funcName === 'SUM') return count === 0 ? null : sum
         if (funcName === 'AVG') return count === 0 ? null : sum / count
         if (funcName === 'MIN') return min
         if (funcName === 'MAX') return max
@@ -403,7 +403,7 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
     const exprVal = await evaluateExpr({ node: node.expr, row, tables, functions, rowIndex, rows })
     for (const valueNode of node.values) {
       const val = await evaluateExpr({ node: valueNode, row, tables, functions, rowIndex, rows })
-      if (exprVal === val) return true
+      if (exprVal == val) return true
     }
     return false
   }
@@ -413,7 +413,7 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
     const results = executeSelect({ select: node.subquery, tables })
     for await (const resRow of results) {
       const value = await resRow.cells[resRow.columns[0]]()
-      if (exprVal === value) return true
+      if (exprVal == value) return true
     }
     return false
   }
@@ -439,7 +439,7 @@ export async function evaluateExpr({ node, row, tables, functions, rowIndex, row
       if (caseValue !== undefined) {
         // Simple CASE: compare caseValue with condition
         const whenValue = await evaluateExpr({ node: whenClause.condition, row, tables, functions, rowIndex, rows })
-        conditionResult = caseValue === whenValue
+        conditionResult = caseValue == whenValue
       } else {
         // Searched CASE: evaluate condition as boolean
         conditionResult = await evaluateExpr({ node: whenClause.condition, row, tables, functions, rowIndex, rows })

package/src/execute/math.js

@@ -23,12 +23,27 @@ export function evaluateMathFunc({ funcName, args }) {
     return Math.ceil(Number(val))
   }
 
+  if (funcName === 'ROUND') {
+    const val = args[0]
+    if (val == null) return null
+    const decimals = args[1] ?? 0
+    if (decimals == null) return null
+    const multiplier = 10 ** Number(decimals)
+    return Math.round(Number(val) * multiplier) / multiplier
+  }
+
   if (funcName === 'ABS') {
     const val = args[0]
     if (val == null) return null
     return Math.abs(Number(val))
   }
 
+  if (funcName === 'SIGN') {
+    const val = args[0]
+    if (val == null) return null
+    return Math.sign(Number(val))
+  }
+
   if (funcName === 'MOD') {
     const dividend = args[0]
     const divisor = args[1]

package/src/parse/parse.js

@@ -214,8 +214,7 @@ function parseFromSubquery(state) {
   expect(state, 'paren', '(')
   const query = parseSelectInternal(state)
   expect(state, 'paren', ')')
-  expect(state, 'keyword', 'AS')
-  const alias = expectIdentifier(state).value
+  const alias = parseTableAlias(state)
   return { kind: 'subquery', query, alias }
 }
 

package/src/types.d.ts

@@ -217,7 +217,9 @@ export type MathFunc =
   | 'FLOOR'
   | 'CEIL'
   | 'CEILING'
+  | 'ROUND'
   | 'ABS'
+  | 'SIGN'
   | 'MOD'
   | 'EXP'
   | 'LN'

package/src/validation.js

@@ -22,7 +22,7 @@ export function isRegexpFunc(name) {
  */
 export function isMathFunc(name) {
   return [
-    'FLOOR', 'CEIL', 'CEILING', 'ABS', 'MOD', 'EXP', 'LN', 'LOG10', 'POWER', 'SQRT',
+    'FLOOR', 'CEIL', 'CEILING', 'ROUND', 'ABS', 'SIGN', 'MOD', 'EXP', 'LN', 'LOG10', 'POWER', 'SQRT',
     'SIN', 'COS', 'TAN', 'COT', 'ASIN', 'ACOS', 'ATAN', 'ATAN2', 'DEGREES', 'RADIANS', 'PI',
     'RAND', 'RANDOM',
   ].includes(name)
@@ -88,7 +88,9 @@ export const FUNCTION_ARG_COUNTS = {
   FLOOR: { min: 1, max: 1 },
   CEIL: { min: 1, max: 1 },
   CEILING: { min: 1, max: 1 },
+  ROUND: { min: 1, max: 2 },
   ABS: { min: 1, max: 1 },
+  SIGN: { min: 1, max: 1 },
   MOD: { min: 2, max: 2 },
   EXP: { min: 1, max: 1 },
   LN: { min: 1, max: 1 },

package/src/validationErrors.js

@@ -34,6 +34,7 @@ export const FUNCTION_SIGNATURES = {
   FLOOR: 'number',
   CEIL: 'number',
   CEILING: 'number',
+  ROUND: 'number[, decimals]',
   ABS: 'number',
   MOD: 'dividend, divisor',
   EXP: 'number',