perf: coalesceRanges auto-computes gap — eliminates redundant sort

All 6 call sites used coalesceRanges(ranges, autoCoalesceGap(ranges))
which sorted the ranges array twice — once in autoCoalesceGap and again
in coalesceRanges. Now coalesceRanges accepts optional maxGap and
auto-computes from the already-sorted array when omitted.

Author: teamchong

src/coalesce.ts

@@ -13,14 +13,13 @@ export interface CoalescedRange {
 }
 
 /**
- * Compute optimal coalesce gap based on page density.
+ * Compute optimal coalesce gap from a **pre-sorted** range array.
  * Dense layouts (small gaps between pages) benefit from aggressive merging.
  * Sparse layouts waste bandwidth with large gaps.
  * Returns a gap between 16KB (sparse) and 256KB (dense).
  */
-export function autoCoalesceGap(ranges: Range[]): number {
-  if (ranges.length < 2) return 64 * 1024;
-  const sorted = [...ranges].sort((a, b) => a.offset - b.offset);
+function computeGap(sorted: Range[]): number {
+  if (sorted.length < 2) return 64 * 1024;
   // Compute median gap between adjacent ranges
   const gaps: number[] = [];
   for (let i = 1; i < sorted.length; i++) {
@@ -34,17 +33,26 @@ export function autoCoalesceGap(ranges: Range[]): number {
   return Math.max(16 * 1024, Math.min(256 * 1024, medianGap * 2));
 }
 
-/** Merge nearby byte ranges into fewer R2 reads. Sorts by offset, merges if gap <= maxGap. */
-export function coalesceRanges(ranges: Range[], maxGap: number): CoalescedRange[] {
+/** Compute optimal coalesce gap based on page density. Sorts a copy internally. */
+export function autoCoalesceGap(ranges: Range[]): number {
+  if (ranges.length < 2) return 64 * 1024;
+  const sorted = [...ranges].sort((a, b) => a.offset - b.offset);
+  return computeGap(sorted);
+}
+
+/** Merge nearby byte ranges into fewer R2 reads. Sorts by offset, merges if gap <= maxGap.
+ *  If maxGap is omitted, auto-computes from page density (sorts once instead of twice). */
+export function coalesceRanges(ranges: Range[], maxGap?: number): CoalescedRange[] {
   if (ranges.length === 0) return [];
   const sorted = [...ranges].sort((a, b) => a.offset - b.offset);
+  const gap = maxGap ?? computeGap(sorted);
   const result: CoalescedRange[] = [];
   let cur: CoalescedRange = { offset: sorted[0].offset, length: sorted[0].length, ranges: [sorted[0]] };
 
   for (let i = 1; i < sorted.length; i++) {
     const r = sorted[i];
     const curEnd = cur.offset + cur.length;
-    if (r.offset <= curEnd + maxGap) {
+    if (r.offset <= curEnd + gap) {
       cur.length = Math.max(curEnd, r.offset + r.length) - cur.offset;
       cur.ranges.push(r);
     } else {

src/fragment-do.ts

@@ -3,7 +3,7 @@ import type { Env, TableMeta, QueryResult, Row } from "./types.js";
 import { queryReferencedColumns } from "./types.js";
 import type { QueryDescriptor } from "./client.js";
 import { instantiateWasm, type WasmEngine } from "./wasm-engine.js";
-import { coalesceRanges, autoCoalesceGap, fetchBounded, withRetry, withTimeout } from "./coalesce.js";
+import { coalesceRanges, fetchBounded, withRetry, withTimeout } from "./coalesce.js";
 import { R2SpillBackend } from "./r2-spill.js";
 import {
   type Operator, type RowBatch,
@@ -121,7 +121,7 @@ export class FragmentDO extends DurableObject<Env> {
       const r2Start = Date.now();
       if (uncachedRanges.length > 0) {
         const fetchRanges = uncachedRanges.map(u => u.range);
-        const coalesced = coalesceRanges(fetchRanges, autoCoalesceGap(fetchRanges));
+        const coalesced = coalesceRanges(fetchRanges);
         const fetched = await fetchBounded(
           coalesced.map(c => () =>
             withRetry(() =>

src/local-executor.ts

@@ -12,7 +12,7 @@ import { parseFooter, parseColumnMetaFromProtobuf, FOOTER_SIZE } from "./footer.
 import { parseManifest } from "./manifest.js";
 import { detectFormat, getParquetFooterLength, parseParquetFooter, parquetMetaToTableMeta } from "./parquet.js";
 import { assembleRows, canSkipFragment } from "./decode.js";
-import { coalesceRanges, autoCoalesceGap } from "./coalesce.js";
+import { coalesceRanges } from "./coalesce.js";
 import { instantiateWasm, rowsToColumnArrays, type WasmEngine } from "./wasm-engine.js";
 
 import { VipCache } from "./vip-cache.js";
@@ -208,7 +208,7 @@ export class LocalExecutor implements QueryExecutor {
       colDetails.push({ name: col.name, dtype: col.dtype as DataType, pages: colPages, bytes: colBytes });
     }
 
-    const coalesced = coalesceRanges(ranges, autoCoalesceGap(ranges));
+    const coalesced = coalesceRanges(ranges);
     const estimatedBytes = ranges.reduce((s, r) => s + r.length, 0);
     const totalRows = columns[0]?.pages.reduce((s, p) => s + p.rowCount, 0) ?? 0;
 

src/query-do.ts

@@ -11,7 +11,7 @@ import { decodeParquetColumnChunk } from "./parquet-decode.js";
 import { instantiateWasm, type WasmEngine } from "./wasm-engine.js";
 import { mergeQueryResults } from "./merge.js";
 import { decodeColumnarBatch, columnarBatchToRows } from "./columnar.js";
-import { coalesceRanges, autoCoalesceGap, fetchBounded, withRetry, withTimeout } from "./coalesce.js";
+import { coalesceRanges, fetchBounded, withRetry, withTimeout } from "./coalesce.js";
 import { R2SpillBackend, encodeColumnarRun } from "./r2-spill.js";
 import {
   type Operator, type RowBatch,
@@ -192,7 +192,7 @@ class EdgeScanOperator implements Operator {
     // L3: R2
     if (uncachedRanges.length > 0) {
       const r2Start = Date.now();
-      const coalesced = coalesceRanges(uncachedRanges, autoCoalesceGap(uncachedRanges));
+      const coalesced = coalesceRanges(uncachedRanges);
       const fetched = await fetchBounded(
         coalesced.map(c => () =>
           withRetry(() =>
@@ -750,7 +750,7 @@ export class QueryDO extends DurableObject<Env> {
       colDetails.push({ name: col.name, dtype: col.dtype as DataType, pages: colPages, bytes: colBytes });
     }
 
-    const coalesced = coalesceRanges(ranges, autoCoalesceGap(ranges));
+    const coalesced = coalesceRanges(ranges);
     const estimatedBytes = ranges.reduce((s, r) => s + r.length, 0);
     const dataset = this.datasetCache.get(query.table);
     const totalFragments = dataset ? dataset.fragmentMetas.size : 1;
@@ -1060,7 +1060,7 @@ export class QueryDO extends DurableObject<Env> {
     let bytesRead = 0;
 
     if (uncachedRanges.length > 0) {
-      const coalesced = coalesceRanges(uncachedRanges, autoCoalesceGap(uncachedRanges));
+      const coalesced = coalesceRanges(uncachedRanges);
 
       const fetched = await fetchBounded(
         coalesced.map(c => () =>