@tinvar/renderer 0.0.0-stage → 0.4.1

package/src/vitest.d.ts

@@ -0,0 +1,20 @@
+import type { Plugin } from 'vite';
+
+/** Where `tinvar codegen` writes the mocks and fakes, under the types directory. */
+export declare const TESTING_DIRECTORY: 'testing';
+
+/** Throws unless this is a Vitest run, outside production, and not a build. */
+export declare function assertTestRun(
+  env: Record<string, string | undefined>,
+  command: string | undefined,
+): void;
+
+/**
+ * For a Vitest config: `@queries/*` and `@actions/*` resolved to codegen's
+ * mocks, and each 'use client' module's exports marked for renderServer().
+ * Refuses a build, and any process that says production. See ADR 0061.
+ */
+export declare function tinvarTesting(options?: { types?: string }): Plugin[];
+
+/** The local names a 'use client' module exports, or null when it is not one. */
+export declare function clientExports(code: string): string[] | null;

package/src/vitest.js

@@ -0,0 +1,179 @@
+// The Vitest side of the testing layer: component tests against codegen's
+// mocks (tinvar-spec.md, "Testing", "Client components"; ADR 0061).
+//
+//   // vitest.config.ts
+//   plugins: [tinvarTesting()]
+//
+// Two things a component test needs and a build must never have:
+//
+//   - `@queries/*` and `@actions/*` resolved to the mocks `tinvar codegen`
+//     writes under resources/types/testing, which record their calls and
+//     answer with fakes of the PHP Data classes. In the build the same
+//     specifiers are the real functions (queryFunctions()) and references
+//     (the app's alias); here nothing posts and nothing reaches PHP.
+//   - Each 'use client' module's exports marked, so renderServer() in
+//     @tinvar/react/testing knows which components to call as server
+//     components and which to leave to React, as the RSC build's split on
+//     the same directive does.
+//
+// It refuses a build, a process that says production, and anything that is
+// not a Vitest run, before it does either.
+
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseAst } from 'vite';
+import { PRODUCTION_MARKERS } from './dev-guard.js';
+
+/** Where `tinvar codegen` writes the mocks and fakes, under the types directory. */
+export const TESTING_DIRECTORY = 'testing';
+
+/** `@queries` and `@queries/a/b`: a codegen module, by its path segments. */
+const QUERIES_MODULE = /^@queries((?:\/[A-Za-z0-9_-]+)*)$/;
+
+/** `@actions/RackActions`: one module per class with actions. */
+const ACTIONS_MODULE = /^@actions\/([A-Za-z_$][A-Za-z0-9_$]*)$/;
+
+/** Anything under either prefix, so a specifier that is neither of those shapes is refused, not passed on. */
+const MOCKED_PREFIX = /^@(?:queries|actions)(?:\/|$)/;
+
+const SOURCE = /\.(?:[cm]?[jt]sx?)(?:\?.*)?$/;
+
+const TESTING_SPECIFIER = '@tinvar/react/testing';
+
+/**
+ * Throws unless this is a Vitest run, outside production.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @param {string | undefined} command
+ */
+export function assertTestRun(env, command) {
+  if (command === 'build') {
+    throw new Error(
+      '[tinvar] tinvarTesting() is in a build. It belongs in a Vitest config, never a Vite build.',
+    );
+  }
+  for (const name of PRODUCTION_MARKERS) {
+    if (
+      String(env[name] ?? '')
+        .trim()
+        .toLowerCase() === 'production'
+    ) {
+      throw new Error(
+        `[tinvar] tinvarTesting() is refused: ${name}=production. It puts mocks where queries and actions are.`,
+      );
+    }
+  }
+  if (!env.VITEST) {
+    throw new Error('[tinvar] tinvarTesting() runs only under Vitest, and VITEST is not set.');
+  }
+}
+
+/**
+ * @param {{ types?: string }} [options] `types` is where `tinvar codegen`
+ *        writes, relative to the Vite root
+ * @returns {import('vite').Plugin[]}
+ */
+export function tinvarTesting({ types = 'resources/types' } = {}) {
+  let root = process.cwd();
+
+  /** @param {string} relative */
+  const mock = (relative) => resolve(root, types, TESTING_DIRECTORY, relative);
+
+  return [
+    {
+      name: 'tinvar:testing-mocks',
+      enforce: 'pre',
+      config(_config, env) {
+        assertTestRun(process.env, env.command);
+      },
+      configResolved(config) {
+        root = config.root;
+      },
+      resolveId(source, importer) {
+        if (!MOCKED_PREFIX.test(source)) return null;
+        const query = QUERIES_MODULE.exec(source);
+        const action = ACTIONS_MODULE.exec(source);
+        const file =
+          query !== null
+            ? mock(query[1] === '' ? 'queries.ts' : `queries${query[1]}.ts`)
+            : action !== null
+              ? mock(`actions/${action[1]}.ts`)
+              : null;
+        const from = importer ? ` (imported by ${importer})` : '';
+        if (file === null) {
+          this.error(`[tinvar] ${source}${from} is not a module tinvar codegen writes.`);
+        }
+        if (!existsSync(file)) {
+          this.error(`[tinvar] ${source}${from} has no mock: tinvar codegen writes one to ${file}; run it.`);
+        }
+        return file;
+      },
+    },
+    {
+      // After TypeScript and JSX are compiled away, so the module parses as
+      // JavaScript; and on every module Vitest transforms, an inlined
+      // dependency's included.
+      name: 'tinvar:testing-client-components',
+      transform(code, id) {
+        if (!SOURCE.test(id) || !code.includes('use client')) return null;
+        const names = clientExports(code);
+        if (names === null || names.length === 0) return null;
+        return {
+          code:
+            `${code}\n;import { markClient as __tinvarMarkClient } from ${JSON.stringify(TESTING_SPECIFIER)};\n` +
+            `__tinvarMarkClient(${names.join(', ')});\n`,
+          map: null,
+        };
+      },
+    },
+  ];
+}
+
+/**
+ * The local names a 'use client' module exports, or null when it is not
+ * one. A directive is only in the prologue: the string anywhere else is not
+ * one. An anonymous default export has no name to mark, and is left out --
+ * renderServer() would call it as a server component, and says so if it
+ * then calls a hook.
+ *
+ * @param {string} code
+ * @returns {string[] | null}
+ */
+export function clientExports(code) {
+  const program = /** @type {any} */ (parseAst(code));
+  let client = false;
+  for (const statement of program.body) {
+    if (statement.type !== 'ExpressionStatement' || typeof statement.directive !== 'string') break;
+    if (statement.directive === 'use client') client = true;
+  }
+  if (!client) return null;
+
+  /** @type {Set<string>} */
+  const names = new Set();
+  for (const statement of program.body) {
+    if (statement.type === 'ExportNamedDeclaration' && statement.source == null) {
+      const declaration = statement.declaration;
+      if (declaration?.type === 'FunctionDeclaration' || declaration?.type === 'ClassDeclaration') {
+        if (declaration.id) names.add(declaration.id.name);
+      } else if (declaration?.type === 'VariableDeclaration') {
+        for (const declarator of declaration.declarations) {
+          if (declarator.id.type === 'Identifier') names.add(declarator.id.name);
+        }
+      }
+      for (const specifier of statement.specifiers ?? []) {
+        if (specifier.local?.type === 'Identifier') names.add(specifier.local.name);
+      }
+    } else if (statement.type === 'ExportDefaultDeclaration') {
+      const declaration = statement.declaration;
+      if (
+        (declaration.type === 'FunctionDeclaration' || declaration.type === 'ClassDeclaration') &&
+        declaration.id
+      ) {
+        names.add(declaration.id.name);
+      } else if (declaration.type === 'Identifier') {
+        names.add(declaration.name);
+      }
+    }
+  }
+  return [...names];
+}

