@tinvar/react 0.0.0-stage → 0.4.0

package/src/testing.js

@@ -0,0 +1,634 @@
+// The JavaScript half of the testing layer: what codegen's mocks of
+// `@queries/*` and `@actions/*` are built on, and the harness server
+// components render in (tinvar-spec.md, "Testing", "Client components").
+//
+//   "Vitest plus React Testing Library on the JavaScript side. Codegen emits:
+//    typed fakes from Data objects (`fakeRackData({ name: 'R-14' })`); mock
+//    versions of `@queries/*` and `@actions/*`, with call recording. Server
+//    components render in the same harness against those mocks."
+//
+// The fakes are plain functions codegen writes beside the types; nothing of
+// them is here. What is here is the mocks' state -- the calls each one was
+// made with, and what it answers -- and renderServer(), which awaits a tree
+// of server components into one React Testing Library can render.
+//
+// This module never runs anywhere but a Vitest worker. It refuses to load
+// outside one, and in any process that says production, before anything of
+// it is defined; and `queryFunctions()` in @tinvar/renderer/vite fails a
+// Vite build whose graph reaches it. A mock that answered in production
+// would be an action that does nothing and says it succeeded (ADR 0061).
+
+import { cloneElement, isValidElement } from 'react';
+import { ActionError } from './action.js';
+import { runInRenderContext } from './server.js';
+
+/** Found by `queryFunctions()`, which fails any Vite build whose graph holds it. */
+export const TESTING_RUNTIME = 'tinvar:testing-runtime';
+
+/** The variables any of which, saying `production`, refuse this module. Mirrors Tinvar\Support\DevMode. */
+const PRODUCTION_MARKERS = ['NODE_ENV', 'TINVAR_ENV', 'APP_ENV'];
+
+refuseOutsideTests(globalThis.process?.env);
+
+/**
+ * Throws unless this is a Vitest worker in a process that is not production.
+ * Exported for its own test; it has already run by the time anything can
+ * import it.
+ *
+ * Vitest sets VITEST in every worker it starts. A browser has no `process`
+ * at all, so a bundle that somehow carried this module stops here too.
+ *
+ * @param {Record<string, string | undefined> | undefined} env
+ */
+export function refuseOutsideTests(env) {
+  if (env === undefined || env === null || typeof env !== 'object') {
+    throw new Error(
+      '[tinvar] @tinvar/react/testing loaded where there is no process: it runs only in a Vitest worker.',
+    );
+  }
+  for (const name of PRODUCTION_MARKERS) {
+    if (
+      String(env[name] ?? '')
+        .trim()
+        .toLowerCase() === 'production'
+    ) {
+      throw new Error(
+        `[tinvar] @tinvar/react/testing is refused: ${name}=production. Its mocks answer for queries and ` +
+          'actions without running them, so it never loads in production.',
+      );
+    }
+  }
+  if (!env.VITEST) {
+    throw new Error('[tinvar] @tinvar/react/testing runs only in a Vitest worker, and VITEST is not set.');
+  }
+}
+
+/** Marks an action reference; the same symbol action.js marks real ones with. */
+const REFERENCE = Symbol.for('tinvar.action');
+
+/** Where a mock keeps its entry. */
+const MOCK = Symbol('tinvar.mock');
+
+const ACTION_PREFIX = '/_action/';
+const QUERY_PREFIX = '/_query/';
+
+/**
+ * @typedef {{
+ *   kind: 'query' | 'action',
+ *   name: string,
+ *   calls: unknown[],
+ *   fallback: () => unknown,
+ *   answer: { type: 'value', value: unknown } | { type: 'refuse', status: number, errors: Record<string, string[]> } | null,
+ * }} Entry
+ */
+
+/**
+ * Every mock this worker has made, by kind and wire name: an action is
+ * reached by name from a <Form>'s fetch as well as by its reference.
+ *
+ * @type {Map<string, Entry>}
+ */
+const entries = new Map();
+
+/**
+ * @param {'query' | 'action'} kind
+ * @param {string} name
+ * @param {() => unknown} fallback
+ * @returns {Entry}
+ */
+function register(kind, name, fallback) {
+  if (typeof name !== 'string' || name === '') {
+    throw new TypeError(`[tinvar] A mocked ${kind} needs its wire name.`);
+  }
+  if (typeof fallback !== 'function') {
+    throw new TypeError(
+      `[tinvar] The mocked ${kind} ${name} needs a function that makes its default answer.`,
+    );
+  }
+  // A module evaluated again -- vi.resetModules() -- makes its mocks again;
+  // they keep the calls and answers a test gave the first ones.
+  const key = `${kind}:${name}`;
+  const existing = entries.get(key);
+  if (existing) {
+    existing.fallback = fallback;
+    return existing;
+  }
+  /** @type {Entry} */
+  const entry = { kind, name, calls: [], fallback, answer: null };
+  entries.set(key, entry);
+  return entry;
+}
+
+/**
+ * What a mock answers for one call: what the test gave it, or else a fresh
+ * default from its fake.
+ *
+ * @param {Entry} entry
+ * @param {unknown} args
+ */
+function answerFor(entry, args) {
+  const answer = entry.answer;
+  if (answer === null) return entry.fallback();
+  if (answer.type === 'value') {
+    return typeof answer.value === 'function' ? answer.value(args) : answer.value;
+  }
+  if (entry.kind === 'action') {
+    throw new ActionError(entry.name, refusalOutcome(answer.status, answer.errors));
+  }
+  throw new Error(`[tinvar] The query ${entry.name} was refused (${answer.status}), as the test asked.`);
+}
+
+/**
+ * The outcome transport.js classifies a refusal as, for an ActionError.
+ *
+ * @param {number} status
+ * @param {Record<string, string[]>} errors
+ */
+function refusalOutcome(status, errors) {
+  const headers = new Headers();
+  return status === 422
+    ? { type: 'validation', status: 422, errors, body: { errors }, headers }
+    : { type: 'http', status, body: null, headers, code: null, reference: null, retryAfter: null };
+}
+
+/**
+ * A stand-in for one `@queries/*` function: called as the real one is, it
+ * records its arguments and resolves with what the test said, or a fake.
+ * What codegen's mock query modules are made of.
+ *
+ * @param {string} name the query's wire name
+ * @param {() => unknown} fallback
+ */
+export function mockQuery(name, fallback) {
+  const entry = register('query', name, fallback);
+  /** @param {Record<string, unknown>} [args] */
+  const call = async (args = {}) => {
+    entry.calls.push(args);
+    return answerFor(entry, args);
+  };
+  Object.defineProperties(call, {
+    query: { value: name, enumerable: true },
+    [MOCK]: { value: entry },
+  });
+  return Object.freeze(call);
+}
+
+/**
+ * A stand-in for one `@actions/*` reference. It is a reference -- <Form>,
+ * useForm and useHttp take it, `.optimistic()` works -- and called directly
+ * it records its arguments and resolves with what the test said, or an
+ * empty ActionResult. A post a <Form> makes reaches it through
+ * actionFetch(), which a test installs as fetch.
+ *
+ * @param {string} name the action's wire name
+ * @param {() => unknown} fallback
+ */
+export function mockAction(name, fallback) {
+  return actionReference(register('action', name, fallback), null);
+}
+
+/**
+ * @param {Entry} entry
+ * @param {((state: Record<string, any>) => Record<string, unknown>) | null} patch
+ */
+function actionReference(entry, patch) {
+  /** @param {Record<string, unknown>} [args] */
+  const call = async (args = {}) => {
+    entry.calls.push(args);
+    return answerFor(entry, args);
+  };
+  Object.defineProperties(call, {
+    action: { value: entry.name, enumerable: true },
+    url: { value: ACTION_PREFIX + encodeURIComponent(entry.name), enumerable: true },
+    optimisticPatch: { value: patch },
+    [REFERENCE]: { value: true },
+    [MOCK]: { value: entry },
+    optimistic: {
+      /** @param {(state: Record<string, any>) => Record<string, unknown>} next */
+      value: (next) => {
+        if (typeof next !== 'function') {
+          throw new TypeError('[tinvar] optimistic() takes a function from the current state to a patch.');
+        }
+        return actionReference(entry, next);
+      },
+    },
+  });
+  return Object.freeze(call);
+}
+
+/** @param {unknown} mock @returns {Entry} */
+function entryOf(mock) {
+  const entry = mock !== null && typeof mock === 'function' ? /** @type {any} */ (mock)[MOCK] : undefined;
+  if (entry === undefined) {
+    throw new TypeError(
+      '[tinvar] That is not a mocked query or action. Import it from @queries/* or @actions/* in a test ' +
+        'run with tinvarTesting(), which puts the mocks codegen wrote in their place.',
+    );
+  }
+  return entry;
+}
+
+/**
+ * The arguments each call to a mock was made with, oldest first: a direct
+ * call's as given, a <Form>'s as it posted them.
+ *
+ * @param {unknown} mock
+ * @returns {unknown[]}
+ */
+export function calls(mock) {
+  return [...entryOf(mock).calls];
+}
+
+/**
+ * What a mock answers from now on, until resetMocks(): a value, or a
+ * function of the call's arguments. A promise that never settles keeps a
+ * server component suspended; a function that throws fails the call.
+ *
+ * @param {unknown} mock
+ * @param {unknown} value
+ */
+export function answer(mock, value) {
+  entryOf(mock).answer = { type: 'value', value };
+}
+
+/**
+ * Has a mock refuse from now on: an action rejects with the ActionError the
+ * endpoint's answer would give -- field errors with 422 -- and a <Form>
+ * posting to it gets that status; a query rejects.
+ *
+ * @param {unknown} mock
+ * @param {{ status?: number, errors?: Record<string, string[]> }} [refusal]
+ */
+export function refuse(mock, { status = 422, errors = {} } = {}) {
+  if (!Number.isInteger(status) || status < 400 || status > 599) {
+    throw new RangeError(`[tinvar] A refusal is a 4xx or 5xx status, not ${status}.`);
+  }
+  entryOf(mock).answer = { type: 'refuse', status, errors };
+}
+
+/**
+ * A fake's defaults under a test's overrides, at any depth: a plain object
+ * given for a field that holds one is laid over that field's own defaults,
+ * so `fakeOrderData({ customer: { name: 'Ada' } })` keeps the customer's
+ * other fields. Anything else given -- a list, null, a string -- takes the
+ * field's place whole, and a field given as `undefined` keeps its default.
+ * What codegen's fakes return; neither argument is changed.
+ *
+ * The keys an object can be given its prototype by (`__proto__`,
+ * `constructor`, `prototype`) are refused, not copied: a fake is built from
+ * what a test wrote, and a merge that let one through would change every
+ * object in the worker.
+ *
+ * @template T
+ * @param {T} base
+ * @param {unknown} overrides
+ * @returns {T}
+ */
+export function withOverrides(base, overrides) {
+  return /** @type {T} */ (layered(base, overrides, 'overrides'));
+}
+
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isPlainObject(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/** @param {unknown} base @param {unknown} over @param {string} where @returns {unknown} */
+function layered(base, over, where) {
+  if (over === undefined) return base;
+  if (!isPlainObject(over) || !isPlainObject(base)) return over;
+  /** @type {Record<string, unknown>} */
+  const out = { ...base };
+  for (const key of Object.keys(over)) {
+    if (UNSAFE_KEYS.has(key)) {
+      throw new TypeError(
+        `[tinvar] ${where} names \`${key}\`, which no fake has: it would change the prototype.`,
+      );
+    }
+    out[key] = layered(base[key], over[key], `${where}.${key}`);
+  }
+  return out;
+}
+
+/** Forgets every call and answer, so each test starts from the fakes. */
+export function resetMocks() {
+  for (const entry of entries.values()) {
+    entry.calls = [];
+    entry.answer = null;
+  }
+}
+
+/**
+ * A fetch for component tests: a post to `/_action/{name}` answered by that
+ * action's mock, and one to `/_query/{name}` -- what useHttp() sends -- by
+ * that query's mock, each recorded and then answered as its endpoint would;
+ * anything else refused with a 404, never sent. Install it with
+ * `vi.stubGlobal('fetch', actionFetch)`.
+ *
+ * A query's call is recorded with the arguments it was sent under `args`,
+ * as a direct call's are, and answered `{ value }`; a refusal the test
+ * asked for is its status, with the field errors at 422.
+ *
+ * @param {RequestInfo | URL} input
+ * @param {RequestInit} [init]
+ * @returns {Promise<Response>}
+ */
+export async function actionFetch(input, init = {}) {
+  // The page's own origin only, as the endpoint is: a post elsewhere is not
+  // one of the application's actions, whatever its path says.
+  const here = new URL(globalThis.location?.href ?? 'http://localhost/');
+  const request = input instanceof Request ? input : null;
+  const url = new URL(request?.url ?? String(input), here);
+  const method = (init.method ?? request?.method ?? 'GET').toUpperCase();
+  const ours = url.origin === here.origin;
+  const kind =
+    ours && url.pathname.startsWith(ACTION_PREFIX)
+      ? 'action'
+      : ours && url.pathname.startsWith(QUERY_PREFIX)
+        ? 'query'
+        : null;
+  const name =
+    kind === null
+      ? null
+      : actionOf(url.pathname.slice((kind === 'action' ? ACTION_PREFIX : QUERY_PREFIX).length));
+  const entry = name === null ? undefined : entries.get(`${kind}:${name}`);
+  if (entry === undefined || method !== 'POST') {
+    return json(404, {
+      error: {
+        code: 'not_mocked',
+        message: `No mocked ${kind ?? 'action'} answers ${method} ${url.pathname}.`,
+      },
+    });
+  }
+
+  const sent = await bodyOf(init.body ?? (request === null ? null : await request.text()));
+  if (entry.kind === 'query') return queryAnswer(entry, sent);
+
+  const args = sent;
+  entry.calls.push(args);
+  try {
+    const body = await answerFor(entry, args);
+    return json(200, body ?? { value: null, flash: {}, revalidated: [], payloads: {} });
+  } catch (error) {
+    if (error instanceof ActionError) {
+      return json(error.status, error.kind === 'validation' ? { errors: error.errors } : null);
+    }
+    throw error;
+  }
+}
+
+/**
+ * A query's answer over the wire: `{ value }`, or the refusal the test asked
+ * for. Its arguments are what useHttp() sends under `args`; a body without
+ * them is refused with the 422 the endpoint gives, and not recorded.
+ *
+ * @param {Entry} entry
+ * @param {unknown} sent
+ */
+async function queryAnswer(entry, sent) {
+  const args = isPlainObject(sent) ? (sent.args ?? {}) : null;
+  if (!isPlainObject(args)) {
+    return json(422, { errors: { args: ['The arguments are an object under `args`.'] } });
+  }
+  entry.calls.push(args);
+  const answer = entry.answer;
+  if (answer?.type === 'refuse') {
+    return json(answer.status, answer.status === 422 ? { errors: answer.errors } : null);
+  }
+  return json(200, { value: (await answerFor(entry, args)) ?? null });
+}
+
+/** An action's name from its path segment, or null for one that does not decode. @param {string} segment */
+function actionOf(segment) {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return null;
+  }
+}
+
+/** @param {BodyInit | null | undefined} body */
+async function bodyOf(body) {
+  if (typeof body === 'string') {
+    try {
+      return JSON.parse(body);
+    } catch {
+      return body;
+    }
+  }
+  if (body instanceof FormData) {
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const [key, value] of body.entries()) out[key] = value;
+    return out;
+  }
+  return {};
+}
+
+/** @param {number} status @param {unknown} body */
+function json(status, body) {
+  return new Response(body === null ? '' : JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Server components
+
+/** Where 'use client' functions are kept: one set however often this module is loaded. */
+const CLIENT = Symbol.for('tinvar.testing.client');
+/** @type {WeakSet<Function>} */
+const clientComponents = /** @type {any} */ (globalThis)[CLIENT] ?? new WeakSet();
+/** @type {any} */ (globalThis)[CLIENT] = clientComponents;
+
+/**
+ * Marks the exports of a 'use client' module as client components, which
+ * renderServer() leaves for React to render. `tinvarTesting()` adds the call
+ * to each such module; a test has no need of it.
+ *
+ * @param {...unknown} exports
+ */
+export function markClient(...exports) {
+  for (const value of exports) {
+    if (typeof value === 'function') clientComponents.add(value);
+  }
+}
+
+/** @param {unknown} type */
+export function isClientComponent(type) {
+  return typeof type === 'function' && clientComponents.has(type);
+}
+
+/**
+ * Renders the server components of a tree, as the renderer's rsc
+ * environment does, and hands back what is left: host elements and client
+ * components, with every server component's output in its place, for React
+ * Testing Library's render().
+ *
+ * A server component is any function component not exported from a
+ * 'use client' module. It is called with its props and awaited, inside a
+ * render context whose `shared()` answers from `options.shared` -- a key not
+ * given fails, as a key PHP does not share does -- and whose query()
+ * answers from the mocks. Suspense boundaries are waited out, so what comes
+ * back is the tree as it finally streams; a query the test answered with a
+ * promise that never settles never comes back.
+ *
+ * The props a server component gives a client component or an element are
+ * held to what Flight can send: a function there that is not an action
+ * reference fails the render, as it would in the real one.
+ *
+ * @param {import('react').ReactNode} node
+ * @param {{ shared?: Record<string, unknown> }} [options]
+ * @returns {Promise<import('react').ReactNode>}
+ */
+export function renderServer(node, { shared = {} } = {}) {
+  const context = {
+    requestId: 'test',
+    nonce: 'test-nonce',
+    get allowed() {
+      return [...entries.values()].filter((e) => e.kind === 'query').map((e) => e.name);
+    },
+    client: {
+      /** @param {string} name @param {Record<string, unknown>} args */
+      call: async (name, args = {}) => {
+        if (name.startsWith('$shared.')) {
+          const key = name.slice('$shared.'.length);
+          if (!Object.hasOwn(shared, key)) {
+            throw new Error(
+              `[tinvar] A component read shared('${key}'), and renderServer() was given no value for it. ` +
+                `Pass { shared: { ${key}: ... } }.`,
+            );
+          }
+          return shared[key];
+        }
+        const entry = entries.get(`query:${name}`);
+        if (entry === undefined) throw new Error(`[tinvar] No mocked query is named ${name}.`);
+        entry.calls.push(args);
+        return answerFor(entry, args);
+      },
+    },
+    mints: {
+      /** @param {string} component */
+      mint: async (component) => `test-fragment-token:${component}`,
+    },
+  };
+
+  return runInRenderContext(context, () => resolve(node));
+}
+
+/**
+ * @param {unknown} node
+ * @returns {Promise<any>}
+ */
+async function resolve(node) {
+  if (Array.isArray(node)) return Promise.all(node.map((child) => resolve(child)));
+  if (isThenable(node)) return resolve(await node);
+  if (!isValidElement(node)) return node;
+
+  const element = /** @type {import('react').ReactElement<Record<string, unknown>>} */ (node);
+  const type = element.type;
+
+  if (typeof type === 'function' && !isClientComponent(type) && !type.prototype?.isReactComponent) {
+    let output;
+    try {
+      output = type(element.props);
+    } catch (error) {
+      throw explainHooks(error, type);
+    }
+    return resolve(await output);
+  }
+
+  // A host element, a fragment, Suspense, a provider, or a client
+  // component: rendered by React. What it was handed may hold server
+  // components still -- children, a fallback -- so those are rendered.
+  // Everything here came out of a server component, so a host element's
+  // props and a client component's are what Flight would have to send.
+  const sent = typeof type === 'string' ? `<${type}>` : isClientComponent(type) ? `<${nameOf(type)}>` : null;
+  /** @type {Record<string, unknown>} */
+  const props = {};
+  let changed = false;
+  for (const [key, value] of Object.entries(element.props)) {
+    if (sent !== null) assertSendable(value, `${sent}'s ${key}`);
+    if (holdsElements(value, key === 'children')) {
+      props[key] = await resolve(value);
+      changed = true;
+    }
+  }
+  return changed ? cloneElement(element, props) : element;
+}
+
+/**
+ * Whether a prop is something to render: an element, or a list holding
+ * one, and as children a promise too -- what an async child streams as. A
+ * promise in any other prop is one Flight sends as a promise, for the
+ * client component to use(), so it is left one. A list of plain data -- a
+ * page's products -- is left as it is.
+ *
+ * @param {unknown} value
+ * @param {boolean} children
+ * @returns {boolean}
+ */
+function holdsElements(value, children) {
+  if (isValidElement(value) || (children && isThenable(value))) return true;
+  return Array.isArray(value) && value.some((item) => holdsElements(item, children));
+}
+
+/**
+ * What Flight refuses: a function, unless it is an action reference (which
+ * the real build sends as `{ action, url }`), and a symbol.
+ *
+ * @param {unknown} value
+ * @param {string} where
+ * @param {Set<unknown>} [seen]
+ */
+function assertSendable(value, where, seen = new Set()) {
+  if (typeof value === 'symbol') {
+    throw new TypeError(`[tinvar] ${where} is a symbol, which a server component cannot hand a client one.`);
+  }
+  if (typeof value === 'function') {
+    if (/** @type {any} */ (value)[REFERENCE] === true) return;
+    throw new TypeError(
+      `[tinvar] ${where} is a function, which a server component cannot hand a client one ` +
+        '("Functions cannot be passed directly to Client Components"). Pass an action reference or data.',
+    );
+  }
+  if (value === null || typeof value !== 'object' || seen.has(value) || isValidElement(value)) return;
+  seen.add(value);
+  for (const [key, inner] of Object.entries(value)) assertSendable(inner, `${where}.${key}`, seen);
+}
+
+/** @param {unknown} value @returns {value is PromiseLike<unknown>} */
+function isThenable(value) {
+  return (
+    value !== null && typeof value === 'object' && typeof (/** @type {any} */ (value).then) === 'function'
+  );
+}
+
+/** @param {Function} type */
+function nameOf(type) {
+  return /** @type {any} */ (type).displayName || type.name || 'a client component';
+}
+
+/**
+ * A hook called outside React means a client component was called as a
+ * server one: its module has no 'use client', or the test runs without
+ * tinvarTesting(), which marks those that do.
+ *
+ * @param {unknown} error
+ * @param {Function} type
+ */
+function explainHooks(error, type) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (!/hook|reading 'use[A-Z]/i.test(message)) return error;
+  return new Error(
+    `[tinvar] ${nameOf(type)} was rendered as a server component and called a hook (${message}). ` +
+      "A component with hooks is a client one: its module needs 'use client', and the test config " +
+      'tinvarTesting() from @tinvar/renderer/vitest.',
+    { cause: error },
+  );
+}

package/src/transfer.d.ts

@@ -0,0 +1,48 @@
+/** What one export takes and writes, as codegen describes it. */
+export interface ExportShape {
+  args: object;
+  formats: string;
+}
+
+/** What one import takes and reads, as codegen describes it. */
+export interface ImportShape {
+  args: object;
+  columns: string;
+}
+
+/** A start the server refused: its status, its error code, and a 422's field errors. */
+export declare class TransferError extends Error {
+  readonly transfer: string;
+  readonly status: number;
+  readonly code: string | null;
+  readonly errors: Record<string, string[]>;
+}
+
+/** The record a start queued: its id, for the page that lists the user's transfers. */
+export interface Started {
+  transfer: string;
+  status: 'queued';
+}
+
+export interface Transfers<
+  E extends { [N in keyof E]: ExportShape },
+  I extends { [N in keyof I]: ImportShape },
+> {
+  /** Starts an export: the file is written by a worker, and linked from the user's list once it is. */
+  export<N extends keyof E & string>(
+    name: N,
+    options?: { args?: E[N]['args']; format?: E[N]['formats']; signal?: AbortSignal; fetch?: typeof fetch },
+  ): Promise<Started>;
+  /** Sends a CSV file to an import: its rows are applied by a worker, all of them or none. */
+  import<N extends keyof I & string>(
+    name: N,
+    file: Blob,
+    options?: { args?: I[N]['args']; signal?: AbortSignal; fetch?: typeof fetch },
+  ): Promise<Started>;
+}
+
+/** Builds the typed `transfer` codegen exports. */
+export declare function transfers<
+  E extends { [N in keyof E]: ExportShape },
+  I extends { [N in keyof I]: ImportShape },
+>(): Transfers<E, I>;