@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

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

@@ -1 +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\n/**\n * Additional GraphQL fragments that select extra fields on each predictive search result type.\n *\n * Each fragment must be named and typed as follows, or\n * `makePredictiveSearchQueries` throws:\n *\n * - `product`: `fragment PredictiveSearchProductFragment on Product`\n * - `collection`: `fragment PredictiveSearchCollectionFragment on Collection`\n * - `page`: `fragment PredictiveSearchPageFragment on Page`\n * - `article`: `fragment PredictiveSearchArticleFragment on Article`\n * - `query`: `fragment PredictiveSearchQueryFragment on SearchQuerySuggestion`\n *\n * Hydrogen's own fields (used for URL generation, tracking, and display) are\n * always selected; custom fragments are merged alongside them.\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\n/** Options for {@link makePredictiveSearchQueries}. */\nexport type CreatePredictiveSearchQueriesOptions<\n  TFragments extends PredictiveSearchFragments = PredictiveSearchFragments,\n> = {\n  /** Extra fields to select per result type. Hydrogen's built-in fields are always included. */\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\n/** Resolves the query map shape from {@link CreatePredictiveSearchQueriesOptions}, preserving full type inference from custom fragments. */\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}\\\\b`);\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\n/**\n * Composes the predictive search GraphQL query document from the built-in\n * base query and either custom or default fragments.\n *\n * Custom fragments are validated at runtime against their expected names\n * and target GraphQL types. See {@link PredictiveSearchFragments} for the\n * naming contract.\n *\n * The returned object's `predictiveSearch` key carries the composed query\n * with full type inference from the provided fragments.\n *\n * @throws {Error} When a custom fragment does not match its required name or target type.\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\n/**\n * Internal default query object built from Hydrogen's default fragments;\n * used when `query` is omitted.\n *\n * Build custom query documents with {@link makePredictiveSearchQueries}.\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;AAmEA,SAAA,uBAAA,UAAA,UAAA;AAEA,KAAA,IADA,OAAA,eAAA,SAAA,KAAA,YAAA,SAAA,SAAA,KACA,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;;AAoBA,SAAA,4BAAA,SAAA;AACA,QAAA,EACA,kBAAA,IAAA,yBAAA,iBAAA,SAAA,UAAA,CAAA,EACA;;;;;;;;AASA,MAAA,0BAAA,6BAAA"}
+{"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\n/**\n * GraphQL fragments that add fields to each type of predictive search result.\n *\n * Each fragment needs the name and type that its option lists, or `makePredictiveSearchQueries` throws an error.\n * Results keep Hydrogen's built-in fields for links, tracking, and display.\n */\nexport type PredictiveSearchFragments = {\n  /** Adds fields to product results. Start the fragment with `fragment PredictiveSearchProductFragment on Product`. */\n  readonly product?: AnyStorefrontQueryString;\n  /** Adds fields to collection results. Start the fragment with `fragment PredictiveSearchCollectionFragment on Collection`. */\n  readonly collection?: AnyStorefrontQueryString;\n  /** Adds fields to page results. Start the fragment with `fragment PredictiveSearchPageFragment on Page`. */\n  readonly page?: AnyStorefrontQueryString;\n  /** Adds fields to article results. Start the fragment with `fragment PredictiveSearchArticleFragment on Article`. */\n  readonly article?: AnyStorefrontQueryString;\n  /** Adds fields to query suggestions. Start the fragment with `fragment PredictiveSearchQueryFragment on SearchQuerySuggestion`. */\n  readonly query?: AnyStorefrontQueryString;\n};\n\n/** Options for a custom predictive search query. */\nexport type CreatePredictiveSearchQueriesOptions<\n  TFragments extends PredictiveSearchFragments = PredictiveSearchFragments,\n> = {\n  /** Fragments that add fields to each result type. Results keep Hydrogen's built-in fields. */\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\n/** Type of a custom predictive search query, with result types from your fragments. */\ntype PredictiveSearchQueryForOptions<TOptions> = StorefrontQueryString<\n  InferResult<PredictiveSearchQuerySourceForOptions<TOptions>>,\n  InferVariables<PredictiveSearchQuerySourceForOptions<TOptions>>,\n  PredictiveSearchQuerySourceForOptions<TOptions>\n>;\n\n/** Type of the object that makePredictiveSearchQueries returns, with result types from your fragments. */\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}\\\\b`);\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\n/**\n * Builds a predictive search query that adds the fields from your fragments to the results.\n *\n * Pass the query to `queryPredictiveSearch`, or pass the same fragments to `createPredictiveSearchServerHandlers`. TypeScript types the results from your fragments.\n * The function throws an error when a fragment doesn't use its required name and type.\n *\n * @throws {Error} When a custom fragment does not match its required name or target type.\n * @publicDocs\n */\nexport function makePredictiveSearchQueries<\n  const TOptions extends CreatePredictiveSearchQueriesOptions,\n>(options: TOptions): PredictiveSearchQueriesForOptions<TOptions>;\nexport function makePredictiveSearchQueries(): PredictiveSearchQueriesForOptions<undefined>;\n/**\n * @param options Fragments that add fields to each result type.\n * @returns An object with the query under `predictiveSearch`.\n */\nexport function makePredictiveSearchQueries(options?: CreatePredictiveSearchQueriesOptions) {\n  return {\n    predictiveSearch: gql(PREDICTIVE_SEARCH_QUERY, resolveFragments(options?.fragments)),\n  } as PredictiveSearchQueriesForOptions<typeof options>;\n}\n\n/**\n * Hydrogen's built-in predictive search query, under `predictiveSearch`.\n * queryPredictiveSearch uses the query when you omit the `query` option.\n *\n * To add fields to the results, use makePredictiveSearchQueries.\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;AAgEA,SAAA,uBAAA,UAAA,UAAA;AAEA,KAAA,IADA,OAAA,eAAA,SAAA,KAAA,YAAA,SAAA,SAAA,KACA,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;;;;;;AAoBA,SAAA,4BAAA,SAAA;AACA,QAAA,EACA,kBAAA,IAAA,yBAAA,iBAAA,SAAA,UAAA,CAAA,EACA;;;;;;;;AASA,MAAA,0BAAA,6BAAA"}

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

@@ -9,11 +9,11 @@ type PredictiveSearchItemsForQuery<TQuery extends AnyStorefrontQueryString> = No
   predictiveSearch?: (infer TItems) | null;
 } ? TItems : never>;
 /**
- * Predictive search result payload returned by {@link queryPredictiveSearch}.
+ * Predictive search results, with the search term and the result count.
  *
- * The generic parameter is the shape of `items` and defaults to the
- * built-in query's items. For custom fragments, infer the full payload from
- * `queryPredictiveSearch` and your query document:
+ * The type parameter sets the shape of the results and defaults to the
+ * results of Hydrogen's built-in query. For a custom query, use the awaited
+ * return type of `queryPredictiveSearch` for that query.
  *
  * @example
  * ```ts
@@ -23,41 +23,39 @@ type PredictiveSearchItemsForQuery<TQuery extends AnyStorefrontQueryString> = No
  * ```
  */
 type PredictiveSearchData<TItems = PredictiveSearchItemsForQuery<typeof predictiveSearchQueries.predictiveSearch>> = {
-  /** Trimmed search term that produced this result. */term: string; /** Number of items returned, summed across every array in `items` (including query suggestions). Not a total match count. */
-  total: number; /** Predictive search items grouped by resource type. */
+  /** Search term for the results, without surrounding whitespace. */term: string; /** Number of results in the response across every result type, including query suggestions. The count leaves out matches beyond the limit. */
+  total: number; /** Results grouped by type. */
   items: TItems;
 };
