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

package/dist/next/client.js

@@ -1,10 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LAYOUT_PAGE = exports.CapaError = void 0;
-exports.isCapaError = isCapaError;
+exports.LAYOUT_PAGE = exports.isCapaError = exports.CapaError = void 0;
+exports.graphqlClient = graphqlClient;
 exports.resolveNextConfig = resolveNextConfig;
 exports.serializeSelect = serializeSelect;
 exports.createClient = createClient;
+const attrs_1 = require("./attrs");
+const errors_1 = require("./errors");
+const edit_mode_1 = require("./graphql/edit-mode");
+const key_family_1 = require("./key-family");
+const system_keys_1 = require("./system-keys");
+const field_names_1 = require("./field-names");
+const introspection_1 = require("./graphql/introspection");
+const request_1 = require("./graphql/request");
+const summary_1 = require("./graphql/summary");
+const typed_1 = require("./graphql/typed");
+var errors_2 = require("./errors");
+Object.defineProperty(exports, "CapaError", { enumerable: true, get: function () { return errors_2.CapaError; } });
+Object.defineProperty(exports, "isCapaError", { enumerable: true, get: function () { return errors_2.isCapaError; } });
 /**
  * What a `Capa-Schema` value may look like: hex, 8 to 64 characters.
  *
@@ -16,29 +29,23 @@ exports.createClient = createClient;
  * appears rather than as an error.
  */
 const SCHEMA_CHECKSUM = /^[a-f0-9]{8,64}$/;
