@tinvar/react 0.0.0-stage → 0.4.0

package/src/segment.d.ts

@@ -0,0 +1,36 @@
+import type { Context, ReactNode } from 'react';
+import type { LayoutPropsStore } from './layout-props';
+
+export interface SegmentStore {
+  /** What partial reloads have put in each segment since the page was last loaded whole. */
+  overrides: Readonly<Record<string, ReactNode>>;
+  /** What each segment last committed. */
+  recorded: Map<string, ReactNode>;
+  /** The whole pages the root has shown. */
+  generation?: number;
+  /** By segment, the times it was committed fresh: its content is keyed by this. */
+  keys?: Readonly<Record<string, number>>;
+  /** The instant visit showing, if one is: the layout whose loading boundary stands in below it. */
+  instant?: { under: string; token: object } | null;
+  /** The layouts on screen that have a loading boundary, each naming the segment it stands in for. */
+  boundaries?: Map<string, string>;
+  /** What pages hand their layouts with setLayoutProps(). */
+  layoutProps?: LayoutPropsStore;
+}
+
+export declare const SegmentContext: Context<SegmentStore | null>;
+
+/** One route segment -- a layout or the page -- as a slot a partial reload can refill. */
+export declare function Segment(props: {
+  id: string;
+  /** The layout this segment sits in, when that layout gave a loading boundary. */
+  parent?: string;
+  /** That layout's loading boundary, shown here during an instant visit under it (ADR 0092). */
+  loading?: ReactNode;
+  children?: ReactNode;
+}): ReactNode;
+
+/** How many segments deep a component sits: 0 outside them, the most in the page. */
+export declare const SegmentDepthContext: Context<number>;
+
+export declare function useSegmentDepth(): number;

package/src/segment.js

@@ -0,0 +1,116 @@
+'use client';
+
+// One route segment -- a layout or the page -- as a slot a partial reload
+// can refill.
+//
+// ADR 0015: a partial reload re-renders only the segments it recomputes, and
+// the browser puts each into the page it already holds. Server components
+// are rendered away by the time a payload arrives, so the page on screen has
+// no layout or page left to find and replace; what it has is this client
+// component around each segment, which the server renders with the
+// segment's content as its children. A partial payload's segments go to the
+// page root, which hands them down here in place of those children.
+//
+// A layout re-rendered alone has its child segment as an empty slot -- the
+// server did not recompute it, so it has nothing to put there -- and the
+// slot shows what it last showed. Each segment records what reached the
+// screen as it commits, which is what makes that possible.
+//
+// A layout given a loading boundary (ADR 0092) hands it to the slot its
+// child sits in, rendered by the server with the rest of the page. An
+// instant visit under that layout shows it there while the next page is
+// fetched: the layout as it is on screen, drawn from data it was already
+// given, and the loading boundary in place of what is below it. The next
+// page itself is never drawn before its data arrives.
+
+import { createContext, createElement, useContext, useLayoutEffect } from 'react';
+
+/**
+ * What the page root hands every segment: the content a partial reload put
+ * in each, by segment, and what each last committed.
+ *
+ * @typedef {{
+ *   overrides: Readonly<Record<string, unknown>>,
+ *   recorded: Map<string, unknown>,
+ *   generation?: number,
+ *   keys?: Readonly<Record<string, number>>,
+ *   instant?: { under: string, token: object } | null,
+ *   boundaries?: Map<string, string>,
+ *   layoutProps?: import('./layout-props.js').LayoutPropsStore,
+ * }} SegmentStore
+ *
+ * `generation` counts the whole pages the root has shown, for what must
+ * start again on one but not on a partial reload (<MergeSlot>).
+ *
+ * `keys` counts, by segment, the times the root committed it fresh -- a
+ * visit that does not preserve state (ADR 0045). The segment's content is
+ * keyed by it, so React mounts it again instead of reconciling it with
+ * what it replaces.
+ *
+ * `instant` is the instant visit showing, if one is: the layout under which
+ * its loading boundary stands in for what the layout holds. `boundaries`
+ * is which layouts on screen have one, by the layout's key, each naming the
+ * segment its boundary stands in for; the page root reads it to tell
+ * whether an instant visit has anything to show.
+ *
+ * `layoutProps` is what pages hand their layouts with setLayoutProps().
+ */
+
+export const SegmentContext = createContext(/** @type {SegmentStore | null} */ (null));
+
+/**
+ * How many segments deep a component sits: 0 in the document outside them,
+ * 1 in the outermost layout, the most in the page. What the head tags read,
+ * so a page's <Title> wins over its layout's whatever order they render in.
+ */
+export const SegmentDepthContext = createContext(0);
+
+/** @returns {number} see SegmentDepthContext */
+export function useSegmentDepth() {
+  return useContext(SegmentDepthContext);
+}
+
+/**
+ * @param {{ id: string, parent?: string, loading?: unknown, children?: unknown }} props
+ *   `parent` and `loading`: the layout this segment sits in, and the loading
+ *   boundary it gave for an instant visit under it -- both or neither
+ */
+export function Segment({ id, parent, loading, children }) {
+  const store = useContext(SegmentContext);
+  const boundary = parent !== undefined && loading !== undefined;
+
+  // An instant visit under this segment's layout: its loading boundary,
+  // until the page arrives or the visit is given up.
+  const pending = boundary && store?.instant?.under === parent;
+
+  // Outside a page root -- the server render that makes the HTML -- a
+  // segment is exactly its children.
+  const content = pending
+    ? loading
+    : store !== null && Object.hasOwn(store.overrides, id)
+      ? store.overrides[id]
+      : children !== undefined
+        ? children
+        : (store?.recorded.get(id) ?? null);
+
+  // What reached the screen is the page's, never the stand-in: a layout
+  // re-rendered alone later puts back what was here before.
+  useLayoutEffect(() => {
+    if (!pending) store?.recorded.set(id, content);
+  });
+
+  const boundaries = store?.boundaries;
+  useLayoutEffect(() => {
+    if (!boundary || boundaries === undefined || parent === undefined) return undefined;
+    boundaries.set(parent, id);
+    return () => {
+      if (boundaries.get(parent) === id) boundaries.delete(parent);
+    };
+  }, [boundary, boundaries, parent, id]);
+
+  return createElement(
+    SegmentDepthContext.Provider,
+    { key: store?.keys?.[id] ?? 0, value: useSegmentDepth() + 1 },
+    content,
+  );
+}

