@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

package/dist/development/core/predictive-search/queries.mjs

@@ -0,0 +1,81 @@
+import { gql } from "../../graphql/graphql.mjs";
+
+//#region src/core/predictive-search/queries.ts
+const PRODUCT_FRAGMENT_NAME = "PredictiveSearchProductFragment";
+const COLLECTION_FRAGMENT_NAME = "PredictiveSearchCollectionFragment";
+const PAGE_FRAGMENT_NAME = "PredictiveSearchPageFragment";
+const ARTICLE_FRAGMENT_NAME = "PredictiveSearchArticleFragment";
+const QUERY_FRAGMENT_NAME = "PredictiveSearchQueryFragment";
+const PRODUCT_TYPE_NAME = "Product";
+const COLLECTION_TYPE_NAME = "Collection";
+const PAGE_TYPE_NAME = "Page";
+const ARTICLE_TYPE_NAME = "Article";
+const QUERY_TYPE_NAME = "SearchQuerySuggestion";
+const PRODUCT_CONTRACT = {
+	label: "product",
+	name: PRODUCT_FRAGMENT_NAME,
+	typeName: PRODUCT_TYPE_NAME
+};
+const COLLECTION_CONTRACT = {
+	label: "collection",
+	name: COLLECTION_FRAGMENT_NAME,
+	typeName: COLLECTION_TYPE_NAME
+};
+const PAGE_CONTRACT = {
+	label: "page",
+	name: PAGE_FRAGMENT_NAME,
+	typeName: PAGE_TYPE_NAME
+};
+const ARTICLE_CONTRACT = {
+	label: "article",
+	name: ARTICLE_FRAGMENT_NAME,
+	typeName: ARTICLE_TYPE_NAME
+};
+const QUERY_CONTRACT = {
+	label: "query",
+	name: QUERY_FRAGMENT_NAME,
+	typeName: QUERY_TYPE_NAME
+};
+const HYDROGEN_PRODUCT_FRAGMENT = gql(`fragment HydrogenPredictiveSearchProductFragment on Product{__typename id title handle trackingParameters selectedOrFirstAvailableVariant(selectedOptions:[]ignoreUnknownOptions:true caseInsensitiveMatch:true){id image{url altText width height}price{amount currencyCode}}}`);
+const HYDROGEN_COLLECTION_FRAGMENT = gql(`fragment HydrogenPredictiveSearchCollectionFragment on Collection{__typename id title handle image{url altText width height}trackingParameters}`);
+const HYDROGEN_PAGE_FRAGMENT = gql(`fragment HydrogenPredictiveSearchPageFragment on Page{__typename id title handle trackingParameters}`);
+const HYDROGEN_ARTICLE_FRAGMENT = gql(`fragment HydrogenPredictiveSearchArticleFragment on Article{__typename id title handle blog{handle}image{url altText width height}trackingParameters}`);
+const HYDROGEN_QUERY_FRAGMENT = gql(`fragment HydrogenPredictiveSearchQueryFragment on SearchQuerySuggestion{__typename text styledText trackingParameters}`);
+const PREDICTIVE_SEARCH_QUERY = gql(`query PredictiveSearch($country:CountryCode$language:LanguageCode$limit:Int$limitScope:PredictiveSearchLimitScope$term:String!$types:[PredictiveSearchType!]$searchableFields:[SearchableField!]$unavailableProducts:SearchUnavailableProductsType)@inContext(country:$country language:$language){predictiveSearch(limit:$limit limitScope:$limitScope query:$term types:$types searchableFields:$searchableFields unavailableProducts:$unavailableProducts){articles{...HydrogenPredictiveSearchArticleFragment ...${ARTICLE_FRAGMENT_NAME}}collections{...HydrogenPredictiveSearchCollectionFragment ...${COLLECTION_FRAGMENT_NAME}}pages{...HydrogenPredictiveSearchPageFragment ...${PAGE_FRAGMENT_NAME}}products{...HydrogenPredictiveSearchProductFragment ...${PRODUCT_FRAGMENT_NAME}}queries{...HydrogenPredictiveSearchQueryFragment ...${QUERY_FRAGMENT_NAME}}}}`, [
+	HYDROGEN_PRODUCT_FRAGMENT,
+	HYDROGEN_COLLECTION_FRAGMENT,
+	HYDROGEN_PAGE_FRAGMENT,
+	HYDROGEN_ARTICLE_FRAGMENT,
+	HYDROGEN_QUERY_FRAGMENT
+]);
+const DEFAULT_PRODUCT_FRAGMENT = gql(`fragment PredictiveSearchProductFragment on Product{id}`);
+const DEFAULT_COLLECTION_FRAGMENT = gql(`fragment PredictiveSearchCollectionFragment on Collection{id}`);
+const DEFAULT_PAGE_FRAGMENT = gql(`fragment PredictiveSearchPageFragment on Page{id}`);
+const DEFAULT_ARTICLE_FRAGMENT = gql(`fragment PredictiveSearchArticleFragment on Article{id}`);
+const DEFAULT_QUERY_FRAGMENT = gql(`fragment PredictiveSearchQueryFragment on SearchQuerySuggestion{text}`);
+function assertFragmentContract(fragment, contract) {
+	if (new RegExp(`fragment\\s+${contract.name}\\s+on\\s+${contract.typeName}`).test(fragment)) return;
+	throw new Error(`Predictive search ${contract.label} fragment must be named ${contract.name} and target ${contract.typeName}`);
+}
+function resolveFragments(fragments) {
+	if (fragments?.product) assertFragmentContract(fragments.product, PRODUCT_CONTRACT);
+	if (fragments?.collection) assertFragmentContract(fragments.collection, COLLECTION_CONTRACT);
+	if (fragments?.page) assertFragmentContract(fragments.page, PAGE_CONTRACT);
+	if (fragments?.article) assertFragmentContract(fragments.article, ARTICLE_CONTRACT);
+	if (fragments?.query) assertFragmentContract(fragments.query, QUERY_CONTRACT);
+	return [
+		fragments?.product ?? DEFAULT_PRODUCT_FRAGMENT,
+		fragments?.collection ?? DEFAULT_COLLECTION_FRAGMENT,
+		fragments?.page ?? DEFAULT_PAGE_FRAGMENT,
+		fragments?.article ?? DEFAULT_ARTICLE_FRAGMENT,
+		fragments?.query ?? DEFAULT_QUERY_FRAGMENT
+	];
+}
+function makePredictiveSearchQueries(options) {
+	return { predictiveSearch: gql(PREDICTIVE_SEARCH_QUERY, resolveFragments(options?.fragments)) };
+}
+const predictiveSearchQueries = makePredictiveSearchQueries();
+
+//#endregion
+export { makePredictiveSearchQueries, predictiveSearchQueries };
+//# sourceMappingURL=queries.mjs.map

