@tanstack/db-ivm 0.1.19 → 0.1.20

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'
 
 /*
@@ -19,6 +19,10 @@ const MAP_MARKER = randomHash()
 const SET_MARKER = 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`,
@@ -48,63 +52,65 @@ const UINT8ARRAY_CONTENT_HASH_THRESHOLD = 128
 
 const hashCache = new WeakMap<object, number>()
 
+/** @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()
   updateHasher(hasher, input)
   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
-    }
+      let plainObjectInput = input
+      let marker = OBJECT_MARKER
 
-    if (input instanceof Map) {
-      marker = MAP_MARKER
-      plainObjectInput = [...input.entries()]
-    }
+      if (input instanceof Array) {
+        marker = ARRAY_MARKER
+      }
 
-    if (input instanceof Set) {
-      marker = SET_MARKER
-      plainObjectInput = [...input.entries()]
-    }
+      if (input instanceof Map) {
+        marker = MAP_MARKER
+        plainObjectInput = [...input.entries()]
+      }
 
-    valueHash = hashPlainObject(plainObjectInput, marker)
+      if (input instanceof Set) {
+        marker = SET_MARKER
+        plainObjectInput = [...input.entries()]
+      }
+
+      valueHash = hashPlainObject(plainObjectInput, marker, context)
+    }
+  } finally {
+    context.activeObjects.delete(input)
   }
 
-  hashCache.set(input, valueHash)
+  context.pendingHashes.set(input, valueHash)
   return valueHash
 }
 
@@ -135,7 +141,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 +155,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 +198,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 +212,53 @@ 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
+  )
 }
 
 let nextRefId = 1

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/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/utils.ts

@@ -185,6 +185,14 @@ function range(start: number, end: number): Array<number> {
 export function compareKeys(a: string | number, b: string | number): number {
   // Same type: compare directly
   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/cjs/operators/orderByBTree.d.cts

@@ -1,3 +0,0 @@
-import { KeyValue } from '../types.js';
-import { OrderByOptions } from './orderBy.js';
-export declare function orderByWithFractionalIndexBTree<T extends KeyValue<unknown, unknown>, Ve = unknown>(valueExtractor: (value: T extends KeyValue<unknown, infer V> ? V : never) => Ve, options?: OrderByOptions<Ve>): (stream: import('../types.js').IStreamBuilder<T>) => import('../types.js').IStreamBuilder<[T extends KeyValue<infer K, unknown> ? K : never, [T extends KeyValue<unknown, infer V> ? V : never, string]]>;

package/dist/esm/operators/orderByBTree.d.ts

@@ -1,3 +0,0 @@
-import { KeyValue } from '../types.js';
-import { OrderByOptions } from './orderBy.js';
-export declare function orderByWithFractionalIndexBTree<T extends KeyValue<unknown, unknown>, Ve = unknown>(valueExtractor: (value: T extends KeyValue<unknown, infer V> ? V : never) => Ve, options?: OrderByOptions<Ve>): (stream: import('../types.js').IStreamBuilder<T>) => import('../types.js').IStreamBuilder<[T extends KeyValue<infer K, unknown> ? K : never, [T extends KeyValue<unknown, infer V> ? V : never, string]]>;

package/src/operators/orderByBTree.ts

@@ -1,20 +0,0 @@
-import { orderByWithFractionalIndexBase } from './orderBy.js'
-import { topKWithFractionalIndexBTree } from './topKWithFractionalIndexBTree.js'
-import type { KeyValue } from '../types.js'
-import type { OrderByOptions } from './orderBy.js'
-
-export function orderByWithFractionalIndexBTree<
-  T extends KeyValue<unknown, unknown>,
-  Ve = unknown,
->(
-  valueExtractor: (
-    value: T extends KeyValue<unknown, infer V> ? V : never,
-  ) => Ve,
-  options?: OrderByOptions<Ve>,
-) {
-  return orderByWithFractionalIndexBase(
-    topKWithFractionalIndexBTree,
-    valueExtractor,
-    options,
-  )
-}