@occluze/tether 0.6.8 → 0.7.0

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

@@ -1,16 +1,26 @@
 /**
  * The product scopes and lists on the page: mounting a product root, the live roots a country switch re-renders, and
- * the products the server rendered into the page. Shared by `index.js` and the optional markets part.
+ * the products the server rendered into the page. Shared by `index.ts` and the optional markets part.
  */
-import { cfg, log, warn, reportError } from './config.js';
-import { ProductScope, scopes, rememberOptionNames } from './product.js';
-import { listSelector } from './collection.js';
-import { getProduct, takeStale, refreshProducts, hydrateProducts } from './loader.js';
-import { resolveProductKey, setScopeStatus, isNotFound } from './status.js';
-import { attr, get, qsa, emit } from './dom.js';
-/** @import { Product } from './fragments.js' */
+import { cfg, log, warn, reportError } from './config.ts';
+import { ProductScope, scopes, rememberOptionNames } from './product.ts';
+import { listSelector } from './collection.ts';
+import { getProduct, takeStale, refreshProduct, hydrateProducts } from './loader.ts';
+import { resolveProductKey, setScopeStatus, isNotFound } from './status.ts';
+import { attr, get, qsa, emit } from './dom.ts';
+import { toCountry, toLanguage } from './market-codes.ts';
+import { isRecord } from '../server/src/shared/json.ts';
+import { isProductShape } from './product-shape.ts';
+import type { Product } from './fragments.ts';
+import type { CountryCode, LanguageCode } from './market-codes.ts';
 
-/** @typedef {{ root: Element, load: (more?: boolean) => Promise<unknown> }} MountedList A mounted `ListScope`. */
+/** A mounted `ListScope`. */
+interface MountedList {
+  root: Element;
+  load: (more?: boolean) => Promise<unknown>;
+}
+
+type KeySource = Pick<ReturnType<typeof resolveProductKey>, 'fromUrl' | 'raw'>;
 
 /**
  * The marker on the `<script type="application/json">` tags `tether/server`'s `hydrate()` writes. It is fixed, not
@@ -18,19 +28,17 @@ import { attr, get, qsa, emit } from './dom.js';
  */
 const HYDRATE_SELECTOR = 'script[type="application/json"][data-tether-hydrate]';
 
-/** @type {WeakSet<Element>} */
-export const mountedProducts = new WeakSet();
-/** @type {WeakSet<Element>} */
-export const mountedLists = new WeakSet();
-/** @type {Set<HTMLElement>} Product roots to re-render after a country switch; pruned once disconnected. */
-export const liveProducts = new Set();
-/** @type {Set<MountedList>} Lists to reload after a country switch; pruned once disconnected. */
-export const liveLists = new Set();
-/** @type {WeakMap<Element, object>} Each product root's latest request, so a slow older response can't win. */
-const latestRequest = new WeakMap();
+export const mountedProducts = new WeakSet<Element>();
+export const mountedLists = new WeakSet<Element>();
+/** Product roots to re-render after a country switch; pruned once disconnected. */
+export const liveProducts = new Set<HTMLElement>();
+/** Lists to reload after a country switch; pruned once disconnected. */
+export const liveLists = new Set<MountedList>();
+/** Each product root's latest request, so a slow older response can't win. */
+const latestRequest = new WeakMap<Element, object>();
 
 /** Forgets roots a page transition removed, so they aren't kept alive. */
-export function pruneLive() {
+export function pruneLive(): void {
   liveProducts.forEach((el) => {
     if (!el.isConnected) liveProducts.delete(el);
   });
@@ -39,23 +47,15 @@ export function pruneLive() {
   });
 }
 
