@tanstack/db-ivm 0.1.19 → 0.1.22

package/dist/esm/operators/topKWithFractionalIndex.js.map

@@ -1 +1 @@
-{"version":3,"file":"topKWithFractionalIndex.js","sources":["../../../src/operators/topKWithFractionalIndex.ts"],"sourcesContent":["import { DifferenceStreamWriter, UnaryOperator } from '../graph.js'\nimport { StreamBuilder } from '../d2.js'\nimport { MultiSet } from '../multiset.js'\nimport { TopKState, handleMoveIn, handleMoveOut } from './topKState.js'\nimport { TopKArray, createKeyedComparator } from './topKArray.js'\nimport type { IndexedValue, TopK } from './topKArray.js'\nimport type { DifferenceStreamReader } from '../graph.js'\nimport type { IStreamBuilder, PipedOperator } from '../types.js'\n\nexport interface TopKWithFractionalIndexOptions {\n  limit?: number\n  offset?: number\n  setSizeCallback?: (getSize: () => number) => void\n  setWindowFn?: (\n    windowFn: (options: { offset?: number; limit?: number }) => void,\n  ) => void\n}\n\n/**\n * Operator for fractional indexed topK operations\n * This operator maintains fractional indices for sorted elements\n * and only updates indices when elements move position\n */\nexport class TopKWithFractionalIndexOperator<\n  K extends string | number,\n  T,\n> extends UnaryOperator<[K, T], [K, IndexedValue<T>]> {\n  #state: TopKState<K, T>\n\n  constructor(\n    id: number,\n    inputA: DifferenceStreamReader<[K, T]>,\n    output: DifferenceStreamWriter<[K, IndexedValue<T>]>,\n    comparator: (a: T, b: T) => number,\n    options: TopKWithFractionalIndexOptions,\n  ) {\n    super(id, inputA, output)\n    const limit = options.limit ?? Infinity\n    const offset = options.offset ?? 0\n    const topK = this.createTopK(\n      offset,\n      limit,\n      createKeyedComparator(comparator),\n    )\n    this.#state = new TopKState(topK)\n    options.setSizeCallback?.(() => this.#state.size)\n    options.setWindowFn?.(this.moveTopK.bind(this))\n  }\n\n  protected createTopK(\n    offset: number,\n    limit: number,\n    comparator: (a: [K, T], b: [K, T]) => number,\n  ): TopK<[K, T]> {\n    return new TopKArray(offset, limit, comparator)\n  }\n\n  /**\n   * Moves the topK window based on the provided offset and limit.\n   * Any changes to the topK are sent to the output.\n   */\n  moveTopK({ offset, limit }: { offset?: number; limit?: number }) {\n    const result: Array<[[K, IndexedValue<T>], number]> = []\n    const diff = this.#state.move({ offset, limit })\n\n    diff.moveIns.forEach((moveIn) => handleMoveIn(moveIn, result))\n    diff.moveOuts.forEach((moveOut) => handleMoveOut(moveOut, result))\n\n    if (diff.changes) {\n      // There are changes to the topK\n      // it could be that moveIns and moveOuts are empty\n      // because the collection is lazy, so we will run the graph again to load the data\n      this.output.sendData(new MultiSet(result))\n    }\n  }\n\n  run(): void {\n    const result: Array<[[K, IndexedValue<T>], number]> = []\n    for (const message of this.inputMessages()) {\n      for (const [item, multiplicity] of message.getInner()) {\n        const [key, value] = item\n        this.processElement(key, value, multiplicity, result)\n      }\n    }\n\n    if (result.length > 0) {\n      this.output.sendData(new MultiSet(result))\n    }\n  }\n\n  processElement(\n    key: K,\n    value: T,\n    multiplicity: number,\n    result: Array<[[K, IndexedValue<T>], number]>,\n  ): void {\n    const changes = this.#state.processElement(key, value, multiplicity)\n    handleMoveIn(changes.moveIn, result)\n    handleMoveOut(changes.moveOut, result)\n  }\n}\n\n/**\n * Limits the number of results based on a comparator, with optional offset.\n * Uses fractional indexing to minimize the number of changes when elements move positions.\n * Each element is assigned a fractional index that is lexicographically sortable.\n * When elements move, only the indices of the moved elements are updated, not all elements.\n *\n * @param comparator - A function that compares two elements\n * @param options - An optional object containing limit and offset properties\n * @returns A piped operator that orders the elements and limits the number of results\n */\nexport function topKWithFractionalIndex<KType extends string | number, T>(\n  comparator: (a: T, b: T) => number,\n  options?: TopKWithFractionalIndexOptions,\n): PipedOperator<[KType, T], [KType, IndexedValue<T>]> {\n  const opts = options || {}\n\n  return (\n    stream: IStreamBuilder<[KType, T]>,\n  ): IStreamBuilder<[KType, IndexedValue<T>]> => {\n    const output = new StreamBuilder<[KType, IndexedValue<T>]>(\n      stream.graph,\n      new DifferenceStreamWriter<[KType, IndexedValue<T>]>(),\n    )\n    const operator = new TopKWithFractionalIndexOperator<KType, T>(\n      stream.graph.getNextOperatorId(),\n      stream.connectReader(),\n      output.writer,\n      comparator,\n      opts,\n    )\n    stream.graph.addOperator(operator)\n    return output\n  }\n}\n"],"names":[],"mappings":";;;;;AAuBO,MAAM,wCAGH,cAA4C;AAAA,EACpD;AAAA,EAEA,YACE,IACA,QACA,QACA,YACA,SACA;AACA,UAAM,IAAI,QAAQ,MAAM;AACxB,UAAM,QAAQ,QAAQ,SAAS;AAC/B,UAAM,SAAS,QAAQ,UAAU;AACjC,UAAM,OAAO,KAAK;AAAA,MAChB;AAAA,MACA;AAAA,MACA,sBAAsB,UAAU;AAAA,IAAA;AAElC,SAAK,SAAS,IAAI,UAAU,IAAI;AAChC,YAAQ,kBAAkB,MAAM,KAAK,OAAO,IAAI;AAChD,YAAQ,cAAc,KAAK,SAAS,KAAK,IAAI,CAAC;AAAA,EAChD;AAAA,EAEU,WACR,QACA,OACA,YACc;AACd,WAAO,IAAI,UAAU,QAAQ,OAAO,UAAU;AAAA,EAChD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,SAAS,EAAE,QAAQ,SAA8C;AAC/D,UAAM,SAAgD,CAAA;AACtD,UAAM,OAAO,KAAK,OAAO,KAAK,EAAE,QAAQ,OAAO;AAE/C,SAAK,QAAQ,QAAQ,CAAC,WAAW,aAAa,QAAQ,MAAM,CAAC;AAC7D,SAAK,SAAS,QAAQ,CAAC,YAAY,cAAc,SAAS,MAAM,CAAC;AAEjE,QAAI,KAAK,SAAS;AAIhB,WAAK,OAAO,SAAS,IAAI,SAAS,MAAM,CAAC;AAAA,IAC3C;AAAA,EACF;AAAA,EAEA,MAAY;AACV,UAAM,SAAgD,CAAA;AACtD,eAAW,WAAW,KAAK,iBAAiB;AAC1C,iBAAW,CAAC,MAAM,YAAY,KAAK,QAAQ,YAAY;AACrD,cAAM,CAAC,KAAK,KAAK,IAAI;AACrB,aAAK,eAAe,KAAK,OAAO,cAAc,MAAM;AAAA,MACtD;AAAA,IACF;AAEA,QAAI,OAAO,SAAS,GAAG;AACrB,WAAK,OAAO,SAAS,IAAI,SAAS,MAAM,CAAC;AAAA,IAC3C;AAAA,EACF;AAAA,EAEA,eACE,KACA,OACA,cACA,QACM;AACN,UAAM,UAAU,KAAK,OAAO,eAAe,KAAK,OAAO,YAAY;AACnE,iBAAa,QAAQ,QAAQ,MAAM;AACnC,kBAAc,QAAQ,SAAS,MAAM;AAAA,EACvC;AACF;AAYO,SAAS,wBACd,YACA,SACqD;AACrD,QAAM,OAAO,WAAW,CAAA;AAExB,SAAO,CACL,WAC6C;AAC7C,UAAM,SAAS,IAAI;AAAA,MACjB,OAAO;AAAA,MACP,IAAI,uBAAA;AAAA,IAAiD;AAEvD,UAAM,WAAW,IAAI;AAAA,MACnB,OAAO,MAAM,kBAAA;AAAA,MACb,OAAO,cAAA;AAAA,MACP,OAAO;AAAA,MACP;AAAA,MACA;AAAA,IAAA;AAEF,WAAO,MAAM,YAAY,QAAQ;AACjC,WAAO;AAAA,EACT;AACF;"}
+{"version":3,"file":"topKWithFractionalIndex.js","sources":["../../../src/operators/topKWithFractionalIndex.ts"],"sourcesContent":["import { DifferenceStreamWriter, UnaryOperator } from '../graph.js'\nimport { StreamBuilder } from '../d2.js'\nimport { MultiSet } from '../multiset.js'\nimport {\n  TopKState,\n  handleMoveIn,\n  handleMoveOut,\n  topKBatch,\n} from './topKState.js'\nimport { TopKArray, createKeyedComparator } from './topKArray.js'\nimport type { IndexedValue, TopK } from './topKArray.js'\nimport type { DifferenceStreamReader } from '../graph.js'\nimport type { IStreamBuilder, PipedOperator } from '../types.js'\n\nexport interface TopKWithFractionalIndexOptions {\n  limit?: number\n  offset?: number\n  setSizeCallback?: (getSize: () => number) => void\n  setWindowFn?: (\n    windowFn: (options: { offset?: number; limit?: number }) => void,\n  ) => void\n}\n\n/**\n * Operator for fractional indexed topK operations\n * This operator maintains fractional indices for sorted elements\n * and only updates indices when elements move position\n */\nexport class TopKWithFractionalIndexOperator<\n  K extends string | number,\n  T,\n> extends UnaryOperator<[K, T], [K, IndexedValue<T>]> {\n  #state: TopKState<K, T>\n\n  constructor(\n    id: number,\n    inputA: DifferenceStreamReader<[K, T]>,\n    output: DifferenceStreamWriter<[K, IndexedValue<T>]>,\n    comparator: (a: T, b: T) => number,\n    options: TopKWithFractionalIndexOptions,\n  ) {\n    super(id, inputA, output)\n    const limit = options.limit ?? Infinity\n    const offset = options.offset ?? 0\n    const topK = this.createTopK(\n      offset,\n      limit,\n      createKeyedComparator(comparator),\n    )\n    this.#state = new TopKState(topK)\n    options.setSizeCallback?.(() => this.#state.size)\n    options.setWindowFn?.(this.moveTopK.bind(this))\n  }\n\n  protected createTopK(\n    offset: number,\n    limit: number,\n    comparator: (a: [K, T], b: [K, T]) => number,\n  ): TopK<[K, T]> {\n    return new TopKArray(offset, limit, comparator)\n  }\n\n  /**\n   * Moves the topK window based on the provided offset and limit.\n   * Any changes to the topK are sent to the output.\n   */\n  moveTopK({ offset, limit }: { offset?: number; limit?: number }) {\n    const result: Array<[[K, IndexedValue<T>], number]> = []\n    const diff = this.#state.move({ offset, limit })\n\n    diff.moveIns.forEach((moveIn) => handleMoveIn(moveIn, result))\n    diff.moveOuts.forEach((moveOut) => handleMoveOut(moveOut, result))\n\n    if (diff.changes) {\n      // There are changes to the topK\n      // it could be that moveIns and moveOuts are empty\n      // because the collection is lazy, so we will run the graph again to load the data\n      this.output.sendData(new MultiSet(result))\n    }\n  }\n\n  run(): void {\n    const result: Array<[[K, IndexedValue<T>], number]> = []\n    for (const [[key, value], multiplicity] of topKBatch(\n      this.inputMessages(),\n    )) {\n      this.processElement(key, value, multiplicity, result)\n    }\n\n    if (result.length > 0) {\n      this.output.sendData(new MultiSet(result))\n    }\n  }\n\n  processElement(\n    key: K,\n    value: T,\n    multiplicity: number,\n    result: Array<[[K, IndexedValue<T>], number]>,\n  ): void {\n    const changes = this.#state.processElement(key, value, multiplicity)\n    handleMoveIn(changes.moveIn, result)\n    handleMoveOut(changes.moveOut, result)\n  }\n}\n\n/**\n * Limits the number of results based on a comparator, with optional offset.\n * Uses fractional indexing to minimize the number of changes when elements move positions.\n * Each element is assigned a fractional index that is lexicographically sortable.\n * When elements move, only the indices of the moved elements are updated, not all elements.\n *\n * @param comparator - A function that compares two elements\n * @param options - An optional object containing limit and offset properties\n * @returns A piped operator that orders the elements and limits the number of results\n */\nexport function topKWithFractionalIndex<KType extends string | number, T>(\n  comparator: (a: T, b: T) => number,\n  options?: TopKWithFractionalIndexOptions,\n): PipedOperator<[KType, T], [KType, IndexedValue<T>]> {\n  const opts = options || {}\n\n  return (\n    stream: IStreamBuilder<[KType, T]>,\n  ): IStreamBuilder<[KType, IndexedValue<T>]> => {\n    const output = new StreamBuilder<[KType, IndexedValue<T>]>(\n      stream.graph,\n      new DifferenceStreamWriter<[KType, IndexedValue<T>]>(),\n    )\n    const operator = new TopKWithFractionalIndexOperator<KType, T>(\n      stream.graph.getNextOperatorId(),\n      stream.connectReader(),\n      output.writer,\n      comparator,\n      opts,\n    )\n    stream.graph.addOperator(operator)\n    return output\n  }\n}\n"],"names":[],"mappings":";;;;;AA4BO,MAAM,wCAGH,cAA4C;AAAA,EACpD;AAAA,EAEA,YACE,IACA,QACA,QACA,YACA,SACA;AACA,UAAM,IAAI,QAAQ,MAAM;AACxB,UAAM,QAAQ,QAAQ,SAAS;AAC/B,UAAM,SAAS,QAAQ,UAAU;AACjC,UAAM,OAAO,KAAK;AAAA,MAChB;AAAA,MACA;AAAA,MACA,sBAAsB,UAAU;AAAA,IAAA;AAElC,SAAK,SAAS,IAAI,UAAU,IAAI;AAChC,YAAQ,kBAAkB,MAAM,KAAK,OAAO,IAAI;AAChD,YAAQ,cAAc,KAAK,SAAS,KAAK,IAAI,CAAC;AAAA,EAChD;AAAA,EAEU,WACR,QACA,OACA,YACc;AACd,WAAO,IAAI,UAAU,QAAQ,OAAO,UAAU;AAAA,EAChD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,SAAS,EAAE,QAAQ,SAA8C;AAC/D,UAAM,SAAgD,CAAA;AACtD,UAAM,OAAO,KAAK,OAAO,KAAK,EAAE,QAAQ,OAAO;AAE/C,SAAK,QAAQ,QAAQ,CAAC,WAAW,aAAa,QAAQ,MAAM,CAAC;AAC7D,SAAK,SAAS,QAAQ,CAAC,YAAY,cAAc,SAAS,MAAM,CAAC;AAEjE,QAAI,KAAK,SAAS;AAIhB,WAAK,OAAO,SAAS,IAAI,SAAS,MAAM,CAAC;AAAA,IAC3C;AAAA,EACF;AAAA,EAEA,MAAY;AACV,UAAM,SAAgD,CAAA;AACtD,eAAW,CAAC,CAAC,KAAK,KAAK,GAAG,YAAY,KAAK;AAAA,MACzC,KAAK,cAAA;AAAA,IAAc,GAClB;AACD,WAAK,eAAe,KAAK,OAAO,cAAc,MAAM;AAAA,IACtD;AAEA,QAAI,OAAO,SAAS,GAAG;AACrB,WAAK,OAAO,SAAS,IAAI,SAAS,MAAM,CAAC;AAAA,IAC3C;AAAA,EACF;AAAA,EAEA,eACE,KACA,OACA,cACA,QACM;AACN,UAAM,UAAU,KAAK,OAAO,eAAe,KAAK,OAAO,YAAY;AACnE,iBAAa,QAAQ,QAAQ,MAAM;AACnC,kBAAc,QAAQ,SAAS,MAAM;AAAA,EACvC;AACF;AAYO,SAAS,wBACd,YACA,SACqD;AACrD,QAAM,OAAO,WAAW,CAAA;AAExB,SAAO,CACL,WAC6C;AAC7C,UAAM,SAAS,IAAI;AAAA,MACjB,OAAO;AAAA,MACP,IAAI,uBAAA;AAAA,IAAiD;AAEvD,UAAM,WAAW,IAAI;AAAA,MACnB,OAAO,MAAM,kBAAA;AAAA,MACb,OAAO,cAAA;AAAA,MACP,OAAO;AAAA,MACP;AAAA,MACA;AAAA,IAAA;AAEF,WAAO,MAAM,YAAY,QAAQ;AACjC,WAAO;AAAA,EACT;AACF;"}

