@capacms/sdk 1.0.0-next.1 → 1.0.0-next.10

package/dist/next/graphql/plan.js

@@ -0,0 +1,531 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_RELATION_DEPTH = exports.MEDIA_FIELDS = exports.SYSTEM_FIELDS = exports.CapaBuildError = exports.LIST_DEFAULT = exports.END_OF_LIST = void 0;
+exports.didYouMean = didYouMean;
+exports.findModel = findModel;
+exports.isHop = isHop;
+exports.planQuery = planQuery;
+/**
+ * plan.ts — a query spec, checked against a key's schema summary.
+ *
+ * The spec is the small JSON an Explorer, an agent or a script writes ("these
+ * fields of articles, newest first, five of them"). Resolving it once, here,
+ * gives both printers (GraphQL in build.ts, REST in rest.ts) the same checked
+ * tree, so the two can only differ in syntax. Every refusal is a
+ * `CapaBuildError` naming the closest real names, so a caller can correct
+ * itself in one step.
+ */
+const filter_values_1 = require("./filter-values");
+const summary_1 = require("./summary");
+/** REST's `before=end`: the last entries of the list, read back from its end (spec 17, amendment 132). */
+exports.END_OF_LIST = "end";
+/** REST's and GraphQL's root page size when none is given. */
+exports.LIST_DEFAULT = 25;
+class CapaBuildError extends Error {
+    /** The closest real names, nearest first. */
+    didYouMean;
+    /** Every name that would have been accepted. */
+    available;
+    constructor(message, didYouMean = [], available = []) {
+        super(message);
+        this.name = "CapaBuildError";
+        this.didYouMean = didYouMean;
+        this.available = available;
+    }
+}
+exports.CapaBuildError = CapaBuildError;
+/** The system fields every model type has (N6), in schema order. */
+exports.SYSTEM_FIELDS = [
+    "id",
+    "model",
+    "status",
+    "createdAt",
+    "updatedAt",
+    "publishedAt",
+    "_version",
+    "_tags",
+    "_folder",
+];
+exports.MEDIA_FIELDS = ["id", "url", "alt", "type", "width", "height"];
+const MEDIA_DEFAULT = ["id", "url", "alt"];
+/**
+ * Relations a query may nest below its root entry. The API reads 5 levels of
+ * entries per root field and counts the root's own as the first, so 4
+ * relations below it (spec 17, amendment 78).
+ */
+exports.MAX_RELATION_DEPTH = 4;
+function levenshtein(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let previous = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const current = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+            previous = current;
+        }
+    }
+    return row[b.length];
+}
+/** Names within two edits of `wanted`, nearest first then by name, at most three. */
+function didYouMean(wanted, candidates) {
+    const needle = wanted.toLowerCase();
+    return [...new Set(candidates)]
+        .map((name) => ({ name, distance: levenshtein(needle, name.toLowerCase()) }))
+        .filter((c) => c.distance <= 2)
+        .sort((a, b) => a.distance - b.distance || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+        .slice(0, 3)
+        .map((c) => c.name);
+}
+/**
+ * The refusal for a model the key reads that GraphQL leaves out (N1): REST
+ * serves it, so the message names that read and why, and suggests no other
+ * model. `@capacms/mcp` says the same, pinned by a test.
+ */
+function restOnlyModel(namespace, restOnly) {
+    // N1 leaves models out when their type names would collide, as these
+    // spellings do. For the sentence only, never for a name that is sent.
+    const letters = (name) => name.toLowerCase().replace(/[^0-9a-z]/g, "");
+    const partners = restOnly.filter((other) => other !== namespace && letters(other) === letters(namespace));
+    const named = ["it", ...partners];
+    const why = partners.length
+        ? `${named.slice(0, -1).join(", ")} and ${named[named.length - 1]} would have the same GraphQL type name`
+        : "its namespace gives no GraphQL type name of its own";
+    return new CapaBuildError(`${namespace} is readable over REST only: GET /api/entries/${namespace}. GraphQL leaves it out, since ${why}.`);
+}
+/**
+ * A model by namespace or type name, then by any of those or its display name
+ * ignoring case (`Writers`, `scalar specimens`). An unknown name is refused
+ * with the nearest models, each by namespace, whichever of its names was near.
+ */
+function findModel(summary, wanted) {
+    const exact = summary.models.find((m) => m.namespace === wanted || m.typeName === wanted);
+    if (exact)
+        return exact;
+    const { restOnly } = summary;
+    if (restOnly.includes(wanted))
+        throw restOnlyModel(wanted, restOnly);
+    const lower = String(wanted).toLowerCase();
+    const names = (m) => [m.namespace, m.typeName, (0, summary_1.modelDisplayName)(m)];
+    const loose = summary.models.filter((m) => names(m).some((name) => name.toLowerCase() === lower));
+    if (loose.length === 1)
+        return loose[0];
+    const looseRestOnly = restOnly.filter((name) => name.toLowerCase() === lower);
+    if (!loose.length && looseRestOnly.length === 1)
+        throw restOnlyModel(looseRestOnly[0], restOnly);
+    const namespaces = summary.models.map((m) => m.namespace);
+    if (loose.length > 1) {
+        throw new CapaBuildError(`model ${wanted} is ambiguous: pass one of ${orList(loose.map((m) => m.namespace))}`, loose.map((m) => m.namespace), namespaces);
+    }
+    const namespaceOf = new Map(summary.models.flatMap((m) => names(m).map((name) => [name, m.namespace])));
+    const near = [...new Set(didYouMean(String(wanted), [...namespaceOf.keys()]).map((name) => namespaceOf.get(name)))];
+    throw new CapaBuildError(`unknown model ${wanted}`, near, namespaces);
+}
+function modelByNamespace(summary, namespace) {
+    return namespace === null ? undefined : summary.models.find((m) => m.namespace === namespace);
+}
+function selectableNames(model) {
+    return [...exports.SYSTEM_FIELDS, ...model.fields.map((f) => f.name)];
+}
+/**
+ * A field by its GraphQL name, then a system field, then a field by its
+ * namespace: `createdAt` is the system field even where a field's namespace
+ * is `createdAt` (that field is `createdAt_field`, N5).
+ */
+function findField(model, wanted) {
+    const byName = model.fields.find((f) => f.name === wanted);
+    if (byName)
+        return byName;
+    if (exports.SYSTEM_FIELDS.includes(wanted))
+        return null;
+    const byNamespace = model.fields.find((f) => f.namespace === wanted);
+    if (byNamespace)
+        return byNamespace;
+    throw new CapaBuildError(`unknown field ${wanted} on ${model.typeName}`, didYouMean(wanted, selectableNames(model)), selectableNames(model));
+}
+function checkFirst(value, where) {
+    if (!Number.isInteger(value) || value < 1 || value > 200) {
+        throw new CapaBuildError(`${where} must be a whole number from 1 to 200`);
+    }
+    return value;
+}
+/**
+ * A relation list's sort: one value, as its argument takes (N7). A list of
+ * one, the root's shape, is that value; a longer list is refused, since the
+ * API sorts a relation list by one key.
+ */
+function oneSort(value, name) {
+    if (!Array.isArray(value))
+        return value;
+    if (value.length === 1)
+        return value[0];
+    throw new CapaBuildError(`sort on ${name} takes one value: a relation list sorts by one key, unlike the root's up to 3`);
+}
+function checkSort(value, model, where) {
+    if (typeof value !== "string" || !model.sortValues.includes(value)) {
+        const written = typeof value === "string" ? restSortValue(value) : null;
+        if (written && model.sortValues.includes(written)) {
+            throw new CapaBuildError(`${where} ${JSON.stringify(value)} is REST's sort syntax: write ${JSON.stringify(written)}`, [written]);
+        }
+        throw new CapaBuildError(`${where} ${JSON.stringify(value)} is not a value of ${model.sortType}`, didYouMean(String(value), model.sortValues), model.sortValues);
+    }
+    return value;
+}
+// ------------------------------------------------------------ REST forms ---
+//
+// A spec written as REST writes a read (`author.name` or `author(name)` for a
+// relation's fields, `*` for every field, `-publishedAt` for a sort) is
+// refused with what to write instead, spelled out, since the same read is one
+// edit away. @capacms/mcp refuses them in the same words, pinned by
+// test/fixtures/graphql-rest-forms.json.
+/** A REST sort key as a sort value: `-publishedAt` is `publishedAt_DESC`, `author.name` is `author__name_ASC`. */
+function restSortValue(value) {
+    const match = /^(-?)([^\s-][^\s]*)$/.exec(value);
+    if (!match || /_(ASC|DESC)$/.test(match[2]))
+        return null;
+    return `${match[2].split(".").join("__")}_${match[1] ? "DESC" : "ASC"}`;
+}
+/** Split REST select text on the commas outside parentheses; null when the parentheses do not pair. */
+function restItems(text) {
+    const items = [];
+    let depth = 0;
+    let start = 0;
+    for (let at = 0; at < text.length; at++) {
+        if (text[at] === "(")
+            depth++;
+        else if (text[at] === ")" && --depth < 0)
+            return null;
+        else if (text[at] === "," && depth === 0) {
+            items.push(text.slice(start, at).trim());
+            start = at + 1;
+        }
+    }
+    if (depth !== 0)
+        return null;
+    items.push(text.slice(start).trim());
+    return items.filter(Boolean);
+}
+/** One REST select item as a field of a spec: `author(name,limit:5)` is `{ field: "author", fields: ["name"], first: 5 }`. */
+function restItemSpec(text) {
+    const open = text.indexOf("(");
+    const dot = text.indexOf(".");
+    if (open === -1 && dot === -1)
+        return text;
+    if (open === -1 || (dot !== -1 && dot < open)) {
+        const nested = restItemSpec(text.slice(dot + 1));
+        return nested === null ? null : { field: text.slice(0, dot), fields: [nested] };
+    }
+    if (!text.endsWith(")"))
+        return null;
+    const inner = restItems(text.slice(open + 1, -1));
+    if (!inner)
+        return null;
+    const fields = [];
+    const args = {};
+    for (const item of inner) {
+        const modifier = /^(limit|sort|after):(.+)$/.exec(item);
+        if (!modifier) {
+            const nested = restItemSpec(item);
+            if (nested === null)
+                return null;
+            fields.push(nested);
+        }
+        else if (modifier[1] === "limit")
+            args.first = Number(modifier[2]);
+        else if (modifier[1] === "sort")
+            args.sort = restSortValue(modifier[2]) ?? modifier[2];
+        else
+            args.after = modifier[2];
+    }
+    return { field: text.slice(0, open), ...(fields.length ? { fields } : {}), ...args };
+}
+/**
+ * The refusal for a field item written as REST writes a select, or null when
+ * `wanted` is not one. A dotted or parenthesised item counts only when what
+ * comes first is a field of `model`: a namespace may itself hold a dot.
+ */
+function restFormRefusal(model, wanted, at) {
+    if (wanted === "*") {
+        return new CapaBuildError(`${at} "*" is REST's select syntax: leave fields out for every field that is not a relation, or name the fields you want`);
+    }
+    const head = /^[^.(]+/.exec(wanted)?.[0];
+    if (!head || head === wanted || !model.fields.some((f) => f.name === head || f.namespace === head))
+        return null;
+    const spec = restItemSpec(wanted);
+    if (spec === null || typeof spec === "string")
+        return null;
+    return new CapaBuildError(`${at} ${JSON.stringify(wanted)} is REST's select syntax: write ${JSON.stringify(spec)}`);
+}
+function mediaChildren(fields, owner) {
+    const names = fields === undefined ? MEDIA_DEFAULT : fields;
+    const planned = [{ name: "id", field: null }];
+    for (const item of names) {
+        if (typeof item !== "string" || !exports.MEDIA_FIELDS.includes(item)) {
+            const name = typeof item === "string" ? item : item.field;
+            throw new CapaBuildError(`unknown field ${name} on Media (${owner})`, didYouMean(name, exports.MEDIA_FIELDS), [...exports.MEDIA_FIELDS]);
+        }
+        if (item !== "id")
+            planned.push({ name: item, field: null });
+    }
+    return planned;
+}
+/** Every current non-relation field, single relations as `{ id }`, media as `{ id url alt }`; array relations and deprecated fields left out. */
+function defaultFields(model) {
+    return model.fields.filter((f) => f.kind !== "relationList" && !f.deprecationReason).map((f) => f.name);
+}
+/** The keys a relation spec (`{ field, fields, first, sort }`) takes, and `after` in a read of one entry. */
+const FIELD_SPEC_KEYS = ["field", "fields", "first", "sort"];
+const SINGLE_FIELD_SPEC_KEYS = [...FIELD_SPEC_KEYS, "after"];
+/**
+ * A key the builder does not read is refused by name, at any depth: a typo
+ * dropped silently (`frist`) builds a query without the argument and reports
+ * that it worked. The types refuse it at compile time; this is for specs
+ * written in JSON or plain JavaScript. `after` names one entry's list, so a
+ * list read refuses it in the API's words.
+ */
+function checkSpecKeys(spec, path, single) {
+    const allowed = single ? SINGLE_FIELD_SPEC_KEYS : FIELD_SPEC_KEYS;
+    for (const key of Object.keys(spec)) {
+        if (allowed.includes(key))
+            continue;
+        if (key === "after") {
+            throw new CapaBuildError(`after: applies to a single entry: ${path}.after pages one entry's relation list. Read that entry by id to page it, or leave after out`);
+        }
+        const near = didYouMean(key, allowed);
+        throw new CapaBuildError(`Unknown argument ${key} in ${path}.${near.length ? ` Did you mean ${near.join(" or ")}?` : ""} Allowed: ${allowed.join(", ")}.`, near, [...allowed]);
+    }
+}
+/**
+ * `path` names where `specs` sit in the spec, `fields[1].fields`, for a
+ * refusal. `single` is whether the read is of one entry, where a relation
+ * list may be read on from a cursor.
+ */
+function planFields(summary, model, specs, depth, single, path = "fields") {
+    if (specs !== undefined && !Array.isArray(specs)) {
+        throw new CapaBuildError(`fields of ${model.typeName} must be an array`);
+    }
+    const planned = [{ name: "id", field: null }];
+    const seen = new Set(["id"]);
+    for (const [index, spec] of (specs ?? defaultFields(model)).entries()) {
+        const nested = typeof spec === "object" && spec !== null;
+        if (nested)
+            checkSpecKeys(spec, `${path}[${index}]`, single);
+        const wanted = nested ? spec.field : spec;
+        if (typeof wanted !== "string" || wanted === "") {
+            throw new CapaBuildError(`each field of ${model.typeName} must be a name or { field, fields }`);
+        }
+        let field;
+        try {
+            field = findField(model, wanted);
+        }
+        catch (error) {
+            throw (!nested && restFormRefusal(model, wanted, `${path}[${index}]`)) || error;
+        }
+        const name = field?.name ?? wanted;
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        const kind = field?.kind ?? "scalar";
+        if (nested && (spec.first !== undefined || spec.sort !== undefined) && kind !== "relationList") {
+            throw new CapaBuildError(`first and sort apply to array relations; ${name} on ${model.typeName} is not one`);
+        }
+        if (nested && spec.after !== undefined && kind !== "relationList") {
+            throw new CapaBuildError(`after applies to array relations; ${name} on ${model.typeName} is not one`);
+        }
+        if (kind === "relation" || kind === "relationList") {
+            const target = modelByNamespace(summary, field.target);
+            if (!target)
+                throw new CapaBuildError(`${name} on ${model.typeName} points at a model this key cannot read`);
+            if (depth >= exports.MAX_RELATION_DEPTH) {
+                throw new CapaBuildError(`${name} would expand past ${exports.MAX_RELATION_DEPTH} relation levels. Select ${name} without fields for its id, or read it with a second query`);
+            }
+            const children = planFields(summary, target, nested ? spec.fields ?? ["id"] : ["id"], depth + 1, single, `${path}[${index}].fields`);
+            const entry = { name, field, children, target };
+            if (nested && spec.first !== undefined)
+                entry.first = checkFirst(spec.first, `first on ${name}`);
+            if (nested && spec.sort !== undefined)
+                entry.sort = checkSort(oneSort(spec.sort, name), target, `sort on ${name}`);
+            if (nested && spec.after !== undefined) {
+                if (typeof spec.after !== "string" || spec.after === "")
+                    throw new CapaBuildError(`after on ${name} must be a cursor: the list's endCursor`);
+                entry.after = spec.after;
+            }
+            planned.push(entry);
+        }
+        else if (kind === "media") {
+            planned.push({ name, field, children: mediaChildren(nested ? spec.fields : undefined, name) });
+        }
+        else {
+            if (nested && spec.fields !== undefined) {
+                throw new CapaBuildError(kind === "id" || kind === "idList"
+                    ? `${name} on ${model.typeName} is an id here: this key cannot read the model it points at. Select ${name} without fields for the id`
+                    : `${name} on ${model.typeName} has no fields to select`);
+            }
+            planned.push({ name, field });
+        }
+    }
+    return planned;
+}
+const systemFilterNames = (model) => model.systemFilters.map((system) => system.name);
+function filterableNames(model) {
+    return ["and", "or", "not", ...systemFilterNames(model), ...model.fields.filter((f) => f.filterOps.length > 0).map((f) => f.name)];
+}
+/** `a, b and c`, `a, b or c`: names in a sentence. */
+const andList = (names) => `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+const orList = (names) => `${names.slice(0, -1).join(", ")} or ${names[names.length - 1]}`;
+/** GraphQL scalars an operator takes; any other input type under a field's filter is a hop into a related field. */
+const OPERAND_SCALARS = new Set(["String", "ID", "Float", "Int", "Boolean", "DateTime", "JSON"]);
+/** The operators of a system field reached through a hop (`author: { id: { eq } }`), as the API's IDFilter and DateTimeFilter declare them. */
+const SYSTEM_HOP_OPERATORS = ["eq", "ne", "lt", "lte", "gt", "gte", "in", "nin", "exists", "null"];
+/** Whether `key` under `field`'s filter is a hop into a field of the related model rather than an operator. */
+function isHop(field, key) {
+    const type = field.filterInputs[key];
+    return type !== undefined && !OPERAND_SCALARS.has(type);
+}
+/**
+ * The operator a bare value stands for under `operators`, and the value it
+ * takes: equality for one value, membership for a list, `null: true` for null.
+ */
+function operatorFor(operators, value) {
+    if (value === null)
+        return operators.includes("null") ? ["null", true] : null;
+    if (Array.isArray(value)) {
+        const op = ["in", "hasAny"].find((name) => operators.includes(name));
+        return op ? [op, value] : null;
+    }
+    const op = ["eq", "has", "id"].find((name) => operators.includes(name));
+    return op ? [op, value] : null;
+}
+/**
+ * A filter written without operators (`{ featured: true }`) is refused with
+ * the operator form to write instead: GraphQL declares an object of operators
+ * there, so the shorthand would fail on the API and has no REST twin.
+ */
+function refuseBareValue(label, operators, value, wrap) {
+    const operator = operatorFor(operators, value);
+    const fix = operator ? ` write ${JSON.stringify(wrap({ [operator[0]]: operator[1] }))}` : ` use one of ${orList(operators)}`;
+    throw new CapaBuildError(`${label} takes operators, not a bare value:${fix}`, [], [...operators]);
+}
+/**
+ * The keys under one field's filter: its operators and, on a relation, the
+ * target fields one hop reaches, exactly the input fields its filter type
+ * declares, each hop taking operators of its own. A relation the key cannot
+ * read is an id, and its filter has no hop at all, so a hop through it is
+ * refused here without naming the model it points at (REST answers the same
+ * read `unknown_field`).
+ */
+function checkFieldFilter(summary, model, field, operations) {
+    if (!(0, filter_values_1.isObject)(operations))
+        refuseBareValue(field.name, field.filterOps, operations, (ops) => ({ [field.name]: ops }));
+    for (const [key, inner] of Object.entries(operations)) {
+        if (!field.filterOps.includes(key)) {
+            if (field.kind === "id" || field.kind === "idList") {
+                throw new CapaBuildError(`${field.name} on ${model.typeName} is an id here: this key cannot read the model it points at, so a filter cannot reach ${key} through it. Filter ${field.name} by id with ${orList(field.filterOps)}`, [], field.filterOps);
+            }
+            throw new CapaBuildError(`unknown filter ${key} under ${field.name} on ${model.filterType}`, didYouMean(key, field.filterOps), field.filterOps);
+        }
+        if (!isHop(field, key))
+            continue;
+        const hop = modelByNamespace(summary, field.target)?.fields.find((f) => f.name === key);
+        const operators = hop ? hop.filterOps : SYSTEM_HOP_OPERATORS;
+        const wrap = (ops) => ({ [field.name]: { [key]: ops } });
+        if (!(0, filter_values_1.isObject)(inner))
+            refuseBareValue(`${field.name}.${key}`, operators, inner, wrap);
+        for (const op of Object.keys(inner)) {
+            if (!operators.includes(op)) {
+                throw new CapaBuildError(`unknown filter ${op} under ${field.name}.${key} on ${model.filterType}`, didYouMean(op, operators), [...operators]);
+            }
+        }
+    }
+}
+/**
+ * A filter's names, checked through `and`, `or` and `not` before anything is
+ * sent. The system fields it takes are the ones `filterType` declares
+ * (`systemFilters`): `_version`, `_folder`, `model` and `status` are
+ * selectable but never filterable, on REST too.
+ */
+function checkFilter(summary, model, filter) {
+    if (!(0, filter_values_1.isObject)(filter)) {
+        throw new CapaBuildError(`filter must be an object of ${model.filterType}`);
+    }
+    const allowed = filterableNames(model);
+    for (const [key, value] of Object.entries(filter)) {
+        if (key === "and" || key === "or") {
+            for (const part of Array.isArray(value) ? value : [value])
+                checkFilter(summary, model, part);
+            continue;
+        }
+        if (key === "not") {
+            checkFilter(summary, model, value);
+            continue;
+        }
+        if (!allowed.includes(key)) {
+            if (exports.SYSTEM_FIELDS.includes(key)) {
+                throw new CapaBuildError(`${key} cannot be filtered: ${model.filterType} filters the system fields ${andList(systemFilterNames(model))} only`, [], allowed);
+            }
+            throw new CapaBuildError(`unknown filter field ${key} on ${model.filterType}`, didYouMean(key, allowed), allowed);
+        }
+        const field = model.fields.find((f) => f.name === key);
+        const system = model.systemFilters.find((f) => f.name === key);
+        if (field)
+            checkFieldFilter(summary, model, field, value);
+        else if (system && !(0, filter_values_1.isObject)(value))
+            refuseBareValue(key, system.filterOps, value, (ops) => ({ [key]: ops }));
+    }
+    return filter;
+}
+/** Resolve and check a spec. Throws `CapaBuildError`. */
+function planQuery(summary, spec) {
+    if (!spec || typeof spec !== "object")
+        throw new CapaBuildError("a query spec must be an object with model");
+    const model = findModel(summary, spec.model);
+    // An id reads that one entry: it is never dropped into a list of every entry.
+    const mode = spec.mode ?? (spec.id !== undefined ? "single" : "list");
+    if (mode !== "list" && mode !== "single")
+        throw new CapaBuildError(`mode must be list or single, not ${String(mode)}`);
+    if (mode === "list" && spec.id !== undefined) {
+        throw new CapaBuildError('id reads one entry, so it takes mode single: pass mode "single", or leave id out to list entries');
+    }
+    if (mode === "single" && (typeof spec.id !== "string" || spec.id === "")) {
+        throw new CapaBuildError("mode single needs id, the entry's UUID");
+    }
+    if (mode === "single") {
+        for (const key of ["first", "after", "before", "sort", "filter", "totalCount"]) {
+            if (spec[key] !== undefined)
+                throw new CapaBuildError(`${key} applies to mode list only`);
+        }
+    }
+    if (spec.after !== undefined && spec.before !== undefined) {
+        throw new CapaBuildError("after and before page in opposite directions: pass after to read on, or before to read back, not both");
+    }
+    if (spec.after !== undefined && String(spec.after) === exports.END_OF_LIST) {
+        throw new CapaBuildError('after takes an endCursor, and "end" is none: pass before: "end" to read the last entries of the list');
+    }
+    const planned = {
+        model,
+        mode,
+        fields: planFields(summary, model, spec.fields, 0, mode === "single"),
+        totalCount: spec.totalCount === true,
+        operationName: spec.operationName ?? `${model.typeName}${mode === "single" ? "ById" : "List"}`,
+        summary,
+    };
+    if (mode === "single")
+        planned.id = spec.id;
+    if (spec.first !== undefined)
+        planned.first = checkFirst(spec.first, "first");
+    if (spec.after !== undefined)
+        planned.after = String(spec.after);
+    if (spec.before !== undefined)
+        planned.before = String(spec.before);
+    if (spec.sort !== undefined) {
+        // One value may be given alone, as a relation list's sort is.
+        const sort = typeof spec.sort === "string" ? [spec.sort] : spec.sort;
+        if (!Array.isArray(sort) || sort.length === 0 || sort.length > 3) {
+            throw new CapaBuildError(`sort takes 1 to 3 values of ${model.sortType}`, [], model.sortValues);
+        }
+        planned.sort = sort.map((value) => checkSort(value, model, "sort"));
+    }
+    if (spec.filter !== undefined)
+        planned.filter = (0, filter_values_1.typedFilter)(summary, model, checkFilter(summary, model, spec.filter));
+    return planned;
+}