squirreling 0.12.27 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.12.27",
+  "version": "0.13.0",
   "description": "Squirreling Async SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -42,7 +42,7 @@
     "@types/node": "26.1.0",
     "@vitest/coverage-v8": "4.1.9",
     "eslint": "9.39.4",
-    "eslint-plugin-jsdoc": "63.0.10",
+    "eslint-plugin-jsdoc": "63.0.11",
     "typescript": "6.0.3",
     "vitest": "4.1.9"
   }

package/src/execute/aggregates.js

@@ -101,7 +101,7 @@ export function executeHashAggregate(plan, context) {
       for await (const row of child.rows()) {
         if (++collectCount % YIELD_INTERVAL === 0) {
           await yieldToEventLoop()
-          if (context.signal?.aborted) return
+          context.signal?.throwIfAborted()
         }
         allRows.push(row)
       }
@@ -121,7 +121,7 @@ export function executeHashAggregate(plan, context) {
       for (let chunkStart = 0; chunkStart < allRows.length; chunkStart += YIELD_INTERVAL) {
         if (chunkStart > 0) {
           await yieldToEventLoop()
-          if (context.signal?.aborted) return
+          context.signal?.throwIfAborted()
         }
         const chunkEnd = Math.min(chunkStart + YIELD_INTERVAL, allRows.length)
         const chunkLen = chunkEnd - chunkStart
@@ -227,7 +227,7 @@ export function executeScalarAggregate(plan, context) {
       for await (const row of child.rows()) {
         if (++collectCount % YIELD_INTERVAL === 0) {
           await yieldToEventLoop()
-          if (context.signal?.aborted) return
+          context.signal?.throwIfAborted()
         }
         group.push(row)
       }

package/src/execute/execute.js

@@ -174,7 +174,7 @@ function executeUnnest(plan, context) {
       const value = await evaluateExpr({ node: plan.args[0], row, rowIndex: 1, context })
       if (!Array.isArray(value)) return
       for (const element of value) {
-        if (context.signal?.aborted) return
+        context.signal?.throwIfAborted()
         yield {
           columns,
           cells: { [columnName]: () => Promise.resolve(element) },
@@ -209,7 +209,7 @@ function executeJsonEach(plan, context) {
       }
       if (Array.isArray(parsed)) {
         for (let i = 0; i < parsed.length; i++) {
-          if (context.signal?.aborted) return
+          context.signal?.throwIfAborted()
           const k = i
           const v = parsed[i]
           yield {
@@ -224,7 +224,7 @@ function executeJsonEach(plan, context) {
       }
       if (typeof parsed === 'object' && parsed !== null) {
         for (const [k, v] of Object.entries(parsed)) {
-          if (context.signal?.aborted) return
+          context.signal?.throwIfAborted()
           yield {
             columns,
             cells: {
@@ -294,7 +294,7 @@ function executeScan(plan, context) {
       async *rows() {
         const columns = [column]
         for await (const chunk of chunks) {
-          if (signal?.aborted) return
+          signal?.throwIfAborted()
           for (let i = 0; i < chunk.length; i++) {
             const value = chunk[i]
             yield {
@@ -303,6 +303,9 @@ function executeScan(plan, context) {
             }
           }
         }
+        // A data source may end its stream cooperatively on abort; surface
+        // the abort so a truncated scan is not mistaken for a complete one
+        signal?.throwIfAborted()
       },
     }
   }
@@ -335,6 +338,10 @@ function executeScan(plan, context) {
       }
 
       yield* result
+
+      // A data source may end its stream cooperatively on abort; surface
+      // the abort so a truncated scan is not mistaken for a complete one
+      signal?.throwIfAborted()
     },
   }
 }
@@ -420,10 +427,10 @@ async function* filterRows(rows, condition, context, limit) {
   let buffer = []
 
   for await (const row of rows) {
-    if (context.signal?.aborted) return
+    context.signal?.throwIfAborted()
     if (++innerCount % YIELD_INTERVAL === 0) {
       await yieldToEventLoop()
-      if (context.signal?.aborted) return
+      context.signal?.throwIfAborted()
     }
     rowIndex++
     buffer.push({ row, rowIndex })
@@ -466,10 +473,10 @@ async function* limitRows(rows, limit = Infinity, offset = 0, signal) {
   let yielded = 0
   let innerCount = 0
   for await (const row of rows) {
-    if (signal?.aborted) return
+    signal?.throwIfAborted()
     if (++innerCount % YIELD_INTERVAL === 0) {
       await yieldToEventLoop()
-      if (signal?.aborted) return
+      signal?.throwIfAborted()
     }
     if (skipped < offset) {
       skipped++
@@ -521,10 +528,10 @@ function executeProject(plan, context) {
       let innerCount = 0
 
       for await (const row of child.rows()) {
-        if (context.signal?.aborted) return
+        context.signal?.throwIfAborted()
         if (++innerCount % YIELD_INTERVAL === 0) {
           await yieldToEventLoop()
-          if (context.signal?.aborted) return
+          context.signal?.throwIfAborted()
         }
         rowIndex++
         const currentRowIndex = rowIndex
@@ -614,10 +621,10 @@ function executeDistinct(plan, context) {
       let innerCount = 0
 
       for await (const row of child.rows()) {
-        if (signal?.aborted) return
+        signal?.throwIfAborted()
         if (++innerCount % YIELD_INTERVAL === 0) {
           await yieldToEventLoop()
-          if (signal?.aborted) return
+          signal?.throwIfAborted()
         }
         buffer.push(row)
 
@@ -701,10 +708,10 @@ function executeSetOperation(plan, context) {
           const seen = new Set()
           let count = 0
           for await (const row of left.rows()) {
-            if (signal?.aborted) return
+            signal?.throwIfAborted()
             if (++count % YIELD_INTERVAL === 0) {
               await yieldToEventLoop()
-              if (signal?.aborted) return
+              signal?.throwIfAborted()
             }
             const key = await stableRowKey(row)
             if (!seen.has(key)) {
@@ -713,10 +720,10 @@ function executeSetOperation(plan, context) {
             }
           }
           for await (const row of right.rows()) {
-            if (signal?.aborted) return
+            signal?.throwIfAborted()
             if (++count % YIELD_INTERVAL === 0) {
               await yieldToEventLoop()
-              if (signal?.aborted) return
+              signal?.throwIfAborted()
             }
             const key = await stableRowKey(row)
             if (!seen.has(key)) {
@@ -739,10 +746,10 @@ function executeSetOperation(plan, context) {
         const rightKeys = new Map()
         let tick = 0
         for await (const row of right.rows()) {
-          if (signal?.aborted) return
+          signal?.throwIfAborted()
           if (++tick % YIELD_INTERVAL === 0) {
             await yieldToEventLoop()
-            if (signal?.aborted) return
+            signal?.throwIfAborted()
           }
           const key = await stableRowKey(row)
           rightKeys.set(key, (rightKeys.get(key) ?? 0) + 1)
@@ -751,10 +758,10 @@ function executeSetOperation(plan, context) {
         if (plan.all) {
           // INTERSECT ALL: yield each left row that matches, consuming right counts
           for await (const row of left.rows()) {
-            if (signal?.aborted) return
+            signal?.throwIfAborted()
             if (++tick % YIELD_INTERVAL === 0) {
               await yieldToEventLoop()
-              if (signal?.aborted) return
+              signal?.throwIfAborted()
             }
             const key = await stableRowKey(row)
             const count = rightKeys.get(key)
@@ -767,10 +774,10 @@ function executeSetOperation(plan, context) {
           // INTERSECT: yield deduplicated rows present in both
           const seen = new Set()
           for await (const row of left.rows()) {
-            if (signal?.aborted) return
+            signal?.throwIfAborted()
             if (++tick % YIELD_INTERVAL === 0) {
               await yieldToEventLoop()
-              if (signal?.aborted) return
+              signal?.throwIfAborted()
             }
             const key = await stableRowKey(row)
             if (rightKeys.has(key) && !seen.has(key)) {
@@ -794,10 +801,10 @@ function executeSetOperation(plan, context) {
         const rightKeys = new Map()
         let tick = 0
         for await (const row of right.rows()) {
-          if (signal?.aborted) return
+          signal?.throwIfAborted()
           if (++tick % YIELD_INTERVAL === 0) {
             await yieldToEventLoop()
-            if (signal?.aborted) return
+            signal?.throwIfAborted()
           }
           const key = await stableRowKey(row)
           rightKeys.set(key, (rightKeys.get(key) ?? 0) + 1)
@@ -806,10 +813,10 @@ function executeSetOperation(plan, context) {
         if (plan.all) {
           // EXCEPT ALL: yield left rows, consuming right counts
           for await (const row of left.rows()) {
-            if (signal?.aborted) return
+            signal?.throwIfAborted()
             if (++tick % YIELD_INTERVAL === 0) {
               await yieldToEventLoop()
-              if (signal?.aborted) return
+              signal?.throwIfAborted()
             }
             const key = await stableRowKey(row)
             const count = rightKeys.get(key)
@@ -823,10 +830,10 @@ function executeSetOperation(plan, context) {
           // EXCEPT: yield deduplicated left rows not in right
           const seen = new Set()
           for await (const row of left.rows()) {
-            if (signal?.aborted) return
+            signal?.throwIfAborted()
             if (++tick % YIELD_INTERVAL === 0) {
               await yieldToEventLoop()
-              if (signal?.aborted) return
+              signal?.throwIfAborted()
             }
             const key = await stableRowKey(row)
             if (!rightKeys.has(key) && !seen.has(key)) {

package/src/execute/join.js

@@ -56,7 +56,7 @@ export function executeNestedLoopJoin(plan, context) {
       /** @type {AsyncRow[]} */
       const innerRows = []
       for await (const row of inner.rows()) {
-        if (context.signal?.aborted) return
+        context.signal?.throwIfAborted()
         innerRows.push(row)
       }
 
@@ -69,7 +69,7 @@ export function executeNestedLoopJoin(plan, context) {
 
       let innerCount = 0
       for await (const outerRow of outer.rows()) {
-        if (context.signal?.aborted) return
+        context.signal?.throwIfAborted()
 
         if (!outerCols) {
           outerCols = outerRow.columns
@@ -80,7 +80,7 @@ export function executeNestedLoopJoin(plan, context) {
         for (const innerRow of innerRows) {
           if (++innerCount % YIELD_INTERVAL === 0) {
             await yieldToEventLoop()
-            if (context.signal?.aborted) return
+            context.signal?.throwIfAborted()
           }
           const tempMerged = merge(outerRow, innerRow)
           const matches = await evaluateExpr({
@@ -101,7 +101,7 @@ export function executeNestedLoopJoin(plan, context) {
         }
       }
 
-      if (context.signal?.aborted) return
+      context.signal?.throwIfAborted()
 
       // Unmatched inner rows for outer joins on the buffered side
       if (matchedInnerRows) {
@@ -134,7 +134,7 @@ function executeLateralJoin(plan, context) {
       const rightTable = plan.rightAlias
 
       for await (const leftRow of left.rows()) {
-        if (context.signal?.aborted) return
+        context.signal?.throwIfAborted()
 
         // When nested inside a correlated subquery, preserve the enclosing
         // outer row so UNNEST args can reference its columns (e.g. o.arr).
@@ -146,7 +146,7 @@ function executeLateralJoin(plan, context) {
 
         let hasMatch = false
         for await (const rightRow of right.rows()) {
-          if (context.signal?.aborted) return
+          context.signal?.throwIfAborted()
           const merged = mergeRows(leftRow, rightRow, leftTable, rightTable)
           const matches = plan.condition === undefined
             ? true
@@ -199,10 +199,10 @@ export function executePositionalJoin(plan, context) {
       while (true) {
         const [leftResult, rightResult] = await Promise.all([leftRows.next(), rightRows.next()])
         if (leftResult.done && rightResult.done) return
-        if (signal?.aborted) return
+        signal?.throwIfAborted()
         if (++tick % YIELD_INTERVAL === 0) {
           await yieldToEventLoop()
-          if (signal?.aborted) return
+          signal?.throwIfAborted()
         }
         if (!leftResult.done && !leftCols.length) leftCols = leftResult.value.columns
         if (!rightResult.done && !rightCols.length) rightCols = rightResult.value.columns
@@ -266,10 +266,10 @@ export function executeHashJoin(plan, context) {
       let buildCols = []
       let innerCount = 0
       for await (const buildRow of build.rows()) {
-        if (context.signal?.aborted) return
+        context.signal?.throwIfAborted()
         if (++innerCount % YIELD_INTERVAL === 0) {
           await yieldToEventLoop()
-          if (context.signal?.aborted) return
+          context.signal?.throwIfAborted()
         }
         if (!buildCols.length) {
           buildCols = buildRow.columns
@@ -297,7 +297,7 @@ export function executeHashJoin(plan, context) {
 
       // Probe phase: stream the other side
       for await (const probeRow of probe.rows()) {
-        if (context.signal?.aborted) return
+        context.signal?.throwIfAborted()
 
         if (!probeCols) {
           probeCols = probeRow.columns
@@ -314,7 +314,7 @@ export function executeHashJoin(plan, context) {
             for (const buildRow of candidates) {
               if (++innerCount % YIELD_INTERVAL === 0) {
                 await yieldToEventLoop()
-                if (context.signal?.aborted) return
+                context.signal?.throwIfAborted()
               }
               const merged = merge(probeRow, buildRow)
               if (residual) {
@@ -333,7 +333,7 @@ export function executeHashJoin(plan, context) {
         }
       }
 
-      if (context.signal?.aborted) return
+      context.signal?.throwIfAborted()
 
       // Unmatched build rows for outer joins on the build side
       if (buildRows && matchedBuildRows) {

package/src/execute/sort.js

@@ -146,7 +146,7 @@ export function executeSort(plan, context) {
       /** @type {SortEntry[]} */
       let entries = []
       for await (const row of child.rows()) {
-        if (context.signal?.aborted) return
+        context.signal?.throwIfAborted()
         entries.push({ row })
         if (entries.length >= bufferLimit) {
           // Sort keys are cached on the rows, so survivors of one truncation

package/src/execute/streamingAggregate.js

@@ -409,8 +409,8 @@ async function accumulateChunk({ chunk, groupBy, specs, groups, needsRow, contex
 
 /**
  * Consumes the child rows into per-group accumulators, holding at most one
- * chunk of rows at a time. Returns undefined when aborted mid-collection so
- * callers end the row stream silently, matching the buffered path.
+ * chunk of rows at a time. Throws when aborted so partial accumulators are
+ * never finalized into results.
  *
  * @param {object} options
  * @param {QueryResults} options.child
@@ -418,7 +418,7 @@ async function accumulateChunk({ chunk, groupBy, specs, groups, needsRow, contex
  * @param {StreamingAggSpec[]} options.specs
  * @param {boolean} options.needsRow
  * @param {ExecuteContext} options.context
- * @returns {Promise<Map<unknown, StreamingGroup> | undefined>}
+ * @returns {Promise<Map<unknown, StreamingGroup>>}
  */
 async function accumulateGroups({ child, groupBy, specs, needsRow, context }) {
   /** @type {Map<unknown, StreamingGroup>} */
@@ -431,14 +431,11 @@ async function accumulateGroups({ child, groupBy, specs, needsRow, context }) {
       await accumulateChunk({ chunk, groupBy, specs, groups, needsRow, context })
       chunk = []
       await yieldToEventLoop()
-      if (context.signal?.aborted) return
+      context.signal?.throwIfAborted()
     }
   }
   if (chunk.length) {
     await accumulateChunk({ chunk, groupBy, specs, groups, needsRow, context })
-    // An abort during the final partial chunk ends the stream silently,
-    // consistent with the full-chunk check above
-    if (context.signal?.aborted) return
   }
   context.signal?.throwIfAborted()
   return groups
@@ -531,7 +528,6 @@ export function streamingHashAggregateRows({ plan, streaming, child, context })
   const { specs, keyRefs, needsRow } = streaming
   return async function* () {
     const groups = await accumulateGroups({ child, groupBy: plan.groupBy, specs, needsRow, context })
-    if (!groups) return
     const { orderBy, having } = plan
 
     // Without ORDER BY, groups finalize and yield one at a time so output
@@ -585,7 +581,6 @@ export function streamingScalarAggregateRows({ plan, streaming, child, context }
   const { specs, keyRefs, needsRow } = streaming
   return async function* () {
     const groups = await accumulateGroups({ child, groupBy: [], specs, needsRow, context })
-    if (!groups) return
     /** @type {StreamingGroup} */
     const group = groups.get(true) ?? { firstRow: undefined, keyValues: [], accumulators: specs.map(spec => newAccumulator(spec.funcName, spec.node.distinct)) }
 

package/src/execute/window.js

@@ -42,7 +42,7 @@ export function executeWindow(plan, context) {
         for await (const row of child.rows()) {
           if (++i % YIELD_INTERVAL === 0) {
             await yieldToEventLoop()
-            if (context.signal?.aborted) return
+            context.signal?.throwIfAborted()
           }
           const cells = { ...row.cells }
           for (const w of plan.windows) {
@@ -69,7 +69,7 @@ export function executeWindow(plan, context) {
       for await (const row of child.rows()) {
         if (++collectCount % YIELD_INTERVAL === 0) {
           await yieldToEventLoop()
-          if (context.signal?.aborted) return
+          context.signal?.throwIfAborted()
         }
         rows.push(row)
       }
@@ -81,14 +81,14 @@ export function executeWindow(plan, context) {
 
       for (let w = 0; w < plan.windows.length; w++) {
         await computeWindow(plan.windows[w], rows, windowValues[w], context)
-        if (context.signal?.aborted) return
+        context.signal?.throwIfAborted()
       }
 
       let emitCount = 0
       for (let i = 0; i < rows.length; i++) {
         if (++emitCount % YIELD_INTERVAL === 0) {
           await yieldToEventLoop()
-          if (context.signal?.aborted) return
+          context.signal?.throwIfAborted()
         }
         const row = rows[i]
         const cells = { ...row.cells }
@@ -122,7 +122,7 @@ async function computeWindow(spec, rows, output, context) {
   for (let chunkStart = 0; chunkStart < rows.length; chunkStart += YIELD_INTERVAL) {
     if (chunkStart > 0) {
       await yieldToEventLoop()
-      if (context.signal?.aborted) return
+      context.signal?.throwIfAborted()
     }
     const chunkEnd = Math.min(chunkStart + YIELD_INTERVAL, rows.length)
     const chunkKeys = await Promise.all(
@@ -142,7 +142,7 @@ async function computeWindow(spec, rows, output, context) {
   }
 
   for (const bucket of partitions.values()) {
-    if (context.signal?.aborted) return
+    context.signal?.throwIfAborted()
 
     // Order within the partition. Empty ORDER BY → input order.
     /** @type {number[]} */
@@ -153,7 +153,7 @@ async function computeWindow(spec, rows, output, context) {
       for (let chunkStart = 0; chunkStart < bucket.length; chunkStart += YIELD_INTERVAL) {
         if (chunkStart > 0) {
           await yieldToEventLoop()
-          if (context.signal?.aborted) return
+          context.signal?.throwIfAborted()
         }
         const chunkEnd = Math.min(chunkStart + YIELD_INTERVAL, bucket.length)
         const chunkValues = await Promise.all(
@@ -205,7 +205,7 @@ async function applyWindowFunction(spec, ordered, rows, output, context) {
     for (let k = 0; k < ordered.length; k++) {
       if (++tick % YIELD_INTERVAL === 0) {
         await yieldToEventLoop()
-        if (context.signal?.aborted) return
+        context.signal?.throwIfAborted()
       }
       const idx = ordered[k]
       const row = rows[idx]

package/src/index.d.ts

@@ -28,7 +28,7 @@ export type {
  * @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
+ * @param options.signal - AbortSignal to cancel the query; an aborted query rejects with the signal's reason
  * @returns async generator yielding rows matching the query
  */
 export function executeSql(options: ExecuteSqlOptions): QueryResults