@tanstack/db-ivm 0.1.14 → 0.1.15

package/dist/esm/operators/topKArray.js

@@ -0,0 +1,137 @@
+import { generateKeyBetween } from "fractional-indexing";
+import { compareKeys, diffHalfOpen, binarySearch } from "../utils.js";
+function indexedValue(value, index) {
+  return [value, index];
+}
+function getValue(indexedVal) {
+  return indexedVal[0];
+}
+function getIndex(indexedVal) {
+  return indexedVal[1];
+}
+function createKeyedComparator(comparator) {
+  return ([aKey, aVal], [bKey, bVal]) => {
+    const valueComparison = comparator(aVal, bVal);
+    if (valueComparison !== 0) {
+      return valueComparison;
+    }
+    return compareKeys(aKey, bKey);
+  };
+}
+class TopKArray {
+  #sortedValues = [];
+  #comparator;
+  #topKStart;
+  #topKEnd;
+  constructor(offset, limit, comparator) {
+    this.#topKStart = offset;
+    this.#topKEnd = offset + limit;
+    this.#comparator = comparator;
+  }
+  get size() {
+    const offset = this.#topKStart;
+    const limit = this.#topKEnd - this.#topKStart;
+    const available = this.#sortedValues.length - offset;
+    return Math.max(0, Math.min(limit, available));
+  }
+  /**
+   * Moves the topK window
+   */
+  move({
+    offset,
+    limit
+  }) {
+    const oldOffset = this.#topKStart;
+    const oldLimit = this.#topKEnd - this.#topKStart;
+    const oldRange = [
+      this.#topKStart,
+      this.#topKEnd === Infinity ? this.#topKStart + this.size : this.#topKEnd
+    ];
+    this.#topKStart = offset ?? oldOffset;
+    this.#topKEnd = this.#topKStart + (limit ?? oldLimit);
+    const newRange = [
+      this.#topKStart,
+      this.#topKEnd === Infinity ? Math.max(this.#topKStart + this.size, oldRange[1]) : this.#topKEnd
+    ];
+    const { onlyInA, onlyInB } = diffHalfOpen(oldRange, newRange);
+    const moveIns = [];
+    onlyInB.forEach((index) => {
+      const value = this.#sortedValues[index];
+      if (value) {
+        moveIns.push(value);
+      }
+    });
+    const moveOuts = [];
+    onlyInA.forEach((index) => {
+      const value = this.#sortedValues[index];
+      if (value) {
+        moveOuts.push(value);
+      }
+    });
+    return { moveIns, moveOuts, changes: onlyInA.length + onlyInB.length > 0 };
+  }
+  insert(value) {
+    const result = { moveIn: null, moveOut: null };
+    const index = this.#findIndex(value);
+    const indexBefore = index === 0 ? null : getIndex(this.#sortedValues[index - 1]);
+    const indexAfter = index === this.#sortedValues.length ? null : getIndex(this.#sortedValues[index]);
+    const fractionalIndex = generateKeyBetween(indexBefore, indexAfter);
+    const val = indexedValue(value, fractionalIndex);
+    this.#sortedValues.splice(index, 0, val);
+    if (index < this.#topKEnd) {
+      const moveInIndex = Math.max(index, this.#topKStart);
+      if (moveInIndex < this.#sortedValues.length) {
+        result.moveIn = this.#sortedValues[moveInIndex];
+        if (this.#topKEnd < this.#sortedValues.length) {
+          result.moveOut = this.#sortedValues[this.#topKEnd];
+        }
+      }
+    }
+    return result;
+  }
+  /**
+   * Deletes a value that may or may not be in the topK.
+   * IMPORTANT: this assumes that the value is present in the collection
+   *            if it's not the case it will remove the element
+   *            that is on the position where the provided `value` would be.
+   */
+  delete(value) {
+    const result = { moveIn: null, moveOut: null };
+    const index = this.#findIndex(value);
+    const [removedElem] = this.#sortedValues.splice(index, 1);
+    if (index < this.#topKEnd) {
+      result.moveOut = removedElem;
+      if (index < this.#topKStart) {
+        const moveOutIndex = this.#topKStart - 1;
+        if (moveOutIndex < this.#sortedValues.length) {
+          result.moveOut = this.#sortedValues[moveOutIndex];
+        } else {
+          result.moveOut = null;
+        }
+      }
+      const moveInIndex = this.#topKEnd - 1;
+      if (moveInIndex < this.#sortedValues.length) {
+        result.moveIn = this.#sortedValues[moveInIndex];
+      }
+    }
+    return result;
+  }
+  // TODO: see if there is a way to refactor the code for insert and delete in the topK above
+  //       because they are very similar, one is shifting the topK window to the left and the other is shifting it to the right
+  //       so i have the feeling there is a common pattern here and we can implement both cases using that pattern
+  #findIndex(value) {
+    return binarySearch(
+      this.#sortedValues,
+      indexedValue(value, ``),
+      (a, b) => this.#comparator(getValue(a), getValue(b))
+    );
+  }
+}
+export {
+  TopKArray,
+  createKeyedComparator,
+  getIndex,
+  getValue,
+  indexedValue
+};
+//# sourceMappingURL=topKArray.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"topKArray.js","sources":["../../../src/operators/topKArray.ts"],"sourcesContent":["import { generateKeyBetween } from 'fractional-indexing'\nimport { binarySearch, compareKeys, diffHalfOpen } from '../utils.js'\nimport type { HRange } from '../utils.js'\n\n// Abstraction for fractionally indexed values\nexport type FractionalIndex = string\nexport type IndexedValue<V> = [V, FractionalIndex]\n\nexport function indexedValue<V>(\n  value: V,\n  index: FractionalIndex,\n): IndexedValue<V> {\n  return [value, index]\n}\n\nexport function getValue<V>(indexedVal: IndexedValue<V>): V {\n  return indexedVal[0]\n}\n\nexport function getIndex<V>(indexedVal: IndexedValue<V>): FractionalIndex {\n  return indexedVal[1]\n}\n\n/**\n * Creates a comparator for [key, value] tuples that first compares values,\n * then uses the row key as a stable tie-breaker.\n */\nexport function createKeyedComparator<K extends string | number, T>(\n  comparator: (a: T, b: T) => number,\n): (a: [K, T], b: [K, T]) => number {\n  return ([aKey, aVal], [bKey, bVal]) => {\n    // First compare on the value\n    const valueComparison = comparator(aVal, bVal)\n    if (valueComparison !== 0) {\n      return valueComparison\n    }\n    // If the values are equal, use the row key as tie-breaker\n    // This provides stable, deterministic ordering since keys are string | number\n    return compareKeys(aKey, bKey)\n  }\n}\n\nexport type TopKChanges<V> = {\n  /** Indicates which element moves into the topK (if any) */\n  moveIn: IndexedValue<V> | null\n  /** Indicates which element moves out of the topK (if any) */\n  moveOut: IndexedValue<V> | null\n}\n\nexport type TopKMoveChanges<V> = {\n  /** Flag that marks whether there were any changes to the topK */\n  changes: boolean\n  /** Indicates which elements move into the topK (if any) */\n  moveIns: Array<IndexedValue<V>>\n  /** Indicates which elements move out of the topK (if any) */\n  moveOuts: Array<IndexedValue<V>>\n}\n\n/**\n * A topK data structure that supports insertions and deletions\n * and returns changes to the topK.\n */\nexport interface TopK<V> {\n  size: number\n  insert: (value: V) => TopKChanges<V>\n  delete: (value: V) => TopKChanges<V>\n}\n\n/**\n * Implementation of a topK data structure.\n * Uses a sorted array internally to store the values and keeps a topK window over that array.\n * Inserts and deletes are O(n) operations because worst case an element is inserted/deleted\n * at the start of the array which causes all the elements to shift to the right/left.\n */\nexport class TopKArray<V> implements TopK<V> {\n  #sortedValues: Array<IndexedValue<V>> = []\n  #comparator: (a: V, b: V) => number\n  #topKStart: number\n  #topKEnd: number\n\n  constructor(\n    offset: number,\n    limit: number,\n    comparator: (a: V, b: V) => number,\n  ) {\n    this.#topKStart = offset\n    this.#topKEnd = offset + limit\n    this.#comparator = comparator\n  }\n\n  get size(): number {\n    const offset = this.#topKStart\n    const limit = this.#topKEnd - this.#topKStart\n    const available = this.#sortedValues.length - offset\n    return Math.max(0, Math.min(limit, available))\n  }\n\n  /**\n   * Moves the topK window\n   */\n  move({\n    offset,\n    limit,\n  }: {\n    offset?: number\n    limit?: number\n  }): TopKMoveChanges<V> {\n    const oldOffset = this.#topKStart\n    const oldLimit = this.#topKEnd - this.#topKStart\n\n    // `this.#topKEnd` can be `Infinity` if it has no limit\n    // but `diffHalfOpen` expects a finite range\n    // so we restrict it to the size of the topK if topKEnd is infinite\n    const oldRange: HRange = [\n      this.#topKStart,\n      this.#topKEnd === Infinity ? this.#topKStart + this.size : this.#topKEnd,\n    ]\n\n    this.#topKStart = offset ?? oldOffset\n    this.#topKEnd = this.#topKStart + (limit ?? oldLimit) // can be `Infinity` if limit is `Infinity`\n\n    // Also handle `Infinity` in the newRange\n    const newRange: HRange = [\n      this.#topKStart,\n      this.#topKEnd === Infinity\n        ? Math.max(this.#topKStart + this.size, oldRange[1]) // since the new limit is Infinity we need to take everything (so we need to take the biggest (finite) topKEnd)\n        : this.#topKEnd,\n    ]\n    const { onlyInA, onlyInB } = diffHalfOpen(oldRange, newRange)\n\n    const moveIns: Array<IndexedValue<V>> = []\n    onlyInB.forEach((index) => {\n      const value = this.#sortedValues[index]\n      if (value) {\n        moveIns.push(value)\n      }\n    })\n\n    const moveOuts: Array<IndexedValue<V>> = []\n    onlyInA.forEach((index) => {\n      const value = this.#sortedValues[index]\n      if (value) {\n        moveOuts.push(value)\n      }\n    })\n\n    // It could be that there are changes (i.e. moveIns or moveOuts)\n    // but that the collection is lazy so we don't have the data yet that needs to move in/out\n    // so `moveIns` and `moveOuts` will be empty but `changes` will be true\n    // this will tell the caller that it needs to run the graph to load more data\n    return { moveIns, moveOuts, changes: onlyInA.length + onlyInB.length > 0 }\n  }\n\n  insert(value: V): TopKChanges<V> {\n    const result: TopKChanges<V> = { moveIn: null, moveOut: null }\n\n    // Lookup insert position\n    const index = this.#findIndex(value)\n    // Generate fractional index based on the fractional indices of the elements before and after it\n    const indexBefore =\n      index === 0 ? null : getIndex(this.#sortedValues[index - 1]!)\n    const indexAfter =\n      index === this.#sortedValues.length\n        ? null\n        : getIndex(this.#sortedValues[index]!)\n    const fractionalIndex = generateKeyBetween(indexBefore, indexAfter)\n\n    // Insert the value at the correct position\n    const val = indexedValue(value, fractionalIndex)\n    // Splice is O(n) where n = all elements in the collection (i.e. n >= k) !\n    this.#sortedValues.splice(index, 0, val)\n\n    // Check if the topK changed\n    if (index < this.#topKEnd) {\n      // The inserted element is either before the top K or within the top K\n      // If it is before the top K then it moves the element that was right before the topK into the topK\n      // If it is within the top K then the inserted element moves into the top K\n      // In both cases the last element of the old top K now moves out of the top K\n      const moveInIndex = Math.max(index, this.#topKStart)\n      if (moveInIndex < this.#sortedValues.length) {\n        // We actually have a topK\n        // because in some cases there may not be enough elements in the array to reach the start of the topK\n        // e.g. [1, 2, 3] with K = 2 and offset = 3 does not have a topK\n        result.moveIn = this.#sortedValues[moveInIndex]!\n\n        // We need to remove the element that falls out of the top K\n        // The element that falls out of the top K has shifted one to the right\n        // because of the element we inserted, so we find it at index topKEnd\n        if (this.#topKEnd < this.#sortedValues.length) {\n          result.moveOut = this.#sortedValues[this.#topKEnd]!\n        }\n      }\n    }\n\n    return result\n  }\n\n  /**\n   * Deletes a value that may or may not be in the topK.\n   * IMPORTANT: this assumes that the value is present in the collection\n   *            if it's not the case it will remove the element\n   *            that is on the position where the provided `value` would be.\n   */\n  delete(value: V): TopKChanges<V> {\n    const result: TopKChanges<V> = { moveIn: null, moveOut: null }\n\n    // Lookup delete position\n    const index = this.#findIndex(value)\n    // Remove the value at that position\n    const [removedElem] = this.#sortedValues.splice(index, 1)\n\n    // Check if the topK changed\n    if (index < this.#topKEnd) {\n      // The removed element is either before the top K or within the top K\n      // If it is before the top K then the first element of the topK moves out of the topK\n      // If it is within the top K then the removed element moves out of the topK\n      result.moveOut = removedElem!\n      if (index < this.#topKStart) {\n        // The removed element is before the topK\n        // so actually, the first element of the topK moves out of the topK\n        // and not the element that we removed\n        // The first element of the topK is now at index topKStart - 1\n        // since we removed an element before the topK\n        const moveOutIndex = this.#topKStart - 1\n        if (moveOutIndex < this.#sortedValues.length) {\n          result.moveOut = this.#sortedValues[moveOutIndex]!\n        } else {\n          // No value is moving out of the topK\n          // because there are no elements in the topK\n          result.moveOut = null\n        }\n      }\n\n      // Since we removed an element that was before or in the topK\n      // the first element after the topK moved one position to the left\n      // and thus falls into the topK now\n      const moveInIndex = this.#topKEnd - 1\n      if (moveInIndex < this.#sortedValues.length) {\n        result.moveIn = this.#sortedValues[moveInIndex]!\n      }\n    }\n\n    return result\n  }\n\n  // TODO: see if there is a way to refactor the code for insert and delete in the topK above\n  //       because they are very similar, one is shifting the topK window to the left and the other is shifting it to the right\n  //       so i have the feeling there is a common pattern here and we can implement both cases using that pattern\n\n  #findIndex(value: V): number {\n    return binarySearch(this.#sortedValues, indexedValue(value, ``), (a, b) =>\n      this.#comparator(getValue(a), getValue(b)),\n    )\n  }\n}\n"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,35 @@
+import { IndexedValue, TopK, TopKChanges, TopKMoveChanges } from './topKArray.js';
+/**
+ * Helper class that manages the state for a single topK window.
+ * Encapsulates the multiplicity tracking and topK data structure,
+ * providing a clean interface for processing elements and moving the window.
+ *
+ * This class is used by both TopKWithFractionalIndexOperator (single instance)
+ * and GroupedTopKWithFractionalIndexOperator (one instance per group).
+ */
+export declare class TopKState<K extends string | number, T> {
+    #private;
+    constructor(topK: TopK<[K, T]>);
+    get size(): number;
+    get isEmpty(): boolean;
+    /**
+     * Process an element update (insert or delete based on multiplicity change).
+     * Returns the changes to the topK window.
+     */
+    processElement(key: K, value: T, multiplicity: number): TopKChanges<[K, T]>;
+    /**
+     * Move the topK window. Only works with TopKArray implementation.
+     */
+    move(options: {
+        offset?: number;
+        limit?: number;
+    }): TopKMoveChanges<[K, T]>;
+}
+/**
+ * Handles a moveIn change by adding it to the result array.
+ */
+export declare function handleMoveIn<K extends string | number, T>(moveIn: IndexedValue<[K, T]> | null, result: Array<[[K, IndexedValue<T>], number]>): void;
+/**
+ * Handles a moveOut change by adding it to the result array.
+ */
+export declare function handleMoveOut<K extends string | number, T>(moveOut: IndexedValue<[K, T]> | null, result: Array<[[K, IndexedValue<T>], number]>): void;

package/dist/esm/operators/topKState.js

@@ -0,0 +1,73 @@
+import { TopKArray } from "./topKArray.js";
+class TopKState {
+  #multiplicities = /* @__PURE__ */ new Map();
+  #topK;
+  constructor(topK) {
+    this.#topK = topK;
+  }
+  get size() {
+    return this.#topK.size;
+  }
+  get isEmpty() {
+    return this.#multiplicities.size === 0 && this.#topK.size === 0;
+  }
+  /**
+   * Process an element update (insert or delete based on multiplicity change).
+   * Returns the changes to the topK window.
+   */
+  processElement(key, value, multiplicity) {
+    const { oldMultiplicity, newMultiplicity } = this.#updateMultiplicity(
+      key,
+      multiplicity
+    );
+    if (oldMultiplicity <= 0 && newMultiplicity > 0) {
+      return this.#topK.insert([key, value]);
+    } else if (oldMultiplicity > 0 && newMultiplicity <= 0) {
+      return this.#topK.delete([key, value]);
+    }
+    return { moveIn: null, moveOut: null };
+  }
+  /**
+   * Move the topK window. Only works with TopKArray implementation.
+   */
+  move(options) {
+    if (!(this.#topK instanceof TopKArray)) {
+      throw new Error(
+        `Cannot move B+-tree implementation of TopK with fractional index`
+      );
+    }
+    return this.#topK.move(options);
+  }
+  #updateMultiplicity(key, multiplicity) {
+    if (multiplicity === 0) {
+      const current = this.#multiplicities.get(key) ?? 0;
+      return { oldMultiplicity: current, newMultiplicity: current };
+    }
+    const oldMultiplicity = this.#multiplicities.get(key) ?? 0;
+    const newMultiplicity = oldMultiplicity + multiplicity;
+    if (newMultiplicity === 0) {
+      this.#multiplicities.delete(key);
+    } else {
+      this.#multiplicities.set(key, newMultiplicity);
+    }
+    return { oldMultiplicity, newMultiplicity };
+  }
+}
+function handleMoveIn(moveIn, result) {
+  if (moveIn) {
+    const [[key, value], index] = moveIn;
+    result.push([[key, [value, index]], 1]);
+  }
+}
+function handleMoveOut(moveOut, result) {
+  if (moveOut) {
+    const [[key, value], index] = moveOut;
+    result.push([[key, [value, index]], -1]);
+  }
+}
+export {
+  TopKState,
+  handleMoveIn,
+  handleMoveOut
+};
+//# sourceMappingURL=topKState.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"topKState.js","sources":["../../../src/operators/topKState.ts"],"sourcesContent":["import { TopKArray } from './topKArray.js'\nimport type {\n  IndexedValue,\n  TopK,\n  TopKChanges,\n  TopKMoveChanges,\n} from './topKArray.js'\n\n/**\n * Helper class that manages the state for a single topK window.\n * Encapsulates the multiplicity tracking and topK data structure,\n * providing a clean interface for processing elements and moving the window.\n *\n * This class is used by both TopKWithFractionalIndexOperator (single instance)\n * and GroupedTopKWithFractionalIndexOperator (one instance per group).\n */\nexport class TopKState<K extends string | number, T> {\n  #multiplicities: Map<K, number> = new Map()\n  #topK: TopK<[K, T]>\n\n  constructor(topK: TopK<[K, T]>) {\n    this.#topK = topK\n  }\n\n  get size(): number {\n    return this.#topK.size\n  }\n\n  get isEmpty(): boolean {\n    return this.#multiplicities.size === 0 && this.#topK.size === 0\n  }\n\n  /**\n   * Process an element update (insert or delete based on multiplicity change).\n   * Returns the changes to the topK window.\n   */\n  processElement(key: K, value: T, multiplicity: number): TopKChanges<[K, T]> {\n    const { oldMultiplicity, newMultiplicity } = this.#updateMultiplicity(\n      key,\n      multiplicity,\n    )\n\n    if (oldMultiplicity <= 0 && newMultiplicity > 0) {\n      // The value was invisible but should now be visible\n      return this.#topK.insert([key, value])\n    } else if (oldMultiplicity > 0 && newMultiplicity <= 0) {\n      // The value was visible but should now be invisible\n      return this.#topK.delete([key, value])\n    }\n    // The value was invisible and remains invisible,\n    // or was visible and remains visible - no topK change\n    return { moveIn: null, moveOut: null }\n  }\n\n  /**\n   * Move the topK window. Only works with TopKArray implementation.\n   */\n  move(options: { offset?: number; limit?: number }): TopKMoveChanges<[K, T]> {\n    if (!(this.#topK instanceof TopKArray)) {\n      throw new Error(\n        `Cannot move B+-tree implementation of TopK with fractional index`,\n      )\n    }\n    return this.#topK.move(options)\n  }\n\n  #updateMultiplicity(\n    key: K,\n    multiplicity: number,\n  ): { oldMultiplicity: number; newMultiplicity: number } {\n    if (multiplicity === 0) {\n      const current = this.#multiplicities.get(key) ?? 0\n      return { oldMultiplicity: current, newMultiplicity: current }\n    }\n\n    const oldMultiplicity = this.#multiplicities.get(key) ?? 0\n    const newMultiplicity = oldMultiplicity + multiplicity\n    if (newMultiplicity === 0) {\n      this.#multiplicities.delete(key)\n    } else {\n      this.#multiplicities.set(key, newMultiplicity)\n    }\n    return { oldMultiplicity, newMultiplicity }\n  }\n}\n\n/**\n * Handles a moveIn change by adding it to the result array.\n */\nexport function handleMoveIn<K extends string | number, T>(\n  moveIn: IndexedValue<[K, T]> | null,\n  result: Array<[[K, IndexedValue<T>], number]>,\n): void {\n  if (moveIn) {\n    const [[key, value], index] = moveIn\n    result.push([[key, [value, index]], 1])\n  }\n}\n\n/**\n * Handles a moveOut change by adding it to the result array.\n */\nexport function handleMoveOut<K extends string | number, T>(\n  moveOut: IndexedValue<[K, T]> | null,\n  result: Array<[[K, IndexedValue<T>], number]>,\n): void {\n  if (moveOut) {\n    const [[key, value], index] = moveOut\n    result.push([[key, [value, index]], -1])\n  }\n}\n"],"names":[],"mappings":";AAgBO,MAAM,UAAwC;AAAA,EACnD,sCAAsC,IAAA;AAAA,EACtC;AAAA,EAEA,YAAY,MAAoB;AAC9B,SAAK,QAAQ;AAAA,EACf;AAAA,EAEA,IAAI,OAAe;AACjB,WAAO,KAAK,MAAM;AAAA,EACpB;AAAA,EAEA,IAAI,UAAmB;AACrB,WAAO,KAAK,gBAAgB,SAAS,KAAK,KAAK,MAAM,SAAS;AAAA,EAChE;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,eAAe,KAAQ,OAAU,cAA2C;AAC1E,UAAM,EAAE,iBAAiB,gBAAA,IAAoB,KAAK;AAAA,MAChD;AAAA,MACA;AAAA,IAAA;AAGF,QAAI,mBAAmB,KAAK,kBAAkB,GAAG;AAE/C,aAAO,KAAK,MAAM,OAAO,CAAC,KAAK,KAAK,CAAC;AAAA,IACvC,WAAW,kBAAkB,KAAK,mBAAmB,GAAG;AAEtD,aAAO,KAAK,MAAM,OAAO,CAAC,KAAK,KAAK,CAAC;AAAA,IACvC;AAGA,WAAO,EAAE,QAAQ,MAAM,SAAS,KAAA;AAAA,EAClC;AAAA;AAAA;AAAA;AAAA,EAKA,KAAK,SAAuE;AAC1E,QAAI,EAAE,KAAK,iBAAiB,YAAY;AACtC,YAAM,IAAI;AAAA,QACR;AAAA,MAAA;AAAA,IAEJ;AACA,WAAO,KAAK,MAAM,KAAK,OAAO;AAAA,EAChC;AAAA,EAEA,oBACE,KACA,cACsD;AACtD,QAAI,iBAAiB,GAAG;AACtB,YAAM,UAAU,KAAK,gBAAgB,IAAI,GAAG,KAAK;AACjD,aAAO,EAAE,iBAAiB,SAAS,iBAAiB,QAAA;AAAA,IACtD;AAEA,UAAM,kBAAkB,KAAK,gBAAgB,IAAI,GAAG,KAAK;AACzD,UAAM,kBAAkB,kBAAkB;AAC1C,QAAI,oBAAoB,GAAG;AACzB,WAAK,gBAAgB,OAAO,GAAG;AAAA,IACjC,OAAO;AACL,WAAK,gBAAgB,IAAI,KAAK,eAAe;AAAA,IAC/C;AACA,WAAO,EAAE,iBAAiB,gBAAA;AAAA,EAC5B;AACF;AAKO,SAAS,aACd,QACA,QACM;AACN,MAAI,QAAQ;AACV,UAAM,CAAC,CAAC,KAAK,KAAK,GAAG,KAAK,IAAI;AAC9B,WAAO,KAAK,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC;AAAA,EACxC;AACF;AAKO,SAAS,cACd,SACA,QACM;AACN,MAAI,SAAS;AACX,UAAM,CAAC,CAAC,KAAK,KAAK,GAAG,KAAK,IAAI;AAC9B,WAAO,KAAK,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,GAAG,EAAE,CAAC;AAAA,EACzC;AACF;"}

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