package/src/server.d.ts

@@ -0,0 +1,71 @@
+/** Types for the server helpers components import. */
+
+export interface QueryClientLike {
+  /**
+   * A trailing call leaves with the next one that is not, or alone once the
+   * event loop turns. `by` names the component making the call and its
+   * owners, in development only, for the dev toolbar.
+   */
+  call(
+    name: string,
+    args: Record<string, unknown>,
+    options?: { trailing?: boolean; by?: string[] },
+  ): Promise<unknown>;
+}
+
+export interface MintClientLike {
+  mint(component: string, props: Record<string, unknown>): Promise<string>;
+}
+
+export interface RenderContext {
+  requestId: string;
+  nonce: string;
+  allowed: string[];
+  client: QueryClientLike;
+  /** Absent in a fragment render: a deferred boundary does not nest. */
+  mints?: MintClientLike;
+}
+
+export declare function runInRenderContext<T>(context: RenderContext, fn: () => T): T;
+export declare function getRenderContext(): RenderContext;
+
+/** The per-request CSP nonce PHP minted, for any inline script the app emits. */
+export declare function nonce(): string;
+export declare function requestId(): string;
+
+/**
+ * Calls a PHP #[Query] over the request's own socket.
+ *
+ * Calls made in the same microtask tick leave as one frame; identical calls
+ * collapse into one.
+ */
+export declare function query<T = unknown>(name: string, args?: Record<string, unknown>): Promise<T>;
+
+/**
+ * Every key the application shares, with its type. Empty here; `tinvar
+ * codegen` fills it in, from the PHP `#[Shared]` methods, by augmenting this
+ * module in the generated types.
+ */
+export interface SharedDataMap {}
+
+/**
+ * Reads a value every page shares: a PHP `#[Shared]` method, run once for
+ * this render the first time any component asks. Server components only.
+ */
+export declare function shared<K extends keyof SharedDataMap & string>(key: K): Promise<SharedDataMap[K]>;
+
+/**
+ * The components a <Deferred> boundary may name, as the rsc entry keeps them.
+ * Returns them frozen; the build reads the call, so each value must be a
+ * component imported from its own module, under a name written out.
+ */
+export declare function deferredRegistry<T extends Record<string, unknown>>(components: T): Readonly<T>;
+
+/**
+ * Asks PHP to sign a fragment token for one <Deferred> boundary. The renderer
+ * holds no key; see ADR 0009.
+ */
+export declare function mintFragmentToken(
+  component: string,
+  props?: Record<string, unknown>,
+): Promise<string>;

package/src/server.js

