fix: coerce non-string suggestion values at the response boundary (#871)

If a server or local lookup supplies a suggestion with a non-string
`value` (e.g. numeric IDs), downstream string methods such as
`toLowerCase`, `replace`, `substr`, and `indexOf` throw mid-render.

`verifySuggestionsFormat` now coerces any non-string `value` to a
string via `String(...)` (preserving the rest of the suggestion shape
via shallow copy). The coercion is also applied to the function-lookup
callback path and ahead of the ajax `onSearchComplete` fire so all
callbacks see a normalized `Suggestion.value: string`, matching the
declared TypeScript contract.

Closes #844.

Co-authored-by: Tomas Kirda <tomas.kirda@bisoncommerce.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

dist/jquery.autocomplete.esm.js

@@ -399,8 +399,9 @@ var _Autocomplete = class _Autocomplete {
     const params = options.ignoreParams ? null : options.params;
     if (typeof options.lookup === "function") {
       options.lookup(q, (data) => {
-        this.suggestions = data.suggestions;
-        options.onSearchComplete.call(this.element, q, data.suggestions);
+        const suggestions = this.verifySuggestionsFormat(data.suggestions);
+        this.suggestions = suggestions;
+        options.onSearchComplete.call(this.element, q, suggestions);
         this.suggest();
       });
       return;
@@ -430,6 +431,7 @@ var _Autocomplete = class _Autocomplete {
       this.currentRequest = $.ajax(ajaxSettings).done((data) => {
         this.currentRequest = null;
         const result = options.transformResult(data, q);
+        result.suggestions = this.verifySuggestionsFormat(result.suggestions);
         options.onSearchComplete.call(this.element, q, result.suggestions);
         this.processResponse(result, q, cacheKey);
       }).fail((jqXHR, textStatus, errorThrown) => {
@@ -560,7 +562,9 @@ var _Autocomplete = class _Autocomplete {
     if (suggestions.length && typeof suggestions[0] === "string") {
       return suggestions.map((value) => ({ value, data: null }));
     }
-    return suggestions;
+    return suggestions.map(
+      (s) => typeof s.value === "string" ? s : { ...s, value: String(s.value) }
+    );
   }
   validateOrientation(orientation, fallback) {
     const normalized = (orientation || "").trim().toLowerCase();

dist/jquery.autocomplete.js

@@ -407,8 +407,9 @@
       const params = options.ignoreParams ? null : options.params;
       if (typeof options.lookup === "function") {
         options.lookup(q, (data) => {
-          this.suggestions = data.suggestions;
-          options.onSearchComplete.call(this.element, q, data.suggestions);
+          const suggestions = this.verifySuggestionsFormat(data.suggestions);
+          this.suggestions = suggestions;
+          options.onSearchComplete.call(this.element, q, suggestions);
           this.suggest();
         });
         return;
@@ -438,6 +439,7 @@
         this.currentRequest = $2.ajax(ajaxSettings).done((data) => {
           this.currentRequest = null;
           const result = options.transformResult(data, q);
+          result.suggestions = this.verifySuggestionsFormat(result.suggestions);
           options.onSearchComplete.call(this.element, q, result.suggestions);
           this.processResponse(result, q, cacheKey);
         }).fail((jqXHR, textStatus, errorThrown) => {
@@ -568,7 +570,9 @@
       if (suggestions.length && typeof suggestions[0] === "string") {
         return suggestions.map((value) => ({ value, data: null }));
       }
-      return suggestions;
+      return suggestions.map(
+        (s) => typeof s.value === "string" ? s : { ...s, value: String(s.value) }
+      );
     }
     validateOrientation(orientation, fallback) {
       const normalized = (orientation || "").trim().toLowerCase();

dist/jquery.autocomplete.min.js

@@ -415,10 +415,11 @@ export class Autocomplete {
 
         if (typeof options.lookup === "function") {
             (options.lookup as LookupCallback)(q, (data) => {
-                this.suggestions = data.suggestions;
+                const suggestions = this.verifySuggestionsFormat(data.suggestions);
+                this.suggestions = suggestions;
                 // Fire onSearchComplete before suggest() so consumers see
                 // "search complete" before any auto-select fires onSelect.
-                options.onSearchComplete.call(this.element, q, data.suggestions);
+                options.onSearchComplete.call(this.element, q, suggestions);
                 this.suggest();
             });
             return;
@@ -453,6 +454,7 @@ export class Autocomplete {
                 .done((data) => {
                     this.currentRequest = null;
                     const result = options.transformResult(data, q);
+                    result.suggestions = this.verifySuggestionsFormat(result.suggestions);
                     options.onSearchComplete.call(this.element, q, result.suggestions);
                     this.processResponse(result, q, cacheKey!);
                 })
@@ -622,7 +624,11 @@ export class Autocomplete {
         if (suggestions.length && typeof suggestions[0] === "string") {
             return (suggestions as string[]).map((value) => ({ value, data: null }));
         }
-        return suggestions as Suggestion[];
+        // Coerce non-string `value` so downstream string methods (toLowerCase,
+        // replace, substr, indexOf) don't throw on numeric or other types.
+        return (suggestions as Suggestion[]).map((s) =>
+            typeof s.value === "string" ? s : { ...s, value: String(s.value) }
+        );
     }
 
     validateOrientation(orientation: string | undefined, fallback: Orientation): Orientation {

src/Autocomplete.ts

@@ -708,6 +708,47 @@ describe("Autocomplete", () => {
     });
 });
 
+describe("Autocomplete non-string suggestion values", () => {
+    afterEach(() => {
+        $(".autocomplete-suggestions").remove();
+    });
+
+    it("coerces numeric value from a local lookup so render does not throw", () => {
+        const input = document.createElement("input");
+        const autocomplete = new $.Autocomplete(input, {
+            lookup: [{ value: 12345, data: "n" }],
+            triggerSelectOnValidInput: false,
+        });
+
+        input.value = "1";
+        expect(() => autocomplete.onValueChange()).not.toThrow();
+
+        expect(typeof autocomplete.suggestions[0].value).toBe("string");
+        expect(autocomplete.suggestions[0].value).toBe("12345");
+    });
+
+    it("coerces numeric value from a function lookup callback", () => {
+        const input = document.createElement("input");
+        let completedValueType;
+        let selectedValueType;
+        const autocomplete = new $.Autocomplete(input, {
+            lookup: (_q, done) => done({ suggestions: [{ value: 42, data: "n" }] }),
+            onSearchComplete: (_q, suggestions) => {
+                completedValueType = typeof suggestions[0].value;
+            },
+            onSelect: (suggestion) => {
+                selectedValueType = typeof suggestion.value;
+            },
+        });
+
+        input.value = "42";
+        autocomplete.onValueChange();
+
+        expect(completedValueType).toBe("string");
+        expect(selectedValueType).toBe("string");
+    });
+});
+
 describe("Autocomplete event ordering", () => {
     afterEach(() => {
         $(".autocomplete-suggestions").remove();