-/**
- * @param {ParentNode & Partial<Pick<Element, 'matches'>>} root
- * @param {string} selector
- * @returns {HTMLElement[]} `root` itself when it matches, then the matches inside it.
- */
-export function within(root, selector) {
-  const self = root.matches?.(selector) ? [/** @type {HTMLElement} */ (root)] : [];
+/** @returns `root` itself when it matches, then the matches inside it. */
+export function within(root: ParentNode & Partial<Pick<Element, 'matches'>>, selector: string): HTMLElement[] {
+  // A root that matches carries Tether's markup, which goes on HTML elements (see `qsa`).
+  const self = root.matches?.(selector) ? [root as HTMLElement] : [];
   return [...self, ...qsa(root, selector)];
 }
 
-/**
- * `tether-page-title="{title} | My shop"` on a product root sets `document.title`, for dynamic product pages.
- *
- * @param {Element} el
- * @param {Product} product
- */
-function applyPageTitle(el, product) {
+/** `tether-page-title="{title} | My shop"` on a product root sets `document.title`, for dynamic product pages. */
+function applyPageTitle(el: Element, product: Product): void {
   const template = get(el, 'page-title');
   if (!template || typeof document === 'undefined') return;
   document.title = template
@@ -67,11 +67,8 @@ function applyPageTitle(el, product) {
 /**
  * A product root without a key: on a dynamic page opened without `?handle=` (or with an empty path) it is a product
  * that isn't there; inside a list it gets its handle when the list renders.
- *
- * @param {HTMLElement} el
- * @param {{ fromUrl: boolean, raw: string }} source
  */
-function mountWithoutKey(el, { fromUrl, raw }) {
+function mountWithoutKey(el: HTMLElement, { fromUrl, raw }: KeySource): void {
   if (fromUrl) {
     mountedProducts.add(el);
     setScopeStatus(el, 'not-found');
@@ -81,13 +78,7 @@ function mountWithoutKey(el, { fromUrl, raw }) {
   }
 }
 
-/**
- * @param {HTMLElement} el
- * @param {string} key
- * @param {{ fromUrl: boolean, raw: string }} source
- * @param {unknown} error
- */
-function showLoadFailure(el, key, { fromUrl, raw }, error) {
+function showLoadFailure(el: HTMLElement, key: string, { fromUrl, raw }: KeySource, error: unknown): void {
   const notFound = isNotFound(error);
   setScopeStatus(el, notFound ? 'not-found' : 'error', error);
   if (!notFound) {
@@ -104,10 +95,9 @@ function showLoadFailure(el, key, { fromUrl, raw }, error) {
 /**
  * Mounts one product root.
  *
- * @param {HTMLElement} el
- * @returns {boolean} True when a product request was started.
+ * @returns True when a product request was started.
  */
-export function mountProduct(el) {
+export function mountProduct(el: HTMLElement): boolean {
   if (mountedProducts.has(el)) return false;
   const { key, ...source } = resolveProductKey(el);
   if (!key) {
@@ -132,14 +122,14 @@ export function mountProduct(el) {
       applyPageTitle(el, product);
       if (cfg.revalidate && takeStale(key)) queueRefresh(key);
     })
-    .catch((/** @type {unknown} */ error) => {
+    .catch((error: unknown) => {
       if (isLatest()) showLoadFailure(el, key, source, error);
     });
   return true;
 }
 
 /** Loads again the product scopes that failed on a network or API error, for when the browser is back online. */
-export function retryFailed() {
+export function retryFailed(): void {
   pruneLive();
   liveProducts.forEach((el) => {
     if (el.getAttribute(attr('state')) !== 'error' || el.getAttribute(attr('error')) === 'not-found') return;
@@ -148,20 +138,16 @@ export function retryFailed() {
   });
 }
 
-/** @type {Set<string>} Server-rendered products to refresh in the next batch. */
-let refreshQueue = new Set();
+/** Server-rendered products to refresh in the next batch. */
+let refreshQueue = new Set<string>();
 
-/** @param {string} key */
-function queueRefresh(key) {
+function queueRefresh(key: string): void {
   if (!refreshQueue.size) setTimeout(flushRefresh, 0);
   refreshQueue.add(key);
 }
 
-/**
- * @param {string} key The key the refresh was asked for.
- * @param {Product} fresh
- */
-function applyRefresh(key, fresh) {
+/** @param key The key the refresh was asked for. */
+function applyRefresh(key: string, fresh: Product): void {
   liveProducts.forEach((el) => {
     const scope = scopes.get(el);
     if (!scope || !el.isConnected) return;
@@ -175,38 +161,35 @@ function applyRefresh(key, fresh) {
 function flushRefresh() {
   const keys = [...refreshQueue];
   refreshQueue = new Set();
-  refreshProducts(keys).forEach((promise, index) => {
-    const key = /** @type {string} */ (keys[index]);
-    promise
+  keys.forEach((key) => {
+    refreshProduct(key)
       .then((fresh) => {
         applyRefresh(key, fresh);
       })
-      .catch((/** @type {unknown} */ error) => {
+      .catch((error: unknown) => {
         reportError(error, `refresh ${key}`);
       });
   });
 }
 
 /**
- * @type {Set<Promise<unknown>> | null} While the page's server-rendered prices are another market's: the loads to
- *   wait for before `html.tether-market-pending` goes. `null` when no market is pending.
+ * While the page's server-rendered prices are another market's: the loads to wait for before
+ * `html.tether-market-pending` goes. `null` when no market is pending.
  */
-let marketPending = null;
+let marketPending: Set<Promise<unknown>> | null = null;
 
 /**
  * Lists, and anything else that loads prices, hold `html.tether-market-pending` until they are in.
  *
- * @template T
- * @param {Promise<T>} loading
- * @returns {Promise<T>} `loading` itself.
+ * @returns `loading` itself.
  */
-export const trackMarket = (loading) => {
+export const trackMarket = <T>(loading: Promise<T>): Promise<T> => {
   marketPending?.add(loading);
   return loading;
 };
 
 /** After a mount: drops `html.tether-market-pending` once this page's products are live. */
-export function settleMarket() {
+export function settleMarket(): void {
   if (!marketPending) return;
   const waits = [...marketPending];
   void Promise.allSettled(waits).then(() => {
@@ -220,52 +203,56 @@ export function settleMarket() {
   });
 }
 
-/**
- * What `tether/server`'s `hydrate()` writes. The tag is the site's own markup, so its shape is trusted; a product
- * without an id or a handle is skipped.
- *
- * @typedef {{ country?: string | null, language?: string | null, products?: (Product | null)[] }} HydratePayload
- */
-
-/**
- * @param {Product | null} product
- * @returns {product is Product}
- */
-const isUsable = (product) => Boolean(product?.id && product.handle);
-
-/**
- * @param {string | null | undefined} a
- * @param {string | null | undefined} b
- */
-const sameCode = (a, b) => (a ?? '').toUpperCase() === (b ?? '').toUpperCase();
+/** What `tether/server`'s `hydrate()` writes: the market it fetched in, and the products. */
+interface HydratePayload {
+  country: CountryCode | undefined;
+  language: LanguageCode | undefined;
+  products: Product[];
+}
 
-/** @type {WeakSet<Element>} Hydrate tags already read. */
-const readScripts = new WeakSet();
+/** @param json A hydrate tag's JSON. */
+function toHydratePayload(json: unknown): HydratePayload {
+  if (!isRecord(json)) return { country: undefined, language: undefined, products: [] };
+  const { products } = json;
+  const entries: unknown[] = Array.isArray(products) ? products : [];
+  return {
+    country: toCountry(json['country']) ?? undefined,
+    language: toLanguage(json['language']) ?? undefined,
+    products: entries.filter(isProductShape),
+  };
+}
 
+/** Hydrate tags already read. */
+const readScripts = new WeakSet<Element>();
 /**
  * Uses the products in the page's hydrate tags (`tether/server` `hydrate()`) without a request. A tag made for another
  * market is skipped, and marks the page (`html.tether-market-pending`) until the live prices are in, so CSS can hide
  * prices meanwhile.
  *
- * @param {Document | Element} [root]
+ * Trust: a hydrate tag is part of the page, written by the site's own build like the rest of its HTML and scripts, so
+ * its prices and products are shown until the background refresh replaces them. Whoever can write a tag into the page
+ * can already write a script there; the shape check (`isProductShape`) is for a truncated or hand-written tag, which
+ * is skipped instead of failing a render.
+ *
+ * @param root Where to look: the document for a mount (a tag may sit in `<head>` or anywhere else on the page), the
+ *   added elements for `observe`.
  */
-export function hydrateFromPage(root = document) {
-  qsa(root.ownerDocument ?? root, HYDRATE_SELECTOR).forEach((script) => {
+export function hydrateFromPage(root: Document | Element = document): void {
+  within(root, HYDRATE_SELECTOR).forEach((script) => {
     if (readScripts.has(script)) return;
     readScripts.add(script);
-    /** @type {unknown} */
-    let json;
+    let json: unknown;
     try {
       json = JSON.parse(script.textContent);
     } catch (error) {
       warn('bad data-tether-hydrate', error);
       return;
     }
-    const { country, language, products } = /** @type {HydratePayload | null} */ (json) ?? {};
-    const usable = Array.isArray(products) ? products.filter(isUsable) : [];
-    rememberOptionNames(usable); // the build's option names, also for other languages
-    if (sameCode(country, cfg.country) && sameCode(language, cfg.language)) {
-      hydrateProducts(usable);
+    const { country, language, products } = toHydratePayload(json);
+    // The build's option names, also for other languages.
+    rememberOptionNames(products);
+    if (country === cfg.country && language === cfg.language) {
+      hydrateProducts(products);
       return;
     }
     log('hydration skipped: other market');

package/src/{page-market.js → page-market.ts}

@@ -3,24 +3,25 @@
  * saved or detected market, then the configured one. Init applies it to `cfg` once. Astro's ClientRouter keeps the
  * script running across pages, so each arrival asks again: the next page may be built for another market, or for none.
  */
-import { cfg, log, reportError } from './config.js';
-import { loadPart } from './lazy.js';
-import { toCountry, toLanguage } from './market-codes.js';
-import { readSavedMarket } from './markets.js';
-/** @import { TetherOptions } from './config.js' */
-/** @import { Market, DetectedMarket } from './markets.js' */
-/** @import { SetCountryOptions } from './markets-ui.js' */
-/** @import { ShopifyCart } from './cart/store.js' */
+import { cfg, log, reportError } from './config.ts';
+import { loadPart } from './lazy.ts';
+import { toCountry, toLanguage } from './market-codes.ts';
+import { readSavedMarket } from './markets.ts';
+import type { TetherOptions } from './config.ts';
+import type { Market, DetectedMarket } from './markets.ts';
+import type { Parts } from './lazy.ts';
+import type { ShopifyCart } from './cart/store.ts';
 
-/**
- * @typedef {object} ConfiguredMarket The market of the config, before a page's or visitor's market applied.
- * @property {string | undefined} country
- * @property {string | undefined} language
- * @property {string | undefined} locale
- */
+export type SetCountryOptions = Parameters<Parts['markets']['setCountry']>[1];
+
+/** The market of the config, before a page's or visitor's market applied. */
+interface ConfiguredMarket {
+  country: string | undefined;
+  language: string | undefined;
+  locale: string | undefined;
+}
 
-/** @type {ConfiguredMarket} */
-let configuredMarket = { country: undefined, language: undefined, locale: undefined };
+let configuredMarket: ConfiguredMarket = { country: undefined, language: undefined, locale: undefined };
 
 /** Whether the page arrived at last was built for its own market, which the next page without one switches back from. */
 let lastPageHadOwnMarket = false;
@@ -29,11 +30,10 @@ let lastPageHadOwnMarket = false;
  * `<meta name="tether-page-country" content="DE">`, with `tether-page-language` and `tether-page-locale`. Never
  * remembered: it belongs to the page, not to the visitor.
  *
- * @returns {Market | null} `null` when the page has no valid country of its own.
+ * @returns `null` when the page has no valid country of its own.
  */
-function pageMarket() {
-  /** @param {string} name */
-  const meta = (name) =>
+function pageMarket(): Market | null {
+  const meta = (name: string) =>
     document.querySelector(`meta[name="${cfg.prefix}-page-${name}"]`)?.getAttribute('content') || undefined;
   const country = toCountry(meta('country'));
   if (!country) return null;
@@ -42,10 +42,8 @@ function pageMarket() {
 
 /**
  * Without `markets.detect` only the visitor's saved choice applies, read without loading the markets part.
- *
- * @returns {Promise<Market | DetectedMarket | null>}
  */
-async function visitorMarket() {
+async function visitorMarket(): Promise<Market | DetectedMarket | null> {
   const markets = cfg.markets ?? {};
   if (markets.detect === false) return null;
   if (!markets.detect) return markets.remember === false ? null : readSavedMarket();
@@ -60,10 +58,9 @@ async function visitorMarket() {
 /**
  * Sets `cfg`'s market for the first page, over the configured one.
  *
- * @param {TetherOptions} overrides What `init()` was called with: a `locale` there wins over the visitor's.
- * @returns {Promise<void>}
+ * @param overrides What `init()` was called with: a `locale` there wins over the visitor's.
  */
-export async function applyStartMarket(overrides) {
+export async function applyStartMarket(overrides: TetherOptions): Promise<void> {
   configuredMarket = { country: cfg.country, language: cfg.language, locale: cfg.locale };
   const page = pageMarket();
   lastPageHadOwnMarket = page !== null;
@@ -81,20 +78,19 @@ export async function applyStartMarket(overrides) {
   log('market', market);
 }
 
-/**
- * @param {string | undefined} a
- * @param {string | undefined} b
- */
-const sameCode = (a, b) => (a ?? '').toUpperCase() === (b ?? '').toUpperCase();
+const sameCode = (a: string | undefined, b: string | undefined) => (a ?? '').toUpperCase() === (b ?? '').toUpperCase();
 
 /**
  * The market to switch to on arriving at the current page. A page built for a market switches to it; the first page
  * without one after such a page switches back to the visitor's own choice, else to the configured market.
  *
- * @returns {{ country: string, language: string | undefined, locale: string | undefined } | null} `null` when the page
- *   stays in the market in use.
+ * @returns `null` when the page stays in the market in use.
  */
-export function marketForArrival() {
+export function marketForArrival(): {
+  country: string;
+  language: string | undefined;
+  locale: string | undefined;
+} | null {
   const page = pageMarket();
   const leftOwnMarket = page === null && lastPageHadOwnMarket;
   lastPageHadOwnMarket = page !== null;
@@ -107,10 +103,8 @@ export function marketForArrival() {
 /**
  * `Tether.setCountry('DE')`: loads the markets part on first use.
  *
- * @param {string} code
- * @param {SetCountryOptions} [options]
- * @returns {Promise<ShopifyCart | null>} The cart once everything is in the new market.
+ * @returns The cart once everything is in the new market.
  */
-export function setCountry(code, options) {
+export function setCountry(code: string, options?: SetCountryOptions): Promise<ShopifyCart | null> {
   return loadPart('markets').then((part) => part.setCountry(code, options));
 }

package/src/part-integrity.ts

@@ -0,0 +1,7 @@
+/**
+ * The Subresource Integrity hash of each optional part's file, by file name, so the core loads only the parts built
+ * with it (src/lazy-iife.ts). Every `<script>` build, watch mode included, puts the hashes of the parts it built into
+ * the core in place of this module (scripts/build.ts); the empty map here only lets the source type-check, and a part
+ * missing from the map is not loaded.
+ */
+export const PART_INTEGRITY: Readonly<Record<string, string>> = {};

package/src/parts/account-pages.ts

@@ -0,0 +1,7 @@
+// The <script> build's tether.account-pages.js: registers the part where the core script's loader (lazy-iife.ts) finds it.
+import * as part from '../account-pages.ts';
+import type { TetherInternals } from '../lazy.ts';
+
+const { Tether } = window as { Tether?: TetherInternals };
+if (!Tether) throw new Error('tether.account-pages.js runs after the Tether script, which loads it');
+Tether.__parts['account-pages'] = part;

package/src/parts/account.ts

@@ -0,0 +1,7 @@
+// The <script> build's tether.account.js: registers the part where the core script's loader (lazy-iife.ts) finds it.
+import * as part from '../account.ts';
+import type { TetherInternals } from '../lazy.ts';
+
+const { Tether } = window as { Tether?: TetherInternals };
+if (!Tether) throw new Error('tether.account.js runs after the Tether script, which loads it');
+Tether.__parts.account = part;

package/src/parts/analytics.ts

@@ -0,0 +1,7 @@
+// The <script> build's tether.analytics.js: registers the part where the core script's loader (lazy-iife.ts) finds it.
+import * as part from '../analytics.ts';
+import type { TetherInternals } from '../lazy.ts';
+
+const { Tether } = window as { Tether?: TetherInternals };
+if (!Tether) throw new Error('tether.analytics.js runs after the Tether script, which loads it');
+Tether.__parts.analytics = part;

package/src/parts/diagnose.ts

@@ -0,0 +1,7 @@
+// The <script> build's tether.diagnose.js: registers the part where the core script's loader (lazy-iife.ts) finds it.
+import * as part from '../diagnose.ts';
+import type { TetherInternals } from '../lazy.ts';
+
+const { Tether } = window as { Tether?: TetherInternals };
+if (!Tether) throw new Error('tether.diagnose.js runs after the Tether script, which loads it');
+Tether.__parts.diagnose = part;

package/src/parts/extras.ts

@@ -0,0 +1,7 @@
+// The <script> build's tether.extras.js: registers the part where the core script's loader (lazy-iife.ts) finds it.
+import * as part from '../extras.ts';
+import type { TetherInternals } from '../lazy.ts';
+
+const { Tether } = window as { Tether?: TetherInternals };
+if (!Tether) throw new Error('tether.extras.js runs after the Tether script, which loads it');
+Tether.__parts.extras = part;

package/src/parts/markets.ts

@@ -0,0 +1,7 @@
+// The <script> build's tether.markets.js: registers the part where the core script's loader (lazy-iife.ts) finds it.
+import * as part from '../markets-ui.ts';
+import type { TetherInternals } from '../lazy.ts';
+
+const { Tether } = window as { Tether?: TetherInternals };
+if (!Tether) throw new Error('tether.markets.js runs after the Tether script, which loads it');
+Tether.__parts.markets = part;

package/src/parts/search.ts

@@ -0,0 +1,7 @@
+// The <script> build's tether.search.js: registers the part where the core script's loader (lazy-iife.ts) finds it.
+import * as part from '../search.ts';
+import type { TetherInternals } from '../lazy.ts';
+
+const { Tether } = window as { Tether?: TetherInternals };
+if (!Tether) throw new Error('tether.search.js runs after the Tether script, which loads it');
+Tether.__parts.search = part;