@occluze/tether 0.6.8 → 0.7.1

package/src/loader.js

@@ -1,337 +0,0 @@
-/**
- * Product data for the browser script. Products asked for in the same tick go out as one request, and every product
- * 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' */
-
-/**
- * A product request that missed is remembered this long, so one page asking twice sends one request, and a product
- * published in Shopify meanwhile shows up on the next visit.
- */
-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 = [];
-let flushScheduled = false;
-/**
- * Bumped by `clearProductCache()`: responses to requests sent before that (in the old market, after a country
- * switch) still reach their callers but never refill the cache.
- */
-let generation = 0;
-
-/** @param {string} key */
-const isGid = (key) => 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) {
-  if (!product) return;
-  const loaded = Promise.resolve(product);
-  productCache.set(product.handle, loaded);
-  productCache.set(product.id, loaded);
-}
-
-/**
- * @param {string | number | null | undefined} rawKey A handle, numeric id, gid or product URL.
- * @returns {Promise<Product>}
- * @throws {TetherError} `NOT_FOUND` (rejected) for an empty key or a product the store doesn't have.
- */
-export function getProduct(rawKey) {
-  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) => {
-    waiting.set(key, { resolve, reject });
-    pending.push(key);
-    if (!flushScheduled) {
-      flushScheduled = true;
-      setTimeout(() => void flush(), 0);
-    }
-  });
-  productCache.set(key, loading);
-  return loading;
-}
-
-/**
- * @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>`.
- */
-function batchQuery(keys) {
-  const ids = keys.filter(isGid);
-  const handles = keys.filter((key) => !isGid(key));
-  const definitions = [];
-  const selections = [];
-  /** @type {Record<string, unknown>} */
-  const variables = {};
-  if (ids.length) {
-    definitions.push('$ids: [ID!]!');
-    variables['ids'] = ids;
-    selections.push('byId: nodes(ids: $ids) { ... on Product { ...TetherProduct } }');
-  }
-  handles.forEach((handle, index) => {
-    definitions.push(`$h${index}: String!`);
-    variables[`h${index}`] = handle;
-    selections.push(`h${index}: product(handle: $h${index}) { ...TetherProduct }`);
-  });
-  const query = `query TetherProducts(${definitions.join(',')}) { ${selections.join(' ')} } ${productFragment()}`;
-  return { query, variables, handles };
-}
-
-/**
- * @param {string} key
- * @param {(waiter: { resolve: (product: Product) => void, reject: (error: unknown) => void }) => void} settle
- */
-function settleWaiting(key, settle) {
-  const waiter = waiting.get(key);
-  waiting.delete(key);
-  if (waiter) settle(waiter);
-}
-
-/**
- * @param {string} key
- * @param {number} batchGeneration
- */
-function forgetMissLater(key, batchGeneration) {
-  if (batchGeneration !== generation) return;
-  const miss = productCache.get(key);
-  setTimeout(() => {
-    if (productCache.get(key) === miss) productCache.delete(key);
-  }, MISS_CACHE_MS);
-}
-
-async function flush() {
-  flushScheduled = false;
-  const batchGeneration = generation;
-  const keys = pending.splice(0);
-  if (!keys.length) return;
-  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);
-  } catch (error) {
-    keys.forEach((key) => {
-      settleWaiting(key, (waiter) => {
-        if (batchGeneration === generation) productCache.delete(key);
-        waiter.reject(error);
-      });
-    });
-    return;
-  }
-
-  /** @type {Map<string, Product>} */
-  const found = new Map();
-  for (const product of data.byId ?? []) if (product) found.set(product.id, product);
-  handles.forEach((handle, index) => {
-    const product = data[`h${index}`];
-    if (product) found.set(handle, product);
-  });
-
-  const now = Date.now();
-  keys.forEach((key) => {
-    settleWaiting(key, (waiter) => {
-      const product = found.get(key);
-      if (!product) {
-        forgetMissLater(key, batchGeneration);
-        waiter.reject(new TetherError(`Product not found: ${key}`, { code: 'NOT_FOUND' }));
-        return;
-      }
-      if (batchGeneration === generation) {
-        primeProduct(product);
-        freshAt.set(product.handle, now);
-        freshAt.set(product.id, now);
-      }
-      waiter.resolve(product);
-    });
-  });
-}
-
-/** Forgets every product, for a new market: requests already sent no longer fill the cache. */
-export function clearProductCache() {
-  productCache.clear();
-  generation += 1;
-  stale.clear();
-  freshAt.clear();
-}
-
-/**
- * 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) {
-  for (const product of products ?? []) {
-    if (!product.id || !product.handle) continue;
-    const loadedAgo = Date.now() - (freshAt.get(product.handle) ?? 0);
-    if (loadedAgo < FRESH_MS && productCache.has(product.handle)) continue;
-    primeProduct(product);
-    stale.add(product.handle);
-    stale.add(product.id);
-  }
-}
-
-/**
- * @param {string | number | null | undefined} rawKey
- * @returns {boolean} True once per server-rendered product: the caller then refreshes it.
- */
-export function takeStale(rawKey) {
-  const key = normalizeProductKey(rawKey);
-  if (!key || !stale.has(key)) return false;
-  stale.delete(key);
-  // The handle and the id point to the same product: one refresh covers both.
-  void productCache.get(key)?.then((product) => {
-    stale.delete(product.handle);
-    stale.delete(product.id);
-  });
-  return true;
-}
-
-/**
- * Loads these products again, past the cache.
- *
- * @param {readonly (string | number)[]} keys
- * @returns {Promise<Product>[]}
- */
-export function refreshProducts(keys) {
-  for (const key of keys) {
-    const normalized = normalizeProductKey(key);
-    if (normalized) productCache.delete(normalized);
-  }
-  return keys.map((key) => getProduct(key));
-}
-
-/** @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.
- */
-
-const COLLECTION_QUERY = `query TetherCollection($handle: String!, $first: Int!, $after: String, $sortKey: ProductCollectionSortKeys, $reverse: Boolean, $filters: [ProductFilter!]) {
-  collection(handle: $handle) {
-    ${collectionFields()}
-    products(first: $first, after: $after, sortKey: $sortKey, reverse: $reverse, filters: $filters) {
-      nodes { ...TetherProduct }
-      pageInfo { hasNextPage endCursor }
-    }
-  }
-}`;
-
-const SEARCH_QUERY = `query TetherSearch($first: Int!, $after: String, $query: String, $sortKey: ProductSortKeys, $reverse: Boolean) {
-  products(first: $first, after: $after, query: $query, sortKey: $sortKey, reverse: $reverse) {
-    nodes { ...TetherProduct }
-    pageInfo { hasNextPage endCursor }
-  }
-}`;
-
-/**
- * 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({
-  collection,
-  query,
-  first = cfg.collectionFirst,
-  after = null,
-  sortKey,
-  reverse = false,
-  filters,
-} = {}) {
-  const fragment = productFragment();
-  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,
-    });
-    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,
-  });
-  data.products.nodes.forEach(primeProduct);
-  return { collection: null, products: data.products.nodes, pageInfo: data.products.pageInfo };
-}
-
-/**
- * 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[]>}
- */
-export async function getRecommendations(product, intent = 'RELATED') {
-  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) {
-  productRecommendations(${byId ? 'productId: $id' : 'productHandle: $handle'}, intent: $intent) { ...TetherProduct }
-}
-${productFragment()}`,
-    byId ? { id: key, intent } : { handle: key, intent },
-  );
-  const list = data.productRecommendations ?? [];
-  list.forEach(primeProduct);
-  return list;
-}

package/src/market-codes.js

@@ -1,35 +0,0 @@
-/**
- * Country and language codes as Shopify's `@inContext` takes them. Every market value that reaches a query passes
- * through here: they are written into the query text, so anything else is dropped rather than sent.
- */
-
-/** @typedef {string & { readonly __brand: 'CountryCode' }} CountryCode An ISO 3166-1 alpha-2 code, upper case. */
-/** @typedef {string & { readonly __brand: 'LanguageCode' }} LanguageCode A Shopify `LanguageCode` value. */
-
-const COUNTRY = /^[A-Z]{2}$/;
-/** Cloudflare's codes for an unknown country (XX) and Tor (T1), which a `cf-ipcountry` cookie can carry. */
-const NOT_A_COUNTRY = new Set(['XX', 'T1']);
-/** Shopify `LanguageCode` values with a region. Every other language is its plain ISO 639 code. */
-const REGIONAL_LANGUAGES = new Set(['PT_BR', 'PT_PT', 'ZH_CN', 'ZH_TW']);
-const LANGUAGE = /^[A-Z]{2,3}$/;
-
-/**
- * @param {unknown} value
- * @returns {CountryCode | null} `'de'` → `'DE'`; `null` for anything that is not a country code.
- */
-export function toCountry(value) {
-  const code = (typeof value === 'string' ? value : '').trim().toUpperCase();
-  if (!COUNTRY.test(code) || NOT_A_COUNTRY.has(code)) return null;
-  return /** @type {CountryCode} */ (code);
-}
-
-/**
- * @param {unknown} value
- * @returns {LanguageCode | null} `'de-DE'` → `'DE'`, `'pt-BR'` → `'PT_BR'`, `'en'` → `'EN'`; `null` otherwise.
- */
-export function toLanguage(value) {
-  const raw = (typeof value === 'string' ? value : '').trim().replace('-', '_').toUpperCase();
-  if (REGIONAL_LANGUAGES.has(raw)) return /** @type {LanguageCode} */ (raw);
-  const primary = raw.split('_')[0] ?? '';
-  return LANGUAGE.test(primary) ? /** @type {LanguageCode} */ (primary) : null;
-}

package/src/markets-ui.js

@@ -1,204 +0,0 @@
-/**
- * Optional part, loaded on first use: market detection, `select[tether-country-select]`, `tether-country-bind` and
- * `Tether.setCountry()`. See markets.js for the detection rules.
- */
-import { cfg, reportError } from './config.js';
-import { TetherError } from './client.js';
-import { Cart } from './cart.js';
-import { listSelector } from './collection.js';
-import { clearProductCache } from './loader.js';
-import { attr, sel, get, emit } from './dom.js';
-import { within, pruneLive, liveLists, liveProducts, mountedProducts, mountProduct } from './mounting.js';
-import { rememberMarket, getLocalization, clearLocalization } from './markets.js';
-import { toCountry, toLanguage } from './market-codes.js';
-/** @import { LocalizedCountry, Localization } from './markets.js' */
-/** @import { CountryCode } from './market-codes.js' */
-
-export { detectMarket, getLocalization } from './markets.js';
-
-const DEFAULT_LABEL = '{name} ({currency})';
-const DEFAULT_BIND = 'name';
-
-/**
- * @typedef {object} SetCountryOptions
- * @property {string | null | undefined} [language] A Shopify language; `null` clears it. Default: the
- *   `markets.locales` entry for the country, else unchanged.
- * @property {string | undefined} [locale] The money format. Default: the `markets.locales` entry, else unchanged.
- * @property {boolean | undefined} [remember] Save the choice for the next pages (default true).
- */
-
-/**
- * @param {LocalizedCountry} country
- * @param {string} field A `tether-country-bind` value or a label placeholder: `name`, `code`, `currency`, `symbol`.
- * @returns {string} `''` for any other field.
- */
-function countryField(country, field) {
-  switch (field) {
-    case 'name':
-      return country.name;
-    case 'code':
-      return country.isoCode;
-    case 'currency':
-      return country.currency.isoCode;
-    case 'symbol':
-      return country.currency.symbol;
-    default:
-      return '';
-  }
-}
-
-/**
- * @param {string} template `tether-country-label`, e.g. `{name} ({currency})`.
- * @param {LocalizedCountry} country
- */
-const fillLabel = (template, country) =>
-  template.replace(/\{(name|code|currency|symbol)\}/g, (_match, /** @type {string} */ field) =>
-    countryField(country, field),
-  );
-
-/**
- * @param {HTMLSelectElement} select
- * @param {LocalizedCountry[]} countries The store's countries, sorted by name.
- * @param {string} current The country in use.
- */
-function fillCountrySelect(select, countries, current) {
-  const template = select.getAttribute(attr('country-label')) || DEFAULT_LABEL;
-  // tether-countries="NL,DE,BE": only these, in that order; otherwise every country of the store.
-  const only = (select.getAttribute(attr('countries')) || '')
-    .toUpperCase()
-    .split(/[\s,]+/)
-    .filter(Boolean);
-  const listed = only.length
-    ? only
-        .map((code) => countries.find((country) => country.isoCode === code))
-        .filter((country) => country !== undefined)
-    : countries;
-  select.replaceChildren(...listed.map((country) => new Option(fillLabel(template, country), country.isoCode)));
-  select.value = current;
-  // A country the store doesn't sell to selects nothing.
-  if (select.value !== current) select.selectedIndex = -1;
-  select.disabled = listed.length < 2 && !select.hasAttribute(attr('always-enabled'));
-}
-
-/**
- * @param {HTMLSelectElement[]} selects
- * @param {HTMLElement[]} binds
- * @param {Localization} localization
- */
-function fillCountries(selects, binds, localization) {
-  const current = (cfg.country || localization.country.isoCode).toUpperCase();
-  const countries = [...localization.availableCountries].sort((a, b) =>
-    a.name.localeCompare(b.name, cfg.locale || undefined),
-  );
-  const inUse = countries.find((country) => country.isoCode === current) ?? localization.country;
-  selects.forEach((select) => {
-    fillCountrySelect(select, countries, current);
-  });
-  binds.forEach((el) => {
-    el.textContent = countryField(inUse, get(el, 'country-bind') || DEFAULT_BIND);
-  });
-}
-
-/**
- * Fills `select[tether-country-select]` with the countries the store sells to (Shopify Markets), and
- * `tether-country-bind="name|code|currency|symbol"` with the current country. `tether-country-label` sets the option
- * text from `{name}`, `{code}`, `{currency}` and `{symbol}`. A failure is reported, never thrown.
- *
- * @param {ParentNode} [root]
- * @returns {Promise<void>}
- */
-export function renderCountrySelects(root = document) {
-  const selects = /** @type {HTMLSelectElement[]} */ (within(root, `select${sel('country-select')}`));
-  const binds = within(root, sel('country-bind'));
-  if (!selects.length && !binds.length) return Promise.resolve();
-  return getLocalization()
-    .then((localization) => {
-      fillCountries(selects, binds, localization);
-    })
-    .catch((/** @type {unknown} */ error) => {
-      reportError(error, 'country select');
-    });
-}
-
-/**
- * @param {CountryCode} country
- * @returns {{ country?: string, language?: string, locale?: string } | undefined} The `markets.locales` entry for it.
- */
-const localeEntryFor = (country) =>
-  Object.values(cfg.markets?.locales ?? {}).find((entry) => toCountry(entry.country) === country);
-
-/**
- * @param {string | null | undefined} language The `setCountry()` option.
- * @param {{ language?: string } | undefined} entry The `markets.locales` entry for the country.
- * @returns {string | null | undefined} The option, else the entry's language (which may have none), else unchanged.
- */
-function languageFor(language, entry) {
-  if (language !== undefined) return toLanguage(language);
-  if (!entry) return cfg.language;
-  return entry.language ? toLanguage(entry.language) : undefined;
-}
-
-/**
- * Loads every live product and list again in the market `cfg` now holds, and moves an existing cart to `country`.
- *
- * @param {CountryCode} country
- * @returns {Promise<unknown>[]} The cart update and the list loads.
- */
-function rerenderInMarket(country) {
-  clearProductCache();
-  /** @type {Promise<unknown>[]} */
-  const jobs = [];
-  // Only an existing cart moves; switching country never creates one.
-  if (Cart.id()) {
-    jobs.push(
-      Cart.setBuyerIdentity({ countryCode: country }, { create: false }).catch((/** @type {unknown} */ error) => {
-        reportError(error, 'cart country');
-      }),
-    );
-  }
-  pruneLive();
-  liveLists.forEach((list) => jobs.push(list.load()));
-  liveProducts.forEach((el) => {
-    // A product inside a list is re-rendered by its list.
-    if (el.closest(listSelector())) return;
-    mountedProducts.delete(el);
-    mountProduct(el);
-  });
-  return jobs;
-}
-
-/**
- * Switches the market: prices, currency and translations follow (`@inContext`), the cart's
- * `buyerIdentity.countryCode` is updated, and every product and list on the page re-renders.
- *
- *   Tether.setCountry('DE')            Tether.setCountry('BE', { language: 'FR' })
- *
- * @param {string} code
- * @param {SetCountryOptions} [options]
- * @returns {Promise<typeof Cart.state>} The cart once everything is in the new market.
- * @throws {TetherError} `INVALID_COUNTRY` for anything that isn't a country code.
- */
-export async function setCountry(code, { language, locale, remember = true } = {}) {
-  const country = toCountry(code);
-  if (!country) throw new TetherError(`Not a country code: ${code}`, { code: 'INVALID_COUNTRY' });
-  const entry = localeEntryFor(country);
-  const ownLocale = locale || entry?.locale;
-  const nextLocale = ownLocale || cfg.locale;
-  const nextLanguage = languageFor(language, entry);
-  const changed = country !== cfg.country?.toUpperCase() || nextLanguage !== cfg.language || nextLocale !== cfg.locale;
-  cfg.country = country;
-  cfg.language = nextLanguage || undefined;
-  cfg.locale = nextLocale;
-  if (remember) rememberMarket({ country, language: nextLanguage, locale: ownLocale });
-  if (!changed) {
-    void renderCountrySelects();
-    return Cart.state;
-  }
-  // Country names follow the language.
-  if (language !== undefined) clearLocalization();
-  const jobs = rerenderInMarket(country);
-  void renderCountrySelects();
-  emit('country-changed', { country, language: cfg.language });
-  await Promise.all(jobs);
-  return Cart.state;
-}