-/** Resolves {@link PredictiveSearchData} from a custom query document type, inferring the items shape from the query's result type. */
+/** Predictive search results typed from a custom query. The results take their shape from the query's fields. */
 type PredictiveSearchDataForQuery<TQuery extends AnyStorefrontQueryString> = PredictiveSearchData<PredictiveSearchItemsForQuery<TQuery>>;
-/** Resolves {@link PredictiveSearchData} from {@link CreatePredictiveSearchQueriesOptions}, reflecting the items shape produced by custom fragments. */
+/** Predictive search results typed from query options. The results include the fields from your custom fragments. */
 type PredictiveSearchDataForOptions<TOptions extends CreatePredictiveSearchQueriesOptions> = PredictiveSearchDataForQuery<PredictiveSearchQueriesForOptions<TOptions>["predictiveSearch"]>;
-/**
- * Options for {@link queryPredictiveSearch}.
- *
- * The generic parameter accepts a custom query document type and defaults to
- * the built-in predictive search query.
- */
+/** Storefront client, search term, custom query, and search settings for `queryPredictiveSearch`. */
 type QueryPredictiveSearchOptions<TQuery extends AnyStorefrontQueryString = typeof predictiveSearchQueries.predictiveSearch> = {
-  /** Storefront client instance. Only the `graphql` method is used. */storefrontClient: Pick<StorefrontClient, "graphql">; /** Search term. Trimmed before use; empty or whitespace-only terms return an empty result without a network request. */
-  term: string; /** Custom GraphQL query document, usually created with `makePredictiveSearchQueries`. Must declare the same variables as the built-in query (`$term`, `$limit`, `$limitScope`, `$types`, `$searchableFields`, `$unavailableProducts`). */
-  query?: TQuery; /** Maximum result count. Truncated to an integer, then clamped to the Storefront API's accepted range (1-10). Omitted or non-finite values use Hydrogen's default of 5 (the Storefront API's own default is 10). */
-  limit?: number; /** Whether the limit applies to each resource type independently or to all types combined. Defaults to `"EACH"` (the Storefront API's own default is `"ALL"`). */
-  limitScope?: PredictiveSearchLimitScope; /** Resource types to include. When omitted, the Storefront API uses the shop's predictive search type settings, which exclude articles by default. Pass `types` explicitly to control which result arrays are populated. */
-  types?: PredictiveSearchType[]; /** Fields to search within. When omitted, the Storefront API searches its default field set (title, product type, variant title, and vendor), not every field. */
-  searchableFields?: SearchableField[]; /** How to handle unavailable products. Defaults to `"HIDE"` rather than the Storefront API's shop-specific setting (which defaults to `"LAST"`). */
-  unavailableProducts?: SearchUnavailableProductsType; /** Signal to abort the in-flight request. */
+  /** Storefront client that sends the query. Any object with a `graphql()` method works. */storefrontClient: Pick<StorefrontClient, "graphql">; /** Search term. A blank term returns empty results without a Storefront API request. */
+  term: string; /** Custom query, usually from `makePredictiveSearchQueries`. Defaults to Hydrogen's built-in query. A hand-written query receives the term, limit, limit scope, types, searchable fields, and unavailable products as variables. */
+  query?: TQuery; /** Maximum number of results, from 1 to 10. Predictive search clamps other values to that range. Defaults to `5`, which differs from the Storefront API default of 10. */
+  limit?: number; /** Whether the limit applies to each result type or to all result types combined. Defaults to `EACH`. */
+  limitScope?: PredictiveSearchLimitScope; /** Result types to include. */
+  types?: PredictiveSearchType[]; /** Fields to search for page, article, and collection results. Defaults to the title. Product results always search every product field. */
+  searchableFields?: SearchableField[]; /** Whether results hide unavailable products, show them, or list them last. Defaults to `HIDE`, which differs from the Storefront API default of `LAST`. */
+  unavailableProducts?: SearchUnavailableProductsType; /** Cancels the request when the signal aborts. */
   signal?: AbortSignal;
 };
 /**
- * Executes a predictive search query against the Storefront API and returns
- * the data payload.
+ * Queries the Storefront API for predictive search results. Use the function in server code, such as a route loader. Pass the Storefront client and the search term.
+ *
+ * The function throws an error when the Storefront API returns GraphQL errors or no predictive search data. Network failures and aborts from the Storefront client also throw.
  *
- * To serve results with the Storefront API response headers (e.g. cache
- * headers), use the `get` handler from `createPredictiveSearchServerHandlers()`.
+ * To serve results to the browser with the Storefront API response headers, use `createPredictiveSearchServerHandlers`.
  *
+ * @param options - The Storefront client, the search term, a custom query, and search settings.
+ * @returns The search term, the result count, and the results grouped by type.
  * @throws {Error} When the Storefront API returns GraphQL errors.
  * @throws {Error} When the response contains no predictive search data.
- * @throws Errors from `storefrontClient.graphql` (e.g. network failures or an `AbortError` when `signal` aborts).
+ * @throws Errors from the Storefront client, such as network failures or an abort error when the signal aborts.
+ * @publicDocs
  */
 declare function queryPredictiveSearch<const TQuery extends AnyStorefrontQueryString = typeof predictiveSearchQueries.predictiveSearch>(options: QueryPredictiveSearchOptions<TQuery>): Promise<PredictiveSearchDataForQuery<TQuery>>;
 //#endregion

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

