@tinvar/react 0.0.0-stage → 0.4.1

package/src/document-load.js

@@ -0,0 +1,95 @@
+// A document load the page has begun: the router sending the browser off to
+// another origin or a full load, an action's X-Location, a sign-out.
+//
+// What ends the session on this client loads the page again, so nothing of
+// the old session stays on screen: a 401 heard by the live stream's trade
+// (live.js), by a <Deferred> boundary's fetch (deferred-boundary.js), by a
+// form, a useHttp call or an upload (endSession() in router-hooks.js), or by
+// the router for the page on screen -- a poll, a prefetch, a list's next
+// page, a reload(), a page fetched in the background drawn for another
+// session (router.js). Begun after a load was, that reload replaced it: an
+// action that replaced the session and sent the browser on landed it back
+// on the page it left. So a load begun is left to arrive, for this long;
+// one that never does -- a download, a navigation stopped -- is loaded over
+// once its time is up (reloadUnlessLoading()).
+
+/** How long a document load begun is waited for before the page is reloaded over it, in ms. */
+export const DOCUMENT_LOAD_MS = 10_000;
+
+/** @type {{ url: string, at: number } | null} */
+let begun = null;
+
+/**
+ * The page is being replaced by a document load of $url.
+ *
+ * @param {string} url
+ * @param {number} [at] when, in ms; now unless given
+ */
+export function markDocumentLoad(url, at = Date.now()) {
+  begun = { url, at };
+}
+
+/**
+ * How long, in ms, a document load begun in the last DOCUMENT_LOAD_MS is
+ * still waited for; 0 when none is.
+ *
+ * @param {number} [now]
+ * @returns {number}
+ */
+export function documentLoadWait(now = Date.now()) {
+  return begun === null ? 0 : Math.max(0, begun.at + DOCUMENT_LOAD_MS - now);
+}
+
+/** Forgets a load begun: the page is on screen again, restored from the back-forward cache. */
+export function clearDocumentLoad() {
+  begun = null;
+}
+
+/**
+ * Loads the page on screen again, without its fragment, for what heard the
+ * session end -- unless a document load has begun, which is the page being
+ * replaced already: an action that ended the session and sent the browser
+ * on. Loading this page over it would replace that load with this page, and
+ * land the browser back on the page it was leaving. Then the reload waits
+ * for it, and is made only if it has not come once its time is up -- or, if
+ * another was begun meanwhile, once that one's is.
+ *
+ * Only the load waits. What the session held is the caller's to clear, and
+ * at once (revokeSession()): an action sent, or a page shown, while the
+ * load is on its way must not carry it.
+ *
+ * @param {(url: string) => void} load the document load, given the page's URL
+ * @param {{ location?: { href: string } }} [win] whose page it is; the window's unless given
+ * @returns {() => void} forgets the reload, while it still waits
+ */
+export function reloadUnlessLoading(load, win = globalThis) {
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let timer = null;
+
+  const reload = () => {
+    timer = null;
+    const wait = documentLoadWait();
+    if (wait > 0) {
+      timer = setTimeout(reload, wait);
+      return;
+    }
+
+    const href = win.location?.href;
+    if (href === undefined) return;
+    // Without the fragment: assigning the URL the document already has,
+    // fragment and all, scrolls to it and loads nothing.
+    const url = new URL(href);
+    url.hash = '';
+    load(url.href);
+  };
+
+  reload();
+  return () => {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+  };
+}
+
+globalThis.addEventListener?.('pageshow', (/** @type {PageTransitionEvent} */ event) => {
+  if (event.persisted) clearDocumentLoad();
+});

package/src/endpoint.d.ts