package/src/warm.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Loads every client component's module through the RSC plugin's ssr
+ * loader before the first render, marking each load settled, so the first
+ * page's head preloads every module a later one's would.
+ */
+export declare function warmClientReferences(
+  references: Record<string, unknown> | null | undefined,
+  loader?: unknown,
+): Promise<{ loaded: number; failed: string[] }>;

package/src/warm.js

@@ -0,0 +1,60 @@
+// Every client component's module loaded before the first render, so the
+// first page preloads what the hundredth does.
+//
+// The ssr environment loads a client component's module the first time a
+// payload names it. The RSC plugin hints its chunks for preloading as the
+// module is reached, and React keeps a hint only while it is rendering: the
+// first time, the module's load settles while the payload is still being
+// decoded, the component is reached then, outside React's render, and the
+// hint is dropped. That page's head named fewer modules than every page
+// after it -- in the browser, a chunk fetched as the payload named it, and a
+// shorter Link header. Once a module has loaded, and the decoder has seen
+// it settle, the component is reached as React renders it, and the hint is
+// kept.
+//
+// So the renderer loads every one before it says it is ready, through the
+// same loader the decoder asks -- the plugin's, which memoizes each load --
+// and marks each load settled the way React's decoder does, on the promise
+// itself, so the first payload finds them all already there.
+//
+// The ssr entry calls it with the plugin's own map of the client references
+// (`virtual:vite-rsc/client-references`, a module only an app's own build
+// can import), and the rsc entry hands it to the renderer as `warm()`,
+// which the renderer awaits before it listens. A module that does not load
+// is not the start's to fail: it is the page's, which fails as it did.
+
+/** The loader the RSC plugin's ssr runtime installs for client references. */
+const LOADER = '__vite_rsc_client_require__';
+
+/**
+ * @param {Record<string, unknown> | null | undefined} references the plugin's
+ *        map of client references, by id
+ * @param {unknown} [loader] the plugin's loader; the global one by default
+ * @returns {Promise<{ loaded: number, failed: string[] }>}
+ */
+export async function warmClientReferences(references, loader = /** @type {any} */ (globalThis)[LOADER]) {
+  if (typeof loader !== 'function' || references === null || typeof references !== 'object') {
+    return { loaded: 0, failed: [] };
+  }
+
+  const ids = Object.keys(references);
+  const failed = [];
+  await Promise.all(
+    ids.map(async (id) => {
+      try {
+        const loading = loader(id);
+        const value = await loading;
+        // As React's decoder marks a module load it has seen settle: it then
+        // reads the module where it is rendering, instead of waiting for it.
+        if (loading !== null && typeof loading === 'object' && typeof loading.then === 'function') {
+          loading.status = 'fulfilled';
+          loading.value = value;
+        }
+      } catch {
+        failed.push(id);
+      }
+    }),
+  );
+
+  return { loaded: ids.length - failed.length, failed: failed.sort() };
+}