@@ -1,22 +1,22 @@
 import { predictiveSearchQueries } from "./queries.mjs";
 
 //#region src/core/predictive-search/search.ts
-/** Minimum result count accepted by the Storefront API predictive search query. Values below this are clamped up. */
+/** Smallest result limit. Predictive search raises lower limits to this value. */
 const MIN_PREDICTIVE_SEARCH_LIMIT = 1;
-/** Maximum result count accepted by the Storefront API predictive search query. Values above this are clamped down. */
+/** Largest result limit. Predictive search lowers higher limits to this value. */
 const MAX_PREDICTIVE_SEARCH_LIMIT = 10;
-/** Default result count used when no limit is specified. */
+/** Result limit that predictive search uses when you don't set one. */
 const DEFAULT_PREDICTIVE_SEARCH_LIMIT = 5;
-/** Default limit scope, applying the limit to each resource type independently. */
+/** Default limit scope, which applies the limit to each result type separately. */
 const DEFAULT_PREDICTIVE_SEARCH_LIMIT_SCOPE = "EACH";
-/** Default unavailable-product behavior, hiding them from results. */
+/** Default unavailable product behavior, which hides unavailable products. */
 const DEFAULT_PREDICTIVE_SEARCH_UNAVAILABLE_PRODUCTS = "HIDE";
 /**
-* Returns a zero-result `PredictiveSearchData` payload with empty arrays
-* for every resource type.
+* Returns an empty predictive search result with an empty array for every
+* resource type.
 *
-* Used internally for blank terms and for the client store's initial and
-* reset state. Typed with the default items shape.
+* The query function returns the empty result for blank terms. The client
+* store uses the empty result for its initial and reset state.
 */
 function getEmptyPredictiveSearchResult(term = "") {
 	return {
@@ -32,29 +32,30 @@ function getEmptyPredictiveSearchResult(term = "") {
 	};
 }
 /**
-* Executes a predictive search query against the Storefront API and returns
-* the data payload.
+* Queries the Storefront API for predictive search results. Use the function in server code, such as a route loader. Pass the Storefront client and the search term.
 *
-* To serve results with the Storefront API response headers (e.g. cache
-* headers), use the `get` handler from `createPredictiveSearchServerHandlers()`.
+* The function throws an error when the Storefront API returns GraphQL errors or no predictive search data. Network failures and aborts from the Storefront client also throw.
 *
+* To serve results to the browser with the Storefront API response headers, use `createPredictiveSearchServerHandlers`.
+*
+* @param options - The Storefront client, the search term, a custom query, and search settings.
+* @returns The search term, the result count, and the results grouped by type.
 * @throws {Error} When the Storefront API returns GraphQL errors.
 * @throws {Error} When the response contains no predictive search data.
-* @throws Errors from `storefrontClient.graphql` (e.g. network failures or an `AbortError` when `signal` aborts).
+* @throws Errors from the Storefront client, such as network failures or an abort error when the signal aborts.
+* @publicDocs
 */
 async function queryPredictiveSearch(options) {
 	return (await fetchPredictiveSearch(options)).data;
 }
 /**
-* Executes a predictive search query against the Storefront API and returns
-* both the data payload and response headers.
+* Queries the Storefront API for predictive search results and returns the results with the Storefront API response headers.
 *
-* See `QueryPredictiveSearchOptions` for option defaults and
-* `PredictiveSearchData` for the shape of the returned data.
+* The function takes the same options as queryPredictiveSearch.
 *
 * @throws {Error} When the Storefront API returns GraphQL errors.
 * @throws {Error} When the response contains no predictive search data.
-* @throws Errors from `storefrontClient.graphql` (e.g. network failures or an `AbortError` when `signal` aborts).
+* @throws Errors from the Storefront client, such as network failures or an abort error when the signal aborts.
 */
 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();

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

@@ -1 +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\n/** Minimum result count accepted by the Storefront API predictive search query. Values below this are clamped up. */\nexport const MIN_PREDICTIVE_SEARCH_LIMIT = 1;\n/** Maximum result count accepted by the Storefront API predictive search query. Values above this are clamped down. */\nexport const MAX_PREDICTIVE_SEARCH_LIMIT = 10;\n/** Default result count used when no limit is specified. */\nexport const DEFAULT_PREDICTIVE_SEARCH_LIMIT = 5;\n/** Default limit scope, applying the limit to each resource type independently. */\nexport const DEFAULT_PREDICTIVE_SEARCH_LIMIT_SCOPE = \"EACH\" satisfies PredictiveSearchLimitScope;\n/** Default unavailable-product behavior, hiding them from results. */\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\n/**\n * Predictive search result payload returned by {@link queryPredictiveSearch}.\n *\n * The generic parameter is the shape of `items` and defaults to the\n * built-in query's items. For custom fragments, infer the full payload from\n * `queryPredictiveSearch` and your query document:\n *\n * @example\n * ```ts\n * type CustomSearchData = Awaited<\n *   ReturnType<typeof queryPredictiveSearch<typeof queries.predictiveSearch>>\n * >;\n * ```\n */\nexport type PredictiveSearchData<\n  TItems = PredictiveSearchItemsForQuery<typeof predictiveSearchQueries.predictiveSearch>,\n> = {\n  /** Trimmed search term that produced this result. */\n  term: string;\n  /** Number of items returned, summed across every array in `items` (including query suggestions). Not a total match count. */\n  total: number;\n  /** Predictive search items grouped by resource type. */\n  items: TItems;\n};\n\n/** Resolves {@link PredictiveSearchData} from a custom query document type, inferring the items shape from the query's result type. */\nexport type PredictiveSearchDataForQuery<TQuery extends AnyStorefrontQueryString> =\n  PredictiveSearchData<PredictiveSearchItemsForQuery<TQuery>>;\n\n/** Resolves {@link PredictiveSearchData} from {@link CreatePredictiveSearchQueriesOptions}, reflecting the items shape produced by custom fragments. */\nexport type PredictiveSearchDataForOptions<TOptions extends CreatePredictiveSearchQueriesOptions> =\n  PredictiveSearchDataForQuery<PredictiveSearchQueriesForOptions<TOptions>[\"predictiveSearch\"]>;\n\n/**\n * Options for {@link queryPredictiveSearch}.\n *\n * The generic parameter accepts a custom query document type and defaults to\n * the built-in predictive search query.\n */\nexport type QueryPredictiveSearchOptions<\n  TQuery extends AnyStorefrontQueryString = typeof predictiveSearchQueries.predictiveSearch,\n> = {\n  /** Storefront client instance. Only the `graphql` method is used. */\n  storefrontClient: Pick<StorefrontClient, \"graphql\">;\n  /** Search term. Trimmed before use; empty or whitespace-only terms return an empty result without a network request. */\n  term: string;\n  /** Custom GraphQL query document, usually created with `makePredictiveSearchQueries`. Must declare the same variables as the built-in query (`$term`, `$limit`, `$limitScope`, `$types`, `$searchableFields`, `$unavailableProducts`). */\n  query?: TQuery;\n  /** Maximum result count. Truncated to an integer, then clamped to the Storefront API's accepted range (1-10). Omitted or non-finite values use Hydrogen's default of 5 (the Storefront API's own default is 10). */\n  limit?: number;\n  /** Whether the limit applies to each resource type independently or to all types combined. Defaults to `\"EACH\"` (the Storefront API's own default is `\"ALL\"`). */\n  limitScope?: PredictiveSearchLimitScope;\n  /** Resource types to include. When omitted, the Storefront API uses the shop's predictive search type settings, which exclude articles by default. Pass `types` explicitly to control which result arrays are populated. */\n  types?: PredictiveSearchType[];\n  /** Fields to search within. When omitted, the Storefront API searches its default field set (title, product type, variant title, and vendor), not every field. */\n  searchableFields?: SearchableField[];\n  /** How to handle unavailable products. Defaults to `\"HIDE\"` rather than the Storefront API's shop-specific setting (which defaults to `\"LAST\"`). */\n  unavailableProducts?: SearchUnavailableProductsType;\n  /** Signal to abort the in-flight request. */\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\n/**\n * Returns a zero-result `PredictiveSearchData` payload with empty arrays\n * for every resource type.\n *\n * Used internally for blank terms and for the client store's initial and\n * reset state. Typed with the default items shape.\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\n/**\n * Executes a predictive search query against the Storefront API and returns\n * the data payload.\n *\n * To serve results with the Storefront API response headers (e.g. cache\n * headers), use the `get` handler from `createPredictiveSearchServerHandlers()`.\n *\n * @throws {Error} When the Storefront API returns GraphQL errors.\n * @throws {Error} When the response contains no predictive search data.\n * @throws Errors from `storefrontClient.graphql` (e.g. network failures or an `AbortError` when `signal` aborts).\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\n/**\n * Executes a predictive search query against the Storefront API and returns\n * both the data payload and response headers.\n *\n * See `QueryPredictiveSearchOptions` for option defaults and\n * `PredictiveSearchData` for the shape of the returned data.\n *\n * @throws {Error} When the Storefront API returns GraphQL errors.\n * @throws {Error} When the response contains no predictive search data.\n * @throws Errors from `storefrontClient.graphql` (e.g. network failures or an `AbortError` when `signal` aborts).\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":";;;;AAeA,MAAa,8BAA8B;;AAE3C,MAAa,8BAA8B;;AAE3C,MAAa,kCAAkC;;AAE/C,MAAa,wCAAwC;;AAErD,MAAa,iDACX;;;;;;;;AA2GF,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;;;;;;;;;;;;;AAcH,eAAsB,sBAEpB,SAA8F;AAE9F,SAAO,MADc,sBAAsB,QAAQ,EACrC;;;;;;;;;;;;;AAchB,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"}
+{"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\n/** Smallest result limit. Predictive search raises lower limits to this value. */\nexport const MIN_PREDICTIVE_SEARCH_LIMIT = 1;\n/** Largest result limit. Predictive search lowers higher limits to this value. */\nexport const MAX_PREDICTIVE_SEARCH_LIMIT = 10;\n/** Result limit that predictive search uses when you don't set one. */\nexport const DEFAULT_PREDICTIVE_SEARCH_LIMIT = 5;\n/** Default limit scope, which applies the limit to each result type separately. */\nexport const DEFAULT_PREDICTIVE_SEARCH_LIMIT_SCOPE = \"EACH\" satisfies PredictiveSearchLimitScope;\n/** Default unavailable product behavior, which hides unavailable products. */\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\n/**\n * Predictive search results, with the search term and the result count.\n *\n * The type parameter sets the shape of the results and defaults to the\n * results of Hydrogen's built-in query. For a custom query, use the awaited\n * return type of `queryPredictiveSearch` for that query.\n *\n * @example\n * ```ts\n * type CustomSearchData = Awaited<\n *   ReturnType<typeof queryPredictiveSearch<typeof queries.predictiveSearch>>\n * >;\n * ```\n */\nexport type PredictiveSearchData<\n  TItems = PredictiveSearchItemsForQuery<typeof predictiveSearchQueries.predictiveSearch>,\n> = {\n  /** Search term for the results, without surrounding whitespace. */\n  term: string;\n  /** Number of results in the response across every result type, including query suggestions. The count leaves out matches beyond the limit. */\n  total: number;\n  /** Results grouped by type. */\n  items: TItems;\n};\n\n/** Predictive search results typed from a custom query. The results take their shape from the query's fields. */\nexport type PredictiveSearchDataForQuery<TQuery extends AnyStorefrontQueryString> =\n  PredictiveSearchData<PredictiveSearchItemsForQuery<TQuery>>;\n\n/** Predictive search results typed from query options. The results include the fields from your custom fragments. */\nexport type PredictiveSearchDataForOptions<TOptions extends CreatePredictiveSearchQueriesOptions> =\n  PredictiveSearchDataForQuery<PredictiveSearchQueriesForOptions<TOptions>[\"predictiveSearch\"]>;\n\n/** Storefront client, search term, custom query, and search settings for `queryPredictiveSearch`. */\nexport type QueryPredictiveSearchOptions<\n  TQuery extends AnyStorefrontQueryString = typeof predictiveSearchQueries.predictiveSearch,\n> = {\n  /** Storefront client that sends the query. Any object with a `graphql()` method works. */\n  storefrontClient: Pick<StorefrontClient, \"graphql\">;\n  /** Search term. A blank term returns empty results without a Storefront API request. */\n  term: string;\n  /** Custom query, usually from `makePredictiveSearchQueries`. Defaults to Hydrogen's built-in query. A hand-written query receives the term, limit, limit scope, types, searchable fields, and unavailable products as variables. */\n  query?: TQuery;\n  /** Maximum number of results, from 1 to 10. Predictive search clamps other values to that range. Defaults to `5`, which differs from the Storefront API default of 10. */\n  limit?: number;\n  /** Whether the limit applies to each result type or to all result types combined. Defaults to `EACH`. */\n  limitScope?: PredictiveSearchLimitScope;\n  /** Result types to include. */\n  types?: PredictiveSearchType[];\n  /** Fields to search for page, article, and collection results. Defaults to the title. Product results always search every product field. */\n  searchableFields?: SearchableField[];\n  /** Whether results hide unavailable products, show them, or list them last. Defaults to `HIDE`, which differs from the Storefront API default of `LAST`. */\n  unavailableProducts?: SearchUnavailableProductsType;\n  /** Cancels the request when the signal aborts. */\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\n/**\n * Returns an empty predictive search result with an empty array for every\n * resource type.\n *\n * The query function returns the empty result for blank terms. The client\n * store uses the empty result for its initial and reset state.\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\n/**\n * Queries the Storefront API for predictive search results. Use the function in server code, such as a route loader. Pass the Storefront client and the search term.\n *\n * The function throws an error when the Storefront API returns GraphQL errors or no predictive search data. Network failures and aborts from the Storefront client also throw.\n *\n * To serve results to the browser with the Storefront API response headers, use `createPredictiveSearchServerHandlers`.\n *\n * @param options - The Storefront client, the search term, a custom query, and search settings.\n * @returns The search term, the result count, and the results grouped by type.\n * @throws {Error} When the Storefront API returns GraphQL errors.\n * @throws {Error} When the response contains no predictive search data.\n * @throws Errors from the Storefront client, such as network failures or an abort error when the signal aborts.\n * @publicDocs\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\n/**\n * Queries the Storefront API for predictive search results and returns the results with the Storefront API response headers.\n *\n * The function takes the same options as queryPredictiveSearch.\n *\n * @throws {Error} When the Storefront API returns GraphQL errors.\n * @throws {Error} When the response contains no predictive search data.\n * @throws Errors from the Storefront client, such as network failures or an abort error when the signal aborts.\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\n/**\n * Queries the Storefront API for predictive search results. Use the function in server code, such as a route loader. Pass the Storefront client and the search term.\n *\n * The function throws an error when the Storefront API returns GraphQL errors or no predictive search data. Network failures and aborts from the Storefront client also throw.\n *\n * To serve results to the browser with the Storefront API response headers, use `createPredictiveSearchServerHandlers`.\n *\n * @throws {Error} When the Storefront API returns GraphQL errors.\n * @throws {Error} When the response contains no predictive search data.\n * @throws Errors from the Storefront client, such as network failures or an abort error when the signal aborts.\n * @publicDocs\n */\nexport type QueryPredictiveSearchForDocs =\n  /**\n   * @param options - The Storefront client, the search term, a custom query, and search settings.\n   * @returns The search term, the result count, and the results grouped by type.\n   */\n  (options: QueryPredictiveSearchOptions) => Promise<PredictiveSearchData>;\n"],"mappings":";;;;AAeA,MAAa,8BAA8B;;AAE3C,MAAa,8BAA8B;;AAE3C,MAAa,kCAAkC;;AAE/C,MAAa,wCAAwC;;AAErD,MAAa,iDACX;;;;;;;;AAsGF,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;;;;;;;;;;;;;;;;AAiBH,eAAsB,sBAEpB,SAA8F;AAE9F,SAAO,MADc,sBAAsB,QAAQ,EACrC;;;;;;;;;;;AAYhB,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

