@tinvar/renderer 0.0.0-stage → 0.4.0

package/src/classify.js

@@ -0,0 +1,157 @@
+// What kind of failure a render threw, read from the error itself.
+//
+// tinvar-spec.md, "Operations and tooling": "Classify errors (browser API
+// used on the server, component not found, render error) with hints." The
+// classification is made here, where the error object is, and travels to
+// PHP as a code on the error frame. The hint does not: PHP keeps the text
+// for each code itself, so what a log line or the dev overlay advises is
+// the framework's own words, never something the renderer -- the side that
+// runs third-party npm code -- chose to send.
+//
+// Matched on the messages React, Node and Vite write. A message nobody
+// recognises is a plain render error, which is what it was called before
+// any of this existed.
+
+/** The codes, mirrored by Tinvar\Render\RenderFailure on PHP's side. */
+export const FAILURE = {
+  BROWSER_API: 'browser_api_on_server',
+  COMPONENT_NOT_FOUND: 'component_not_found',
+  NOT_SERIALIZABLE: 'not_serializable',
+  CLIENT_API_ON_SERVER: 'client_only_api_on_server',
+  ASYNC_CLIENT_COMPONENT: 'async_client_component',
+  QUERY_FAILED: 'query_failed',
+  RENDER_ERROR: 'render_failed',
+};
+
+/** Globals only a browser has. Read as a ReferenceError on Node, which has none of them. */
+const BROWSER_GLOBALS = new Set([
+  'window',
+  'document',
+  'navigator',
+  'location',
+  'history',
+  'localStorage',
+  'sessionStorage',
+  'indexedDB',
+  'alert',
+  'confirm',
+  'prompt',
+  'matchMedia',
+  'getComputedStyle',
+  'requestAnimationFrame',
+  'cancelAnimationFrame',
+  'requestIdleCallback',
+  'IntersectionObserver',
+  'ResizeObserver',
+  'MutationObserver',
+  'HTMLElement',
+  'Element',
+  'Node',
+  'Image',
+  'FileReader',
+  'XMLHttpRequest',
+  'self',
+]);
+
+/** Reading a property of a browser global that a module stubbed out, as `window?.x` guards do not. */
+const BROWSER_PROPERTY =
+  /^Cannot read propert(?:y|ies) of undefined \(reading '(?:addEventListener|removeEventListener|querySelector|getElementById|localStorage|sessionStorage)'\)/;
+
+const COMPONENT_NOT_FOUND = [
+  /^Unknown route '/,
+  /^Unknown deferred component '/,
+  /^Element type is invalid/,
+  /Could not find the module .* in the React (?:Client|Server) Manifest/,
+  /^Failed to load url /,
+  /^Cannot find module /,
+  /does not provide an export named/,
+];
+
+const NOT_SERIALIZABLE = [
+  /Functions cannot be passed directly to Client Components/,
+  /Event handlers cannot be passed to Client Component props/,
+  /Only plain objects(?:,| and) .* can be passed to Client Components/,
+  /Classes or other objects with methods are not supported/,
+  /Objects with toJSON methods are not supported/,
+  /Symbols cannot be passed to Client Components/,
+  /BigInt .* serialize/i,
+];
+
+/** A hook or a client-only React API called by a server component, under the react-server build. */
+const CLIENT_API = [
+  /\b(?:use(?:State|Effect|LayoutEffect|InsertionEffect|Reducer|Ref|Context|ImperativeHandle|SyncExternalStore|Transition|DeferredValue|Optimistic|ActionState|FormStatus)|createContext|Component|PureComponent)\b.* is not a function/,
+  /only works in Client Components/,
+  /is not supported in React Server Components/,
+];
+
+const ASYNC_CLIENT = [
+  /async\/await is not yet supported in Client Components/,
+  /is an async Client Component/,
+];
+
+/**
+ * @param {unknown} error
+ * @returns {string} one of FAILURE
+ */
+export function classify(error) {
+  if (error && typeof error === 'object' && error.name === 'QueryFailed') return FAILURE.QUERY_FAILED;
+
+  const message = String(error?.message ?? error ?? '');
+
+  if (error?.name === 'ReferenceError') {
+    const name = /^(\S+) is not defined$/.exec(message)?.[1];
+    if (name !== undefined && BROWSER_GLOBALS.has(name)) return FAILURE.BROWSER_API;
+  }
+  if (BROWSER_PROPERTY.test(message)) return FAILURE.BROWSER_API;
+  if (ASYNC_CLIENT.some((pattern) => pattern.test(message))) return FAILURE.ASYNC_CLIENT_COMPONENT;
+  if (NOT_SERIALIZABLE.some((pattern) => pattern.test(message))) return FAILURE.NOT_SERIALIZABLE;
+  if (CLIENT_API.some((pattern) => pattern.test(message))) return FAILURE.CLIENT_API_ON_SERVER;
+  if (COMPONENT_NOT_FOUND.some((pattern) => pattern.test(message))) return FAILURE.COMPONENT_NOT_FOUND;
+
+  return FAILURE.RENDER_ERROR;
+}
+
+/**
+ * The first frame of a stack that is the application's own code: not
+ * React, not Vite, not Node -- the line a person would open.
+ *
+ * In dev the module runner maps stacks back to the source, so this is a
+ * line of a .tsx file; from a build it is a line of the bundle, which is
+ * still where to start.
+ *
+ * @param {unknown} error
+ * @returns {{ file: string, line: number, column: number } | null}
+ */
+export function locate(error) {
+  const stack = typeof error?.stack === 'string' ? error.stack : '';
+  for (const line of stack.split('\n').slice(1)) {
+    const match = /\(?((?:file:\/\/)?\/[^():]+):(\d+):(\d+)\)?\s*$/.exec(line.trim());
+    if (!match) continue;
+    const file = match[1].replace(/^file:\/\//, '');
+    if (/\/node_modules\/|^node:|\/packages\/renderer\//.test(file)) continue;
+    return { file, line: Number(match[2]), column: Number(match[3]) };
+  }
+  return null;
+}
+
+/** The longest stack sent to PHP. A stack is for a person to read, not to fill a frame. */
+export const MAX_STACK_BYTES = 16384;
+
+/**
+ * The fields an error frame carries about its cause: the code, and where it
+ * happened. PHP shows them in the dev overlay and drops them otherwise.
+ *
+ * @param {unknown} error
+ * @returns {{ code: string, stack?: string, file?: string, line?: number }}
+ */
+export function describe(error) {
+  const out = { code: classify(error) };
+  if (typeof error?.stack === 'string' && error.stack !== '')
+    out.stack = error.stack.slice(0, MAX_STACK_BYTES);
+  const at = locate(error);
+  if (at) {
+    out.file = at.file.slice(0, 1024);
+    out.line = at.line;
+  }
+  return out;
+}

package/src/client-chunks.js

@@ -0,0 +1,54 @@
+// One chunk per client component, for @vitejs/plugin-rsc's `clientChunks`.
+//
+// tinvar-spec.md, "Operations and tooling": "Code splitting: one chunk per
+// client component; `modulepreload` for the current page's client
+// references, capped so `Link` headers never overflow server buffers."
+//
+// The plugin groups client references by the server chunk that refers to
+// them, and an app's rsc build is one server chunk -- so every 'use client'
+// module the app has went into one client chunk, and a page with one button
+// on it downloaded every page's islands. Named here by module, each
+// reference is a chunk of its own: a page's payload names the references it
+// renders, the browser loads those, and the head preloads those alone.
+// What several of them import -- React, a kit's internals, the router -- the
+// bundler still puts in shared chunks, so each module is one instance
+// however many chunks reach it.
+//
+// A dependency's modules are named the same way, one chunk each, not one per
+// package: a kit's client components are as separate as the app's, and a
+// page using its toast has no need of its tabs. Only the modules the server
+// graph renders are client references at all -- the shop's kit is six
+// modules and its icons one, not a module per icon -- and ModulePreload caps
+// the header however many a page reaches (ADR 0036).
+
+/**
+ * The chunk a client reference goes in: a name of its own, from its path
+ * relative to the Vite root -- after the last `node_modules/` for a
+ * dependency, without leading `../` for a workspace package -- with no
+ * query and no extension. Distinct modules get distinct names, so no two
+ * share a chunk; the bundler names the file from the last segment.
+ *
+ * @param {string} normalizedId the reference's id as the plugin gives it, relative to the root
+ * @returns {string}
+ */
+export function clientChunkName(normalizedId) {
+  let name = normalizedId.replaceAll('\\', '/').replace(/[?#].*$/, '');
+  const modules = name.lastIndexOf('node_modules/');
+  name = modules === -1 ? name.replace(/^(?:\.\.?\/)+/, '') : name.slice(modules + 'node_modules/'.length);
+  name = name.replace(/\.[cm]?[jt]sx?$/, '');
+  // Always a path of two parts at least. panelChunks() names a panel's
+  // chunk `panel-<name>`, one part, and the plugin puts every reference of
+  // one name in one chunk: a component at the root named panel-admin.tsx
+  // went into the admin panel's, and a customer page rendering it loaded
+  // all the admin's code.
+  return name.includes('/') ? name : `root/${name}`;
+}
+
+/**
+ * The `clientChunks` option: `rsc({ clientChunks: clientComponentChunks() })`.
+ *
+ * @returns {(meta: { id: string, normalizedId: string, serverChunk: string }) => string}
+ */
+export function clientComponentChunks() {
+  return (meta) => clientChunkName(meta.normalizedId);
+}