@wix/headless-stores 0.0.48 → 0.0.49

package/cjs/dist/services/index.d.ts

@@ -4,4 +4,4 @@ export { ProductModifiersService, ProductModifiersServiceDefinition, } from "./p
 export { ProductService, ProductServiceDefinition, loadProductServiceConfig, } from "./product-service.js";
 export { SelectedVariantService, SelectedVariantServiceDefinition, } from "./selected-variant-service.js";
 export { ProductListService, ProductsListServiceDefinition, loadProductsListServiceConfig, ProductsListServiceConfig, } from "./products-list-service.js";
-export { ProductOption, InventoryStatusType, SortType, ProductChoice, ProductsListSearchService, ProductsListSearchServiceDefinition, ProductsListSearchServiceConfig, loadProductsListSearchServiceConfig, parseUrlForProductsListSearch, convertUrlSortToSortType, } from "./products-list-search-service.js";
+export { ProductOption, InventoryStatusType, SortType, ProductChoice, ProductsListSearchService, ProductsListSearchServiceDefinition, ProductsListSearchServiceConfig, loadProductsListSearchServiceConfig, parseUrlToSearchOptions, convertUrlSortToSortType, } from "./products-list-search-service.js";

package/cjs/dist/services/index.js

@@ -4,4 +4,4 @@ export { ProductModifiersService, ProductModifiersServiceDefinition, } from "./p
 export { ProductService, ProductServiceDefinition, loadProductServiceConfig, } from "./product-service.js";
 export { SelectedVariantService, SelectedVariantServiceDefinition, } from "./selected-variant-service.js";
 export { ProductListService, ProductsListServiceDefinition, loadProductsListServiceConfig, } from "./products-list-service.js";
-export { InventoryStatusType, SortType, ProductsListSearchService, ProductsListSearchServiceDefinition, loadProductsListSearchServiceConfig, parseUrlForProductsListSearch, convertUrlSortToSortType, } from "./products-list-search-service.js";
+export { InventoryStatusType, SortType, ProductsListSearchService, ProductsListSearchServiceDefinition, loadProductsListSearchServiceConfig, parseUrlToSearchOptions, convertUrlSortToSortType, } from "./products-list-search-service.js";

package/cjs/dist/services/products-list-search-service.d.ts

