Held writes and waits (TypeScript)
Handle writes that wait for a person with the Result, Done and Held types of the TypeScript SDK, and hold for checks, merges and decisions with sf.wait.
Some writes wait for a person, and some code has to wait for the world. This page covers the Result type for the first and sf.wait for the second.
Writes held for a person
A few operations can be held. When an organization's agent permissions hold the write, the call does not throw. It resolves to a Held result, and the same call without a hold resolves to a Done result. Only pulls.merge and pulls.autoMergeEnable (on sf.pulls, repo.pulls and PullRequest) are typed this way today; every other method returns its data directly.
import type { Done, HeldOutcome, Result, types } from 'sailfork';
type MergeResult = Result<types.Pull>;
type Merged = Done<types.Pull>; // { status: 'done'; value: types.Pull }
type Waiting = HeldOutcome; // { status: 'held'; held: string; url: string; message: string } | Field | Present on | Holds |
|---|---|---|
status | both | 'done' or 'held'; narrow on it |
value | done | The operation's usual answer |
held | held | The id of the held request |
url | held | An absolute address where a person decides it; the server's path resolved against the client's host, /requests when the server named none |
message | held | The server's sentence, which starts HELD FOR A PERSON |
import Sailfork from 'sailfork';
const sf = new Sailfork();
const pr = sf.repo('acme/api').pull(128);
const merge = await pr.merge();
if (merge.status === 'held') {
console.log(merge.message);
console.log(`decide it at ${merge.url} (request ${merge.held})`);
} else {
console.log(`merged: ${merge.value.state}`);
} An agent cannot approve its own request. Hand url to a person, wait for the decision with sf.wait({ kind: 'held', ... }), then call again. A decline makes the repeated call throw an AgentPolicyError with code held_declined. The list of your own requests is sf.held.mine(), which answers { pending, decided }.
import Sailfork from 'sailfork';
const sf = new Sailfork();
const { pending, decided } = await sf.held.mine();
for (const request of pending) console.log(request.id, request.kind, request.summary);
console.log(decided.length); Writes through a caisson that a path rule holds do not use Result. They change the caisson's state to waiting; see Writes held for a person.
Wait for something to happen
sf.wait(target, options?) holds until the thing reaches the state you ask for, or within seconds pass, and answers a WaitAnswer. It is one call to you and several requests underneath: each is a window of at most 55 seconds, and the client carries the server's baseline from one window to the next. It does not poll. See Wait for a change for the route.
kind | Target fields | until |
|---|---|---|
pull | owner, repo, number | checks, merged or reviewed |
run | owner, repo, id (a number) | not used; a run is waited on until it finishes |
caisson | owner, id (a string) | the state to reach: editing, waiting, review, merged or stopped |
issue | owner, repo, number | open, closed, or a status such as in-review or done |
held | owner (the organization), id | not used; a held request is waited on until it is decided |
| Option | Meaning |
|---|---|
until | As above |
within | Seconds to wait in all before answering pending. Default 600 |
signal, timeout, maxRetries, idempotencyKey, headers | The usual request options. timeout is in milliseconds and applies to each window; it defaults to the window plus 15 seconds |
WaitAnswer field | Holds |
|---|---|
state | met, failed, pending (within ran out first) or none (there is nothing to wait for, such as a repository with no CI) |
detail | The target's state in words, such as merged or approved |
condition | What was waited for, such as #128 merged |
value | What the server last read, typed unknown: the pull request, the checks summary, the run, the held request |
baseline | What the next window is compared against. The client passes it back for you |
failed means the target can no longer reach the state: a pull request closed without merging, a failed check, a failed run. A pending answer is not an error.
import Sailfork from 'sailfork';
const sf = new Sailfork();
const repo = { owner: 'acme', repo: 'api' };
const checks = await sf.wait({ kind: 'pull', ...repo, number: 128 }, { until: 'checks', within: 900 });
const merged = await sf.wait({ kind: 'pull', ...repo, number: 128 }, { until: 'merged', within: 60 });
const reviewed = await sf.wait({ kind: 'pull', ...repo, number: 128 }, { until: 'reviewed', within: 600 });
const run = await sf.wait({ kind: 'run', ...repo, id: 1804 }, { within: 1200 });
const caisson = await sf.wait({ kind: 'caisson', owner: 'acme', id: 'c-z4nwicj7' }, { until: 'review' });
const issue = await sf.wait({ kind: 'issue', ...repo, number: 42 }, { until: 'closed', within: 300 });
const decision = await sf.wait({ kind: 'held', owner: 'acme', id: '31068dbe-d36e-4c70-a706-47fdb8f535ed' }, { within: 3600 });
for (const answer of [checks, merged, reviewed, run, caisson, issue, decision]) {
console.log(answer.state, answer.condition, answer.detail);
} Stop a long wait with a signal. The aborted call throws the signal's reason.
import Sailfork from 'sailfork';
const sf = new Sailfork();
const stop = new AbortController();
setTimeout(() => stop.abort(new Error('gave up')), 120_000);
const answer = await sf.wait({ kind: 'pull', owner: 'acme', repo: 'api', number: 128 }, { until: 'checks', within: 900, signal: stop.signal }); sf.waits.wait(input) is the raw single-window operation, for code that wants to manage waited and baseline itself.
The same topic for Python: Python held writes and waits.