@occluze/tether 0.7.0 → 0.7.1

package/src/lazy-iife.ts

@@ -1,197 +0,0 @@
-/**
- * `<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

@@ -1,42 +0,0 @@
-/**
- * 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.ts

@@ -1,363 +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.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
- * 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;
-
-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
- * switch) still reach their callers but never refill the cache.
- */
-let generation = 0;
-
-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. */
-export function primeProduct(product: Product | null | undefined): void {
-  if (!product) return;
-  const loaded = Promise.resolve(product);
-  productCache.set(product.handle, loaded);
-  productCache.set(product.id, loaded);
-}
-
-/**
- * @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: 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;
-
-  const loading = new Promise<Product>((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 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.
- */
-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: string[] = [];
-  const selections: string[] = [];
-  const variables: Record<string, unknown> = {};
-  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 = withProductFragment(`query TetherProducts(${definitions.join(',')}) { ${selections.join(' ')} }`);
-  return { query, variables, handles };
-}
-
-function settleWaiting(key: string, settle: (waiter: Waiter) => void): void {
-  const waiter = waiting.get(key);
-  waiting.delete(key);
-  if (waiter) settle(waiter);
-}
-
-function forgetMissLater(key: string, batchGeneration: number): void {
-  if (batchGeneration !== generation) return;
-  const miss = productCache.get(key);
-  setTimeout(() => {
-    if (productCache.get(key) === miss) productCache.delete(key);
-  }, 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;
-  const keys = pending.splice(0);
-  if (!keys.length) return;
-  const { query, variables, handles } = batchQuery(keys);
-  log('fetch products', keys);
-
-  let data;
-  try {
-    data = await gql(query, variables, isBatchData);
-  } catch (error) {
-    keys.forEach((key) => {
-      settleWaiting(key, (waiter) => {
-        if (batchGeneration === generation) productCache.delete(key);
-        waiter.reject(error);
-      });
-    });
-    return;
-  }
-
-  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);
-  });
-
-  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(): void {
-  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.
- */
-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);
-    if (loadedAgo < FRESH_MS && productCache.has(product.handle)) continue;
-    primeProduct(product);
-    stale.add(product.handle);
-    stale.add(product.id);
-  }
-}
-
-/** @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);
-  // 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);
-  }, failureIsReportedByTheRender);
-  return true;
-}
-
-/**
- * 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.
- */
-function failureIsReportedByTheRender() {
-  // Nothing to clean: see above.
-}
-
-/** 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) {
-    ${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.
- *
- * @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,
-}: ProductQuery = {}): Promise<ProductPage> {
-  if (collection) {
-    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 };
-  }
-
-  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 };
-}
-
-/**
- * Shopify's recommendations for a product. Every product in them is cached.
- *
- * @param product A product, or its handle, id or gid.
- */
-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;
-  const data = await gql(
-    withProductFragment(
-      `query TetherRecs(${byId ? '$id: ID!' : '$handle: String!'}, $intent: ProductRecommendationIntent) {
-  productRecommendations(${byId ? 'productId: $id' : 'productHandle: $handle'}, intent: $intent) { ...TetherProduct }
-}`,
-    ),
-    byId ? { id: key, intent } : { handle: key, intent },
-    isRecommendationsAnswer,
-  );
-  const list = data.productRecommendations ?? [];
-  list.forEach(primeProduct);
-  return list;
-}

package/src/market-codes.ts

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