@tinvar/react 0.0.0-stage → 0.4.1

package/src/once-store.js

@@ -0,0 +1,211 @@
+// What the browser keeps of #[Once] fields: the subtree rendered from each,
+// by its once key (ADR 0020).
+//
+// The server sends a once field's rendered content once; after that a
+// request lists the key in X-Have-Once and gets a marker in its place,
+// which <OnceSlot> fills from here. Under RSC there is no field value on
+// the client to keep -- server components read their data on the server --
+// so what is kept is what was drawn from it: React elements, decoded from
+// a payload. They cannot be serialized, so they live in memory only, and a
+// document load starts with none.
+//
+// Client-held data, bound to the session it was rendered for: every entry
+// carries the binding of the page it arrived with, is only ever read for a
+// page of the same binding, and goes when that session does.
+//
+// Claiming and holding are kept apart. An entry stops being claimed -- its
+// key left out of X-Have-Once -- when its time is up or a tag it carries is
+// invalidated, so the next response sends it fresh. But its content stays
+// until that fresh copy replaces it: a response already on its way, or a
+// prefetched one, may have been answered while the key was still claimed,
+// and has only this to fill its hole with. It shows what it would have
+// shown had it arrived a moment sooner, and nothing is ever left empty.
+//
+// A key names content rendered for one subject -- a default key, the page
+// it was rendered for -- so there is one entry for each page visited, not
+// one for each field. Most recently used first: that is the order they are
+// claimed in, so the request's list, which the server reads only so far,
+// always starts with the page on screen's; and only so many are kept, the
+// least recently used dropped first. The router hears which, and drops any
+// prefetched page that claimed one, which nothing could fill any more.
+//
+// A once-shared value (ADR 0065) is kept here too, under its `$shared.key`,
+// with the signed hold the server sent it with. It is claimed by that hold,
+// in X-Have-Shared, never by its key in X-Have-Once: the server reads a
+// shared key as held only on a hold it can verify for this session, user,
+// tenant, panel and build.
+
+/** How many rendered fields are kept, at most, before the least recently used go. */
+export const MAX_KEPT = 256;
+
+/**
+ * @typedef {{
+ *   binding: string,
+ *   content: unknown,
+ *   expiresAt: number | null,
+ *   tags: readonly string[],
+ *   claimable: boolean,
+ *   hold: string | null,
+ * }} Held
+ */
+
+/**
+ * @param {{ now?: () => number, max?: number }} [options]
+ */
+export function createOnceStore({ now = () => Date.now(), max = MAX_KEPT } = {}) {
+  /**
+   * Least recently used first, as a Map iterates once each use moves its
+   * entry to the end.
+   *
+   * @type {Map<string, Held>}
+   */
+  const entries = new Map();
+
+  /**
+   * Every entry that may be claimed under a binding: kept under it, still
+   * within its time, and not invalidated since -- most recently used first.
+   *
+   * @param {string | null} binding
+   * @returns {[string, Held][]}
+   */
+  function claimed(binding) {
+    if (binding === null) return [];
+    const at = now();
+    return [...entries].reverse().filter(([, held]) => {
+      if (held.binding !== binding || !held.claimable) return false;
+      return held.expiresAt === null || at < held.expiresAt;
+    });
+  }
+
+  return {
+    /**
+     * The keys to list in X-Have-Once for a request made under a binding:
+     * held under it, still within their time, and not invalidated since --
+     * most recently used first. Not a once-shared value's, which its hold
+     * claims.
+     *
+     * @param {string | null} binding
+     * @returns {string[]}
+     */
+    claimable(binding) {
+      return claimed(binding)
+        .filter(([, held]) => held.hold === null)
+        .map(([key]) => key);
+    },
+
+    /**
+     * The once-shared values to claim in X-Have-Shared for a request made
+     * under a binding, as claimable() picks them: each key, with the hold
+     * the server sent it with.
+     *
+     * @param {string | null} binding
+     * @returns {{ key: string, hold: string }[]}
+     */
+    holds(binding) {
+      /** @type {{ key: string, hold: string }[]} */
+      const out = [];
+      for (const [key, held] of claimed(binding)) {
+        if (held.hold !== null) out.push({ key, hold: held.hold });
+      }
+      return out;
+    },
+
+    /**
+     * What was kept under a key for a page of this binding -- whether or not
+     * it may still be claimed -- or undefined. Reading it is using it.
+     *
+     * @param {string} key
+     * @param {string | null} binding
+     * @returns {{ content: unknown } | undefined}
+     */
+    read(key, binding) {
+      const held = entries.get(key);
+      if (held === undefined || binding === null || held.binding !== binding) return undefined;
+      entries.delete(key);
+      entries.set(key, held);
+      return { content: held.content };
+    },
+
+    /**
+     * Keeps what a page rendered from a once field, for its binding, and
+     * drops the least recently used beyond what is kept.
+     *
+     * @param {string} key
+     * @param {string | null} binding
+     * @param {unknown} content
+     * @param {number | null} ttl seconds it may be claimed for; null for as long as the session lasts
+     * @param {readonly string[]} tags
+     * @param {string | null} [hold] a once-shared value's signed hold, which claims it
+     * @returns {string[]} the keys dropped to make room
+     */
+    record(key, binding, content, ttl, tags, hold = null) {
+      if (binding === null) return [];
+      const seconds = typeof ttl === 'number' && Number.isFinite(ttl) && ttl > 0 ? ttl : null;
+      entries.delete(key);
+      entries.set(key, {
+        binding,
+        content,
+        expiresAt: seconds === null ? null : now() + seconds * 1000,
+        tags: Array.isArray(tags) ? tags.filter((tag) => typeof tag === 'string') : [],
+        claimable: true,
+        hold: typeof hold === 'string' && hold !== '' ? hold : null,
+      });
+
+      const dropped = [];
+      for (const oldest of entries.keys()) {
+        if (entries.size <= max) break;
+        entries.delete(oldest);
+        dropped.push(oldest);
+      }
+      return dropped;
+    },
+
+    /**
+     * Stops claiming every entry carrying one of these tags -- an action
+     * invalidated them -- so the next response sends each fresh.
+     *
+     * @param {readonly string[]} tags
+     * @returns {number} how many stopped
+     */
+    flushTags(tags) {
+      if (tags.length === 0) return 0;
+      let flushed = 0;
+      for (const held of entries.values()) {
+        if (held.claimable && held.tags.some((tag) => tags.includes(tag))) {
+          held.claimable = false;
+          flushed++;
+        }
+      }
+      return flushed;
+    },
+
+    /**
+     * Stops claiming the given keys, or every key.
+     *
+     * @param {readonly string[]} [keys]
+     */
+    flush(keys) {
+      for (const [key, held] of entries) {
+        if (keys === undefined || keys.includes(key)) held.claimable = false;
+      }
+    },
+
+    /**
+     * Drops everything kept under any other binding: a page for another
+     * session has been mounted, and nothing rendered for the last one may
+     * be shown to this one.
+     *
+     * @param {string | null} binding
+     */
+    keepOnly(binding) {
+      for (const [key, held] of entries) {
+        if (held.binding !== binding) entries.delete(key);
+      }
+    },
+
+    /** Drops everything: the session ended. */
+    clear() {
+      entries.clear();
+    },
+  };
+}

