Skip to content

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 }
FieldPresent onHolds
statusboth'done' or 'held'; narrow on it
valuedoneThe operation's usual answer
heldheldThe id of the held request
urlheldAn absolute address where a person decides it; the server's path resolved against the client's host, /requests when the server named none
messageheldThe 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.

kindTarget fieldsuntil
pullowner, repo, numberchecks, merged or reviewed
runowner, repo, id (a number)not used; a run is waited on until it finishes
caissonowner, id (a string)the state to reach: editing, waiting, review, merged or stopped
issueowner, repo, numberopen, closed, or a status such as in-review or done
heldowner (the organization), idnot used; a held request is waited on until it is decided
OptionMeaning
untilAs above
withinSeconds to wait in all before answering pending. Default 600
signal, timeout, maxRetries, idempotencyKey, headersThe usual request options. timeout is in milliseconds and applies to each window; it defaults to the window plus 15 seconds
WaitAnswer fieldHolds
statemet, failed, pending (within ran out first) or none (there is nothing to wait for, such as a repository with no CI)
detailThe target's state in words, such as merged or approved
conditionWhat was waited for, such as #128 merged
valueWhat the server last read, typed unknown: the pull request, the checks summary, the run, the held request
baselineWhat 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.

Loading Sailfork