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,28 @@ 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.
+ *
+ * Returns a sign-only contract: negative if a < b, 0 if equal, positive
+ * if a > b. Callers must NOT rely on the magnitude of the return value.
+ */
+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 +63,15 @@ export function compareValues(a: Value, b: Value): number {
   if (a === b) {
     return 0;
   }
+  // String check before null: strings are the most common value type in
+  // practice, so testing them first reduces branch mispredictions. The
+  // null sub-check inside handles the string-vs-null comparison without
+  // falling through to the generic null checks below.
+  if (typeof a === 'string') {
+    if (b === null) return 1;
+    assertString(b);
+    return compareStringUTF8Fast(a, b);
+  }
   if (a === null) {
     return -1;
   }
@@ -55,18 +86,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 +103,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,4 +1,9 @@
-import {assert, unreachable} from '../../../shared/src/asserts.ts';
+import {
+  assert,
+  assertNumber,
+  assertString,
+  unreachable,
+} from '../../../shared/src/asserts.ts';
 import {BTreeSet} from '../../../shared/src/btree-set.ts';
 import {hasOwn} from '../../../shared/src/has-own.ts';
 import {once} from '../../../shared/src/iterables.ts';
@@ -25,6 +30,7 @@ import {
   type Constraint,
 } from './constraint.ts';
 import {
+  compareStringUTF8Fast,
   compareValues,
   makeComparator,
   valuesEqual,
@@ -801,12 +807,51 @@ type MinValue = typeof minValue;
 const maxValue = Symbol('max-value');
 type MaxValue = typeof maxValue;
 
+/**
+ * Compares two Bound values, handling minValue/maxValue sentinels,
+ * null, and delegating to type-specific comparison. This merges the
+ * logic of compareBounds + compareValues into a single function that
+ * V8 can inline at the call site (well within TurboFan's 460-bytecode
+ * inlining threshold).
+ */
+function compareBoundValue(a: Bound, b: Bound): number {
+  if (a === b) return 0;
+  if (a === minValue) return -1;
+  if (b === minValue) return 1;
+  if (a === maxValue) return 1;
+  if (b === maxValue) return -1;
+  const aN: Value = a ?? null;
+  const bN: Value = b ?? null;
+  if (aN === null) return bN === null ? 0 : -1;
+  if (bN === null) return 1;
+  if (typeof a === 'string') {
+    assertString(b);
+    return compareStringUTF8Fast(a, b);
+  }
+  if (typeof a === 'number') {
+    assertNumber(b);
+    return a - (b as number);
+  }
+  return compareValues(aN, bN);
+}
+
+/**
+ * Creates a comparator for RowBound values used in BTree index scans.
+ *
+ * For single-key sorts (the common case), returns a direct comparator
+ * that avoids the multi-key loop. The actual comparison logic lives in
+ * compareBoundValue, which V8 inlines at the call site.
+ */
 function makeBoundComparator(sort: Ordering) {
+  if (sort.length === 1) {
+    const key = sort[0][0];
+    const dir = sort[0][1];
+    const cmp = (a: RowBound, b: RowBound) => compareBoundValue(a[key], b[key]);
+    return dir === 'asc' ? cmp : (a: RowBound, b: RowBound) => -cmp(a, b);
+  }
   return (a: RowBound, b: RowBound) => {
-    // Hot! Do not use destructuring
     for (const entry of sort) {
-      const key = entry[0];
-      const cmp = compareBounds(a[key], b[key]);
+      const cmp = compareBoundValue(a[entry[0]], b[entry[0]]);
       if (cmp !== 0) {
         return entry[1] === 'asc' ? cmp : -cmp;
       }
@@ -815,25 +860,6 @@ function makeBoundComparator(sort: Ordering) {
   };
 }
 
-function compareBounds(a: Bound, b: Bound): number {
-  if (a === b) {
-    return 0;
-  }
-  if (a === minValue) {
-    return -1;
-  }
-  if (b === minValue) {
-    return 1;
-  }
-  if (a === maxValue) {
-    return 1;
-  }
-  if (b === maxValue) {
-    return -1;
-  }
-  return compareValues(a, b);
-}
-
 function* generateRows(
   data: BTreeSet<Row>,
   scanStart: RowBound | undefined,