-class CapaError extends Error {
-    status;
-    type;
-    code;
-    param;
-    hint;
-    requestId;
-    docs;
-    constructor(input) {
-        super(input.message);
-        this.name = "CapaError";
-        this.status = input.status;
-        this.type = input.type;
-        this.code = input.code;
-        this.param = input.param;
-        this.hint = input.hint;
-        this.requestId = input.requestId;
-        this.docs = input.docs;
-    }
-}
-exports.CapaError = CapaError;
-function isCapaError(error) {
-    return error instanceof CapaError;
+const BUILDER_NOT_PERSISTED = "@capacms/sdk/next: graphql.query() cannot send persisted: true. It builds its document when it runs, " +
+    "so capa persist never stored it and every read would fall back to an uncached POST. " +
+    "Leave persisted out (a builder read is already a cached GET), or write the read as a #graphql literal and run capa persist.";
+/**
+ * `client.graphql` over one way of reading a document: called with a
+ * document, and `query()` printing a selection's document for it. `createClient`
+ * reads straight from the API, and `getCapaClient` from `/nextjs` through
+ * Next's data cache, with the same refusals.
+ */
+function graphqlClient(read) {
+    const query = async (selection, options) => {
+        if (options?.persisted)
+            throw new TypeError(BUILDER_NOT_PERSISTED);
+        return read((0, typed_1.selectionToDocument)(selection, options?.operationName), undefined, options);
+    };
+    const call = (document, variables, options) => read(document, variables, options);
+    return Object.assign(call, { query });
 }
 function resolveNextConfig(config) {
     const value = (config ?? {});
@@ -47,8 +54,9 @@ function resolveNextConfig(config) {
         throw new Error(`@capacms/sdk/next: missing ${missing.join(", ")}. ` +
             "createClient needs baseUrl, apiKey and version.");
     }
-    if (!value.apiKey.startsWith("cap_")) {
-        throw new Error("@capacms/sdk/next: apiKey must start with cap_. Use the legacy @capacms/sdk client for pk_ and sk_ keys.");
+    if ((0, key_family_1.keyFamily)(value.apiKey) === null) {
+        throw new Error("@capacms/sdk/next: apiKey must be a string: a cap_ key, or the legacy key your site already holds. " +
+            "Mint a cap_ key in the Capa admin under Developers > Keys.");
     }
     if (value.contract !== undefined && value.contract !== 1) {
         throw new Error("@capacms/sdk/next: contract must be 1 when provided.");
@@ -60,6 +68,7 @@ function resolveNextConfig(config) {
     // Checked here as well as per call, so a bad page on the config throws where
     // the client is built rather than on whichever read happens to run first.
     resolvePage(value.page, undefined);
+    resolvePath(value.path, undefined);
     // THROWS rather than dropping, the same rule `page` follows and for the same
     // reason: the API must never 400 a running site over a telemetry header, so
     // it ignores what it cannot store, and the SDK is the place a wrong value
@@ -120,12 +129,59 @@ function resolvePage(configPage, callPage) {
     }
     return value;
 }
-const NAME = /^[A-Za-z0-9_-]+$/;
+/**
+ * What a `Capa-Path` value may look like: a site path, query and hash cut off.
+ * COPIED from `PAGE_PATH_PATTERN` in `apps/api/src/api-next/page-header.ts`.
+ */
+const PAGE_PATH = /^\/[^\s?#]{0,1023}$/;
+function resolvePath(configPath, callPath) {
+    const value = callPath !== undefined ? callPath : configPath;
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string") {
+        throw new TypeError(`@capacms/sdk/next: path must be a string such as "/blog/hello".`);
+    }
+    const bare = value.split("#")[0].split("?")[0];
+    if (!PAGE_PATH.test(bare)) {
+        throw new TypeError(`@capacms/sdk/next: path must be the concrete path being rendered, such as "/blog/hello". Got ${JSON.stringify(value)}.`);
+    }
+    return bare;
+}
+/*
+ * The array form names each field by its namespace, as saved in the admin,
+ * and the select is written in REST's grammar: a namespace that holds a
+ * character the grammar uses goes quoted (`"price.usd"`, field-names.ts). A
+ * name starting with `$` is a system key, so no field can be named that way;
+ * select "*" returns such a field.
+ */
+/** A relation's name: a field, since a system key expands nothing. */
 function selectName(value, context) {
-    if (typeof value !== "string" || !NAME.test(value)) {
+    if (typeof value !== "string" || !(0, field_names_1.isNameable)(value)) {
         throw new TypeError(`@capacms/sdk/next: ${context} must be a field name.`);
     }
-    return value;
+    return (0, field_names_1.writeName)(value);
+}
+/**
+ * A select item: a field, or a system key by its `$` name, which means the
+ * system key even beside a field of the same plain name (spec 17, amendment 29).
+ */
+function selectItemName(value) {
+    if ((0, system_keys_1.sigilSystemKey)(value) !== null)
+        return value;
+    if ((0, field_names_1.isNameable)(value))
+        return (0, field_names_1.writeName)(value);
+    throw new TypeError(`@capacms/sdk/next: select item must be a field name, or a system key: ${system_keys_1.SYSTEM_KEY_LIST}.`);
+}
+/** One nested sort key: a field, or a system key the API sorts by, either with a leading `-`. */
+function nestedSort(value, relation) {
+    const descending = typeof value === "string" && value.startsWith("-");
+    const key = descending ? value.slice(1) : value;
+    const system = typeof key === "string" ? (0, system_keys_1.sigilSystemKey)(key) : null;
+    if (system !== null && (0, system_keys_1.isSortableSystemKey)(system))
+        return value;
+    if (typeof key === "string" && system === null && (0, field_names_1.isNameable)(key))
+        return `${descending ? "-" : ""}${(0, field_names_1.writeName)(key)}`;
+    throw new TypeError(`@capacms/sdk/next: ${relation}.sort must be one field name, or one of ${system_keys_1.SORTABLE_SYSTEM_KEYS.map((k) => `$${k}`).join(", ")}, with - to sort descending.`);
 }
 function serializeSelectItems(items) {
     if (items.length === 0)
@@ -133,7 +189,7 @@ function serializeSelectItems(items) {
     return items
         .map((item) => {
         if (typeof item === "string") {
-            return item === "*" ? item : selectName(item, "select item");
+            return item === "*" ? item : selectItemName(item);
         }
         if (!item || typeof item !== "object" || Array.isArray(item)) {
             throw new TypeError("@capacms/sdk/next: each select item must be a field name or relation object.");
@@ -142,12 +198,12 @@ function serializeSelectItems(items) {
         if (entries.length !== 1) {
             throw new TypeError("@capacms/sdk/next: a relation select object must name exactly one field.");
         }
-        const [rawName, value] = entries[0];
-        const name = selectName(rawName, "relation select key");
+        const [name, value] = entries[0];
+        const written = selectName(name, "relation select key");
         if (value === "*")
-            return `${name}(*)`;
+            return `${written}(*)`;
         if (Array.isArray(value))
-            return `${name}(${serializeSelectItems(value)})`;
+            return `${written}(${serializeSelectItems(value)})`;
         if (!value || typeof value !== "object") {
             throw new TypeError(`@capacms/sdk/next: ${name} must select fields, "*", or select options.`);
         }
@@ -172,19 +228,15 @@ function serializeSelectItems(items) {
             }
             args.push(`limit:${options.limit}`);
         }
-        if (options.sort !== undefined) {
-            if (typeof options.sort !== "string" || !/^-?[A-Za-z0-9_-]+$/.test(options.sort)) {
-                throw new TypeError(`@capacms/sdk/next: ${name}.sort must be one field name.`);
-            }
-            args.push(`sort:${options.sort}`);
-        }
+        if (options.sort !== undefined)
+            args.push(`sort:${nestedSort(options.sort, name)}`);
         if (options.after !== undefined) {
             if (typeof options.after !== "string" || options.after === "") {
                 throw new TypeError(`@capacms/sdk/next: ${name}.after must be a non-empty cursor.`);
             }
             args.push(`after:${options.after}`);
         }
-        return `${name}(${args.join(",")})`;
+        return `${written}(${args.join(",")})`;
     })
         .join(",");
 }
@@ -225,10 +277,21 @@ function filterValue(operator, value) {
     }
     return String(value);
 }
+/** `shape` is sent only when it is `flat`, so a tree read's URL is the one it always was. */
+function shapeOf(options) {
+    const shape = options.shape;
+    if (shape === undefined || shape === "tree")
+        return undefined;
+    if (shape === "flat")
+        return "flat";
+    throw new TypeError(`@capacms/sdk/next: shape must be "tree" or "flat". Got ${JSON.stringify(shape)}.`);
+}
 function listQuery(options) {
     const query = new URLSearchParams();
     if (options.select !== undefined)
         query.set("select", serializeSelect(options.select));
+    if (shapeOf(options) === "flat")
+        query.set("shape", "flat");
     if (options.filter !== undefined) {
         for (const [path, operations] of Object.entries(options.filter)) {
             for (const [rawOperator, value] of Object.entries(operations)) {
@@ -256,45 +319,12 @@ function listQuery(options) {
         query.set("before", options.before);
     return query;
 }
-function optionalString(value) {
-    return typeof value === "string" ? value : undefined;
-}
-function unparseable(status, requestId) {
-    return new CapaError({
-        status,
-        type: "api_error",
-        code: "unparseable_response",
-        message: "Capa returned a response that was not a valid /api/ JSON envelope.",
-        requestId,
-        docs: "",
-    });
-}
-function errorFromEnvelope(status, body, fallbackRequestId) {
-    const detail = body.error;
-    if (!detail ||
-        typeof detail.type !== "string" ||
-        typeof detail.code !== "string" ||
-        typeof detail.message !== "string" ||
-        typeof detail.docs !== "string") {
-        return unparseable(status, fallbackRequestId);
-    }
-    return new CapaError({
-        status,
-        type: detail.type,
-        code: detail.code,
-        message: detail.message,
-        param: optionalString(detail.param),
-        hint: optionalString(detail.hint),
-        requestId: optionalString(body.meta?.requestId) ?? fallbackRequestId,
-        docs: detail.docs,
-    });
-}
 function cacheTags(response) {
     const value = response.headers?.get?.("Surrogate-Key") ?? "";
     return value.split(/\s+/).filter(Boolean);
 }
 function createRequester(config) {
-    return async function request(path, query = new URLSearchParams(), signal, page) {
+    return async function request(path, query = new URLSearchParams(), signal, page, pagePath) {
         const url = new URL(config.baseUrl + path);
         query.forEach((value, key) => url.searchParams.append(key, value));
         const headers = {
@@ -308,6 +338,8 @@ function createRequester(config) {
         // byte-identical requests to the ones it sent before this option existed.
         if (page !== undefined)
             headers["Capa-Page"] = page;
+        if (page !== undefined && pagePath !== undefined)
+            headers["Capa-Path"] = pagePath;
         // Same rule, and on EVERY call rather than only the entries reads: the
         // stamp describes the build, so a page whose only Capa call is `me()`
         // still reports which schema it was generated from.
@@ -321,33 +353,82 @@ function createRequester(config) {
             body = JSON.parse(text);
         }
         catch {
-            throw unparseable(response.status, requestId);
+            throw (0, errors_1.unparseable)(response.status, requestId);
+        }
+        if (!response.ok) {
+            throw (0, errors_1.errorFromEnvelope)(response.status, body, requestId, (0, errors_1.retryAfterOf)(response.headers?.get?.("Retry-After")));
         }
-        if (!response.ok)
-            throw errorFromEnvelope(response.status, body, requestId);
         if (!body || typeof body !== "object")
-            throw unparseable(response.status, requestId);
+            throw (0, errors_1.unparseable)(response.status, requestId);
+        if (config.editMode === true) {
+            // `included` holds a flat read's related entries, which are marked
+            // exactly as they are when the tree nests them inside `data`.
+            const { data, included } = body;
+            (0, attrs_1.markEditEntries)(data);
+            if (included !== undefined)
+                (0, attrs_1.markEditEntries)(included);
+        }
         return { body: body, cacheTags: cacheTags(response) };
     };
 }
 function createClient(config) {
     const resolved = resolveNextConfig(config);
+    if ((0, key_family_1.keyFamily)(resolved.apiKey) === "legacy")
+        (0, key_family_1.warnLegacyKeyOnce)(resolved.apiKey);
     const request = createRequester(resolved);
+    // By POST: introspection is never cached (G plan D16), and the admin host
+    // serves GraphQL by POST only.
+    const readSchema = async (signal) => {
+        const result = await (0, request_1.runGraphQL)(resolved, introspection_1.INTROSPECTION_QUERY, undefined, { signal, method: "POST" });
+        const requestId = result.extensions.capa?.requestId ?? "";
+        // The API answered 200, so the status says so; the errors say what failed.
+        if (result.errors.length > 0)
+            throw (0, errors_1.errorFromGraphQLErrors)(200, result.errors, requestId);
+        if (!result.data)
+            throw (0, errors_1.unparseable)(200, requestId);
+        return (0, summary_1.summarizeIntrospection)(result.data);
+    };
+    // By POST, as the schema above: it selects only `__schema`.
+    const readFieldNames = async () => {
+        const result = await (0, request_1.runGraphQL)(resolved, introspection_1.FIELD_NAMES_QUERY, undefined, { method: "POST" });
+        if (!result.data || result.errors.length > 0)
+            throw new Error("the key's field names could not be read");
+        return result.data;
+    };
+    /** One GraphQL read; in edit mode its entries are marked for `capaAttrs`, as REST's are. */
+    const readGraphQL = (document, variables, options) => {
+        const read = () => (0, request_1.runGraphQL)(resolved, document, variables, options);
+        if (resolved.editMode !== true)
+            return read();
+        return (0, edit_mode_1.readMarked)(document, `${resolved.baseUrl}\n${resolved.apiKey}\n${resolved.version}`, readFieldNames, read);
+    };
+    const graphql = graphqlClient(readGraphQL);
+    /**
+     * A flat read's result carries the select it sent, so `inflate(result)`
+     * needs nothing else. A tree read's result is exactly what it always was.
+     */
+    const withSelect = (result, options) => {
+        if (shapeOf(options) !== "flat" || options.select === undefined)
+            return result;
+        return { ...result, select: serializeSelect(options.select) };
+    };
     const entries = {
         async list(namespace, options = {}) {
-            const result = await request(`/api/entries/${encodeURIComponent(namespace)}`, listQuery(options), options.signal, resolvePage(resolved.page, options.page));
-            return { ...result.body, cacheTags: result.cacheTags };
+            const result = await request(`/api/entries/${encodeURIComponent(namespace)}`, listQuery(options), options.signal, resolvePage(resolved.page, options.page), resolvePath(resolved.path, options.path));
+            return withSelect({ ...result.body, cacheTags: result.cacheTags }, options);
         },
         async get(namespace, id, options = {}) {
             const query = new URLSearchParams();
             if (options.select !== undefined)
                 query.set("select", serializeSelect(options.select));
+            if (shapeOf(options) === "flat")
+                query.set("shape", "flat");
             try {
-                const result = await request(`/api/entries/${encodeURIComponent(namespace)}/${encodeURIComponent(id)}`, query, options.signal, resolvePage(resolved.page, options.page));
-                return { ...result.body, cacheTags: result.cacheTags };
+                const result = await request(`/api/entries/${encodeURIComponent(namespace)}/${encodeURIComponent(id)}`, query, options.signal, resolvePage(resolved.page, options.page), resolvePath(resolved.path, options.path));
+                return withSelect({ ...result.body, cacheTags: result.cacheTags }, options);
             }
             catch (error) {
-                if (error instanceof CapaError &&
+                if (error instanceof errors_1.CapaError &&
                     error.status === 404 &&
                     error.type === "not_found" &&
                     error.code === "entry_not_found") {
@@ -357,6 +438,9 @@ function createClient(config) {
             }
         },
         async *iterate(namespace, options = {}) {
+            if (shapeOf(options) === "flat") {
+                throw new TypeError("@capacms/sdk/next: iterate reads the tree shape only. Use list with shape: \"flat\" and page.next.");
+            }
             let after = options.after;
             for (;;) {
                 const page = await entries.list(namespace, { ...options, after });
@@ -386,7 +470,7 @@ function createClient(config) {
                 // Same shape as `entries.get`: a page nobody has declared or read is a
                 // null, not a throw, because "is this page known to Capa" is a question
                 // a caller asks on purpose.
-                if (error instanceof CapaError &&
+                if (error instanceof errors_1.CapaError &&
                     error.status === 404 &&
                     error.code === "page_not_found") {
                     return null;
@@ -398,7 +482,12 @@ function createClient(config) {
     return {
         entries,
         pages,
+        graphql,
+        graphqlSchema(options = {}) {
+            return readSchema(options.signal);
+        },
         async preview(token, options = {}) {
+            (0, key_family_1.requirePreviewKey)(resolved.apiKey);
             const query = new URLSearchParams();
             query.set("token", token);
             try {
@@ -409,7 +498,7 @@ function createClient(config) {
                 // preview route has the same fallback for either: render the published
                 // page. Anything else (a 500, a network failure, a missing scope) is a
                 // real problem and must not be mistaken for a stale link.
-                if (error instanceof CapaError &&
+                if (error instanceof errors_1.CapaError &&
                     (error.code === "preview_token_invalid" || error.code === "preview_token_expired")) {
                     return null;
                 }
@@ -417,10 +506,10 @@ function createClient(config) {
             }
         },
         async me(options = {}) {
-            return (await request("/api/me", new URLSearchParams(), options.signal, resolvePage(resolved.page, options.page))).body;
+            return (await request("/api/me", new URLSearchParams(), options.signal, resolvePage(resolved.page, options.page), resolvePath(resolved.path, options.path))).body;
         },
         async versions(options = {}) {
-            return (await request("/api/versions", new URLSearchParams(), options.signal, resolvePage(resolved.page, options.page))).body;
+            return (await request("/api/versions", new URLSearchParams(), options.signal, resolvePage(resolved.page, options.page), resolvePath(resolved.path, options.path))).body;
         },
     };
 }

package/dist/next/entry-fields.d.ts

@@ -0,0 +1,162 @@
+/**
+ * entry-fields.ts — an entry's `fields` as `/api/entries` returns them, typed
+ * from the model and the select.
+ *
+ * A model type says what an editor stores: `capa-codegen` writes a relation as
+ * the related model (`CapaRelation<Authors>`), a relation list as a list of
+ * them, and media as the upload (`CapaImage`). A read answers in its own shape
+ * (docs/api/entries.md), and these types say which:
+ *
+ *   - a field the select names is always there, and `null` when it was never
+ *     filled, as the API writes it: optional in the model, never absent here;
+ *   - a field the select does not name is not there;
+ *   - a relation the select does not expand is a reference, `{ id, model }`,
+ *     or null when it is empty;
+ *   - an expanded relation is the related entry, with `fields` of its own, or
+ *     `{ id, model, missing: true }` when that entry was deleted, is
+ *     unpublished for a production key, or is in a model the key cannot read;
+ *   - a relation list is `{ items, pageInfo }`, expanded or not;
+ *   - media is `{ id, url, alt, type, width, height }`, never the upload's
+ *     own keys.
+ *
+ * A select the compiler can read exactly, a literal passed as its type
+ * (`list<Articles, typeof select>`), types what it names. One it cannot, a
+ * string or a value typed as `Select<T>` itself, types every field, and each
+ * relation as any of the three it may be, which the caller narrows
+ * (`"fields" in author`). An untyped model (`Record<string, unknown>`) stays
+ * untyped.
+ */
+import type { Entry } from "./client";
+import type { Select } from "./select-types";
+/** A relation a read did not expand: the entry's id, and its model's namespace, null when the key cannot read that model. */
+export interface EntryReference {
+    id: string;
+    model: string | null;
+}
+/**
+ * An expanded relation the API looked for and did not find: the entry was
+ * deleted, is unpublished for a production key, or is in a model the key
+ * cannot read.
+ */
+export interface MissingEntry extends EntryReference {
+    missing: true;
+}
+/** A relation list, expanded or not. `limit` is there when the read expanded it. */
+export interface RelationItems<E> {
+    items: E[];
+    pageInfo: {
+        limit?: number;
+        hasNext: boolean;
+        next: string | null;
+    };
+}
+/** An image, video or file as `/api/` returns it. */
+export interface EntryMedia {
+    id: string;
+    url: string | null;
+    alt: string | null;
+    type: string | null;
+    width: number | null;
+    height: number | null;
+}
+/**
+ * Levels of entries left to type: the root entry and 4 below it, the API's 5
+ * levels. A relation past the last level is typed as a reference, which is all
+ * the API returns there.
+ */
+type Depth = [never, 0, 1, 2, 3, 4];
+type Flatten<T> = {
+    [K in keyof T]: T[K];
+};
+/** A field type that says nothing: `unknown`, or `any`. */
+type Untyped<V> = 0 extends 1 & V ? true : unknown extends V ? true : false;
+type RelationBrand = {
+    readonly __capaRelation: "one" | "many";
+    readonly __capaRelationTarget: unknown;
+};
+type IsRelation<V> = Untyped<V> extends true ? false : NonNullable<V> extends RelationBrand ? true : false;
+type IsList<V> = NonNullable<V> extends {
+    readonly __capaRelation: "many";
+} ? true : false;
+type TargetOf<V> = NonNullable<V> extends {
+    readonly __capaRelationTarget: infer R;
+} ? R : never;
+/** Media as codegen types it: `CapaImage`, `CapaVideo` and `CapaFile` each have a `url`. */
+type StoredMedia = {
+    url: string;
+};
+/**
+ * A field that is no relation: as stored, or `null` when it was never filled,
+ * but media, which the read returns in its public shape.
+ */
+type ValueTree<V> = Untyped<V> extends true ? V : NonNullable<V> extends ReadonlyArray<infer M> ? [M] extends [StoredMedia] ? EntryMedia[] | null : NonNullable<V> | null : NonNullable<V> extends StoredMedia ? EntryMedia | null : NonNullable<V> | null;
+/** A relation the read did not expand. */
+type ReferenceTree<V> = IsList<V> extends true ? RelationItems<EntryReference> : EntryReference | null;
+/** A field the read names without expanding it. */
+type FieldTree<V> = IsRelation<V> extends true ? ReferenceTree<V> : ValueTree<V>;
+/** An expanded relation, its entries read with `S`, at level `D`. */
+type ExpandedTree<V, S, D extends number> = IsList<V> extends true ? RelationItems<Entry<FieldsAt<TargetOf<V>, S, D>> | MissingEntry> : Entry<FieldsAt<TargetOf<V>, S, D>> | MissingEntry | null;
+/** A relation the read may or may not have expanded, with any select, at level `D`. */
+type EitherTree<V, D extends number> = IsList<V> extends true ? RelationItems<EntryReference | MissingEntry | Entry<FieldsAt<TargetOf<V>, string, D>>> : EntryReference | MissingEntry | Entry<FieldsAt<TargetOf<V>, string, D>> | null;
+/** Every field, relations as references: a read with no select, or `*`. */
+type ReferenceFields<T> = {
+    [K in keyof T]-?: FieldTree<T[K]>;
+};
+/** Every field, each relation as whatever it may be: a select the compiler cannot read. */
+type LooseFields<T, D extends number> = {
+    [K in keyof T]-?: IsRelation<T[K]> extends true ? EitherTree<T[K], Depth[D]> : ValueTree<T[K]>;
+};
+/** The relations a select item expands, by name. */
+type ExpandedIn<I> = I extends string ? never : Extract<keyof I, string>;
+/** What the select writes for relation `K`: its list, `*`, or its options' `select`. */
+type SubSelect<I, K extends string> = I extends {
+    readonly [P in K]: infer V;
+} ? V extends {
+    readonly select: infer S;
+} ? S : V : never;
+/**
+ * The fields a literal select names, `I` being the union of its items: each
+ * named field, every field for `*`, and each expanded relation as the entries
+ * its own select reads. A system key (`$tags`) sits beside `fields`, on the entry.
+ */
+type SelectedFields<T, I, D extends number> = Flatten<{
+    [K in keyof T as K extends ExpandedIn<I> ? IsRelation<T[K]> extends true ? never : K : "*" extends I ? K : K extends I ? K : never]-?: FieldTree<T[K]>;
+} & {
+    [K in keyof T as K extends ExpandedIn<I> ? (IsRelation<T[K]> extends true ? K : never) : never]-?: ExpandedTree<T[K], SubSelect<I, K & string>, Depth[D]>;
+}>;
+type FieldsAt<T, S, D extends number> = string extends keyof T ? T : [D] extends [never] ? ReferenceFields<T> : [S] extends [undefined] ? ReferenceFields<T> : [S] extends ["*"] ? ReferenceFields<T> : S extends ReadonlyArray<infer I> ? Select<T> extends S ? LooseFields<T, D> : SelectedFields<T, I, D> : LooseFields<T, D>;
+/**
+ * `fields` of an entry of model `T` read with select `S`, as `/api/entries`
+ * returns them. Pass the select's own type for exact fields
+ * (`list<Articles, typeof select>`); without it every field is typed, and
+ * each relation as whatever it may be.
+ */
+export type EntryFields<T, S = Select<T> | string> = FieldsAt<T, S, 4>;
+/** A field of a `shape=flat` read: each relation a reference, since the entry it names is in `included`. */
+type FlatTree<V> = IsRelation<V> extends true ? IsList<V> extends true ? RelationItems<EntryReference | MissingEntry> : EntryReference | MissingEntry | null : ValueTree<V>;
+/** The fields a select names at its root: every field for none, `*`, a string or `Select<T>`. */
+type NamedKeys<T, S> = [S] extends [undefined] ? keyof T : S extends ReadonlyArray<infer I> ? Select<T> extends S ? keyof T : "*" extends I ? keyof T : Extract<keyof T, I | ExpandedIn<I>> : keyof T;
+/** `fields` of an entry in a `shape=flat` read's `data`. */
+export type FlatFields<T, S = Select<T>> = string extends keyof T ? T : {
+    [K in keyof T as K extends NamedKeys<T, S> ? K : never]-?: FlatTree<T[K]>;
+};
+/**
+ * `fields` of an entry in `included`: the union of what every path that
+ * reached it selected, so any field may be absent.
+ */
+export type IncludedFields<I> = I extends unknown ? string extends keyof I ? I : {
+    [K in keyof I]?: FlatTree<I[K]>;
+} : never;
+/**
+ * Where a flat result keeps the model and select it was read with, for
+ * `inflate` to type the tree it returns. A symbol, never a field, and never a
+ * runtime value.
+ */
+declare const flatRead: unique symbol;
+export type { flatRead };
+export interface FlatRead<T, S> {
+    readonly [flatRead]?: {
+        model: T;
+        select: S;
+    };
+}

package/dist/next/entry-fields.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });