@osdlc/typed-gh 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @osdlc/typed-gh
 
+## 0.17.0
+
+### Minor Changes
+
+- 61b12ce: `graphql` (experimental) reads a partial answer with `{ partial: true }`. Each page comes back as a `GraphqlPage`, its `data` with its `errors` (`GraphqlError`: `message`, `type`, `path`), so a batch of aliased lookups keeps the ones that worked when one is gone. gh exits 1 for such a response; the partial form reads it as the answer on the plain method, `try` and `soft`. It still fails when there is no `data` to read, when gh failed for another reason, or when `paginate` stopped at a page with errors that has a next page. `nodesAt(pages, path, { partial: true })` joins one connection across partial pages and returns `PartialNodes`: the nodes and every page's errors. Without `partial`, nothing changes. There is no page cap: `paginate` follows every page, and a caller that needs to stop early pages with `$endCursor` itself, as the README shows. The `try` and `soft` types now keep both overloads of an overloaded method.
+
+## 0.16.1
+
+### Patch Changes
+
+- Updated dependencies [25ccd9e]
+  - @osdlc/typed-git@0.13.0
+
 ## 0.16.0
 
 ### Minor Changes

package/README.md

@@ -492,7 +492,7 @@ const branches = gh.api('repos/{owner}/{repo}/branches', { paginate: true }).bod
 ```
 
 `graphql` (experimental) runs a query and returns each page's `data`. It throws when the
-call failed or any page has `errors` or no `data` (`soft.graphql` is `null`). A partial answer counts as a failure. `nodesAt` joins
+call failed or any page has `errors` or no `data` (`soft.graphql` is `null`). A partial answer counts as a failure, unless you pass `partial: true` (see [Partial answers](#partial-answers)). `nodesAt` joins
 one connection's `nodes` across the pages, and is `null` when any page lacks them.
 `fromTarget('owner')` and `fromTarget('repo')` fill a variable from the client's repo, or let gh
 fill it from the clone. A plain string is always sent as written, so a real value of `{owner}` stays
@@ -518,6 +518,70 @@ const prs = nodesAt(pages, ['repository', 'pullRequests'])
 With `paginate`, the query must take `$endCursor` and page one connection. gh follows only that
 one. `graphql` refuses a document holding a mutation or subscription with `RangeError`. Send one through `raw`.
 
+### Partial answers
+
+When part of a query fails, GitHub still answers the rest: an aliased pull request that was
+deleted is `null` in `data`, and an entry in `errors` names its path. gh prints that response and
+exits 1. Pass `partial: true` to read it. Each page comes back as a `GraphqlPage`, its `data` with
+its `errors` (each a `GraphqlError` of `message`, `type` and `path`). `errors` is empty for a page
+that came back whole.
+
+```ts
+const [page] = gh.graphql(
+  `query($owner: String!, $name: String!) {
+    repository(owner: $owner, name: $name) {
+      a: pullRequest(number: 1) { title }
+      b: pullRequest(number: 2) { title }
+    }
+  }`,
+  { owner: fromTarget('owner'), name: fromTarget('repo') },
+  { partial: true },
+)
+const missing = page?.errors.map((e) => e.path.join('.')) // ['repository.b'] when #2 is gone
+```
+
+It still throws (`soft.graphql` is `null`) when there is no `data` to read: a failed call, a
+response with no `data` or `data: null` (a rate limit, a query that does not validate), or output
+that does not parse. With `paginate`, gh stops at the first page with errors. When that page still has a next
+page, the pages after it were never fetched, so that throws too, rather than return fewer rows.
+`nodesAt(pages, path, { partial: true })` joins one connection across partial pages and returns
+`PartialNodes`: the `nodes`, where a node GitHub could not resolve is `null`, and every page's
+`errors`.
+
+### Stopping early
+
+`paginate` has no page cap: gh follows the connection to its end. To read at most a few pages, or
+to carry on past a page with errors (add `partial: true` and read each page's `data`), leave
+`paginate` off and pass the cursor yourself:
+
+```ts
+const query = `query($endCursor: String) {
+  repository(owner: "acme", name: "widgets") {
+    pullRequests(first: 100, after: $endCursor) {
+      pageInfo { hasNextPage endCursor }
+      nodes { number }
+    }
+  }
+}`
+interface PageInfo {
+  hasNextPage: boolean
+  endCursor: string | null
+}
+type Page = { repository: { pullRequests: { pageInfo: PageInfo } } }
+const prs: unknown[] = []
+let endCursor: string | null = null
+for (let n = 0; n < 3; n += 1) {
+  const [data]: unknown[] = gh.graphql(query, { endCursor })
+  prs.push(...(nodesAt([data], ['repository', 'pullRequests']) ?? []))
+  const info: PageInfo = (data as Page).repository.pullRequests.pageInfo
+  if (!info.hasNextPage) break
+  endCursor = info.endCursor
+}
+```
+
+The decision is in
+[docs/planning/decisions/graphql-partial-and-page-cap.md](docs/planning/decisions/graphql-partial-and-page-cap.md).
+
 ## Repositories and search
 
 ```ts