package/dist/development/core/predictive-search/queries.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.mjs","names":[],"sources":["../../../../src/core/predictive-search/queries.ts"],"sourcesContent":["import {\n  gql,\n  type AnyStorefrontQueryString,\n  type ComposedSource,\n  type SourceOf,\n  type StorefrontQueryString,\n} from \"../../graphql\";\nimport type { InferResult, InferVariables } from \"../../graphql\";\n\nconst PRODUCT_FRAGMENT_NAME = \"PredictiveSearchProductFragment\";\nconst COLLECTION_FRAGMENT_NAME = \"PredictiveSearchCollectionFragment\";\nconst PAGE_FRAGMENT_NAME = \"PredictiveSearchPageFragment\";\nconst ARTICLE_FRAGMENT_NAME = \"PredictiveSearchArticleFragment\";\nconst QUERY_FRAGMENT_NAME = \"PredictiveSearchQueryFragment\";\n\nconst PRODUCT_TYPE_NAME = \"Product\";\nconst COLLECTION_TYPE_NAME = \"Collection\";\nconst PAGE_TYPE_NAME = \"Page\";\nconst ARTICLE_TYPE_NAME = \"Article\";\nconst QUERY_TYPE_NAME = \"SearchQuerySuggestion\";\n\ntype FragmentContract = {\n  readonly label: string;\n  readonly name: string;\n  readonly typeName: string;\n};\n\nconst PRODUCT_CONTRACT = {\n  label: \"product\",\n  name: PRODUCT_FRAGMENT_NAME,\n  typeName: PRODUCT_TYPE_NAME,\n} as const satisfies FragmentContract;\n\nconst COLLECTION_CONTRACT = {\n  label: \"collection\",\n  name: COLLECTION_FRAGMENT_NAME,\n  typeName: COLLECTION_TYPE_NAME,\n} as const satisfies FragmentContract;\n\nconst PAGE_CONTRACT = {\n  label: \"page\",\n  name: PAGE_FRAGMENT_NAME,\n  typeName: PAGE_TYPE_NAME,\n} as const satisfies FragmentContract;\n\nconst ARTICLE_CONTRACT = {\n  label: \"article\",\n  name: ARTICLE_FRAGMENT_NAME,\n  typeName: ARTICLE_TYPE_NAME,\n} as const satisfies FragmentContract;\n\nconst QUERY_CONTRACT = {\n  label: \"query\",\n  name: QUERY_FRAGMENT_NAME,\n  typeName: QUERY_TYPE_NAME,\n} as const satisfies FragmentContract;\n\nconst HYDROGEN_PRODUCT_FRAGMENT = gql(`\n  fragment HydrogenPredictiveSearchProductFragment on Product {\n    __typename\n    id\n    title\n    handle\n    trackingParameters\n    selectedOrFirstAvailableVariant(\n      selectedOptions: []\n      ignoreUnknownOptions: true\n      caseInsensitiveMatch: true\n    ) {\n      id\n      image {\n        url\n        altText\n        width\n        height\n      }\n      price {\n        amount\n        currencyCode\n      }\n    }\n  }\n`);\n\nconst HYDROGEN_COLLECTION_FRAGMENT = gql(`\n  fragment HydrogenPredictiveSearchCollectionFragment on Collection {\n    __typename\n    id\n    title\n    handle\n    image {\n      url\n      altText\n      width\n      height\n    }\n    trackingParameters\n  }\n`);\n\nconst HYDROGEN_PAGE_FRAGMENT = gql(`\n  fragment HydrogenPredictiveSearchPageFragment on Page {\n    __typename\n    id\n    title\n    handle\n    trackingParameters\n  }\n`);\n\nconst HYDROGEN_ARTICLE_FRAGMENT = gql(`\n  fragment HydrogenPredictiveSearchArticleFragment on Article {\n    __typename\n    id\n    title\n    handle\n    blog {\n      handle\n    }\n    image {\n      url\n      altText\n      width\n      height\n    }\n    trackingParameters\n  }\n`);\n\nconst HYDROGEN_QUERY_FRAGMENT = gql(`\n  fragment HydrogenPredictiveSearchQueryFragment on SearchQuerySuggestion {\n    __typename\n    text\n    styledText\n    trackingParameters\n  }\n`);\n\n// The consumer-overridable fragment spreads (e.g. PredictiveSearchProductFragment)\n// are interpolated on purpose: those fragments only exist at runtime, and the\n// gql.tada plugin skips documents containing interpolations instead of flagging\n// unknown fragments, while TypeScript still resolves the full literal source type.\n// The resolved fragments are composed in at runtime by `makePredictiveSearchQueries`.\nconst PREDICTIVE_SEARCH_QUERY = gql(\n  `query PredictiveSearch(\n    $country: CountryCode\n    $language: LanguageCode\n    $limit: Int\n    $limitScope: PredictiveSearchLimitScope\n    $term: String!\n    $types: [PredictiveSearchType!]\n    $searchableFields: [SearchableField!]\n    $unavailableProducts: SearchUnavailableProductsType\n  ) @inContext(country: $country, language: $language) {\n    predictiveSearch(\n      limit: $limit\n      limitScope: $limitScope\n      query: $term\n      types: $types\n      searchableFields: $searchableFields\n      unavailableProducts: $unavailableProducts\n    ) {\n      articles {\n        ...HydrogenPredictiveSearchArticleFragment\n        ...${ARTICLE_FRAGMENT_NAME}\n      }\n      collections {\n        ...HydrogenPredictiveSearchCollectionFragment\n        ...${COLLECTION_FRAGMENT_NAME}\n      }\n      pages {\n        ...HydrogenPredictiveSearchPageFragment\n        ...${PAGE_FRAGMENT_NAME}\n      }\n      products {\n        ...HydrogenPredictiveSearchProductFragment\n        ...${PRODUCT_FRAGMENT_NAME}\n      }\n      queries {\n        ...HydrogenPredictiveSearchQueryFragment\n        ...${QUERY_FRAGMENT_NAME}\n      }\n    }\n  }`,\n  [\n    HYDROGEN_PRODUCT_FRAGMENT,\n    HYDROGEN_COLLECTION_FRAGMENT,\n    HYDROGEN_PAGE_FRAGMENT,\n    HYDROGEN_ARTICLE_FRAGMENT,\n    HYDROGEN_QUERY_FRAGMENT,\n  ],\n);\n\nconst DEFAULT_PRODUCT_FRAGMENT = gql(`\n  fragment PredictiveSearchProductFragment on Product {\n    id\n  }\n`);\n\nconst DEFAULT_COLLECTION_FRAGMENT = gql(`\n  fragment PredictiveSearchCollectionFragment on Collection {\n    id\n  }\n`);\n\nconst DEFAULT_PAGE_FRAGMENT = gql(`\n  fragment PredictiveSearchPageFragment on Page {\n    id\n  }\n`);\n\nconst DEFAULT_ARTICLE_FRAGMENT = gql(`\n  fragment PredictiveSearchArticleFragment on Article {\n    id\n  }\n`);\n\nconst DEFAULT_QUERY_FRAGMENT = gql(`\n  fragment PredictiveSearchQueryFragment on SearchQuerySuggestion {\n    text\n  }\n`);\n\nexport type PredictiveSearchFragments = {\n  readonly product?: AnyStorefrontQueryString;\n  readonly collection?: AnyStorefrontQueryString;\n  readonly page?: AnyStorefrontQueryString;\n  readonly article?: AnyStorefrontQueryString;\n  readonly query?: AnyStorefrontQueryString;\n};\n\nexport type CreatePredictiveSearchQueriesOptions<\n  TFragments extends PredictiveSearchFragments = PredictiveSearchFragments,\n> = {\n  readonly fragments?: TFragments;\n};\n\ntype FragmentForOptions<\n  TOptions,\n  TKey extends keyof PredictiveSearchFragments,\n  TDefault extends AnyStorefrontQueryString,\n> = TOptions extends { readonly fragments: infer TFragments }\n  ? TFragments extends Record<TKey, infer TFragment extends AnyStorefrontQueryString>\n    ? TFragment\n    : TDefault\n  : TDefault;\n\ntype PredictiveSearchQueryFragmentsForOptions<TOptions> = [\n  FragmentForOptions<TOptions, \"product\", typeof DEFAULT_PRODUCT_FRAGMENT>,\n  FragmentForOptions<TOptions, \"collection\", typeof DEFAULT_COLLECTION_FRAGMENT>,\n  FragmentForOptions<TOptions, \"page\", typeof DEFAULT_PAGE_FRAGMENT>,\n  FragmentForOptions<TOptions, \"article\", typeof DEFAULT_ARTICLE_FRAGMENT>,\n  FragmentForOptions<TOptions, \"query\", typeof DEFAULT_QUERY_FRAGMENT>,\n];\n\ntype PredictiveSearchQuerySourceForOptions<TOptions> = ComposedSource<\n  SourceOf<typeof PREDICTIVE_SEARCH_QUERY>,\n  PredictiveSearchQueryFragmentsForOptions<TOptions>\n>;\n\ntype PredictiveSearchQueryForOptions<TOptions> = StorefrontQueryString<\n  InferResult<PredictiveSearchQuerySourceForOptions<TOptions>>,\n  InferVariables<PredictiveSearchQuerySourceForOptions<TOptions>>,\n  PredictiveSearchQuerySourceForOptions<TOptions>\n>;\n\nexport type PredictiveSearchQueriesForOptions<TOptions> = {\n  readonly predictiveSearch: PredictiveSearchQueryForOptions<TOptions>;\n};\n\nfunction assertFragmentContract(fragment: string, contract: FragmentContract): void {\n  const pattern = new RegExp(`fragment\\\\s+${contract.name}\\\\s+on\\\\s+${contract.typeName}`);\n  if (pattern.test(fragment)) return;\n\n  throw new Error(\n    `Predictive search ${contract.label} fragment must be named ${contract.name} and target ${contract.typeName}`,\n  );\n}\n\nfunction resolveFragments(fragments: PredictiveSearchFragments | undefined) {\n  if (fragments?.product) assertFragmentContract(fragments.product, PRODUCT_CONTRACT);\n  if (fragments?.collection) assertFragmentContract(fragments.collection, COLLECTION_CONTRACT);\n  if (fragments?.page) assertFragmentContract(fragments.page, PAGE_CONTRACT);\n  if (fragments?.article) assertFragmentContract(fragments.article, ARTICLE_CONTRACT);\n  if (fragments?.query) assertFragmentContract(fragments.query, QUERY_CONTRACT);\n\n  return [\n    fragments?.product ?? DEFAULT_PRODUCT_FRAGMENT,\n    fragments?.collection ?? DEFAULT_COLLECTION_FRAGMENT,\n    fragments?.page ?? DEFAULT_PAGE_FRAGMENT,\n    fragments?.article ?? DEFAULT_ARTICLE_FRAGMENT,\n    fragments?.query ?? DEFAULT_QUERY_FRAGMENT,\n  ] as const;\n}\n\nexport function makePredictiveSearchQueries<\n  const TOptions extends CreatePredictiveSearchQueriesOptions,\n>(options: TOptions): PredictiveSearchQueriesForOptions<TOptions>;\nexport function makePredictiveSearchQueries(): PredictiveSearchQueriesForOptions<undefined>;\nexport function makePredictiveSearchQueries(options?: CreatePredictiveSearchQueriesOptions) {\n  return {\n    predictiveSearch: gql(PREDICTIVE_SEARCH_QUERY, resolveFragments(options?.fragments)),\n  } as PredictiveSearchQueriesForOptions<typeof options>;\n}\n\nexport const predictiveSearchQueries = makePredictiveSearchQueries();\n"],"mappings":";;;AASA,MAAA,wBAAA;AACA,MAAA,2BAAA;AACA,MAAA,qBAAA;AACA,MAAA,wBAAA;AACA,MAAA,sBAAA;AAEA,MAAA,oBAAA;AACA,MAAA,uBAAA;AACA,MAAA,iBAAA;AACA,MAAA,oBAAA;AACA,MAAA,kBAAA;AAQA,MAAA,mBAAA;CACA,OAAA;CACA,MAAA;CACA,UAAA;CACA;AAEA,MAAA,sBAAA;CACA,OAAA;CACA,MAAA;CACA,UAAA;CACA;AAEA,MAAA,gBAAA;CACA,OAAA;CACA,MAAA;CACA,UAAA;CACA;AAEA,MAAA,mBAAA;CACA,OAAA;CACA,MAAA;CACA,UAAA;CACA;AAEA,MAAA,iBAAA;CACA,OAAA;CACA,MAAA;CACA,UAAA;CACA;AAEA,MAAA,4BAAA,IAAA,kRAyBA;AAEA,MAAA,+BAAA,IAAA,kJAcA;AAEA,MAAA,yBAAA,IAAA,uGAQA;AAEA,MAAA,4BAAA,IAAA,wJAiBA;AAEA,MAAA,0BAAA,IAAA,yHAOA;AAOA,MAAA,0BAAA,IACA,wfAoBW,sBAAwB,gEAIxB,yBAA2B,oDAI3B,mBAAqB,0DAIrB,sBAAwB,uDAIxB,oBAAsB,MAIjC;CACA;CACA;CACA;CACA;CACA;CACA,CACA;AAEA,MAAA,2BAAA,IAAA,0DAIA;AAEA,MAAA,8BAAA,IAAA,gEAIA;AAEA,MAAA,wBAAA,IAAA,oDAIA;AAEA,MAAA,2BAAA,IAAA,0DAIA;AAEA,MAAA,yBAAA,IAAA,wEAIA;AAiDA,SAAA,uBAAA,UAAA,UAAA;AAEA,KAAA,IADA,OAAA,eAAA,SAAA,KAAA,YAAA,SAAA,WACA,CAAA,KAAA,SAAA,CAAA;AAEA,OAAA,IAAA,MACA,qBAAA,SAAA,MAAA,0BAAA,SAAA,KAAA,cAAA,SAAA,WACA;;AAGA,SAAA,iBAAA,WAAA;AACA,KAAA,WAAA,QAAA,wBAAA,UAAA,SAAA,iBAAA;AACA,KAAA,WAAA,WAAA,wBAAA,UAAA,YAAA,oBAAA;AACA,KAAA,WAAA,KAAA,wBAAA,UAAA,MAAA,cAAA;AACA,KAAA,WAAA,QAAA,wBAAA,UAAA,SAAA,iBAAA;AACA,KAAA,WAAA,MAAA,wBAAA,UAAA,OAAA,eAAA;AAEA,QAAA;EACA,WAAA,WAAA;EACA,WAAA,cAAA;EACA,WAAA,QAAA;EACA,WAAA,WAAA;EACA,WAAA,SAAA;EACA;;AAOA,SAAA,4BAAA,SAAA;AACA,QAAA,EACA,kBAAA,IAAA,yBAAA,iBAAA,SAAA,UAAA,CAAA,EACA;;AAGA,MAAA,0BAAA,6BAAA"}

