@tinvar/react 0.0.0-stage → 0.4.0

package/src/poll.js

@@ -0,0 +1,224 @@
+'use client';
+
+// usePoll: the page on screen, refreshed on a timer.
+//
+// tinvar-spec.md, "Client router and components": "`usePoll(ms, options,
+// { mode, background })` with `mode: 'overlap' | 'cancel' | 'rest'` and
+// `background: 'throttle' | 'pause' | 'continue'`, re-running only named
+// loader fields."
+//
+// Each tick is a background reload -- with `only` or `except`, a partial
+// one -- so everything the router promises a background request holds: it
+// never navigates, never cancels a visit the user made, waits while one is
+// in flight, and a version mismatch fires the cancelable `location` event
+// instead of reloading. A 401 still loads the page, as for every request:
+// the session is gone.
+//
+// The timing lives in createPoller(), which knows nothing of React, so the
+// modes can be read and tested without rendering anything.
+
+import { useEffect, useMemo, useRef } from 'react';
+import { refreshDeferred } from './deferred-revalidation.js';
+import { useOptionalRouter } from './link.js';
+
+/** How much slower a `throttle` poll runs while its tab is in the background. */
+export const THROTTLE_FACTOR = 10;
+
+/**
+ * @typedef {'overlap' | 'cancel' | 'rest'} PollMode
+ * @typedef {'throttle' | 'pause' | 'continue'} PollBackground
+ *
+ * @typedef {{
+ *   mode?: PollMode,
+ *   background?: PollBackground,
+ *   autoStart?: boolean,
+ *   deferred?: boolean,
+ * }} PollSettings
+ *
+ * `deferred` also asks the page's loaded <Deferred> boundaries to fetch
+ * again after each poll, quietly (refreshDeferred()): a reload keeps a
+ * boundary's content, so what a poll is for -- an order's shipping
+ * timeline, say -- would otherwise never move.
+ *
+ * `mode` is what a tick does about the one before it, still in flight:
+ * `rest` (the default) waits for it, and the interval runs from when it
+ * settled, so a slow server is never asked again before it has answered;
+ * `cancel` cancels it; `overlap` lets both run, and an older answer that
+ * arrives after a newer one is dropped by the router.
+ *
+ * `background` is what happens while the tab is hidden, by the Page
+ * Visibility API: `throttle` (the default) polls ten times less often,
+ * `pause` stops until the tab is shown again, `continue` carries on.
+ */
+
+/**
+ * @param {{
+ *   router: Pick<import('./router.js').Router, 'reload'>,
+ *   interval: number,
+ *   options?: () => import('./router.js').VisitOptions,
+ *   mode?: PollMode,
+ *   background?: PollBackground,
+ *   document?: Document,
+ *   now?: () => number,
+ *   onPolled?: () => void,
+ * }} settings
+ * @returns {{ start: () => void, stop: () => void, readonly running: boolean }}
+ */
+export function createPoller({
+  router,
+  interval,
+  options = () => ({}),
+  mode = 'rest',
+  background = 'throttle',
+  document: doc = globalThis.document,
+  now = Date.now,
+  onPolled = () => {},
+}) {
+  if (!Number.isFinite(interval) || interval <= 0) {
+    throw new TypeError(`[tinvar:client] A poll needs a positive interval in ms, not ${interval}.`);
+  }
+
+  let running = false;
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let timer = null;
+  /** When the last poll was sent. */
+  let last = now();
+  /** @type {Set<AbortController>} */
+  const inFlight = new Set();
+
+  const hidden = () => doc?.visibilityState === 'hidden';
+  const every = () => (hidden() && background === 'throttle' ? interval * THROTTLE_FACTOR : interval);
+
+  function clear() {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+  }
+
+  /** @param {number} ms */
+  function schedule(ms) {
+    clear();
+    if (!running) return;
+    // Paused: nothing is due until the tab is shown again.
+    if (hidden() && background === 'pause') return;
+    timer = setTimeout(tick, Math.max(0, ms));
+  }
+
+  function tick() {
+    timer = null;
+    if (!running) return;
+
+    if (mode === 'cancel') {
+      for (const c of inFlight) c.abort();
+    }
+
+    const controller = new AbortController();
+    inFlight.add(controller);
+    last = now();
+
+    // A background reload: the router waits out a visit in flight, mounts
+    // only onto the page it was asked for, and never moves the page.
+    Promise.resolve()
+      .then(() => router.reload({ ...options(), background: true, signal: controller.signal }))
+      // After a poll that landed, not one that failed or was cancelled. The
+      // router reports which: a failed poll resolves as well as one that
+      // mounted -- it is reported on the router's own events -- and so does
+      // one never sent because a visit was under way.
+      .then((mounted) => {
+        if (mounted === true && !controller.signal.aborted) onPolled();
+      })
+      .catch(() => {})
+      .finally(() => {
+        inFlight.delete(controller);
+        if (mode === 'rest' && running) schedule(every());
+      });
+
+    if (mode !== 'rest') schedule(every());
+  }
+
+  function onVisibility() {
+    if (!running) return;
+    // A poll resting on one in flight is rescheduled when that settles.
+    if (mode === 'rest' && inFlight.size > 0) return;
+
+    // Due from when the last one was sent, at the rate that applies now: a
+    // tab shown again after longer than an interval polls at once.
+    schedule(last + every() - now());
+  }
+
+  return {
+    get running() {
+      return running;
+    },
+
+    start() {
+      if (running) return;
+      running = true;
+      last = now();
+      doc?.addEventListener('visibilitychange', onVisibility);
+      schedule(every());
+    },
+
+    stop() {
+      if (!running) return;
+      running = false;
+      clear();
+      doc?.removeEventListener('visibilitychange', onVisibility);
+      for (const c of inFlight) c.abort();
+      inFlight.clear();
+    },
+  };
+}
+
+/**
+ * Polls the page on screen every `interval` ms while the component is
+ * mounted, through background reloads -- partial ones, given `only` or
+ * `except` -- and stops when it unmounts. Returns `start` and `stop` for a
+ * poll that should run only some of the time (`autoStart: false`).
+ *
+ * The reload options are read at each tick, so they can change between
+ * renders without restarting the poll.
+ *
+ * @param {number} interval
+ * @param {Omit<import('./router.js').VisitOptions, 'background' | 'signal'>} [options]
+ * @param {PollSettings} [settings]
+ * @returns {{ start: () => void, stop: () => void }}
+ */
+export function usePoll(
+  interval,
+  options = {},
+  { mode = 'rest', background = 'throttle', autoStart = true, deferred = false } = {},
+) {
+  const router = useOptionalRouter();
+  const latest = useRef(options);
+  latest.current = options;
+  const poller = useRef(/** @type {ReturnType<typeof createPoller> | null} */ (null));
+
+  useEffect(() => {
+    // A server render, or a test without a router: nothing to poll with.
+    if (router === null) return undefined;
+
+    const created = createPoller({
+      router,
+      interval,
+      options: () => latest.current,
+      mode,
+      background,
+      onPolled: deferred ? refreshDeferred : undefined,
+    });
+    poller.current = created;
+    if (autoStart) created.start();
+
+    return () => {
+      created.stop();
+      if (poller.current === created) poller.current = null;
+    };
+  }, [router, interval, mode, background, autoStart, deferred]);
+
+  return useMemo(
+    () => ({
+      start: () => poller.current?.start(),
+      stop: () => poller.current?.stop(),
+    }),
+    [],
+  );
+}