package/src/once.d.ts

@@ -0,0 +1,44 @@
+import type { ReactNode } from 'react';
+
+/** The key a once field is sent under, holding its once key. */
+export declare const ONCE_KEY: '$once';
+
+/** A #[Once] field the server sent whole: its value, and how long the browser may claim it. */
+export interface OnceValue<T> {
+  $once: string;
+  /** Seconds the browser may list it in X-Have-Once; null for as long as the session lasts. */
+  ttl: number | null;
+  /** Cache tags whose invalidation makes the browser stop listing it. */
+  tags: string[];
+  value: T;
+  /**
+   * False when the value is a #[Rescue] failure, or a once-shared value no
+   * hold could be minted for: shown, never kept, so the next visit asks again.
+   */
+  keep?: false;
+  /** A once-shared value's signed hold, which the browser claims it by (ADR 0065). */
+  hold?: string;
+  held?: undefined;
+}
+
+/** A #[Once] field the browser said it holds: its key alone. */
+export interface OnceHeld {
+  $once: string;
+  held: true;
+}
+
+/**
+ * What the encoder sends for a #[Once] field: its value, or -- in a response
+ * to a client that holds what it renders -- its key alone. Rendered through
+ * <Once>, which draws the value or puts back what the browser kept.
+ */
+export type OnceField<T> = OnceValue<T> | OnceHeld;
+
+export declare function isHeld<T>(field: OnceField<T>): field is OnceHeld;
+
+/**
+ * Renders a once field from its value, or -- when the browser holds what it
+ * renders -- leaves it to the browser, rendering nothing and calling none of
+ * the queries the children would. A server component.
+ */
+export declare function Once<T>(props: { field: OnceField<T>; children: (value: T) => ReactNode }): ReactNode;