package/dist/development/core/predictive-search/search.d.mts

@@ -0,0 +1,32 @@
+import { PredictiveSearchLimitScope, PredictiveSearchType, SearchUnavailableProductsType, SearchableField } from "../../graphql/generated/storefront-api-types.mjs";
+import { AnyStorefrontQueryString, StorefrontQueryString } from "../../graphql/graphql.mjs";
+import { StorefrontClient } from "../../client/types.mjs";
+import { CreatePredictiveSearchQueriesOptions, PredictiveSearchQueriesForOptions, predictiveSearchQueries } from "./queries.mjs";
+
+//#region src/core/predictive-search/search.d.ts
+type PredictiveSearchGraphqlResult<TQuery extends AnyStorefrontQueryString> = TQuery extends StorefrontQueryString<infer TResult, infer _Variables, string> ? TResult : never;
+type PredictiveSearchItemsForQuery<TQuery extends AnyStorefrontQueryString> = NonNullable<PredictiveSearchGraphqlResult<TQuery> extends {
+  predictiveSearch?: (infer TItems) | null;
+} ? TItems : never>;
+type PredictiveSearchData<TItems = PredictiveSearchItemsForQuery<typeof predictiveSearchQueries.predictiveSearch>> = {
+  term: string;
+  total: number;
+  items: TItems;
+};
+type PredictiveSearchDataForQuery<TQuery extends AnyStorefrontQueryString> = PredictiveSearchData<PredictiveSearchItemsForQuery<TQuery>>;
+type PredictiveSearchDataForOptions<TOptions extends CreatePredictiveSearchQueriesOptions> = PredictiveSearchDataForQuery<PredictiveSearchQueriesForOptions<TOptions>["predictiveSearch"]>;
+type QueryPredictiveSearchOptions<TQuery extends AnyStorefrontQueryString = typeof predictiveSearchQueries.predictiveSearch> = {
+  storefrontClient: Pick<StorefrontClient, "graphql">;
+  term: string;
+  query?: TQuery;
+  limit?: number;
+  limitScope?: PredictiveSearchLimitScope;
+  types?: PredictiveSearchType[];
+  searchableFields?: SearchableField[];
+  unavailableProducts?: SearchUnavailableProductsType;
+  signal?: AbortSignal;
+};
+declare function queryPredictiveSearch<const TQuery extends AnyStorefrontQueryString = typeof predictiveSearchQueries.predictiveSearch>(options: QueryPredictiveSearchOptions<TQuery>): Promise<PredictiveSearchDataForQuery<TQuery>>;
+//#endregion
+export { PredictiveSearchData, PredictiveSearchDataForOptions, QueryPredictiveSearchOptions, queryPredictiveSearch };
+//# sourceMappingURL=search.d.mts.map

