@graphty/graphty-element / session / Run
Interface: Run<T> ​
Defined in: graphty-element/src/session/runs/types.ts:532
A started computation.
A run is a PromiseLike, NOT a Promise subclass, and the element attaches a no-op rejection handler to the promise behind it. The two together are what make an element driven by clicks, a console and an agent safe to use: a run fired from a click handler and never awaited cannot produce an unhandled rejection, while await run still throws. Subclassing Promise would give the opposite -- every unawaited failure reaching the window as an unhandled rejection -- and there is no way to have both.
What a rejection means is fixed, so a consumer can tell the three cases apart without parsing a message:
cancel()and an abortedsignalreject with aDOMExceptionnamedAbortError, which is what every consumer already knows how to test for.AbortSignal.timeout()rejects with aDOMExceptionnamedTimeoutError, so a timeout is distinguishable from somebody pressing Cancel.- Everything else rejects with a GraphtyError carrying a code.
A time boxed run that hits its box does not reject at all: it RESOLVES, with partial set and caveats.partialReason saying why. A stopped-early result is data.
Extends ​
PromiseLike<T>
Type Parameters ​
T ​
T = RunResult
Properties ​
algorithm ​
readonlyalgorithm:AlgorithmKey
Defined in: graphty-element/src/session/runs/types.ts:545
Which algorithm is running.
cancellable ​
readonlycancellable:boolean
Defined in: graphty-element/src/session/runs/types.ts:557
Whether it can be stopped. Distinct from whether it HAS been stopped.
caveats ​
readonlycaveats:Caveats
Defined in: graphty-element/src/session/runs/types.ts:578
What qualifies the numbers.
determinate ​
readonlydeterminate:boolean
Defined in: graphty-element/src/session/runs/types.ts:555
Whether the total is knowable, so a consumer can choose a bar or a spinner.
durationMs ​
readonlydurationMs:number|null
Defined in: graphty-element/src/session/runs/types.ts:563
How long it took, in milliseconds, or null until it finishes.
engine ​
readonlyengine:EngineVersions
Defined in: graphty-element/src/session/runs/types.ts:572
Which versions produced the numbers.
error? ​
readonlyoptionalerror?:GraphtyError
Defined in: graphty-element/src/session/runs/types.ts:590
Why it failed, when it failed. Optional-or-undefined for the reason Run.result gives.
fields ​
readonlyfields: readonlyFieldDescriptor[]
Defined in: graphty-element/src/session/runs/types.ts:574
The fields it publishes.
id ​
readonlyid:string
Defined in: graphty-element/src/session/runs/types.ts:534
The run id: stable, selector-safe, and author-assignable through as.
journalId ​
readonlyjournalId:string|null
Defined in: graphty-element/src/session/runs/types.ts:597
The journal entry this run's command wrote (session.journal.get(run.journalId)), or null until the command has finished. A re-run points it at the newer entry.
label ​
readonlylabel:string
Defined in: graphty-element/src/session/runs/types.ts:543
What to call the run.
Computed by the element, never by the consumer: the algorithm's plain name on its own while it is the only run of that algorithm, gaining the parameter that differs in parentheses the moment a sibling exists. One string, used by the layer row, the legend, the journal and every export.
params ​
readonlyparams:Readonly<Record<string,unknown>>
Defined in: graphty-element/src/session/runs/types.ts:547
The parameters it is running with, canonicalised.
partial ​
readonlypartial:boolean
Defined in: graphty-element/src/session/runs/types.ts:568
Whether it stopped early and published what it had. Not a failure. True exactly when caveats.partialReason is set, whatever stopped it -- a time box or an iteration cap.
progress ​
readonlyprogress:Progress
Defined in: graphty-element/src/session/runs/types.ts:553
How far along it is.
queuePosition ​
readonlyqueuePosition:number|null
Defined in: graphty-element/src/session/runs/types.ts:559
Its place in the queue, counting from 0, or null when it is not waiting.
record ​
readonlyrecord:RunRecord
Defined in: graphty-element/src/session/runs/types.ts:592
The frozen, structured-cloneable snapshot of everything above.
result? ​
readonlyoptionalresult?:T
Defined in: graphty-element/src/session/runs/types.ts:588
The result, once there is one. Awaiting the run is the other way to get it. Undefined again once undo has taken the run out of the project (status "removed"); a redo brings the same result object back.
Spelled ?: T | undefined rather than ?: T because the implementation answers with a getter, and under a consumer's exactOptionalPropertyTypes a getter that can return undefined does not satisfy a property that can only be absent or present.
scope ​
readonlyscope:ResolvedScope
Defined in: graphty-element/src/session/runs/types.ts:549
What it is allowed to look at, resolved against the graph as it stood when it started.
shape ​
readonlyshape:"node-metric"|"edge-metric"|"community"|"layered-grouping"|"category-table"|"path"|"node-set"|"edge-set"|"pair-list"|"temporal"|"fact"
Defined in: graphty-element/src/session/runs/types.ts:576
The shape, which fixes those field names.
stale ​
readonlystale:StaleNote|null
Defined in: graphty-element/src/session/runs/types.ts:570
Why its numbers no longer describe what is on screen, when they do not.
startedAt ​
readonlystartedAt:string|null
Defined in: graphty-element/src/session/runs/types.ts:561
When it started, as an ISO 8601 timestamp, or null while it is still queued.
status ​
readonlystatus:"succeeded"|"failed"|"removed"|"queued"|"running"|"canceled"
Defined in: graphty-element/src/session/runs/types.ts:551
Where it has got to.
Methods ​
cancel() ​
cancel(
reason?):void
Defined in: graphty-element/src/session/runs/types.ts:605
Stop the run.
The promise rejects with a DOMException named AbortError. Calling this on a run that has already finished does nothing.
Parameters ​
reason? ​
string
Why, for the journal and for an error message.
Returns ​
void
rerun() ​
rerun():
Run<T>
Defined in: graphty-element/src/session/runs/types.ts:615
Run it again, in place.
The new run keeps the SAME id, so every style layer, legend and saved reference bound to it survives. That is what "re-run from a layer" needs, and it is why a binding never dangles after a re-run. The last result stays readable until the new one is recorded, and undoing the re-run puts the previous result back without computing it again.
Returns ​
Run<T>
The run, which is this one restarted rather than a second entry.
suggestEncodings() ​
suggestEncodings(): readonly
StyleSuggestion[]
Defined in: graphty-element/src/session/runs/types.ts:631
What this run suggests be drawn from it.
Derived from the run's own shape and the fields it published, never from a block of styling written per algorithm: a measurement suggests a colour over the elements it measured, a grouping suggests a categorical colour, a route or a chosen set suggests a highlight, and a table of pairs, a time series or a bare fact suggests nothing at all.
The element applies these itself on a run's first completion unless { style: false } was asked for. Reading them is for a consumer that wants to show what WOULD be painted, apply it at another moment, or alter the taste before it lands -- each suggestion is the specification styles.encode() or styles.highlight() takes, with its taste left unsaid so the element's own defaults settle it.
Returns ​
readonly StyleSuggestion[]
The suggestions, empty when the result is read rather than painted.