@@ -16,44 +16,43 @@ type PredictiveSearchErrorCode = "invalid_predictive_search_request";
 type PredictiveSearchError = ShopifyRouteError & {
   code: PredictiveSearchErrorCode;
 };
+/** GET route handler that returns predictive search results or an error. */
 type PredictiveSearchGetHandler<TData = PredictiveSearchDataForOptions<{}>> = CallableRouteHandler<PredictiveSearchHandlerContext, PredictiveSearchGetResult<TData>, string, typeof PREDICTIVE_SEARCH_GET_METHOD>;
+/** Predictive search route handlers to pass to `handleShopifyRoutes`. */
 type PredictiveSearchServerHandlers<TOptions extends CreatePredictiveSearchServerHandlersOptions = {}, TData = PredictiveSearchDataForOptions<TOptions>> = {
-  readonly [predictiveSearchServerHandlersQuery]: PredictiveSearchQueriesForOptions<TOptions>["predictiveSearch"];
+  /** Query that the handlers run, with any custom fragments. */readonly [predictiveSearchServerHandlersQuery]: PredictiveSearchQueriesForOptions<TOptions>["predictiveSearch"]; /** Answers GET requests with predictive search results as JSON. */
   get: PredictiveSearchGetHandler<TData>;
 };
 /**
- * Options for {@link createPredictiveSearchServerHandlers}.
+ * Route path, custom fragments, and default search settings for the predictive search route.
  *
- * Extends {@link CreatePredictiveSearchQueriesOptions} with server-specific
- * defaults. Each search option sets a default that individual requests can
- * override via query parameters. These are defaults, not restrictions: any
- * client can override them.
+ * A request overrides a default search setting with a URL parameter of the same name.
  */
