perf(zql): comparator fast paths - string comparison + single-key optimization

Optimize hot comparison paths in the IVM pipeline:

* Add compareStringUTF8Fast for ASCII-fast string comparison with UTF-8 fallback
* Reorder compareValues to check strings before nulls (most common type)
* Add single-key fast path in makeComparator avoiding loop overhead
* Add single-key fast path in makeBoundComparator with fully inlined comparison
* Fix compareBounds null handling for nullable database columns

Author: Alp

packages/zql/src/ivm/data.test.ts

@@ -1,7 +1,8 @@
 import {compareUTF8} from 'compare-utf8';
 import fc from 'fast-check';
-import {expect, test} from 'vitest';
+import {describe, expect, test} from 'vitest';
 import {
+  compareStringUTF8Fast,
   compareValues,
   makeComparator,
   normalizeUndefined,
@@ -84,10 +85,13 @@ test('compareValues', () => {
     ),
   );
 
-  // string
+  // string - compareStringUTF8Fast returns different magnitudes for ASCII
+  // but always matches the sign of compareUTF8
   fc.assert(
     fc.property(fc.fullUnicodeString(), fc.fullUnicodeString(), (s1, s2) => {
-      expect(compareValues(s1, s2)).toBe(compareUTF8(s1, s2));
+      expect(Math.sign(compareValues(s1, s2))).toBe(
+        Math.sign(compareUTF8(s1, s2)),
+      );
     }),
   );
   fc.assert(
@@ -132,3 +136,73 @@ test('valuesEquals', () => {
 test('comparator', () => {
   compareRowsTest(makeComparator);
 });
+
+describe('compareStringUTF8Fast', () => {
+  test('ASCII strings compare correctly', () => {
+    expect(compareStringUTF8Fast('abc', 'def')).toBeLessThan(0);
+    expect(compareStringUTF8Fast('def', 'abc')).toBeGreaterThan(0);
+    expect(compareStringUTF8Fast('abc', 'abc')).toBe(0);
+  });
+
+  test('empty strings', () => {
+    expect(compareStringUTF8Fast('', '')).toBe(0);
+    expect(compareStringUTF8Fast('', 'a')).toBeLessThan(0);
+    expect(compareStringUTF8Fast('a', '')).toBeGreaterThan(0);
+  });
+
+  test('Unicode strings fall back correctly', () => {
+    // Non-ASCII chars trigger compareUTF8 fallback; sign must match
+    expect(Math.sign(compareStringUTF8Fast('café', 'cafë'))).toBe(
+      Math.sign(compareUTF8('café', 'cafë')),
+    );
+  });
+
+  test('prefix strings', () => {
+    expect(compareStringUTF8Fast('abc', 'abcd')).toBeLessThan(0);
+    expect(compareStringUTF8Fast('abcd', 'abc')).toBeGreaterThan(0);
+  });
+
+  test('sign matches compareUTF8 for all ASCII', () => {
+    fc.assert(
+      fc.property(fc.asciiString(), fc.asciiString(), (a, b) => {
+        expect(Math.sign(compareStringUTF8Fast(a, b))).toBe(
+          Math.sign(compareUTF8(a, b)),
+        );
+      }),
+    );
+  });
+});
+
+describe('makeComparator single-key fast path', () => {
+  test('single key asc matches multi-key behavior', () => {
+    const singleKey = makeComparator([['name', 'asc']]);
+    const multiKey = makeComparator([
+      ['name', 'asc'],
+      ['id', 'asc'],
+    ]);
+    // For rows where only 'name' differs, both should give same sign
+    expect(Math.sign(singleKey({name: 'a'}, {name: 'b'}))).toBe(
+      Math.sign(multiKey({name: 'a', id: '1'}, {name: 'b', id: '1'})),
+    );
+  });
+
+  test('single key desc', () => {
+    const cmp = makeComparator([['name', 'desc']]);
+    expect(cmp({name: 'a'}, {name: 'b'})).toBeGreaterThan(0);
+  });
+
+  test('single key with reverse', () => {
+    const cmp = makeComparator([['name', 'asc']], true);
+    expect(cmp({name: 'a'}, {name: 'b'})).toBeGreaterThan(0);
+  });
+
+  test('single key desc with reverse', () => {
+    const cmp = makeComparator([['name', 'desc']], true);
+    expect(cmp({name: 'a'}, {name: 'b'})).toBeLessThan(0);
+  });
+
+  test('single key equality', () => {
+    const cmp = makeComparator([['id', 'asc']]);
+    expect(cmp({id: 42}, {id: 42})).toBe(0);
+  });
+});

packages/zql/src/ivm/data.ts

@@ -22,6 +22,25 @@ export type Node = {
   relationships: Record<string, () => Stream<Node | 'yield'>>;
 };
 
+/**
+ * Fast-path string comparison that handles the common ASCII case
+ * without calling into compareUTF8. Falls back to compareUTF8 for
+ * non-ASCII characters.
+ */
+export function compareStringUTF8Fast(a: string, b: string): number {
+  if (a === b) return 0;
+  const len = a.length < b.length ? a.length : b.length;
+  for (let i = 0; i < len; i++) {
+    const ac = a.charCodeAt(i);
+    const bc = b.charCodeAt(i);
+    if (ac !== bc) {
+      if (ac < 128 && bc < 128) return ac - bc;
+      return compareUTF8(a, b);
+    }
+  }
+  return a.length - b.length;
+}
+
 /**
  * Compare two values. The values must be of the same type. This function
  * throws at runtime if the types differ.
@@ -41,6 +60,12 @@ export function compareValues(a: Value, b: Value): number {
   if (a === b) {
     return 0;
   }
+  // String check first - most common type in practice
+  if (typeof a === 'string') {
+    if (b === null) return 1;
+    assertString(b);
+    return compareStringUTF8Fast(a, b);
+  }
   if (a === null) {
     return -1;
   }
@@ -55,18 +80,6 @@ export function compareValues(a: Value, b: Value): number {
     assertNumber(b);
     return a - b;
   }
-  if (typeof a === 'string') {
-    assertString(b);
-    // We compare all strings in Zero as UTF-8. This is the default on SQLite
-    // and we need to match it. See:
-    // https://blog.replicache.dev/blog/replicache-11-adventures-in-text-encoding.
-    //
-    // TODO: We could change this since SQLite supports UTF-16. Microbenchmark
-    // to see if there's a big win.
-    //
-    // https://www.sqlite.org/c3ref/create_collation.html
-    return compareUTF8(a, b);
-  }
   throw new Error(`Unsupported type: ${a}`);
 }
 
@@ -84,6 +97,18 @@ export function normalizeUndefined(v: Value): NormalizedValue {
 export type Comparator = (r1: Row, r2: Row) => number;
 
 export function makeComparator(order: Ordering, reverse?: boolean): Comparator {
+  if (order.length === 1) {
+    const key = order[0][0];
+    const dir = order[0][1];
+    if (dir === 'asc') {
+      return reverse
+        ? (a, b) => -compareValues(a[key], b[key])
+        : (a, b) => compareValues(a[key], b[key]);
+    }
+    return reverse
+      ? (a, b) => compareValues(a[key], b[key])
+      : (a, b) => -compareValues(a[key], b[key]);
+  }
   return (a, b) => {
     // Skip destructuring here since it is hot code.
     for (const ord of order) {

packages/zql/src/ivm/memory-source.ts

@@ -1,3 +1,4 @@
+import {compareUTF8} from 'compare-utf8';
 import {assert, unreachable} from '../../../shared/src/asserts.ts';
 import {BTreeSet} from '../../../shared/src/btree-set.ts';
 import {hasOwn} from '../../../shared/src/has-own.ts';
@@ -788,7 +789,57 @@ type MinValue = typeof minValue;
 const maxValue = Symbol('max-value');
 type MaxValue = typeof maxValue;
 
+/**
+ * Creates a comparator for RowBound values used in BTree index scans.
+ *
+ * For single-key sorts (the common case), we fully inline the comparison
+ * logic to eliminate function call overhead. This is the hottest comparator
+ * in the IVM pipeline: it runs for every BTree node visited during index
+ * scans. In production profiling (135 pipelines x ~200 rows), this path
+ * accounts for a significant portion of CPU time, and each eliminated
+ * function call frame (compareBounds -> compareValues -> compareUTF8)
+ * compounds across millions of invocations.
+ */
 function makeBoundComparator(sort: Ordering) {
+  if (sort.length === 1) {
+    const key = sort[0][0];
+    const dir = sort[0][1];
+    const cmp = (a: RowBound, b: RowBound): number => {
+      const av = a[key];
+      const bv = b[key];
+      if (av === bv) return 0;
+      if (av === minValue) return -1;
+      if (bv === minValue) return 1;
+      if (av === maxValue) return 1;
+      if (bv === maxValue) return -1;
+      // Null handling (min/max symbols ruled out above, safe to narrow)
+      const aN: Value = av ?? null;
+      const bN: Value = bv ?? null;
+      if (aN === null) return bN === null ? 0 : -1;
+      if (bN === null) return 1;
+      // Inline compareValues for string (most common) and number
+      if (typeof av === 'string') {
+        const aStr = av;
+        const bStr = bv as string;
+        if (aStr === bStr) return 0;
+        const len = aStr.length < bStr.length ? aStr.length : bStr.length;
+        for (let i = 0; i < len; i++) {
+          const ac = aStr.charCodeAt(i);
+          const bc = bStr.charCodeAt(i);
+          if (ac !== bc) {
+            if (ac < 128 && bc < 128) return ac - bc;
+            return compareUTF8(aStr, bStr);
+          }
+        }
+        return aStr.length - bStr.length;
+      }
+      if (typeof av === 'number') return av - (bv as number);
+      // Fallback for other types (boolean, etc.)
+      return compareValues(aN, bN);
+    };
+    return dir === 'asc' ? cmp : (a: RowBound, b: RowBound) => -cmp(a, b);
+  }
+  // Multi-key path
   return (a: RowBound, b: RowBound) => {
     // Hot! Do not use destructuring
     for (const entry of sort) {
@@ -818,7 +869,19 @@ function compareBounds(a: Bound, b: Bound): number {
   if (b === maxValue) {
     return -1;
   }
-  return compareValues(a, b);
+  // Handle null/undefined before delegating to compareValues.
+  // compareValues asserts type homogeneity (e.g. assertString(b) when a
+  // is a string). Nullable database columns can produce null vs
+  // string/number comparisons that compareValues doesn't handle.
+  const aN: Value = a ?? null;
+  const bN: Value = b ?? null;
+  if (aN === null) {
+    return bN === null ? 0 : -1;
+  }
+  if (bN === null) {
+    return 1;
+  }
+  return compareValues(aN, bN);
 }
 
 function* generateRows(