@@ -1,4 +1,5 @@
 import { DifferenceStreamWriter, UnaryOperator, DifferenceStreamReader } from '../graph.js';
+import { IndexedValue, TopK } from './topKArray.js';
 import { PipedOperator } from '../types.js';
 export interface TopKWithFractionalIndexOptions {
     limit?: number;
@@ -9,29 +10,6 @@ export interface TopKWithFractionalIndexOptions {
         limit?: number;
     }) => void) => void;
 }
-export type TopKChanges<V> = {
-    /** Indicates which element moves into the topK (if any) */
-    moveIn: IndexedValue<V> | null;
-    /** Indicates which element moves out of the topK (if any) */
-    moveOut: IndexedValue<V> | null;
-};
-export type TopKMoveChanges<V> = {
-    /** Flag that marks whether there were any changes to the topK */
-    changes: boolean;
-    /** Indicates which elements move into the topK (if any) */
-    moveIns: Array<IndexedValue<V>>;
-    /** Indicates which elements move out of the topK (if any) */
-    moveOuts: Array<IndexedValue<V>>;
-};
-/**
- * A topK data structure that supports insertions and deletions
- * and returns changes to the topK.
- */
-export interface TopK<V> {
-    size: number;
-    insert: (value: V) => TopKChanges<V>;
-    delete: (value: V) => TopKChanges<V>;
-}
 /**
  * Operator for fractional indexed topK operations
  * This operator maintains fractional indices for sorted elements
@@ -51,10 +29,6 @@ export declare class TopKWithFractionalIndexOperator<K extends string | number,
     }): void;
     run(): void;
     processElement(key: K, value: T, multiplicity: number, result: Array<[[K, IndexedValue<T>], number]>): void;
-    private handleMoveIn;
-    private handleMoveOut;
-    private getMultiplicity;
-    private addKey;
 }
 /**
  * Limits the number of results based on a comparator, with optional offset.
@@ -67,8 +41,3 @@ export declare class TopKWithFractionalIndexOperator<K extends string | number,
  * @returns A piped operator that orders the elements and limits the number of results
  */
 export declare function topKWithFractionalIndex<KType extends string | number, T>(comparator: (a: T, b: T) => number, options?: TopKWithFractionalIndexOptions): PipedOperator<[KType, T], [KType, IndexedValue<T>]>;
