fix(index): correct doc-index alignment for Fuse<string> with blank docs

Fuse<string> collections containing blank strings produced records
whose .i values drifted from _docs indices through add, removeAt, and
remove/removeAll. Search results were silently misaligned with the
source array — e.g. removeAt(1) on ["", "apple", "banana"] could
return "banana" as a match for "apple".

Root cause: FuseIndex.add / removeAt / removeAll conflated
records-array offset with source-array doc-index. Blank docs produce
no record (per _createStringRecord), so records.length < _docs.length
and the two index spaces diverge.

- FuseIndex.add(doc, docIndex): IndexRecord | null — explicit doc-index
  parameter; returns the appended record or null when doc is blank.
- FuseIndex.removeAt(idx) — operates on doc-index, order-independent.
- FuseIndex.removeAll(indices) — filter by doc-index, shift surviving
  .i by count of removed indices strictly less than it.
- Fuse.add now only feeds the inverted index when a record was
  appended; previously could re-ingest the prior doc on add("") under
  useTokenSearch, or crash on an all-blank collection.
- Fuse.removeAt(idx) validates idx (integer, in-range) atomically
  before any mutation.
- FuseIndex.add / removeAt / removeAll gain cheap input guards for
  direct callers.

API note: FuseIndex.add gained a required docIndex parameter. The
public Fuse.add(doc) signature is unchanged; only direct callers of
FuseIndex.add are affected and will throw INVALID_DOC_INDEX if called
without it. The alternative — optional docIndex with this.docs.length
fallback — silently produces wrong indices when the FuseIndex is
shared with a Fuse instance that ran .remove (the docs reference
detaches), which is exactly the bug class this fix eliminates.

Migration: if you serialized a Fuse<string> index via
getIndex().toJSON() from a pre-fix instance whose collection contained
blanks and ran any add/remove/removeAt/removeAll before serialization,
those records may misrepresent the source array — rebuild via
new Fuse(docs, options). Indexes from clean string collections are
unaffected.

Surfaced during fuse-swift port planning; fuse-swift v1 inherits the
doc-index-canonical model from this fix.

Author: krisk

bench/search.mjs

@@ -117,3 +117,47 @@ console.log('\n=== remove() — 10k docs, remove 1k ===')
     })
   }, 2, 5)
 }
+
+// --- String mutation paths (Plan 013) ---
+// These exercise blank-heavy string collections through the fixed mutation
+// paths — add() per the new docIndex-parameter signature, removeAt with the
+// order-independent algorithm, and removeAll with the binary-search shift
+// (vs the pre-fix O(N) sequential-rewrite). Roughly 1/3 of docs are blank to
+// stress the records-shorter-than-docs case.
+console.log('\n=== String mutations (blank-heavy) — 10k docs ===')
+{
+  const buildDocs = (n) => {
+    const out = new Array(n)
+    for (let i = 0; i < n; i++) {
+      out[i] = i % 3 === 0 ? '' : randomWords(1, 4)
+    }
+    return out
+  }
+
+  bench('build Fuse from 10k (1/3 blank)', () => {
+    new Fuse(buildDocs(10_000))
+  }, 2, 5)
+
+  bench('add 100 strings to 10k (1/3 blank)', () => {
+    const fuse = new Fuse(buildDocs(10_000))
+    for (let i = 0; i < 100; i++) {
+      fuse.add(i % 4 === 0 ? '' : 'extra ' + i)
+    }
+  }, 2, 5)
+
+  bench('removeAt(0) ×100 on 10k (1/3 blank)', () => {
+    const fuse = new Fuse(buildDocs(10_000))
+    for (let i = 0; i < 100; i++) {
+      fuse.removeAt(0)
+    }
+  }, 2, 5)
+
+  bench('remove 1k from 10k (1/3 blank)', () => {
+    const fuse = new Fuse(buildDocs(10_000))
+    let removed = 0
+    fuse.remove(() => {
+      if (removed < 1000) { removed++; return true }
+      return false
+    })
+  }, 2, 5)
+}

dist/fuse.basic.cjs

@@ -62,6 +62,7 @@ const EXTENDED_SEARCH_UNAVAILABLE = 'Extended search is not available';
 const LOGICAL_SEARCH_UNAVAILABLE = 'Logical search is not available';
 const TOKEN_SEARCH_UNAVAILABLE = 'Token search is not available';
 const INCORRECT_INDEX_TYPE = "Incorrect 'index' type";