@@ -0,0 +1,87 @@
+/** What one endpoint takes and answers with, as codegen describes it. */
+export interface EndpointShape {
+  params: object;
+  input: object;
+  returns: unknown;
+}
+
+/** Endpoint name => what it answers, where, and with what. */
+export type EndpointTable<M> = {
+  readonly [N in keyof M]: {
+    readonly methods: readonly string[];
+    readonly segments: readonly string[];
+    /** The host pattern of one on a host of its own (ADR 0149); none for the primary host. */
+    readonly host?: string;
+    readonly returns: 'data' | 'nothing' | 'response';
+  };
+};
+
+/** An endpoint that answered with anything but a 2xx: its status, its body, and a 422's field errors. */
+export declare class EndpointError extends Error {
+  readonly endpoint: string;
+  readonly status: number;
+  readonly body: unknown;
+  readonly errors: Record<string, string[]>;
+}
+
+/**
+ * What `useForm().withPrecognition()` and `<Form validateAgainst>` ask
+ * instead of an action (ADR 0125): an endpoint, by `endpoint.precognitive()`.
+ */
+export interface PrecognitionTarget {
+  readonly endpoint?: string;
+  /** Each field's errors, none when they would do; null for an answer that says nothing about them. */
+  precognition(
+    fields: string[],
+    input: Record<string, unknown>,
+    signal: AbortSignal,
+  ): Promise<Record<string, string[]> | null>;
+}
+
+export interface CallOptions<S extends EndpointShape> {
+  params: S['params'];
+  input?: S['input'];
+  /** One of the methods it answers; its first unless given. */
+  method?: string;
+  signal?: AbortSignal;
+  fetch?: typeof fetch;
+}
+
+export interface Endpoints<M extends { [N in keyof M]: EndpointShape }> {
+  /** The URL of an endpoint, with a GET's input as its query string. */
+  url<N extends keyof M & string>(name: N, params: M[N]['params'], query?: M[N]['input']): string;
+  /**
+   * Calls an endpoint: its Data parsed, nothing for a void one, or the
+   * Response for one that returns a Response. Anything but a 2xx throws an
+   * EndpointError.
+   */
+  call<N extends keyof M & string>(name: N, options: CallOptions<M[N]>): Promise<M[N]['returns']>;
+  /**
+   * Precognition (ADR 0074): the endpoint's checks and form requests -- or
+   * only the fields in `only` -- without its body. Each field's errors;
+   * none when the input would do.
+   */
+  validate<N extends keyof M & string>(
+    name: N,
+    options: CallOptions<M[N]> & { input?: Partial<M[N]['input']>; only?: readonly string[] },
+  ): Promise<Record<string, string[]>>;
+  /**
+   * The endpoint as a form's validate() asks it (ADR 0125):
+   * `useForm(data).withPrecognition(endpoint.precognitive('racks.resize', { params: { rack } }))`,
+   * or `<Form validateAgainst={...}>`.
+   */
+  precognitive<N extends keyof M & string>(
+    name: N,
+    options?: Omit<CallOptions<M[N]>, 'input' | 'signal'>,
+  ): PrecognitionTarget;
+  /**
+   * Whether a URL is one of these endpoints', at any method: what the
+   * router is given as `endpoints`, so a link to one is left to the browser.
+   */
+  matches(url: URL | string): boolean;
+}
+
+/** Builds the typed `endpoint` codegen exports from its table. */
+export declare function endpoints<M extends { [N in keyof M]: EndpointShape }>(
+  table: EndpointTable<M>,
+): Endpoints<M>;

package/src/endpoint.js

