@occluze/tether 0.6.8 → 0.7.0

package/src/lazy-iife.ts

@@ -0,0 +1,197 @@
+/**
+ * `<script>` build: the optional parts are separate files next to tether(.min).js (tether.markets.min.js), loaded on
+ * first use and checked against the hashes the core was built with, from that folder or from `partsUrl`, which must
+ * serve the files of the same release. A part registers itself in `window.Tether.__parts` and uses the core modules in
+ * `window.Tether.__core` instead of bundling copies.
+ */
+import { cfg, isConfigured, log, MARKET_SOURCES, parseMarkets, reportError, warn } from './config.ts';
+import { endpoint, gql, orNull, shaped, TetherError } from './client.ts';
+import {
+  ANALYTICS_EVENTS,
+  attr,
+  attributesFromJson,
+  emit,
+  formatDate,
+  formatMoney,
+  get,
+  has,
+  hasTemplate,
+  isOwnEvent,
+  parseJSONAttr,
+  productUrl,
+  qsa,
+  repeat,
+  sel,
+  setImage,
+  setText,
+  show,
+} from './dom.ts';
+import { clearProductCache, getProduct } from './loader.ts';
+import { allPlans } from './selling-plans.ts';
+import { boundary, resolveProductKey } from './status.ts';
+import { Cart } from './cart.ts';
+import { scopes } from './product.ts';
+import { listSelector } from './collection.ts';
+import { liveLists, liveProducts, mountedProducts, mountProduct, pruneLive, within } from './mounting.ts';
+import { toCountry, toLanguage } from './market-codes.ts';
+import { isHttpsUrl } from './shopify-values.ts';
+import { PART_INTEGRITY } from './part-integrity.ts';
+import type { Parts, PartName, TetherInternals } from './lazy.ts';
+
+/**
+ * The core exports the parts use, shared instead of bundled twice, by the file name scripts/build.ts maps a part's
+ * imports to. Each file shares a list of values without their names: the build finds each value's export name in its
+ * module and hands a part's import of that name the value at its position. The core so carries no export names and no
+ * export a part doesn't use, and a part that imports one not listed here fails its build. A part reads its entries
+ * when it loads, once every module has run; read while the core runs, an import cycle through this file could leave
+ * a value unset.
+ */
+export const coreModules = {
+  get 'config.ts'() {
+    return [cfg, isConfigured, log, MARKET_SOURCES, parseMarkets, reportError, warn];
+  },
+  get 'client.ts'() {
+    return [endpoint, gql, orNull, shaped, TetherError];
+  },
+  get 'dom.ts'() {
+    return [
+      ANALYTICS_EVENTS,
+      attr,
+      attributesFromJson,
+      emit,
+      formatDate,
+      formatMoney,
+      get,
+      has,
+      hasTemplate,
+      isOwnEvent,
+      parseJSONAttr,
+      productUrl,
+      qsa,
+      repeat,
+      sel,
+      setImage,
+      setText,
+      show,
+    ];
+  },
+  get 'loader.ts'() {
+    return [clearProductCache, getProduct];
+  },
+  get 'selling-plans.ts'() {
+    return [allPlans];
+  },
+  get 'status.ts'() {
+    return [boundary, resolveProductKey];
+  },
+  get 'cart.ts'() {
+    return [Cart];
+  },
+  get 'product.ts'() {
+    return [scopes];
+  },
+  get 'collection.ts'() {
+    return [listSelector];
+  },
+  get 'mounting.ts'() {
+    return [liveLists, liveProducts, mountedProducts, mountProduct, pruneLive, within];
+  },
+  get 'market-codes.ts'() {
+    return [toCountry, toLanguage];
+  },
+  get 'shopify-values.ts'() {
+    return [isHttpsUrl];
+  },
+  // Parts that load other parts (account → account-pages) use this same loader.
+  get 'lazy.ts'() {
+    return [loadPart];
+  },
+};
+
+const MINIFIED_SCRIPT = /\.min\.js(\?|$)/;
+const coreScript = typeof document === 'undefined' ? '' : (document.currentScript?.getAttribute('src') ?? '');
+const coreScriptUrl = coreScript ? new URL(coreScript, document.baseURI).href : '';
+
+/** Parts loaded or loading. */
+const parts = new Map<PartName, Promise<unknown>>();
+
+/**
+ * The folder parts load from: the `partsUrl` (checked to be https or on this site when the config was resolved), else
+ * the core script's own folder. `null` when the core was not loaded by a `<script src>` (a module, a loader) and no
+ * `partsUrl` is set, so nothing says where parts are.
+ */
+function partsFolder(): string | null {
+  if (cfg.partsUrl) return new URL(cfg.partsUrl, document.baseURI).href;
+  if (!coreScriptUrl) return null;
+  return coreScriptUrl.replace(/[^/]*$/, '');
+}
+
+/**
+ * Pins the script to the part file built with this core, wherever it loads from: a page that pins the core with
+ * `integrity` then runs only parts of that build, and a `partsUrl` must serve the same release's files.
+ */
+function applyIntegrity(script: HTMLScriptElement, integrity: string): void {
+  script.integrity = integrity;
+  // A cross-origin script is only checked when fetched with CORS (CDNs such as jsDelivr allow it).
+  if (new URL(script.src).origin !== window.location.origin) script.crossOrigin = 'anonymous';
+}
+
+/**
+ * Loads a part's file. A failed load leaves the cache, so the next use tries again (the network may be back).
+ *
+ * @param integrity The file's hash from this core's build.
+ */
+function loadScript(name: PartName, folder: string, file: string, integrity: string): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const url = `${folder.replace(/\/?$/, '/')}${file}`;
+    const script = document.createElement('script');
+    script.src = url;
+    script.async = true;
+    applyIntegrity(script, integrity);
+    script.onload = () => {
+      const { Tether } = window as { Tether?: TetherInternals };
+      const part = Tether?.__parts[name];
+      if (part) {
+        resolve(part);
+        return;
+      }
+      parts.delete(name);
+      reject(new Error(`${url} did not register`));
+    };
+    script.onerror = () => {
+      parts.delete(name);
+      reject(
+        new Error(
+          `Could not load ${url}, or it is not the file built with this Tether script. Host the same release's files ` +
+            'next to the Tether script or at partsUrl.',
+        ),
+      );
+    };
+    document.head.appendChild(script);
+  });
+}
+
+/**
+ * @throws {Error} (rejected) When the part's file can't be loaded, fails its integrity check or doesn't register.
+ */
+export function loadPart<Name extends PartName>(name: Name): Promise<Parts[Name]> {
+  let loading = parts.get(name);
+  if (!loading) {
+    const folder = partsFolder();
+    if (folder === null) {
+      return Promise.reject(
+        new Error(`The Tether script's own location is unknown, so its ${name} part can't be found: set partsUrl.`),
+      );
+    }
+    const suffix = MINIFIED_SCRIPT.test(coreScriptUrl) || !coreScriptUrl ? '.min' : '';
+    const file = `tether.${name}${suffix}.js`;
+    const integrity = PART_INTEGRITY[file];
+    if (integrity === undefined) {
+      return Promise.reject(new Error(`This Tether script was built without ${file}, so it can't load that part.`));
+    }
+    loading = loadScript(name, folder, file, integrity);
+    parts.set(name, loading);
+  }
+  // A part's file is built from the module `Parts[Name]` names (scripts/build.ts), and registers that module.
+  return loading as Promise<Parts[Name]>;
+}