package/src/precognition.js

@@ -0,0 +1,190 @@
+// Precognition: asking an action whether a field is valid, without running it.
+//
+// tinvar-spec.md, "Forms and mutations": "an action can be called in
+// validate-only mode (`validate('email')`, debounced, files excluded by
+// default), running its declared authorization and form request without the
+// method body." The endpoint does the server half: `Precognition: true` and
+// `Precognition-Validate-Only: email` run the order up to validation and
+// stop, answering 204 when the fields are fine and 422 with their errors
+// when not.
+//
+// What is asked is an action, or an endpoint (ADR 0125): `endpoint.
+// precognitive(name, { params })` is a target whose own `precognition`
+// asks the endpoint through `endpoint.validate()` -- the same headers, its
+// CSRF token, its checks -- and answers each field's errors, or null for
+// an answer that is no verdict on them.
+//
+// This is the client half, shared by <Form> and useForm: fields asked about
+// within the timeout go together in one request, the request still out is
+// replaced by the next (its fields go with it), and the answer touches only
+// the fields that were asked about -- an error elsewhere on the form, from a
+// submit, stays where it is.
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { actionUrl } from './action.js';
+import { withoutFiles } from './form-data.js';
+import { send } from './transport.js';
+
+/** Inertia's default: long enough not to ask on every keystroke. */
+export const VALIDATION_TIMEOUT_MS = 1500;
+
+/**
+ * @typedef {{ precognition: (fields: string[], input: Record<string, unknown>, signal: AbortSignal) => Promise<Record<string, string[]> | null> }} PrecognitionTarget
+ */
+
+/**
+ * Whether $target asks for itself -- an endpoint's -- rather than being an
+ * action to post to.
+ *
+ * @param {unknown} target
+ * @returns {target is PrecognitionTarget}
+ */
+export function isPrecognitionTarget(target) {
+  return (
+    target !== null &&
+    typeof target === 'object' &&
+    typeof (/** @type {{ precognition?: unknown }} */ (target).precognition) === 'function'
+  );
+}
+
+/**
+ * @param {{
+ *   action: () => import('./action.js').ActionTarget | PrecognitionTarget | null,
+ *   data: () => Record<string, unknown>,
+ *   setErrors: (update: (now: Record<string, string>) => Record<string, string>) => void,
+ *   errors: Record<string, string>,
+ *   timeout?: number | (() => number | undefined),
+ *   files?: boolean | (() => boolean | undefined),
+ * }} options `timeout` and `files` may be read when a field is validated
+ *   rather than when the hook is called -- useForm learns them after
+ */
+export function usePrecognition({ action, data, setErrors, errors, timeout, files }) {
+  const [validating, setValidating] = useState(false);
+  const [validated, setValidated] = useState(/** @type {ReadonlySet<string>} */ (new Set()));
+
+  const pending = useRef(/** @type {Set<string>} */ (new Set()));
+  const inFlight = useRef(/** @type {{ controller: AbortController, fields: string[] } | null} */ (null));
+  const timer = useRef(/** @type {ReturnType<typeof setTimeout> | undefined} */ (undefined));
+
+  const latest = useRef({ action, data, setErrors, timeout, files });
+  latest.current = { action, data, setErrors, timeout, files };
+
+  const cancel = useCallback(() => {
+    clearTimeout(timer.current);
+    pending.current.clear();
+    inFlight.current?.controller.abort();
+    inFlight.current = null;
+    setValidating(false);
+  }, []);
+
+  useEffect(() => cancel, [cancel]);
+
+  const run = useCallback(async () => {
+    const { action: target, data: read, setErrors: set } = latest.current;
+    const withFiles =
+      (typeof latest.current.files === 'function' ? latest.current.files() : latest.current.files) ?? false;
+    const to = target();
+    if (to === null) return;
+
+    // The request still out asked about some fields; this one asks about
+    // them too, since its answer is the one that will count.
+    const fields = [...new Set([...(inFlight.current?.fields ?? []), ...pending.current])];
+    pending.current.clear();
+    inFlight.current?.controller.abort();
+    if (fields.length === 0) return;
+
+    const controller = new AbortController();
+    inFlight.current = { controller, fields };
+    setValidating(true);
+
+    const values = read();
+    const payload = /** @type {Record<string, unknown>} */ (withFiles ? values : withoutFiles(values));
+
+    /** @type {Record<string, string[]> | null} */
+    let found;
+    if (isPrecognitionTarget(to)) {
+      // An endpoint's: JSON, so never a file, whatever validateFiles says.
+      found = await to.precognition(
+        fields,
+        /** @type {Record<string, unknown>} */ (withoutFiles(values)),
+        controller.signal,
+      );
+    } else {
+      const outcome = await send({
+        url: actionUrl(to),
+        data: payload,
+        headers: { Precognition: 'true', 'Precognition-Validate-Only': fields.join(',') },
+        signal: controller.signal,
+      });
+      // A 204 says every field asked about is fine; a 422 names the ones
+      // that are not. Anything else -- a 500, no answer -- says nothing
+      // about the input, and the fields are left as they were. So does a
+      // 422 with no errors in it: the endpoint refusing the request itself,
+      // a field the action does not declare, is an HTTP problem, not a
+      // verdict on the fields. Read as one with nothing wrong, it marked
+      // every field asked about valid -- an address the server had just
+      // refused among them.
+      found =
+        outcome.type === 'success'
+          ? {}
+          : outcome.type === 'validation' && namesErrors(outcome.body)
+            ? outcome.errors
+            : null;
+    }
+
+    if (inFlight.current?.controller !== controller) return;
+    inFlight.current = null;
+    setValidating(false);
+    if (found === null) return;
+
+    set((now) => {
+      const next = { ...now };
+      for (const field of fields) {
+        const message = found[field]?.[0];
+        if (message === undefined) delete next[field];
+        else next[field] = message;
+      }
+      return next;
+    });
+    setValidated((now) => {
+      const next = new Set(now);
+      for (const field of fields) {
+        if (found[field] === undefined) next.add(field);
+        else next.delete(field);
+      }
+      return next;
+    });
+  }, []);
+
+  const validate = useCallback(
+    (/** @type {string | string[]} */ field) => {
+      for (const name of Array.isArray(field) ? field : [field]) pending.current.add(name);
+      clearTimeout(timer.current);
+      const wait =
+        typeof latest.current.timeout === 'function' ? latest.current.timeout() : latest.current.timeout;
+      timer.current = setTimeout(() => void run(), wait ?? VALIDATION_TIMEOUT_MS);
+    },
+    [run],
+  );
+
+  const valid = useCallback(
+    (/** @type {string} */ field) => validated.has(field) && errors[field] === undefined,
+    [validated, errors],
+  );
+  const invalid = useCallback((/** @type {string} */ field) => errors[field] !== undefined, [errors]);
+
+  return useMemo(
+    () => ({ validate, validating, valid, invalid, cancelValidation: cancel }),
+    [validate, validating, valid, invalid, cancel],
+  );
+}
+
+/**
+ * Whether a 422's body is the endpoint's verdict on the fields: it carries
+ * `errors`, the fields it found wrong.
+ *
+ * @param {any} body
+ */
+function namesErrors(body) {
+  return body?.errors !== null && typeof body?.errors === 'object';
+}