package/dist/esm/utils.js

@@ -105,6 +105,14 @@ function range(start, end) {
 }
 function compareKeys(a, b) {
   if (typeof a === typeof b) {
+    if (typeof a === `number` && typeof b === `number`) {
+      const aIsNaN = Number.isNaN(a);
+      const bIsNaN = Number.isNaN(b);
+      if (aIsNaN || bIsNaN) {
+        if (aIsNaN && bIsNaN) return 0;
+        return aIsNaN ? 1 : -1;
+      }
+    }
     if (a < b) return -1;
     if (a > b) return 1;
     return 0;

package/dist/esm/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sources":["../../src/utils.ts"],"sourcesContent":["/**\n * Simple assertion function for runtime checks.\n * Throws an error if the condition is false.\n */\nexport function assert(\n  condition: unknown,\n  message?: string,\n): asserts condition {\n  if (!condition) {\n    throw new Error(message || `Assertion failed`)\n  }\n}\n\n/**\n * A map that returns a default value for keys that are not present.\n */\nexport class DefaultMap<K, V> extends Map<K, V> {\n  constructor(\n    private defaultValue: () => V,\n    entries?: Iterable<[K, V]>,\n  ) {\n    super(entries)\n  }\n\n  get(key: K): V {\n    if (!this.has(key)) {\n      // this.set(key, this.defaultValue())\n      return this.defaultValue()\n    }\n    return super.get(key)!\n  }\n\n  /**\n   * Update the value for a key using a function.\n   */\n  update(key: K, updater: (value: V) => V): V {\n    const value = this.get(key)\n    const newValue = updater(value)\n    this.set(key, newValue)\n    return newValue\n  }\n}\n\n// JS engines have various limits on how many args can be passed to a function\n// with a spread operator, so we need to split the operation into chunks\n// 32767 is the max for Chrome 14, all others are higher\n// TODO: investigate the performance of this and other approaches\nconst chunkSize = 30000\nexport function chunkedArrayPush(array: Array<unknown>, other: Array<unknown>) {\n  if (other.length <= chunkSize) {\n    array.push(...other)\n  } else {\n    for (let i = 0; i < other.length; i += chunkSize) {\n      const chunk = other.slice(i, i + chunkSize)\n      array.push(...chunk)\n    }\n  }\n}\n\nexport function binarySearch<T>(\n  array: Array<T>,\n  value: T,\n  comparator: (a: T, b: T) => number,\n): number {\n  let low = 0\n  let high = array.length\n  while (low < high) {\n    const mid = Math.floor((low + high) / 2)\n    const comparison = comparator(array[mid]!, value)\n    if (comparison < 0) {\n      low = mid + 1\n    } else if (comparison > 0) {\n      high = mid\n    } else {\n      return mid\n    }\n  }\n  return low\n}\n\n/**\n * Utility for generating unique IDs for objects and values.\n * Uses WeakMap for object reference tracking and consistent hashing for primitives.\n */\nexport class ObjectIdGenerator {\n  private objectIds = new WeakMap<object, number>()\n  private nextId = 0\n\n  /**\n   * Get a unique identifier for any value.\n   * - Objects: Uses WeakMap for reference-based identity\n   * - Primitives: Uses consistent string-based hashing\n   */\n  getId(value: any): number {\n    // For primitives, use a simple hash of their string representation\n    if (typeof value !== `object` || value === null) {\n      const str = String(value)\n      let hashValue = 0\n      for (let i = 0; i < str.length; i++) {\n        const char = str.charCodeAt(i)\n        hashValue = (hashValue << 5) - hashValue + char\n        hashValue = hashValue & hashValue // Convert to 32-bit integer\n      }\n      return hashValue\n    }\n\n    // For objects, use WeakMap to assign unique IDs\n    if (!this.objectIds.has(value)) {\n      this.objectIds.set(value, this.nextId++)\n    }\n    return this.objectIds.get(value)!\n  }\n\n  /**\n   * Get a string representation of the ID for use in composite keys.\n   */\n  getStringId(value: any): string {\n    if (value === null) return `null`\n    if (value === undefined) return `undefined`\n    if (typeof value !== `object`) return `str_${String(value)}`\n\n    return `obj_${this.getId(value)}`\n  }\n}\n\n/**\n * Global instance for cases where a shared object ID space is needed.\n */\nexport const globalObjectIdGenerator = new ObjectIdGenerator()\n\nexport function* concatIterable<T>(\n  ...iterables: Array<Iterable<T>>\n): Iterable<T> {\n  for (const iterable of iterables) {\n    yield* iterable\n  }\n}\n\nexport function* mapIterable<T, U>(\n  it: Iterable<T>,\n  fn: (t: T) => U,\n): Iterable<U> {\n  for (const t of it) {\n    yield fn(t)\n  }\n}\n\nexport type HRange = [number, number] // half-open [start, end[ i.e. end is exclusive\n\n/**\n * Computes the difference between two half-open ranges.\n * @param a - The first half-open range\n * @param b - The second half-open range\n * @returns The difference between the two ranges\n */\nexport function diffHalfOpen(a: HRange, b: HRange) {\n  const [a1, a2] = a\n  const [b1, b2] = b\n\n  // A \\ B can be up to two segments (left and right of the overlap)\n  const onlyInA: Array<number> = [\n    ...range(a1, Math.min(a2, b1)), // left side of A outside B\n    ...range(Math.max(a1, b2), a2), // right side of A outside B\n  ]\n\n  // B \\ A similarly\n  const onlyInB: Array<number> = [\n    ...range(b1, Math.min(b2, a1)),\n    ...range(Math.max(b1, a2), b2),\n  ]\n\n  return { onlyInA, onlyInB }\n}\n\nfunction range(start: number, end: number): Array<number> {\n  const out: Array<number> = []\n  for (let i = start; i < end; i++) out.push(i)\n  return out\n}\n\n/**\n * Compares two keys (string | number) in a consistent, deterministic way.\n * Handles mixed types by ordering strings before numbers.\n */\nexport function compareKeys(a: string | number, b: string | number): number {\n  // Same type: compare directly\n  if (typeof a === typeof b) {\n    if (a < b) return -1\n    if (a > b) return 1\n    return 0\n  }\n  // Different types: strings come before numbers\n  return typeof a === `string` ? -1 : 1\n}\n\ntype CanonicalValue =\n  | readonly [`undefined`]\n  | readonly [`null`]\n  | readonly [`boolean`, boolean]\n  | readonly [`number`, number | `NaN` | `Infinity` | `-Infinity`]\n  | readonly [`bigint`, string]\n  | readonly [`string`, string]\n  | readonly [`date`, number | `Invalid`]\n  | readonly [`regexp`, string, string]\n  | readonly [`bytes`, Array<number>]\n  | readonly [`array`, Array<CanonicalValue>]\n  | readonly [`map`, Array<readonly [CanonicalValue, CanonicalValue]>]\n  | readonly [`set`, Array<CanonicalValue>]\n  | readonly [`object`, Array<readonly [string, CanonicalValue]>]\n\n/**\n * Serializes a supported query value into one canonical key.\n *\n * JSON's native encoding is not suitable for relation keys: it merges BigInt\n * with strings when a replacer is used, merges NaN with null, drops undefined,\n * and depends on object insertion order. Ordinary JSON values keep their\n * established wire form. Values that need richer types use a reserved prefix\n * plus a structural, type-tagged encoding.\n */\nexport function serializeValue(value: unknown): string {\n  if (isJsonSafeStructuralValue(value, new Set())) {\n    return JSON.stringify(toStableJsonValue(value))\n  }\n\n  return `~${JSON.stringify(toCanonicalValue(value, new Set()))}`\n}\n\ntype JsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | Array<JsonValue>\n  | { [key: string]: JsonValue }\n\nfunction isJsonSafeStructuralValue(\n  value: unknown,\n  ancestors: Set<object>,\n): boolean {\n  if (value === null) return true\n\n  switch (typeof value) {\n    case `boolean`:\n    case `string`:\n      return true\n    case `number`:\n      return Number.isFinite(value)\n    case `undefined`:\n    case `bigint`:\n    case `symbol`:\n    case `function`:\n      return false\n  }\n\n  return withAcyclicValue(value, ancestors, () => {\n    if (\n      value instanceof Date ||\n      value instanceof RegExp ||\n      value instanceof Uint8Array ||\n      value instanceof Map ||\n      value instanceof Set\n    ) {\n      return false\n    }\n\n    return Array.isArray(value)\n      ? value.every((item) => isJsonSafeStructuralValue(item, ancestors))\n      : Object.keys(value).every((key) =>\n          isJsonSafeStructuralValue(\n            (value as Record<string, unknown>)[key],\n            ancestors,\n          ),\n        )\n  })\n}\n\nfunction toStableJsonValue(value: unknown): JsonValue {\n  if (\n    value === null ||\n    typeof value === `boolean` ||\n    typeof value === `number` ||\n    typeof value === `string`\n  ) {\n    return value\n  }\n\n  if (Array.isArray(value)) {\n    return value.map(toStableJsonValue)\n  }\n\n  return Object.fromEntries(\n    Object.keys(value as object)\n      .sort()\n      .map((key) => [\n        key,\n        toStableJsonValue((value as Record<string, unknown>)[key]),\n      ]),\n  )\n}\n\nfunction toCanonicalValue(\n  value: unknown,\n  ancestors: Set<object>,\n): CanonicalValue {\n  if (value === undefined) return [`undefined`]\n  if (value === null) return [`null`]\n\n  switch (typeof value) {\n    case `boolean`:\n      return [`boolean`, value]\n    case `number`:\n      if (Number.isNaN(value)) return [`number`, `NaN`]\n      if (value === Infinity) return [`number`, `Infinity`]\n      if (value === -Infinity) return [`number`, `-Infinity`]\n      return [`number`, value === 0 ? 0 : value]\n    case `bigint`:\n      return [`bigint`, value.toString()]\n    case `string`:\n      return [`string`, value]\n    case `symbol`:\n    case `function`:\n      throw new TypeError(\n        `Cannot serialize ${typeof value} as a structural relation key`,\n      )\n  }\n\n  return withAcyclicValue(value, ancestors, () => {\n    if (value instanceof Date) {\n      const timestamp = value.getTime()\n      return Number.isNaN(timestamp)\n        ? ([`date`, `Invalid`] as const)\n        : ([`date`, timestamp] as const)\n    }\n\n    if (value instanceof RegExp) {\n      return [`regexp`, value.source, value.flags]\n    }\n\n    if (value instanceof Uint8Array) {\n      return [`bytes`, Array.from(value)]\n    }\n\n    if (Array.isArray(value)) {\n      return [`array`, value.map((item) => toCanonicalValue(item, ancestors))]\n    }\n\n    if (value instanceof Map) {\n      const entries = [...value.entries()].map(\n        ([key, entryValue]) =>\n          [\n            toCanonicalValue(key, ancestors),\n            toCanonicalValue(entryValue, ancestors),\n          ] as const,\n      )\n      entries.sort((left, right) =>\n        compareSerializedValues(JSON.stringify(left), JSON.stringify(right)),\n      )\n      return [`map`, entries]\n    }\n\n    if (value instanceof Set) {\n      const entries = [...value].map((entry) =>\n        toCanonicalValue(entry, ancestors),\n      )\n      entries.sort((left, right) =>\n        compareSerializedValues(JSON.stringify(left), JSON.stringify(right)),\n      )\n      return [`set`, entries]\n    }\n\n    const entries = Object.keys(value)\n      .sort()\n      .map(\n        (key) =>\n          [\n            key,\n            toCanonicalValue(\n              (value as Record<string, unknown>)[key],\n              ancestors,\n            ),\n          ] as const,\n      )\n    return [`object`, entries]\n  })\n}\n\nfunction compareSerializedValues(left: string, right: string): number {\n  return left < right ? -1 : left > right ? 1 : 0\n}\n\nfunction withAcyclicValue<T>(\n  value: object,\n  ancestors: Set<object>,\n  encode: () => T,\n): T {\n  if (ancestors.has(value)) {\n    throw new TypeError(`Cannot serialize a cyclic structural relation key`)\n  }\n\n  ancestors.add(value)\n  try {\n    return encode()\n  } finally {\n    ancestors.delete(value)\n  }\n}\n"],"names":["entries"],"mappings":"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"}
+{"version":3,"file":"utils.js","sources":["../../src/utils.ts"],"sourcesContent":["/**\n * Simple assertion function for runtime checks.\n * Throws an error if the condition is false.\n */\nexport function assert(\n  condition: unknown,\n  message?: string,\n): asserts condition {\n  if (!condition) {\n    throw new Error(message || `Assertion failed`)\n  }\n}\n\n/**\n * A map that returns a default value for keys that are not present.\n */\nexport class DefaultMap<K, V> extends Map<K, V> {\n  constructor(\n    private defaultValue: () => V,\n    entries?: Iterable<[K, V]>,\n  ) {\n    super(entries)\n  }\n\n  get(key: K): V {\n    if (!this.has(key)) {\n      // this.set(key, this.defaultValue())\n      return this.defaultValue()\n    }\n    return super.get(key)!\n  }\n\n  /**\n   * Update the value for a key using a function.\n   */\n  update(key: K, updater: (value: V) => V): V {\n    const value = this.get(key)\n    const newValue = updater(value)\n    this.set(key, newValue)\n    return newValue\n  }\n}\n\n// JS engines have various limits on how many args can be passed to a function\n// with a spread operator, so we need to split the operation into chunks\n// 32767 is the max for Chrome 14, all others are higher\n// TODO: investigate the performance of this and other approaches\nconst chunkSize = 30000\nexport function chunkedArrayPush(array: Array<unknown>, other: Array<unknown>) {\n  if (other.length <= chunkSize) {\n    array.push(...other)\n  } else {\n    for (let i = 0; i < other.length; i += chunkSize) {\n      const chunk = other.slice(i, i + chunkSize)\n      array.push(...chunk)\n    }\n  }\n}\n\nexport function binarySearch<T>(\n  array: Array<T>,\n  value: T,\n  comparator: (a: T, b: T) => number,\n): number {\n  let low = 0\n  let high = array.length\n  while (low < high) {\n    const mid = Math.floor((low + high) / 2)\n    const comparison = comparator(array[mid]!, value)\n    if (comparison < 0) {\n      low = mid + 1\n    } else if (comparison > 0) {\n      high = mid\n    } else {\n      return mid\n    }\n  }\n  return low\n}\n\n/**\n * Utility for generating unique IDs for objects and values.\n * Uses WeakMap for object reference tracking and consistent hashing for primitives.\n */\nexport class ObjectIdGenerator {\n  private objectIds = new WeakMap<object, number>()\n  private nextId = 0\n\n  /**\n   * Get a unique identifier for any value.\n   * - Objects: Uses WeakMap for reference-based identity\n   * - Primitives: Uses consistent string-based hashing\n   */\n  getId(value: any): number {\n    // For primitives, use a simple hash of their string representation\n    if (typeof value !== `object` || value === null) {\n      const str = String(value)\n      let hashValue = 0\n      for (let i = 0; i < str.length; i++) {\n        const char = str.charCodeAt(i)\n        hashValue = (hashValue << 5) - hashValue + char\n        hashValue = hashValue & hashValue // Convert to 32-bit integer\n      }\n      return hashValue\n    }\n\n    // For objects, use WeakMap to assign unique IDs\n    if (!this.objectIds.has(value)) {\n      this.objectIds.set(value, this.nextId++)\n    }\n    return this.objectIds.get(value)!\n  }\n\n  /**\n   * Get a string representation of the ID for use in composite keys.\n   */\n  getStringId(value: any): string {\n    if (value === null) return `null`\n    if (value === undefined) return `undefined`\n    if (typeof value !== `object`) return `str_${String(value)}`\n\n    return `obj_${this.getId(value)}`\n  }\n}\n\n/**\n * Global instance for cases where a shared object ID space is needed.\n */\nexport const globalObjectIdGenerator = new ObjectIdGenerator()\n\nexport function* concatIterable<T>(\n  ...iterables: Array<Iterable<T>>\n): Iterable<T> {\n  for (const iterable of iterables) {\n    yield* iterable\n  }\n}\n\nexport function* mapIterable<T, U>(\n  it: Iterable<T>,\n  fn: (t: T) => U,\n): Iterable<U> {\n  for (const t of it) {\n    yield fn(t)\n  }\n}\n\nexport type HRange = [number, number] // half-open [start, end[ i.e. end is exclusive\n\n/**\n * Computes the difference between two half-open ranges.\n * @param a - The first half-open range\n * @param b - The second half-open range\n * @returns The difference between the two ranges\n */\nexport function diffHalfOpen(a: HRange, b: HRange) {\n  const [a1, a2] = a\n  const [b1, b2] = b\n\n  // A \\ B can be up to two segments (left and right of the overlap)\n  const onlyInA: Array<number> = [\n    ...range(a1, Math.min(a2, b1)), // left side of A outside B\n    ...range(Math.max(a1, b2), a2), // right side of A outside B\n  ]\n\n  // B \\ A similarly\n  const onlyInB: Array<number> = [\n    ...range(b1, Math.min(b2, a1)),\n    ...range(Math.max(b1, a2), b2),\n  ]\n\n  return { onlyInA, onlyInB }\n}\n\nfunction range(start: number, end: number): Array<number> {\n  const out: Array<number> = []\n  for (let i = start; i < end; i++) out.push(i)\n  return out\n}\n\n/**\n * Compares two keys (string | number) in a consistent, deterministic way.\n * Handles mixed types by ordering strings before numbers.\n */\nexport function compareKeys(a: string | number, b: string | number): number {\n  // Same type: compare directly\n  if (typeof a === typeof b) {\n    if (typeof a === `number` && typeof b === `number`) {\n      const aIsNaN = Number.isNaN(a)\n      const bIsNaN = Number.isNaN(b)\n      if (aIsNaN || bIsNaN) {\n        if (aIsNaN && bIsNaN) return 0\n        return aIsNaN ? 1 : -1\n      }\n    }\n    if (a < b) return -1\n    if (a > b) return 1\n    return 0\n  }\n  // Different types: strings come before numbers\n  return typeof a === `string` ? -1 : 1\n}\n\ntype CanonicalValue =\n  | readonly [`undefined`]\n  | readonly [`null`]\n  | readonly [`boolean`, boolean]\n  | readonly [`number`, number | `NaN` | `Infinity` | `-Infinity`]\n  | readonly [`bigint`, string]\n  | readonly [`string`, string]\n  | readonly [`date`, number | `Invalid`]\n  | readonly [`regexp`, string, string]\n  | readonly [`bytes`, Array<number>]\n  | readonly [`array`, Array<CanonicalValue>]\n  | readonly [`map`, Array<readonly [CanonicalValue, CanonicalValue]>]\n  | readonly [`set`, Array<CanonicalValue>]\n  | readonly [`object`, Array<readonly [string, CanonicalValue]>]\n\n/**\n * Serializes a supported query value into one canonical key.\n *\n * JSON's native encoding is not suitable for relation keys: it merges BigInt\n * with strings when a replacer is used, merges NaN with null, drops undefined,\n * and depends on object insertion order. Ordinary JSON values keep their\n * established wire form. Values that need richer types use a reserved prefix\n * plus a structural, type-tagged encoding.\n */\nexport function serializeValue(value: unknown): string {\n  if (isJsonSafeStructuralValue(value, new Set())) {\n    return JSON.stringify(toStableJsonValue(value))\n  }\n\n  return `~${JSON.stringify(toCanonicalValue(value, new Set()))}`\n}\n\ntype JsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | Array<JsonValue>\n  | { [key: string]: JsonValue }\n\nfunction isJsonSafeStructuralValue(\n  value: unknown,\n  ancestors: Set<object>,\n): boolean {\n  if (value === null) return true\n\n  switch (typeof value) {\n    case `boolean`:\n    case `string`:\n      return true\n    case `number`:\n      return Number.isFinite(value)\n    case `undefined`:\n    case `bigint`:\n    case `symbol`:\n    case `function`:\n      return false\n  }\n\n  return withAcyclicValue(value, ancestors, () => {\n    if (\n      value instanceof Date ||\n      value instanceof RegExp ||\n      value instanceof Uint8Array ||\n      value instanceof Map ||\n      value instanceof Set\n    ) {\n      return false\n    }\n\n    return Array.isArray(value)\n      ? value.every((item) => isJsonSafeStructuralValue(item, ancestors))\n      : Object.keys(value).every((key) =>\n          isJsonSafeStructuralValue(\n            (value as Record<string, unknown>)[key],\n            ancestors,\n          ),\n        )\n  })\n}\n\nfunction toStableJsonValue(value: unknown): JsonValue {\n  if (\n    value === null ||\n    typeof value === `boolean` ||\n    typeof value === `number` ||\n    typeof value === `string`\n  ) {\n    return value\n  }\n\n  if (Array.isArray(value)) {\n    return value.map(toStableJsonValue)\n  }\n\n  return Object.fromEntries(\n    Object.keys(value as object)\n      .sort()\n      .map((key) => [\n        key,\n        toStableJsonValue((value as Record<string, unknown>)[key]),\n      ]),\n  )\n}\n\nfunction toCanonicalValue(\n  value: unknown,\n  ancestors: Set<object>,\n): CanonicalValue {\n  if (value === undefined) return [`undefined`]\n  if (value === null) return [`null`]\n\n  switch (typeof value) {\n    case `boolean`:\n      return [`boolean`, value]\n    case `number`:\n      if (Number.isNaN(value)) return [`number`, `NaN`]\n      if (value === Infinity) return [`number`, `Infinity`]\n      if (value === -Infinity) return [`number`, `-Infinity`]\n      return [`number`, value === 0 ? 0 : value]\n    case `bigint`:\n      return [`bigint`, value.toString()]\n    case `string`:\n      return [`string`, value]\n    case `symbol`:\n    case `function`:\n      throw new TypeError(\n        `Cannot serialize ${typeof value} as a structural relation key`,\n      )\n  }\n\n  return withAcyclicValue(value, ancestors, () => {\n    if (value instanceof Date) {\n      const timestamp = value.getTime()\n      return Number.isNaN(timestamp)\n        ? ([`date`, `Invalid`] as const)\n        : ([`date`, timestamp] as const)\n    }\n\n    if (value instanceof RegExp) {\n      return [`regexp`, value.source, value.flags]\n    }\n\n    if (value instanceof Uint8Array) {\n      return [`bytes`, Array.from(value)]\n    }\n\n    if (Array.isArray(value)) {\n      return [`array`, value.map((item) => toCanonicalValue(item, ancestors))]\n    }\n\n    if (value instanceof Map) {\n      const entries = [...value.entries()].map(\n        ([key, entryValue]) =>\n          [\n            toCanonicalValue(key, ancestors),\n            toCanonicalValue(entryValue, ancestors),\n          ] as const,\n      )\n      entries.sort((left, right) =>\n        compareSerializedValues(JSON.stringify(left), JSON.stringify(right)),\n      )\n      return [`map`, entries]\n    }\n\n    if (value instanceof Set) {\n      const entries = [...value].map((entry) =>\n        toCanonicalValue(entry, ancestors),\n      )\n      entries.sort((left, right) =>\n        compareSerializedValues(JSON.stringify(left), JSON.stringify(right)),\n      )\n      return [`set`, entries]\n    }\n\n    const entries = Object.keys(value)\n      .sort()\n      .map(\n        (key) =>\n          [\n            key,\n            toCanonicalValue(\n              (value as Record<string, unknown>)[key],\n              ancestors,\n            ),\n          ] as const,\n      )\n    return [`object`, entries]\n  })\n}\n\nfunction compareSerializedValues(left: string, right: string): number {\n  return left < right ? -1 : left > right ? 1 : 0\n}\n\nfunction withAcyclicValue<T>(\n  value: object,\n  ancestors: Set<object>,\n  encode: () => T,\n): T {\n  if (ancestors.has(value)) {\n    throw new TypeError(`Cannot serialize a cyclic structural relation key`)\n  }\n\n  ancestors.add(value)\n  try {\n    return encode()\n  } finally {\n    ancestors.delete(value)\n  }\n}\n"],"names":["entries"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/db-ivm",
-  "version": "0.1.19",
+  "version": "0.1.22",
   "description": "Incremental View Maintenance for TanStack DB based on Differential Dataflow",
   "author": "Sam Willis",
   "license": "MIT",
@@ -56,6 +56,9 @@
     "build": "vite build",
     "dev": "vite build --watch",
     "lint": "eslint . --fix",
-    "test": "vitest --run"
+    "test": "vitest --run",
+    "test:incrementalization": "vitest --run tests/incrementalization-law.property.test.ts",
+    "typecheck": "tsc --noEmit",
+    "bench:hash": "vitest bench --run tests/hash.bench.ts --coverage.enabled=false"
   }
 }

package/src/hashing/hash.ts

@@ -1,4 +1,4 @@
-import { MurmurHashStream, randomHash } from './murmur.js'
+import { MurmurHashStream, getSymbolIdentity, randomHash } from './murmur.js'
 import type { Hasher } from './murmur.js'
 
 /*
@@ -13,12 +13,18 @@ const UNDEFINED = randomHash()
 const KEY = randomHash()
 const FUNCTIONS = randomHash()
 const DATE_MARKER = randomHash()
-const OBJECT_MARKER = randomHash()
-const ARRAY_MARKER = randomHash()
-const MAP_MARKER = randomHash()
-const SET_MARKER = randomHash()
+const STRUCTURAL_MARKERS = {
+  object: randomHash(),
+  array: randomHash(),
+  map: randomHash(),
+  set: randomHash(),
+}
 const UINT8ARRAY_MARKER = randomHash()
 const TEMPORAL_MARKER = randomHash()
+// Bound structural recursion and value visits. Shared acyclic subtrees are
+// cached; cycles are rejected rather than given context-dependent hashes.
+const MAX_STRUCTURAL_HASH_WORK = 1_000_000
+const MAX_STRUCTURAL_HASH_DEPTH = 768
 
 const temporalTypes = new Set([
   `Temporal.Duration`,
@@ -47,6 +53,18 @@ function isTemporal(input: object): input is TemporalLike {
 const UINT8ARRAY_CONTENT_HASH_THRESHOLD = 128
 
 const hashCache = new WeakMap<object, number>()
+const referenceValues = new WeakSet<object>()
+
+/** @internal Register a mutable handle before it enters a structural value. */
+export function registerOpaqueHash(value: object): void {
+  cachedReferenceHash(value)
+}
+
+type HashContext = {
+  activeObjects: Set<object>
+  work: number
+  pendingHashes: Map<object, number>
+}
 
 export function hash(input: any): number {
   const hasher = new MurmurHashStream()
@@ -54,57 +72,36 @@ export function hash(input: any): number {
   return hasher.digest()
 }
 
-function hashObject(input: object): number {
-  const cachedHash = hashCache.get(input)
-  if (cachedHash !== undefined) {
-    return cachedHash
+function hashObject(input: object, context: HashContext): number {
+  if (context.activeObjects.size >= MAX_STRUCTURAL_HASH_DEPTH) {
+    throw new RangeError(
+      `Value is too complex to hash safely: structural depth`,
+    )
   }
 
+  context.activeObjects.add(input)
+
   let valueHash: number | undefined
-  if (input instanceof Date) {
-    valueHash = hashDate(input)
-  } else if (
-    // Check if input is a Uint8Array or Buffer
-    (typeof Buffer !== `undefined` && input instanceof Buffer) ||
-    input instanceof Uint8Array
-  ) {
-    // For small Uint8Arrays/Buffers (e.g., ULIDs, UUIDs), hash by content
-    // to enable proper equality comparisons. For large arrays, hash by reference
-    // to avoid performance costs.
-    if (input.byteLength <= UINT8ARRAY_CONTENT_HASH_THRESHOLD) {
+  try {
+    if (input instanceof Date) {
+      valueHash = hashDate(input)
+    } else if (isBinaryValue(input)) {
       valueHash = hashUint8Array(input)
+    } else if (isTemporal(input)) {
+      valueHash = hashTemporal(input)
     } else {
-      // Deeply hashing large arrays would be too costly
-      // so we track them by reference and cache them in a weak map
-      return cachedReferenceHash(input)
-    }
-  } else if (input instanceof File) {
-    // Files are always hashed by reference due to their potentially large size
-    return cachedReferenceHash(input)
-  } else if (isTemporal(input)) {
-    valueHash = hashTemporal(input)
-  } else {
-    let plainObjectInput = input
-    let marker = OBJECT_MARKER
-
-    if (input instanceof Array) {
-      marker = ARRAY_MARKER
-    }
-
-    if (input instanceof Map) {
-      marker = MAP_MARKER
-      plainObjectInput = [...input.entries()]
-    }
-
-    if (input instanceof Set) {
-      marker = SET_MARKER
-      plainObjectInput = [...input.entries()]
+      const [kind, plainObjectInput] = structuralShape(input)
+      valueHash = hashPlainObject(
+        plainObjectInput,
+        STRUCTURAL_MARKERS[kind],
+        context,
+      )
     }
-
-    valueHash = hashPlainObject(plainObjectInput, marker)
+  } finally {
+    context.activeObjects.delete(input)
   }
 
-  hashCache.set(input, valueHash)
+  context.pendingHashes.set(input, valueHash)
   return valueHash
 }
 
@@ -135,7 +132,11 @@ function hashTemporal(input: TemporalLike): number {
   return hasher.digest()
 }
 
-function hashPlainObject(input: object, marker: number): number {
+function hashPlainObject(
+  input: object,
+  marker: number,
+  context: HashContext,
+): number {
   const hasher = new MurmurHashStream()
 
   // Mark the type of the input
@@ -145,13 +146,28 @@ function hashPlainObject(input: object, marker: number): number {
   for (const key of keys) {
     hasher.update(KEY)
     hasher.update(key)
-    updateHasher(hasher, input[key as keyof typeof input])
+    updateHasher(hasher, input[key as keyof typeof input], context)
+  }
+  const symbolKeys = Object.getOwnPropertySymbols(input)
+    .filter((key) => Object.prototype.propertyIsEnumerable.call(input, key))
+    .sort((left, right) => getSymbolIdentity(left) - getSymbolIdentity(right))
+  for (const key of symbolKeys) {
+    hasher.update(KEY)
+    hasher.update(key)
+    updateHasher(hasher, input[key as keyof typeof input], context)
   }
 
   return hasher.digest()
 }
 
-function updateHasher(hasher: Hasher, input: unknown): void {
+function updateHasher(
+  hasher: Hasher,
+  input: unknown,
+  context?: HashContext,
+): void {
+  if (context && ++context.work > MAX_STRUCTURAL_HASH_WORK) {
+    throw new RangeError(`Value is too complex to hash safely: structural work`)
+  }
   if (input === null) {
     hasher.update(NULL)
     return
@@ -173,7 +189,7 @@ function updateHasher(hasher: Hasher, input: unknown): void {
       hasher.update(input)
       return
     case `object`:
-      hasher.update(getCachedHash(input))
+      hasher.update(getCachedHash(input, context))
       return
     case `function`:
       // Functions are assigned a globally unique ID
@@ -187,12 +203,127 @@ function updateHasher(hasher: Hasher, input: unknown): void {
   }
 }
 
-function getCachedHash(input: object): number {
-  let valueHash = hashCache.get(input)
-  if (valueHash === undefined) {
-    valueHash = hashObject(input)
+function getCachedHash(input: object, context?: HashContext): number {
+  if (!context) {
+    const cached = hashCache.get(input)
+    if (cached !== undefined) return cached
+    if (isReferenceHashedObject(input)) return cachedReferenceHash(input)
+
+    // Only an uncached structural root needs graph traversal state. Commit its
+    // cache entries after success so a failed traversal cannot poison retries.
+    context = {
+      activeObjects: new Set(),
+      work: 0,
+      pendingHashes: new Map(),
+    }
+    const result = hashObject(input, context)
+    for (const [object, valueHash] of context.pendingHashes) {
+      hashCache.set(object, valueHash)
+    }
+    return result
   }
-  return valueHash
+
+  if (context.activeObjects.has(input)) {
+    throw new TypeError(`Cannot hash cyclic structural values`)
+  }
+
+  // Opaque leaves cannot contain structural back-references. Resolve them
+  // before entering structural recursion, even when they have user properties.
+  if (isReferenceHashedObject(input)) return cachedReferenceHash(input)
+
+  const valueHash = hashCache.get(input) ?? context.pendingHashes.get(input)
+  if (valueHash !== undefined) return valueHash
+
+  return hashObject(input, context)
+}
+
+function isReferenceHashedObject(input: object): boolean {
+  return (
+    input instanceof File ||
+    (isBinaryValue(input) &&
+      input.byteLength > UINT8ARRAY_CONTENT_HASH_THRESHOLD)
+  )
+}
+
+function isBinaryValue(input: object): input is Uint8Array {
+  return (
+    (typeof Buffer !== `undefined` && input instanceof Buffer) ||
+    input instanceof Uint8Array
+  )
+}
+
+function structuralShape(
+  input: object,
+): [keyof typeof STRUCTURAL_MARKERS, object] {
+  if (input instanceof Map) return [`map`, [...input.entries()]]
+  if (input instanceof Set) return [`set`, [...input.values()]]
+  return [input instanceof Array ? `array` : `object`, input]
+}
+
+/** @internal Compare immutable structural values without computing a digest.
+ * Pair memoization also permits cyclic values that structural hashing rejects.
+ * Reference-valued leaves remain opaque, including registered mutable handles.
+ */
+export function equalHashValues(left: unknown, right: unknown): boolean {
+  const compared = new Map<object, Set<object>>()
+  function equal(a: unknown, b: unknown): boolean {
+    if (a === b || (Number.isNaN(a) && Number.isNaN(b))) return true
+    if (
+      a === null ||
+      b === null ||
+      typeof a !== `object` ||
+      typeof b !== `object`
+    )
+      return false
+    if (
+      referenceValues.has(a) ||
+      referenceValues.has(b) ||
+      isReferenceHashedObject(a) ||
+      isReferenceHashedObject(b)
+    )
+      return false
+    if (a instanceof Date || b instanceof Date)
+      return (
+        a instanceof Date &&
+        b instanceof Date &&
+        equal(a.getTime(), b.getTime())
+      )
+    if (isBinaryValue(a) || isBinaryValue(b))
+      return (
+        isBinaryValue(a) &&
+        isBinaryValue(b) &&
+        a.byteLength === b.byteLength &&
+        a.every((value, index) => value === b[index])
+      )
+    if (isTemporal(a) || isTemporal(b))
+      return (
+        isTemporal(a) &&
+        isTemporal(b) &&
+        a[Symbol.toStringTag] === b[Symbol.toStringTag] &&
+        a.toString() === b.toString()
+      )
+
+    // Revisited pairs close cycles and avoid expanding shared subtrees.
+    const peers = compared.get(a)
+    if (peers?.has(b)) return true
+    if (peers) peers.add(b)
+    else compared.set(a, new Set([b]))
+    const [aKind, aShape] = structuralShape(a)
+    const [bKind, bShape] = structuralShape(b)
+    if (aKind !== bKind) return false
+    const keys = (value: object) =>
+      Reflect.ownKeys(value).filter((key) =>
+        Object.prototype.propertyIsEnumerable.call(value, key),
+      )
+    const aKeys = keys(aShape)
+    if (aKeys.length !== keys(bShape).length) return false
+    return aKeys.every(
+      (key) =>
+        Object.prototype.propertyIsEnumerable.call(bShape, key) &&
+        equal(aShape[key as keyof object], bShape[key as keyof object]),
+    )
+  }
+  return equal(left, right)
 }
 
 let nextRefId = 1
@@ -202,6 +333,7 @@ function cachedReferenceHash(fn: object): number {
     valueHash = nextRefId ^ FUNCTIONS
     nextRefId++
     hashCache.set(fn, valueHash)
+    referenceValues.add(fn)
   }
   return valueHash
 }

package/src/hashing/murmur.ts

@@ -9,6 +9,49 @@ const BIG_INT_MARKER = randomHash()
 const NEG_BIG_INT_MARKER = randomHash()
 const SYMBOL_MARKER = randomHash()
 
+type SymbolIdStore = {
+  get: (key: symbol) => number | undefined
+  set: (key: symbol, value: number) => unknown
+}
+
+const symbolIds = createSymbolIdStore()
+const registeredSymbolIds = new Map<string, number>()
+let nextSymbolId = 0
+
+export function getSymbolIdentity(symbol: symbol): number {
+  const registeredKey = Symbol.keyFor(symbol)
+  if (registeredKey !== undefined) {
+    let id = registeredSymbolIds.get(registeredKey)
+    if (id === undefined) {
+      id = ++nextSymbolId
+      registeredSymbolIds.set(registeredKey, id)
+    }
+    return id
+  }
+
+  let id = symbolIds.get(symbol)
+  if (id === undefined) {
+    id = ++nextSymbolId
+    symbolIds.set(symbol, id)
+  }
+  return id
+}
+
+function createSymbolIdStore(): SymbolIdStore {
+  const weakIds = new WeakMap<object, number>() as unknown as SymbolIdStore
+  const probe = Symbol()
+
+  try {
+    weakIds.set(probe, 0)
+    if (weakIds.get(probe) === 0) return weakIds
+  } catch {
+    // Older runtimes reject symbols as weak keys. Retain them rather than
+    // merge distinct symbols and corrupt differential state.
+  }
+
+  return new Map<symbol, number>()
+}
+
 export type Hash = number
 
 export function randomHash() {
@@ -67,16 +110,7 @@ export class MurmurHashStream implements Hasher {
     switch (typeof chunk) {
       case `symbol`: {
         this.update(SYMBOL_MARKER)
-        const description = chunk.description
-        if (!description) {
-          return
-        }
-
-        for (let i = 0; i < description.length; i++) {
-          const code = description.charCodeAt(i)
-          this.writeByte(code & 0xff)
-          this.writeByte((code >>> 8) & 0xff)
-        }
+        this.update(getSymbolIdentity(chunk))
         return
       }
       case `string`:

package/src/index.ts

@@ -3,3 +3,4 @@ export * from './multiset.js'
 export * from './operators/index.js'
 export * from './types.js'
 export { compareKeys, serializeValue } from './utils.js'
+export { registerOpaqueHash } from './hashing/hash.js'

package/src/operators/distinct.ts

@@ -85,10 +85,12 @@ export class DistinctOperator<
 export function distinct<T extends KeyValue<any, any>>(
   by: (value: T) => any = (value: T) => value,
 ) {
-  return (stream: IStreamBuilder<T>): IStreamBuilder<T> => {
-    const output = new StreamBuilder<T>(
+  return (
+    stream: IStreamBuilder<T>,
+  ): IStreamBuilder<KeyValue<number, GetValue<T>>> => {
+    const output = new StreamBuilder<KeyValue<number, GetValue<T>>>(
       stream.graph,
-      new DifferenceStreamWriter<T>(),
+      new DifferenceStreamWriter<KeyValue<number, GetValue<T>>>(),
     )
     const operator = new DistinctOperator<T>(
       stream.graph.getNextOperatorId(),

package/src/operators/groupBy.ts

@@ -62,7 +62,7 @@ export function groupBy<
     stream: IStreamBuilder<T>,
   ): IStreamBuilder<KeyValue<string, ResultType>> => {
     // Special key to store the original key object
-    const KEY_SENTINEL = `__original_key__`
+    const KEY_SENTINEL = Symbol(`original_group_key`)
 
     // First map to extract keys and pre-aggregate values
     const withKeysAndValues = stream.pipe(
@@ -71,7 +71,7 @@ export function groupBy<
         const keyString = serializeValue(key)
 
         // Create values object with pre-aggregated values
-        const values: Record<string, unknown> = {}
+        const values: Record<string | symbol, unknown> = {}
 
         // Store the original key object
         values[KEY_SENTINEL] = key
@@ -81,7 +81,10 @@ export function groupBy<
           values[name] = aggregate.preMap(data)
         }
 
-        return [keyString, values] as KeyValue<string, Record<string, unknown>>
+        return [keyString, values] as KeyValue<
+          string,
+          Record<string | symbol, unknown>
+        >
       }),
     )
 
@@ -99,7 +102,7 @@ export function groupBy<
           return []
         }
 
-        const result: Record<string, unknown> = {}
+        const result: Record<PropertyKey, unknown> = {}
 
         // Get the original key from first value in group
         const originalKey = values[0]?.[0]?.[KEY_SENTINEL]

package/src/operators/groupedTopKWithFractionalIndex.ts

@@ -1,7 +1,12 @@
 import { DifferenceStreamWriter, UnaryOperator } from '../graph.js'
 import { StreamBuilder } from '../d2.js'
 import { MultiSet } from '../multiset.js'
-import { TopKState, handleMoveIn, handleMoveOut } from './topKState.js'
+import {
+  TopKState,
+  handleMoveIn,
+  handleMoveOut,
+  topKBatch,
+} from './topKState.js'
 import { TopKArray, createKeyedComparator } from './topKArray.js'
 import type { IndexedValue, TopK } from './topKArray.js'
 import type { DifferenceStreamReader } from '../graph.js'
@@ -125,11 +130,10 @@ export class GroupedTopKWithFractionalIndexOperator<
 
   run(): void {
     const result: Array<[[K, IndexedValue<T>], number]> = []
-    for (const message of this.inputMessages()) {
-      for (const [item, multiplicity] of message.getInner()) {
-        const [key, value] = item
-        this.#processElement(key, value, multiplicity, result)
-      }
+    for (const [[key, value], multiplicity] of topKBatch(
+      this.inputMessages(),
+    )) {
+      this.#processElement(key, value, multiplicity, result)
     }
 
     if (result.length > 0) {

package/src/operators/topKArray.ts

@@ -170,6 +170,8 @@ export class TopKArray<V> implements TopK<V> {
     // Splice is O(n) where n = all elements in the collection (i.e. n >= k) !
     this.#sortedValues.splice(index, 0, val)
 
+    if (this.#topKStart === this.#topKEnd) return result
+
     // Check if the topK changed
     if (index < this.#topKEnd) {
       // The inserted element is either before the top K or within the top K
@@ -209,6 +211,8 @@ export class TopKArray<V> implements TopK<V> {
     // Remove the value at that position
     const [removedElem] = this.#sortedValues.splice(index, 1)
 
+    if (this.#topKStart === this.#topKEnd) return result
+
     // Check if the topK changed
     if (index < this.#topKEnd) {
       // The removed element is either before the top K or within the top K