Align API of loadProductsListSearchServiceConfig and loadProductsListServiceConfig (#118)

* Align API of loadProductsListSearchServiceConfig and loadProductsListServiceConfig

* Align the API more

* Bump stores version

Author: yurynix

examples/astro-stores-demo/src/pages/category/[categorySlug].astro

@@ -7,15 +7,15 @@ import {
   loadCategoryServiceConfig,
   loadProductsListSearchServiceConfig,
   loadProductsListServiceConfig,
-  parseUrlForProductsListSearch,
+  parseUrlToSearchOptions,
 } from '@wix/headless-stores/services';
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import StoreCollectionPage from '../../react-pages/category/index';
 
 // Get category slug from URL params
 const { categorySlug = '' } = Astro.params;
 
-// Load categories first so we can pass them to parseUrlForProductsListSearch
+// Load categories first so we can pass them to parseUrlToSearchOptions
 const categoriesListConfig = await loadCategoriesListServiceConfig();
 const category = categoriesListConfig.categories.find(
   category => category.slug === categorySlug
@@ -27,7 +27,8 @@ if (!category) {
 
 const categoryName = category?.name || '';
 
-const { searchOptions } = await parseUrlForProductsListSearch(
+// Parse URL to get search options with defaults for this category
+const parsed = await parseUrlToSearchOptions(
   Astro.url.href,
   categoriesListConfig.categories,
   {
@@ -48,9 +49,9 @@ const [
   productsListSearchConfig,
   seoTagsServiceConfig,
 ] = await Promise.all([
-  loadProductsListServiceConfig(searchOptions),
+  loadProductsListServiceConfig(parsed), // Both services now use same parsed result
   loadCurrentCartServiceConfig(),
-  loadProductsListSearchServiceConfig(Astro.url.href),
+  loadProductsListSearchServiceConfig(parsed),
   loadSEOTagsServiceConfig({
     pageUrl: Astro.url.href,
     itemData: {

packages/headless-components/stores/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/headless-stores",
-  "version": "0.0.48",
+  "version": "0.0.49",
   "type": "module",
   "scripts": {
     "prebuild": "cd ../media && yarn build && cd ../ecom && yarn build",

packages/headless-components/stores/src/services/index.ts

@@ -45,6 +45,6 @@ export {
   ProductsListSearchServiceDefinition,
   ProductsListSearchServiceConfig,
   loadProductsListSearchServiceConfig,
-  parseUrlForProductsListSearch,
+  parseUrlToSearchOptions,
   convertUrlSortToSortType,
 } from "./products-list-search-service.js";

packages/headless-components/stores/src/services/products-list-search-service.ts

@@ -49,7 +49,7 @@ export interface ProductChoice {
 /**
  * Initial search state that can be loaded from URL parameters.
  */
-type InitialSearchState = {
+export type InitialSearchState = {
   sort?: SortType;
   limit?: number;
   cursor?: string | null;
@@ -293,9 +293,33 @@ function updateUrlWithSearchState(searchState: {
 }
 
 /**
- * Parse URL and build complete search options with all filters, sort, and pagination
+ * Parse URL and build complete search options with all filters, sort, and pagination.
+ * This function extracts search parameters, filters, sorting, and pagination from a URL
+ * and converts them into the format expected by the Wix Stores API.
+ *
+ * @param {string} url - The URL to parse search parameters from
+ * @param {Category[]} categoriesList - List of available categories for category slug resolution
+ * @param {productsV3.V3ProductSearch} [defaultSearchOptions] - Default search options to merge with parsed URL parameters
+ * @returns {Promise<{searchOptions: productsV3.V3ProductSearch, initialSearchState: InitialSearchState}>}
+ *   Object containing both API-ready search options and UI-ready initial state
+ *
+ * @example
+ * ```tsx
+ * // Parse URL with filters, sort, and pagination
+ * const categories = await loadCategoriesListServiceConfig();
+ * const { searchOptions, initialSearchState } = await parseUrlToSearchOptions(
+ *   'https://example.com/products?sort=price:desc&Color=red,blue&minPrice=50',
+ *   categories.categories
+ * );
+ *
+ * // Use searchOptions for API calls
+ * const products = await productsV3.searchProducts(searchOptions);
+ *
+ * // Use initialSearchState for UI initialization
+ * const filterState = initialSearchState.productOptions; // { colorId: ['red-id', 'blue-id'] }
+ * ```
  */
-export async function parseUrlForProductsListSearch(
+export async function parseUrlToSearchOptions(
   url: string,
   categoriesList: Category[],
   defaultSearchOptions?: productsV3.V3ProductSearch,
@@ -570,18 +594,57 @@ export async function parseUrlForProductsListSearch(
 }
 
 /**
- * Load search service configuration from URL
+ * Load search service configuration from URL or parsed URL result.
+ * This function provides the configuration for the Products List Search service,
+ * including customizations and initial search state.
+ *
+ * @param {string | { searchOptions: productsV3.V3ProductSearch; initialSearchState: InitialSearchState }} input - Either a URL to parse or parsed URL result from parseUrlToSearchOptions
+ * @returns {Promise<ProductsListSearchServiceConfig>} Promise that resolves to the search service configuration
+ *
+ * @example
+ * ```tsx
+ * // Option 1: Load from URL (will parse filters, sort, pagination from URL params)
+ * const searchConfig = await loadProductsListSearchServiceConfig(window.location.href);
+ *
+ * // Option 2: Custom parsing with defaults
+ * const categories = await loadCategoriesListServiceConfig();
+ * const parsed = await parseUrlToSearchOptions(
+ *   window.location.href,
+ *   categories.categories,
+ *   {
+ *     cursorPaging: { limit: 12 },
+ *     filter: { 'categoryIds': ['123'] },
+ *     sort: [{ fieldName: 'name' as const, order: 'ASC' as const }]
+ *   }
+ * );
+ * const searchConfig = await loadProductsListSearchServiceConfig(parsed);
+ *
+ * // Option 3: Performance optimization - use parsed result for both services (no duplicate parsing)
+ * const categories = await loadCategoriesListServiceConfig();
+ * const parsed = await parseUrlToSearchOptions(url, categories.categories);
+ * const [productsConfig, searchConfig] = await Promise.all([
+ *   loadProductsListServiceConfig(parsed),
+ *   loadProductsListSearchServiceConfig(parsed),
+ * ]);
+ * ```
  */
 export async function loadProductsListSearchServiceConfig(
-  url: string,
+  input: string | { searchOptions: productsV3.V3ProductSearch; initialSearchState: InitialSearchState },
 ): Promise<ProductsListSearchServiceConfig> {
-  // Load categories using the categories service
-  const categoriesListConfig = await loadCategoriesListServiceConfig();
-
-  const { initialSearchState } = await parseUrlForProductsListSearch(
-    url,
-    categoriesListConfig.categories,
-  );
+  let initialSearchState: InitialSearchState;
+
+  if (typeof input === 'string') {
+    // URL input - parse it
+    const categoriesListConfig = await loadCategoriesListServiceConfig();
+    const { initialSearchState: parsedState } = await parseUrlToSearchOptions(
+      input,
+      categoriesListConfig.categories,
+    );
+    initialSearchState = parsedState;
+  } else {
+    // Parsed URL result - use initialSearchState directly (no duplicate work)
+    initialSearchState = input.initialSearchState;
+  }
 
   const { items: customizations = [] } = await customizationsV3
     .queryCustomizations()

packages/headless-components/stores/src/services/products-list-service.ts

@@ -4,6 +4,8 @@ import {
   type Signal,
 } from "@wix/services-definitions/core-services/signals";
 import { productsV3, readOnlyVariantsV3 } from "@wix/stores";
+import { loadCategoriesListServiceConfig } from "./categories-list-service.js";
+import { parseUrlToSearchOptions, type InitialSearchState } from "./products-list-search-service.js";
 
 export const DEFAULT_QUERY_LIMIT = 100;
 
@@ -27,27 +29,33 @@ export type ProductsListServiceConfig = {
 /**
  * Loads products list service configuration from the Wix Stores API for SSR initialization.
  * This function is designed to be used during Server-Side Rendering (SSR) to preload
- * a list of products based on search criteria.
+ * a list of products based on search criteria or URL parameters.
  *
- * @param {productsV3.V3ProductSearch} searchOptions - The search options for querying products
+ * @param {string | { searchOptions: productsV3.V3ProductSearch; initialSearchState: InitialSearchState }} input - Either a URL to parse or parsed URL result from parseUrlToSearchOptions
  * @returns {Promise<ProductsListServiceConfig>} Promise that resolves to the products list configuration
  *
  * @example
  * ```astro
  * ---
  * // Astro page example - pages/products.astro
- * import { loadProductsListServiceConfig } from '@wix/stores/services';
+ * import { loadProductsListServiceConfig, parseUrlToSearchOptions, loadCategoriesListServiceConfig } from '@wix/stores/services';
  * import { ProductList } from '@wix/stores/components';
  *
- * // Define search options
- * const searchOptions = {
- *   cursorPaging: { limit: 12 },
- *   filter: {},
- *   sort: [{ fieldName: 'name', order: 'ASC' }]
- * };
+ * // Option 1: Load from URL (will parse filters, sort, pagination from URL params)
+ * const productsConfig = await loadProductsListServiceConfig(Astro.url.href);
  *
- * // Load products data during SSR
- * const productsConfig = await loadProductsListServiceConfig(searchOptions);
+ * // Option 2: Custom parsing with defaults
+ * const categories = await loadCategoriesListServiceConfig();
+ * const parsed = await parseUrlToSearchOptions(
+ *   Astro.url.href,
+ *   categories.categories,
+ *   {
+ *     cursorPaging: { limit: 12 },
+ *     filter: {},
+ *     sort: [{ fieldName: 'name' as const, order: 'ASC' as const }]
+ *   }
+ * );
+ * const productsConfig = await loadProductsListServiceConfig(parsed);
  * ---
  *
  * <ProductList.Root productsConfig={productsConfig}>
@@ -66,23 +74,31 @@ export type ProductsListServiceConfig = {
  * ```tsx
  * // Next.js page example - pages/products.tsx
  * import { GetServerSideProps } from 'next';
- * import { loadProductsListServiceConfig } from '@wix/stores/services';
+ * import { loadProductsListServiceConfig, parseUrlToSearchOptions, loadCategoriesListServiceConfig } from '@wix/stores/services';
  * import { ProductsList } from '@wix/stores/components';
  *
  * interface ProductsPageProps {
  *   productsConfig: Awaited<ReturnType<typeof loadProductsListServiceConfig>>;
  * }
  *
- * export const getServerSideProps: GetServerSideProps<ProductsPageProps> = async () => {
- *   const searchOptions = {
- *     cursorPaging: { limit: 12 },
- *     filter: {
- *       'allCategoriesInfo.categories': { $matchItems: [{ _id: { $in: [category._id] } }] }
- *     },
- *     sort: [{ fieldName: 'name' as const, order: 'ASC' as const }]
- *   };
+ * export const getServerSideProps: GetServerSideProps<ProductsPageProps> = async ({ req }) => {
+ *   // Option 1: Parse from URL
+ *   const productsConfig = await loadProductsListServiceConfig(`${req.url}`);
  *
- *   const productsConfig = await loadProductsListServiceConfig(searchOptions);
+ *   // Option 2: Custom parsing with filters
+ *   const categories = await loadCategoriesListServiceConfig();
+ *   const parsed = await parseUrlToSearchOptions(
+ *     `${req.url}`,
+ *     categories.categories,
+ *     {
+ *       cursorPaging: { limit: 12 },
+ *       filter: {
+ *         'allCategoriesInfo.categories': { $matchItems: [{ _id: { $in: [category._id] } }] }
+ *       },
+ *       sort: [{ fieldName: 'name' as const, order: 'ASC' as const }]
+ *     }
+ *   );
+ *   const productsConfig = await loadProductsListServiceConfig(parsed);
  *
  *   return {
  *     props: {
@@ -106,10 +122,40 @@ export type ProductsListServiceConfig = {
  *   );
  * }
  * ```
+ *
+  * @example
+ * ```tsx
+ * // Advanced: Performance optimization when using both services
+ * import { parseUrlToSearchOptions, loadProductsListServiceConfig, loadProductsListSearchServiceConfig, loadCategoriesListServiceConfig } from '@wix/stores/services';
+ *
+ * const categories = await loadCategoriesListServiceConfig();
+ * const parsed = await parseUrlToSearchOptions(url, categories.categories);
+ *
+ * // Both services use the same parsed result (no duplicate URL parsing)
+ * const [productsConfig, searchConfig] = await Promise.all([
+ *   loadProductsListServiceConfig(parsed),
+ *   loadProductsListSearchServiceConfig(parsed)
+ * ]);
+ * ```
  */
 export async function loadProductsListServiceConfig(
-  searchOptions: productsV3.V3ProductSearch,
+  input: string | { searchOptions: productsV3.V3ProductSearch; initialSearchState: InitialSearchState },
 ): Promise<ProductsListServiceConfig> {
+  let searchOptions: productsV3.V3ProductSearch;
+
+  if (typeof input === 'string') {
+    // URL input - parse it
+    const categoriesListConfig = await loadCategoriesListServiceConfig();
+    const { searchOptions: parsedOptions } = await parseUrlToSearchOptions(
+      input,
+      categoriesListConfig.categories
+    );
+    searchOptions = parsedOptions;
+  } else {
+    // Parsed URL result - use searchOptions directly
+    searchOptions = input.searchOptions;
+  }
+
   const searchWithoutFilter = { ...searchOptions, filter: {} };
 
   const [resultWithoutFilter, resultWithFilter] = await Promise.all([