@effected/github 0.15.1 → 0.17.0

package/README.md

@@ -25,7 +25,7 @@ Hand-rolled octokit wrappers tend to converge on the same shape: a `rest<T>(oper
 
 The error model gets the same treatment. `GitHubError.kind` is a literal union (`notFound`, `alreadyExists`, `rejected`, `unauthorized`, `rateLimited`, `transport`, `decode`) produced by one classification step, `GitHubError.fromOctokit`, instead of one hand-written mapper per resource. `kind: "alreadyExists"` is what makes `GitBranch.upsert` and `GitTag.upsert` a single round trip in the common case, rather than a create-then-catch-then-check-then-reset dance repeated at every call site that needs it.
 
-This package also owns the octokit runtime so nothing downstream has to. `@octokit/rest` and `@octokit/auth-app` are deliberately absent — the rest wrapper is a request-logging plugin plus 1.4 MB of duplicate endpoint types, and `auth-app` drags in `createOAuthUserAuth`, roughly 492 KB of OAuth machinery this package never calls. GitHub App JWTs are signed by `universal-github-app-jwt` instead, the same zero-dependency signer `@octokit/auth-app` itself uses. A consumer that only authenticates with a token it already holds never links the JWT signer at all: the App-authenticated layer lives in its own module (`GitHubApp`), and nothing here is gathered into a namespace object that would defeat that split.
+This package also owns the octokit runtime so nothing downstream has to. `@octokit/rest` and `@octokit/auth-app` are deliberately absent — the rest wrapper is a request-logging plugin plus 1.4 MB of duplicate endpoint types, and `auth-app` drags in `createOAuthUserAuth`, roughly 492 KB of OAuth machinery this package never calls. GitHub App JWTs are signed by the kit's own `@effected/jwt` instead: WebCrypto RS256 with no runtime dependencies, so App auth runs on Cloudflare Workers as well as Node. A consumer that only authenticates with a token it already holds never links the JWT signer at all: the App-authenticated layer lives in its own module (`GitHubApp`), and nothing here is gathered into a namespace object that would defeat that split.
 
 ## Install
 

package/Repo.js

@@ -16,6 +16,15 @@ input: Schema.String }) {
 /**
 * Which repository an operation acts on.
 *
+* @remarks
+* **`RepoRef.make` validates at construction and throws** on an empty `owner`
+* or `repo`, so inside an `Effect` a bad value dies rather than failing. That
+* is right for a coordinate the program itself spells out, and wrong for one
+* built from data: for a slug read from a database row, a config file or a
+* webhook, use {@link RepoRef.parse}, which fails with a typed
+* {@link InvalidRepoRefError} instead (or {@link RepoRef.parseResult}
+* outside an `Effect`).
+*
 * @public
 */
 var RepoRef = class RepoRef extends Schema.Class("RepoRef")({
@@ -41,7 +50,13 @@ var RepoRef = class RepoRef extends Schema.Class("RepoRef")({
 			repo
 		}));
 	}
-	/** Parse `"owner/repo"`. */
+	/**
+	* Parse `"owner/repo"`, failing with a typed {@link InvalidRepoRefError}.
+	*
+	* @remarks
+	* The typed path for building a `Repo` from stored data, such as a stored
+	* `full_name`: a malformed value fails here, where `make` would die.
+	*/
 	static parse = Effect.fn("RepoRef.parse")((slug) => Effect.fromResult(RepoRef.parseResult(slug)));
 	/** `"owner/repo"`. */
 	get slug() {

package/WorkflowDispatch.js

@@ -26,6 +26,24 @@ var WorkflowRunStatus = class extends Schema.Class("WorkflowRunStatus")({
 		return this.status === "completed";
 	}
 };
+/**
+* The run a `workflow_dispatch` created, as GitHub reports it when asked.
+*
+* @remarks
+* Returned by {@link WorkflowDispatchShape.dispatchWithRun}. `runId` is usable
+* directly with {@link WorkflowDispatchShape.runStatus} and
+* {@link WorkflowDispatchShape.cancelRun}.
+*
+* @public
+*/
+var DispatchedRun = class extends Schema.Class("DispatchedRun")({
+	/** The created run's numeric id. */
+	runId: Schema.Int,
+	/** The run's API URL. */
+	runUrl: Schema.String,
+	/** The run's web URL. */
+	htmlUrl: Schema.String
+}) {};
 const DEFAULT_INTERVAL = Duration.seconds(10);
 const DEFAULT_TIMEOUT = Duration.minutes(5);
 /**
@@ -60,7 +78,9 @@ var WorkflowDispatch = class WorkflowDispatch extends Context.Service()("@effect
 	/** An in-memory double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({
 		dispatch: overrides.dispatch ?? (() => unstubbed("dispatch")),
+		dispatchWithRun: overrides.dispatchWithRun ?? (() => unstubbed("dispatchWithRun")),
 		runStatus: overrides.runStatus ?? (() => unstubbed("runStatus")),
+		cancelRun: overrides.cancelRun ?? (() => unstubbed("cancelRun")),
 		list: overrides.list ?? Effect.sync(() => unstubbed("list")),
 		dispatchAndWait: overrides.dispatchAndWait ?? (() => unstubbed("dispatchAndWait"))
 	});
@@ -76,6 +96,14 @@ const statusOf = (raw) => WorkflowRunStatus.make({
 	...raw.conclusion != null ? { conclusion: raw.conclusion } : {},
 	url: raw.html_url
 });
+/** GitHub's `workflow-dispatch-response`; the id is `number | bigint` in the generated types. */
+const DispatchResponse = Schema.Struct({
+	workflow_run_id: Schema.Union([Schema.Number, Schema.BigInt]),
+	run_url: Schema.String,
+	html_url: Schema.String
+});
+const decodeDispatchResponse = Schema.decodeUnknownEffect(DispatchResponse);
+const decodeDispatchedRun = Schema.decodeUnknownEffect(DispatchedRun);
 const make = (client) => {
 	const dispatch = Effect.fn("WorkflowDispatch.dispatch")(function* (workflow, ref, inputs) {
 		const { owner, repo } = yield* Repo;
@@ -93,38 +121,78 @@ const make = (client) => {
 			...inputs !== void 0 ? { inputs } : {}
 		});
 	});
+	const dispatchWithRun = Effect.fn("WorkflowDispatch.dispatchWithRun")(function* (workflow, ref, inputs) {
+		const { owner, repo } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({
+			owner,
+			repo,
+			workflow,
+			ref
+		});
+		const data = yield* client.request("POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches", {
+			owner,
+			repo,
+			workflow_id: workflow,
+			ref,
+			...inputs !== void 0 ? { inputs } : {},
+			return_run_details: true
+		});
+		if (data === "" || data === null) return Option.none();
+		const run = yield* decodeDispatchResponse(data).pipe(Effect.flatMap((raw) => decodeDispatchedRun({
+			runId: numericId(raw.workflow_run_id),
+			runUrl: raw.run_url,
+			htmlUrl: raw.html_url
+		})), Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubError.decode("WorkflowDispatch.dispatchWithRun", "GitHub returned unexpected run details", error))));
+		return Option.some(run);
+	});
+	const runStatus = Effect.fn("WorkflowDispatch.runStatus")(function* (runId) {
+		const { owner, repo } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({
+			owner,
+			repo,
+			runId
+		});
+		const raw = yield* client.request("GET /repos/{owner}/{repo}/actions/runs/{run_id}", {
+			owner,
+			repo,
+			run_id: runId
+		});
+		return statusOf(raw);
+	});
+	const list = Effect.fn("WorkflowDispatch.list")(function* () {
+		const { owner, repo } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({
+			owner,
+			repo
+		});
+		return (yield* client.paginate("GET /repos/{owner}/{repo}/actions/workflows", {
+			owner,
+			repo
+		})).map((workflow) => ({
+			id: workflow.id,
+			name: workflow.name,
+			path: workflow.path,
+			state: workflow.state
+		}));
+	});
 	return {
 		dispatch,
-		runStatus: Effect.fn("WorkflowDispatch.runStatus")(function* (runId) {
+		dispatchWithRun,
+		runStatus,
+		cancelRun: Effect.fn("WorkflowDispatch.cancelRun")(function* (runId) {
 			const { owner, repo } = yield* Repo;
 			yield* Effect.annotateCurrentSpan({
 				owner,
 				repo,
 				runId
 			});
-			const raw = yield* client.request("GET /repos/{owner}/{repo}/actions/runs/{run_id}", {
+			return yield* client.request("POST /repos/{owner}/{repo}/actions/runs/{run_id}/cancel", {
 				owner,
 				repo,
 				run_id: runId
-			});
-			return statusOf(raw);
+			}).pipe(Effect.as("cancelled"), Effect.catchIf((error) => error.status === 409, () => Effect.succeed("alreadyCompleted")));
 		}),
-		list: Effect.fn("WorkflowDispatch.list")(function* () {
-			const { owner, repo } = yield* Repo;
-			yield* Effect.annotateCurrentSpan({
-				owner,
-				repo
-			});
-			return (yield* client.paginate("GET /repos/{owner}/{repo}/actions/workflows", {
-				owner,
-				repo
-			})).map((workflow) => ({
-				id: workflow.id,
-				name: workflow.name,
-				path: workflow.path,
-				state: workflow.state
-			}));
-		})(),
+		list: list(),
 		dispatchAndWait: Effect.fn("WorkflowDispatch.dispatchAndWait")(function* (workflow, ref, options) {
 			const { owner, repo } = yield* Repo;
 			const interval = options?.poll?.interval ?? DEFAULT_INTERVAL;
@@ -138,8 +206,8 @@ const make = (client) => {
 				attempts
 			});
 			const dispatchedAt = new Date(yield* Clock.currentTimeMillis).toISOString();
-			yield* dispatch(workflow, ref, options?.inputs);
-			const findRun = Effect.gen(function* () {
+			const dispatched = yield* dispatchWithRun(workflow, ref, options?.inputs);
+			const findRun = Option.isSome(dispatched) ? Effect.map(runStatus(dispatched.value.runId), Option.some) : Effect.gen(function* () {
 				const match = (yield* client.paginate("GET /repos/{owner}/{repo}/actions/runs", {
 					owner,
 					repo,
@@ -163,4 +231,4 @@ const make = (client) => {
 };
 
 //#endregion
-export { WorkflowDispatch, WorkflowRunStatus };
+export { DispatchedRun, WorkflowDispatch, WorkflowRunStatus };