-type CreatePredictiveSearchServerHandlersOptions = CreatePredictiveSearchQueriesOptions & {
-  /** Route path the handler is registered at. Defaults to `"/api/predictive-search"`. */path?: string; /** Default result count. Requests can override it with the `limit` query parameter; empty or unparseable values fall back to this default. See {@link QueryPredictiveSearchOptions.limit} for normalization and the default when omitted. */
-  limit?: number; /** Default limit scope. Individual requests override via the `limitScope` query parameter. */
-  limitScope?: PredictiveSearchLimitScope; /** Default resource types to search. Individual requests override via the `types` query parameter (comma-separated). */
-  types?: PredictiveSearchType[]; /** Default fields to search. Individual requests override via the `searchableFields` query parameter (comma-separated). */
-  searchableFields?: SearchableField[]; /** Default unavailable-product behavior. Individual requests override via the `unavailableProducts` query parameter. */
+interface CreatePredictiveSearchServerHandlersOptions extends CreatePredictiveSearchQueriesOptions {
+  /** Route path that the GET handler serves. Defaults to `/api/predictive-search`. */
+  path?: string;
+  /** Default maximum number of results, from 1 to 10. Applies when a request has no numeric `limit` parameter. Predictive search clamps other values to that range. Defaults to `5`. */
+  limit?: number;
+  /** Default limit scope. Defaults to `EACH`. */
+  limitScope?: PredictiveSearchLimitScope;
+  /** Default result types. A request can set `types` to a comma-separated list. */
+  types?: PredictiveSearchType[];
+  /** Default fields to search. A request can set `searchableFields` to a comma-separated list. */
+  searchableFields?: SearchableField[];
+  /** Default handling of unavailable products. Defaults to `HIDE`. */
   unavailableProducts?: SearchUnavailableProductsType;
-};
+}
 /**
- * Creates a GET request handler that serves predictive search results from
- * the Storefront API.
- *
- * The handler parses search parameters from the request URL:
+ * Creates the route that answers predictive search requests from the browser.
+ * Register the handlers with `handleShopifyRoutes`. The default route path matches
+ * the default endpoint of `createPredictiveSearchStore` and `PredictiveSearchProvider`.
  *
- * - `q` for the search term
- * - Each search option in {@link CreatePredictiveSearchServerHandlersOptions}
- *   can be overridden by a query parameter of the same name
+ * The route reads the search term from the `q` URL parameter. A URL parameter with the same name as a search setting overrides the setting's default.
  *
- * The `types` and `searchableFields` parameters accept comma-separated values. Invalid enum
- * values, and any Storefront API failure, produce an error result with code
- * `"invalid_predictive_search_request"`.
+ * An invalid setting value or a failed Storefront API query returns HTTP status `400` with a JSON body of `{error: {code, message}}`. The `code` value is `invalid_predictive_search_request`.
+ * A successful response forwards the Storefront API response headers except the content encoding, content length, and server timing headers.
  *
- * The returned handlers object has a `get` method that can be registered
- * as a route handler. Successful results include the Storefront API response
- * headers, excluding `content-encoding`, `content-length`, and `server-timing`.
+ * @publicDocs
  */
 declare function createPredictiveSearchServerHandlers(): PredictiveSearchServerHandlers;
 declare function createPredictiveSearchServerHandlers<const TOptions extends CreatePredictiveSearchServerHandlersOptions>(options: TOptions): PredictiveSearchServerHandlers<TOptions>;

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

