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

package/dist/next/graphql/rest.js

@@ -0,0 +1,502 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.restWhere = restWhere;
+exports.specToSelect = specToSelect;
+exports.selectToGraphQL = selectToGraphQL;
+/**
+ * rest.ts — the same read as a REST request, and back.
+ *
+ * `/api/graphql` runs every root field as the equivalent `/api/entries`
+ * request (G plan D2), so a query spec has exactly one REST twin. These two
+ * helpers write it down in each direction, so `select` and GraphQL stay
+ * interchangeable in code: `specToSelect` for "show me the REST URL of this
+ * query" (public as `graphqlToSelect`, which also takes a builder selection),
+ * `selectToGraphQL` for "port this REST read to GraphQL".
+ *
+ * Names cross the boundary through the schema summary, because GraphQL and
+ * REST name a few things differently: a field renamed by N5 (`tags_field`,
+ * `price_usd`), a relation hop (`author__name_ASC` against `author.name`), the
+ * system fields the schema prefixes with `_`, a system key a field of the
+ * model shadows, which REST writes with `$` (`$tags`, `$createdAt`,
+ * `author.$id`), and a namespace holding a character REST's grammars use,
+ * which REST writes quoted (`"price.usd"`, field-names.ts).
+ */
+const plan_1 = require("./plan");
+const filter_values_1 = require("./filter-values");
+const system_keys_1 = require("../system-keys");
+const field_names_1 = require("../field-names");
+/**
+ * The system fields a REST `select` can name, in the order the API prints
+ * them, with their REST keys. `id`, `model` and `status` are not here: REST
+ * returns them whatever a select says, so the API never writes them.
+ */
+const REST_SYSTEM_SELECT = [
+    ["createdAt", "createdAt"],
+    ["updatedAt", "updatedAt"],
+    ["publishedAt", "publishedAt"],
+    ["_version", "version"],
+    ["_folder", "folder"],
+    ["_tags", "tags"],
+];
+/** REST system keys to GraphQL field names, where the two differ. */
+const GRAPHQL_SYSTEM_NAME = { version: "_version", folder: "_folder", tags: "_tags" };
+/** GraphQL system field names to REST system keys, where the two differ. */
+const REST_SYSTEM_KEY = Object.fromEntries(Object.entries(GRAPHQL_SYSTEM_NAME).map(([restKey, graphqlName]) => [graphqlName, restKey]));
+/** Operators a relation filter input carries beside its hop fields (N10). */
+const RELATION_OPERATORS = new Set(["eq", "ne", "in", "nin", "exists", "null", "has", "hasAny", "hasAll"]);
+/**
+ * Field kinds whose filter is the field's own operators plus dotted paths
+ * below it: a relation's hops, a media value's `id`. A relation the key cannot
+ * read is one too, so anything but its operators prints as the dotted path
+ * REST documents (`secret.code`), never as a nested object.
+ */
+const HOP_KINDS = new Set(["relation", "relationList", "id", "idList", "media"]);
+/** Every filter operator, in the order the API's filter input types declare them. */
+const OPERATOR_ORDER = [
+    "eq", "ne", "lt", "lte", "gt", "gte", "in", "nin", "contains", "startsWith", "endsWith",
+    "has", "hasAny", "hasAll", "exists", "null", "id",
+];
+/** Encoded as the API prints a twin: commas, colons and a system key's `$` stay readable. */
+function encode(value) {
+    return encodeURIComponent(value).replace(/%2C/g, ",").replace(/%3A/g, ":").replace(/%24/g, "$");
+}
+function fieldByName(model, name) {
+    return model.fields.find((f) => f.name === name);
+}
+function fieldByNamespace(model, namespace) {
+    return model.fields.find((f) => f.namespace === namespace);
+}
+/**
+ * Whether a field of `model` takes the REST name `namespace`: one GraphQL
+ * exposes, or one N5 left out (the type description's `Not exposed:` line),
+ * which REST still reads by that name.
+ */
+function hasField(model, namespace) {
+    return fieldByNamespace(model, namespace) !== undefined || model.notExposed.includes(namespace);
+}
+/**
+ * A system key as REST writes it on `model`: `$tags` where a field is called
+ * `tags`, plain `tags` wherever no field takes the name, as the API writes it.
+ */
+function systemKeyName(model, key) {
+    return hasField(model, key) ? `${system_keys_1.SYSTEM_KEY_SIGIL}${key}` : key;
+}
+/** The system key a REST name spells: `$tags` always, `tags` only where no field takes the name. */
+function restSystemKey(model, name) {
+    if (name.startsWith(system_keys_1.SYSTEM_KEY_SIGIL))
+        return (0, system_keys_1.sigilSystemKey)(name);
+    return (0, system_keys_1.isSystemKey)(name) && !hasField(model, name) ? name : null;
+}
+/** A REST name for a field GraphQL leaves out has no GraphQL twin: say so, rather than read it as the system field. */
+function refuseNotExposed(model, name) {
+    if (!model.notExposed.includes(name))
+        return;
+    throw new plan_1.CapaBuildError(`${name} on ${model.typeName} is a field GraphQL does not expose, because its name collides with another field's; ` +
+        `read it over REST${(0, system_keys_1.isSystemKey)(name) ? `, and write the system key as ${system_keys_1.SYSTEM_KEY_SIGIL}${name}` : ""}`);
+}
+function targetOf(summary, field) {
+    return summary.models.find((m) => m.namespace === field.target);
+}
+/** `keys` in `order` first, then the rest as they came. */
+function ordered(keys, order) {
+    const rank = (key) => {
+        const at = order.indexOf(key);
+        return at === -1 ? order.length : at;
+    };
+    return keys.map((key, i) => ({ key, i })).sort((a, b) => rank(a.key) - rank(b.key) || a.i - b.i).map((k) => k.key);
+}
+// ------------------------------------------------------ GraphQL to REST ---
+function restSort(summary, model, value) {
+    const match = /^(.*)_(ASC|DESC)$/.exec(value);
+    if (!match)
+        throw new plan_1.CapaBuildError(`sort ${value} is not a value of ${model.sortType}`);
+    const [relationName, targetName] = match[1].split("__");
+    const direction = match[2] === "DESC" ? "-" : "";
+    const field = fieldByName(model, relationName);
+    if (targetName === undefined)
+        return `${direction}${field ? (0, field_names_1.writeName)(field.namespace) : systemKeyName(model, relationName)}`;
+    const target = field ? targetOf(summary, field) : undefined;
+    const targetField = target ? fieldByName(target, targetName) : undefined;
+    return `${direction}${(0, field_names_1.writePath)([field?.namespace ?? relationName, targetField?.namespace ?? targetName])}`;
+}
+/**
+ * One level of a REST `select`, written as the API writes the twin in
+ * `extensions.capa.rest`: system keys first in the API's order, then fields in
+ * the order selected, each namespace bare or quoted as REST writes it, an
+ * expanded relation always with parentheses, a level that selects nothing else
+ * as `id` (`$id` beside a field called id). A system key whose REST name a
+ * field of the model shadows is written `$tags`, so the twin returns what
+ * GraphQL did.
+ */
+function restSelectText(summary, model, fields) {
+    const system = new Set(fields.filter((f) => !f.field).map((f) => f.name));
+    const items = [];
+    for (const [graphqlName, restKey] of REST_SYSTEM_SELECT) {
+        if (system.has(graphqlName))
+            items.push(systemKeyName(model, restKey));
+    }
+    for (const planned of fields) {
+        if (!planned.field)
+            continue;
+        const namespace = (0, field_names_1.writeName)(planned.field.namespace);
+        if (!planned.target || !planned.children) {
+            items.push(namespace);
+            continue;
+        }
+        const args = [restSelectText(summary, planned.target, planned.children)];
+        if (planned.field.kind === "relationList") {
+            // A written `first` is written, 100 included: REST's node bound counts an
+            // unwritten limit as 10 and a written one in full (spec 17, amendment 76).
+            if (planned.first !== undefined)
+                args.push(`limit:${planned.first}`);
+            if (planned.sort !== undefined)
+                args.push(`sort:${restSort(summary, planned.target, planned.sort)}`);
+            if (planned.after !== undefined)
+                args.push(`after:${planned.after}`);
+        }
+        items.push(`${namespace}(${args.join(",")})`);
+    }
+    return items.length ? items.join(",") : systemKeyName(model, "id");
+}
+/** An operator object without its null members, in the API's operator order; null when empty. */
+function restOperations(value, order = OPERATOR_ORDER) {
+    if (!(0, filter_values_1.isObject)(value))
+        return null;
+    const out = {};
+    for (const key of ordered(Object.keys(value), order)) {
+        if (value[key] !== null && value[key] !== undefined)
+            out[key] = value[key];
+    }
+    return Object.keys(out).length ? out : null;
+}
+/**
+ * A GraphQL filter input as the REST `where` object, key for key what the API
+ * prints in `extensions.capa.rest`: namespaces for field names, written as
+ * REST writes them, a hop as a dotted path after the relation's own
+ * operators, keys in the order the
+ * filter input type declares them, and null members dropped (GraphQL reads a
+ * null as "no condition").
+ */
+function restWhere(summary, model, filter) {
+    const where = {};
+    const order = ["and", "or", "not", ...model.systemFilters.map((system) => system.name), ...model.fields.map((f) => f.name)];
+    for (const key of ordered(Object.keys(filter), order)) {
+        const value = filter[key];
+        if (value === null || value === undefined)
+            continue;
+        if (key === "and" || key === "or") {
+            where[key] = (Array.isArray(value) ? value : [value]).map((part) => restWhere(summary, model, part));
+            continue;
+        }
+        if (key === "not") {
+            const inner = restWhere(summary, model, value);
+            if (Object.keys(inner).length)
+                where.not = inner;
+            continue;
+        }
+        const field = fieldByName(model, key);
+        if (!field) {
+            // A system field: `_tags` is REST's `tags`, or `$tags` beside a field called tags (amendment 56).
+            const system = model.systemFilters.find((f) => f.name === key);
+            const operations = restOperations(value, system?.filterOps.length ? system.filterOps : OPERATOR_ORDER);
+            if (operations)
+                where[systemKeyName(model, REST_SYSTEM_KEY[key] ?? key)] = operations;
+            continue;
+        }
+        const operations = restOperations(value, field.filterOps.length ? field.filterOps : OPERATOR_ORDER);
+        if (!operations)
+            continue;
+        const written = (0, field_names_1.writeName)(field.namespace);
+        if (!HOP_KINDS.has(field.kind)) {
+            where[written] = operations;
+            continue;
+        }
+        const target = targetOf(summary, field);
+        const own = {};
+        const hops = [];
+        for (const [name, inner] of Object.entries(operations)) {
+            if (field.kind === "media" && name === "id") {
+                hops.push([`${written}.id`, { eq: inner }]);
+            }
+            else if (field.kind === "media" || RELATION_OPERATORS.has(name)) {
+                own[name] = inner;
+            }
+            else {
+                const hop = restOperations(inner);
+                const hopField = target ? fieldByName(target, name) : undefined;
+                const segment = hopField?.namespace ?? (target ? systemKeyName(target, name) : name);
+                if (hop)
+                    hops.push([`${written}.${(0, field_names_1.writePathSegment)(segment)}`, hop]);
+            }
+        }
+        if (Object.keys(own).length)
+            where[written] = own;
+        for (const [path, hop] of hops)
+            where[path] = hop;
+    }
+    return where;
+}
+/**
+ * The REST request a query spec is equal to, written the way the API writes
+ * it in `extensions.capa.rest`: the filter as `where` JSON, the root's default
+ * page size left out, a relation list's `first` written as `limit:` whenever
+ * the spec gives it, parameters in the API's order. Public as
+ * `graphqlToSelect`, in selection.ts.
+ */
+function specToSelect(summary, spec) {
+    const plan = (0, plan_1.planQuery)(summary, spec);
+    return restRequestFor(plan);
+}
+/** `specToSelect` for a plan already checked. */
+function restRequestFor(plan) {
+    const { model, summary } = plan;
+    const select = restSelectText(summary, model, plan.fields);
+    const params = [["select", select]];
+    if (plan.filter) {
+        const where = restWhere(summary, model, plan.filter);
+        if (Object.keys(where).length)
+            params.push(["where", JSON.stringify(where)]);
+    }
+    if (plan.sort)
+        params.push(["sort", plan.sort.map((value) => restSort(summary, model, value)).join(",")]);
+    if (plan.first !== undefined && plan.first !== plan_1.LIST_DEFAULT)
+        params.push(["limit", String(plan.first)]);
+    if (plan.after !== undefined)
+        params.push(["after", plan.after]);
+    if (plan.before !== undefined)
+        params.push(["before", plan.before]);
+    if (plan.totalCount)
+        params.push(["count", "true"]);
+    const path = plan.mode === "single"
+        ? `/api/entries/${encodeURIComponent(model.namespace)}/${encodeURIComponent(plan.id)}`
+        : `/api/entries/${encodeURIComponent(model.namespace)}`;
+    const url = `${path}?${params.map(([key, value]) => `${key}=${encode(value)}`).join("&")}`;
+    return { path, select, params, url };
+}
+// ------------------------------------------------------ REST to GraphQL ---
+/** Split on the commas outside quoted names and parentheses. */
+function splitTopLevel(text) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (char === field_names_1.NAME_QUOTE) {
+            const quoted = (0, field_names_1.readQuoted)(text, i);
+            if (!quoted)
+                throw new plan_1.CapaBuildError(`select has an unclosed quote: ${text}`);
+            i = quoted.end - 1;
+            continue;
+        }
+        if (char === "(")
+            depth++;
+        else if (char === ")")
+            depth--;
+        else if (char === "," && depth === 0) {
+            parts.push(text.slice(start, i));
+            start = i + 1;
+        }
+        if (depth < 0)
+            throw new plan_1.CapaBuildError(`select has an unmatched ")": ${text}`);
+    }
+    if (depth !== 0)
+        throw new plan_1.CapaBuildError(`select has an unclosed "(": ${text}`);
+    parts.push(text.slice(start));
+    return parts.map((part) => part.trim()).filter(Boolean);
+}
+/** A sort or filter path read back, at most a field and one hop; `what` names it in a refusal. */
+function restPath(text, what) {
+    const path = (0, field_names_1.readPath)(text);
+    if (!path)
+        throw new plan_1.CapaBuildError(`${what} ${text} has a quote that does not close its name`);
+    if (path.length > 2)
+        throw new plan_1.CapaBuildError(`${what} ${text} goes more than one relation deep, which REST does not read`);
+    return path;
+}
+function graphqlSort(summary, model, raw) {
+    const direction = raw.startsWith("-") ? "DESC" : "ASC";
+    const [relation, hop] = restPath(raw.replace(/^-/, ""), "sort");
+    if (hop === undefined)
+        return `${graphqlFieldName(model, relation)}_${direction}`;
+    const field = fieldByNamespace(model, relation.name);
+    const name = field?.name ?? relation.name;
+    const target = field ? targetOf(summary, field) : undefined;
+    const targetName = target ? graphqlFieldName(target, hop) : hop.name;
+    return `${name}__${targetName}_${direction}`;
+}
+/**
+ * A REST name on `model` as its GraphQL field: `$tags` and an unshadowed
+ * `tags` are `_tags`. A quoted name is always a field, as the API reads it.
+ */
+function graphqlFieldName(model, { name, quoted }) {
+    const system = quoted ? null : restSystemKey(model, name);
+    if (system !== null)
+        return GRAPHQL_SYSTEM_NAME[system] ?? system;
+    refuseNotExposed(model, name);
+    return fieldByNamespace(model, name)?.name ?? name;
+}
+/**
+ * A select item's name, read back, and what follows it: `"at.place"(name)` is
+ * `at.place` then `(name)`, `title` is `title` then nothing.
+ */
+function selectItem(item) {
+    let name;
+    let rest;
+    if (item.startsWith(field_names_1.NAME_QUOTE)) {
+        const quoted = (0, field_names_1.readQuoted)(item, 0); // splitTopLevel refused a quote that does not close
+        name = { name: quoted.name, quoted: true };
+        rest = item.slice(quoted.end);
+    }
+    else {
+        const open = item.indexOf("(");
+        name = { name: open === -1 ? item : item.slice(0, open), quoted: false };
+        rest = open === -1 ? "" : item.slice(open);
+    }
+    if (rest === "")
+        return { name, args: null };
+    if (!rest.startsWith("(") || !rest.endsWith(")")) {
+        throw new plan_1.CapaBuildError(`select item ${item} is not a field name, or a relation with its fields in parentheses`);
+    }
+    return { name, args: rest.slice(1, -1) };
+}
+/**
+ * A field a REST read returns, as a spec item. A media value is read with all
+ * six of its fields, the one public media shape REST returns (spec 17,
+ * amendment 31): the builder's `id url alt` default is for a query written
+ * without fields, never for the twin of a REST read.
+ */
+function restFieldSpec(field, name) {
+    return field?.kind === "media" ? { field: name, fields: [...plan_1.MEDIA_FIELDS] } : name;
+}
+/**
+ * REST's `*`, and a read with no select, as fields: everything that read
+ * returns. The system keys REST prints beside `id`, `model` and `status`
+ * (`createdAt` to `tags`, as GraphQL names them), then every field,
+ * deprecated ones included. A relation list REST returns as references, a
+ * page of `{ id, model }` items; GraphQL reads it as a connection, so it is
+ * selected as one with `nodes { id }`, the same page of ids. The builder's
+ * own default, for a query written without fields, stays shorter.
+ */
+function restStarFields(model) {
+    const system = REST_SYSTEM_SELECT.map(([graphqlName]) => graphqlName);
+    const fields = model.fields.map((f) => (f.kind === "relationList" ? { field: f.name, fields: ["id"] } : restFieldSpec(f, f.name)));
+    return [...system, ...fields];
+}
+function specFields(summary, model, select) {
+    const items = splitTopLevel(select);
+    const fields = [];
+    const add = (spec) => {
+        const name = typeof spec === "string" ? spec : spec.field;
+        const at = fields.findIndex((f) => (typeof f === "string" ? f : f.field) === name);
+        if (at === -1)
+            fields.push(spec);
+        else if (typeof spec !== "string")
+            fields[at] = spec;
+    };
+    for (const item of items) {
+        if (item === "*") {
+            restStarFields(model).forEach(add);
+            continue;
+        }
+        const { name: itemName, args } = selectItem(item);
+        if (args === null) {
+            const name = graphqlFieldName(model, itemName);
+            add(restFieldSpec(fieldByName(model, name), name));
+            continue;
+        }
+        const field = fieldByNamespace(model, itemName.name);
+        const target = field ? targetOf(summary, field) : undefined;
+        if (!field || !target) {
+            throw new plan_1.CapaBuildError(`${itemName.name} on ${model.typeName} is not a relation this key can expand`);
+        }
+        const spec = { field: field.name };
+        const inner = [];
+        for (const arg of splitTopLevel(args)) {
+            if (arg.startsWith("limit:"))
+                spec.first = Number(arg.slice(6));
+            else if (arg.startsWith("sort:"))
+                spec.sort = graphqlSort(summary, target, arg.slice(5));
+            else if (arg.startsWith("after:"))
+                spec.after = arg.slice(6);
+            else
+                inner.push(arg);
+        }
+        spec.fields = specFields(summary, target, inner.join(",") || "*");
+        add(spec);
+    }
+    return fields;
+}
+/**
+ * REST reads filter values loosely (a query string is all text, and a list
+ * operand may be comma-separated), so each is converted to the type its
+ * GraphQL filter input declares (filter-values.ts).
+ */
+const REST_TEXT = { listText: true };
+function graphqlFilter(summary, model, where) {
+    const filter = {};
+    const merge = (key, value) => {
+        filter[key] = { ...(filter[key] ?? {}), ...value };
+    };
+    for (const [path, value] of Object.entries(where)) {
+        if (path === "and" || path === "or") {
+            filter[path] = value.map((part) => graphqlFilter(summary, model, part));
+            continue;
+        }
+        if (path === "not") {
+            filter.not = graphqlFilter(summary, model, value);
+            continue;
+        }
+        const operations = (value && typeof value === "object" ? value : { eq: value });
+        const [head, hop] = restPath(path, "where key");
+        const system = head.quoted ? null : restSystemKey(model, head.name);
+        if (system === null)
+            refuseNotExposed(model, head.name);
+        const field = system === null ? fieldByNamespace(model, head.name) : undefined;
+        const name = field?.name ?? graphqlFieldName(model, head);
+        if (hop === undefined) {
+            const operands = field ? field.filterInputs ?? {} : model.systemFilters.find((f) => f.name === name)?.filterInputs ?? filter_values_1.SYSTEM_OPERANDS;
+            merge(name, (0, filter_values_1.typedOperations)(operations, operands, REST_TEXT));
+        }
+        else if (field?.kind === "media" && !hop.quoted && hop.name === "id") {
+            merge(name, { id: (0, filter_values_1.toScalar)("ID", operations.eq) });
+        }
+        else {
+            const target = field ? targetOf(summary, field) : undefined;
+            const hopName = target ? graphqlFieldName(target, hop) : hop.name;
+            const hopField = target ? fieldByName(target, hopName) : undefined;
+            const operands = hopField?.filterInputs ?? (hopName === "id" ? filter_values_1.SYSTEM_OPERANDS : {});
+            merge(name, { [hopName]: (0, filter_values_1.typedOperations)(operations, operands, REST_TEXT) });
+        }
+    }
+    return filter;
+}
+/**
+ * The query spec a REST read is equal to. Pass it to `buildGraphQLQuery`.
+ *
+ *   selectToGraphQL(schema, "articles", "title,author(name)", { sort: ["-views"], limit: 5 })
+ *   // { model: "articles", fields: ["title", { field: "author", fields: ["name"] }], sort: ["views_DESC"], first: 5 }
+ */
+function selectToGraphQL(summary, namespace, select, options = {}) {
+    const model = (0, plan_1.findModel)(summary, namespace);
+    const spec = { model: model.namespace };
+    if (options.id !== undefined) {
+        spec.mode = "single";
+        spec.id = options.id;
+    }
+    spec.fields = specFields(summary, model, select ?? "*");
+    const where = { ...(options.filter ?? {}), ...(options.where ?? {}) };
+    if (Object.keys(where).length)
+        spec.filter = graphqlFilter(summary, model, where);
+    if (options.sort?.length)
+        spec.sort = options.sort.map((raw) => graphqlSort(summary, model, raw));
+    if (options.limit !== undefined)
+        spec.first = options.limit;
+    if (options.count)
+        spec.totalCount = true;
+    if (options.after !== undefined)
+        spec.after = options.after;
+    if (options.before !== undefined)
+        spec.before = options.before;
+    (0, plan_1.planQuery)(summary, spec);
+    return spec;
+}

