TURBO for Developers

Home > widget-integration > FilterStorageHelper

FilterStorageHelper class

Storage helper for filter module operations.

Provides a unified interface for localStorage and sessionStorage operations with built-in error handling, type safety, and JSON serialization. Manages filter-related storage including collection data, pagination state, and temporary filter selections.

Signature:

export declare class FilterStorageHelper

Remarks

This helper handles: - localStorage get/set operations with null safety - sessionStorage operations with JSON serialization/parsing - Collection-specific storage (tags, IDs, handles) - Pagination state persistence across sessions - Storage availability detection - Prefix-based bulk operations

All storage operations include SSR-safe checks for storage availability. JSON operations are wrapped in try-catch to handle parsing errors and quota exceeded scenarios gracefully.

Technical Support teams can extend this helper to add custom storage operations, implement shop-specific caching strategies, or integrate with alternative storage backends.

Example 1

Extend to add custom storage encryption:

window.boostWidgetIntegration.extend('FilterStorageHelper', (FilterStorageHelper) => {
  return class CustomStorageHelper extends FilterStorageHelper {
    setLocalStorage(key, value) {
      // Encrypt sensitive data before storage
      const encrypted = this.encrypt(value);
      super.setLocalStorage(key, encrypted);
    }

    getLocalStorage(key) {
      const encrypted = super.getLocalStorage(key);
      return encrypted ? this.decrypt(encrypted) : null;
    }
  };
});

Example 2

Override to add storage analytics:

window.boostWidgetIntegration.extend('FilterStorageHelper', (FilterStorageHelper) => {
  return class extends FilterStorageHelper {
    setSessionStorage(key, value) {
      super.setSessionStorage(key, value);
      // Track storage usage
      this.analytics.track('filter_storage_set', {
        key,
        size: JSON.stringify(value).length
      });
    }
  };
});

Methods

Method	Modifiers	Description
clearLocalStorageByPrefix(prefix)		Clears all items from localStorage with a specific prefix. Removes all local storage keys that start with the given prefix. Useful for clearing all filter-related persistent storage at once.
clearPaginationSession()		Clears pagination from session storage. Removes the stored pagination state. Called when resetting filters or navigating to a new collection.
clearSessionStorageByPrefix(prefix)		Clears all items from sessionStorage with a specific prefix. Removes all session storage keys that start with the given prefix. Useful for clearing all filter-related storage at once.
getCollectionIdByHandleKey(key)		Gets collection ID by handle key. Retrieves the collection ID associated with a collection handle. Returns 0 if the mapping doesn't exist.
getCollectionTagFromSlugKey(key)		Gets collection tag from slug key. Retrieves the collection tag value associated with a URL slug key. Returns undefined if the mapping doesn't exist.
getLocalStorage(key)		Gets a value from localStorage. Retrieves a string value from localStorage with SSR-safe checks. Returns null if localStorage is unavailable or key doesn't exist.
getPaginationSession()		Gets the current pagination page from session storage. Retrieves the stored page number from session storage. Returns 1 if storage is unavailable, key doesn't exist, or value is invalid.
getSessionStorage(key, fallback)		Gets a value from sessionStorage with type-safe JSON parsing. Retrieves and parses a JSON value from sessionStorage. Returns the fallback value if storage is unavailable, key doesn't exist, or JSON parsing fails.
isLocalStorageAvailable()		Checks if localStorage is available and accessible. Tests localStorage availability by attempting to write and remove a test value. Returns false in SSR contexts, private browsing mode, or when storage is disabled.
isSessionStorageAvailable()		Checks if sessionStorage is available and accessible. Tests sessionStorage availability by attempting to write and remove a test value. Returns false in SSR contexts, private browsing mode, or when storage is disabled.
removeLocalStorage(key)		Removes an item from localStorage. Deletes a specific key from local storage with SSR-safe checks.
removeSessionStorage(key)		Removes an item from sessionStorage. Deletes a specific key from session storage with SSR-safe checks.
saveCollectionIdByHandle(handle, value)		Saves collection ID mapping by handle to session storage. Maps collection handles to their numeric IDs for efficient lookup during filter operations. Enables resolving collection IDs from URL handles without additional API calls.
saveCollectionTagsSlugKey(key, value)		Saves collection tag slug mapping to session storage. Maps URL slug keys to collection tag values for proper URL parsing and navigation. Used when collections have tagged variants accessible via /collections/handle/tag-slug URLs.
setLocalStorage(key, value)		Sets a value in localStorage. Stores a string value in localStorage with SSR-safe checks. Silently fails if localStorage is unavailable.
setPaginationSession(page)		Sets the pagination page in session storage. Stores the current page number in session storage for persistence across page reloads during the same browsing session. Validates and normalizes page numbers.
setSessionStorage(key, value)		Sets a value in sessionStorage with JSON serialization. Serializes the value to JSON and stores it in sessionStorage. Catches and logs errors from quota exceeded, circular references, or private browsing mode restrictions.

← Back to Library Reference