package/dist/development/core/predictive-search/search.mjs

@@ -0,0 +1,74 @@
+import { predictiveSearchQueries } from "./queries.mjs";
+
+//#region src/core/predictive-search/search.ts
+const MIN_PREDICTIVE_SEARCH_LIMIT = 1;
+const MAX_PREDICTIVE_SEARCH_LIMIT = 10;
+const DEFAULT_PREDICTIVE_SEARCH_LIMIT = 5;
+const DEFAULT_PREDICTIVE_SEARCH_LIMIT_SCOPE = "EACH";
+const DEFAULT_PREDICTIVE_SEARCH_UNAVAILABLE_PRODUCTS = "HIDE";
+function getEmptyPredictiveSearchResult(term = "") {
+	return {
+		term,
+		total: 0,
+		items: {
+			products: [],
+			collections: [],
+			pages: [],
+			articles: [],
+			queries: []
+		}
+	};
+}
+async function queryPredictiveSearch(options) {
+	return (await fetchPredictiveSearch(options)).data;
+}
+async function fetchPredictiveSearch({ storefrontClient, term, query, limit, limitScope = DEFAULT_PREDICTIVE_SEARCH_LIMIT_SCOPE, types, searchableFields, unavailableProducts = DEFAULT_PREDICTIVE_SEARCH_UNAVAILABLE_PRODUCTS, signal }) {
+	const trimmedTerm = term.trim();
+	if (!trimmedTerm) return {
+		data: getEmptyPredictiveSearchResult(trimmedTerm),
+		headers: new Headers()
+	};
+	const document = query ?? predictiveSearchQueries.predictiveSearch;
+	const graphql = storefrontClient.graphql;
+	const result = await graphql(document, {
+		variables: {
+			limit: clampPredictiveSearchLimit(limit),
+			limitScope,
+			term: trimmedTerm,
+			types,
+			searchableFields,
+			unavailableProducts
+		},
+		...signal ? { signal } : {}
+	});
+	if (result.errors) throw new Error(`Shopify API errors: ${formatGraphQLErrors(result.errors)}`);
+	const items = result.data?.predictiveSearch;
+	if (!items) throw new Error("No predictive search data returned from Shopify API");
+	return {
+		data: {
+			term: trimmedTerm,
+			total: countPredictiveSearchItems(items),
+			items
+		},
+		headers: result.headers
+	};
+}
+function clampPredictiveSearchLimit(limit) {
+	if (typeof limit !== "number") return 5;
+	if (!Number.isFinite(limit)) return 5;
+	return Math.min(10, Math.max(1, Math.trunc(limit)));
+}
+function countPredictiveSearchItems(items) {
+	if (!items || typeof items !== "object") return 0;
+	return Object.values(items).reduce((total, value) => {
+		if (!Array.isArray(value)) return total;
+		return total + value.length;
+	}, 0);
+}
+function formatGraphQLErrors(errors) {
+	return errors.map(({ message }) => message).join(", ");
+}
+
+//#endregion
+export { DEFAULT_PREDICTIVE_SEARCH_LIMIT_SCOPE, DEFAULT_PREDICTIVE_SEARCH_UNAVAILABLE_PRODUCTS, fetchPredictiveSearch, getEmptyPredictiveSearchResult, queryPredictiveSearch };
+//# sourceMappingURL=search.mjs.map

