@tinvar/react 0.0.0-stage → 0.4.0

package/src/submit.js

@@ -0,0 +1,333 @@
+// One submission of an action, start to finish: send it, then do what the
+// answer says to the page.
+//
+// <Form> and useForm both submit through here, so "top-level props control
+// the submission, `options` controls the visit after it" means the same in
+// each. The visit after it is whatever the answer asks for:
+//
+//   a redirect             a client visit there, with `options`
+//   a re-rendered payload  mounted as the page that is up, with `options`
+//   revalidated, no payload  the page reloaded -- "reload that route yourself"
+//   any success            every prefetched page, dropped
+//   invalidated tags       the page's loaded <Deferred> boundaries, fetched
+//                          again
+//   a flash                onFlash, and a `tinvar:flash` event
+//
+// and only then onSuccess, so a callback sees the page the action left.
+// Around all of it, the router's `actionStart` and `actionSettle` -- once
+// the answer has been applied, whatever it was -- and `progress` as files
+// upload.
+
+import { actionName, actionUrl, optimisticPatch } from './action.js';
+import { beginRevalidation, revalidateDeferred } from './deferred-revalidation.js';
+import { invalidatedTags } from './router.js';
+import { send } from './transport.js';
+import {
+  announceAction,
+  announceFlash,
+  applyPayloads,
+  assignLocation,
+  endSession,
+  flushAfterAction,
+  followRedirect,
+  routeTokens,
+} from './router-hooks.js';
+
+/**
+ * @typedef {{
+ *   value: unknown,
+ *   flash: Record<string, unknown>,
+ *   revalidated: string[],
+ *   payloads: Record<string, string>,
+ *   redirect?: string,
+ * }} ActionResult
+ *
+ * @typedef {{
+ *   status: number,
+ *   code: string | null,
+ *   reference: string | null,
+ *   retryAfter: number | null,
+ *   body: unknown,
+ * }} HttpFailure
+ *
+ * @typedef {{
+ *   onStart?: () => void,
+ *   onProgress?: (progress: import('./transport.js').Progress) => void,
+ *   onSuccess?: (result: ActionResult) => void | Promise<void>,
+ *   onError?: (errors: Record<string, string[]>) => void,
+ *   onHttpException?: (failure: HttpFailure) => void,
+ *   onNetworkError?: (error: unknown) => void,
+ *   onCancel?: () => void,
+ *   onFinish?: () => void,
+ *   onFlash?: (flash: Record<string, unknown>) => void,
+ *   onExpired?: () => void,
+ * }} Callbacks
+ *
+ * @typedef {(
+ *   | { type: 'success', result: ActionResult }
+ *   | { type: 'validation', errors: Record<string, string[]> }
+ *   | { type: 'http', failure: HttpFailure }
+ *   | { type: 'network', error: unknown }
+ *   | { type: 'expired' }
+ *   | { type: 'cancelled' }
+ * )} Submitted
+ */
+
+/**
+ * @param {{
+ *   action: import('./action.js').ActionTarget,
+ *   data: Record<string, unknown>,
+ *   router?: import('./router-hooks.js').RouterLike,
+ *   options?: Record<string, unknown>,
+ *   headers?: Record<string, string>,
+ *   callbacks?: Callbacks,
+ *   signal?: AbortSignal,
+ *   hardNavigate?: (url: string) => void,
+ *   optimistic?: import('./optimistic.js').Store | null,
+ * }} submission
+ * @returns {Promise<Submitted>}
+ */
+export async function submitAction({
+  action,
+  data,
+  router,
+  options = {},
+  headers = {},
+  callbacks = {},
+  signal,
+  hardNavigate = assignLocation,
+  optimistic = null,
+}) {
+  const name = actionName(action);
+
+  // "The client sends the route tokens it is holding", so the action can
+  // re-render the page that is up. Transport, not input: the endpoint takes
+  // them off before the form request sees the data.
+  const tokens = routeTokens(router);
+  const body = tokens.length > 0 ? { ...data, _routes: tokens } : data;
+
+  // `action.optimistic(patch)`: the patch shows from now, and gives way to
+  // the server's re-render once the answer -- payload and all -- has been
+  // applied, or is dropped when the request fails (ADR 0016).
+  const ticket = optimisticBegin(optimistic, action);
+
+  // An action that carries the mounted page's token may re-render it, so
+  // the page's <Deferred> boundaries show their content as `reloading`
+  // until it is known whether it did -- and fetch it again if so.
+  const revalidation = tokens.length > 0 ? beginRevalidation() : null;
+  let rerendered = false;
+  // Tags the action invalidated, on the page it leaves up: what a mounted
+  // fragment shows may have read them, whether or not a route was
+  // re-rendered -- or a route token sent at all.
+  let tagged = false;
+
+  const settle = (/** @type {boolean} */ succeeded) => {
+    if (ticket !== null && optimistic) optimistic.settle(ticket, succeeded);
+    if (revalidation) revalidation({ revalidated: tagged || rerendered });
+    else if (tagged) revalidateDeferred();
+  };
+  let succeeded = false;
+
+  // How the call came back, for its `actionSettle`: what it returned, or
+  // `error` for something that threw on the way.
+  /** @type {{ type: string, status?: number }} */
+  let settledAs = { type: 'error' };
+  const settled = (/** @type {Submitted} */ submitted) => {
+    settledAs =
+      submitted.type === 'http'
+        ? { type: 'http', status: submitted.failure.status }
+        : { type: submitted.type };
+    return submitted;
+  };
+
+  announceAction(router, 'actionStart', { action: name });
+  call(callbacks.onStart);
+
+  try {
+    const outcome = await send({
+      url: actionUrl(name),
+      data: body,
+      headers,
+      signal,
+      onUploadProgress: (progress) => {
+        announceAction(router, 'progress', { action: name, progress });
+        callbacks.onProgress?.(progress);
+      },
+    });
+
+    switch (outcome.type) {
+      case 'success': {
+        const result = resultOf(outcome.body);
+        flushAfterAction(router, outcome.headers);
+        if (Object.keys(result.flash).length > 0) {
+          call(callbacks.onFlash, result.flash);
+          announceFlash(router, result.flash, name);
+        }
+        rerendered = await applyPayloads(
+          router,
+          result.payloads,
+          result.revalidated,
+          options,
+          tokens[0] ?? null,
+          outcome.body?.live,
+        );
+        tagged = invalidatedTags(outcome.headers).length > 0;
+        succeeded = true;
+        settle(true);
+        await callAsync(callbacks.onSuccess, result);
+        return settled({ type: 'success', result });
+      }
+
+      case 'redirect':
+      case 'location': {
+        const result = { ...resultOf(null), redirect: outcome.location };
+        flushAfterAction(router, outcome.headers);
+        // X-Location is another origin, allowlisted by the server: always a
+        // document load, as the router treats one.
+        if (outcome.type === 'redirect')
+          await followRedirect(router, outcome.location, options, hardNavigate);
+        else hardNavigate(outcome.location);
+        succeeded = true;
+        settle(true);
+        await callAsync(callbacks.onSuccess, result);
+        return settled({ type: 'success', result });
+      }
+
+      case 'validation':
+        // The patch goes; the errors stay, on the form that owns them.
+        call(callbacks.onError, outcome.errors);
+        return settled({ type: 'validation', errors: outcome.errors });
+
+      case 'http': {
+        /** @type {HttpFailure} */
+        const failure = {
+          status: outcome.status,
+          code: outcome.code,
+          reference: outcome.reference,
+          retryAfter: outcome.retryAfter,
+          body: outcome.body,
+        };
+        call(callbacks.onHttpException, failure);
+
+        // The session is over, and what the form holds belongs to it; see
+        // endSession().
+        if (outcome.status === 401) endSession(router, hardNavigate);
+        return settled({ type: 'http', failure });
+      }
+
+      case 'network':
+        call(callbacks.onNetworkError, outcome.error);
+        return settled({ type: 'network', error: outcome.error });
+
+      case 'expired':
+        // Refused twice for its token: the page outlived its session. "A
+        // 419 becomes a same-origin redirect back with a 'page expired'
+        // flash, not an error screen." Back is this page, loaded again --
+        // a client visit, so what was typed stays -- which hands the
+        // session's current token over; the form says the page expired.
+        call(callbacks.onExpired);
+        if (typeof router?.reload === 'function') {
+          await router.reload({ preserveScroll: true });
+          rerendered = true;
+        } else {
+          hardNavigate(globalThis.location.href);
+        }
+        return settled({ type: 'expired' });
+
+      default:
+        call(callbacks.onCancel);
+        return settled({ type: 'cancelled' });
+    }
+  } finally {
+    // Every way but success rolls the patch back: a refusal, a failure, no
+    // answer, a cancel -- and a throw on the way, which would otherwise
+    // leave it showing for good.
+    if (!succeeded) settle(false);
+    announceAction(router, 'actionSettle', { action: name, ...settledAs });
+    call(callbacks.onFinish);
+  }
+}
+
+/**
+ * Begins an action's optimistic patch on the store, if it carries one and
+ * there is a store to patch.
+ *
+ * @param {import('./optimistic.js').Store | null | undefined} store
+ * @param {import('./action.js').ActionTarget} action
+ * @returns {number | null}
+ */
+function optimisticBegin(store, action) {
+  const patch = optimisticPatch(action);
+  if (patch === null) return null;
+  if (!store) {
+    // Nothing to patch: the request still runs. Said once, so an app that
+    // forgot the boundary finds out why nothing moved.
+    if (!warnedNoStore) {
+      warnedNoStore = true;
+      console.warn('[tinvar:client] An optimistic action ran with no <OptimisticState> above it to patch.');
+    }
+    return null;
+  }
+  return store.begin(patch);
+}
+
+let warnedNoStore = false;
+
+/**
+ * The endpoint's body as an ActionResult, whatever arrived: a field the
+ * server left out, or sent as the wrong shape, is the empty one.
+ *
+ * @param {any} body
+ * @returns {ActionResult}
+ */
+export function resultOf(body) {
+  const object = (/** @type {unknown} */ value) =>
+    value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+
+  return {
+    value: body?.value ?? null,
+    flash: /** @type {Record<string, unknown>} */ (object(body?.flash)),
+    revalidated: Array.isArray(body?.revalidated)
+      ? body.revalidated.filter((r) => typeof r === 'string')
+      : [],
+    payloads: /** @type {Record<string, string>} */ (object(body?.payloads)),
+  };
+}
+
+/**
+ * Runs an app callback. Its exception is its own bug, not the submission's:
+ * reported, as dispatchEvent reports a listener's, and the submission goes
+ * on -- a throw in onStart must not leave a form processing for good.
+ *
+ * @template {unknown[]} A
+ * @param {((...args: A) => unknown) | undefined} fn
+ * @param {A} args
+ */
+export function call(fn, ...args) {
+  if (typeof fn !== 'function') return;
+  try {
+    fn(...args);
+  } catch (error) {
+    report(error);
+  }
+}
+
+/**
+ * @template {unknown[]} A
+ * @param {((...args: A) => unknown) | undefined} fn
+ * @param {A} args
+ */
+async function callAsync(fn, ...args) {
+  if (typeof fn !== 'function') return;
+  try {
+    await fn(...args);
+  } catch (error) {
+    report(error);
+  }
+}
+
+/** @param {unknown} error */
+function report(error) {
+  if (typeof globalThis.reportError === 'function') globalThis.reportError(error);
+  else console.error(error);
+}

