@olivervea/pipelines 2.0.0-beta.2 → 2.0.0-beta.20

package/src/describe/mapper-source.ts

@@ -12,34 +12,103 @@
 //   function (from) { return { … }; }
 // Free identifiers (`RELEASE`, `CONFIG.url`) are allowed: they are module constants, recorded as
 // `{const}` by the proxy. This requires the harness bundle not to be minified.
-import { MapperError } from "./record.ts";
+import { MapperError } from './record.ts';
 
 type Tok =
-  | { t: "ident"; v: string; pos: number }
-  | { t: "str"; v: string; pos: number }
-  | { t: "num"; v: string; pos: number }
-  | { t: "punc"; v: string; pos: number }
-  | { t: "op"; v: string; pos: number }
-  | { t: "eof"; v: ""; pos: number };
+  | { t: 'ident'; v: string; pos: number }
+  | { t: 'str'; v: string; pos: number }
+  | { t: 'num'; v: string; pos: number }
+  | { t: 'punc'; v: string; pos: number }
+  | { t: 'op'; v: string; pos: number }
+  | { t: 'eof'; v: ''; pos: number };
 
-const PUNCS = ["...", "=>", "?.", "(", ")", "{", "}", "[", "]", ",", ":", ".", ";"];
-const OPS = ["===", "!==", "**=", "??=", "&&=", "||=", "==", "!=", "<=", ">=", "&&", "||", "??", "++", "--", "**", "<<", ">>", "+=", "-=", "*=", "/=", "?", "!", "+", "-", "*", "/", "%", "<", ">", "=", "&", "|", "^", "~", "@", "#"];
+const PUNCS = ['...', '=>', '?.', '(', ')', '{', '}', '[', ']', ',', ':', '.', ';'];
+const OPS = [
+  '===',
+  '!==',
+  '**=',
+  '??=',
+  '&&=',
+  '||=',
+  '==',
+  '!=',
+  '<=',
+  '>=',
+  '&&',
+  '||',
+  '??',
+  '++',
+  '--',
+  '**',
+  '<<',
+  '>>',
+  '+=',
+  '-=',
+  '*=',
+  '/=',
+  '?',
+  '!',
+  '+',
+  '-',
+  '*',
+  '/',
+  '%',
+  '<',
+  '>',
+  '=',
+  '&',
+  '|',
+  '^',
+  '~',
+  '@',
+  '#',
+];
 
 function describeOp(op: string): string {
-  if (op === "?") return "a ternary (`? :`)";
-  if (op === "??") return "nullish coalescing (`??`)";
-  if (op === "&&" || op === "||") return `a logical operator (\`${op}\`)`;
-  if (op === "!") return "negation (`!`)";
-  if (["===", "!==", "==", "!=", "<", ">", "<=", ">="].includes(op)) return `a comparison (\`${op}\`)`;
-  if (["+", "-", "*", "/", "%", "**"].includes(op)) return `arithmetic/concatenation (\`${op}\`)`;
-  if (op.endsWith("=") || op === "++" || op === "--") return `an assignment (\`${op}\`)`;
+  if (op === '?') return 'a ternary (`? :`)';
+  if (op === '??') return 'nullish coalescing (`??`)';
+  if (op === '&&' || op === '||') return `a logical operator (\`${op}\`)`;
+  if (op === '!') return 'negation (`!`)';
+  if (['===', '!==', '==', '!=', '<', '>', '<=', '>='].includes(op))
+    return `a comparison (\`${op}\`)`;
+  if (['+', '-', '*', '/', '%', '**'].includes(op))
+    return `arithmetic/concatenation (\`${op}\`)`;
+  if (op.endsWith('=') || op === '++' || op === '--') return `an assignment (\`${op}\`)`;
   return `the operator \`${op}\``;
 }
 
 const KEYWORDS = new Set([
-  "typeof", "void", "delete", "new", "await", "yield", "this", "super", "class", "function", "async",
-  "if", "else", "for", "while", "do", "switch", "case", "try", "catch", "throw", "var", "let", "const",
-  "in", "instanceof", "import", "export", "return", "arguments", "eval",
+  'typeof',
+  'void',
+  'delete',
+  'new',
+  'await',
+  'yield',
+  'this',
+  'super',
+  'class',
+  'function',
+  'async',
+  'if',
+  'else',
+  'for',
+  'while',
+  'do',
+  'switch',
+  'case',
+  'try',
+  'catch',
+  'throw',
+  'var',
+  'let',
+  'const',
+  'in',
+  'instanceof',
+  'import',
+  'export',
+  'return',
+  'arguments',
+  'eval',
 ]);
 
 function tokenize(src: string): Tok[] {
@@ -47,57 +116,72 @@ function tokenize(src: string): Tok[] {
   let i = 0;
   while (i < src.length) {
     const c = src[i]!;
-    if (/\s/.test(c)) { i++; continue; }
-    if (src.startsWith("//", i)) { const e = src.indexOf("\n", i); i = e < 0 ? src.length : e + 1; continue; }
-    if (src.startsWith("/*", i)) {
-      const e = src.indexOf("*/", i + 2);
-      if (e < 0) throw new MapperError("mapper source has an unterminated comment");
+    if (/\s/.test(c)) {
+      i++;
+      continue;
+    }
+    if (src.startsWith('//', i)) {
+      const e = src.indexOf('\n', i);
+      i = e < 0 ? src.length : e + 1;
+      continue;
+    }
+    if (src.startsWith('/*', i)) {
+      const e = src.indexOf('*/', i + 2);
+      if (e < 0) throw new MapperError('mapper source has an unterminated comment');
       i = e + 2;
       continue;
     }
-    if (c === "`") throw new MapperError("mapper uses a template string");
+    if (c === '`') throw new MapperError('mapper uses a template string');
     if (c === '"' || c === "'") {
       let j = i + 1;
-      let v = "";
+      let v = '';
       for (;;) {
-        if (j >= src.length) throw new MapperError("mapper source has an unterminated string");
+        if (j >= src.length)
+          throw new MapperError('mapper source has an unterminated string');
         const d = src[j]!;
         if (d === c) break;
-        if (d === "\\") { v += src.slice(j, j + 2); j += 2; continue; }
+        if (d === '\\') {
+          v += src.slice(j, j + 2);
+          j += 2;
+          continue;
+        }
         v += d;
         j++;
       }
-      toks.push({ t: "str", v, pos: i });
+      toks.push({ t: 'str', v, pos: i });
       i = j + 1;
       continue;
     }
-    const num = /^(?:0[xXoObB][0-9a-fA-F_]+|(?:\d[\d_]*)?\.?\d[\d_]*(?:[eE][+-]?\d+)?)n?/.exec(src.slice(i));
-    if (num && /[\d.]/.test(c) && num[0] !== ".") {
-      toks.push({ t: "num", v: num[0], pos: i });
+    const num =
+      /^(?:0[xXoObB][0-9a-fA-F_]+|(?:\d[\d_]*)?\.?\d[\d_]*(?:[eE][+-]?\d+)?)n?/.exec(
+        src.slice(i),
+      );
+    if (num && /[\d.]/.test(c) && num[0] !== '.') {
+      toks.push({ t: 'num', v: num[0], pos: i });
       i += num[0].length;
       continue;
     }
     const id = /^[\p{ID_Start}$_][\p{ID_Continue}$‌‍]*/u.exec(src.slice(i));
     if (id) {
-      toks.push({ t: "ident", v: id[0], pos: i });
+      toks.push({ t: 'ident', v: id[0], pos: i });
       i += id[0].length;
       continue;
     }
     const p = PUNCS.find((x) => src.startsWith(x, i));
-    if (p && !(p === "?." && /\d/.test(src[i + 2] ?? ""))) {
-      toks.push({ t: "punc", v: p, pos: i });
+    if (p && !(p === '?.' && /\d/.test(src[i + 2] ?? ''))) {
+      toks.push({ t: 'punc', v: p, pos: i });
       i += p.length;
       continue;
     }
     const o = OPS.find((x) => src.startsWith(x, i));
     if (o) {
-      toks.push({ t: "op", v: o, pos: i });
+      toks.push({ t: 'op', v: o, pos: i });
       i += o.length;
       continue;
     }
     throw new MapperError(`mapper source has an unexpected character '${c}'`);
   }
-  toks.push({ t: "eof", v: "", pos: src.length });
+  toks.push({ t: 'eof', v: '', pos: src.length });
   return toks;
 }
 
@@ -107,132 +191,193 @@ export function analyzeMapperSource(src: string): void {
   let k = 0;
   const peek = (o = 0) => toks[Math.min(k + o, toks.length - 1)]!;
   const next = () => toks[k++]!;
-  const is = (t: Tok["t"], v?: string, o = 0) => peek(o).t === t && (v === undefined || peek(o).v === v);
-  const unexpected = (what = "here"): never => {
+  const is = (t: Tok['t'], v?: string, o = 0) =>
+    peek(o).t === t && (v === undefined || peek(o).v === v);
+  const unexpected = (what = 'here'): never => {
     const tok = peek();
-    if (tok.t === "op") throw new MapperError(`mapper uses ${describeOp(tok.v)}; mappers may only contain property access and literals — move logic into the handler or a when block`);
-    if (tok.t === "punc" && tok.v === "?.") throw new MapperError("mapper uses optional chaining (`?.`); declare the input optional(...) and map the whole ref instead");
-    if (tok.t === "punc" && tok.v === "...") throw new MapperError("mapper uses spread (`...`); list the fields explicitly");
-    if (tok.t === "punc" && tok.v === "(") throw new MapperError("mapper calls a function or method; mappers may only contain property access and literals");
-    if (tok.t === "ident" && KEYWORDS.has(tok.v)) throw new MapperError(`mapper uses \`${tok.v}\`; mappers may only contain property access and literals`);
-    throw new MapperError(`mapper source is not an object literal of property accesses and literals (unexpected ${tok.t === "eof" ? "end" : `'${tok.v}'`} ${what})`);
+    if (tok.t === 'op')
+      throw new MapperError(
+        `mapper uses ${describeOp(tok.v)}; mappers may only contain property access and literals — move logic into the handler or a when block`,
+      );
+    if (tok.t === 'punc' && tok.v === '?.')
+      throw new MapperError(
+        'mapper uses optional chaining (`?.`); declare the input optional(...) and map the whole ref instead',
+      );
+    if (tok.t === 'punc' && tok.v === '...')
+      throw new MapperError('mapper uses spread (`...`); list the fields explicitly');
+    if (tok.t === 'punc' && tok.v === '(')
+      throw new MapperError(
+        'mapper calls a function or method; mappers may only contain property access and literals',
+      );
+    if (tok.t === 'ident' && KEYWORDS.has(tok.v))
+      throw new MapperError(
+        `mapper uses \`${tok.v}\`; mappers may only contain property access and literals`,
+      );
+    throw new MapperError(
+      `mapper source is not an object literal of property accesses and literals (unexpected ${tok.t === 'eof' ? 'end' : `'${tok.v}'`} ${what})`,
+    );
   };
-  const expect = (t: Tok["t"], v?: string) => (is(t, v) ? next() : unexpected(`(expected ${v ?? t})`));
+  const expect = (t: Tok['t'], v?: string) =>
+    is(t, v) ? next() : unexpected(`(expected ${v ?? t})`);
 
   const identifier = () => {
-    if (!is("ident") || KEYWORDS.has(peek().v)) unexpected("(expected an identifier)");
+    if (!is('ident') || KEYWORDS.has(peek().v)) unexpected('(expected an identifier)');
     return next();
   };
 
   // ── parameters ──
   const params = () => {
-    if (is("ident")) { identifier(); return; }
-    expect("punc", "(");
-    if (is("punc", ")")) { next(); return; }
-    if (is("punc", "{")) destructuring();
+    if (is('ident')) {
+      identifier();
+      return;
+    }
+    expect('punc', '(');
+    if (is('punc', ')')) {
+      next();
+      return;
+    }
+    if (is('punc', '{')) destructuring();
     else identifier();
-    if (is("punc", ",")) next();
-    if (is("op", "=")) throw new MapperError("mapper parameter has a default value");
-    expect("punc", ")");
+    if (is('punc', ',')) next();
+    if (is('op', '=')) throw new MapperError('mapper parameter has a default value');
+    expect('punc', ')');
   };
   const destructuring = () => {
-    expect("punc", "{");
-    while (!is("punc", "}")) {
-      if (is("str")) { next(); expect("punc", ":"); identifier(); }
-      else {
+    expect('punc', '{');
+    while (!is('punc', '}')) {
+      if (is('str')) {
+        next();
+        expect('punc', ':');
+        identifier();
+      } else {
         identifier();
-        if (is("punc", ":")) { next(); identifier(); }
+        if (is('punc', ':')) {
+          next();
+          identifier();
+        }
       }
-      if (is("op", "=")) throw new MapperError("mapper parameter destructuring has a default value");
-      if (!is("punc", ",")) break;
+      if (is('op', '='))
+        throw new MapperError('mapper parameter destructuring has a default value');
+      if (!is('punc', ',')) break;
       next();
     }
-    expect("punc", "}");
+    expect('punc', '}');
   };
 
   // ── values ──
   const value = (): void => {
-    if (is("punc", "(")) { next(); value(); expect("punc", ")"); return; }
-    if (is("punc", "{")) return object();
-    if (is("punc", "[")) return array();
-    if (is("str") || is("num")) { next(); return; }
-    if (is("op", "-") && is("num", undefined, 1)) { next(); next(); return; }
-    if (is("ident", "true") || is("ident", "false") || is("ident", "null")) { next(); return; }
-    if (is("ident", "undefined")) throw new MapperError("mapper uses `undefined`; leave optional fields out instead");
+    if (is('punc', '(')) {
+      next();
+      value();
+      expect('punc', ')');
+      return;
+    }
+    if (is('punc', '{')) return object();
+    if (is('punc', '[')) return array();
+    if (is('str') || is('num')) {
+      next();
+      return;
+    }
+    if (is('op', '-') && is('num', undefined, 1)) {
+      next();
+      next();
+      return;
+    }
+    if (is('ident', 'true') || is('ident', 'false') || is('ident', 'null')) {
+      next();
+      return;
+    }
+    if (is('ident', 'undefined'))
+      throw new MapperError('mapper uses `undefined`; leave optional fields out instead');
     chain();
   };
   const chain = () => {
     identifier();
     for (;;) {
-      if (is("punc", ".")) { next(); if (!is("ident")) unexpected("(expected a property name)"); next(); continue; }
-      if (is("punc", "[")) {
+      if (is('punc', '.')) {
+        next();
+        if (!is('ident')) unexpected('(expected a property name)');
+        next();
+        continue;
+      }
+      if (is('punc', '[')) {
         next();
-        if (!is("str") && !is("num")) throw new MapperError("mapper uses a computed property access; only literal keys (from[\"step-name\"]) are allowed");
+        if (!is('str') && !is('num'))
+          throw new MapperError(
+            'mapper uses a computed property access; only literal keys (from["step-name"]) are allowed',
+          );
         next();
-        expect("punc", "]");
+        expect('punc', ']');
         continue;
       }
       break;
     }
   };
   const array = () => {
-    expect("punc", "[");
-    while (!is("punc", "]")) {
-      if (is("punc", ",")) unexpected("(array holes are not allowed)");
+    expect('punc', '[');
+    while (!is('punc', ']')) {
+      if (is('punc', ',')) unexpected('(array holes are not allowed)');
       value();
-      if (!is("punc", ",")) break;
+      if (!is('punc', ',')) break;
       next();
     }
-    expect("punc", "]");
+    expect('punc', ']');
   };
   const object = () => {
-    expect("punc", "{");
-    while (!is("punc", "}")) {
-      if (is("punc", "...")) unexpected();
-      if (is("punc", "[")) throw new MapperError("mapper uses a computed key; only literal keys are allowed");
-      if (is("ident") && (is("punc", ",", 1) || is("punc", "}", 1))) {
+    expect('punc', '{');
+    while (!is('punc', '}')) {
+      if (is('punc', '...')) unexpected();
+      if (is('punc', '['))
+        throw new MapperError(
+          'mapper uses a computed key; only literal keys are allowed',
+        );
+      if (is('ident') && (is('punc', ',', 1) || is('punc', '}', 1))) {
         // shorthand `{ input }` — a destructured root or a module constant
         identifier();
       } else {
-        if (is("ident") || is("str") || is("num")) next();
-        else unexpected("(expected a property name)");
-        if (is("punc", "(")) throw new MapperError("mapper defines a method; mappers may only contain property access and literals");
-        expect("punc", ":");
+        if (is('ident') || is('str') || is('num')) next();
+        else unexpected('(expected a property name)');
+        if (is('punc', '('))
+          throw new MapperError(
+            'mapper defines a method; mappers may only contain property access and literals',
+          );
+        expect('punc', ':');
         value();
       }
-      if (!is("punc", ",")) break;
+      if (!is('punc', ',')) break;
       next();
     }
-    expect("punc", "}");
+    expect('punc', '}');
   };
   const returnBody = () => {
-    expect("punc", "{");
-    if (!is("ident", "return")) unexpected("(a block-bodied mapper must consist of a single `return { … }`)");
+    expect('punc', '{');
+    if (!is('ident', 'return'))
+      unexpected('(a block-bodied mapper must consist of a single `return { … }`)');
     next();
     object();
-    if (is("punc", ";")) next();
-    expect("punc", "}");
+    if (is('punc', ';')) next();
+    expect('punc', '}');
   };
 
   // ── function ──
-  if (is("ident", "async")) throw new MapperError("mapper must not be async");
-  if (is("ident", "function")) {
+  if (is('ident', 'async')) throw new MapperError('mapper must not be async');
+  if (is('ident', 'function')) {
     next();
-    if (is("op", "*")) throw new MapperError("mapper must not be a generator");
-    if (is("ident")) next();
+    if (is('op', '*')) throw new MapperError('mapper must not be a generator');
+    if (is('ident')) next();
     params();
     returnBody();
   } else {
     params();
-    expect("punc", "=>");
-    if (is("punc", "(")) {
+    expect('punc', '=>');
+    if (is('punc', '(')) {
       next();
       object();
-      expect("punc", ")");
-    } else if (is("punc", "{")) {
+      expect('punc', ')');
+    } else if (is('punc', '{')) {
       returnBody();
-    } else unexpected("(the mapper body must be an object literal: from => ({ … }))");
+    } else unexpected('(the mapper body must be an object literal: from => ({ … }))');
   }
-  if (is("punc", ";")) next();
-  if (!is("eof")) unexpected("after the mapper body");
+  if (is('punc', ';')) next();
+  if (!is('eof')) unexpected('after the mapper body');
 }

package/src/describe/record.ts

@@ -4,10 +4,10 @@
 // `in`, assignment and JSON.stringify. It CANNOT see truthiness, `!`, `??`, `||`, ternaries or
 // `===` against a value — those are rejected by the static source analysis (mapper-source.ts),
 // and primarily by the `Ref<T>` types.
-import { REF_PATH } from "../core/brands.ts";
+import { REF_PATH } from '../core/brands.ts';
 
 export class MapperError extends Error {
-  override name = "MapperError";
+  override name = 'MapperError';
 }
 
 /** Manifest mapping node: `{ref}` | `{const}` | a nested object of mappings. */
@@ -24,22 +24,28 @@ function refProxy(path: string): unknown {
   return new Proxy(target, {
     get(_t, prop) {
       if (prop === REF_PATH) return path;
-      if (prop === "then") return undefined; // `await ref` must not recurse
-      if (prop === Symbol.toPrimitive || prop === "toString" || prop === "valueOf")
-        return fail("coerces a value (template string / concatenation / arithmetic / comparison)");
-      if (prop === "toJSON") return fail("serializes a reference (JSON.stringify)");
-      if (typeof prop === "symbol") return fail(`uses ${String(prop)} (iteration/spread/inspection)`);
-      if (prop.includes(".")) return fail(`accesses field '${prop}' (field names containing '.' cannot be mapped)`);
+      if (prop === 'then') return undefined; // `await ref` must not recurse
+      if (prop === Symbol.toPrimitive || prop === 'toString' || prop === 'valueOf')
+        return fail(
+          'coerces a value (template string / concatenation / arithmetic / comparison)',
+        );
+      if (prop === 'toJSON') return fail('serializes a reference (JSON.stringify)');
+      if (typeof prop === 'symbol')
+        return fail(`uses ${String(prop)} (iteration/spread/inspection)`);
+      if (prop.includes('.'))
+        return fail(
+          `accesses field '${prop}' (field names containing '.' cannot be mapped)`,
+        );
       return refProxy(`${path}.${prop}`);
     },
-    apply: () => fail("calls a function/method"),
-    construct: () => fail("constructs"),
-    set: () => fail("assigns"),
-    deleteProperty: () => fail("deletes"),
-    has: () => fail("uses the `in` operator"),
-    ownKeys: () => fail("enumerates/spreads"),
-    defineProperty: () => fail("defines a property"),
-    getPrototypeOf: () => fail("inspects the prototype (instanceof)"),
+    apply: () => fail('calls a function/method'),
+    construct: () => fail('constructs'),
+    set: () => fail('assigns'),
+    deleteProperty: () => fail('deletes'),
+    has: () => fail('uses the `in` operator'),
+    ownKeys: () => fail('enumerates/spreads'),
+    defineProperty: () => fail('defines a property'),
+    getPrototypeOf: () => fail('inspects the prototype (instanceof)'),
   });
 }
 
@@ -49,59 +55,83 @@ export function rootProxy(available: ReadonlySet<string>): unknown {
     {},
     {
       get(_t, prop) {
-        if (typeof prop === "symbol" || prop === "then") return undefined;
+        if (typeof prop === 'symbol' || prop === 'then') return undefined;
         if (!available.has(prop))
-          throw new MapperError(`mapper references '${prop}', which is not available at this stage (available: ${[...available].sort().join(", ") || "none"})`);
+          throw new MapperError(
+            `mapper references '${prop}', which is not available at this stage (available: ${[...available].sort().join(', ') || 'none'})`,
+          );
         return refProxy(prop);
       },
       has: () => {
-        throw new MapperError("mapper uses the `in` operator on its argument");
+        throw new MapperError('mapper uses the `in` operator on its argument');
       },
       ownKeys: () => {
-        throw new MapperError("mapper enumerates/spreads its argument");
+        throw new MapperError('mapper enumerates/spreads its argument');
       },
     },
   );
 }
 
 export const refPathOf = (v: unknown): string | undefined =>
-  typeof v === "function" ? ((v as unknown as Record<symbol, unknown>)[REF_PATH] as string | undefined) : undefined;
+  typeof v === 'function'
+    ? ((v as unknown as Record<symbol, unknown>)[REF_PATH] as string | undefined)
+    : undefined;
 
 function toMapping(v: unknown, at: string): Mapping {
   const path = refPathOf(v);
   if (path !== undefined) return { ref: path };
-  if (typeof v === "function") throw new MapperError(`mapper returns a function at '${at}'`);
+  if (typeof v === 'function')
+    throw new MapperError(`mapper returns a function at '${at}'`);
   if (v === undefined) throw new MapperError(`mapper returns undefined at '${at}'`);
-  if (v === null || typeof v === "string" || typeof v === "boolean") return { const: v };
-  if (typeof v === "number") {
-    if (!Number.isFinite(v)) throw new MapperError(`mapper returns a non-finite number at '${at}'`);
+  if (v === null || typeof v === 'string' || typeof v === 'boolean') return { const: v };
+  if (typeof v === 'number') {
+    if (!Number.isFinite(v))
+      throw new MapperError(`mapper returns a non-finite number at '${at}'`);
     return { const: v };
   }
   if (Array.isArray(v)) {
     const items = v.map((x, i) => toMapping(x, `${at}[${i}]`));
-    if (items.every((e) => "const" in e && Object.keys(e).length === 1)) return { const: items.map((e) => (e as { const: unknown }).const) };
-    throw new MapperError(`mapper puts references inside an array at '${at}' (only constant arrays are supported)`);
+    if (items.every((e) => 'const' in e && Object.keys(e).length === 1))
+      return { const: items.map((e) => (e as { const: unknown }).const) };
+    throw new MapperError(
+      `mapper puts references inside an array at '${at}' (only constant arrays are supported)`,
+    );
   }
-  if (typeof v === "object") {
-    if (Object.getPrototypeOf(v) !== Object.prototype && Object.getPrototypeOf(v) !== null)
+  if (typeof v === 'object') {
+    if (
+      Object.getPrototypeOf(v) !== Object.prototype &&
+      Object.getPrototypeOf(v) !== null
+    )
       throw new MapperError(`mapper returns a non-plain object at '${at}'`);
     const keys = Object.keys(v);
-    if (keys.length === 1 && (keys[0] === "ref" || keys[0] === "const"))
-      throw new MapperError(`mapper builds an object whose only field is '${keys[0]}' at '${at}'; that is reserved by the manifest's mapping encoding — map the whole object with a ref instead`);
+    if (keys.length === 1 && (keys[0] === 'ref' || keys[0] === 'const'))
+      throw new MapperError(
+        `mapper builds an object whose only field is '${keys[0]}' at '${at}'; that is reserved by the manifest's mapping encoding — map the whole object with a ref instead`,
+      );
     const out: Record<string, Mapping> = {};
-    for (const k of keys) out[k] = toMapping((v as Record<string, unknown>)[k], at ? `${at}.${k}` : k);
+    for (const k of keys)
+      out[k] = toMapping((v as Record<string, unknown>)[k], at ? `${at}.${k}` : k);
     return out;
   }
   throw new MapperError(`mapper returns an unsupported value (${typeof v}) at '${at}'`);
 }
 
 /** Calls `fn` with recording proxies and returns `{ inputKey: Mapping }`. */
-export function recordMapper(fn: (from: unknown) => unknown, available: ReadonlySet<string>): Record<string, Mapping> {
+export function recordMapper(
+  fn: (from: unknown) => unknown,
+  available: ReadonlySet<string>,
+): Record<string, Mapping> {
   const result = fn(rootProxy(available));
-  if (refPathOf(result) !== undefined || typeof result !== "object" || result === null || Array.isArray(result))
-    throw new MapperError("mapper must return an object literal");
-  if (result instanceof Promise) throw new MapperError("mapper must be synchronous");
+  if (
+    refPathOf(result) !== undefined ||
+    typeof result !== 'object' ||
+    result === null ||
+    Array.isArray(result)
+  )
+    throw new MapperError('mapper must return an object literal');
+  if (result instanceof Promise) throw new MapperError('mapper must be synchronous');
   const out: Record<string, Mapping> = {};
-  for (const k of Object.keys(result)) out[k] = toMapping((result as Record<string, unknown>)[k], k);
+  for (const k of Object.keys(result))
+    out[k] = toMapping((result as Record<string, unknown>)[k], k);
   return out;
 }