package/dist/development/core/predictive-search/search.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.mjs","names":[],"sources":["../../../../src/core/predictive-search/search.ts"],"sourcesContent":["import type { GraphQLFormattedError, StorefrontClient } from \"../../client\";\nimport type { AnyStorefrontQueryString, StorefrontQueryString } from \"../../graphql\";\nimport type {\n  PredictiveSearchLimitScope,\n  PredictiveSearchType,\n  SearchUnavailableProductsType,\n  SearchableField,\n} from \"../../graphql/generated/storefront-api-types\";\nimport {\n  predictiveSearchQueries,\n  type CreatePredictiveSearchQueriesOptions,\n  type PredictiveSearchQueriesForOptions,\n} from \"./queries\";\n\nexport const MIN_PREDICTIVE_SEARCH_LIMIT = 1;\nexport const MAX_PREDICTIVE_SEARCH_LIMIT = 10;\nexport const DEFAULT_PREDICTIVE_SEARCH_LIMIT = 5;\nexport const DEFAULT_PREDICTIVE_SEARCH_LIMIT_SCOPE = \"EACH\" satisfies PredictiveSearchLimitScope;\nexport const DEFAULT_PREDICTIVE_SEARCH_UNAVAILABLE_PRODUCTS =\n  \"HIDE\" satisfies SearchUnavailableProductsType;\n\ntype PredictiveSearchGraphqlResult<TQuery extends AnyStorefrontQueryString> =\n  TQuery extends StorefrontQueryString<infer TResult, infer _Variables, string> ? TResult : never;\n\ntype PredictiveSearchItemsForQuery<TQuery extends AnyStorefrontQueryString> = NonNullable<\n  PredictiveSearchGraphqlResult<TQuery> extends { predictiveSearch?: (infer TItems) | null }\n    ? TItems\n    : never\n>;\n\nexport type PredictiveSearchData<\n  TItems = PredictiveSearchItemsForQuery<typeof predictiveSearchQueries.predictiveSearch>,\n> = {\n  term: string;\n  total: number;\n  items: TItems;\n};\n\nexport type PredictiveSearchDataForQuery<TQuery extends AnyStorefrontQueryString> =\n  PredictiveSearchData<PredictiveSearchItemsForQuery<TQuery>>;\n\nexport type PredictiveSearchDataForOptions<TOptions extends CreatePredictiveSearchQueriesOptions> =\n  PredictiveSearchDataForQuery<PredictiveSearchQueriesForOptions<TOptions>[\"predictiveSearch\"]>;\n\nexport type QueryPredictiveSearchOptions<\n  TQuery extends AnyStorefrontQueryString = typeof predictiveSearchQueries.predictiveSearch,\n> = {\n  storefrontClient: Pick<StorefrontClient, \"graphql\">;\n  term: string;\n  query?: TQuery;\n  limit?: number;\n  limitScope?: PredictiveSearchLimitScope;\n  types?: PredictiveSearchType[];\n  searchableFields?: SearchableField[];\n  unavailableProducts?: SearchUnavailableProductsType;\n  signal?: AbortSignal;\n};\n\ntype FetchPredictiveSearchResult<TQuery extends AnyStorefrontQueryString> = {\n  data: PredictiveSearchDataForQuery<TQuery>;\n  headers: Headers;\n};\n\ntype PredictiveSearchQueryDocument = AnyStorefrontQueryString;\n\ntype PredictiveSearchVariables = {\n  term: string;\n  limit: number;\n  limitScope: PredictiveSearchLimitScope;\n  types: PredictiveSearchType[] | undefined;\n  searchableFields: SearchableField[] | undefined;\n  unavailableProducts: SearchUnavailableProductsType;\n};\n\ntype PredictiveSearchQueryResult<TItems> = {\n  data: { predictiveSearch?: TItems | null } | null;\n  errors?: GraphQLFormattedError[];\n  headers: Headers;\n};\n\ntype PredictiveSearchGraphql<TItems> = (\n  query: PredictiveSearchQueryDocument,\n  options: { variables: PredictiveSearchVariables; signal?: AbortSignal },\n) => Promise<PredictiveSearchQueryResult<TItems>>;\n\nexport function getEmptyPredictiveSearchResult(term = \"\"): PredictiveSearchData {\n  return {\n    term,\n    total: 0,\n    items: {\n      products: [],\n      collections: [],\n      pages: [],\n      articles: [],\n      queries: [],\n    },\n  };\n}\n\nexport async function queryPredictiveSearch<\n  const TQuery extends AnyStorefrontQueryString = typeof predictiveSearchQueries.predictiveSearch,\n>(options: QueryPredictiveSearchOptions<TQuery>): Promise<PredictiveSearchDataForQuery<TQuery>> {\n  const result = await fetchPredictiveSearch(options);\n  return result.data;\n}\n\nexport async function fetchPredictiveSearch<\n  const TQuery extends AnyStorefrontQueryString = typeof predictiveSearchQueries.predictiveSearch,\n>({\n  storefrontClient,\n  term,\n  query,\n  limit,\n  limitScope = DEFAULT_PREDICTIVE_SEARCH_LIMIT_SCOPE,\n  types,\n  searchableFields,\n  unavailableProducts = DEFAULT_PREDICTIVE_SEARCH_UNAVAILABLE_PRODUCTS,\n  signal,\n}: QueryPredictiveSearchOptions<TQuery>): Promise<FetchPredictiveSearchResult<TQuery>> {\n  const trimmedTerm = term.trim();\n  if (!trimmedTerm) {\n    return {\n      data: getEmptyPredictiveSearchResult(\n        trimmedTerm,\n      ) as unknown as PredictiveSearchDataForQuery<TQuery>,\n      headers: new Headers(),\n    };\n  }\n\n  const document = query ?? predictiveSearchQueries.predictiveSearch;\n  const graphql = storefrontClient.graphql as PredictiveSearchGraphql<\n    PredictiveSearchItemsForQuery<TQuery>\n  >;\n  const result = await graphql(document, {\n    variables: {\n      limit: clampPredictiveSearchLimit(limit),\n      limitScope,\n      term: trimmedTerm,\n      types,\n      searchableFields,\n      unavailableProducts,\n    },\n    ...(signal ? { signal } : {}),\n  });\n\n  if (result.errors) {\n    throw new Error(`Shopify API errors: ${formatGraphQLErrors(result.errors)}`);\n  }\n\n  const items = result.data?.predictiveSearch;\n  if (!items) {\n    throw new Error(\"No predictive search data returned from Shopify API\");\n  }\n\n  return {\n    data: {\n      term: trimmedTerm,\n      total: countPredictiveSearchItems(items),\n      items,\n    } as PredictiveSearchDataForQuery<TQuery>,\n    headers: result.headers,\n  };\n}\n\nfunction clampPredictiveSearchLimit(limit: number | undefined): number {\n  if (typeof limit !== \"number\") return DEFAULT_PREDICTIVE_SEARCH_LIMIT;\n  if (!Number.isFinite(limit)) return DEFAULT_PREDICTIVE_SEARCH_LIMIT;\n\n  const integerLimit = Math.trunc(limit);\n  return Math.min(MAX_PREDICTIVE_SEARCH_LIMIT, Math.max(MIN_PREDICTIVE_SEARCH_LIMIT, integerLimit));\n}\n\nfunction countPredictiveSearchItems(items: unknown): number {\n  if (!items || typeof items !== \"object\") return 0;\n\n  return Object.values(items).reduce((total, value) => {\n    if (!Array.isArray(value)) return total;\n    return total + value.length;\n  }, 0);\n}\n\nfunction formatGraphQLErrors(errors: GraphQLFormattedError[]): string {\n  return errors.map(({ message }) => message).join(\", \");\n}\n"],"mappings":";;;AAcA,MAAa,8BAA8B;AAC3C,MAAa,8BAA8B;AAC3C,MAAa,kCAAkC;AAC/C,MAAa,wCAAwC;AACrD,MAAa,iDACX;AAkEF,SAAgB,+BAA+B,OAAO,IAA0B;AAC9E,QAAO;EACL;EACA,OAAO;EACP,OAAO;GACL,UAAU,EAAE;GACZ,aAAa,EAAE;GACf,OAAO,EAAE;GACT,UAAU,EAAE;GACZ,SAAS,EAAE;GACZ;EACF;;AAGH,eAAsB,sBAEpB,SAA8F;AAE9F,SAAO,MADc,sBAAsB,QAAQ,EACrC;;AAGhB,eAAsB,sBAEpB,EACA,kBACA,MACA,OACA,OACA,aAAa,uCACb,OACA,kBACA,sBAAsB,gDACtB,UACqF;CACrF,MAAM,cAAc,KAAK,MAAM;AAC/B,KAAI,CAAC,YACH,QAAO;EACL,MAAM,+BACJ,YACD;EACD,SAAS,IAAI,SAAS;EACvB;CAGH,MAAM,WAAW,SAAS,wBAAwB;CAClD,MAAM,UAAU,iBAAiB;CAGjC,MAAM,SAAS,MAAM,QAAQ,UAAU;EACrC,WAAW;GACT,OAAO,2BAA2B,MAAM;GACxC;GACA,MAAM;GACN;GACA;GACA;GACD;EACD,GAAI,SAAS,EAAE,QAAQ,GAAG,EAAE;EAC7B,CAAC;AAEF,KAAI,OAAO,OACT,OAAM,IAAI,MAAM,uBAAuB,oBAAoB,OAAO,OAAO,GAAG;CAG9E,MAAM,QAAQ,OAAO,MAAM;AAC3B,KAAI,CAAC,MACH,OAAM,IAAI,MAAM,sDAAsD;AAGxE,QAAO;EACL,MAAM;GACJ,MAAM;GACN,OAAO,2BAA2B,MAAM;GACxC;GACD;EACD,SAAS,OAAO;EACjB;;AAGH,SAAS,2BAA2B,OAAmC;AACrE,KAAI,OAAO,UAAU,SAAU;AAC/B,KAAI,CAAC,OAAO,SAAS,MAAM,CAAE;AAG7B,QAAO,KAAK,QAAiC,KAAK,OAD7B,KAAK,MAAM,MAC+D,CAAC,CAAC;;AAGnG,SAAS,2BAA2B,OAAwB;AAC1D,KAAI,CAAC,SAAS,OAAO,UAAU,SAAU,QAAO;AAEhD,QAAO,OAAO,OAAO,MAAM,CAAC,QAAQ,OAAO,UAAU;AACnD,MAAI,CAAC,MAAM,QAAQ,MAAM,CAAE,QAAO;AAClC,SAAO,QAAQ,MAAM;IACpB,EAAE;;AAGP,SAAS,oBAAoB,QAAyC;AACpE,QAAO,OAAO,KAAK,EAAE,cAAc,QAAQ,CAAC,KAAK,KAAK"}