package/dist/next/graphql/selection.d.ts

@@ -0,0 +1,55 @@
+/**
+ * selection.ts — a REST read as a typed-builder selection, and back.
+ *
+ * The SDK writes a read three ways: a REST `select` (`entries.list`), the
+ * tool spec (`{ model, fields, first, sort, filter }`, which
+ * `buildGraphQLQuery` prints and the Explorer and MCP builders share), and the
+ * typed builder's selection (`{ articles: { args, nodes: { ... } } }`, which
+ * `client.graphql.query` runs and `toTree` reads). `selectToGraphQL` writes a
+ * REST read as the tool spec and `selectToSelection` as a selection;
+ * `graphqlToSelect` takes either back to REST (G brief, npm item 4). Each goes
+ * through the tool spec, which checks every name.
+ *
+ * A selection written here names what `toTree` needs to answer exactly what
+ * REST answers: `id`, `model` and `status` on every entry, `pageInfo {
+ * hasNextPage endCursor }` on every relation list, and every media field REST
+ * returns.
+ */
+import { type GraphQLQuerySpec } from "./plan";
+import { type RestReadOptions, type RestRequest } from "./rest";
+import type { GraphQLSchemaSummary } from "./summary";
+import { type RuntimeSelection } from "./typed";
+/**
+ * The typed-builder selection a REST read is equal to. `client.graphql.query`
+ * runs it, and `toTree` turns its result into the REST `data`:
+ *
+ *   const schema = await capa.graphqlSchema();
+ *   const selection = selectToSelection(schema, "articles", "title,author(name)", { sort: ["-views"], limit: 5 });
+ *   const { data } = await capa.graphql.query(selection);
+ *   const { articles } = toTree(data, selection, schema);
+ *   // deep-equal to (await capa.entries.list("articles", { select: "title,author(name)", sort: ["-views"], limit: 5 })).data
+ *
+ * It takes what `selectToGraphQL` takes and refuses what it refuses, with
+ * `CapaBuildError`. Built at run time, its result is untyped.
+ */
+export declare function selectToSelection(summary: GraphQLSchemaSummary, namespace: string, select?: string, options?: RestReadOptions): RuntimeSelection;
+/**
+ * The REST request a read is equal to, written the way the API writes it in
+ * `extensions.capa.rest`. It takes the read either way the SDK writes one:
+ * the tool spec `selectToGraphQL` returns, or a typed-builder selection, the
+ * one `client.graphql.query` runs.
+ *
+ *   graphqlToSelect(schema, { model: "articles", fields: ["title", { field: "author", fields: ["name"] }] }).url
+ *   graphqlToSelect(schema, { articles: { nodes: { title: true, author: { name: true } } } }).url
+ *   // both "/api/entries/articles?select=title,author(name)"
+ *
+ * A read REST cannot make throws `CapaBuildError`: a name the schema does not
+ * have, and for a selection another root field (`version`, `entry`), more
+ * than one root field, or a relation list read from a cursor in a list read.
+ * `last` with no `before`, or with `before: null`, is REST's `before=end`.
+ */
+export declare function graphqlToSelect(summary: GraphQLSchemaSummary, spec: GraphQLQuerySpec): RestRequest;
+export declare function graphqlToSelect(summary: GraphQLSchemaSummary, selection: {
+    readonly model?: never;
+    readonly [rootField: string]: unknown;
+}): RestRequest;