@occluze/tether 0.6.7 → 0.6.8

package/src/loader.js

@@ -1,162 +1,257 @@
 /**
- * Data loading. Products are batched per tick into one request and cached for
- * the lifetime of the page (survives Barba/Swup page swaps).
+ * 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' */
 
-const productCache = new Map(); // key -> Promise<product>
-let pending = [];
-const resolvers = new Map();
-let scheduled = false;
-// Bumped by clearProductCache(): responses to requests sent before that (e.g. in the old
-// market after a country switch) still reach their callers but never refill the cache.
+/**
+ * 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;
 
-const isGid = (v) => typeof v === 'string' && v.startsWith('gid://');
+/** @param {string} key */
+const isGid = (key) => key.startsWith('gid://');
 
 /** Accepts a handle, numeric id, gid or a full product URL. */
-export function normalizeProductKey(raw) {
-  const v = String(raw ?? '').trim();
-  if (!v) return null;
-  if (isGid(v)) return v;
-  if (/^\d+$/.test(v)) return `gid://shopify/Product/${v}`;
-  const m = v.match(/\/products\/([^/?#]+)/);
-  return m ? m[1] : v;
-}
+export const normalizeProductKey = productKey;
 
-/** Put a product we already have (from a collection query) in the cache. */
+/**
+ * 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 p = Promise.resolve(product);
-  productCache.set(product.handle, p);
-  productCache.set(product.id, p);
+  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' }));
-  if (productCache.has(key)) return productCache.get(key);
+  const cached = productCache.get(key);
+  if (cached) return cached;
 
-  const p = new Promise((resolve, reject) => {
-    resolvers.set(key, { resolve, reject });
+  /** @type {Promise<Product>} */
+  const loading = new Promise((resolve, reject) => {
+    waiting.set(key, { resolve, reject });
     pending.push(key);
-    if (!scheduled) {
-      scheduled = true;
-      setTimeout(flush, 0);
+    if (!flushScheduled) {
+      flushScheduled = true;
+      setTimeout(() => void flush(), 0);
     }
   });
-  productCache.set(key, p);
-  return p;
+  productCache.set(key, loading);
+  return loading;
 }
 
-async function flush() {
-  scheduled = false;
-  const gen = generation;
-  const keys = pending.splice(0);
-  if (!keys.length) return;
-
+/**
+ * @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((k) => !isGid(k));
-  const defs = [];
-  const parts = [];
-  const vars = {};
-
+  const handles = keys.filter((key) => !isGid(key));
+  const definitions = [];
+  const selections = [];
+  /** @type {Record<string, unknown>} */
+  const variables = {};
   if (ids.length) {
-    defs.push('$ids: [ID!]!');
-    vars.ids = ids;
-    parts.push('byId: nodes(ids: $ids) { ... on Product { ...TetherProduct } }');
+    definitions.push('$ids: [ID!]!');
+    variables['ids'] = ids;
+    selections.push('byId: nodes(ids: $ids) { ... on Product { ...TetherProduct } }');
   }
-  handles.forEach((h, i) => {
-    defs.push(`$h${i}: String!`);
-    vars[`h${i}`] = h;
-    parts.push(`h${i}: product(handle: $h${i}) { ...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 };
+}
 
-  const query = `query TetherProducts(${defs.join(',')}) { ${parts.join(' ')} } ${productFragment()}`;
-  log('fetch products', keys);
+/**
+ * @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);
+}
 
-  const settle = (k, fn) => {
-    const r = resolvers.get(k);
-    resolvers.delete(k);
-    if (r) fn(r);
-  };
+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 {
-    const data = await gql(query, vars);
-    const got = new Map();
-    (data.byId || []).forEach((p) => { if (p) got.set(p.id, p); });
-    handles.forEach((h, i) => { if (data[`h${i}`]) got.set(h, data[`h${i}`]); });
-
-    keys.forEach((k) => settle(k, (r) => {
-      if (got.has(k)) {
-        const p = got.get(k);
-        if (gen === generation) { primeProduct(p); freshAt.set(p.handle, Date.now()); freshAt.set(p.id, Date.now()); }
-        r.resolve(p);
-      } else {
-        // A miss is remembered for a few seconds (one page load asking twice makes one request),
-        // not longer: a product published in Shopify shows up on the next visit.
-        const miss = productCache.get(k);
-        if (gen === generation) setTimeout(() => { if (productCache.get(k) === miss) productCache.delete(k); }, 10000);
-        r.reject(new TetherError(`Product not found: ${k}`, { code: 'NOT_FOUND' }));
-      }
-    }));
-  } catch (err) {
-    keys.forEach((k) => settle(k, (r) => { if (gen === generation) productCache.delete(k); r.reject(err); }));
+    data = await gql(query, variables);
+  } catch (error) {
+    keys.forEach((key) => {
+      settleWaiting(key, (waiter) => {
+        if (batchGeneration === generation) productCache.delete(key);
+        waiter.reject(error);
+      });
+    });
+    return;
   }
-}
 
-export function clearProductCache() { productCache.clear(); generation++; stale.clear(); freshAt.clear(); }
+  /** @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);
+  });
 
-// ---------------------------------------------------------------------------
-// Hydration: products rendered on the server (tether/server hydrate()) are used at once and
-// refreshed once in the background, so prices and stock are live without a loading state.
-// ---------------------------------------------------------------------------
+  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);
+    });
+  });
+}
 
-const stale = new Set(); // keys of products that came from the server and weren't refreshed yet
-const freshAt = new Map(); // key -> when it was last loaded live (this page session)
-const FRESH_MS = 60000;
+/** 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) {
-  (products || []).forEach((p) => {
-    if (!p?.id || !p.handle) return;
-    // Loaded live in the last minute (an earlier page of a View Transition visit): that copy is newer.
-    if (Date.now() - (freshAt.get(p.handle) || 0) < FRESH_MS && productCache.has(p.handle)) return;
-    primeProduct(p);
-    stale.add(p.handle);
-    stale.add(p.id);
-  });
+  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);
+  }
 }
 
-/** True once per server-provided product: the caller refreshes it. */
-export function takeStale(key) {
-  const k = normalizeProductKey(key);
-  if (!stale.has(k)) return false;
-  const p = productCache.get(k);
-  stale.delete(k);
-  // Both keys point to the same product: refresh it once.
-  p?.then?.((x) => { stale.delete(x.handle); stale.delete(x.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;
 }
 
-/** Fetch these products again (bypassing the cache). */
+/**
+ * Loads these products again, past the cache.
+ *
+ * @param {readonly (string | number)[]} keys
+ * @returns {Promise<Product>[]}
+ */
 export function refreshProducts(keys) {
-  keys.forEach((k) => productCache.delete(normalizeProductKey(k)));
-  return keys.map((k) => getProduct(k));
+  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 */
 /**
- * A page of products from a collection (by handle) or from a search query.
- * Returns { collection, products, 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.
  */
-export async function getProducts({
-  collection, query, first = cfg.collectionFirst, after = null, sortKey, reverse = false, filters,
-} = {}) {
-  const fragment = productFragment();
 
-  if (collection) {
-    const data = await gql(`query TetherCollection($handle: String!, $first: Int!, $after: String, $sortKey: ProductCollectionSortKeys, $reverse: Boolean, $filters: [ProductFilter!]) {
+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) {
@@ -164,9 +259,41 @@ export async function getProducts({
       pageInfo { hasNextPage endCursor }
     }
   }
-}
-${fragment}`, {
-      handle: collection, first, after, sortKey: sortKey || undefined, reverse, filters: filters || undefined,
+}`;
+
+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;
@@ -174,25 +301,37 @@ ${fragment}`, {
     return { collection: rest, products: products.nodes, pageInfo: products.pageInfo };
   }
 
-  const data = await gql(`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 }
-  }
-}
-${fragment}`, { first, after, query: query || undefined, sortKey: sortKey || undefined, reverse });
+  /** @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://');
-  const data = await gql(`query TetherRecs(${byId ? '$id: ID!' : '$handle: String!'}, $intent: ProductRecommendationIntent) {
+  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 || [];
+${productFragment()}`,
+    byId ? { id: key, intent } : { handle: key, intent },
+  );
+  const list = data.productRecommendations ?? [];
   list.forEach(primeProduct);
   return list;
 }

package/src/market-codes.js

@@ -0,0 +1,35 @@
+/**
+ * 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;
+}