package/dist/development/core/predictive-search/server-handlers.d.mts

@@ -0,0 +1,36 @@
+import { PredictiveSearchLimitScope, PredictiveSearchType, SearchUnavailableProductsType, SearchableField } from "../../graphql/generated/storefront-api-types.mjs";
+import { CallableRouteHandler, ShopifyRouteError, ShopifyRouteErrorResult, ShopifyRouteJsonResult } from "../request-routing/route-types.mjs";
+import { CreatePredictiveSearchQueriesOptions, PredictiveSearchQueriesForOptions } from "./queries.mjs";
+import { PredictiveSearchDataForOptions, QueryPredictiveSearchOptions } from "./search.mjs";
+import { PREDICTIVE_SEARCH_GET_METHOD } from "./constants.mjs";
+
+//#region src/core/predictive-search/server-handlers.d.ts
+declare const predictiveSearchServerHandlersQuery: unique symbol;
+type PredictiveSearchHandlerContext = {
+  request: Request;
+  storefrontClient: QueryPredictiveSearchOptions["storefrontClient"];
+};
+type PredictiveSearchGetData<TData = PredictiveSearchDataForOptions<{}>> = TData;
+type PredictiveSearchGetResult<TData = PredictiveSearchDataForOptions<{}>> = ShopifyRouteJsonResult<PredictiveSearchGetData<TData>> | ShopifyRouteErrorResult<PredictiveSearchError>;
+type PredictiveSearchErrorCode = "invalid_predictive_search_request";
+type PredictiveSearchError = ShopifyRouteError & {
+  code: PredictiveSearchErrorCode;
+};
+type PredictiveSearchGetHandler<TData = PredictiveSearchDataForOptions<{}>> = CallableRouteHandler<PredictiveSearchHandlerContext, PredictiveSearchGetResult<TData>, string, typeof PREDICTIVE_SEARCH_GET_METHOD>;
+type PredictiveSearchServerHandlers<TOptions extends CreatePredictiveSearchServerHandlersOptions = {}, TData = PredictiveSearchDataForOptions<TOptions>> = {
+  readonly [predictiveSearchServerHandlersQuery]: PredictiveSearchQueriesForOptions<TOptions>["predictiveSearch"];
+  get: PredictiveSearchGetHandler<TData>;
+};
+type CreatePredictiveSearchServerHandlersOptions = CreatePredictiveSearchQueriesOptions & {
+  path?: string;
+  limit?: number;
+  limitScope?: PredictiveSearchLimitScope;
+  types?: PredictiveSearchType[];
+  searchableFields?: SearchableField[];
+  unavailableProducts?: SearchUnavailableProductsType;
+};
+declare function createPredictiveSearchServerHandlers(): PredictiveSearchServerHandlers;
+declare function createPredictiveSearchServerHandlers<const TOptions extends CreatePredictiveSearchServerHandlersOptions>(options: TOptions): PredictiveSearchServerHandlers<TOptions>;
+//#endregion
+export { CreatePredictiveSearchServerHandlersOptions, createPredictiveSearchServerHandlers };
+//# sourceMappingURL=server-handlers.d.mts.map

package/dist/development/core/predictive-search/server-handlers.mjs

@@ -0,0 +1,113 @@
+import { createProxyResponseHeaders } from "../request-routing/interceptors/proxy.mjs";
+import { createCallableRouteHandler } from "../request-routing/registered-routes.mjs";
+import { PREDICTIVE_SEARCH_API_PATH } from "./constants.mjs";
+import { makePredictiveSearchQueries, predictiveSearchQueries } from "./queries.mjs";
+import { DEFAULT_PREDICTIVE_SEARCH_LIMIT_SCOPE, DEFAULT_PREDICTIVE_SEARCH_UNAVAILABLE_PRODUCTS, fetchPredictiveSearch } from "./search.mjs";
+
+//#region src/core/predictive-search/server-handlers.ts
+const predictiveSearchServerHandlersQuery = Symbol("hydrogen.predictiveSearchQuery");
+const VALID_LIMIT_SCOPES = ["ALL", "EACH"];
+const VALID_PREDICTIVE_SEARCH_TYPES = [
+	"ARTICLE",
+	"COLLECTION",
+	"PAGE",
+	"PRODUCT",
+	"QUERY"
+];
+const VALID_SEARCHABLE_FIELDS = [
+	"AUTHOR",
+	"BODY",
+	"PRODUCT_TYPE",
+	"TAG",
+	"TITLE",
+	"VARIANTS_BARCODE",
+	"VARIANTS_SKU",
+	"VARIANTS_TITLE",
+	"VENDOR"
+];
+const VALID_UNAVAILABLE_PRODUCTS = [
+	"HIDE",
+	"LAST",
+	"SHOW"
+];
+function createPredictiveSearchServerHandlers(options = {}) {
+	const queries = options.fragments ? makePredictiveSearchQueries(options) : predictiveSearchQueries;
+	const handlers = { get: createCallableRouteHandler(options.path ?? "/api/predictive-search", "GET", (context) => handleGet(context, options, queries)) };
+	Object.defineProperty(handlers, predictiveSearchServerHandlersQuery, { value: queries.predictiveSearch });
+	return handlers;
+}
+async function handleGet({ request, storefrontClient }, options, queries) {
+	let searchOptions;
+	try {
+		searchOptions = parsePredictiveSearchRequest(request, options);
+	} catch (error) {
+		return errorResult(getErrorMessage(error, "Invalid predictive search request"));
+	}
+	try {
+		const result = await fetchPredictiveSearch({
+			storefrontClient,
+			query: queries.predictiveSearch,
+			...searchOptions
+		});
+		return {
+			type: "json",
+			data: result.data,
+			headers: createProxyResponseHeaders(result.headers)
+		};
+	} catch (error) {
+		return errorResult(getErrorMessage(error, "Predictive search request failed"));
+	}
+}
+function parsePredictiveSearchRequest(request, options) {
+	const searchParams = new URL(request.url).searchParams;
+	return {
+		term: searchParams.get("q") ?? "",
+		limit: parseLimit(searchParams, options),
+		limitScope: parseOne(searchParams, "limitScope", VALID_LIMIT_SCOPES) ?? options.limitScope ?? "EACH",
+		types: parseMany(searchParams, "types", VALID_PREDICTIVE_SEARCH_TYPES) ?? options.types,
+		searchableFields: parseMany(searchParams, "searchableFields", VALID_SEARCHABLE_FIELDS) ?? options.searchableFields,
+		unavailableProducts: parseOne(searchParams, "unavailableProducts", VALID_UNAVAILABLE_PRODUCTS) ?? options.unavailableProducts ?? "HIDE"
+	};
+}
+function parseLimit(searchParams, options) {
+	const rawLimit = searchParams.get("limit");
+	if (rawLimit === null) return options.limit ?? 5;
+	return Number(rawLimit);
+}
+function parseOne(searchParams, name, allowedValues) {
+	const value = searchParams.get(name);
+	if (value === null || value === "") return void 0;
+	if (isAllowedValue(value, allowedValues)) return value;
+	throw new Error(`Invalid ${name} value "${value}".`);
+}
+function parseMany(searchParams, name, allowedValues) {
+	const values = splitParamValues(searchParams, name);
+	if (values.length === 0) return void 0;
+	return values.map((value) => parseAllowedValue(name, value, allowedValues));
+}
+function splitParamValues(searchParams, name) {
+	return searchParams.getAll(name).flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean);
+}
+function parseAllowedValue(name, value, allowedValues) {
+	if (isAllowedValue(value, allowedValues)) return value;
+	throw new Error(`Invalid ${name} value "${value}".`);
+}
+function isAllowedValue(value, allowedValues) {
+	return allowedValues.some((allowedValue) => allowedValue === value);
+}
+function errorResult(message) {
+	return {
+		type: "error",
+		error: {
+			code: "invalid_predictive_search_request",
+			message
+		}
+	};
+}
+function getErrorMessage(error, fallback) {
+	return error instanceof Error ? error.message : fallback;
+}
+
+//#endregion
+export { createPredictiveSearchServerHandlers };
+//# sourceMappingURL=server-handlers.mjs.map