@@ -0,0 +1,304 @@
+// Calling the application's #[Get], #[Post] and #[Endpoint] routes, from the
+// table codegen writes (ADR 0067).
+//
+// `endpoint.url('orders.receipt', { order })` builds a link, by the rules
+// route() builds a page's by; `endpoint.call('products.stock', { params:
+// { product } })` fetches one and answers with what the PHP method returns:
+// its Data object, parsed, for one that returns Data; nothing, for one that
+// returns void; the Response itself for one that returns a Response, which
+// is the caller's to read -- a download, a file, a body of its own type.
+//
+// A method that changes something carries the session's CSRF token, read
+// from the cookie as the request is sent, as every action does. The URL is
+// always a path on this origin -- the table holds nothing else -- so the
+// token never goes anywhere else. A GET's input goes in the query string,
+// anything else's in a JSON body. No method is ever spoofed: a method is
+// sent as itself, and PHP reads nothing that says otherwise.
+//
+// What a call that may write invalidated -- its answer's X-Invalidated-Tags
+// -- is flushed from every router's prefetch cache, as an action's is.
+//
+// No React and nothing from Node: a server component can build a URL with
+// it, and a client component can call one.
+
+import { CSRF_HEADER, csrfToken } from './csrf.js';
+import { revalidateDeferred } from './deferred-revalidation.js';
+import { routes } from './route.js';
+import { flushInvalidated } from './router.js';
+
+/** An endpoint that answered with anything but a 2xx. */
+export class EndpointError extends Error {
+  /**
+   * @param {string} name
+   * @param {number} status
+   * @param {unknown} body
+   */
+  constructor(name, status, body) {
+    super(`[tinvar] The endpoint '${name}' answered ${status}.`);
+    this.name = 'EndpointError';
+    this.endpoint = name;
+    this.status = status;
+    this.body = body;
+    /** @type {Record<string, string[]>} */
+    this.errors =
+      status === 422 && body !== null && typeof body === 'object' && 'errors' in body
+        ? /** @type {Record<string, string[]>} */ (body.errors)
+        : {};
+  }
+}
+
+/**
+ * @typedef {{ methods: readonly string[], segments: readonly string[], host?: string, returns: 'data' | 'nothing' | 'response' }} EndpointEntry
+ */
+
+/**
+ * @param {Record<string, EndpointEntry>} table endpoint name => what it answers, where, and with what --
+ *        with the host pattern of one on a host of its own (ADR 0149), which route() writes a path on
+ *        that host and an absolute URL anywhere else, as it does for a page
+ */
+export function endpoints(table) {
+  /** @type {Record<string, readonly string[] | { segments: readonly string[], host: string }>} */
+  const paths = {};
+  for (const [name, entry] of Object.entries(table)) {
+    paths[name] =
+      typeof entry.host === 'string' ? { segments: entry.segments, host: entry.host } : entry.segments;
+  }
+  const path = routes(paths);
+
+  /**
+   * @param {string} name
+   * @returns {EndpointEntry}
+   */
+  const entryOf = (name) => {
+    if (!Object.hasOwn(table, name)) throw new Error(`[tinvar] No endpoint is named '${name}'.`);
+    return table[name];
+  };
+
+  /**
+   * @param {string} name
+   * @param {Record<string, unknown>} [params]
+   * @param {Record<string, unknown>} [query]
+   */
+  const url = (name, params, query) => {
+    entryOf(name);
+    const base = path(name, params ?? {});
+    const search = toQuery(query);
+    return search === '' ? base : `${base}?${search}`;
+  };
+
+  /**
+   * @param {string} name
+   * @param {{ params?: Record<string, unknown>, input?: Record<string, unknown>, method?: string, signal?: AbortSignal, fetch?: typeof fetch }} [options]
+   */
+  const call = async (name, options = {}) => {
+    const entry = entryOf(name);
+    const method = (options.method ?? entry.methods[0]).toUpperCase();
+    if (!entry.methods.includes(method)) {
+      throw new Error(`[tinvar] The endpoint '${name}' does not answer ${method}.`);
+    }
+
+    const safe = method === 'GET';
+    /** @type {Record<string, string>} */
+    const headers = { accept: 'application/json' };
+    const target = safe ? url(name, options.params, options.input) : url(name, options.params);
+    assertStaysPut(name, target, entry.segments.length);
+    /** @type {string | undefined} */
+    let body;
+    if (!safe) {
+      headers['content-type'] = 'application/json';
+      body = JSON.stringify(options.input ?? {});
+      const token = csrfToken();
+      if (token !== null) headers[CSRF_HEADER] = token;
+    }
+
+    const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const response = await doFetch(target, {
+      method,
+      headers,
+      body,
+      signal: options.signal,
+      credentials: 'same-origin',
+      // Nothing is followed: a redirect is the caller's to read, never a
+      // second request somewhere else with the token on it.
+      redirect: 'manual',
+    });
+
+    // What a call that may write invalidated, as an action's answer says
+    // it: the pages prefetched under those tags are dropped from every
+    // router on the page, and the fragments on screen fetched again
+    // (ADR 0106). Read before anything else, whatever the status -- a
+    // redirect or an error may follow writes that are in.
+    if (!safe && flushInvalidated(response.headers).length > 0) revalidateDeferred();
+
+    if (entry.returns === 'response' && response.ok) return response;
+    if (!response.ok) {
+      const text = await response.text();
+      let parsed = /** @type {unknown} */ (text);
+      try {
+        parsed = text === '' ? null : JSON.parse(text);
+      } catch {
+        // Not JSON: the text is the body.
+      }
+      throw new EndpointError(name, response.status, parsed);
+    }
+    if (entry.returns === 'nothing') return undefined;
+
+    return response.json();
+  };
+
+  /**
+   * Precognition (ADR 0074): asks whether input would do, without running
+   * the endpoint -- its checks and its form requests, all of them or only
+   * the fields in `only`. Resolves with each field's errors, none when the
+   * input would do; anything but a 204 or a 422 throws an EndpointError.
+   *
+   * @param {string} name
+   * @param {{ params?: Record<string, unknown>, input?: Record<string, unknown>, only?: readonly string[], method?: string, signal?: AbortSignal, fetch?: typeof fetch }} [options]
+   * @returns {Promise<Record<string, string[]>>}
+   */
+  const validate = async (name, options = {}) => {
+    const entry = entryOf(name);
+    const method = (options.method ?? entry.methods[0]).toUpperCase();
+    if (!entry.methods.includes(method)) {
+      throw new Error(`[tinvar] The endpoint '${name}' does not answer ${method}.`);
+    }
+
+    const safe = method === 'GET';
+    /** @type {Record<string, string>} */
+    const headers = { accept: 'application/json', Precognition: 'true' };
+    if (options.only !== undefined && options.only.length > 0) {
+      headers['Precognition-Validate-Only'] = options.only.join(',');
+    }
+    const target = safe ? url(name, options.params, options.input) : url(name, options.params);
+    assertStaysPut(name, target, entry.segments.length);
+    /** @type {string | undefined} */
+    let body;
+    if (!safe) {
+      headers['content-type'] = 'application/json';
+      body = JSON.stringify(options.input ?? {});
+      const token = csrfToken();
+      if (token !== null) headers[CSRF_HEADER] = token;
+    }
+
+    const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const response = await doFetch(target, {
+      method,
+      headers,
+      body,
+      signal: options.signal,
+      credentials: 'same-origin',
+      redirect: 'manual',
+    });
+    if (response.status === 204) return {};
+
+    const text = await response.text();
+    let parsed = /** @type {unknown} */ (text);
+    try {
+      parsed = text === '' ? null : JSON.parse(text);
+    } catch {
+      // Not JSON: the text is the body.
+    }
+    const error = new EndpointError(name, response.status, parsed);
+    if (response.status === 422 && Object.keys(error.errors).length > 0) return error.errors;
+    throw error;
+  };
+
+  /**
+   * What `useForm().withPrecognition()` and `<Form validateAgainst>` take
+   * to ask an endpoint, not an action, whether fields would do (ADR 0125):
+   * the endpoint's name and where it is, and the fields asked about with
+   * the form's data at the time. Resolves with each field's errors, or
+   * null for an answer that says nothing about them -- a 403, a 500, no
+   * answer -- so the fields are left as they were.
+   *
+   * @param {string} name
+   * @param {{ params?: Record<string, unknown>, method?: string, fetch?: typeof fetch }} [options]
+   */
+  const precognitive = (name, options = {}) => {
+    entryOf(name);
+    return Object.freeze({
+      endpoint: name,
+      /**
+       * @param {string[]} fields
+       * @param {Record<string, unknown>} input
+       * @param {AbortSignal} signal
+       */
+      precognition: async (fields, input, signal) => {
+        try {
+          return await validate(name, { ...options, input, only: fields, signal });
+        } catch (error) {
+          if (
+            error instanceof EndpointError ||
+            /** @type {{ name?: unknown }} */ (error)?.name === 'AbortError'
+          )
+            return null;
+          throw error;
+        }
+      },
+    });
+  };
+
+  /**
+   * Whether a URL is one of these endpoints': a path one of them answers,
+   * by the rules PHP matches it by -- each literal segment equal, each
+   * parameter some segment, and never under `/_`. Any method: a link is
+   * followed with GET, and whatever answers is not a page. The router
+   * leaves such a link to the browser (ADR 0074).
+   *
+   * @param {URL | string} target a URL, or a path
+   */
+  const matches = (target) => {
+    let pathname;
+    try {
+      pathname = new URL(String(target), 'http://placeholder').pathname;
+    } catch {
+      return false;
+    }
+    const parts = pathname.split('/').filter((part) => part !== '');
+    if (parts.length > 0 && parts[0].startsWith('_')) return false;
+    return Object.values(table).some(
+      (entry) =>
+        entry.segments.length === parts.length &&
+        entry.segments.every((segment, index) =>
+          segment.startsWith('{') && segment.endsWith('}') ? parts[index] !== '' : segment === parts[index],
+        ),
+    );
+  };
+
+  return { url, call, validate, precognitive, matches };
+}
+
+/**
+ * Defence in depth behind route()'s segment rule: the path the browser will
+ * actually request -- after it has resolved dots and backslashes -- must be
+ * the one built, on this origin, with the table's number of segments.
+ * Anything else is refused before a request carrying the CSRF token leaves.
+ *
+ * @param {string} name
+ * @param {string} target
+ * @param {number} segments
+ */
+function assertStaysPut(name, target, segments) {
+  const base = globalThis.location?.origin ?? 'http://localhost';
+  const path = target.split('?', 1)[0];
+  const resolved = new URL(target, base);
+  const parts = path === '/' ? 0 : path.split('/').length - 1;
+  if (resolved.origin !== new URL(base).origin || resolved.pathname !== path || parts !== segments) {
+    throw new Error(`[tinvar] The endpoint '${name}' would be sent somewhere else than ${path}.`);
+  }
+}
+
+/**
+ * A query string from plain values, each key once; a list repeats its key.
+ *
+ * @param {Record<string, unknown> | undefined} query
+ */
+function toQuery(query) {
+  if (query === undefined) return '';
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) continue;
+    for (const item of Array.isArray(value) ? value : [value]) search.append(key, String(item));
+  }
+  return search.toString();
+}