package/src/once.js

@@ -0,0 +1,65 @@
+// <Once>: renders a #[Once] field, or -- when the browser already holds what
+// it renders -- nothing, which the browser fills from what it kept.
+//
+// A server component. The field crosses as `{ $once: key, value, ttl, tags }`
+// the first time and `{ $once: key, held: true }` once a request has listed
+// the key in X-Have-Once (ADR 0020). Given the value, this renders the
+// children from it inside an <OnceSlot>, which keeps the result in the
+// browser; given the marker, it renders the slot alone, and skips the
+// subtree and every query in it. No Node and no DOM: it runs in the RSC
+// environment, where <OnceSlot> is a client reference.
+
+import { createElement } from 'react';
+import { OnceSlot } from './once-slot.js';
+
+/** The key a once field is sent under, holding its once key. */
+export const ONCE_KEY = '$once';
+
+/**
+ * Whether a once field was left out because the browser holds it.
+ *
+ * @param {unknown} field
+ * @returns {boolean}
+ */
+export function isHeld(field) {
+  return isOnceField(field) && /** @type {{ held?: unknown }} */ (field).held === true;
+}
+
+/**
+ * @param {unknown} field
+ * @returns {boolean}
+ */
+function isOnceField(field) {
+  return (
+    field !== null &&
+    typeof field === 'object' &&
+    typeof (/** @type {Record<string, unknown>} */ (field)[ONCE_KEY]) === 'string'
+  );
+}
+
+/**
+ * @template T
+ * @param {{ field: import('./once.d.ts').OnceField<T>, children: (value: T) => unknown }} props
+ */
+export function Once({ field, children }) {
+  if (!isOnceField(field)) {
+    throw new TypeError('[tinvar] <Once> renders a #[Once] field; this is not one.');
+  }
+
+  if (field.held === true) return createElement(OnceSlot, { id: field.$once, held: true });
+
+  // `keep: false` is a #[Rescue] failure: shown this once, never kept, so
+  // the next visit asks for the field again rather than claim the failure.
+  // A once-shared value comes with the hold it is claimed by (ADR 0065).
+  return createElement(
+    OnceSlot,
+    {
+      id: field.$once,
+      ttl: field.ttl ?? null,
+      tags: field.tags ?? [],
+      keep: field.keep !== false,
+      hold: typeof field.hold === 'string' ? field.hold : null,
+    },
+    children(/** @type {T} */ (field.value)),
+  );
+}

package/src/optimistic.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+
+/**
+ * The state an optimistic patch applies to: the server's values, handed to
+ * this boundary by the server component that renders it. A revalidated
+ * payload renders it again with new ones. See ADR 0016.
+ */
+export declare function OptimisticState<S extends Record<string, unknown>>(props: {
+  value: S;
+  children?: ReactNode;
+}): ReactNode;
+
+/** The nearest `<OptimisticState>`'s values, with the pending optimistic patches applied. */
+export declare function useOptimisticState<S extends Record<string, unknown> = Record<string, unknown>>(): S;

package/src/optimistic.js