package/dist/development/core/predictive-search/server-handlers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-handlers.mjs","names":[],"sources":["../../../../src/core/predictive-search/server-handlers.ts"],"sourcesContent":["import type {\n  PredictiveSearchLimitScope,\n  PredictiveSearchType,\n  SearchUnavailableProductsType,\n  SearchableField,\n} from \"../../graphql/generated/storefront-api-types\";\nimport { createProxyResponseHeaders } from \"../request-routing/interceptors/proxy\";\nimport type {\n  CallableRouteHandler,\n  ShopifyRouteError,\n  ShopifyRouteErrorResult,\n  ShopifyRouteJsonResult,\n} from \"../request-routing/registered-routes\";\nimport { createCallableRouteHandler } from \"../request-routing/registered-routes\";\nimport { PREDICTIVE_SEARCH_API_PATH, PREDICTIVE_SEARCH_GET_METHOD } from \"./constants\";\nimport {\n  makePredictiveSearchQueries,\n  predictiveSearchQueries,\n  type CreatePredictiveSearchQueriesOptions,\n  type PredictiveSearchQueriesForOptions,\n} from \"./queries\";\nimport {\n  DEFAULT_PREDICTIVE_SEARCH_LIMIT,\n  DEFAULT_PREDICTIVE_SEARCH_LIMIT_SCOPE,\n  DEFAULT_PREDICTIVE_SEARCH_UNAVAILABLE_PRODUCTS,\n  fetchPredictiveSearch,\n  type PredictiveSearchDataForOptions,\n  type QueryPredictiveSearchOptions,\n} from \"./search\";\n\nconst predictiveSearchServerHandlersQuery: unique symbol = Symbol(\"hydrogen.predictiveSearchQuery\");\n\nconst VALID_LIMIT_SCOPES: readonly PredictiveSearchLimitScope[] = [\"ALL\", \"EACH\"];\nconst VALID_PREDICTIVE_SEARCH_TYPES: readonly PredictiveSearchType[] = [\n  \"ARTICLE\",\n  \"COLLECTION\",\n  \"PAGE\",\n  \"PRODUCT\",\n  \"QUERY\",\n];\nconst VALID_SEARCHABLE_FIELDS: readonly SearchableField[] = [\n  \"AUTHOR\",\n  \"BODY\",\n  \"PRODUCT_TYPE\",\n  \"TAG\",\n  \"TITLE\",\n  \"VARIANTS_BARCODE\",\n  \"VARIANTS_SKU\",\n  \"VARIANTS_TITLE\",\n  \"VENDOR\",\n];\nconst VALID_UNAVAILABLE_PRODUCTS: readonly SearchUnavailableProductsType[] = [\n  \"HIDE\",\n  \"LAST\",\n  \"SHOW\",\n];\n\ntype PredictiveSearchHandlerContext = {\n  request: Request;\n  storefrontClient: QueryPredictiveSearchOptions[\"storefrontClient\"];\n};\n\ntype PredictiveSearchGetData<TData = PredictiveSearchDataForOptions<{}>> = TData;\ntype PredictiveSearchGetResult<TData = PredictiveSearchDataForOptions<{}>> =\n  | ShopifyRouteJsonResult<PredictiveSearchGetData<TData>>\n  | ShopifyRouteErrorResult<PredictiveSearchError>;\n\ntype PredictiveSearchErrorCode = \"invalid_predictive_search_request\";\ntype PredictiveSearchError = ShopifyRouteError & {\n  code: PredictiveSearchErrorCode;\n};\n\ntype PredictiveSearchGetHandler<TData = PredictiveSearchDataForOptions<{}>> = CallableRouteHandler<\n  PredictiveSearchHandlerContext,\n  PredictiveSearchGetResult<TData>,\n  string,\n  typeof PREDICTIVE_SEARCH_GET_METHOD\n>;\n\ntype PredictiveSearchServerHandlers<\n  TOptions extends CreatePredictiveSearchServerHandlersOptions = {},\n  TData = PredictiveSearchDataForOptions<TOptions>,\n> = {\n  readonly [predictiveSearchServerHandlersQuery]: PredictiveSearchQueriesForOptions<TOptions>[\"predictiveSearch\"];\n  get: PredictiveSearchGetHandler<TData>;\n};\n\nexport type CreatePredictiveSearchServerHandlersOptions = CreatePredictiveSearchQueriesOptions & {\n  path?: string;\n  limit?: number;\n  limitScope?: PredictiveSearchLimitScope;\n  types?: PredictiveSearchType[];\n  searchableFields?: SearchableField[];\n  unavailableProducts?: SearchUnavailableProductsType;\n};\n\nexport function createPredictiveSearchServerHandlers(): PredictiveSearchServerHandlers;\nexport function createPredictiveSearchServerHandlers<\n  const TOptions extends CreatePredictiveSearchServerHandlersOptions,\n>(options: TOptions): PredictiveSearchServerHandlers<TOptions>;\nexport function createPredictiveSearchServerHandlers(\n  options: CreatePredictiveSearchServerHandlersOptions = {},\n): PredictiveSearchServerHandlers<CreatePredictiveSearchServerHandlersOptions> {\n  const queries = options.fragments\n    ? makePredictiveSearchQueries(options)\n    : predictiveSearchQueries;\n  const handler = createCallableRouteHandler(\n    options.path ?? PREDICTIVE_SEARCH_API_PATH,\n    PREDICTIVE_SEARCH_GET_METHOD,\n    (context: PredictiveSearchHandlerContext) => handleGet(context, options, queries),\n  );\n  const handlers = {\n    get: handler,\n  } as PredictiveSearchServerHandlers<CreatePredictiveSearchServerHandlersOptions>;\n\n  Object.defineProperty(handlers, predictiveSearchServerHandlersQuery, {\n    value: queries.predictiveSearch,\n  });\n  return handlers;\n}\n\nasync function handleGet(\n  { request, storefrontClient }: PredictiveSearchHandlerContext,\n  options: CreatePredictiveSearchServerHandlersOptions,\n  queries: PredictiveSearchQueriesForOptions<CreatePredictiveSearchServerHandlersOptions>,\n): Promise<PredictiveSearchGetResult> {\n  let searchOptions: ParsedPredictiveSearchRequest;\n  try {\n    searchOptions = parsePredictiveSearchRequest(request, options);\n  } catch (error) {\n    return errorResult(getErrorMessage(error, \"Invalid predictive search request\"));\n  }\n\n  try {\n    const result = await fetchPredictiveSearch({\n      storefrontClient,\n      query: queries.predictiveSearch,\n      ...searchOptions,\n    });\n    return {\n      type: \"json\",\n      data: result.data,\n      headers: createProxyResponseHeaders(result.headers),\n    };\n  } catch (error) {\n    return errorResult(getErrorMessage(error, \"Predictive search request failed\"));\n  }\n}\n\ntype ParsedPredictiveSearchRequest = Omit<\n  QueryPredictiveSearchOptions,\n  \"storefrontClient\" | \"query\" | \"signal\"\n>;\n\nfunction parsePredictiveSearchRequest(\n  request: Request,\n  options: CreatePredictiveSearchServerHandlersOptions,\n): ParsedPredictiveSearchRequest {\n  const searchParams = new URL(request.url).searchParams;\n  return {\n    term: searchParams.get(\"q\") ?? \"\",\n    limit: parseLimit(searchParams, options),\n    limitScope:\n      parseOne(searchParams, \"limitScope\", VALID_LIMIT_SCOPES) ??\n      options.limitScope ??\n      DEFAULT_PREDICTIVE_SEARCH_LIMIT_SCOPE,\n    types: parseMany(searchParams, \"types\", VALID_PREDICTIVE_SEARCH_TYPES) ?? options.types,\n    searchableFields:\n      parseMany(searchParams, \"searchableFields\", VALID_SEARCHABLE_FIELDS) ??\n      options.searchableFields,\n    unavailableProducts:\n      parseOne(searchParams, \"unavailableProducts\", VALID_UNAVAILABLE_PRODUCTS) ??\n      options.unavailableProducts ??\n      DEFAULT_PREDICTIVE_SEARCH_UNAVAILABLE_PRODUCTS,\n  };\n}\n\nfunction parseLimit(\n  searchParams: URLSearchParams,\n  options: CreatePredictiveSearchServerHandlersOptions,\n): number {\n  const rawLimit = searchParams.get(\"limit\");\n  if (rawLimit === null) return options.limit ?? DEFAULT_PREDICTIVE_SEARCH_LIMIT;\n  return Number(rawLimit);\n}\n\nfunction parseOne<TValue extends string>(\n  searchParams: URLSearchParams,\n  name: string,\n  allowedValues: readonly TValue[],\n): TValue | undefined {\n  const value = searchParams.get(name);\n  if (value === null || value === \"\") return undefined;\n  if (isAllowedValue(value, allowedValues)) return value;\n  throw new Error(`Invalid ${name} value \"${value}\".`);\n}\n\nfunction parseMany<TValue extends string>(\n  searchParams: URLSearchParams,\n  name: string,\n  allowedValues: readonly TValue[],\n): TValue[] | undefined {\n  const values = splitParamValues(searchParams, name);\n  if (values.length === 0) return undefined;\n  return values.map((value) => parseAllowedValue(name, value, allowedValues));\n}\n\nfunction splitParamValues(searchParams: URLSearchParams, name: string): string[] {\n  return searchParams\n    .getAll(name)\n    .flatMap((value) => value.split(\",\"))\n    .map((value) => value.trim())\n    .filter(Boolean);\n}\n\nfunction parseAllowedValue<TValue extends string>(\n  name: string,\n  value: string,\n  allowedValues: readonly TValue[],\n): TValue {\n  if (isAllowedValue(value, allowedValues)) return value;\n  throw new Error(`Invalid ${name} value \"${value}\".`);\n}\n\nfunction isAllowedValue<TValue extends string>(\n  value: string,\n  allowedValues: readonly TValue[],\n): value is TValue {\n  return allowedValues.some((allowedValue) => allowedValue === value);\n}\n\nfunction errorResult(message: string): ShopifyRouteErrorResult<PredictiveSearchError> {\n  return {\n    type: \"error\",\n    error: {\n      code: \"invalid_predictive_search_request\",\n      message,\n    },\n  };\n}\n\nfunction getErrorMessage(error: unknown, fallback: string): string {\n  return error instanceof Error ? error.message : fallback;\n}\n"],"mappings":"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"}

