fix(workers): reject useTokenSearch in FuseWorker

Token search depends on corpus-level statistics (df, fieldCount). Each
shard would build those stats from its own slice of the dataset, so
ranking would diverge from single-thread Fuse — quietly, with no
visible error.

Reject useTokenSearch at construction time with a clear, dedicated
error and document the limitation alongside the other unsupported
options. Sharing global token stats across shards is a bigger change
that belongs with the inverted-index work tracked in Plan 008.

Plan 007 (post-review HIGH).

Author: krisk

docs/web-workers.md

@@ -175,6 +175,7 @@ The unsupported options are:
 - **`sortFn`** — `FuseWorker` always sorts results by Fuse's default `(score, refIndex)` tie-break. If you need a custom sort, run `Fuse` on the main thread or sort the returned array yourself.
 - **`getFn`** (top-level) — Fall back to dotted key paths (`'a.b.c'`) or array paths (`['a', 'b', 'c']`).
 - **`keys[].getFn`** — Same as above. Use a string or array path on the key.
+- **`useTokenSearch`** — Token search depends on corpus-level statistics (`df`, `fieldCount`) that would be computed independently inside each worker shard, producing scores that don't match single-thread `Fuse`. Use `Fuse` directly on the main thread for token search.
 
 Default ordering is preserved: `FuseWorker` returns the same order as `Fuse` for the same inputs (with or without `includeScore`), and `shouldSort: false` returns results in global collection order.
 

src/core/errorMessages.ts

@@ -22,6 +22,12 @@ export const FUSE_WORKER_UNSUPPORTED_FN_OPTION = (option: string): string =>
   `functions cannot be transferred to Web Workers via postMessage. ` +
   `Remove this option or fall back to Fuse.`
 
+export const FUSE_WORKER_TOKEN_SEARCH_UNSUPPORTED =
+  `FuseWorker does not support useTokenSearch: token search depends on ` +
+  `corpus-level statistics (df, fieldCount) that are computed per shard, ` +
+  `so per-shard scores would diverge from single-thread Fuse. Use Fuse on ` +
+  `the main thread for token search.`
+
 export const FUSE_MATCH_TOKEN_SEARCH_UNSUPPORTED =
   `Fuse.match does not support useTokenSearch: token search requires ` +
   `corpus-level statistics (df, fieldCount) that a one-off string ` +

src/workers/FuseWorker.ts

@@ -57,6 +57,12 @@ export default class FuseWorker<T> {
     // Reject function-valued options eagerly. Without this check, postMessage
     // throws DataCloneError on first search() rather than at construction.
     FuseWorker._assertNoFunctionOptions(this._options)
+    // Token search needs global corpus statistics, but each shard would build
+    // its own — scores would diverge from single-thread Fuse. Refuse upfront
+    // rather than silently returning ordering that doesn't match.
+    if (this._options.useTokenSearch) {
+      throw new Error(ErrorMsg.FUSE_WORKER_TOKEN_SEARCH_UNSUPPORTED)
+    }
     // eslint-disable-next-line @typescript-eslint/ban-ts-comment
     // @ts-ignore -- import.meta.url is resolved by Rollup at build time
     this._workerUrl = this._workerOptions.workerUrl

test/fuse-worker.test.js

@@ -425,4 +425,12 @@ describe('FuseWorker rejects function-valued options', () => {
       })
     ).not.toThrow()
   })
+
+  test('throws when useTokenSearch is true', () => {
+    // Token search needs global corpus stats; per-shard stats would diverge
+    // from single-thread Fuse, so FuseWorker rejects it upfront.
+    expect(
+      () => new FuseWorker(Books, { keys: ['title'], useTokenSearch: true })
+    ).toThrowError(/useTokenSearch/)
+  })
 })