TURBO for Developers

Home > widget-integration > InstantSearchService

InstantSearchService class

Service for instant search business logic.

Technical Support teams can extend this service for custom search behavior:

Signature:

export declare class InstantSearchService

Example

window.boostWidgetIntegration.extend('InstantSearchService', (InstantSearchService) => {
  return class CustomSearchService extends InstantSearchService {
    // Filter products before rendering — preferred extension point
    protected filterWidgetProducts(products, searchSettings) {
      const available = products.filter(p => p.available);
      return super.filterWidgetProducts(available, searchSettings);
    }
  };
});

Constructors

Constructor	Modifiers	Description
(constructor)(appService, instantSearchAPI, instantSearchSelectors, recentSearchService, predictiveBundleService, volumeBundleService)		Constructs a new instance of the `InstantSearchService` class

Properties

Property	Modifiers	Type	Description
abortController	`protected`	AbortController \| null	Current search abort controller
appService	`protected`	AppService
DEBOUNCE_DELAY	`protected` `readonly`	(not declared)	Debounce delay in milliseconds
debounceTimer	`protected`	ReturnType<typeof setTimeout> \| null	Debounce timer ID
debugMode	`protected`	boolean	Debug mode flag
instantSearchAPI	`protected`	InstantSearchAPI
instantSearchSelectors	`protected`	InstantSearchSelectors
PRE_REQUEST_IDS	`static` `readonly`	(not declared)	localStorage key for analytics pre-request IDs.
predictiveBundleService	`protected`	PredictiveBundleService
recentSearchService	`protected`	RecentSearchService
redirectsCache	`protected`	Record<string, string> \| null	Cached redirects map
SUGGESTION_DATA_KEY	`static` `readonly`	(not declared)	localStorage key for suggestion data caching.
volumeBundleService	`protected`	VolumeBundleService

Methods

Method	Modifiers	Description
addRecentSearch(title, extraParam)		Add recent search entry.
applyShopSpecificFilters(products, _searchSettings)	`protected`	Apply shop-specific product filters after base price transformation. Second-level extension hook called by `filterWidgetProducts()`. Override to add availability checks, tag filters, vendor rules, metafield filtering, etc.
areAllBlocksEmpty(data, searchSettings)	`protected`	Check if all visible suggestion blocks are empty.
cacheSuggestionData(query, data)	`protected`	Cache suggestion data in localStorage for analytics. Legacy: setLocalStorage(SUGGESTION_DATA, { query, id, suggestions }) New: Dedicated method with typed structure
cancelSearch()		Cancel any pending debounced search.
checkRedirect(query, redirects)		Check if query should redirect. Legacy: Inline check in handleRedirect() New: Dedicated method with type safety
clearRecentSearches()		Clear all recent searches.
clearRedirectsCache()		Clear redirects cache to force re-fetch.
dispose()		Cleanup resources.
filterWidgetProducts(products, searchSettings)	`protected`	Filter and transform products for display. Extension point for TS teams to add shop-specific product filtering. The base implementation transforms product prices via `transformProductPrices()` — override to add additional filters (availability, tags, vendor, metafields, etc.). Legacy: `transformProductPrice(context, products)` — not overridable New: Protected method with full override capability
getCachedSuggestionData()		Get cached suggestion data from localStorage.
getDefaultSuggestionData(searchSettings)		Build default suggestion data for initial state. Legacy: buildDefaultDataSuggestion(context) New: getDefaultSuggestionData(searchSettings) with typed return
getPriceFormatSettings()	`protected`	Get price formatting settings from theme configuration.
getRecentSearches(limit)		Get recent searches.
getRedirects()		Get redirect mappings.
getSearchPageUrl(query, extraParams)		Generate search page URL. Legacy: generateSearchPageHref(term, extraParam) New: getSearchPageUrl(query, extraParams) with proper encoding
getSuggestProducts(searchSettings)		Get suggested products for search box on-click. Legacy: getSuggestProducts(context) New: getSuggestProducts(searchSettings) with typed return
handleNoResults(data, query, searchSettings)	`protected`	Handle no-results scenario by fetching fallback products.
handleRedirect(query, redirects)		Handle redirect if query matches.
log(message, data)	`protected`	Log debug messages when debug mode is enabled.
mergeSuggestionData(defaultData, searchResponse)		Merge default data with search response for rendering.
processBundles(data, _searchSettings)	`protected`	Process bundle data from search response. Legacy: Inline bundle processing with volumeBundleData/dynamicBundleData New: Delegated to bundle services (when integrated)
processWidgetConfig(config)	`protected`	Process widget configuration before use. Extension point for TS teams to customise search settings on a per-shop basis before any search or default-data operations begin.
renderSuggestions(template, data)		Render suggestions using template.
saveRequestId(type, requestId, bundles)	`protected`	Save request ID to localStorage for analytics tracking. Stores the API request ID under the `suggest` key in `boostSdPreRequestIds` so that downstream analytics can attribute product-click events to this specific search request. Legacy: `saveRequestId('suggest', requestId, bundles)` in `@deprecation/api/search.js` New: Protected method on the service, called immediately after `getSuggestions()`
search(query, searchSettings)		Execute search immediately. Legacy: requestSuggestion(context, query) New: search(query, searchSettings) with typed response
searchDebounced(query, searchSettings)		Execute search with debouncing. Legacy: requestSuggestionDebounce() using debounce utility New: Method with built-in debouncing and Promise support
setDebugMode(enabled)		Enable or disable debug logging.
transformProductPrices(products, _searchSettings)		Transform product prices for display. Legacy: transformProductPrice(context, products) New: transformProductPrices(products, searchSettings) using AppService
validateWidgetData(data)	`protected`	Validate suggestion data before caching or rendering. Extension point for TS teams to add custom validation rules. Return `false` to skip rendering and treat the response as empty.

← Back to Library Reference