package/dist/development/core/predictive-search/store.d.mts

@@ -0,0 +1,44 @@
+import { PredictiveSearchLimitScope, PredictiveSearchType, SearchUnavailableProductsType, SearchableField } from "../../graphql/generated/storefront-api-types.mjs";
+import { PredictiveSearchData } from "./search.mjs";
+
+//#region src/core/predictive-search/store.d.ts
+/** Lifecycle state for the predictive search client store. */
+type PredictiveSearchStatus = "idle" | "loading" | "success" | "error";
+/** Current predictive search snapshot exposed to UI bindings. */
+type PredictiveSearchState<TData extends PredictiveSearchData = PredictiveSearchData> = {
+  /** Latest trimmed search term known to the store. */term: string; /** Request lifecycle state for the current term. */
+  status: PredictiveSearchStatus; /** Predictive search data for the current term, or an empty result while idle. */
+  result: TData; /** Error message for the latest failed request, or null when there is no active error. */
+  error: string | null;
+};
+/** Options for creating a framework-neutral predictive search client store. */
+type CreatePredictiveSearchStoreOptions = {
+  /**
+   * Same-origin JSON endpoint used for browser predictive-search requests.
+   *
+   * The endpoint must return JSON matching the data payload from
+   * `await predictiveSearchHandlers.get(...)`.
+   */
+  predictiveSearchEndpoint?: string; /** Delay before sending a request after the term changes. */
+  debounceInMs?: number; /** Minimum trimmed term length required before searching. */
+  minTermLength?: number; /** Fetch implementation, injectable for tests and non-browser runtimes. */
+  fetch?: typeof globalThis.fetch; /** Maximum result count requested from the Storefront API. */
+  limit?: number; /** Whether `limit` applies to each result type or all result types combined. */
+  limitScope?: PredictiveSearchLimitScope; /** Storefront API result types to include in predictive search. */
+  types?: PredictiveSearchType[]; /** Storefront API fields to search. */
+  searchableFields?: SearchableField[]; /** Storefront API unavailable-product behavior. */
+  unavailableProducts?: SearchUnavailableProductsType;
+};
+/** Framework-neutral predictive search store used by UI bindings. */
+type PredictiveSearchStore<TData extends PredictiveSearchData = PredictiveSearchData> = {
+  /** Reactivates store updates after destroy(). */connect(): void; /** Returns the current predictive search state snapshot. */
+  getState(): PredictiveSearchState<TData>; /** Subscribes to state changes and returns an unsubscribe callback. */
+  subscribe(listener: (state: PredictiveSearchState<TData>) => void): () => void; /** Searches for a term using the configured debounce and request lifecycle. */
+  search(term: string): Promise<void>; /** Cancels pending work and resets the store to an empty state. */
+  clear(): void; /** Cancels pending work and pauses store updates until reconnect. */
+  destroy(): void;
+};
+declare function createPredictiveSearchStore<TData extends PredictiveSearchData = PredictiveSearchData>(options?: CreatePredictiveSearchStoreOptions): PredictiveSearchStore<TData>;
+//#endregion
+export { CreatePredictiveSearchStoreOptions, PredictiveSearchState, PredictiveSearchStatus, PredictiveSearchStore, createPredictiveSearchStore };
+//# sourceMappingURL=store.d.mts.map