fix(workers): match Fuse ordering and reject non-cloneable options

FuseWorker previously merged shard results and sorted by `score ?? 0`,
which broke parity with Fuse in three ways:

1. With `includeScore: false`, score was never returned from the shards,
   so the merge step had nothing to sort on and the order was effectively
   shard-concat order.
2. Equal-score results across shards collapsed in shard-concat order
   instead of Fuse's `(score, idx)` global tie-break.
3. With `shouldSort: false`, results came back in shard-concat order
   rather than global collection order — visible after `add()` (which
   round-robins across shards) and `setCollection()`.

The worker is now initialized with `includeScore: true` so the main
thread always receives the score it needs to tie-break, then strips it
from the final result if the caller didn't ask for it. The merge sort
mirrors Fuse's default `(score, idx)` comparator on the global refIndex,
and `shouldSort: false` re-sorts by global refIndex.

Also reject function-valued options (`sortFn`, top-level `getFn`,
`keys[].getFn`) at construction time. Functions aren't structured-
cloneable, so they used to crash with an opaque `DataCloneError` on the
first `search()` call. The new error names the offending option.

Plan 007.

Author: krisk

README.md

@@ -40,7 +40,7 @@ const results = await fuse.search('query')
 fuse.terminate()
 ```
 
-Same options, same results as `Fuse` — just async. See the [Web Workers docs](https://fusejs.io/web-workers.html) for the interactive demo and full API.
+Same options and results as `Fuse` — just async. Function-valued options (`sortFn`, `getFn`, `keys[].getFn`) aren't supported because functions can't be transferred to a worker; everything else carries over. See the [Web Workers docs](https://fusejs.io/web-workers.html) for the interactive demo and full API.
 
 ## Installation
 

docs/web-workers.md

@@ -58,7 +58,7 @@ const results = await fuse.search('javascript')
 fuse.terminate()
 ```
 
-Same options and same results as `Fuse` — the only difference is that `search()` returns a Promise.
+Almost the same API as `Fuse`, with a few caveats covered in [Differences from Fuse](#differences-from-fuse) below — the headline one is that `search()` returns a Promise.
 
 ## How It Works
 
@@ -161,9 +161,23 @@ Workers add overhead from data serialization (`postMessage`) and worker startup.
 | `remove(predicate)` | Supported | Use `setCollection()` instead |
 | `getIndex()` | Supported | Not available |
 | Result object references | Same as input docs | Copies (structured clone) |
-| Custom `sortFn` | Supported | Not available (sorts by score) |
+| Custom `sortFn` | Supported | Throws at construction |
+| Custom `getFn` (top-level) | Supported | Throws at construction |
+| Custom `keys[].getFn` | Supported | Throws at construction |
 | Cleanup required | No | Call `terminate()` |
 
+#### Unsupported options
+
+`FuseWorker` rejects function-valued options at construction time. Functions can't be transferred to a worker via `postMessage` (they aren't structured-cloneable), so `FuseWorker` throws an explicit error instead of failing later with an opaque `DataCloneError`.
+
+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.
+
+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.
+
 ## Worker URL
 
 `FuseWorker` needs to load a separate script file inside each Web Worker. By default, it finds this file automatically — you don't need to do anything.

src/core/errorMessages.ts

@@ -16,3 +16,13 @@ export const MISSING_KEY_PROPERTY = (name: string): string => `Missing ${name} p
 
 export const INVALID_KEY_WEIGHT_VALUE = (key: string): string =>
   `Property 'weight' in key '${key}' must be a positive integer`
+
+export const FUSE_WORKER_UNSUPPORTED_FN_OPTION = (option: string): string =>
+  `FuseWorker does not support function-valued option '${option}': ` +
+  `functions cannot be transferred to Web Workers via postMessage. ` +
+  `Remove this option or fall back to Fuse.`
+
+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 ` +
+  `comparison does not have. Use new Fuse(...).search(...) instead.`

src/workers/FuseWorker.ts

@@ -1,7 +1,9 @@
 /// <reference lib="dom" />
 
