@capacms/sdk 1.0.0-next.4 → 1.0.0-next.6

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

@@ -0,0 +1,171 @@
+import type { Entry } from "../client";
+import type { CapaTreeLayout } from "./tree-layout";
+import type { AliasFor, AliasKeys, Base, FieldResult, Flatten, IsUntyped, Nullable, Returns, RuntimeSelection, TreeLayout, treeLayout, UntypedQuery } from "./typed";
+/** One model root field of an untyped builder result, in REST's shape. */
+export type TreeRoot = Entry[] | Entry | null;
+/** GraphQL's system fields, and each one's key on a REST entry. */
+type SystemField = "id" | "model" | "status" | "createdAt" | "updatedAt" | "publishedAt" | "_version" | "_folder" | "_tags";
+type RestSystemKey<K> = K extends "_version" ? "version" : K extends "_folder" ? "folder" : K extends "_tags" ? "tags" : K;
+/** The layout codegen wrote on model type `T`; `never` for any other object (media, a connection). */
+type LayoutOf<T> = typeof treeLayout extends keyof T ? Extract<T[typeof treeLayout], TreeLayout> : never;
+type IsModel<T> = [LayoutOf<T>] extends [never] ? false : true;
+type FieldsOf<T> = LayoutOf<T> extends {
+    fields: infer F;
+} ? F : never;
+type NamespaceOf<T, K> = K extends keyof FieldsOf<T> ? Extract<FieldsOf<T>[K], string> : K;
+/** Keys a selection level always selects (`true` or an object), and those selected with a `boolean`. */
+type Always<S> = {
+    [K in keyof S]-?: [S[K]] extends [false | undefined] ? never : boolean extends S[K] ? never : K;
+}[keyof S];
+type Maybe<S> = {
+    [K in keyof S]-?: boolean extends S[K] ? K : never;
+}[keyof S];
+/** The entries of a connection selection: `nodes`, or `edges { node }`. */
+type EntrySelection<S> = S extends {
+    nodes: infer N;
+} ? N : S extends {
+    edges: {
+        node: infer N;
+    };
+} ? N : never;
+/** A relation GraphQL types as an id, as REST writes it unexpanded. */
+type RelationId = {
+    id: string;
+    model: string | null;
+};
+type IdTree<R> = Nullable<R> extends true ? IdTree<NonNullable<R>> | null : R extends ReadonlyArray<unknown> ? {
+    items: RelationId[];
+    pageInfo: {
+        hasNext: boolean;
+        next: string | null;
+    };
+} : RelationId;
+/** A relation list as REST writes it expanded; `pageInfo` only when the selection asks for it. */
+type RelationListTree<E, S> = Flatten<{
+    items: Array<TreeEntry<E, EntrySelection<S>>>;
+} & (S extends {
+    pageInfo: {
+        hasNextPage: true;
+    };
+} ? {
+    pageInfo: {
+        limit: number;
+        hasNext: boolean;
+        next: string | null;
+    };
+} : {})>;
+/** One customer field's value in REST's shape, for its GraphQL type `R` and its selection `S`. */
+type FieldTree<R, S> = unknown extends R ? R : Nullable<R> extends true ? FieldTree<NonNullable<R>, S> | null : R extends ReadonlyArray<infer E> ? Array<FieldTree<E, S>> : IsModel<R> extends true ? TreeEntry<R, S> : R extends {
+    nodes: ReadonlyArray<infer E>;
+} ? RelationListTree<E, S> : FieldResult<R, S>;
+type CustomerField<T> = Extract<keyof FieldsOf<T>, keyof T>;
+type ValueOf<T, K extends keyof T, S> = K extends LayoutOf<T>["ids"] ? IdTree<Returns<T[K]>> : FieldTree<Returns<T[K]>, S>;
+/**
+ * One entry of model type `T` for selection `S`, as REST returns it: `model`
+ * always, the system fields selected beside `fields` (`_version` as
+ * `version`), every customer field selected under `fields` by its namespace.
+ */
+export type TreeEntry<T, S> = Flatten<{
+    model: string;
+} & {
+    [K in Always<S> & Exclude<SystemField, "model"> & keyof T as RestSystemKey<K>]: FieldResult<Returns<T[K]>, true>;
+} & {
+    [K in Maybe<S> & Exclude<SystemField, "model"> & keyof T as RestSystemKey<K>]?: FieldResult<Returns<T[K]>, true>;
+} & {
+    fields: Flatten<{
+        [K in Always<S> & CustomerField<T> as NamespaceOf<T, K>]: ValueOf<T, K, S[K & keyof S]>;
+    } & {
+        [K in Maybe<S> & CustomerField<T> as NamespaceOf<T, K>]?: ValueOf<T, K, true>;
+    }>;
+}>;
+/** A root field in REST's shape: a list root as its entries, a single root as its entry, `null` where the root failed. */
+type RootTree<R, S> = NonNullable<R> extends {
+    nodes: ReadonlyArray<infer E>;
+} ? Array<TreeEntry<E, EntrySelection<S>>> | null : TreeEntry<NonNullable<R>, S> | null;
+/**
+ * A builder result in REST's shape: each model root field as its REST `data`.
+ * With a schema typed by `CapaQuery`, a list root is an array of entries and a
+ * single root an entry or `null`, each typed from the selection; untyped, each
+ * root is a `TreeRoot`.
+ */
+export type TreeData<S, Q = UntypedQuery> = S extends RuntimeSelection ? {
+    [rootField: string]: TreeRoot;
+} : IsUntyped<Q> extends true ? {
+    [K in Exclude<keyof S, "args">]: TreeRoot;
+} : Flatten<{
+    [K in Always<S> & keyof Q]: RootTree<Returns<Q[K]>, S[K]>;
+} & {
+    [K in AliasKeys<S, Q>]: RootTree<Returns<Q[Extract<AliasFor<S[K]>, keyof Q>]>, S[K]>;
+}>;
+/**
+ * What `toTree` needs selected to return what REST returns, on top of the
+ * selection itself: `id` and `status` on every entry, which only GraphQL knows.
+ * `model` comes from the layout, and a relation list's `pageInfo` is
+ * left out of the tree when it is not selected. A root may be an alias; an
+ * alias below a root may not, since REST reads each field once.
+ */
+export type TreeSelection<S, Q> = S extends RuntimeSelection ? unknown : IsUntyped<Q> extends true ? unknown : {
+    [K in keyof S & keyof Q]: RootNeeds<Returns<Q[K]>, S[K]>;
+} & {
+    [K in AliasKeys<S, Q>]: RootNeeds<Returns<Q[Extract<AliasFor<S[K]>, keyof Q>]>, S[K]>;
+};
+type RootNeeds<R, S> = NonNullable<R> extends {
+    nodes: ReadonlyArray<infer E>;
+} ? ConnectionNeeds<E, S> : EntryNeeds<NonNullable<R>, S>;
+type ConnectionNeeds<E, S> = S extends {
+    edges: {
+        node: infer N;
+    };
+} ? S extends {
+    nodes: unknown;
+} ? {
+    nodes: EntryNeeds<E, EntrySelection<S>>;
+} : {
+    edges: {
+        node: EntryNeeds<E, N>;
+    };
+} : {
+    nodes: EntryNeeds<E, EntrySelection<S>>;
+};
+type EntryNeeds<T, S> = {
+    id: true;
+    status: true;
+} & {
+    [K in keyof S & CustomerField<T>]: FieldNeeds<Base<Returns<T[K]>>, S[K]>;
+} & {
+    [K in AliasKeys<S, T>]: never;
+};
+type FieldNeeds<B, S> = IsModel<B> extends true ? EntryNeeds<B, S> : B extends {
+    nodes: ReadonlyArray<infer E>;
+} ? ConnectionNeeds<E, S> : unknown;
+/**
+ * A `client.graphql.query()` result in the shape `/api/entries` answers with:
+ * each model root field as its REST `data`, a list root as its entries, a
+ * single root as its entry, and `null` for a root that failed (its error is in
+ * the GraphQL result's `errors`).
+ *
+ *   import { capaTreeLayout } from "./capa-graphql"; // written by capa-codegen --graphql
+ *   const selection = { articles: { args: { first: 5 }, nodes: { id: true, status: true, title: true } } } as const;
+ *   const { data } = await capa.graphql.query(selection);
+ *   const { articles } = toTree(data, selection, capaTreeLayout);
+ *   articles?.map((entry) => entry.fields.title); // string | null, as REST's entries.list
+ *   // deep-equal to (await capa.entries.list("articles", { select: "title", limit: 5 })).data
+ *
+ * Without codegen, pass the key's schema instead: `await capa.graphqlSchema()`,
+ * one introspection request. Either carries the types (`capaTreeLayout`
+ * always, a schema when the client is typed by `CapaQuery`): the result is
+ * typed from the selection, and the selection must name `id` and `status` on
+ * every entry, which REST always returns. Each entry's `model` comes from the
+ * layout. A selection from `selectToSelection` names all of that itself, and
+ * its tree is untyped, as its fields are known only at run time.
+ *
+ * A root field may be an alias (`latest: { __aliasFor: "articles", ... }`),
+ * and becomes the REST data of the field it names, under its own key. An
+ * alias below a root field throws a `TypeError`: REST reads each field once.
+ *
+ * Only model root fields convert; `version`, `me` and `entry` throw a
+ * `TypeError`, since REST has no entry list for them. Page through a list
+ * with the GraphQL result's own `pageInfo`.
+ */
+export declare function toTree<S extends object, Q = UntypedQuery>(data: unknown, selection: S & TreeSelection<S, Q>, schema: CapaTreeLayout<Q>): TreeData<S, Q>;
+export {};