@@ -0,0 +1,159 @@
+'use client';
+
+// Optimistic updates: client state that shows an action's effect before the
+// server has re-rendered it.
+//
+// tinvar-spec.md, "Forms and mutations": "`moveUnit.optimistic(state =>
+// patch)`. Snapshot only the keys the patch touches, roll them back on
+// failure, keep validation errors on 422, and do not let a server response
+// overwrite a key until the last optimistic request touching it has
+// settled. The 'server response' is the revalidated RSC payload."
+//
+// Which state, in a page made of server components, is ADR 0016: the values
+// an <OptimisticState> boundary was given by the server component that
+// rendered it. Those are the server's values -- a revalidated payload
+// renders the boundary again with new ones -- and the client components
+// below read them, patched, through useOptimisticState(). A server
+// component cannot show an optimistic value: it is not rendered here.
+//
+// Per key, while any request touching it is pending, the key is HELD: the
+// value it had when the first such request began is frozen, and what shows
+// is every pending patch replayed over it, in the order the requests began.
+// So patches are functions of the state they are given, and must be pure.
+//
+//   success   the patch is folded into the frozen value, so a request still
+//             pending on the key keeps showing on top of it;
+//   failure   the patch is dropped, and the rest replayed without it -- a
+//             422's field errors stay on the form, which owns them;
+//   the last request on a key settles
+//             the key is released, and shows the server's value again --
+//             by now the revalidated one, which includes the change. An
+//             action that does not revalidate the page leaves the server's
+//             value as it was, and so does the page.
+
+import { createContext, createElement, useCallback, useContext, useMemo, useRef, useState } from 'react';
+
+const OptimisticContext = createContext(/** @type {Store | null} */ (null));
+
+/**
+ * @typedef {(state: Record<string, any>) => Record<string, unknown>} Patch
+ *
+ * @typedef {{
+ *   state: Record<string, unknown>,
+ *   begin: (patch: Patch) => number,
+ *   settle: (ticket: number, succeeded: boolean) => void,
+ * }} Store
+ */
+
+/**
+ * The state an optimistic patch applies to.
+ *
+ * @param {{ value: Record<string, unknown>, children?: unknown }} props
+ *   `value`: the server's values, from the server component that renders
+ *   this; a revalidated payload brings new ones
+ */
+export function OptimisticState({ value, children }) {
+  const base = useRef(value);
+  base.current = value;
+
+  /** The frozen value of each held key. */
+  const held = useRef(/** @type {Map<string, unknown>} */ (new Map()));
+  /** Requests still pending, in the order they began. */
+  const pending = useRef(/** @type {{ ticket: number, patch: Patch, keys: string[] }[]} */ ([]));
+  const tickets = useRef(0);
+  const [version, setVersion] = useState(0);
+
+  const view = useCallback(() => {
+    /** @type {Record<string, unknown>} */
+    const frozen = { ...base.current };
+    for (const [key, held_] of held.current) frozen[key] = held_;
+    return frozen;
+  }, []);
+
+  const displayed = useCallback(() => {
+    let state = view();
+    for (const { patch, keys } of pending.current) state = apply(state, patch, keys);
+    return state;
+  }, [view]);
+
+  const begin = useCallback(
+    (/** @type {Patch} */ patch) => {
+      const now = displayed();
+      const keys = Object.keys(patch(now) ?? {});
+
+      // Snapshot only the keys the patch touches, as they stand before any
+      // pending request touched them.
+      for (const key of keys) {
+        if (!held.current.has(key)) held.current.set(key, base.current[key]);
+      }
+
+      const ticket = ++tickets.current;
+      pending.current = [...pending.current, { ticket, patch, keys }];
+      setVersion((v) => v + 1);
+      return ticket;
+    },
+    [displayed],
+  );
+
+  const settle = useCallback(
+    (/** @type {number} */ ticket, /** @type {boolean} */ succeeded) => {
+      const request = pending.current.find((p) => p.ticket === ticket);
+      if (!request) return;
+      pending.current = pending.current.filter((p) => p !== request);
+
+      const stillTouched = new Set(pending.current.flatMap((p) => p.keys));
+      const folded = succeeded ? apply(view(), request.patch, request.keys) : null;
+
+      for (const key of request.keys) {
+        if (!stillTouched.has(key)) held.current.delete(key);
+        else if (folded !== null) held.current.set(key, folded[key]);
+      }
+      setVersion((v) => v + 1);
+    },
+    [view],
+  );
+
+  // Recomputed when the server's values change and when a request begins
+  // or settles; `version` stands for the second.
+  const state = useMemo(() => displayed(), [value, version, displayed]);
+  const store = useMemo(() => ({ state, begin, settle }), [state, begin, settle]);
+
+  return createElement(OptimisticContext.Provider, { value: store }, children);
+}
+
+/**
+ * The state of the nearest <OptimisticState>: the server's values, with the
+ * pending optimistic patches applied.
+ *
+ * @returns {Record<string, unknown>}
+ */
+export function useOptimisticState() {
+  const store = useContext(OptimisticContext);
+  if (store === null) {
+    throw new Error('[tinvar:client] useOptimisticState() needs an <OptimisticState> above it.');
+  }
+  return store.state;
+}
+
+/** @internal The store a submission patches, or null when there is none. */
+export function useOptimisticStore() {
+  return useContext(OptimisticContext);
+}
+
+/**
+ * One patch over a state, keeping only the keys it touched when it began: a
+ * patch that answers differently on replay cannot reach a key it was not
+ * snapshotted for.
+ *
+ * @param {Record<string, unknown>} state
+ * @param {Patch} patch
+ * @param {string[]} keys
+ */
+function apply(state, patch, keys) {
+  const out = patch(state) ?? {};
+  const next = { ...state };
+  for (const key of keys) {
+    if (Object.hasOwn(out, key)) next[key] = out[key];
+  }
+  return next;
+}