-export type FractionalIndex = string;
-export type IndexedValue<V> = [V, FractionalIndex];
-export declare function indexedValue<V>(value: V, index: FractionalIndex): IndexedValue<V>;
-export declare function getValue<V>(indexedVal: IndexedValue<V>): V;
-export declare function getIndex<V>(indexedVal: IndexedValue<V>): FractionalIndex;

package/dist/esm/operators/topKWithFractionalIndex.js

@@ -1,136 +1,21 @@
-import { generateKeyBetween } from "fractional-indexing";
 import { UnaryOperator, DifferenceStreamWriter } from "../graph.js";
 import { StreamBuilder } from "../d2.js";
 import { MultiSet } from "../multiset.js";
-import { compareKeys, diffHalfOpen, binarySearch } from "../utils.js";
-class TopKArray {
-  #sortedValues = [];
-  #comparator;
-  #topKStart;
-  #topKEnd;
-  constructor(offset, limit, comparator) {
-    this.#topKStart = offset;
-    this.#topKEnd = offset + limit;
-    this.#comparator = comparator;
-  }
-  get size() {
-    const offset = this.#topKStart;
-    const limit = this.#topKEnd - this.#topKStart;
-    const available = this.#sortedValues.length - offset;
-    return Math.max(0, Math.min(limit, available));
-  }
-  /**
-   * Moves the topK window
-   */
-  move({
-    offset,
-    limit
-  }) {
-    const oldOffset = this.#topKStart;
-    const oldLimit = this.#topKEnd - this.#topKStart;
-    const oldRange = [
-      this.#topKStart,
-      this.#topKEnd === Infinity ? this.#topKStart + this.size : this.#topKEnd
-    ];
-    this.#topKStart = offset ?? oldOffset;
-    this.#topKEnd = this.#topKStart + (limit ?? oldLimit);
-    const newRange = [
-      this.#topKStart,
-      this.#topKEnd === Infinity ? Math.max(this.#topKStart + this.size, oldRange[1]) : this.#topKEnd
-    ];
-    const { onlyInA, onlyInB } = diffHalfOpen(oldRange, newRange);
-    const moveIns = [];
-    onlyInB.forEach((index) => {
-      const value = this.#sortedValues[index];
-      if (value) {
-        moveIns.push(value);
-      }
-    });
-    const moveOuts = [];
-    onlyInA.forEach((index) => {
-      const value = this.#sortedValues[index];
-      if (value) {
-        moveOuts.push(value);
-      }
-    });
-    return { moveIns, moveOuts, changes: onlyInA.length + onlyInB.length > 0 };
-  }
-  insert(value) {
-    const result = { moveIn: null, moveOut: null };
-    const index = this.#findIndex(value);
-    const indexBefore = index === 0 ? null : getIndex(this.#sortedValues[index - 1]);
-    const indexAfter = index === this.#sortedValues.length ? null : getIndex(this.#sortedValues[index]);
-    const fractionalIndex = generateKeyBetween(indexBefore, indexAfter);
-    const val = indexedValue(value, fractionalIndex);
-    this.#sortedValues.splice(index, 0, val);
-    if (index < this.#topKEnd) {
-      const moveInIndex = Math.max(index, this.#topKStart);
-      if (moveInIndex < this.#sortedValues.length) {
-        result.moveIn = this.#sortedValues[moveInIndex];
-        if (this.#topKEnd < this.#sortedValues.length) {
-          result.moveOut = this.#sortedValues[this.#topKEnd];
-        }
-      }
-    }
-    return result;
-  }
-  /**
-   * Deletes a value that may or may not be in the topK.
-   * IMPORTANT: this assumes that the value is present in the collection
-   *            if it's not the case it will remove the element
-   *            that is on the position where the provided `value` would be.
-   */
-  delete(value) {
-    const result = { moveIn: null, moveOut: null };
-    const index = this.#findIndex(value);
-    const [removedElem] = this.#sortedValues.splice(index, 1);
-    if (index < this.#topKEnd) {
-      result.moveOut = removedElem;
-      if (index < this.#topKStart) {
-        const moveOutIndex = this.#topKStart - 1;
-        if (moveOutIndex < this.#sortedValues.length) {
-          result.moveOut = this.#sortedValues[moveOutIndex];
-        } else {
-          result.moveOut = null;
-        }
-      }
-      const moveInIndex = this.#topKEnd - 1;
-      if (moveInIndex < this.#sortedValues.length) {
-        result.moveIn = this.#sortedValues[moveInIndex];
-      }
-    }
-    return result;
-  }
-  // TODO: see if there is a way to refactor the code for insert and delete in the topK above
-  //       because they are very similar, one is shifting the topK window to the left and the other is shifting it to the right
-  //       so i have the feeling there is a common pattern here and we can implement both cases using that pattern
-  #findIndex(value) {
-    return binarySearch(
-      this.#sortedValues,
-      indexedValue(value, ``),
-      (a, b) => this.#comparator(getValue(a), getValue(b))
-    );
-  }
-}
+import { TopKState, handleMoveIn, handleMoveOut } from "./topKState.js";
+import { createKeyedComparator, TopKArray } from "./topKArray.js";
 class TopKWithFractionalIndexOperator extends UnaryOperator {
-  #index = /* @__PURE__ */ new Map();
-  // maps keys to their multiplicity
-  /**
-   * topK data structure that supports insertions and deletions
-   * and returns changes to the topK.
-   * Elements are stored as [key, value] tuples for stable tie-breaking.
-   */
-  #topK;
+  #state;
   constructor(id, inputA, output, comparator, options) {
     super(id, inputA, output);
     const limit = options.limit ?? Infinity;
     const offset = options.offset ?? 0;
-    this.#topK = this.createTopK(
+    const topK = this.createTopK(
       offset,
       limit,
       createKeyedComparator(comparator)
     );
-    options.setSizeCallback?.(() => this.#topK.size);
+    this.#state = new TopKState(topK);
+    options.setSizeCallback?.(() => this.#state.size);
     options.setWindowFn?.(this.moveTopK.bind(this));
   }
   createTopK(offset, limit, comparator) {
@@ -141,15 +26,10 @@ class TopKWithFractionalIndexOperator extends UnaryOperator {
    * Any changes to the topK are sent to the output.
    */
   moveTopK({ offset, limit }) {
-    if (!(this.#topK instanceof TopKArray)) {
-      throw new Error(
-        `Cannot move B+-tree implementation of TopK with fractional index`
-      );
-    }
     const result = [];
-    const diff = this.#topK.move({ offset, limit });
-    diff.moveIns.forEach((moveIn) => this.handleMoveIn(moveIn, result));
-    diff.moveOuts.forEach((moveOut) => this.handleMoveOut(moveOut, result));
+    const diff = this.#state.move({ offset, limit });
+    diff.moveIns.forEach((moveIn) => handleMoveIn(moveIn, result));
+    diff.moveOuts.forEach((moveOut) => handleMoveOut(moveOut, result));
     if (diff.changes) {
       this.output.sendData(new MultiSet(result));
     }
@@ -167,44 +47,9 @@ class TopKWithFractionalIndexOperator extends UnaryOperator {
     }
   }
   processElement(key, value, multiplicity, result) {
-    const { oldMultiplicity, newMultiplicity } = this.addKey(key, multiplicity);
-    let res = {
-      moveIn: null,
-      moveOut: null
-    };
-    if (oldMultiplicity <= 0 && newMultiplicity > 0) {
-      res = this.#topK.insert([key, value]);
-    } else if (oldMultiplicity > 0 && newMultiplicity <= 0) {
-      res = this.#topK.delete([key, value]);
-    } else ;
-    this.handleMoveIn(res.moveIn, result);
-    this.handleMoveOut(res.moveOut, result);
-    return;
-  }
-  handleMoveIn(moveIn, result) {
-    if (moveIn) {
-      const [[key, value], index] = moveIn;
-      result.push([[key, [value, index]], 1]);
-    }
-  }
-  handleMoveOut(moveOut, result) {
-    if (moveOut) {
-      const [[key, value], index] = moveOut;
-      result.push([[key, [value, index]], -1]);
-    }
-  }
-  getMultiplicity(key) {
-    return this.#index.get(key) ?? 0;
-  }
-  addKey(key, multiplicity) {
-    const oldMultiplicity = this.getMultiplicity(key);
-    const newMultiplicity = oldMultiplicity + multiplicity;
-    if (newMultiplicity === 0) {
-      this.#index.delete(key);
-    } else {
-      this.#index.set(key, newMultiplicity);
-    }
-    return { oldMultiplicity, newMultiplicity };
+    const changes = this.#state.processElement(key, value, multiplicity);
+    handleMoveIn(changes.moveIn, result);
+    handleMoveOut(changes.moveOut, result);
   }
 }
 function topKWithFractionalIndex(comparator, options) {
@@ -225,29 +70,8 @@ function topKWithFractionalIndex(comparator, options) {
     return output;
   };
 }
-function indexedValue(value, index) {
-  return [value, index];
-}
-function getValue(indexedVal) {
-  return indexedVal[0];
-}
-function getIndex(indexedVal) {
-  return indexedVal[1];
-}
-function createKeyedComparator(comparator) {
-  return ([aKey, aVal], [bKey, bVal]) => {
-    const valueComparison = comparator(aVal, bVal);
-    if (valueComparison !== 0) {
-      return valueComparison;
-    }
-    return compareKeys(aKey, bKey);
-  };
-}
 export {
   TopKWithFractionalIndexOperator,
-  getIndex,
-  getValue,
-  indexedValue,
   topKWithFractionalIndex
 };
 //# sourceMappingURL=topKWithFractionalIndex.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"topKWithFractionalIndex.js","sources":["../../../src/operators/topKWithFractionalIndex.ts"],"sourcesContent":["import { generateKeyBetween } from 'fractional-indexing'\nimport { DifferenceStreamWriter, UnaryOperator } from '../graph.js'\nimport { StreamBuilder } from '../d2.js'\nimport { MultiSet } from '../multiset.js'\nimport { binarySearch, compareKeys, diffHalfOpen } from '../utils.js'\nimport type { HRange } from '../utils.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\nexport type TopKChanges<V> = {\n  /** Indicates which element moves into the topK (if any) */\n  moveIn: IndexedValue<V> | null\n  /** Indicates which element moves out of the topK (if any) */\n  moveOut: IndexedValue<V> | null\n}\n\nexport type TopKMoveChanges<V> = {\n  /** Flag that marks whether there were any changes to the topK */\n  changes: boolean\n  /** Indicates which elements move into the topK (if any) */\n  moveIns: Array<IndexedValue<V>>\n  /** Indicates which elements move out of the topK (if any) */\n  moveOuts: Array<IndexedValue<V>>\n}\n\n/**\n * A topK data structure that supports insertions and deletions\n * and returns changes to the topK.\n */\nexport interface TopK<V> {\n  size: number\n  insert: (value: V) => TopKChanges<V>\n  delete: (value: V) => TopKChanges<V>\n}\n\n/**\n * Implementation of a topK data structure.\n * Uses a sorted array internally to store the values and keeps a topK window over that array.\n * Inserts and deletes are O(n) operations because worst case an element is inserted/deleted\n * at the start of the array which causes all the elements to shift to the right/left.\n */\nclass TopKArray<V> implements TopK<V> {\n  #sortedValues: Array<IndexedValue<V>> = []\n  #comparator: (a: V, b: V) => number\n  #topKStart: number\n  #topKEnd: number\n\n  constructor(\n    offset: number,\n    limit: number,\n    comparator: (a: V, b: V) => number,\n  ) {\n    this.#topKStart = offset\n    this.#topKEnd = offset + limit\n    this.#comparator = comparator\n  }\n\n  get size(): number {\n    const offset = this.#topKStart\n    const limit = this.#topKEnd - this.#topKStart\n    const available = this.#sortedValues.length - offset\n    return Math.max(0, Math.min(limit, available))\n  }\n\n  /**\n   * Moves the topK window\n   */\n  move({\n    offset,\n    limit,\n  }: {\n    offset?: number\n    limit?: number\n  }): TopKMoveChanges<V> {\n    const oldOffset = this.#topKStart\n    const oldLimit = this.#topKEnd - this.#topKStart\n\n    // `this.#topKEnd` can be `Infinity` if it has no limit\n    // but `diffHalfOpen` expects a finite range\n    // so we restrict it to the size of the topK if topKEnd is infinite\n    const oldRange: HRange = [\n      this.#topKStart,\n      this.#topKEnd === Infinity ? this.#topKStart + this.size : this.#topKEnd,\n    ]\n\n    this.#topKStart = offset ?? oldOffset\n    this.#topKEnd = this.#topKStart + (limit ?? oldLimit) // can be `Infinity` if limit is `Infinity`\n\n    // Also handle `Infinity` in the newRange\n    const newRange: HRange = [\n      this.#topKStart,\n      this.#topKEnd === Infinity\n        ? Math.max(this.#topKStart + this.size, oldRange[1]) // since the new limit is Infinity we need to take everything (so we need to take the biggest (finite) topKEnd)\n        : this.#topKEnd,\n    ]\n    const { onlyInA, onlyInB } = diffHalfOpen(oldRange, newRange)\n\n    const moveIns: Array<IndexedValue<V>> = []\n    onlyInB.forEach((index) => {\n      const value = this.#sortedValues[index]\n      if (value) {\n        moveIns.push(value)\n      }\n    })\n\n    const moveOuts: Array<IndexedValue<V>> = []\n    onlyInA.forEach((index) => {\n      const value = this.#sortedValues[index]\n      if (value) {\n        moveOuts.push(value)\n      }\n    })\n\n    // It could be that there are changes (i.e. moveIns or moveOuts)\n    // but that the collection is lazy so we don't have the data yet that needs to move in/out\n    // so `moveIns` and `moveOuts` will be empty but `changes` will be true\n    // this will tell the caller that it needs to run the graph to load more data\n    return { moveIns, moveOuts, changes: onlyInA.length + onlyInB.length > 0 }\n  }\n\n  insert(value: V): TopKChanges<V> {\n    const result: TopKChanges<V> = { moveIn: null, moveOut: null }\n\n    // Lookup insert position\n    const index = this.#findIndex(value)\n    // Generate fractional index based on the fractional indices of the elements before and after it\n    const indexBefore =\n      index === 0 ? null : getIndex(this.#sortedValues[index - 1]!)\n    const indexAfter =\n      index === this.#sortedValues.length\n        ? null\n        : getIndex(this.#sortedValues[index]!)\n    const fractionalIndex = generateKeyBetween(indexBefore, indexAfter)\n\n    // Insert the value at the correct position\n    const val = indexedValue(value, fractionalIndex)\n    // Splice is O(n) where n = all elements in the collection (i.e. n >= k) !\n    this.#sortedValues.splice(index, 0, val)\n\n    // Check if the topK changed\n    if (index < this.#topKEnd) {\n      // The inserted element is either before the top K or within the top K\n      // If it is before the top K then it moves the element that was right before the topK into the topK\n      // If it is within the top K then the inserted element moves into the top K\n      // In both cases the last element of the old top K now moves out of the top K\n      const moveInIndex = Math.max(index, this.#topKStart)\n      if (moveInIndex < this.#sortedValues.length) {\n        // We actually have a topK\n        // because in some cases there may not be enough elements in the array to reach the start of the topK\n        // e.g. [1, 2, 3] with K = 2 and offset = 3 does not have a topK\n        result.moveIn = this.#sortedValues[moveInIndex]!\n\n        // We need to remove the element that falls out of the top K\n        // The element that falls out of the top K has shifted one to the right\n        // because of the element we inserted, so we find it at index topKEnd\n        if (this.#topKEnd < this.#sortedValues.length) {\n          result.moveOut = this.#sortedValues[this.#topKEnd]!\n        }\n      }\n    }\n\n    return result\n  }\n\n  /**\n   * Deletes a value that may or may not be in the topK.\n   * IMPORTANT: this assumes that the value is present in the collection\n   *            if it's not the case it will remove the element\n   *            that is on the position where the provided `value` would be.\n   */\n  delete(value: V): TopKChanges<V> {\n    const result: TopKChanges<V> = { moveIn: null, moveOut: null }\n\n    // Lookup delete position\n    const index = this.#findIndex(value)\n    // Remove the value at that position\n    const [removedElem] = this.#sortedValues.splice(index, 1)\n\n    // Check if the topK changed\n    if (index < this.#topKEnd) {\n      // The removed element is either before the top K or within the top K\n      // If it is before the top K then the first element of the topK moves out of the topK\n      // If it is within the top K then the removed element moves out of the topK\n      result.moveOut = removedElem!\n      if (index < this.#topKStart) {\n        // The removed element is before the topK\n        // so actually, the first element of the topK moves out of the topK\n        // and not the element that we removed\n        // The first element of the topK is now at index topKStart - 1\n        // since we removed an element before the topK\n        const moveOutIndex = this.#topKStart - 1\n        if (moveOutIndex < this.#sortedValues.length) {\n          result.moveOut = this.#sortedValues[moveOutIndex]!\n        } else {\n          // No value is moving out of the topK\n          // because there are no elements in the topK\n          result.moveOut = null\n        }\n      }\n\n      // Since we removed an element that was before or in the topK\n      // the first element after the topK moved one position to the left\n      // and thus falls into the topK now\n      const moveInIndex = this.#topKEnd - 1\n      if (moveInIndex < this.#sortedValues.length) {\n        result.moveIn = this.#sortedValues[moveInIndex]!\n      }\n    }\n\n    return result\n  }\n\n  // TODO: see if there is a way to refactor the code for insert and delete in the topK above\n  //       because they are very similar, one is shifting the topK window to the left and the other is shifting it to the right\n  //       so i have the feeling there is a common pattern here and we can implement both cases using that pattern\n\n  #findIndex(value: V): number {\n    return binarySearch(this.#sortedValues, indexedValue(value, ``), (a, b) =>\n      this.#comparator(getValue(a), getValue(b)),\n    )\n  }\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  #index: Map<K, number> = new Map() // maps keys to their multiplicity\n\n  /**\n   * topK data structure that supports insertions and deletions\n   * and returns changes to the topK.\n   * Elements are stored as [key, value] tuples for stable tie-breaking.\n   */\n  #topK: TopK<[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    this.#topK = this.createTopK(\n      offset,\n      limit,\n      createKeyedComparator(comparator),\n    )\n    options.setSizeCallback?.(() => this.#topK.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    if (!(this.#topK instanceof TopKArray)) {\n      throw new Error(\n        `Cannot move B+-tree implementation of TopK with fractional index`,\n      )\n    }\n\n    const result: Array<[[K, IndexedValue<T>], number]> = []\n\n    const diff = this.#topK.move({ offset, limit })\n\n    diff.moveIns.forEach((moveIn) => this.handleMoveIn(moveIn, result))\n    diff.moveOuts.forEach((moveOut) => this.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 { oldMultiplicity, newMultiplicity } = this.addKey(key, multiplicity)\n\n    let res: TopKChanges<[K, T]> = {\n      moveIn: null,\n      moveOut: null,\n    }\n    if (oldMultiplicity <= 0 && newMultiplicity > 0) {\n      // The value was invisible but should now be visible\n      // Need to insert it into the array of sorted values\n      res = this.#topK.insert([key, value])\n    } else if (oldMultiplicity > 0 && newMultiplicity <= 0) {\n      // The value was visible but should now be invisible\n      // Need to remove it from the array of sorted values\n      res = this.#topK.delete([key, value])\n    } else {\n      // The value was invisible and it remains invisible\n      // or it was visible and remains visible\n      // so it doesn't affect the topK\n    }\n\n    this.handleMoveIn(res.moveIn, result)\n    this.handleMoveOut(res.moveOut, result)\n\n    return\n  }\n\n  private handleMoveIn(\n    moveIn: IndexedValue<[K, T]> | null,\n    result: Array<[[K, IndexedValue<T>], number]>,\n  ) {\n    if (moveIn) {\n      const [[key, value], index] = moveIn\n      result.push([[key, [value, index]], 1])\n    }\n  }\n\n  private handleMoveOut(\n    moveOut: IndexedValue<[K, T]> | null,\n    result: Array<[[K, IndexedValue<T>], number]>,\n  ) {\n    if (moveOut) {\n      const [[key, value], index] = moveOut\n      result.push([[key, [value, index]], -1])\n    }\n  }\n\n  private getMultiplicity(key: K): number {\n    return this.#index.get(key) ?? 0\n  }\n\n  private addKey(\n    key: K,\n    multiplicity: number,\n  ): { oldMultiplicity: number; newMultiplicity: number } {\n    const oldMultiplicity = this.getMultiplicity(key)\n    const newMultiplicity = oldMultiplicity + multiplicity\n    if (newMultiplicity === 0) {\n      this.#index.delete(key)\n    } else {\n      this.#index.set(key, newMultiplicity)\n    }\n    return { oldMultiplicity, newMultiplicity }\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\n// Abstraction for fractionally indexed values\nexport type FractionalIndex = string\nexport type IndexedValue<V> = [V, FractionalIndex]\n\nexport function indexedValue<V>(\n  value: V,\n  index: FractionalIndex,\n): IndexedValue<V> {\n  return [value, index]\n}\n\nexport function getValue<V>(indexedVal: IndexedValue<V>): V {\n  return indexedVal[0]\n}\n\nexport function getIndex<V>(indexedVal: IndexedValue<V>): FractionalIndex {\n  return indexedVal[1]\n}\n\n/**\n * Creates a comparator for [key, value] tuples that first compares values,\n * then uses the row key as a stable tie-breaker.\n */\nfunction createKeyedComparator<K extends string | number, T>(\n  comparator: (a: T, b: T) => number,\n): (a: [K, T], b: [K, T]) => number {\n  return ([aKey, aVal], [bKey, bVal]) => {\n    // First compare on the value\n    const valueComparison = comparator(aVal, bVal)\n    if (valueComparison !== 0) {\n      return valueComparison\n    }\n    // If the values are equal, use the row key as tie-breaker\n    // This provides stable, deterministic ordering since keys are string | number\n    return compareKeys(aKey, bKey)\n  }\n}\n"],"names":[],"mappings":"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"}
+{"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;"}

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

@@ -1,4 +1,5 @@
-import { TopKWithFractionalIndexOperator, IndexedValue, TopK, TopKWithFractionalIndexOptions } from './topKWithFractionalIndex.js';
+import { TopKWithFractionalIndexOperator, TopKWithFractionalIndexOptions } from './topKWithFractionalIndex.js';
+import { IndexedValue, TopK } from './topKArray.js';
 import { PipedOperator } from '../types.js';
 export declare function loadBTree(): Promise<void>;
 /**