package/dist/next/graphql/tree.js

@@ -0,0 +1,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toTree = toTree;
+/**
+ * tree.ts — a typed builder result in the shape `/api/entries` answers with.
+ *
+ * `client.graphql.query()` returns GraphQL's shape, because that is what its
+ * types describe: `articles.nodes[0].author.name`, exactly the selection. Code
+ * written against REST reads entries instead: `data[0].fields.author.fields.name`,
+ * system keys beside `fields`, an array relation as `{ items, pageInfo }`.
+ * `toTree` moves a builder result into that shape, so the two surfaces stay
+ * interchangeable (G brief, npm item 4).
+ *
+ * It follows the SELECTION, not the data: the selection says which object is
+ * an entry, which is a connection and what `first` a relation list asked for,
+ * and the schema's layout says which GraphQL name is which namespace (a field
+ * N5 renamed, such as `hero_image` for `hero-image`, goes back under its
+ * namespace) and which relations GraphQL types as ids, because the key cannot
+ * read their model: those are REST's unexpanded relation, `{ id, model }`, a
+ * list of them `{ items, pageInfo }`. The layout is codegen's `capaTreeLayout`,
+ * or a schema summary read with `capa.graphqlSchema()` (tree-layout.ts). The
+ * input is never modified.
+ *
+ * An entry read in edit mode keeps its mark, so `capaAttrs(entry, namespace)`
+ * tags the tree as it tags a REST entry.
+ *
+ * The types follow the same two: with `capaTreeLayout`, or a schema read by a
+ * client typed with codegen's `CapaQuery`, the result is typed from the
+ * selection, keyed by namespace from the `TreeLayout` codegen writes on each
+ * model type.
+ *
+ * Every entry carries its `model`, from the layout, selected or not: the
+ * layout knows which model each object of the selection is. A relation
+ * list carries `pageInfo` when the selection asks for `pageInfo { hasNextPage
+ * endCursor }`, and is `{ items }` alone when it does not, since only GraphQL
+ * knows whether there is a next page.
+ *
+ * The result is deep-equal to the REST `shape=tree` `data` for the same read,
+ * given the selection names the rest of what REST always returns (`id` and
+ * `status`), `pageInfo` on each relation list, and every media field REST
+ * returns (`id url alt type width height`, the one public media shape of a
+ * single media field and of each item of a list). Where the two surfaces
+ * differ by design, the tree keeps GraphQL's value, because GraphQL does not
+ * say what REST says in these places:
+ *   - a missing single relation (deleted, a draft the key cannot see) is
+ *     `null` (REST: `{ id, model, missing: true }`);
+ *   - a missing item of a relation list is left out, so `items` is shorter
+ *     (REST keeps its slot as `{ id, model, missing: true }`);
+ *   - a value that does not fit its type is `null` (REST: the raw value).
+ */
+const attrs_1 = require("../attrs");
+const plan_1 = require("./plan");
+const typed_1 = require("./typed");
+/**
+ * GraphQL's system fields and their REST keys, in the order REST prints them.
+ * An entry REST returns names its system keys plainly even on a model with a
+ * field of the same name, since that field sits under `fields`: `$tags` is
+ * how a REST request asks for the system key (spec 17, amendment 29), never a
+ * key of the answer.
+ */
+const SYSTEM_KEYS = [
+    ["id", "id"],
+    ["model", "model"],
+    ["status", "status"],
+    ["createdAt", "createdAt"],
+    ["updatedAt", "updatedAt"],
+    ["publishedAt", "publishedAt"],
+    ["_version", "version"],
+    ["_folder", "folder"],
+    ["_tags", "tags"],
+];
+const SYSTEM_NAMES = new Set(SYSTEM_KEYS.map(([name]) => name));
+/** A relation list's page size when the selection gives no `first`, as REST's `limit:`. */
+const NESTED_DEFAULT = 100;
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** The entries of a connection value, from `nodes` or `edges[].node`, with the selection that shaped them. */
+function connectionItems(selection, value) {
+    if (isObject(selection.nodes) && Array.isArray(value.nodes))
+        return { items: value.nodes, entry: selection.nodes };
+    const edges = isObject(selection.edges) ? selection.edges : undefined;
+    if (edges && isObject(edges.node) && Array.isArray(value.edges)) {
+        return { items: value.edges.map((edge) => (isObject(edge) ? edge.node : null)), entry: edges.node };
+    }
+    throw new TypeError("@capacms/sdk/next: toTree needs nodes, or edges { node }, selected on every list.");
+}
+function modelOf(schema, field) {
+    const target = schema.models.find((m) => m.namespace === field.target);
+    if (!target)
+        throw new TypeError(`@capacms/sdk/next: toTree has no model ${String(field.target)} in the schema.`);
+    return target;
+}
+/** A relation list as REST's `{ items, pageInfo }`; `pageInfo` only when the selection asked for it. */
+function relationList(schema, target, selection, value) {
+    const { items, entry } = connectionItems(selection, value);
+    const out = { items: items.map((item) => (isObject(item) ? entryTree(schema, target, entry, item) : item)) };
+    const pageSelection = isObject(selection.pageInfo) ? selection.pageInfo : undefined;
+    const page = isObject(value.pageInfo) ? value.pageInfo : undefined;
+    if (pageSelection?.hasNextPage === true && page) {
+        const args = isObject(selection.args) ? selection.args : {};
+        const hasNext = page.hasNextPage === true;
+        out.pageInfo = {
+            limit: typeof args.first === "number" ? args.first : NESTED_DEFAULT,
+            hasNext,
+            next: hasNext && typeof page.endCursor === "string" ? page.endCursor : null,
+        };
+    }
+    return out;
+}
+/** One media value with its keys in REST's order: `{ id, url, alt, type, width, height }`, as far as selected. */
+function mediaTree(value) {
+    if (!isObject(value))
+        return value;
+    const out = {};
+    for (const key of plan_1.MEDIA_FIELDS)
+        if (key in value)
+            out[key] = value[key];
+    return out;
+}
+/** A relation GraphQL types as an id holds one when it is a non-empty string, as REST reads a stored reference. */
+function isRelationId(value) {
+    return typeof value === "string" && value !== "";
+}
+/** One customer field's value in REST's shape. */
+function fieldTree(schema, field, selection, value) {
+    if (value === null || value === undefined)
+        return value ?? null;
+    switch (field.kind) {
+        case "relation":
+            return isObject(selection) && isObject(value) ? entryTree(schema, modelOf(schema, field), selection, value) : value;
+        case "relationList":
+            return isObject(selection) && isObject(value) ? relationList(schema, modelOf(schema, field), selection, value) : value;
+        case "id":
+            return isRelationId(value) ? { id: value, model: field.target } : null;
+        case "idList":
+            // REST lists the whole stored list here, so there is never a next page.
+            return {
+                items: Array.isArray(value) ? value.filter(isRelationId).map((id) => ({ id, model: field.target })) : [],
+                pageInfo: { hasNext: false, next: null },
+            };
+        case "media":
+            return Array.isArray(value) ? value.map(mediaTree) : mediaTree(value);
+        default:
+            return value;
+    }
+}
+/**
+ * Throws for an alias anywhere below a root field. REST reads each field once,
+ * so a second read of one under another name has no place in its tree. Checked
+ * on the selection, so the answer does not depend on which lists came back empty.
+ */
+function refuseAliasesBelow(selection) {
+    for (const key of (0, typed_1.selectedKeys)(selection)) {
+        const value = selection[key];
+        if (!isObject(value))
+            continue;
+        const aliased = (0, typed_1.aliasedField)(value);
+        if (aliased !== undefined) {
+            throw new TypeError(`@capacms/sdk/next: toTree: ${key} aliases ${aliased} below the root field, and REST has one value per field: ` +
+                `select ${aliased} under its own name, or read ${key} from the GraphQL result.`);
+        }
+        refuseAliasesBelow(value);
+    }
+}
+/**
+ * One entry: system keys at the top in REST's order, `model` from the schema
+ * whether selected or not, every customer field under `fields` by namespace.
+ */
+function entryTree(schema, model, selection, node) {
+    const keys = (0, typed_1.selectedKeys)(selection);
+    const out = {};
+    for (const [name, restKey] of SYSTEM_KEYS) {
+        if (name === "model")
+            out.model = model.namespace;
+        else if (keys.includes(name) && name in node)
+            out[restKey] = node[name];
+    }
+    const fields = {};
+    for (const key of keys) {
+        if (SYSTEM_NAMES.has(key) || !(key in node))
+            continue;
+        const field = model.fields.find((f) => f.name === key);
+        if (!field) {
+            fields[key] = node[key];
+            continue;
+        }
+        fields[field.namespace] = fieldTree(schema, field, selection[key], node[key]);
+    }
+    out.fields = fields;
+    return (0, attrs_1.carryEditMark)(node, out);
+}
+/**
+ * A `client.graphql.query()` result in the shape `/api/entries` answers with:
+ * each model root field as its REST `data`, a list root as its entries, a
+ * single root as its entry, and `null` for a root that failed (its error is in
+ * the GraphQL result's `errors`).
+ *
+ *   import { capaTreeLayout } from "./capa-graphql"; // written by capa-codegen --graphql
+ *   const selection = { articles: { args: { first: 5 }, nodes: { id: true, status: true, title: true } } } as const;
+ *   const { data } = await capa.graphql.query(selection);
+ *   const { articles } = toTree(data, selection, capaTreeLayout);
+ *   articles?.map((entry) => entry.fields.title); // string | null, as REST's entries.list
+ *   // deep-equal to (await capa.entries.list("articles", { select: "title", limit: 5 })).data
+ *
+ * Without codegen, pass the key's schema instead: `await capa.graphqlSchema()`,
+ * one introspection request. Either carries the types (`capaTreeLayout`
+ * always, a schema when the client is typed by `CapaQuery`): the result is
+ * typed from the selection, and the selection must name `id` and `status` on
+ * every entry, which REST always returns. Each entry's `model` comes from the
+ * layout. A selection from `selectToSelection` names all of that itself, and
+ * its tree is untyped, as its fields are known only at run time.
+ *
+ * A root field may be an alias (`latest: { __aliasFor: "articles", ... }`),
+ * and becomes the REST data of the field it names, under its own key. An
+ * alias below a root field throws a `TypeError`: REST reads each field once.
+ *
+ * Only model root fields convert; `version`, `me` and `entry` throw a
+ * `TypeError`, since REST has no entry list for them. Page through a list
+ * with the GraphQL result's own `pageInfo`.
+ */
+function toTree(data, selection, schema) {
+    if (!isObject(selection))
+        throw new TypeError("@capacms/sdk/next: toTree needs the selection the query was built from.");
+    const root = isObject(data) ? data : {};
+    const out = {};
+    for (const key of (0, typed_1.selectedKeys)(selection)) {
+        const rootSelection = selection[key];
+        const field = (0, typed_1.aliasedField)(rootSelection) ?? key;
+        const list = schema.models.find((m) => m.listField === field);
+        const single = list ? undefined : schema.models.find((m) => m.singleField === field);
+        if ((!list && !single) || !isObject(rootSelection)) {
+            throw new TypeError(`@capacms/sdk/next: toTree converts model root fields, and ${key} is not one. Read it from the GraphQL result.`);
+        }
+        refuseAliasesBelow(rootSelection);
+        const value = root[key];
+        if (!isObject(value)) {
+            out[key] = null;
+        }
+        else if (list) {
+            const { items, entry } = connectionItems(rootSelection, value);
+            out[key] = items.map((item) => (isObject(item) ? entryTree(schema, list, entry, item) : item));
+        }
+        else {
+            out[key] = entryTree(schema, single, rootSelection, value);
+        }
+    }
+    return out;
+}