package/src/telemetry.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Client telemetry: each page's web vitals and the errors its script saw, reported to /_vitals and
+ * /_errors, and the violations of a policy in a meta element, reported to /_reports.
+ */
+
+import type { Router } from './router.js';
+
+export declare const VITALS_PATH: '/_vitals';
+export declare const ERRORS_PATH: '/_errors';
+export declare const REPORTS_PATH: '/_reports';
+
+/** The server's cap on one report, in bytes. */
+export declare const MAX_BODY_BYTES: number;
+
+/** Errors reported for one page, at most. */
+export declare const MAX_ERRORS_PER_PAGE: number;
+
+/** Errors in one report. */
+export declare const MAX_ERRORS_PER_REPORT: number;
+
+/** How long errors are gathered before they are sent, in milliseconds. */
+export declare const ERROR_DELAY_MS: number;
+
+/** NAV is a client navigation's: from the visit's start to its page's mount. LCP, FCP and TTFB are the document's alone. */
+export type VitalName = 'LCP' | 'INP' | 'CLS' | 'FCP' | 'TTFB' | 'NAV';
+
+/** Where an error was seen: the window's events, or one of React's root hooks. */
+export type ClientErrorKind = 'error' | 'rejection' | 'caught' | 'uncaught' | 'recoverable';
+
+/** The largest value of each vital the server believes: milliseconds, and a score for CLS. */
+export declare const VITAL_CEILINGS: Readonly<Record<VitalName, number>>;
+
+/** Policy violations sent for one document, at most. */
+export declare const MAX_VIOLATIONS: number;
+
+/** The route name a route token names, read without verifying; null for anything else. */
+export declare function routeNameOf(token: string | null | undefined): string | null;
+
+export interface TelemetryOptions {
+  /** The page's router: the page on screen is read from it. Without one, the document's page metadata. */
+  router?: (Pick<Router, 'on' | 'routeTokens'> & Partial<Pick<Router, 'currentView'>>) | null;
+  window?: Window;
+  fetch?: typeof fetch;
+  /** Measure and send web vitals; true unless false. */
+  vitals?: boolean;
+  /** Listen for the window's errors and unhandled rejections; true unless false. */
+  errors?: boolean;
+  /** Send the violations of a policy in a meta element to /_reports; true unless false. */
+  violations?: boolean;
+}
+
+export interface Telemetry {
+  /** Starts measuring and listening; each page's vitals are sent once, when it is left or first hidden. */
+  start(): Telemetry;
+  /** Stops listening and measuring, sending nothing more. */
+  stop(): void;
+  /** Reports an error for the page on screen: deduplicated, capped per page, and sent in a moment. */
+  reportError(error: unknown, kind?: ClientErrorKind): void;
+  /** For hydrateRoot()'s options: reports, then logs to the console as React does. */
+  readonly onCaughtError: (error: unknown, errorInfo?: unknown) => void;
+  /** For hydrateRoot()'s options: reports, then hands the error to the browser as React does. */
+  readonly onUncaughtError: (error: unknown, errorInfo?: unknown) => void;
+  /** For hydrateRoot()'s options: reports, then hands the error to the browser as React does. */
+  readonly onRecoverableError: (error: unknown, errorInfo?: unknown) => void;
+  /** Sends the errors waiting now. */
+  flush(): void;
+  /** The page on screen's vitals measured so far: milliseconds, and a score for CLS. */
+  vitals(): Partial<Record<VitalName, number>>;
+}
+
+export declare function createTelemetry(options?: TelemetryOptions): Telemetry;