@tinvar/react 0.0.0-stage → 0.4.1

package/src/prefetch-cache.js

@@ -0,0 +1,256 @@
+// The prefetch cache: pages fetched ahead of a click, kept for a while.
+//
+// tinvar-spec.md, "Caching and invalidation": "`<Link prefetch>` on hover
+// (75 ms default), `"click"` (mousedown), `"mount"`, or an array of them.
+// `cacheFor` takes a TTL or a stale-while-revalidate pair such as
+// `['30s', '1m']`."
+//
+// What is kept is the response itself, not its bytes: a click that lands
+// while the prefetch is still streaming waits for its headers and then reads
+// the rest as it arrives, rather than waiting for the whole body or asking
+// the server a second time.
+//
+// The cache is client-held data, so it belongs to one session ("Client-held
+// data ... is bound to (user, tenant)"). Each entry records the binding of
+// the response it holds and the CSRF cookie it was asked for under, and the
+// router purges everything when either stops matching. This module only
+// keeps the entries; when to purge is the router's.
+
+/** How long a prefetched page is used for when `cacheFor` is not given. */
+export const DEFAULT_CACHE_FOR = 30_000;
+
+/**
+ * How many pages are kept at once. A long catalog with `prefetch="mount"` on
+ * every card would otherwise hold every page it links to, each a whole RSC
+ * payload, for as long as the tab is open.
+ */
+export const MAX_ENTRIES = 50;
+
+const UNITS = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+
+/**
+ * A duration in milliseconds: a number of milliseconds, or a string such as
+ * `'500ms'`, `'30s'`, `'1m'`, `'2h'` or `'1d'`.
+ *
+ * @param {number | string} value
+ * @returns {number}
+ */
+export function parseDuration(value) {
+  if (typeof value === 'number') {
+    if (Number.isFinite(value) && value >= 0) return value;
+  } else if (typeof value === 'string') {
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/.exec(value.trim());
+    if (match) return Number(match[1]) * UNITS[/** @type {keyof typeof UNITS} */ (match[2])];
+  }
+
+  // Thrown rather than read as zero: a typo that silently turned caching off
+  // would look like a cache that never works.
+  throw new TypeError(
+    `[tinvar:client] Cannot read ${JSON.stringify(value)} as a duration; write '30s' or 30000.`,
+  );
+}
+
+/**
+ * When a prefetched page stops being fresh and when it stops being usable,
+ * in milliseconds after it arrived.
+ *
+ * A single TTL is fresh for that long and then gone. A pair is
+ * stale-while-revalidate: fresh until the first, then still used -- while a
+ * new copy is fetched behind it -- until the second, which is the whole
+ * lifetime, not a further period after the first.
+ *
+ * @param {number | string | readonly [number | string, number | string]} [cacheFor]
+ * @returns {{ fresh: number, stale: number }}
+ */
+export function cacheWindow(cacheFor = DEFAULT_CACHE_FOR) {
+  if (Array.isArray(cacheFor)) {
+    const [fresh, stale] = cacheFor.map(parseDuration);
+    if (fresh === undefined || stale === undefined || cacheFor.length !== 2) {
+      throw new TypeError("[tinvar:client] A cacheFor pair is [fresh, stale], as ['30s', '1m'].");
+    }
+    if (stale < fresh) {
+      throw new TypeError(
+        '[tinvar:client] In a cacheFor pair the second duration is the whole lifetime, so it cannot be the shorter.',
+      );
+    }
+    return { fresh, stale };
+  }
+
+  const ttl = parseDuration(/** @type {number | string} */ (cacheFor));
+  return { fresh: ttl, stale: ttl };
+}
+
+/**
+ * @typedef {{
+ *   url: string,
+ *   tags: string[],
+ *   window: { fresh: number, stale: number },
+ *   response: Promise<Response | null>,
+ *   controller: AbortController,
+ *   binding: string | null,
+ *   csrf: string | null,
+ *   arrivedAt: number | null,
+ *   claimed?: readonly string[],
+ *   historyKey?: import('./remember-store.js').HistoryKey | null,
+ * }} Entry
+ *
+ * `response` resolves to the stored response once its headers are in, or to
+ * null when what came back is not worth keeping; the entry is gone by then.
+ * `arrivedAt` is null while it is in flight. `binding` is the session the
+ * response was rendered for, once known. `csrf` is the CSRF cookie the page
+ * held when it was asked for, which rotates with the session. `claimed` is
+ * the #[Once] keys it was asked for with, whose fields it may have been
+ * sent without. `historyKey` is the history key the page came with, imported
+ * -- never the raw key, whose header is taken off the response kept.
+ */
+
+export class PrefetchCache {
+  /** @type {Map<string, Entry>} */
+  #entries = new Map();
+  #max;
+  #now;
+
+  /** @param {{ max?: number, now?: () => number }} [options] */
+  constructor(options = {}) {
+    this.#max = options.max ?? MAX_ENTRIES;
+    this.#now = options.now ?? Date.now;
+  }
+
+  get size() {
+    return this.#entries.size;
+  }
+
+  /**
+   * The entry for a URL, in flight or arrived, if it can still be used, and
+   * whether it is past fresh. An expired entry is dropped on the way.
+   *
+   * @param {string} url
+   * @returns {{ entry: Entry, stale: boolean } | null}
+   */
+  lookup(url) {
+    const entry = this.#entries.get(url);
+    if (!entry) return null;
+    if (entry.arrivedAt === null) return { entry, stale: false };
+
+    const age = this.#now() - entry.arrivedAt;
+    if (age >= entry.window.stale) {
+      this.#drop(url, entry);
+      return null;
+    }
+
+    return { entry, stale: age >= entry.window.fresh };
+  }
+
+  /**
+   * Starts keeping an entry, in flight. It replaces any other for the URL.
+   *
+   * @param {Entry} entry
+   */
+  add(entry) {
+    const previous = this.#entries.get(entry.url);
+    if (previous && previous !== entry) this.#drop(entry.url, previous);
+
+    // Oldest first, as a Map iterates: what was prefetched longest ago is
+    // the least likely to be clicked next.
+    while (this.#entries.size >= this.#max) {
+      const [url, oldest] = this.#entries.entries().next().value ?? [];
+      if (url === undefined || oldest === undefined) break;
+      this.#drop(url, oldest);
+    }
+
+    this.#entries.set(entry.url, entry);
+  }
+
+  /**
+   * Marks an entry as arrived, if it is still the one kept for its URL.
+   *
+   * @param {Entry} entry
+   * @param {string | null} binding
+   * @returns {boolean} whether it was still kept
+   */
+  arrived(entry, binding) {
+    if (this.#entries.get(entry.url) !== entry) return false;
+    entry.arrivedAt = this.#now();
+    entry.binding = binding;
+    return true;
+  }
+
+  /**
+   * Forgets an entry, if it is still the one kept for its URL. A request
+   * still in flight for it is left to finish: whoever is waiting on it --
+   * a click that landed mid-prefetch -- still gets its answer.
+   *
+   * @param {Entry} entry
+   */
+  forget(entry) {
+    if (this.#entries.get(entry.url) === entry) this.#entries.delete(entry.url);
+  }
+
+  /** @param {string} url */
+  delete(url) {
+    const entry = this.#entries.get(url);
+    if (entry) this.#drop(url, entry);
+  }
+
+  /** Forgets every entry, and stops those still in flight. */
+  clear() {
+    for (const [url, entry] of [...this.#entries]) this.#drop(url, entry);
+  }
+
+  /**
+   * Forgets every entry carrying any of these tags -- one still in flight
+   * too, since it may have been answered from before the change that
+   * invalidated it.
+   *
+   * @param {Iterable<string>} tags
+   * @returns {number} how many were forgotten
+   */
+  deleteTagged(tags) {
+    const wanted = new Set(tags);
+    if (wanted.size === 0) return 0;
+
+    let forgotten = 0;
+    for (const [url, entry] of [...this.#entries]) {
+      if (!entry.tags.some((tag) => wanted.has(tag))) continue;
+      this.#drop(url, entry);
+      forgotten++;
+    }
+    return forgotten;
+  }
+
+  /**
+   * Forgets every entry asked for claiming any of these once keys: the
+   * browser no longer keeps what they stand for, so a page sent without
+   * those fields has nothing to fill them with.
+   *
+   * @param {readonly string[]} keys
+   */
+  deleteClaiming(keys) {
+    if (keys.length === 0) return;
+    for (const [url, entry] of [...this.#entries]) {
+      if (entry.claimed?.some((key) => keys.includes(key))) this.#drop(url, entry);
+    }
+  }
+
+  /**
+   * Stops every request still in flight, and forgets those entries. Arrived
+   * entries are kept.
+   */
+  abortInFlight() {
+    for (const [url, entry] of [...this.#entries]) {
+      if (entry.arrivedAt === null) this.#drop(url, entry);
+    }
+  }
+
+  /**
+   * @param {string} url
+   * @param {Entry} entry
+   */
+  #drop(url, entry) {
+    this.#entries.delete(url);
+    // An arrived response may still be read by a visit that took a copy of
+    // it; aborting would cut that visit's stream. Only a request still
+    // waiting on its headers is stopped.
+    if (entry.arrivedAt === null) entry.controller.abort();
+  }
+}

package/src/progress.d.ts

@@ -0,0 +1,38 @@
+import type { Router } from './router';
+
+/** How long a visit runs before the bar appears, unless told otherwise, in ms. */
+export declare const PROGRESS_DELAY_MS: number;
+/** How often the bar creeps forward while the server works, in ms. */
+export declare const TRICKLE_MS: number;
+/** How long a finished bar stays full before it goes, in ms. */
+export declare const FINISH_MS: number;
+
+export interface ProgressState {
+  /** Whether to draw the bar: a visit has run past the delay, and nothing has hidden it. */
+  visible: boolean;
+  /** How far along, from 0 to 1. Creeps toward 0.9; 1 once the page has committed. */
+  value: number;
+  /** The visit is done and the bar is at 1, on its way out. */
+  finishing: boolean;
+}
+
+export interface ProgressStore {
+  subscribe(listener: () => void): () => void;
+  snapshot(): ProgressState;
+  /** Hides the bar until a matching reveal(); calls nest. */
+  hide(): void;
+  /** Undoes one hide(). */
+  reveal(): void;
+}
+
+/** The progress state for a router: one per router, with the delay the first caller gives. */
+export declare function progressFor(router: Router, options?: { delay?: number }): ProgressStore;
+
+/**
+ * The progress bar's state for the router above, for the app to draw in its
+ * own style, and hide()/reveal(). The bar finishes when the page commits --
+ * its first meaningful flush -- not when the stream ends.
+ */
+export declare function useProgress(options?: {
+  delay?: number;
+}): ProgressState & { hide: () => void; reveal: () => void };

package/src/progress.js

@@ -0,0 +1,243 @@
+'use client';
+
+// The progress bar's state, for an app to draw in its own style.
+//
+// tinvar-spec.md, "Client router and components": "Progress bar with a delay
+// before showing, ref-counted `hide()`/`reveal()`, and per-visit
+// `showProgress`. With streaming, finish at the first meaningful flush."
+//
+// Only the state lives here -- whether a bar is showing and how far along it
+// is -- because how it looks is the design system's. A visit's `finish`
+// comes once its page has COMMITTED, which for a streamed page is its shell
+// -- the first flush with the page in it -- while Suspense boundaries go on
+// streaming into it. That is where the bar finishes: a bar that waited for
+// the stream's end would sit at the top of a page the reader is already
+// reading.
+//
+// A visit that finishes inside the delay shows nothing at all, so the
+// hundredth fast click is as quiet as the first.
+
+import { useMemo, useSyncExternalStore } from 'react';
+import { useOptionalRouter } from './link.js';
+
+/** How long a visit runs before the bar appears, unless told otherwise. */
+export const PROGRESS_DELAY_MS = 250;
+
+/** How often the bar creeps forward while the server is working. */
+export const TRICKLE_MS = 200;
+
+/** How long a finished bar stays full before it goes, for the app to fade. */
+export const FINISH_MS = 160;
+
+/**
+ * @typedef {{ visible: boolean, value: number, finishing: boolean }} ProgressState
+ *
+ * `visible` is whether to draw the bar; `value` how far along, from 0 to 1;
+ * `finishing` that the visit is done and the bar is at 1 on its way out.
+ */
+
+/** @type {ProgressState} */
+const IDLE = Object.freeze({ visible: false, value: 0, finishing: false });
+
+/** @type {WeakMap<object, ProgressStore>} */
+const stores = new WeakMap();
+
+class ProgressStore {
+  /** @type {Set<() => void>} */
+  #listeners = new Set();
+  /** @type {ProgressState} */
+  #state = IDLE;
+  #delay;
+  /** Whether the visit in progress has passed its delay. */
+  #shown = false;
+  #value = 0;
+  #finishing = false;
+  /** How many hide() calls are waiting for their reveal(). */
+  #hidden = 0;
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  #timer = null;
+  /** An interrupted visit's finish, held until it is known whether a visit follows it. */
+  #interrupted = false;
+
+  /**
+   * @param {import('./router.js').Router} router
+   * @param {number} delay
+   */
+  constructor(router, delay) {
+    this.#delay = delay;
+
+    router.on('start', (event) => {
+      const detail = /** @type {{ background?: boolean, showProgress?: boolean }} */ (event.detail);
+      if (detail.background || detail.showProgress === false) return;
+
+      // The visit that superseded the one the bar is for: it carries on as
+      // it was -- its delay still counting, or its value still creeping.
+      if (this.#interrupted) {
+        this.#interrupted = false;
+        return;
+      }
+      this.#begin();
+    });
+
+    router.on('finish', (event) => {
+      const detail = /** @type {{ background?: boolean, interrupted?: boolean }} */ (event.detail);
+      if (detail.background) return;
+
+      // A visit superseded by the next finishes, interrupted, just before
+      // the next one starts. Finished at once, the bar filled and the next
+      // visit started it over from the beginning: back to 10% in the middle
+      // of what the user sees as one wait. So it is held for the rest of
+      // this task -- the next start comes in it, or none does, and then it
+      // finishes, as after cancelAll().
+      if (detail.interrupted) {
+        this.#interrupted = true;
+        void Promise.resolve().then(() => {
+          if (!this.#interrupted) return;
+          this.#interrupted = false;
+          this.#done();
+        });
+        return;
+      }
+
+      this.#interrupted = false;
+      this.#done();
+    });
+  }
+
+  /** @param {() => void} listener */
+  subscribe = (listener) => {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  };
+
+  snapshot = () => this.#state;
+
+  /** Hides the bar until a matching reveal(); calls nest. */
+  hide = () => {
+    this.#hidden++;
+    this.#publish();
+  };
+
+  /** Undoes one hide(). */
+  reveal = () => {
+    this.#hidden = Math.max(0, this.#hidden - 1);
+    this.#publish();
+  };
+
+  #begin() {
+    this.#clear();
+
+    // A visit that supersedes one already showing carries on from where the
+    // bar is, rather than blinking out and starting again; one that follows
+    // a bar on its way out starts it over.
+    if (this.#shown) {
+      if (this.#finishing) this.#value = 0.1;
+      this.#finishing = false;
+      this.#trickle();
+      this.#publish();
+      return;
+    }
+
+    this.#value = 0;
+    this.#timer = setTimeout(() => {
+      this.#shown = true;
+      this.#value = 0.1;
+      this.#publish();
+      this.#trickle();
+    }, this.#delay);
+  }
+
+  /** Creeps toward, never to, the end: nothing here knows how long is left. */
+  #trickle() {
+    this.#timer = setTimeout(() => {
+      this.#value = Math.min(0.9, this.#value + (0.9 - this.#value) * 0.15);
+      this.#publish();
+      this.#trickle();
+    }, TRICKLE_MS);
+  }
+
+  #done() {
+    this.#clear();
+
+    // Finished inside the delay: nothing was shown, and nothing is.
+    if (!this.#shown) {
+      this.#value = 0;
+      this.#publish();
+      return;
+    }
+
+    this.#value = 1;
+    this.#finishing = true;
+    this.#publish();
+    this.#timer = setTimeout(() => {
+      this.#timer = null;
+      this.#shown = false;
+      this.#finishing = false;
+      this.#value = 0;
+      this.#publish();
+    }, FINISH_MS);
+  }
+
+  #clear() {
+    if (this.#timer !== null) clearTimeout(this.#timer);
+    this.#timer = null;
+  }
+
+  #publish() {
+    const visible = this.#shown && this.#hidden === 0;
+    const next = visible ? { visible, value: this.#value, finishing: this.#finishing } : IDLE;
+    const current = this.#state;
+    if (
+      current.visible === next.visible &&
+      current.value === next.value &&
+      current.finishing === next.finishing
+    ) {
+      return;
+    }
+    this.#state = next;
+    for (const listener of this.#listeners) listener();
+  }
+}
+
+/**
+ * The progress state for a router: one per router, made on first use, with
+ * the delay the first caller gives.
+ *
+ * @param {import('./router.js').Router} router
+ * @param {{ delay?: number }} [options]
+ */
+export function progressFor(router, options = {}) {
+  let store = stores.get(router);
+  if (store === undefined) {
+    store = new ProgressStore(router, options.delay ?? PROGRESS_DELAY_MS);
+    stores.set(router, store);
+  }
+  return store;
+}
+
+const nothing = () => () => {};
+const idle = () => IDLE;
+
+/**
+ * The progress bar's state for the router above, and `hide()` / `reveal()`
+ * to keep it off screen while something else says the page is busy. Idle
+ * without a router, as in a server render.
+ *
+ * @param {{ delay?: number }} [options] how long a visit runs before the
+ *   bar shows; read once per router
+ * @returns {ProgressState & { hide: () => void, reveal: () => void }}
+ */
+export function useProgress(options = {}) {
+  const router = useOptionalRouter();
+  const store = router === null ? null : progressFor(router, options);
+  const state = useSyncExternalStore(store?.subscribe ?? nothing, store?.snapshot ?? idle, idle);
+
+  return useMemo(
+    () => ({
+      ...state,
+      hide: store?.hide ?? (() => {}),
+      reveal: store?.reveal ?? (() => {}),
+    }),
+    [state, store],
+  );
+}

package/src/remember-store.d.ts

@@ -0,0 +1,50 @@
+/** Where remembered state is kept: per tab, per history entry, per session. */
+
+/** The sessionStorage key the map is kept under. */
+export declare const REMEMBER_STORAGE_KEY: 'tinvar:remember';
+/** How many history entries' values are kept; the oldest go first. */
+export declare const MAX_REMEMBERED_ENTRIES: number;
+/** Puts a value in a map by history entry as its newest, dropping the oldest past MAX_REMEMBERED_ENTRIES. */
+export declare function keepNewest<V>(map: Map<string, V>, entry: string, value: V): void;
+
+/** A page's history key, imported; null when it could not be. */
+export type HistoryKey = Promise<CryptoKey | null>;
+
+export interface RememberStore {
+  /**
+   * An entry's values kept in the clear, if the map is bound to this
+   * session; reading under another wipes it. A sealed entry reads as empty
+   * here: see open().
+   */
+  read(entry: string, binding: string | null): Record<string, unknown>;
+  /** Whether an entry is kept sealed, under this session. */
+  isSealed(entry: string, binding: string | null): boolean;
+  /**
+   * An entry's values, opened with the page's history key when they were
+   * sealed. One that does not open under it -- another session's key -- is
+   * dropped.
+   */
+  open(entry: string, binding: string | null, key: HistoryKey | null): Promise<Record<string, unknown>>;
+  /**
+   * Replaces an entry's values under this session -- sealed with the key
+   * when one is given, and then never in the clear -- and settles once
+   * written. A map bound to another session is replaced whole.
+   */
+  write(
+    entry: string,
+    binding: string | null,
+    values: Record<string, unknown>,
+    key?: HistoryKey | null,
+  ): Promise<void>;
+  /** Forgets everything, and every seal still under way. */
+  wipe(): void;
+}
+
+/** The tab's sessionStorage, or null where it cannot be used. */
+export declare function tabStorage(win: Window | undefined): Storage | null;
+
+/** Imports a history key as the server sends it: AES-GCM, not extractable. */
+export declare function importHistoryKey(encoded: string, crypto?: Crypto): HistoryKey;
+
+/** A store over a Storage, or over memory when there is none. */
+export declare function createRememberStore(storage: Storage | null, crypto?: Crypto): RememberStore;