@@ -30,6 +30,10 @@ const VALID_UNAVAILABLE_PRODUCTS = [
 	"LAST",
 	"SHOW"
 ];
+/**
+* @param options Route path, custom fragments, and default search settings for the route.
+* @returns Route handlers to pass to `handleShopifyRoutes`.
+*/
 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)) };

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

@@ -1 +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\n/**\n * Options for {@link createPredictiveSearchServerHandlers}.\n *\n * Extends {@link CreatePredictiveSearchQueriesOptions} with server-specific\n * defaults. Each search option sets a default that individual requests can\n * override via query parameters. These are defaults, not restrictions: any\n * client can override them.\n */\nexport type CreatePredictiveSearchServerHandlersOptions = CreatePredictiveSearchQueriesOptions & {\n  /** Route path the handler is registered at. Defaults to `\"/api/predictive-search\"`. */\n  path?: string;\n  /** Default result count. Requests can override it with the `limit` query parameter; empty or unparseable values fall back to this default. See {@link QueryPredictiveSearchOptions.limit} for normalization and the default when omitted. */\n  limit?: number;\n  /** Default limit scope. Individual requests override via the `limitScope` query parameter. */\n  limitScope?: PredictiveSearchLimitScope;\n  /** Default resource types to search. Individual requests override via the `types` query parameter (comma-separated). */\n  types?: PredictiveSearchType[];\n  /** Default fields to search. Individual requests override via the `searchableFields` query parameter (comma-separated). */\n  searchableFields?: SearchableField[];\n  /** Default unavailable-product behavior. Individual requests override via the `unavailableProducts` query parameter. */\n  unavailableProducts?: SearchUnavailableProductsType;\n};\n\n/**\n * Creates a GET request handler that serves predictive search results from\n * the Storefront API.\n *\n * The handler parses search parameters from the request URL:\n *\n * - `q` for the search term\n * - Each search option in {@link CreatePredictiveSearchServerHandlersOptions}\n *   can be overridden by a query parameter of the same name\n *\n * The `types` and `searchableFields` parameters accept comma-separated values. Invalid enum\n * values, and any Storefront API failure, produce an error result with code\n * `\"invalid_predictive_search_request\"`.\n *\n * The returned handlers object has a `get` method that can be registered\n * as a route handler. Successful results include the Storefront API response\n * headers, excluding `content-encoding`, `content-length`, and `server-timing`.\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\n// Invalid enum params return a typed error, but an unparseable limit falls back to the configured default.\nfunction parseLimit(\n  searchParams: URLSearchParams,\n  options: CreatePredictiveSearchServerHandlersOptions,\n): number {\n  const defaultLimit = options.limit ?? DEFAULT_PREDICTIVE_SEARCH_LIMIT;\n  const rawLimit = searchParams.get(\"limit\")?.trim() ?? \"\";\n  if (rawLimit === \"\") return defaultLimit;\n\n  const limit = Number(rawLimit);\n  return Number.isFinite(limit) ? limit : defaultLimit;\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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"}
+{"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\n/** GET route handler that returns predictive search results or an error. */\ntype PredictiveSearchGetHandler<TData = PredictiveSearchDataForOptions<{}>> = CallableRouteHandler<\n  PredictiveSearchHandlerContext,\n  PredictiveSearchGetResult<TData>,\n  string,\n  typeof PREDICTIVE_SEARCH_GET_METHOD\n>;\n\n/** Predictive search route handlers to pass to `handleShopifyRoutes`. */\ntype PredictiveSearchServerHandlers<\n  TOptions extends CreatePredictiveSearchServerHandlersOptions = {},\n  TData = PredictiveSearchDataForOptions<TOptions>,\n> = {\n  /** Query that the handlers run, with any custom fragments. */\n  readonly [predictiveSearchServerHandlersQuery]: PredictiveSearchQueriesForOptions<TOptions>[\"predictiveSearch\"];\n  /** Answers GET requests with predictive search results as JSON. */\n  get: PredictiveSearchGetHandler<TData>;\n};\n\n/**\n * Route path, custom fragments, and default search settings for the predictive search route.\n *\n * A request overrides a default search setting with a URL parameter of the same name.\n */\nexport interface CreatePredictiveSearchServerHandlersOptions extends CreatePredictiveSearchQueriesOptions {\n  /** Route path that the GET handler serves. Defaults to `/api/predictive-search`. */\n  path?: string;\n  /** Default maximum number of results, from 1 to 10. Applies when a request has no numeric `limit` parameter. Predictive search clamps other values to that range. Defaults to `5`. */\n  limit?: number;\n  /** Default limit scope. Defaults to `EACH`. */\n  limitScope?: PredictiveSearchLimitScope;\n  /** Default result types. A request can set `types` to a comma-separated list. */\n  types?: PredictiveSearchType[];\n  /** Default fields to search. A request can set `searchableFields` to a comma-separated list. */\n  searchableFields?: SearchableField[];\n  /** Default handling of unavailable products. Defaults to `HIDE`. */\n  unavailableProducts?: SearchUnavailableProductsType;\n}\n\n/**\n * Creates the route that answers predictive search requests from the browser.\n * Register the handlers with `handleShopifyRoutes`. The default route path matches\n * the default endpoint of `createPredictiveSearchStore` and `PredictiveSearchProvider`.\n *\n * The route reads the search term from the `q` URL parameter. A URL parameter with the same name as a search setting overrides the setting's default.\n *\n * An invalid setting value or a failed Storefront API query returns HTTP status `400` with a JSON body of `{error: {code, message}}`. The `code` value is `invalid_predictive_search_request`.\n * A successful response forwards the Storefront API response headers except the content encoding, content length, and server timing headers.\n *\n * @publicDocs\n */\nexport function createPredictiveSearchServerHandlers(): PredictiveSearchServerHandlers;\nexport function createPredictiveSearchServerHandlers<\n  const TOptions extends CreatePredictiveSearchServerHandlersOptions,\n>(options: TOptions): PredictiveSearchServerHandlers<TOptions>;\n/**\n * @param options Route path, custom fragments, and default search settings for the route.\n * @returns Route handlers to pass to `handleShopifyRoutes`.\n */\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\n// Invalid enum params return a typed error, but an unparseable limit falls back to the configured default.\nfunction parseLimit(\n  searchParams: URLSearchParams,\n  options: CreatePredictiveSearchServerHandlersOptions,\n): number {\n  const defaultLimit = options.limit ?? DEFAULT_PREDICTIVE_SEARCH_LIMIT;\n  const rawLimit = searchParams.get(\"limit\")?.trim() ?? \"\";\n  if (rawLimit === \"\") return defaultLimit;\n\n  const limit = Number(rawLimit);\n  return Number.isFinite(limit) ? limit : defaultLimit;\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

@@ -2,44 +2,85 @@ import { PredictiveSearchLimitScope, PredictiveSearchType, SearchUnavailableProd
 import { PredictiveSearchData } from "./search.mjs";
 
 //#region src/core/predictive-search/store.d.ts
-/** Lifecycle state for the predictive search client store. */
+/** Status of the current search. */
 type PredictiveSearchStatus = "idle" | "loading" | "success" | "error";
-/** Current predictive search snapshot exposed to UI bindings. */
+/** Current search term, status, results, and error of a predictive search. */
 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. */
+  /** Latest search term, without surrounding whitespace. */term: string; /** Status of the search for the current term. */
+  status: PredictiveSearchStatus; /** Results of the latest successful search. Previous results stay in place while a new search loads and after a search fails. The idle state holds empty results. */
+  result: TData; /** Message from the latest failed search, or `null` when the current search hasn't failed. A custom endpoint sets the message with a JSON body of `{error: {message}}`. */
   error: string | null;
 };
-/** Options for creating a framework-neutral predictive search client store. */
+/**
+ * Endpoint, timing, and search settings for a predictive search store.
+ *
+ * The store sends each search setting to the endpoint as a URL parameter of the same name. The server handlers apply their own defaults to omitted settings.
+ */
 type CreatePredictiveSearchStoreOptions = {
   /**
-   * Same-origin JSON endpoint used for browser predictive-search requests.
+   * Route that returns predictive search results as JSON, in the shape that `createPredictiveSearchServerHandlers` returns.
    *
-   * The endpoint must return JSON matching the data payload from
-   * `await predictiveSearchHandlers.get(...)`.
+   * Defaults to `/api/predictive-search`.
    */
-  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. */
+  predictiveSearchEndpoint?: string;
+  /**
+   * Milliseconds to wait after the latest term change before searching.
+   *
+   * Defaults to `150`. Pass `0` to search right away. Negative and non-finite values use the default.
+   */
+  debounceInMs?: number;
+  /**
+   * Number of characters a term needs, after trimming, before the store searches.
+   *
+   * Defaults to `1`. Negative and non-finite values use the default.
+   */
+  minTermLength?: number; /** Function that sends search requests. Defaults to the global `fetch`. Pass a function for tests or for runtimes without a global `fetch`. */
+  fetch?: typeof globalThis.fetch; /** Maximum number of results, from 1 to 10. The server handlers clamp other values to that range. */
+  limit?: number; /** Whether the limit applies to each result type or to all result types combined. */
+  limitScope?: PredictiveSearchLimitScope; /** Result types to include. */
+  types?: PredictiveSearchType[]; /** Fields to search for page, article, and collection results. */
+  searchableFields?: SearchableField[]; /** Whether results hide unavailable products, show them, or list them last. */
   unavailableProducts?: SearchUnavailableProductsType;
 };
-/** Framework-neutral predictive search store used by UI bindings. */
+/** Holds the search term, status, and results, and runs searches as the customer types. */
 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. */
+  /** Restarts a store after `destroy()`. A new store doesn't need this call. */connect(): void; /** Returns the current search term, status, results, and error. */
+  getState(): PredictiveSearchState<TData>; /** Calls your function with the new state on every change. Returns a function that stops the calls. */
+  subscribe(listener: (state: PredictiveSearchState<TData>) => void): () => void;
+  /**
+   * Searches for a term after the debounce delay. Call the method on every keystroke.
+   *
+   * Each call cancels the previous pending search. A term shorter than the minimum length, after trimming, returns the store to `idle` with empty results. Otherwise, the status changes to `loading` until the search ends with `success` or `error`. Responses for earlier terms never replace newer results.
+   *
+   * The returned promise resolves when the search ends, or when a later search, `clear()`, or `destroy()` cancels the search.
+   */
+  search(term: string): Promise<void>;
+  /**
+   * Cancels any pending search and returns the store to the idle state with no term and empty results.
+   *
+   * Call `clear()` when the customer closes the search UI.
+   */
+  clear(): void;
+  /**
+   * Stops the store. Call `destroy()` when the search UI unmounts.
+   *
+   * The store cancels any pending search, keeps its current state, and ignores searches until you call `connect()`.
+   */
   destroy(): void;
 };
-/** Search methods exposed by the predictive search store. */
+/** Methods that search for a term and clear the results. */
 type PredictiveSearchActions = Pick<PredictiveSearchStore, "search" | "clear">;
+/**
+ * Creates a store that searches as the customer types and holds the latest predictive search results. Use the store in DOM code or in UI frameworks without Hydrogen bindings. In React and Vue, use `PredictiveSearchProvider`.
+ *
+ * Call `search()` with each new term, read results with `getState()` or `subscribe()`, and call `destroy()` when the search UI unmounts. By default, the store requests results from the route that `createPredictiveSearchServerHandlers` serves.
+ *
+ * The function throws an error when you omit the `fetch` option in a runtime without a global `fetch`.
+ *
+ * @param options Endpoint, timing, and search settings for the store.
+ * @returns A store with no term and empty results, ready to search.
+ * @publicDocs
+ */
 declare function createPredictiveSearchStore<TData extends PredictiveSearchData = PredictiveSearchData>(options?: CreatePredictiveSearchStoreOptions): PredictiveSearchStore<TData>;
 //#endregion
 export { CreatePredictiveSearchStoreOptions, PredictiveSearchActions, PredictiveSearchState, PredictiveSearchStatus, PredictiveSearchStore, createPredictiveSearchStore };

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

@@ -3,10 +3,21 @@ import { PREDICTIVE_SEARCH_API_PATH } from "./constants.mjs";
 import { getEmptyPredictiveSearchResult } from "./search.mjs";
 
 //#region src/core/predictive-search/store.ts
-/** Default delay before predictive search sends a request after a term changes. */
+/** Default wait, in milliseconds, between the latest term change and the search request. */
 const DEFAULT_PREDICTIVE_SEARCH_DEBOUNCE_IN_MS = 150;
 /** Default minimum trimmed term length required before predictive search sends a request. */
 const DEFAULT_PREDICTIVE_SEARCH_MIN_TERM_LENGTH = 1;
+/**
+* Creates a store that searches as the customer types and holds the latest predictive search results. Use the store in DOM code or in UI frameworks without Hydrogen bindings. In React and Vue, use `PredictiveSearchProvider`.
+*
+* Call `search()` with each new term, read results with `getState()` or `subscribe()`, and call `destroy()` when the search UI unmounts. By default, the store requests results from the route that `createPredictiveSearchServerHandlers` serves.
+*
+* The function throws an error when you omit the `fetch` option in a runtime without a global `fetch`.
+*
+* @param options Endpoint, timing, and search settings for the store.
+* @returns A store with no term and empty results, ready to search.
+* @publicDocs
+*/
 function createPredictiveSearchStore(options = {}) {
 	const resolvedFetch = options.fetch ?? resolveGlobalFetch();
 	if (typeof resolvedFetch !== "function") throw new Error("No fetch function available. Pass a fetch option or ensure globalThis.fetch exists.");