package/src/workbench.d.ts

@@ -0,0 +1,146 @@
+import type { IncomingMessage } from 'node:http';
+import type { ReactNode } from 'react';
+import type { Plugin } from 'vite';
+
+/**
+ * How a sample answers a query, or a shared read (`$shared.<key>`): a value,
+ * or a function of the call's arguments.
+ */
+export type QueryAnswers = Record<string, unknown | ((args: Record<string, unknown>) => unknown)>;
+
+/** One way of drawing a page: its loaders' data, the route's parameters, and the queries its components call. */
+export interface PageSample {
+  /** What the page's loader returns, as the encoder would send it. */
+  page: unknown;
+  /** Each layout's loader data, by the layout's key. */
+  layouts?: Record<string, unknown>;
+  params?: Record<string, string>;
+  queries?: QueryAnswers;
+}
+
+/** One way of drawing a component: its props, and the queries it calls. */
+export interface ComponentSample {
+  props: Record<string, unknown>;
+  queries?: QueryAnswers;
+}
+
+export interface WorkbenchPage {
+  /** The view the page renders, as the rsc entry's route table names it. */
+  route: string;
+  samples: Record<string, PageSample>;
+  /** Answers every sample shares; a sample's own win. */
+  queries?: QueryAnswers;
+}
+
+export interface WorkbenchComponent<P = Record<string, unknown>> {
+  /** The component drawn with a sample's props. */
+  render: (props: P) => ReactNode;
+  samples: Record<string, ComponentSample>;
+  queries?: QueryAnswers;
+}
+
+/** What a frame of the workbench carries: a render's id, its nonce, and the queries it may call. */
+export interface WorkbenchFrame {
+  rid: string;
+  nonce: string;
+  allow: string[];
+}
+
+export interface WorkbenchPageFrame extends WorkbenchFrame {
+  route: string;
+  params: Record<string, string>;
+  data: { page: unknown; layouts: Record<string, unknown> };
+}
+
+export interface WorkbenchQueryClient {
+  call(name: string, args: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
+}
+
+export interface WorkbenchMintClient {
+  mint(component: string, props: Record<string, unknown>): Promise<string>;
+}
+
+/**
+ * The app's workbench module's default export, loaded in the rsc environment
+ * by the dev server alone. Its renders answer RSC streams.
+ */
+export interface Workbench {
+  pages?: Record<string, WorkbenchPage>;
+  components?: Record<string, WorkbenchComponent<never>>;
+  renderPage(
+    frame: WorkbenchPageFrame,
+    client: WorkbenchQueryClient,
+    mints: WorkbenchMintClient,
+  ): Promise<ReadableStream<Uint8Array>>;
+  renderElement(
+    element: ReactNode,
+    frame: WorkbenchFrame,
+    client: WorkbenchQueryClient,
+    mints: WorkbenchMintClient,
+  ): Promise<ReadableStream<Uint8Array>>;
+}
+
+/** The app's module in the ssr environment that turns a render's RSC stream into its whole HTML. */
+export interface WorkbenchSsr {
+  prerenderHtml(rscStream: ReadableStream<Uint8Array>): Promise<ReadableStream<Uint8Array>>;
+}
+
+export interface WorkbenchOptions {
+  /** The app's workbench module. */
+  module: string;
+  /** The app's module whose `prerenderHtml()` draws the HTML (WorkbenchSsr). */
+  ssr: string;
+  /** The Vite environment the workbench module is loaded in; `rsc` unless given. */
+  environment?: string;
+  /** And the one the ssr module is; `ssr` unless given. */
+  ssrEnvironment?: string;
+  /** Where the pages are served under the dev server's base; `__workbench` unless given. */
+  workbench?: string;
+  /** Where the components are; `__playground` unless given. */
+  playground?: string;
+  /** Styles the app's tooling injects with a script in dev, for the frame, which runs none. */
+  css?: () => string | Promise<string>;
+  /**
+   * The app's client module for a frame drawn with its client script: it reads the payload from
+   * the data block `PAYLOAD_ID` names and hydrates the document. Without one, frames run no script.
+   */
+  client?: string;
+}
+
+export declare const NON_PRODUCTION: readonly string[];
+export declare const MAX_PROPS_BYTES: number;
+export declare class WorkbenchRefused extends Error {}
+
+/** Throws where anything says production; why it is not mounted, or null where it is. */
+export declare function workbenchRefusal(env?: Record<string, string | undefined>): string | null;
+
+/** From this machine, naming this machine, through any proxy of this machine's. */
+export declare function fromThisMachine(req: IncomingMessage): boolean;
+
+/** HTML for a frame that runs no script, with `css` in its head. */
+export declare function forTheFrame(html: string, css?: string): string;
+
+/** The id of the data block holding a scripted frame's payload rows. */
+export declare const PAYLOAD_ID: string;
+
+/** Whether a request is one a scripted frame made of the dev server's modules: allowed `Origin: null`. */
+export declare function forScriptedFrame(req: IncomingMessage, base: string): boolean;
+
+/** HTML for a frame that runs the app's client module under `nonce`, its payload in a data block. */
+export declare function scriptedFrame(
+  html: string,
+  css: string,
+  rows: unknown[],
+  nonce: string,
+  client: string,
+  refresh: string | null,
+): string;
+
+/** An RSC payload as inline payload rows: text, or `{ $b64 }` where it is not UTF-8. */
+export declare function payloadRows(bytes: Uint8Array): unknown[];
+
+/** A query client answering from a sample alone. */
+export declare function sampleQueries(answers: QueryAnswers): WorkbenchQueryClient;
+
+/** The dev server's workbench and playground; no part of a build, and refused outside a developer's machine. */
+export declare function workbench(options: WorkbenchOptions): Plugin;