package/src/lazy.ts

@@ -0,0 +1,42 @@
+/**
+ * Optional parts that most pages never need, loaded on first use. In the ESM and Node builds they are dynamic
+ * imports, which bundlers split into their own chunks; the `<script>` build swaps this file for `lazy-iife.ts`
+ * (scripts/build.ts).
+ */
+
+export interface Parts {
+  diagnose: typeof import('./diagnose.ts');
+  markets: typeof import('./markets-ui.ts');
+  search: typeof import('./search.ts');
+  extras: typeof import('./extras.ts');
+  account: typeof import('./account.ts');
+  'account-pages': typeof import('./account-pages.ts');
+  analytics: typeof import('./analytics.ts');
+}
+export type PartName = keyof Parts;
+
+/**
+ * What `window.Tether` carries for the `<script>` build's separately loaded parts, besides the API sites use. Left out
+ * of the published `Tether` type.
+ */
+export interface TetherInternals {
+  /** `coreModules`: the modules the parts use instead of bundling copies, in the `<script>` build only. */
+  __core: unknown;
+  /** Each part registers its module here when its file has loaded. */
+  __parts: Partial<Parts>;
+}
+
+const PARTS: { [Name in PartName]: () => Promise<Parts[Name]> } = {
+  diagnose: () => import('./diagnose.ts'),
+  markets: () => import('./markets-ui.ts'),
+  search: () => import('./search.ts'),
+  extras: () => import('./extras.ts'),
+  account: () => import('./account.ts'),
+  'account-pages': () => import('./account-pages.ts'),
+  analytics: () => import('./analytics.ts'),
+};
+
+export const loadPart = <Name extends PartName>(name: Name): Promise<Parts[Name]> => PARTS[name]();
+
+/** Only the `<script>` build shares its modules with separately loaded parts. */
+export const coreModules = undefined;