+const INVALID_DOC_INDEX = 'Invalid doc index: must be a non-negative integer within the bounds of the docs array';
 const LOGICAL_SEARCH_INVALID_QUERY_FOR_KEY = key => `Invalid value for key ${key}`;
 const PATTERN_LENGTH_TOO_LARGE = max => `Pattern length exceeds max of ${max}.`;
 const MISSING_KEY_PROPERTY = name => `Missing ${name} property in key`;
@@ -303,30 +304,80 @@ class FuseIndex {
     this.records.length = recordCount;
     this.norm.clear();
   }
-  // Adds a doc to the end of the index
-  add(doc) {
-    const idx = this.size();
+  // Appends a record for `doc` at `docIndex` (the doc's position in the source
+  // array). Returns the appended record, or null when `doc` is a blank string
+  // (those are skipped at record creation; see `_createStringRecord`). Callers
+  // use the return value to gate downstream bookkeeping like the inverted
+  // index, which must not be touched when no record was produced.
+  add(doc, docIndex) {
+    if (!Number.isInteger(docIndex) || docIndex < 0) {
+      throw new Error(INVALID_DOC_INDEX);
+    }
     if (isString(doc)) {
-      this._addString(doc, idx);
-    } else {
-      this._addObject(doc, idx);
+      const record = this._createStringRecord(doc, docIndex);
+      if (record) {
+        this.records.push(record);
+      }
+      return record;
     }
+    const record = this._createObjectRecord(doc, docIndex);
+    this.records.push(record);
+    return record;
   }
-  // Removes the doc at the specified index of the index
+  // Removes the record for the doc at the specified source-array (docs) index.
+  // Blank string docs have no record; callers may pass such an index and the
+  // splice is a no-op, but subsequent records still need their .i decremented
+  // to track the docs array that the caller is splicing in parallel.
   removeAt(idx) {
-    this.records.splice(idx, 1);
+    if (!Number.isInteger(idx) || idx < 0) {
+      throw new Error(INVALID_DOC_INDEX);
+    }
 
-    // Change ref index of every subsquent doc
-    for (let i = idx, len = this.size(); i < len; i += 1) {
-      this.records[i].i -= 1;
+    // Find and remove the record at this doc-index, if one exists. Records are
+    // typically sorted by .i but the algorithm doesn't depend on it — parsed
+    // indexes via setIndexRecords may arrive in arbitrary order.
+    for (let i = 0, len = this.records.length; i < len; i += 1) {
+      if (this.records[i].i === idx) {
+        this.records.splice(i, 1);
+        break;
+      }
+    }
+
+    // Decrement every record whose source-array index is now stale.
+    for (let i = 0, len = this.records.length; i < len; i += 1) {
+      if (this.records[i].i > idx) {
+        this.records[i].i -= 1;
+      }
     }
   }
-  // Removes docs at the specified indices
+  // Removes records for the docs at the specified source-array indices, then
+  // shifts every surviving record's .i down by the count of removed indices
+  // strictly less than it (mirrors removeAndShiftInvertedIndex's shift math).
+  // Invalid entries (non-integer, negative) in `indices` are dropped silently
+  // — removeAll's natural use case is "caller passed a list of matched doc
+  // indices"; asymmetric throw-vs-no-op would be more surprising than a clean
+  // filter.
   removeAll(indices) {
-    const toRemove = new Set(indices);
-    this.records = this.records.filter((_, i) => !toRemove.has(i));
-    for (let i = 0, len = this.records.length; i < len; i += 1) {
-      this.records[i].i = i;
+    const toRemove = new Set();
+    for (const v of indices) {
+      if (Number.isInteger(v) && v >= 0) {
+        toRemove.add(v);
+      }
+    }
+    if (toRemove.size === 0) {
+      return;
+    }
+    this.records = this.records.filter(r => !toRemove.has(r.i));
+    const sorted = Array.from(toRemove).sort((a, b) => a - b);
+    for (const record of this.records) {
+      // shift = count of removed indices strictly less than record.i
+      let lo = 0;
+      let hi = sorted.length;
+      while (lo < hi) {
+        const mid = lo + hi >>> 1;
+        if (sorted[mid] < record.i) lo = mid + 1;else hi = mid;
+      }
+      record.i -= lo;
     }
   }
   getValueForItemAtKeyId(item, keyId) {
@@ -335,15 +386,6 @@ class FuseIndex {
   size() {
     return this.records.length;
   }
-  _addString(doc, docIndex) {
-    const record = this._createStringRecord(doc, docIndex);
-    if (record) {
-      this.records.push(record);
-    }
-  }
-  _addObject(doc, docIndex) {
-    this.records.push(this._createObjectRecord(doc, docIndex));
-  }
   _createStringRecord(doc, docIndex) {
     if (!isDefined(doc) || isBlank(doc)) {
       return null;
@@ -1256,9 +1298,12 @@ class Fuse {
       return;
     }
     this._docs.push(doc);
-    this._myIndex.add(doc);
-    if (this._invertedIndex) {
-      const record = this._myIndex.records[this._myIndex.records.length - 1];
+    const record = this._myIndex.add(doc, this._docs.length - 1);
+
+    // Skip inverted-index bookkeeping when no record was appended (blank
+    // strings produce null). The previous code read `records[records.length-1]`
+    // unconditionally, which would re-ingest the previous doc on `add("")`.
+    if (this._invertedIndex && record) {
       const analyzer = createAnalyzer({
         isCaseSensitive: this.options.isCaseSensitive,
         ignoreDiacritics: this.options.ignoreDiacritics,
@@ -1291,6 +1336,12 @@ class Fuse {
     return results;
   }
   removeAt(idx) {
+    // Validate before any mutation. The previous code spliced `_docs` first
+    // and let FuseIndex.removeAt throw afterward — partial-state on invalid
+    // input. Atomic now.
+    if (!Number.isInteger(idx) || idx < 0 || idx >= this._docs.length) {
+      throw new Error(INVALID_DOC_INDEX);
+    }
     if (this._invertedIndex) {
       removeAndShiftInvertedIndex(this._invertedIndex, [idx]);
     }

dist/fuse.basic.min.cjs

@@ -60,6 +60,7 @@ const EXTENDED_SEARCH_UNAVAILABLE = 'Extended search is not available';
 const LOGICAL_SEARCH_UNAVAILABLE = 'Logical search is not available';
 const TOKEN_SEARCH_UNAVAILABLE = 'Token search is not available';
 const INCORRECT_INDEX_TYPE = "Incorrect 'index' type";
+const INVALID_DOC_INDEX = 'Invalid doc index: must be a non-negative integer within the bounds of the docs array';
 const LOGICAL_SEARCH_INVALID_QUERY_FOR_KEY = key => `Invalid value for key ${key}`;
 const PATTERN_LENGTH_TOO_LARGE = max => `Pattern length exceeds max of ${max}.`;
 const MISSING_KEY_PROPERTY = name => `Missing ${name} property in key`;
@@ -301,30 +302,80 @@ class FuseIndex {
     this.records.length = recordCount;
     this.norm.clear();
   }
-  // Adds a doc to the end of the index
-  add(doc) {
-    const idx = this.size();
+  // Appends a record for `doc` at `docIndex` (the doc's position in the source
+  // array). Returns the appended record, or null when `doc` is a blank string
+  // (those are skipped at record creation; see `_createStringRecord`). Callers
+  // use the return value to gate downstream bookkeeping like the inverted
+  // index, which must not be touched when no record was produced.
+  add(doc, docIndex) {
+    if (!Number.isInteger(docIndex) || docIndex < 0) {
+      throw new Error(INVALID_DOC_INDEX);
+    }
     if (isString(doc)) {
-      this._addString(doc, idx);
-    } else {
-      this._addObject(doc, idx);
+      const record = this._createStringRecord(doc, docIndex);
+      if (record) {
+        this.records.push(record);
+      }
+      return record;
     }
+    const record = this._createObjectRecord(doc, docIndex);
+    this.records.push(record);
+    return record;
   }
-  // Removes the doc at the specified index of the index
+  // Removes the record for the doc at the specified source-array (docs) index.
+  // Blank string docs have no record; callers may pass such an index and the
+  // splice is a no-op, but subsequent records still need their .i decremented
+  // to track the docs array that the caller is splicing in parallel.
   removeAt(idx) {
-    this.records.splice(idx, 1);
+    if (!Number.isInteger(idx) || idx < 0) {
+      throw new Error(INVALID_DOC_INDEX);
+    }
 
-    // Change ref index of every subsquent doc
-    for (let i = idx, len = this.size(); i < len; i += 1) {
-      this.records[i].i -= 1;
+    // Find and remove the record at this doc-index, if one exists. Records are
+    // typically sorted by .i but the algorithm doesn't depend on it — parsed
+    // indexes via setIndexRecords may arrive in arbitrary order.
+    for (let i = 0, len = this.records.length; i < len; i += 1) {
+      if (this.records[i].i === idx) {
+        this.records.splice(i, 1);
+        break;
+      }
+    }
+
+    // Decrement every record whose source-array index is now stale.
+    for (let i = 0, len = this.records.length; i < len; i += 1) {
+      if (this.records[i].i > idx) {
+        this.records[i].i -= 1;
+      }
     }
   }
-  // Removes docs at the specified indices
+  // Removes records for the docs at the specified source-array indices, then
+  // shifts every surviving record's .i down by the count of removed indices
+  // strictly less than it (mirrors removeAndShiftInvertedIndex's shift math).
+  // Invalid entries (non-integer, negative) in `indices` are dropped silently
+  // — removeAll's natural use case is "caller passed a list of matched doc
+  // indices"; asymmetric throw-vs-no-op would be more surprising than a clean
+  // filter.
   removeAll(indices) {
-    const toRemove = new Set(indices);
-    this.records = this.records.filter((_, i) => !toRemove.has(i));
-    for (let i = 0, len = this.records.length; i < len; i += 1) {
-      this.records[i].i = i;
+    const toRemove = new Set();
+    for (const v of indices) {
+      if (Number.isInteger(v) && v >= 0) {
+        toRemove.add(v);
+      }
+    }
+    if (toRemove.size === 0) {
+      return;
+    }
+    this.records = this.records.filter(r => !toRemove.has(r.i));
+    const sorted = Array.from(toRemove).sort((a, b) => a - b);
+    for (const record of this.records) {
+      // shift = count of removed indices strictly less than record.i
+      let lo = 0;
+      let hi = sorted.length;
+      while (lo < hi) {
+        const mid = lo + hi >>> 1;
+        if (sorted[mid] < record.i) lo = mid + 1;else hi = mid;
+      }
+      record.i -= lo;
     }
   }
   getValueForItemAtKeyId(item, keyId) {
@@ -333,15 +384,6 @@ class FuseIndex {
   size() {
     return this.records.length;
   }
-  _addString(doc, docIndex) {
-    const record = this._createStringRecord(doc, docIndex);
-    if (record) {
-      this.records.push(record);
-    }
-  }
-  _addObject(doc, docIndex) {
-    this.records.push(this._createObjectRecord(doc, docIndex));
-  }
   _createStringRecord(doc, docIndex) {
     if (!isDefined(doc) || isBlank(doc)) {
       return null;
@@ -1254,9 +1296,12 @@ class Fuse {
       return;
     }
     this._docs.push(doc);
-    this._myIndex.add(doc);
-    if (this._invertedIndex) {
-      const record = this._myIndex.records[this._myIndex.records.length - 1];
+    const record = this._myIndex.add(doc, this._docs.length - 1);
+
+    // Skip inverted-index bookkeeping when no record was appended (blank
+    // strings produce null). The previous code read `records[records.length-1]`
+    // unconditionally, which would re-ingest the previous doc on `add("")`.
+    if (this._invertedIndex && record) {
       const analyzer = createAnalyzer({
         isCaseSensitive: this.options.isCaseSensitive,
         ignoreDiacritics: this.options.ignoreDiacritics,
@@ -1289,6 +1334,12 @@ class Fuse {
     return results;
   }
   removeAt(idx) {
+    // Validate before any mutation. The previous code spliced `_docs` first
+    // and let FuseIndex.removeAt throw afterward — partial-state on invalid
+    // input. Atomic now.
+    if (!Number.isInteger(idx) || idx < 0 || idx >= this._docs.length) {
+      throw new Error(INVALID_DOC_INDEX);
+    }
     if (this._invertedIndex) {
       removeAndShiftInvertedIndex(this._invertedIndex, [idx]);
     }