package/src/prefetch-cache.d.ts

@@ -0,0 +1,46 @@
+/** The prefetch cache: pages fetched ahead of a click, kept for a while. */
+
+/** How long a prefetched page is used for when `cacheFor` is not given, in ms. */
+export declare const DEFAULT_CACHE_FOR: number;
+/** How many prefetched pages are kept at once; the oldest goes first. */
+export declare const MAX_ENTRIES: number;
+
+/** A number of milliseconds, or `'500ms'`, `'30s'`, `'1m'`, `'2h'`, `'1d'`. Throws on anything else. */
+export declare function parseDuration(value: number | string): number;
+
+/** When a page stops being fresh, and when it stops being usable at all, in ms after it arrived. */
+export declare function cacheWindow(
+  cacheFor?: number | string | readonly [number | string, number | string],
+): { fresh: number; stale: number };
+
+export interface Entry {
+  url: string;
+  tags: string[];
+  window: { fresh: number; stale: number };
+  response: Promise<Response | null>;
+  controller: AbortController;
+  binding: string | null;
+  /** The CSRF cookie the page held when this was asked for; it rotates with the session. */
+  csrf: string | null;
+  arrivedAt: number | null;
+  /** The #[Once] keys it was asked for with, whose fields it may have been sent without. */
+  claimed?: readonly string[];
+  /** The history key the page came with, imported; the kept response has no header for it. */
+  historyKey?: import('./remember-store.js').HistoryKey | null;
+}
+
+export declare class PrefetchCache {
+  constructor(options?: { max?: number; now?: () => number });
+  readonly size: number;
+  lookup(url: string): { entry: Entry; stale: boolean } | null;
+  add(entry: Entry): void;
+  arrived(entry: Entry, binding: string | null): boolean;
+  forget(entry: Entry): void;
+  delete(url: string): void;
+  clear(): void;
+  abortInFlight(): void;
+  /** Forgets every entry carrying any of these tags; returns how many. */
+  deleteTagged(tags: Iterable<string>): number;
+  /** Forgets every entry asked for claiming any of these once keys. */
+  deleteClaiming(keys: readonly string[]): void;
+}