package/src/{loader.js → loader.ts}

@@ -3,11 +3,15 @@
  * is cached for the life of the page, which survives Barba/Swup page swaps. Products the server rendered
  * (`tether/server` `hydrate()`) are used at once and refreshed once in the background.
  */
-import { cfg, log } from './config.js';
-import { gql, TetherError } from './client.js';
-import { productFragment, collectionFields } from './fragments.js';
-import { productKey } from './shopify-values.js';
-/** @import { Product, Image } from './fragments.js' */
+import { cfg, log } from './config.ts';
+import { gql, matches, orNull, shaped, TetherError } from './client.ts';
+import { productFragment, collectionFields } from './fragments.ts';
+import { productKey } from './shopify-values.ts';
+import { isRecord } from '../server/src/shared/json.ts';
+import { PRODUCT, PRODUCT_CONNECTION, PRODUCT_NODE } from './product-shape.ts';
+import type { Product, Image } from './fragments.ts';
+import type { QueryText } from './client.ts';
+import type { ProductConnection } from './product-shape.ts';
 
 /**
  * A product request that missed is remembered this long, so one page asking twice sends one request, and a product
@@ -17,16 +21,20 @@ const MISS_CACHE_MS = 10_000;
 /** A product loaded live this recently is newer than a server-rendered copy of it, which is then ignored. */
 const FRESH_MS = 60_000;
 
-/** @type {Map<string, Promise<Product>>} Handle or gid to the product, loaded or loading. */
-const productCache = new Map();
-/** @type {Map<string, { resolve: (product: Product) => void, reject: (error: unknown) => void }>} */
-const waiting = new Map();
-/** @type {Set<string>} Keys of products that came from the server and weren't refreshed yet. */
-const stale = new Set();
-/** @type {Map<string, number>} Handle or gid to when it last loaded live, in ms since the epoch. */
-const freshAt = new Map();
-/** @type {string[]} Keys for the next batch. */
-const pending = [];
+interface Waiter {
+  resolve: (product: Product) => void;
+  reject: (error: unknown) => void;
+}
+
+/** Handle or gid to the product, loaded or loading. */
+const productCache = new Map<string, Promise<Product>>();
+const waiting = new Map<string, Waiter>();
+/** Keys of products that came from the server and weren't refreshed yet. */
+const stale = new Set<string>();
+/** Handle or gid to when it last loaded live, in ms since the epoch. */
+const freshAt = new Map<string, number>();
+/** Keys for the next batch. */
+const pending: string[] = [];
 let flushScheduled = false;
 /**
  * Bumped by `clearProductCache()`: responses to requests sent before that (in the old market, after a country
@@ -34,18 +42,13 @@ let flushScheduled = false;
  */
 let generation = 0;
 