@@ -0,0 +1,242 @@
+// Server-side helpers for Tinvar components.
+//
+// This module is bundled into the `rsc` environment alongside the app's server
+// components, so the AsyncLocalStorage instance here is the same one the
+// components see. The renderer process never touches it directly; it hands the
+// query client to the rsc entry, which opens the context.
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import * as React from 'react';
+
+/** @typedef {{ requestId: string, nonce: string, allowed: string[], client: QueryClientLike, mints?: MintClientLike }} RenderContext */
+/** @typedef {{ mint(component: string, props: Record<string, unknown>): Promise<string> }} MintClientLike */
+/** @typedef {{ call(name: string, args: Record<string, unknown>, options?: { trailing?: boolean, by?: string[] }): Promise<unknown> }} QueryClientLike */
+
+const storage = new AsyncLocalStorage();
+
+/**
+ * "Each render runs in its own AsyncLocalStorage context. The renderer never
+ * caches query results across requests."
+ *
+ * @template T
+ * @param {RenderContext} context
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function runInRenderContext(context, fn) {
+  return storage.run(context, fn);
+}
+
+/** @returns {RenderContext} */
+export function getRenderContext() {
+  const context = storage.getStore();
+  if (!context) {
+    throw new Error(
+      'No Tinvar render context. A query was called outside a render, or from a client component.',
+    );
+  }
+  return context;
+}
+
+/** The per-request CSP nonce PHP minted, for any inline script the app emits. */
+export function nonce() {
+  return getRenderContext().nonce;
+}
+
+export function requestId() {
+  return getRenderContext().requestId;
+}
+
+/**
+ * Calls a PHP #[Query] over the request's own socket.
+ *
+ * Generated `@queries/*` functions wrap this. Calls made in the same microtask
+ * tick leave as one frame; identical calls collapse into one.
+ *
+ * @param {string} name
+ * @param {Record<string, unknown>} [args]
+ * @returns {Promise<unknown>}
+ */
+export function query(name, args = {}) {
+  const context = getRenderContext();
+
+  // The allowlist is enforced in PHP, which is what actually matters. Failing
+  // here too turns a silent server-side rejection into an error the component
+  // author sees during development. An empty list allows nothing, as it does
+  // in PHP: read as "no list", it let through every call PHP then refused.
+  if (!context.allowed.includes(name)) {
+    throw new Error(
+      `Query '${name}' is not on this route's allowlist. ` +
+        `Allowed here: ${context.allowed.join(', ') || '(none)'}.`,
+    );
+  }
+
+  const by = callers();
+  return by === undefined ? context.client.call(name, args) : context.client.call(name, args, { by });
+}
+
+/** What a shared key's call is named: no query's name can start with `$`. */
+const SHARED_PREFIX = '$shared.';
+
+/** A shared key is an identifier, as PHP's registry refuses any other. */
+const SHARED_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Reads a value every page shares: a PHP `#[Shared]` method, run once for
+ * this render the first time any component asks (ADR 0060).
+ *
+ * It travels as a query call does -- in the same tick's frame, answered
+ * beside the queries and held to the same budget -- under a name no query
+ * can have. It is on no allowlist: PHP answers only the keys of the page's
+ * own panel and of none, and an unknown key fails as an unknown query does.
+ * Codegen types it, through the `SharedDataMap` it declares for this module.
+ *
+ * @param {string} key
+ * @returns {Promise<unknown>}
+ */
+export function shared(key) {
+  if (typeof key !== 'string' || !SHARED_KEY.test(key)) {
+    throw new Error(`'${String(key)}' is not a shared key: a key is an identifier.`);
+  }
+
+  const by = callers();
+  return getRenderContext().client.call(
+    `${SHARED_PREFIX}${key}`,
+    {},
+    by === undefined ? { trailing: true } : { trailing: true, by },
+  );
+}
+
+/** Names kept of a call's callers: the component, and the owners above it. */
+const MAX_CALLERS = 8;
+
+/** What a component's name looks like in a stack: a capital, then an identifier. */
+const COMPONENT = /^[A-Z][A-Za-z0-9_$]*$/;
+
+/**
+ * The component making a call, then the components that rendered it, for
+ * the dev toolbar's tick panel: "tick 3: 1 query for `site`, 20 racks, from
+ * `Stats`, `Header`" (tinvar-spec.md, "Observability (dev toolbar)").
+ *
+ * React's owner stack names the owners -- the components whose render
+ * created each element on the way down -- but not the component rendering
+ * now, which is the frame that called this, found in the call's own stack:
+ * a server component's function is on it, whether it has awaited yet or not.
+ *
+ * In development only, and closed twice over: nothing in production, where
+ * React's captureOwnerStack() answers null, and nothing where NODE_ENV says
+ * production, whichever React is loaded. The names travel beside the call,
+ * which PHP reads without them (Frame::readQueryBatch()); only the toolbar's
+ * recording keeps them.
+ *
+ * @returns {string[] | undefined}
+ */
+function callers() {
+  if (process.env.NODE_ENV === 'production') return undefined;
+  const capture = /** @type {(() => string | null) | undefined} */ (
+    /** @type {Record<string, unknown>} */ (React).captureOwnerStack
+  );
+  const owners = typeof capture === 'function' ? capture() : null;
+  if (typeof owners !== 'string') return undefined;
+
+  /** @type {string[]} */
+  const names = [];
+  const own = framesOf(new Error().stack ?? '').find((name) => COMPONENT.test(name));
+  if (own !== undefined) names.push(own);
+  for (const name of framesOf(owners)) {
+    if (COMPONENT.test(name) && names.at(-1) !== name) names.push(name);
+  }
+  return names.length > 0 ? names.slice(0, MAX_CALLERS) : undefined;
+}
+
+/**
+ * The function names of a V8 stack's frames, as far as React's own frame
+ * below the components: `at async Stats (...)` is `Stats`, and
+ * `at Object.Page (...)` is `Page`.
+ *
+ * @param {string} stack
+ * @returns {string[]}
+ */
+function framesOf(stack) {
+  const names = [];
+  for (const line of stack.split('\n')) {
+    const match = /^\s*at (?:async )?([^\s(]+)/.exec(line);
+    if (match === null) continue;
+    if (match[1].includes('react_stack_bottom_frame')) break;
+    names.push(match[1].slice(match[1].lastIndexOf('.') + 1));
+  }
+  return names;
+}
+
+/**
+ * The components a <Deferred> boundary may name, as the rsc entry keeps them:
+ * a fragment renders the one its token names, from here.
+ *
+ * It returns what it is given, frozen; what it adds is that the build can
+ * read it. A fragment renders under the query allowlist of the route that
+ * minted its token, and the build makes that list from what the route's
+ * views reach -- which a component named by a string is not among. So
+ * `deferredBoundaries()` in @tinvar/renderer/vite reads each call to this:
+ * every name, and the module its component is imported from, whose queries
+ * go on the lists of the routes that may name it. Each value must be a
+ * component imported from its own module, under a name written out;
+ * anything else fails the build.
+ *
+ * @template {Record<string, unknown>} T
+ * @param {T} components
+ * @returns {Readonly<T>}
+ */
+export function deferredRegistry(components) {
+  return Object.freeze({ ...components });
+}
+
+/**
+ * Asks PHP to sign a fragment token for one <Deferred> boundary.
+ *
+ * The renderer holds no key. It knows which boundaries exist and what props
+ * they were given -- facts that exist only while this tree renders -- so it
+ * asks, and PHP chooses the route, params, panel, build, session and expiry
+ * itself. ADR 0009 records why it is this way round and what it costs.
+ *
+ * @param {string} component
+ * @param {Record<string, unknown>} [props]
+ * @returns {Promise<string>}
+ */
+export function mintFragmentToken(component, props = {}) {
+  const context = getRenderContext();
+
+  warnAboutSecretsInProps(component, props);
+
+  if (!context.mints) {
+    throw new Error(
+      `<Deferred> cannot be used here: this render was opened without the ability to mint ` +
+        `fragment tokens. A page render supports deferred boundaries; a fragment render does not ` +
+        `nest them.`,
+    );
+  }
+
+  return context.mints.mint(component, props);
+}
+
+/**
+ * Props travel base64, not encrypted, so a secret in them is public.
+ *
+ * Development only, and only for names that are unambiguous -- a false
+ * positive on a prop called `token` is cheap, and the alternative is a
+ * developer discovering it from page source.
+ */
+const SUSPICIOUS_PROP = /(secret|password|passwd|apikey|api_key|private_key|credential)/i;
+
+/** @param {string} component @param {Record<string, unknown>} props */
+function warnAboutSecretsInProps(component, props) {
+  if (process.env.NODE_ENV === 'production') return;
+
+  for (const name of Object.keys(props)) {
+    if (SUSPICIOUS_PROP.test(name)) {
+      console.warn(
+        `[tinvar] <Deferred component="${component}"> has a prop named "${name}". ` +
+          `Fragment token props are signed, NOT encrypted -- they are readable from page source.`,
+      );
+    }
+  }
+}