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

package/dist/graphql-codegen.d.ts

@@ -0,0 +1,117 @@
+/**
+ * graphql-codegen.ts — `capa-codegen --graphql` and `capa persist`, the pure half.
+ *
+ * Reads a key's schema (introspection JSON) and a project's GraphQL documents,
+ * validates every document against that schema, and writes ONE TypeScript
+ * module holding:
+ *
+ *   - the schema as types, for `createClient<CapaQuery>()` and the typed
+ *     builder (`client.graphql.query`);
+ *   - one `TypedDocument` constant per named operation, so
+ *     `client.graphql(ArticlesPageDocument, vars)` infers the result and the
+ *     variables with no cast, and beside it `<Name>Models`, the models it
+ *     reads, for its Next.js cache tags;
+ *   - for each document written as a literal (`#graphql`, `/* capa *\/` or
+ *     gql(`...`)), an entry in `CapaDocuments` keyed by its exact text, so
+ *     `client.graphql(LITERAL, vars)` infers them too, with no import;
+ *   - `capaTreeLayout`, what `toTree` reads of the schema, so a server lays a
+ *     builder result out in REST's shape without reading the schema first.
+ *
+ * The file walk and the network live in `bin/`; everything here is a function
+ * of its inputs, so it is tested without either.
+ *
+ * `graphql` (graphql-js) is loaded on first use, never at import: it is an
+ * optional peer dependency that only these commands need, and a site that
+ * only calls `client.graphql()` must not pay for it.
+ */
+import type * as GraphQLJs from "graphql";
+import type { CapaIntrospection } from "./next/graphql/introspection";
+/** graphql-js, or an error that says how to get it. */
+export declare function loadGraphQL(): typeof GraphQLJs;
+/** One GraphQL document found in a project, with where it came from. */
+export interface DocumentSource {
+    file: string;
+    /** 1-based line of the document's first character in `file`. */
+    line: number;
+    /** The document's text as the program holds it at run time: a template's escapes are applied. */
+    text: string;
+    /**
+     * True for a literal whose type is its text (`#graphql`, `/* capa *\/`,
+     * gql(`...`)): it is sent exactly as written, and codegen keys its types by
+     * that text.
+     */
+    literal?: true;
+    /** The variable a literal is assigned to (`const CARD = ...`), which another literal's `${CARD}` names. */
+    name?: string;
+    /**
+     * For a literal with `${NAME}` in it: the text around each `${}` and the
+     * names in them, resolved against the project's other literals before the
+     * literal is read. `text` holds the template with its `${NAME}`s meanwhile.
+     */
+    template?: {
+        segments: string[];
+        names: string[];
+        asConst: boolean;
+    };
+}
+/** A template codegen does not read, and why: the CLI prints each one, so none is dropped in silence. */
+export interface SkippedDocument extends DocumentSource {
+    reason: string;
+}
+/** A template's text at run time, from its source text: line ends as LF, escapes applied. */
+export declare function cookTemplate(raw: string): string;
+/**
+ * The GraphQL documents in one file: the whole file for `.graphql` and `.gql`,
+ * and elsewhere every template that is marked as one: a `#graphql` first
+ * line, a `/* capa *\/` comment before it, or `gql` as a tag or a function.
+ * One on a comment line is an example, not a document.
+ *
+ * `skipped` names every template codegen will not read that looks meant for
+ * it, with the reason: one with `${}` inside (its text is only known at run
+ * time, so it cannot be validated or hashed ahead of it), a named operation
+ * left unmarked, and `/nextjs`'s `graphql` used as a tag.
+ */
+export declare function extractDocuments(file: string, text: string): {
+    documents: DocumentSource[];
+    skipped: SkippedDocument[];
+};
+export interface CodegenProblem {
+    file: string;
+    line: number;
+    column: number;
+    message: string;
+}
+export interface GeneratedOperation {
+    name: string;
+    /** The exact text of its `<Name>Document`, and hashed for persisted queries. */
+    document: string;
+    sha256: string;
+    /** The namespaces of the models it reads, written as `<Name>Models` for its cache tags. */
+    models: string[];
+    /** For a document written as a literal: the literal's text, which is what a call with it sends, and its hash. */
+    literal?: {
+        document: string;
+        sha256: string;
+    };
+}
+export interface GraphQLCodegenResult {
+    /** The module to write. Null when a document failed. */
+    source: string | null;
+    operations: GeneratedOperation[];
+    problems: CodegenProblem[];
+    /**
+     * Each use of a deprecated field, argument, input field or enum value, with
+     * the reason the schema gives: it still works, and a later Capa-Version
+     * removes it.
+     */
+    warnings: CodegenProblem[];
+    /** Literals with a `${}` that names no literal of the project, so their text is only known at run time. */
+    skipped: SkippedDocument[];
+}
+/**
+ * The generated module for a schema and a project's documents. Problems (a
+ * syntax error, a field the key cannot read, an unnamed operation, a name used
+ * twice) are returned with their file and line, and no module is produced
+ * while any remain.
+ */
+export declare function generateGraphQLModule(introspection: CapaIntrospection, sources: DocumentSource[]): GraphQLCodegenResult;