@osdlc/typed-gh 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @osdlc/typed-gh
 
+## 0.16.0
+
+### Minor Changes
+
+- 51efdb6: `raw(argv)` and `rawChecked(argv)` are new verbs: `Gh.raw` and `Gh.rawChecked` as functions, so a tool can make a call the verb table lacks without constructing a `Gh`. Through `runVerb`, `raw` returns the `CommandResult` whatever the exit code, and `rawChecked` returns it when `gh` exits 0 with its whole output and throws the classified `GhFailure` otherwise. Neither is `readOnly`. Both clients' `raw` and `rawChecked` methods now run these verbs. The one visible change is that `AsyncGh.raw` rejects, rather than throwing at the call site, when a runner throws synchronously, as `rawChecked` already did.
+  
+  The README has a new section, "Keeping a bundle small": a bundled tool that makes a few calls should import the verbs it calls and run them with `runVerb`, because a bundler cannot drop a class's unused methods. For a diff and one raw checked call, that is 14.4 KB against 68.0 KB through `Gh` (`bun build --minify`). The decision and the measurements are in `docs/planning/decisions/bundle-size.md`.
+
 ## 0.15.0
 
 ### Minor Changes

package/README.md

@@ -419,6 +419,34 @@ const repos = await runVerbAsync(repoList('acme', {}, { hostname: 'ghe.example.c
 `(binary, argv, opts) => result` function is not a runner; wrap it yourself as
 `{ run: (argv, opts) => fn('gh', argv, opts) }`.
 
+`raw(argv)` and `rawChecked(argv)` are `Gh.raw` and `Gh.rawChecked` as verbs, for a call the verb
+table does not have. Through `runVerb`, `raw` returns the `CommandResult` whatever the exit code,
+and `rawChecked` returns it when `gh` exits 0 with its whole output and throws the classified
+failure otherwise. Like the methods, they add no `--repo` and no host.
+
+## Keeping a bundle small
+
+A tool that is bundled and makes a few `gh` calls should import the verbs it calls and run them
+with `runVerb`, and not construct a `Gh`. A bundler drops a function that nothing imports, but it
+cannot drop a method a class never calls. So one `new Gh()` keeps every verb and parser in the
+bundle, and the verb path keeps only the verbs you import:
+
+```ts
+import { defaultRunnerFactory, prDiff, rawChecked, runVerb } from '@osdlc/typed-gh'
+
+const runner = defaultRunnerFactory('gh')
+const opts = { cwd: '/repo' }
+const diff = runVerb(prDiff(42), runner, opts)
+const files = runVerb(rawChecked(['api', 'repos/{owner}/{repo}/pulls/42/files']), runner, opts)
+```
+
+Built with `bun build --minify`, those two calls take 14.4 KB through `runVerb` and 68.0 KB through
+`Gh` (7.6 KB of each is command-seam's runner). The verb path gives up `try`, `soft` and the
+helpers that make several calls (`prFind`, `openPrFor`, `prViewSettled`): catch the `FailureError`
+instead. A tool that already uses many methods loses little by constructing `Gh`. The measurements
+and the reasons `Gh` is not split into entry points are in
+[docs/planning/decisions/bundle-size.md](docs/planning/decisions/bundle-size.md).
+
 ## `AsyncGh`
 
 The awaitable form of `Gh`, with the same methods, for code that runs many calls at once and must
@@ -573,7 +601,9 @@ experimental.
 - `AsyncCallOptions`: `timeoutMs` and `signal`, accepted by sixteen methods of `AsyncGh`.
 - `defaultRunnerFactory` and `RunnerFactory`: how a client makes its default runner for `gh`.
 - `runVerb` and `runVerbAsync`, with `RunVerbOptions` and `RunVerbAsyncOptions`: run one verb through
-  a runner you own, with its `env`, `input`, timeout and checked contract applied.
+  a runner you own, with its `env`, `input`, timeout and checked contract applied. With the verb
+  functions, they are the way to call `gh` without a `Gh`, which keeps a bundle small (see
+  "Keeping a bundle small").
 
 Methods on both clients:
 
@@ -601,10 +631,11 @@ Methods on both clients:
 
 A verb is plain data: argv, a `checked` flag, a `readOnly` flag, optional stdin and environment,
 and a `parse` function. `readOnly` is true for every query and `prDiff`, and false for every
-mutation, so a caller that keeps an allowlist of safe calls can check a verb before running it.
-Each verb takes an optional `GhTarget` last. Each client method has a verb of the same name, except
-`raw`, `rawChecked`, `at`, `withRepo`, `prViewSettled`, `openPrFor`, `prFind`, `authenticated`,
-`ready` and `ownerRepo`. `openPrsForBranch` is a verb with no method.
+mutation and for `raw` and `rawChecked`, so a caller that keeps an allowlist of safe calls can check
+a verb before running it. Each verb takes an optional `GhTarget` last, except `raw` and
+`rawChecked`, which take only argv. Each client method has a verb of the same name, except `at`,
+`withRepo`, `prViewSettled`, `openPrFor`, `prFind`, `authenticated`, `ready` and `ownerRepo`.
+`openPrsForBranch` is a verb with no method.
 
 - `GhVerb`: the shape of a verb. `GhTarget`: the `repo` and `hostname` a verb talks to.
 - Verb builders: `prList`, `prView`, `prBody`, `openPrsForBranch`, `prReviewThreads`, `prDiff`,
@@ -612,6 +643,9 @@ Each verb takes an optional `GhTarget` last. Each client method has a verb of th
   `createReview`, `issueList`, `issueView`, `labelList`, `setIssueLabel`, `createLabel`,
   `editLabel`, `issueCommentEdit`, `repoList`, `repoView`, `searchPrs`, `api`, `graphql`,
   `installed` and `authStatus`.
+- `raw` and `rawChecked`: any argv as a verb whose value is the `CommandResult`. `raw` returns it
+  whatever the exit code; `rawChecked` throws the classified failure unless `gh` exits 0 with its
+  whole output.
 - `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.

package/dist/async.js

@@ -11,7 +11,7 @@
  * block the event loop, such as many per-PR queries at once.
  */
 import { spawnRunnerAsync } from '@osdlc/command-seam';
-import { runCheckedGhAsync, softAsync, triedAsync } from "./doors.js";
+import { softAsync, triedAsync } from "./doors.js";
 import { runVerbAsync } from "./run.js";
 import { ownerRepoSlug, parseOwnerRepo, parsePrRef } from "./repo.js";
 import * as v from "./verbs.js";
@@ -80,11 +80,11 @@ export class AsyncGh {
      * `.at(dir)` first.
      */
     raw(argv, opts = {}) {
-        return this.runner.run(argv, { cwd: this.cwd, ...opts });
+        return this.exec(v.raw(argv), opts);
     }
     /** Run any `gh` call. Rejects with the classified failure on a non-zero exit. Adds no `--repo`, as {@link AsyncGh.raw}. */
     rawChecked(argv, opts = {}) {
-        return runCheckedGhAsync(this.runner, argv, { cwd: this.cwd, ...opts });
+        return this.exec(v.rawChecked(argv), opts);
     }
     /** Run one verb from the table, checked or unchecked as the verb says. */
     async exec(verb, call = {}) {

package/dist/doors.d.ts

@@ -27,11 +27,11 @@ import type { GhVerb } from './verbs.ts';
  * Read the result of running `verb` as the methods that throw do.
  *
  * A checked verb has already thrown on a non-zero exit (the runner is
- * {@link runCheckedGh}). A probe (`installed`, `authStatus`, `api`) 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.
+ * {@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.
  *
  * 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

package/dist/doors.js

@@ -26,11 +26,11 @@ import { classifyGhFailure, unreadableFailure } from "./failure.js";
  * Read the result of running `verb` as the methods that throw do.
  *
  * A checked verb has already thrown on a non-zero exit (the runner is
- * {@link runCheckedGh}). A probe (`installed`, `authStatus`, `api`) 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.
+ * {@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.
  *
  * 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

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, 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 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 { 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/index.js

@@ -23,7 +23,7 @@ export { classifyGhFailure } from "./failure.js";
 export {} from "./doors.js";
 export { runVerb, runVerbAsync } from "./run.js";
 export { Gh, defaultRunnerFactory, } from "./sync.js";
-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, repoList, repoView, searchPrs, setIssueLabel, PR_LIST_FIELDS, PR_REF_FIELDS, PR_VIEW_FIELDS, REPO_FIELDS, SEARCH_PR_FIELDS, } from "./verbs.js";
+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, } from "./verbs.js";
 export { anyCheckFailed, normalizeAuthorLogin, parsePullRequest } from "./parse.js";
 export { ownerRepoSlug, parseOwnerRepo, parsePrRef, parsePrUrl, } from "./repo.js";
 // command-seam's error and runner types appear in this package's signatures, so

package/dist/sync.js

@@ -17,7 +17,7 @@
  * `raw` and `rawChecked` run any `gh` call.
  */
 import { spawnRunner } from '@osdlc/command-seam';
-import { runCheckedGh, softSync, triedSync } from "./doors.js";
+import { softSync, triedSync } from "./doors.js";
 import { runVerb } from "./run.js";
 import * as v from "./verbs.js";
 import { ownerRepoSlug, parseOwnerRepo, parsePrRef } from "./repo.js";
@@ -122,11 +122,11 @@ export class Gh {
      * `.at(dir)` first.
      */
     raw(argv, opts = {}) {
-        return this.runner.run(argv, { cwd: this.cwd, ...opts });
+        return this.exec(v.raw(argv), opts.timeoutMs);
     }
     /** Run any `gh` call. Throws the classified failure on a non-zero exit. Adds no `--repo`, as {@link Gh.raw}. */
     rawChecked(argv, opts = {}) {
-        return runCheckedGh(this.runner, argv, { cwd: this.cwd, ...opts });
+        return this.exec(v.rawChecked(argv), opts.timeoutMs);
     }
     /** Run one verb from the table, checked or unchecked as the verb says. */
     exec(verb, timeoutMs) {

package/dist/verbs.d.ts

@@ -7,22 +7,23 @@
  * their own runner all use the same definitions and the same parsing.
  *
  * `checked` marks a verb the runner throws for on a non-zero exit, with
- * stderr. That is every mutation, and `prDiff`, which is a read. Other
- * queries run unchecked, and `parse` turns a failure into `null`, which is
- * what `soft` returns. The clients' methods that throw read them through
- * `settle` (see `doors.ts`) instead. There a failure throws, except where the
- * verb declares `absent` or is a `probe`.
+ * stderr. That is every mutation, `prDiff`, which is a read, and
+ * `rawChecked`. Other queries run unchecked, and `parse` turns a failure into
+ * `null`, which is what `soft` returns. The clients' methods that throw read
+ * them through `settle` (see `doors.ts`) instead. There a failure throws,
+ * except where the verb declares `absent` or is a `probe`.
  */
 import { type CommandResult } from '@osdlc/command-seam';
 import type { IssueRow, Label, PrSearchHit, PullRequest, Repository } from './types.ts';
 /** One `gh` invocation: what to run, and how to read what came back. */
 export interface GhVerb<T> {
     argv: string[];
-    /** True for every mutation and for `prDiff`: throw on a non-zero exit instead of parsing. */
+    /** True for every mutation, `prDiff` and `rawChecked`: throw on a non-zero exit instead of parsing. */
     checked: boolean;
     /**
      * True when the call only reads and changes nothing on GitHub. Every query
-     * is read-only, and so is `prDiff`. No mutation is. A caller that
+     * is read-only, and so is `prDiff`. No mutation is, and neither are `raw`
+     * and `rawChecked`, whose argv the library cannot judge. A caller that
      * keeps an allowlist of safe calls can check this before running a verb.
      */
     readOnly: boolean;
@@ -34,10 +35,10 @@ export interface GhVerb<T> {
      */
     env?: Record<string, string> | undefined;
     /**
-     * True for a read whose failure is part of its answer. `installed`,
-     * `authStatus` and `api` return what `parse` makes of any result, from the
-     * plain method and from `try`; they have no soft form. Other reads throw
-     * from the plain method when gh exits non-zero.
+     * True for a call whose failure is part of its answer. `installed`,
+     * `authStatus`, `api` and `raw` return what `parse` makes of any result,
+     * from the plain method and from `try`; they have no soft form. Other reads
+     * throw from the plain method when gh exits non-zero.
      */
     probe?: boolean | undefined;
     /**
@@ -507,6 +508,21 @@ export interface CreateReviewOptions {
  * @experimental
  */
 export declare function createReview(number: number, opts: CreateReviewOptions, target?: GhTarget): GhVerb<string>;
+/**
+ * Any `gh` call, as a verb whose value is the `CommandResult`, whatever the
+ * exit code: `Gh.raw` as data. It adds no `--repo` and no host, so put them
+ * in `argv`. It is a `probe`, so `runVerb` returns a failed or cut-short
+ * result rather than throwing, and it is not `readOnly`, since the library
+ * cannot tell what `argv` does.
+ */
+export declare function raw(argv: readonly string[]): GhVerb<CommandResult>;
+/**
+ * {@link raw}, checked: `Gh.rawChecked` as data. `runVerb` returns the
+ * `CommandResult` when gh exits 0 with its whole output, and otherwise throws
+ * a `FailureError` carrying the classified `GhFailure`. So a tool that runs
+ * one call the verb table lacks needs no `Gh` for it.
+ */
+export declare function rawChecked(argv: readonly string[]): GhVerb<CommandResult>;
 /**
  * The first row whose `headRefName` exactly equals `branch`, or null.
  *

package/dist/verbs.js

@@ -7,11 +7,11 @@
  * their own runner all use the same definitions and the same parsing.
  *
  * `checked` marks a verb the runner throws for on a non-zero exit, with
- * stderr. That is every mutation, and `prDiff`, which is a read. Other
- * queries run unchecked, and `parse` turns a failure into `null`, which is
- * what `soft` returns. The clients' methods that throw read them through
- * `settle` (see `doors.ts`) instead. There a failure throws, except where the
- * verb declares `absent` or is a `probe`.
+ * stderr. That is every mutation, `prDiff`, which is a read, and
+ * `rawChecked`. Other queries run unchecked, and `parse` turns a failure into
+ * `null`, which is what `soft` returns. The clients' methods that throw read
+ * them through `settle` (see `doors.ts`) instead. There a failure throws,
+ * except where the verb declares `absent` or is a `probe`.
  */
 import { notAnOption, stderrOrError } from '@osdlc/command-seam';
 import { parseLabels, parsePrSearchHit, parsePullRequest, parseRepository } from "./parse.js";
@@ -1098,6 +1098,26 @@ export function createReview(number, opts, target) {
         },
     };
 }
+// ── raw calls ───────────────────────────────────────────────────────────────
+/**
+ * Any `gh` call, as a verb whose value is the `CommandResult`, whatever the
+ * exit code: `Gh.raw` as data. It adds no `--repo` and no host, so put them
+ * in `argv`. It is a `probe`, so `runVerb` returns a failed or cut-short
+ * result rather than throwing, and it is not `readOnly`, since the library
+ * cannot tell what `argv` does.
+ */
+export function raw(argv) {
+    return { argv: [...argv], checked: false, readOnly: false, probe: true, parse: (r) => r };
+}
+/**
+ * {@link raw}, checked: `Gh.rawChecked` as data. `runVerb` returns the
+ * `CommandResult` when gh exits 0 with its whole output, and otherwise throws
+ * a `FailureError` carrying the classified `GhFailure`. So a tool that runs
+ * one call the verb table lacks needs no `Gh` for it.
+ */
+export function rawChecked(argv) {
+    return { argv: [...argv], checked: true, readOnly: false, parse: (r) => r };
+}
 // ── helpers over the parsed rows ────────────────────────────────────────────
 /**
  * The first row whose `headRefName` exactly equals `branch`, or null.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/typed-gh",
-  "version": "0.15.0",
+  "version": "0.16.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",
@@ -56,6 +56,7 @@
     "@vitest/coverage-v8": "^5.0.5",
     "oxlint": "^1.65.0",
     "prettier": "3.9.6",
+    "rolldown": "^1.2.14",
     "typescript": "~6.0.3",
     "vitest": "^5.0.5",
     "@osdlc/prettier-config": "^0.3.1",