@osdlc/typed-gh 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @osdlc/typed-gh
 
+## 0.15.0
+
+### Minor Changes
+
+- 4f764b7: `graphql` (experimental): fill the target's owner or repo name with the new `fromTarget('owner')` / `fromTarget('repo')` markers. **Breaking for `graphql` callers:** a plain string variable is now always sent as written, so a real value of `{owner}` or `{repo}` (a branch name, say) is no longer replaced. Change `{ owner: '{owner}', name: '{repo}' }` to `{ owner: fromTarget('owner'), name: fromTarget('repo') }`. REST endpoints keep the `{owner}/{repo}` path template, which mirrors gh's own syntax.
+
 ## 0.14.1
 
 ### Patch Changes

package/README.md

@@ -466,6 +466,9 @@ 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
 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
+`{owner}`.
 
 ```ts
 const query = `query($owner: String!, $name: String!, $endCursor: String) {
@@ -476,7 +479,11 @@ const query = `query($owner: String!, $name: String!, $endCursor: String) {
     }
   }
 }`
-const pages = gh.graphql(query, { owner: '{owner}', name: '{repo}' }, { paginate: true })
+const pages = gh.graphql(
+  query,
+  { owner: fromTarget('owner'), name: fromTarget('repo') },
+  { paginate: true },
+)
 const prs = nodesAt(pages, ['repository', 'pullRequests'])
 ```
 
@@ -663,6 +670,7 @@ The experimental items:
 - `nodesAt`
 - `GraphqlOptions`
 - `GraphqlVariable`
+- `fromTarget` and `FromTarget`
 
 Every other export and method is stable, `prDiff` included. So is `@osdlc/typed-gh/testing`: its
 builders and their row types. Their default values may change in any minor release.

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, 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 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, 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, 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, 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/verbs.d.ts

@@ -223,11 +223,34 @@ export interface ApiOptions {
  */
 export declare function api(endpoint: string, opts?: ApiOptions, target?: GhTarget): GhVerb<ApiResponse>;
 /**
- * A GraphQL variable. gh sends a string with `-f` and the rest with `-F`.
+ * A GraphQL variable filled from the target's repository: its owner, or its
+ * name. Make one with {@link fromTarget}.
  *
  * @experimental
  */
-export type GraphqlVariable = string | number | boolean | null;
+export interface FromTarget {
+    readonly fromTarget: 'owner' | 'repo';
+}
+/**
+ * A {@link graphql} variable that holds the target repository's owner or
+ * name. With a target repo, the value comes from it. Without one, gh fills
+ * it from the clone's repository. A plain string is always sent as written,
+ * so a real value of `{owner}` stays `{owner}`.
+ *
+ * ```ts
+ * gh.graphql(query, { owner: fromTarget('owner'), name: fromTarget('repo') })
+ * ```
+ *
+ * @experimental
+ */
+export declare function fromTarget(part: 'owner' | 'repo'): FromTarget;
+/**
+ * A GraphQL variable. gh sends a string with `-f`, as written, and the rest
+ * with `-F`. A {@link FromTarget} is filled from the target's repository.
+ *
+ * @experimental
+ */
+export type GraphqlVariable = string | number | boolean | null | FromTarget;
 /**
  * Options for {@link graphql}.
  *
@@ -249,8 +272,8 @@ export interface GraphqlOptions {
  * carries `errors` or lacks `data`. A partial answer counts as a failure. Read one
  * connection across the pages with {@link nodesAt}.
  *
- * A string variable of exactly `{owner}` or `{repo}` is filled from the
- * target's repo, or by gh from the clone. A document holding any mutation or
+ * 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`.

package/dist/verbs.js

@@ -410,6 +410,24 @@ function flattenPages(body) {
         return body;
     return body.flat();
 }
+/**
+ * A {@link graphql} variable that holds the target repository's owner or
+ * name. With a target repo, the value comes from it. Without one, gh fills
+ * it from the clone's repository. A plain string is always sent as written,
+ * so a real value of `{owner}` stays `{owner}`.
+ *
+ * ```ts
+ * gh.graphql(query, { owner: fromTarget('owner'), name: fromTarget('repo') })
+ * ```
+ *
+ * @experimental
+ */
+export function fromTarget(part) {
+    if (part !== 'owner' && part !== 'repo') {
+        throw new RangeError(`fromTarget: expected 'owner' or 'repo', got ${JSON.stringify(part)}`);
+    }
+    return Object.freeze({ fromTarget: part });
+}
 /**
  * True when any operation in a GraphQL document is a `mutation` or a
  * `subscription`. Strings and comments are dropped first, and only the words
@@ -439,8 +457,8 @@ function writesOrStreams(document) {
  * carries `errors` or lacks `data`. A partial answer counts as a failure. Read one
  * connection across the pages with {@link nodesAt}.
  *
- * A string variable of exactly `{owner}` or `{repo}` is filled from the
- * target's repo, or by gh from the clone. A document holding any mutation or
+ * 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`.
@@ -467,14 +485,20 @@ export function graphql(query, variables = {}, opts = {}, target) {
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || key === 'query' || key === 'operationName') {
             throw new RangeError(`graphql: bad variable name ${JSON.stringify(key)}`);
         }
-        if (typeof value === 'string') {
-            const filled = value === '{owner}' ? owner : value === '{repo}' ? name : undefined;
+        if (typeof value === 'object' && value !== null) {
+            const part = value.fromTarget;
+            if (part !== 'owner' && part !== 'repo') {
+                throw new RangeError(`graphql: variable ${key} is not a fromTarget marker`);
+            }
+            const filled = part === 'owner' ? owner : name;
+            // `-F` lets gh fill the placeholder from the clone; `-f` never fills.
             if (filled !== undefined)
                 argv.push('-f', `${key}=${filled}`);
-            else if (value === '{owner}' || value === '{repo}')
-                argv.push('-F', `${key}=${value}`);
             else
-                argv.push('-f', `${key}=${value}`);
+                argv.push('-F', `${key}={${part}}`);
+        }
+        else if (typeof value === 'string') {
+            argv.push('-f', `${key}=${value}`);
         }
         else {
             argv.push('-F', `${key}=${value === null ? 'null' : String(value)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/typed-gh",
-  "version": "0.14.1",
+  "version": "0.15.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",