-/** @param {string} key */
-const isGid = (key) => key.startsWith('gid://');
+const isGid = (key: string) => key.startsWith('gid://');
 
 /** Accepts a handle, numeric id, gid or a full product URL. */
 export const normalizeProductKey = productKey;
 
-/**
- * Puts a product the page already has (from a collection query) in the cache, under its handle and its id.
- *
- * @param {Product | null | undefined} product
- */
-export function primeProduct(product) {
+/** Puts a product the page already has (from a collection query) in the cache, under its handle and its id. */
+export function primeProduct(product: Product | null | undefined): void {
   if (!product) return;
   const loaded = Promise.resolve(product);
   productCache.set(product.handle, loaded);
@@ -53,18 +56,16 @@ export function primeProduct(product) {
 }
 
 /**
- * @param {string | number | null | undefined} rawKey A handle, numeric id, gid or product URL.
- * @returns {Promise<Product>}
+ * @param rawKey A handle, numeric id, gid or product URL.
  * @throws {TetherError} `NOT_FOUND` (rejected) for an empty key or a product the store doesn't have.
  */
-export function getProduct(rawKey) {
+export function getProduct(rawKey: string | number | null | undefined): Promise<Product> {
   const key = normalizeProductKey(rawKey);
   if (!key) return Promise.reject(new TetherError('empty product key', { code: 'NOT_FOUND' }));
   const cached = productCache.get(key);
   if (cached) return cached;
 
-  /** @type {Promise<Product>} */
-  const loading = new Promise((resolve, reject) => {
+  const loading = new Promise<Product>((resolve, reject) => {
     waiting.set(key, { resolve, reject });
     pending.push(key);
     if (!flushScheduled) {
@@ -77,17 +78,25 @@ export function getProduct(rawKey) {
 }
 
 /**
- * @param {string[]} keys Handles and gids.
- * @returns {{ query: string, variables: Record<string, unknown>, handles: string[] }} One query for all of them: gids
- *   through `nodes(ids:)` as `byId`, each handle as its own alias `h<index>`.
+ * @param operation An operation that spreads `...TetherProduct`.
+ * @returns The operation with the product fragment (which starts on its own line), written for what the token may
+ *   read.
  */
-function batchQuery(keys) {
+const withProductFragment =
+  (operation: string): QueryText =>
+  (access) =>
+    `${operation}${productFragment(cfg, access)}`;
+
+/**
+ * @param keys Handles and gids.
+ * @returns One query for all of them: gids through `nodes(ids:)` as `byId`, each handle as its own alias `h<index>`.
+ */
+function batchQuery(keys: string[]): { query: QueryText; variables: Record<string, unknown>; handles: string[] } {
   const ids = keys.filter(isGid);
   const handles = keys.filter((key) => !isGid(key));
-  const definitions = [];
-  const selections = [];
-  /** @type {Record<string, unknown>} */
-  const variables = {};
+  const definitions: string[] = [];
+  const selections: string[] = [];
+  const variables: Record<string, unknown> = {};
   if (ids.length) {
     definitions.push('$ids: [ID!]!');
     variables['ids'] = ids;
@@ -98,25 +107,17 @@ function batchQuery(keys) {
     variables[`h${index}`] = handle;
     selections.push(`h${index}: product(handle: $h${index}) { ...TetherProduct }`);
   });
-  const query = `query TetherProducts(${definitions.join(',')}) { ${selections.join(' ')} } ${productFragment()}`;
+  const query = withProductFragment(`query TetherProducts(${definitions.join(',')}) { ${selections.join(' ')} }`);
   return { query, variables, handles };
 }
 
-/**
- * @param {string} key
- * @param {(waiter: { resolve: (product: Product) => void, reject: (error: unknown) => void }) => void} settle
- */
-function settleWaiting(key, settle) {
+function settleWaiting(key: string, settle: (waiter: Waiter) => void): void {
   const waiter = waiting.get(key);
   waiting.delete(key);
   if (waiter) settle(waiter);
 }
 
-/**
- * @param {string} key
- * @param {number} batchGeneration
- */
-function forgetMissLater(key, batchGeneration) {
+function forgetMissLater(key: string, batchGeneration: number): void {
   if (batchGeneration !== generation) return;
   const miss = productCache.get(key);
   setTimeout(() => {
@@ -124,6 +125,19 @@ function forgetMissLater(key, batchGeneration) {
   }, MISS_CACHE_MS);
 }
 
+/** A node of a type other than Product, for which `... on Product` selects no field. */
+interface OtherNode {
+  id?: undefined;
+}
+/** The answer to `batchQuery`: `byId` for the gids, `h<index>` for each handle. */
+type BatchData = Partial<Record<`h${number}`, Product | null>> & { byId?: (Product | OtherNode | null)[] };
+
+function isBatchData(data: unknown): data is BatchData {
+  if (!isRecord(data)) return false;
+  const { byId = [], ...byHandle } = data;
+  return matches(byId, [orNull(PRODUCT_NODE)]) && Object.values(byHandle).every(orNull(PRODUCT));
+}
+
 async function flush() {
   flushScheduled = false;
   const batchGeneration = generation;
@@ -132,10 +146,9 @@ async function flush() {
   const { query, variables, handles } = batchQuery(keys);
   log('fetch products', keys);
 
-  /** @type {Record<string, Product | null> & { byId?: (Product | null)[] }} */
   let data;
   try {
-    data = await gql(query, variables);
+    data = await gql(query, variables, isBatchData);
   } catch (error) {
     keys.forEach((key) => {
       settleWaiting(key, (waiter) => {
@@ -146,9 +159,8 @@ async function flush() {
     return;
   }
 
-  /** @type {Map<string, Product>} */
-  const found = new Map();
-  for (const product of data.byId ?? []) if (product) found.set(product.id, product);
+  const found = new Map<string, Product>();
+  for (const product of data.byId ?? []) if (product?.id) found.set(product.id, product);
   handles.forEach((handle, index) => {
     const product = data[`h${index}`];
     if (product) found.set(handle, product);
@@ -174,7 +186,7 @@ async function flush() {
 }
 
 /** Forgets every product, for a new market: requests already sent no longer fill the cache. */
-export function clearProductCache() {
+export function clearProductCache(): void {
   productCache.clear();
   generation += 1;
   stale.clear();
@@ -184,10 +196,8 @@ export function clearProductCache() {
 /**
  * Uses products the server rendered, unless the page loaded the same product live in the last `FRESH_MS` (an earlier
  * page of a View Transition visit), whose copy is newer.
- *
- * @param {readonly Product[] | null | undefined} products
  */
-export function hydrateProducts(products) {
+export function hydrateProducts(products: readonly Product[] | null | undefined): void {
   for (const product of products ?? []) {
     if (!product.id || !product.handle) continue;
     const loadedAgo = Date.now() - (freshAt.get(product.handle) ?? 0);
@@ -198,11 +208,8 @@ export function hydrateProducts(products) {
   }
 }
 
-/**
- * @param {string | number | null | undefined} rawKey
- * @returns {boolean} True once per server-rendered product: the caller then refreshes it.
- */
-export function takeStale(rawKey) {
+/** @returns True once per server-rendered product: the caller then refreshes it. */
+export function takeStale(rawKey: string | number | null | undefined): boolean {
   const key = normalizeProductKey(rawKey);
   if (!key || !stale.has(key)) return false;
   stale.delete(key);
@@ -210,46 +217,66 @@ export function takeStale(rawKey) {
   void productCache.get(key)?.then((product) => {
     stale.delete(product.handle);
     stale.delete(product.id);
-  });
+  }, failureIsReportedByTheRender);
   return true;
 }
 
 /**
- * Loads these products again, past the cache.
- *
- * @param {readonly (string | number)[]} keys
- * @returns {Promise<Product>[]}
+ * The cached promise is the one the product's render awaits, and the render reports its failure: the stale cleanup
+ * above has nothing left to do for a product that did not load.
  */
-export function refreshProducts(keys) {
-  for (const key of keys) {
-    const normalized = normalizeProductKey(key);
-    if (normalized) productCache.delete(normalized);
-  }
-  return keys.map((key) => getProduct(key));
+function failureIsReportedByTheRender() {
+  // Nothing to clean: see above.
 }
 
-/** @typedef {{ hasNextPage: boolean, endCursor: string | null }} PageInfo */
-/**
- * @typedef {object} Collection
- * @property {string} id
- * @property {string} handle
- * @property {string} title
- * @property {string} description
- * @property {string} descriptionHtml
- * @property {Image | null} image
- * @property {{ title: string | null, description: string | null }} seo
- */
-/** @typedef {{ collection: Collection | null, products: Product[], pageInfo: PageInfo }} ProductPage */
-/**
- * @typedef {object} ProductQuery
- * @property {string} [collection] A collection handle; without one, a search.
- * @property {string} [query] Storefront search syntax, for a search.
- * @property {number} [first]
- * @property {string | null} [after] The cursor of the page before.
- * @property {string} [sortKey] `ProductCollectionSortKeys` for a collection, `ProductSortKeys` for a search.
- * @property {boolean} [reverse]
- * @property {unknown[]} [filters] `ProductFilter` values, for a collection.
- */
+/** Loads this product again, past the cache. Products refreshed in the same tick go out as one request. */
+export function refreshProduct(key: string | number): Promise<Product> {
+  const normalized = normalizeProductKey(key);
+  if (normalized) productCache.delete(normalized);
+  return getProduct(key);
+}
+
+export interface PageInfo {
+  hasNextPage: boolean;
+  endCursor: string | null;
+}
+export interface Collection {
+  id: string;
+  handle: string;
+  title: string;
+  description: string;
+  descriptionHtml: string;
+  image: Image | null;
+  seo: { title: string | null; description: string | null };
+}
+export interface ProductPage {
+  collection: Collection | null;
+  products: Product[];
+  pageInfo: PageInfo;
+}
+export interface ProductQuery {
+  /** A collection handle; without one, a search. */
+  collection?: string;
+  /** Storefront search syntax, for a search. */
+  query?: string;
+  first?: number;
+  /** The cursor of the page before. */
+  after?: string | null;
+  /** `ProductCollectionSortKeys` for a collection, `ProductSortKeys` for a search. */
+  sortKey?: string;
+  reverse?: boolean;
+  /** `ProductFilter` values, for a collection. */
+  filters?: unknown[];
+}
+
+/** A collection's answer: `null` for a handle the store doesn't have. Its other fields are written as text. */
+export const isCollectionAnswer = shaped<{ collection: (Collection & { products: ProductConnection }) | null }>({
+  collection: orNull({ handle: 'string', products: PRODUCT_CONNECTION }),
+});
+export const isSearchAnswer = shaped<{ products: ProductConnection }>({ products: PRODUCT_CONNECTION });
+export const isRecommendationsAnswer = shaped<{ productRecommendations: Product[] | null }>({
+  productRecommendations: orNull([PRODUCT]),
+});
 
 const COLLECTION_QUERY = `query TetherCollection($handle: String!, $first: Int!, $after: String, $sortKey: ProductCollectionSortKeys, $reverse: Boolean, $filters: [ProductFilter!]) {
   collection(handle: $handle) {
@@ -271,8 +298,6 @@ const SEARCH_QUERY = `query TetherSearch($first: Int!, $after: String, $query: S
 /**
  * A page of products from a collection (by handle) or from a search. Every product on it is cached.
  *
- * @param {ProductQuery} [options]
- * @returns {Promise<ProductPage>}
  * @throws {TetherError} `NOT_FOUND` for a collection the store doesn't have.
  */
 export async function getProducts({
@@ -283,32 +308,31 @@ export async function getProducts({
   sortKey,
   reverse = false,
   filters,
-} = {}) {
-  const fragment = productFragment();
+}: ProductQuery = {}): Promise<ProductPage> {
   if (collection) {
-    /** @type {{ collection: (Collection & { products: { nodes: Product[], pageInfo: PageInfo } }) | null }} */
-    const data = await gql(`${COLLECTION_QUERY}\n${fragment}`, {
-      handle: collection,
-      first,
-      after,
-      sortKey: sortKey || undefined,
-      reverse,
-      filters: filters ?? undefined,
-    });
+    const data = await gql(
+      withProductFragment(COLLECTION_QUERY),
+      {
+        handle: collection,
+        first,
+        after,
+        sortKey: sortKey || undefined,
+        reverse,
+        filters: filters ?? undefined,
+      },
+      isCollectionAnswer,
+    );
     if (!data.collection) throw new TetherError(`Collection not found: ${collection}`, { code: 'NOT_FOUND' });
     const { products, ...rest } = data.collection;
     products.nodes.forEach(primeProduct);
     return { collection: rest, products: products.nodes, pageInfo: products.pageInfo };
   }
 
-  /** @type {{ products: { nodes: Product[], pageInfo: PageInfo } }} */
-  const data = await gql(`${SEARCH_QUERY}\n${fragment}`, {
-    first,
-    after,
-    query: query || undefined,
-    sortKey: sortKey || undefined,
-    reverse,
-  });
+  const data = await gql(
+    withProductFragment(SEARCH_QUERY),
+    { first, after, query: query || undefined, sortKey: sortKey || undefined, reverse },
+    isSearchAnswer,
+  );
   data.products.nodes.forEach(primeProduct);
   return { collection: null, products: data.products.nodes, pageInfo: data.products.pageInfo };
 }
@@ -316,20 +340,22 @@ export async function getProducts({
 /**
  * Shopify's recommendations for a product. Every product in them is cached.
  *
- * @param {string | number | { id: string } | null | undefined} product A product, or its handle, id or gid.
- * @param {'RELATED' | 'COMPLEMENTARY'} [intent]
- * @returns {Promise<Product[]>}
+ * @param product A product, or its handle, id or gid.
  */
-export async function getRecommendations(product, intent = 'RELATED') {
+export async function getRecommendations(
+  product: string | number | { id: string } | null | undefined,
+  intent: 'RELATED' | 'COMPLEMENTARY' = 'RELATED',
+): Promise<Product[]> {
   const key = normalizeProductKey(typeof product === 'object' ? product?.id : product);
   const byId = key?.startsWith('gid://') ?? false;
-  /** @type {{ productRecommendations: Product[] | null }} */
   const data = await gql(
-    `query TetherRecs(${byId ? '$id: ID!' : '$handle: String!'}, $intent: ProductRecommendationIntent) {
+    withProductFragment(
+      `query TetherRecs(${byId ? '$id: ID!' : '$handle: String!'}, $intent: ProductRecommendationIntent) {
   productRecommendations(${byId ? 'productId: $id' : 'productHandle: $handle'}, intent: $intent) { ...TetherProduct }
-}
-${productFragment()}`,
+}`,
+    ),
     byId ? { id: key, intent } : { handle: key, intent },
+    isRecommendationsAnswer,
   );
   const list = data.productRecommendations ?? [];
   list.forEach(primeProduct);

package/src/market-codes.ts

@@ -0,0 +1,6 @@
+/**
+ * Country and language codes as Shopify's `@inContext` takes them, parsed by the module the Worker uses for the
+ * login's market, so the browser and the Worker accept and refuse the same values.
+ */
+export { toCountry, toLanguage } from '../server/src/shared/market-codes.ts';
+export type { CountryCode, LanguageCode } from '../server/src/shared/market-codes.ts';