@@ -617,7 +681,7 @@ Methods on both clients:
 - Issue and label queries: `issueList`, `issueView` and `labelList`.
 - Repository queries: `repoList` and `repoView`.
 - Issue and label changes: `setIssueLabel`, `createLabel`, `editLabel` and `issueCommentEdit`.
-- REST and GraphQL: `api` is a GET through `gh api` and never throws (failure is `ok: false`); `graphql` is a query and throws on a failed or partial answer.
+- REST and GraphQL: `api` is a GET through `gh api` and never throws (failure is `ok: false`); `graphql` is a query and throws on a failed or partial answer, or returns a partial answer as `{ data, errors }` pages with `partial: true`.
 - Setup checks: `installed`, `authenticated`, `authStatus` and `ready`.
 - `ownerRepo` reads the owner and repository from a remote URL. It starts no process.
 - `try` and `soft`: the whole surface again as a `Result<T, GhFailure>`, and the queries again with `null` for a failure. `TriedSync`, `TriedAsync` and `Soft` are their types.
@@ -649,13 +713,15 @@ a verb before running it. Each verb takes an optional `GhTarget` last, except `r
 - `pickPrForBranch`: the first row whose head branch is exactly the one you name. `prList({ head })`
   already filters exactly. This is for rows from elsewhere, such as a `head:` search. It takes plain
   rows or a `ListResult`, so `openPrsForBranch`'s or `prList`'s parsed answer passes straight in.
-- `nodesAt`: one connection's nodes, joined across `graphql` pages.
+- `nodesAt`: one connection's nodes, joined across `graphql` pages. With `{ partial: true }`, across
+  partial pages, with their errors.
 - Field lists: `PR_REF_FIELDS` (enough to identify a PR), `PR_LIST_FIELDS` (for triage),
   `PR_VIEW_FIELDS` (the full set), `REPO_FIELDS` and `SEARCH_PR_FIELDS`.
 - Option and result types: `ListResult`, `PrListOptions`, `IssueListOptions`, `RepoListOptions`,
   `SearchPrsOptions`, `CreatePrOptions`, `CreateReviewOptions`, `ReviewComment`,
-  `CreateLabelOptions`, `ApiOptions`, `ApiResponse`, `GraphqlOptions`, `GraphqlVariable`,
-  `AuthStatus`, `PrMergeMethod` and `ReviewThread`.
+  `CreateLabelOptions`, `ApiOptions`, `ApiResponse`, `GraphqlOptions`, `GraphqlPartialOptions`,
+  `GraphqlPage`, `GraphqlError`, `PartialNodes`, `GraphqlVariable`, `AuthStatus`, `PrMergeMethod`
+  and `ReviewThread`.
 
 ### Parsers
 
@@ -702,7 +768,8 @@ The experimental items:
 - `ReviewComment`
 - `graphql`, the verb and the method on both clients
 - `nodesAt`
-- `GraphqlOptions`
+- `GraphqlOptions` and `GraphqlPartialOptions`
+- `GraphqlPage`, `GraphqlError` and `PartialNodes`
 - `GraphqlVariable`
 - `fromTarget` and `FromTarget`
 

package/dist/async.d.ts

@@ -116,10 +116,12 @@ export declare class AsyncGh {
     /** A REST GET through `gh api`. Failure is `ok: false`, never a rejection. */
     api(endpoint: string, opts?: ApiOptions & AsyncCallOptions): Promise<ApiResponse>;
     /**
-     * A GraphQL query. Resolves to each page's `data`. Rejects on a failed or partial result. See `Gh.graphql`.
+     * A GraphQL query. Resolves to each page's `data`. Rejects on a failed or partial result.
+     * With `partial: true`, resolves to each page's `data` with its `errors`. See `Gh.graphql`.
      *
      * @experimental
      */
+    graphql(query: string, variables: Record<string, v.GraphqlVariable> | undefined, opts: v.GraphqlPartialOptions & AsyncCallOptions): Promise<v.GraphqlPage[]>;
     graphql(query: string, variables?: Record<string, v.GraphqlVariable>, opts?: v.GraphqlOptions & AsyncCallOptions): Promise<unknown[]>;
     /** Every label on the repository (up to `opts.limit`, default 1000). Rejects when gh fails. */
     labelList(opts?: {

package/dist/async.js

@@ -157,11 +157,6 @@ export class AsyncGh {
     async api(endpoint, opts = {}) {
         return this.exec(v.api(endpoint, opts, this.target), opts);
     }
-    /**
-     * A GraphQL query. Resolves to each page's `data`. Rejects on a failed or partial result. See `Gh.graphql`.
-     *
-     * @experimental
-     */
     async graphql(query, variables = {}, opts = {}) {
         return this.read(v.graphql(query, variables, opts, this.target), opts);
     }

package/dist/doors.d.ts

@@ -29,9 +29,10 @@ import type { GhVerb } from './verbs.ts';
  * A checked verb has already thrown on a non-zero exit (the runner is
  * {@link runCheckedGh}). A probe (`installed`, `authStatus`, `api`, `raw`)
  * carries its failure in its value. A read that exited non-zero throws the
- * classified failure, unless the verb's `absent` says gh's answer was "there
- * is no such thing", which `parse` turns into `null`. A read that exited 0 but
- * parsed to `null` could not be read completely, and throws.
+ * classified failure, unless the verb's `absent` says the result is still an
+ * answer: gh's "there is no such thing", which `parse` turns into `null`, or a
+ * partial `graphql` response. A read that exited 0 but parsed to `null` could
+ * not be read completely, and throws.
  *
  * A result flagged `outputIncomplete` throws for every verb but a probe, as
  * typed-git's `gate` does: gh exited, but the runner stopped reading at the
@@ -59,13 +60,47 @@ export declare function runCheckedGh(runner: CommandRunner, argv: string[], opts
 export declare function runCheckedGhAsync(runner: AsyncCommandRunner, argv: string[], opts: AsyncCommandRunOptions): Promise<CommandResult>;
 /** The members `try` and `soft` leave out: `raw`, `rawChecked`, helpers that run nothing, and properties. */
 type Triable<C> = Omit<C, 'raw' | 'rawChecked' | 'at' | 'withRepo' | 'ownerRepo' | 'try' | 'soft' | 'cwd' | 'repo' | 'hostname'>;
+/**
+ * A method's call signatures as `[args, return]` pairs: its last two when it
+ * is overloaded (`graphql` is, on its `partial` option), and its one
+ * signature twice when it is not. The types below map each pair, so `try` and
+ * `soft` keep both of a method's overloads.
+ */
+type Signatures<F> = F extends {
+    (...a: infer A1): infer R1;
+    (...a: infer A2): infer R2;
+} ? [[A1, R1], [A2, R2]] : never;
 /** Every synchronous client method, returning a `Result<T, GhFailure>`. */
 export type TriedSync<C> = {
-    [K in keyof Triable<C>]: Triable<C>[K] extends (...a: infer A) => infer R ? (...a: A) => Result<R, GhFailure> : never;
+    [K in keyof Triable<C>]: Signatures<Triable<C>[K]> extends [
+        [
+            infer A1 extends unknown[],
+            infer R1
+        ],
+        [
+            infer A2 extends unknown[],
+            infer R2
+        ]
+    ] ? {
+        (...a: A1): Result<R1, GhFailure>;
+        (...a: A2): Result<R2, GhFailure>;
+    } : never;
 };
 /** Every awaitable client method, promising a `Result<T, GhFailure>`. */
 export type TriedAsync<C> = {
-    [K in keyof Triable<C>]: Triable<C>[K] extends (...a: infer A) => Promise<infer R> ? (...a: A) => Promise<Result<R, GhFailure>> : never;
+    [K in keyof Triable<C>]: Signatures<Triable<C>[K]> extends [
+        [
+            infer A1 extends unknown[],
+            Promise<infer R1>
+        ],
+        [
+            infer A2 extends unknown[],
+            Promise<infer R2>
+        ]
+    ] ? {
+        (...a: A1): Promise<Result<R1, GhFailure>>;
+        (...a: A2): Promise<Result<R2, GhFailure>>;
+    } : never;
 };
 /**
  * The queries that have a soft form. A mutation has none. If a write's failure
@@ -77,7 +112,19 @@ export type SoftMethod = (typeof SOFT_METHODS)[number];
 type OrNull<R> = R extends Promise<infer U> ? Promise<U | null> : R | null;
 /** Each queried method again, returning `null` instead of throwing. One type for both clients. */
 export type Soft<C> = {
-    [K in SoftMethod & keyof C]: C[K] extends (...a: infer A) => infer R ? (...a: A) => OrNull<R> : never;
+    [K in SoftMethod & keyof C]: Signatures<C[K]> extends [
+        [
+            infer A1 extends unknown[],
+            infer R1
+        ],
+        [
+            infer A2 extends unknown[],
+            infer R2
+        ]
+    ] ? {
+        (...a: A1): OrNull<R1>;
+        (...a: A2): OrNull<R2>;
+    } : never;
 };
 /** The failure a caught `CommandFailed` or `FailureError` stands for. */
 export declare function failureOf(error: {

package/dist/doors.js

@@ -28,9 +28,10 @@ import { classifyGhFailure, unreadableFailure } from "./failure.js";
  * A checked verb has already thrown on a non-zero exit (the runner is
  * {@link runCheckedGh}). A probe (`installed`, `authStatus`, `api`, `raw`)
  * carries its failure in its value. A read that exited non-zero throws the
- * classified failure, unless the verb's `absent` says gh's answer was "there
- * is no such thing", which `parse` turns into `null`. A read that exited 0 but
- * parsed to `null` could not be read completely, and throws.
+ * classified failure, unless the verb's `absent` says the result is still an
+ * answer: gh's "there is no such thing", which `parse` turns into `null`, or a
+ * partial `graphql` response. A read that exited 0 but parsed to `null` could
+ * not be read completely, and throws.
  *
  * A result flagged `outputIncomplete` throws for every verb but a probe, as
  * typed-git's `gate` does: gh exited, but the runner stopped reading at the
@@ -49,7 +50,7 @@ export function settle(verb, result, binary) {
         : runFailed(result, (r) => verb.absent?.(r) === true);
     if (failed)
         throw ghFailureError(new CommandFailed(verb.argv, result, binary));
-    // A non-zero exit that got this far is gh's "there is no such thing".
+    // A non-zero exit that got this far is an answer the verb's `absent` accepted.
     if (verb.checked || result.exitCode !== 0)
         return verb.parse(result);
     const value = verb.parse(result);

package/dist/index.d.ts

@@ -23,7 +23,7 @@ export { classifyGhFailure, type GhFailure, type GhFailureKind } from './failure
 export { type Soft, type TriedAsync, type TriedSync } from './doors.ts';
 export { runVerb, runVerbAsync, type RunVerbAsyncOptions, type RunVerbOptions } from './run.ts';
 export { Gh, defaultRunnerFactory, type GhOptions, type GhRepoOptions, type RunnerFactory, } from './sync.ts';
-export { api, authStatus, createPr, editPr, editPrBody, fromTarget, graphql, createLabel, createReview, editLabel, installed, issueList, issueView, labelList, nodesAt, openPrsForBranch, pickPrForBranch, prBody, prComment, prSetDraft, issueCommentEdit, prDiff, prList, prMerge, prReviewThreads, prUpdateBranch, prView, raw, rawChecked, repoList, repoView, searchPrs, setIssueLabel, PR_LIST_FIELDS, PR_REF_FIELDS, PR_VIEW_FIELDS, REPO_FIELDS, SEARCH_PR_FIELDS, type ApiOptions, type ApiResponse, type AuthStatus, type CreateLabelOptions, type CreatePrOptions, type CreateReviewOptions, type FromTarget, type GhTarget, type GraphqlOptions, type GraphqlVariable, type GhVerb, type IssueListOptions, type ListResult, type PrListOptions, type PrMergeMethod, type RepoListOptions, type ReviewComment, type ReviewThread, type SearchPrsOptions, } from './verbs.ts';
+export { api, authStatus, createPr, editPr, editPrBody, fromTarget, graphql, createLabel, createReview, editLabel, installed, issueList, issueView, labelList, nodesAt, openPrsForBranch, pickPrForBranch, prBody, prComment, prSetDraft, issueCommentEdit, prDiff, prList, prMerge, prReviewThreads, prUpdateBranch, prView, raw, rawChecked, repoList, repoView, searchPrs, setIssueLabel, PR_LIST_FIELDS, PR_REF_FIELDS, PR_VIEW_FIELDS, REPO_FIELDS, SEARCH_PR_FIELDS, type ApiOptions, type ApiResponse, type AuthStatus, type CreateLabelOptions, type CreatePrOptions, type CreateReviewOptions, type FromTarget, type GhTarget, type GraphqlError, type GraphqlOptions, type GraphqlPage, type GraphqlPartialOptions, type GraphqlVariable, type GhVerb, type IssueListOptions, type ListResult, type PartialNodes, type PrListOptions, type PrMergeMethod, type RepoListOptions, type ReviewComment, type ReviewThread, type SearchPrsOptions, } from './verbs.ts';
 export { anyCheckFailed, normalizeAuthorLogin, parsePullRequest } from './parse.ts';
 export { ownerRepoSlug, parseOwnerRepo, parsePrRef, parsePrUrl, type PrRef, type PullRequestRef, } from './repo.ts';
 export type { Actor, CheckConclusion, CheckRun, Comment, IssueRow, Label, MergeableState, MergeStateStatus, OwnerRepo, PullRequest, PrSearchHit, PullRequestState, Repository, RepositoryVisibility, Review, ReviewDecision, ReviewState, } from './types.ts';

package/dist/sync.d.ts

@@ -202,10 +202,15 @@ export declare class Gh {
     }): ApiResponse;
     /**
      * A GraphQL query. Returns each page's `data`. Throws on a failed or partial
-     * result. `soft.graphql` gives null. See the `graphql` verb.
+     * result. `soft.graphql` gives null. With `partial: true`, returns each
+     * page's `data` with its `errors`, and throws only when there is no data to
+     * read. See the `graphql` verb.
      *
      * @experimental
      */
+    graphql(query: string, variables: Record<string, v.GraphqlVariable> | undefined, opts: v.GraphqlPartialOptions & {
+        timeoutMs?: number | undefined;
+    }): v.GraphqlPage[];
     graphql(query: string, variables?: Record<string, v.GraphqlVariable>, opts?: v.GraphqlOptions & {
         timeoutMs?: number | undefined;
     }): unknown[];

package/dist/sync.js

@@ -225,12 +225,6 @@ export class Gh {
     api(endpoint, opts = {}) {
         return this.exec(v.api(endpoint, opts, this.target), opts.timeoutMs);
     }
-    /**
-     * A GraphQL query. Returns each page's `data`. Throws on a failed or partial
-     * result. `soft.graphql` gives null. See the `graphql` verb.
-     *
-     * @experimental
-     */
     graphql(query, variables = {}, opts = {}) {
         return this.read(v.graphql(query, variables, opts, this.target), opts.timeoutMs);
     }

package/dist/verbs.d.ts

@@ -42,10 +42,13 @@ export interface GhVerb<T> {
      */
     probe?: boolean | undefined;
     /**
-     * For a read of one thing: whether a non-zero result means GitHub has no such
-     * thing (`prView`, `issueView`, `repoView`). The plain method then returns
-     * what `parse` makes of it, `null`, because a missing item is an answer.
-     * Other non-zero results fail the call.
+     * Whether a non-zero result is still an answer. For a read of one thing, it
+     * says GitHub has no such thing (`prView`, `issueView`, `repoView`), and
+     * `parse` makes `null` of it, because a missing item is an answer. For
+     * `graphql` with `partial`, it says gh exited 1 over a response that
+     * carries `errors` alongside its `data`, and `parse` reads the pages. The
+     * plain method returns what `parse` makes of it. Other non-zero results
+     * fail the call.
      */
     absent?: ((result: CommandResult) => boolean) | undefined;
     parse(result: CommandResult): T;
@@ -261,9 +264,59 @@ export interface GraphqlOptions {
     /**
      * Follow every page (`--paginate --slurp`). The query must take
      * `$endCursor: String` and select `pageInfo { hasNextPage endCursor }` on
-     * the one connection it pages through. gh follows only that connection.
+     * the one connection it pages through. gh follows only that connection, to
+     * its end. There is no page cap: to stop early, page yourself (see the
+     * README's "Reading every page").
      */
     paginate?: boolean | undefined;
+    /**
+     * Unset or `false`: a page with `errors` fails the call. Pass
+     * {@link GraphqlPartialOptions} to read partial pages instead.
+     */
+    partial?: false | undefined;
+}
+/**
+ * Options for {@link graphql} that read a partial answer: each page's `data`
+ * with the `errors` that came with it.
+ *
+ * @experimental
+ */
+export interface GraphqlPartialOptions extends Omit<GraphqlOptions, 'partial'> {
+    /**
+     * Return each page as a {@link GraphqlPage}, so a page whose `data` came
+     * back with `errors` is still read. GitHub answers this way when part of a
+     * query fails: an aliased pull request that was deleted is `null` in
+     * `data`, and an error names its path.
+     */
+    partial: true;
+}
+/**
+ * One entry of a GraphQL response's `errors`.
+ *
+ * @experimental
+ */
+export interface GraphqlError {
+    /** What GitHub said went wrong. `''` when the error had no message. */
+    readonly message: string;
+    /** GitHub's error type, such as `NOT_FOUND` or `FORBIDDEN`. `null` when it gave none. */
+    readonly type: string | null;
+    /**
+     * Where in `data` the error happened: field names (an alias, when the
+     * query used one) and list indexes, from the root. Empty when the error
+     * names no path, as one about the whole query does.
+     */
+    readonly path: readonly (string | number)[];
+}
+/**
+ * One page of a partial {@link graphql} answer: the page's `data`, and the
+ * `errors` that came with it. `errors` is empty for a page that came back
+ * whole. A field the errors name is `null` in `data`.
+ *
+ * @experimental
+ */
+export interface GraphqlPage {
+    readonly data: unknown;
+    readonly errors: readonly GraphqlError[];
 }
 /**
  * `gh api graphql -f query=… [--paginate --slurp]`: a GraphQL query.
@@ -273,6 +326,16 @@ export interface GraphqlOptions {
  * carries `errors` or lacks `data`. A partial answer counts as a failure. Read one
  * connection across the pages with {@link nodesAt}.
  *
+ * With `partial: true` ({@link GraphqlPartialOptions}), returns each page as
+ * a {@link GraphqlPage}, its `data` with its `errors`, so a batch of aliased
+ * lookups keeps the ones that worked. gh exits 1 for a response with
+ * `errors`; the verb declares that result an answer (`absent`), so the
+ * methods that throw return it. It is still null when the output did not
+ * parse, a page has no `data` object, gh failed for another reason, or
+ * `paginate` stopped at a page with errors that says it has a next page. gh
+ * stops at the first page with errors, so the pages after it were never
+ * fetched.
+ *
  * A {@link fromTarget} variable is filled from the target's repo, or by gh
  * from the clone. A plain string is sent as written. A document holding any mutation or
  * subscription throws `RangeError`, as does a variable named `query` or
@@ -281,16 +344,41 @@ export interface GraphqlOptions {
  *
  * @experimental
  */
+export declare function graphql(query: string, variables: Record<string, GraphqlVariable> | undefined, opts: GraphqlPartialOptions, target?: GhTarget): GhVerb<GraphqlPage[] | null>;
 export declare function graphql(query: string, variables?: Record<string, GraphqlVariable>, opts?: GraphqlOptions, target?: GhTarget): GhVerb<unknown[] | null>;
+export declare function graphql(query: string, variables: Record<string, GraphqlVariable> | undefined, opts: GraphqlOptions | GraphqlPartialOptions, target?: GhTarget): GhVerb<unknown[] | GraphqlPage[] | null>;
 /**
  * The `nodes` of one connection, joined across {@link graphql} pages. It
  * follows `path` into each page and takes its `nodes` array. Null when `pages` is
  * null, or any page lacks the path or a `nodes` array, so a page that came
  * back short is never read as fewer rows.
  *
+ * With `{ partial: true }`, it reads the {@link GraphqlPage}s of a partial
+ * `graphql` call. It follows `path` into each page's `data`, and returns the
+ * joined `nodes` with every error of every page, as {@link PartialNodes}. A
+ * node that failed is `null` among the nodes, and its error's `path` names
+ * it. It is null on the same terms as the plain form: a connection that is
+ * itself `null` because of an error has no nodes to give, and the errors are
+ * on the pages.
+ *
  * @experimental
  */
-export declare function nodesAt(pages: unknown[] | null, path: readonly string[]): unknown[] | null;
+export declare function nodesAt(pages: readonly GraphqlPage[] | null, path: readonly string[], opts: {
+    partial: true;
+}): PartialNodes | null;
+export declare function nodesAt(pages: readonly unknown[] | null, path: readonly string[]): unknown[] | null;
+/**
+ * One connection's nodes across partial {@link graphql} pages, and the errors
+ * that came with them. What {@link nodesAt} returns with `{ partial: true }`.
+ *
+ * @experimental
+ */
+export interface PartialNodes {
+    /** The joined `nodes`. A node GitHub could not resolve is `null`. */
+    readonly nodes: unknown[];
+    /** Every error of every page, in page order, including any outside `path`. */
+    readonly errors: readonly GraphqlError[];
+}
 /** `gh --version`: checks that `gh` is installed. True when `gh` runs. */
 export declare function installed(): GhVerb<boolean>;
 /**

package/dist/verbs.js

@@ -428,6 +428,87 @@ export function fromTarget(part) {
     }
     return Object.freeze({ fromTarget: part });
 }
+/** One `errors` entry, read leniently: a string is its message, anything else counts with none. */
+function readGraphqlError(entry) {
+    if (typeof entry === 'string')
+        return { message: entry, type: null, path: [] };
+    if (entry === null || typeof entry !== 'object')
+        return { message: '', type: null, path: [] };
+    const rec = entry;
+    const path = rec['path'];
+    const wellFormed = Array.isArray(path) && path.every((p) => typeof p === 'string' || typeof p === 'number');
+    return {
+        message: typeof rec['message'] === 'string' ? rec['message'] : '',
+        type: typeof rec['type'] === 'string' ? rec['type'] : null,
+        path: wellFormed ? path : [],
+    };
+}
+/**
+ * A page's `errors`. None when the field is missing or `null`. gh counts a
+ * string as an error, as an array of entries is, so both are read here.
+ */
+function readGraphqlErrors(errors) {
+    if (errors === undefined || errors === null)
+        return [];
+    return Array.isArray(errors) ? errors.map(readGraphqlError) : [readGraphqlError(errors)];
+}
+/**
+ * True when anything in `value` says `hasNextPage: true`. gh's own test for
+ * another page reads the first `pageInfo` it meets. This one reads every
+ * `hasNextPage`, so it says yes whenever gh would have, and sometimes when it
+ * would not have.
+ */
+function mentionsNextPage(value) {
+    if (Array.isArray(value))
+        return value.some(mentionsNextPage);
+    if (value === null || typeof value !== 'object')
+        return false;
+    const rec = value;
+    if (rec['hasNextPage'] === true)
+        return true;
+    return Object.values(rec).some(mentionsNextPage);
+}
+/**
+ * Read `gh api graphql` output as partial pages, or `null` when it is no
+ * answer. Every page must be an object whose `data` is an object.
+ *
+ * gh exits 1 when a response carries `errors`, after printing it. So a
+ * non-zero exit is an answer only when the last page has errors, which is
+ * why gh stopped. Any other non-zero exit is a failure that left some output
+ * behind, such as earlier pages before a network error. With `paginate`, gh
+ * also stops at the first page with errors. When that page says there was a
+ * next one, the pages after it were never fetched, so the answer is short and
+ * is not read.
+ */
+function readPartialPages(r, paginate) {
+    let body;
+    try {
+        body = JSON.parse(r.stdout);
+    }
+    catch {
+        return null;
+    }
+    const pages = paginate ? body : [body];
+    if (!Array.isArray(pages))
+        return null;
+    const out = [];
+    for (const page of pages) {
+        if (page === null || typeof page !== 'object')
+            return null;
+        const rec = page;
+        if (rec['data'] === null || typeof rec['data'] !== 'object')
+            return null;
+        out.push({ data: rec['data'], errors: readGraphqlErrors(rec['errors']) });
+    }
+    if (r.exitCode !== 0) {
+        const last = out.at(-1);
+        if (last === undefined || last.errors.length === 0)
+            return null;
+        if (paginate && mentionsNextPage(last.data))
+            return null;
+    }
+    return out;
+}
 /**
  * True when any operation in a GraphQL document is a `mutation` or a
  * `subscription`. Strings and comments are dropped first, and only the words
@@ -449,22 +530,6 @@ function writesOrStreams(document) {
     }
     return false;
 }
-/**
- * `gh api graphql -f query=… [--paginate --slurp]`: a GraphQL query.
- *
- * Returns each page's `data`, one entry per page (one without `paginate`).
- * Returns null when the call failed, the output did not parse, or any page
- * carries `errors` or lacks `data`. A partial answer counts as a failure. Read one
- * connection across the pages with {@link nodesAt}.
- *
- * A {@link fromTarget} variable is filled from the target's repo, or by gh
- * from the clone. A plain string is sent as written. A document holding any mutation or
- * subscription throws `RangeError`, as does a variable named `query` or
- * `operationName`, which gh would send as the request's own fields. This is a
- * read, and changes go through `raw`.
- *
- * @experimental
- */
 export function graphql(query, variables = {}, opts = {}, target) {
     checkTarget(target);
     if (writesOrStreams(query)) {
@@ -505,6 +570,25 @@ export function graphql(query, variables = {}, opts = {}, target) {
         }
     }
     argv.push('-f', `query=${query}`);
+    if (opts.partial === true) {
+        // `settle` calls `absent` and then `parse` on the same result, so each
+        // result's output is parsed once and kept here.
+        const read = new WeakMap();
+        const pagesOf = (r) => {
+            if (!read.has(r))
+                read.set(r, readPartialPages(r, paginate));
+            return read.get(r) ?? null;
+        };
+        return {
+            argv,
+            checked: false,
+            readOnly: true,
+            // A response with errors exits 1. When it still holds the pages, it is
+            // the answer, not a failure.
+            absent: (r) => pagesOf(r) !== null,
+            parse: pagesOf,
+        };
+    }
     return {
         argv,
         checked: false,
@@ -537,20 +621,25 @@ export function graphql(query, variables = {}, opts = {}, target) {
         },
     };
 }
-/**
- * The `nodes` of one connection, joined across {@link graphql} pages. It
- * follows `path` into each page and takes its `nodes` array. Null when `pages` is
- * null, or any page lacks the path or a `nodes` array, so a page that came
- * back short is never read as fewer rows.
- *
- * @experimental
- */
-export function nodesAt(pages, path) {
+export function nodesAt(pages, path, opts = {}) {
     if (pages === null)
         return null;
-    const out = [];
+    const partial = opts.partial === true;
+    const nodes = [];
+    const errors = [];
     for (const page of pages) {
         let at = page;
+        if (partial) {
+            if (page === null || typeof page !== 'object')
+                return null;
+            const { data, errors: pageErrors } = page;
+            if (!Array.isArray(pageErrors))
+                return null;
+            // Read each entry as `graphql` does, so a hand-built page cannot pass
+            // a malformed error through as a GraphqlError.
+            errors.push(...pageErrors.map(readGraphqlError));
+            at = data;
+        }
         for (const key of path) {
             if (at === null || typeof at !== 'object')
                 return null;
@@ -558,12 +647,12 @@ export function nodesAt(pages, path) {
         }
         if (at === null || typeof at !== 'object')
             return null;
-        const nodes = at['nodes'];
-        if (!Array.isArray(nodes))
+        const found = at['nodes'];
+        if (!Array.isArray(found))
             return null;
-        out.push(...nodes);
+        nodes.push(...found);
     }
-    return out;
+    return partial ? { nodes, errors } : nodes;
 }
 /** Split one header block off the front of `text`: the block, and what follows its blank line. */
 function takeHeaderBlock(text) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/typed-gh",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "A typed GitHub client for TypeScript over the gh CLI. A total PullRequest/Review/CheckRun model, pure argv builders and parsers, and a tri-modal client — queries return parsed values, mutations throw, raw() is the escape hatch. Uses gh's own credentials; reads no token.",
   "license": "MIT OR Apache-2.0",
   "author": "sksizer",
@@ -27,7 +27,7 @@
   ],
   "dependencies": {
     "@osdlc/command-seam": "^0.14.0",
-    "@osdlc/typed-git": "^0.12.0",
+    "@osdlc/typed-git": "^0.13.0",
     "@osdlc/result": "^0.1.0"
   },
   "engines": {