+import * as ErrorMsg from '../core/errorMessages'
 import type {
   IFuseOptions,
+  FuseOptionKey,
   FuseResult,
   FuseSearchOptions,
   Expression
@@ -52,12 +54,39 @@ export default class FuseWorker<T> {
     this._docs = docs.slice()
     this._options = options || {} as IFuseOptions<T>
     this._workerOptions = workerOptions || {}
+    // Reject function-valued options eagerly. Without this check, postMessage
+    // throws DataCloneError on first search() rather than at construction.
+    FuseWorker._assertNoFunctionOptions(this._options)
     // 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
       || new URL('./fuse.worker.mjs', import.meta.url)
   }
 
+  private static _assertNoFunctionOptions<U>(options: IFuseOptions<U>): void {
+    if (typeof (options as { sortFn?: unknown }).sortFn === 'function') {
+      throw new Error(ErrorMsg.FUSE_WORKER_UNSUPPORTED_FN_OPTION('sortFn'))
+    }
+    if (typeof (options as { getFn?: unknown }).getFn === 'function') {
+      throw new Error(ErrorMsg.FUSE_WORKER_UNSUPPORTED_FN_OPTION('getFn'))
+    }
+    const keys = options.keys
+    if (Array.isArray(keys)) {
+      for (let i = 0, len = keys.length; i < len; i += 1) {
+        const key = keys[i] as FuseOptionKey<U>
+        if (key && typeof key === 'object' && !Array.isArray(key)) {
+          if (typeof (key as { getFn?: unknown }).getFn === 'function') {
+            const name = (key as { name?: string | string[] }).name
+            const label = Array.isArray(name) ? name.join('.') : (name ?? String(i))
+            throw new Error(
+              ErrorMsg.FUSE_WORKER_UNSUPPORTED_FN_OPTION(`keys[${label}].getFn`)
+            )
+          }
+        }
+      }
+    }
+  }
+
   private _getNumWorkers(): number {
     return this._workerOptions.numWorkers || getDefaultWorkerCount()
   }
@@ -93,13 +122,21 @@ export default class FuseWorker<T> {
     return worker
   }
 
+  private _workerInitOptions(): IFuseOptions<T> {
+    // Force includeScore so the main thread can do a global (score, idx)
+    // tie-break across shards. Score is stripped from the final result if the
+    // caller didn't ask for it.
+    return { ...this._options, includeScore: true }
+  }
+
   private async _init(): Promise<void> {
     const numWorkers = this._getNumWorkers()
     const chunkSize = Math.ceil(this._docs.length / numWorkers)
 
     this._shards = []
     this._addCursor = 0
 
+    const workerInitOptions = this._workerInitOptions()
     const initPromises: Promise<void>[] = []
     for (let i = 0; i < numWorkers; i++) {
       const start = i * chunkSize
@@ -110,7 +147,7 @@ export default class FuseWorker<T> {
 
       const shard: Shard = { worker: this._spawnWorker(), globalIndices }
       this._shards.push(shard)
-      initPromises.push(this._call(shard.worker, 'init', [chunk, this._options]))
+      initPromises.push(this._call(shard.worker, 'init', [chunk, workerInitOptions]))
     }
 
     await Promise.all(initPromises)
@@ -144,13 +181,38 @@ export default class FuseWorker<T> {
       }
     }
 
-    // Sort by score (lower is better)
     const shouldSort = this._options.shouldSort !== false
     if (shouldSort) {
-      merged.sort((a, b) => (a.score ?? 0) - (b.score ?? 0))
+      // Mirror Fuse's default sortFn: (score, idx) tie-break, but on the
+      // GLOBAL refIndex so equal-score results across shards collapse into a
+      // deterministic order matching single-thread Fuse.
+      merged.sort((a, b) => {
+        const sa = a.score ?? 0
+        const sb = b.score ?? 0
+        if (sa === sb) {
+          return a.refIndex < b.refIndex ? -1 : 1
+        }
+        return sa < sb ? -1 : 1
+      })
+    } else {
+      // Restore global collection order. Round-robin add() and
+      // shard-concatenation order otherwise leak through.
+      merged.sort((a, b) => a.refIndex - b.refIndex)
+    }
+
+    // Workers always include score so the merge above can tie-break; strip it
+    // here if the caller didn't ask for it. Rebuild the object instead of
+    // `delete`-ing — `delete` deopts the shape and roughly doubles the
+    // post-sort cost on large result sets.
+    if (!this._options.includeScore) {
+      for (let i = 0, len = merged.length; i < len; i += 1) {
+        const r = merged[i]
+        merged[i] = r.matches !== undefined
+          ? { item: r.item, refIndex: r.refIndex, matches: r.matches }
+          : { item: r.item, refIndex: r.refIndex }
+      }
     }
 
-    // Apply limit
     const limit = options?.limit
     if (limit && limit > 0) {
       return merged.slice(0, limit)