@@ -33,7 +33,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;
@@ -138,16 +138,75 @@ export declare const ProductsListSearchServiceDefinition: string & {
  */
 export declare function convertUrlSortToSortType(urlSort: string): SortType | null;
 /**
- * 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 declare function parseUrlForProductsListSearch(url: string, categoriesList: Category[], defaultSearchOptions?: productsV3.V3ProductSearch): Promise<{
+export declare function parseUrlToSearchOptions(url: string, categoriesList: Category[], defaultSearchOptions?: productsV3.V3ProductSearch): Promise<{
     searchOptions: productsV3.V3ProductSearch;
     initialSearchState: InitialSearchState;
 }>;
 /**
- * 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 declare function loadProductsListSearchServiceConfig(url: string): Promise<ProductsListSearchServiceConfig>;
+export declare function loadProductsListSearchServiceConfig(input: string | {
+    searchOptions: productsV3.V3ProductSearch;
+    initialSearchState: InitialSearchState;
+}): Promise<ProductsListSearchServiceConfig>;
 /**
  * Implementation of the Products List Search service
  */

package/cjs/dist/services/products-list-search-service.js

@@ -164,9 +164,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(url, categoriesList, defaultSearchOptions) {
+export async function parseUrlToSearchOptions(url, categoriesList, defaultSearchOptions) {
     const urlObj = new URL(url);
     const searchParams = urlObj.searchParams;
     // Get customizations for product option parsing
@@ -399,12 +423,52 @@ export async function parseUrlForProductsListSearch(url, categoriesList, default
     return { searchOptions, initialSearchState };
 }
 /**
- * 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) {
-    // Load categories using the categories service
-    const categoriesListConfig = await loadCategoriesListServiceConfig();
-    const { initialSearchState } = await parseUrlForProductsListSearch(url, categoriesListConfig.categories);
+export async function loadProductsListSearchServiceConfig(input) {
+    let 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()
         .find();

package/cjs/dist/services/products-list-service.d.ts

@@ -1,5 +1,6 @@
 import { type Signal } from "@wix/services-definitions/core-services/signals";
 import { productsV3 } from "@wix/stores";
+import { type InitialSearchState } from "./products-list-search-service.js";
 export declare const DEFAULT_QUERY_LIMIT = 100;
 /**
  * Configuration interface for the Products List service.
@@ -20,27 +21,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}>
@@ -59,23 +66,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: {
@@ -99,8 +114,26 @@ 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 declare function loadProductsListServiceConfig(searchOptions: productsV3.V3ProductSearch): Promise<ProductsListServiceConfig>;
+export declare function loadProductsListServiceConfig(input: string | {
+    searchOptions: productsV3.V3ProductSearch;
+    initialSearchState: InitialSearchState;
+}): Promise<ProductsListServiceConfig>;
 /**
  * Service definition for the Products List service.
  * This defines the reactive API contract for managing a list of products with search, pagination, and filtering capabilities.

package/cjs/dist/services/products-list-service.js

@@ -1,31 +1,39 @@
 import { defineService, implementService } from "@wix/services-definitions";
 import { SignalsServiceDefinition, } from "@wix/services-definitions/core-services/signals";
 import { productsV3, readOnlyVariantsV3 } from "@wix/stores";
+import { loadCategoriesListServiceConfig } from "./categories-list-service.js";
+import { parseUrlToSearchOptions } from "./products-list-search-service.js";
 export const DEFAULT_QUERY_LIMIT = 100;
 /**
  * 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}>
@@ -44,23 +52,31 @@ export const DEFAULT_QUERY_LIMIT = 100;
  * ```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: {
@@ -84,8 +100,34 @@ export const DEFAULT_QUERY_LIMIT = 100;
  *   );
  * }
  * ```
+ *
+  * @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) {
+export async function loadProductsListServiceConfig(input) {
+    let searchOptions;
+    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([
         fetchProducts(searchWithoutFilter),

package/dist/services/index.d.ts

@@ -4,4 +4,4 @@ export { ProductModifiersService, ProductModifiersServiceDefinition, } from "./p
 export { ProductService, ProductServiceDefinition, loadProductServiceConfig, } from "./product-service.js";
 export { SelectedVariantService, SelectedVariantServiceDefinition, } from "./selected-variant-service.js";
 export { ProductListService, ProductsListServiceDefinition, loadProductsListServiceConfig, ProductsListServiceConfig, } from "./products-list-service.js";
-export { ProductOption, InventoryStatusType, SortType, ProductChoice, ProductsListSearchService, ProductsListSearchServiceDefinition, ProductsListSearchServiceConfig, loadProductsListSearchServiceConfig, parseUrlForProductsListSearch, convertUrlSortToSortType, } from "./products-list-search-service.js";
+export { ProductOption, InventoryStatusType, SortType, ProductChoice, ProductsListSearchService, ProductsListSearchServiceDefinition, ProductsListSearchServiceConfig, loadProductsListSearchServiceConfig, parseUrlToSearchOptions, convertUrlSortToSortType, } from "./products-list-search-service.js";

package/dist/services/index.js

@@ -4,4 +4,4 @@ export { ProductModifiersService, ProductModifiersServiceDefinition, } from "./p
 export { ProductService, ProductServiceDefinition, loadProductServiceConfig, } from "./product-service.js";
 export { SelectedVariantService, SelectedVariantServiceDefinition, } from "./selected-variant-service.js";
 export { ProductListService, ProductsListServiceDefinition, loadProductsListServiceConfig, } from "./products-list-service.js";
-export { InventoryStatusType, SortType, ProductsListSearchService, ProductsListSearchServiceDefinition, loadProductsListSearchServiceConfig, parseUrlForProductsListSearch, convertUrlSortToSortType, } from "./products-list-search-service.js";
+export { InventoryStatusType, SortType, ProductsListSearchService, ProductsListSearchServiceDefinition, loadProductsListSearchServiceConfig, parseUrlToSearchOptions, convertUrlSortToSortType, } from "./products-list-search-service.js";

package/dist/services/products-list-search-service.d.ts

@@ -33,7 +33,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;
@@ -138,16 +138,75 @@ export declare const ProductsListSearchServiceDefinition: string & {
  */
 export declare function convertUrlSortToSortType(urlSort: string): SortType | null;
 /**
- * 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 declare function parseUrlForProductsListSearch(url: string, categoriesList: Category[], defaultSearchOptions?: productsV3.V3ProductSearch): Promise<{
+export declare function parseUrlToSearchOptions(url: string, categoriesList: Category[], defaultSearchOptions?: productsV3.V3ProductSearch): Promise<{
     searchOptions: productsV3.V3ProductSearch;
     initialSearchState: InitialSearchState;
 }>;
 /**
- * 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 declare function loadProductsListSearchServiceConfig(url: string): Promise<ProductsListSearchServiceConfig>;
+export declare function loadProductsListSearchServiceConfig(input: string | {
+    searchOptions: productsV3.V3ProductSearch;
+    initialSearchState: InitialSearchState;
+}): Promise<ProductsListSearchServiceConfig>;
 /**
  * Implementation of the Products List Search service
  */

package/dist/services/products-list-search-service.js

@@ -164,9 +164,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(url, categoriesList, defaultSearchOptions) {
+export async function parseUrlToSearchOptions(url, categoriesList, defaultSearchOptions) {
     const urlObj = new URL(url);
     const searchParams = urlObj.searchParams;
     // Get customizations for product option parsing
@@ -399,12 +423,52 @@ export async function parseUrlForProductsListSearch(url, categoriesList, default
     return { searchOptions, initialSearchState };
 }
 /**
- * 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) {
-    // Load categories using the categories service
-    const categoriesListConfig = await loadCategoriesListServiceConfig();
-    const { initialSearchState } = await parseUrlForProductsListSearch(url, categoriesListConfig.categories);
+export async function loadProductsListSearchServiceConfig(input) {
+    let 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()
         .find();

package/dist/services/products-list-service.d.ts

@@ -1,5 +1,6 @@
 import { type Signal } from "@wix/services-definitions/core-services/signals";
 import { productsV3 } from "@wix/stores";
+import { type InitialSearchState } from "./products-list-search-service.js";
 export declare const DEFAULT_QUERY_LIMIT = 100;
 /**
  * Configuration interface for the Products List service.
@@ -20,27 +21,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}>
@@ -59,23 +66,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: {
@@ -99,8 +114,26 @@ 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 declare function loadProductsListServiceConfig(searchOptions: productsV3.V3ProductSearch): Promise<ProductsListServiceConfig>;
+export declare function loadProductsListServiceConfig(input: string | {
+    searchOptions: productsV3.V3ProductSearch;
+    initialSearchState: InitialSearchState;
+}): Promise<ProductsListServiceConfig>;
 /**
  * Service definition for the Products List service.
  * This defines the reactive API contract for managing a list of products with search, pagination, and filtering capabilities.

package/dist/services/products-list-service.js

@@ -1,31 +1,39 @@
 import { defineService, implementService } from "@wix/services-definitions";
 import { SignalsServiceDefinition, } from "@wix/services-definitions/core-services/signals";
 import { productsV3, readOnlyVariantsV3 } from "@wix/stores";
+import { loadCategoriesListServiceConfig } from "./categories-list-service.js";
+import { parseUrlToSearchOptions } from "./products-list-search-service.js";
 export const DEFAULT_QUERY_LIMIT = 100;
 /**
  * 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}>
@@ -44,23 +52,31 @@ export const DEFAULT_QUERY_LIMIT = 100;
  * ```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: {
@@ -84,8 +100,34 @@ export const DEFAULT_QUERY_LIMIT = 100;
  *   );
  * }
  * ```
+ *
+  * @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) {
+export async function loadProductsListServiceConfig(input) {
+    let searchOptions;
+    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([
         fetchProducts(searchWithoutFilter),

package/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",