package/src/optional.d.ts

@@ -0,0 +1,10 @@
+/** What an #[Optional] field a request did not name is sent as. See ADR 0045. */
+export interface Unrequested {
+  /** The dot path a partial reload names the field by, to ask for it: `page.history`. */
+  readonly $optional: string;
+}
+
+export declare const OPTIONAL_KEY: '$optional';
+
+/** Whether an #[Optional] field was left for later; narrows `T | Unrequested` to either side. */
+export declare function isUnrequested(value: unknown): value is Unrequested;

package/src/optional.js

@@ -0,0 +1,31 @@
+// What an #[Optional] field nobody asked for arrives as.
+//
+// tinvar-spec.md, "Data categories": an #[Optional] field is "never on full
+// renders, only when named in `X-Only`". The encoder sends one a request
+// did not name as `{"$optional": "<dot path>"}`, and codegen types it
+// `T | Unrequested` (ADR 0045), so a component says what it shows until the
+// field is asked for. The path is the one to ask with: a partial reload
+// naming it -- `router.reload({ only: [field.$optional] })` -- re-renders
+// the field's segment with the field resolved.
+//
+// No React and no DOM: a page's server component reads its own data, so
+// this has to import cleanly in either environment.
+
+/** Mirrors Encoder::OPTIONAL_KEY. */
+export const OPTIONAL_KEY = '$optional';
+
+/**
+ * Whether an #[Optional] field was left for later rather than sent.
+ *
+ * Exactly one key, as isRescued() reads its marker: no PHP property is named
+ * with a `$`, so no Data object encodes to this, but a map field's own
+ * value could carry the key among others.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isUnrequested(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const keys = Object.keys(value);
+  return keys.length === 1 && keys[0] === OPTIONAL_KEY && typeof value[OPTIONAL_KEY] === 'string';
+}

package/src/page-root.d.ts

@@ -0,0 +1,56 @@
+import type { ReactNode } from 'react';
+import type { PartialRoute } from './compose-route';
+import type { Page } from './router';
+
+export interface PageRootOptions {
+  /**
+   * Turns a payload's RSC stream into what it holds, with the app's own
+   * client bundle: a page's elements, or for a partial reload the
+   * `{ segments }` composeRoute() rendered.
+   */
+  decode: (
+    stream: ReadableStream<Uint8Array>,
+  ) => ReactNode | PartialRoute | Promise<ReactNode | PartialRoute>;
+}
+
+/** A payload decoded and ready to go on screen. */
+export interface Prepared {
+  /**
+   * Shows the page: fresh, its page segment's components mounted again,
+   * when the visit does not preserve state. Resolves once React has
+   * committed it, or once the visit is aborted, in which case it never
+   * commits.
+   */
+  commit: () => Promise<void>;
+}
+
+export interface PageRoot {
+  /**
+   * The root to hydrate the document with; shows the page the router last
+   * committed, and hands each <Segment> what partial reloads put in it.
+   */
+  PageRoot: (props: { initial: ReactNode }) => ReactNode;
+  /**
+   * The `prepare` to give createRouter(): decodes the payload and hands back
+   * its commit, or null when the visit was aborted meanwhile. The router
+   * holds a view transition around the commit alone.
+   */
+  prepare: (stream: ReadableStream<Uint8Array>, page: Page) => Promise<Prepared | null>;
+  /**
+   * prepare() and its commit in one step, for a router given a `mount`.
+   * Resolves once React has committed the page -- or merged a partial
+   * reload's segments into it -- or once its visit is aborted, in which case
+   * it never commits.
+   */
+  mount: (stream: ReadableStream<Uint8Array>, page: Page) => Promise<void>;
+  /**
+   * The `instant` to give createRouter() (ADR 0092): shows the loading
+   * boundary the layout keyed `under` gave -- true for the layout directly
+   * above the page -- in place of what it holds, and hands back the function
+   * that takes it away. Null when no layout on screen has one by that key.
+   */
+  instant: (under: true | string) => (() => void) | null;
+}
+
+/** Creates an app's page root and the router mount that changes it. */
+export declare function createPageRoot(options: PageRootOptions): PageRoot;