@graphty/graphty-element / session / GraphSession
Interface: GraphSession ​
Defined in: graphty-element/src/session/types.ts:1832
A graph with no view attached.
The session holds the graph data, the coordinates, the runs and their results, the scope, selection and visibility models, the style layers, the status, the catalogue, the configuration and the measured capabilities of the machine. A renderer binds to one; a Node test uses one on its own; two synchronised views of one dataset share one.
What is deliberately NOT here yet: the layout transport. It waits on work that has not landed, and is absent rather than stubbed.
Properties ​
acceleration ​
acceleration:
AccelerationPolicy
Defined in: graphty-element/src/session/types.ts:1935
What the consumer asks of the hardware: use an accelerator when there is one, never look, or refuse to run without one.
Settable, and the set applies at once: the next piece of accelerated work is planned under the new policy, and capabilities:changed reports where that left the hardware.
canRedo ​
readonlycanRedo:boolean
Defined in: graphty-element/src/session/types.ts:2015
Whether redo() would do something.
canUndo ​
readonlycanUndo:boolean
Defined in: graphty-element/src/session/types.ts:2013
Whether undo() would do something: undo a step or cancel pending work.
capabilities ​
readonlycapabilities:AccelerationCapabilities
Defined in: graphty-element/src/session/types.ts:1927
What this machine can do, measured rather than guessed at by the consumer.
catalog ​
readonlycatalog:SessionCatalogApi
Defined in: graphty-element/src/session/types.ts:1923
Everything the element can offer, as data.
config ​
readonlyconfig:SessionConfig
Defined in: graphty-element/src/session/types.ts:1925
The settings as they are now, and set to change the project ones.
data ​
readonlydata:SessionDataApi
Defined in: graphty-element/src/session/types.ts:1834
Reading the graph.
history ​
readonlyhistory:SessionHistory
Defined in: graphty-element/src/session/types.ts:2017
The steps, the cursor, the pending work and the budget.
journal ​
readonlyjournal:JournalApi
Defined in: graphty-element/src/session/types.ts:1864
The record of the commands this session ran, oldest first: one entry per command that finished, published as journal:appended. A run's journalId names the entry its command wrote. Undo does not read it; history is the undo record.
layout ​
readonlylayout:SessionLayout
Defined in: graphty-element/src/session/types.ts:1900
Which layout draws the graph, and in how many dimensions; choosing either is a step.
notes ​
readonlynotes:NotesApi
Defined in: graphty-element/src/session/types.ts:1858
The notes: text people write about the graph, its nodes and edges, kept sets and results. Every write is one undoable step and is published as note:changed; graphty-element stores a note's text exactly as given and never interprets it.
positions ​
readonlypositions:SessionPositions
Defined in: graphty-element/src/session/types.ts:1910
The element-owned node coordinates, read by dense node index, where a row no layout has placed reads as unplaced rather than at the origin, with the verbs that place and pin nodes as undoable steps.
Place and pin through set, pin and unpin; the coordinates themselves are read-only here, because a layout, a drag and a GPU readback write them and a write made there is not a step.
project ​
readonlyproject:ProjectApi
Defined in: graphty-element/src/session/types.ts:2019
Saving the whole session to one project file and opening one again.
results ​
readonlyresults:ResultsApi
Defined in: graphty-element/src/session/types.ts:1838
Addressing what a run produced: the path, the lookup and the completion list.
runs ​
readonlyruns:RunsApi
Defined in: graphty-element/src/session/types.ts:1836
Starting computations, watching them, stopping them, and finding them again.
scope ​
readonlyscope:ScopeApi
Defined in: graphty-element/src/session/types.ts:1843
Which elements a piece of work is allowed to look at: resolving a specification, counting it without resolving it, and keeping one under a name.
seededNodeCount ​
readonlyseededNodeCount:number
Defined in: graphty-element/src/session/types.ts:1919
How many nodes the DATA arrived carrying a coordinate for.
Ask this, not positions.placedCount, whenever the question is "did the file place these nodes". The array above is written by the importer AND by every running layout, so one frame after a file with no coordinates loads, every node carries a position because the layout put it there. This counts the importer's own column, which nothing else writes.
selection ​
readonlyselection:SelectionApi
Defined in: graphty-element/src/session/types.ts:1871
What is selected: two sets, five set operations, one selection for the whole session.
Every surface reads and writes this one -- the canvas, a data table, an inspector, a headset -- which is why it belongs to the session rather than to the thing that draws it.
sets ​
readonlysets:SetsApi
Defined in: graphty-element/src/session/types.ts:1852
The kept sets: named collections of nodes and edges -- groups, kept selections, communities and paths -- that anything taking a scope can name as { set: id }.
A set is fixed (a member list), a rule (a query or rule tree that follows the data) or a path (an ordered walk). Reading and counting one goes through scope.resolve({ set: id }) and scope.count({ set: id }); every change is published as set:changed.
status ​
readonlystatus:SessionStatus
Defined in: graphty-element/src/session/types.ts:1921
The O(1) facts, always current.
styles ​
readonlystyles:StylesApi
Defined in: graphty-element/src/session/types.ts:1893
The style layers: what paints what, in what order, and why one element looks as it does.
The stack is read BOTTOM FIRST, so a layer later in list() paints over one earlier in it, and every layer is addressed by its id rather than by its place -- a position is what goes wrong the moment anything else moves.
The bottom of every stack is the element's own: the layers that give a node and an edge their appearance before anything else is asked for. They carry source.by === "element" and locked: true, and removing, editing or moving one is refused. That is what a consumer tests rather than the layer's NAME, which two layers may share and a reader may change.
views ​
readonlyviews:SessionViews
Defined in: graphty-element/src/session/types.ts:1898
The saved camera views, by name: camera states kept under a name of the consumer's choosing. Saving and removing one are undoable steps; moving the camera to one is not.
visibility ​
readonlyvisibility:VisibilityApi
Defined in: graphty-element/src/session/types.ts:1879
What is visible: the DATA scope, produced by the filters and the time window.
Never the render set. Above the renderer's ceiling fewer elements are drawn than are visible here, and "analyse the visible graph" means this model rather than whatever happened to be drawn.
Methods ​
dispose() ​
dispose():
void
Defined in: graphty-element/src/session/types.ts:2064
Release what this session owns: the accelerator it attached, the store it built, and every run still in flight.
A store handed in by a caller is NOT disposed -- the caller that built it owns its lifetime. Calling this twice is harmless.
Returns ​
void
estimate() ​
estimate(
command):CostEstimate
Defined in: graphty-element/src/session/types.ts:2043
What one command would cost, answered synchronously.
Synchronous because a user interface has to decide how a button behaves before the click happens, and a promise cannot gate a click. It is O(1) in the size of the graph: the session maintains the statistics it reads.
Parameters ​
command ​
What would be done.
Returns ​
The estimate, which reports available: false with a reason rather than throwing.
execute() ​
execute<
C>(command):CommandOutcome<C>
Defined in: graphty-element/src/session/types.ts:2000
Do any command in the vocabulary (COMMANDS in @graphty/graphty-element/commands).
Returns the op's outcome directly, not wrapped in a promise; every outcome is itself awaitable (a Run for algo.run), so await session.execute(...) waits for the command, and a caller that wants the run handle keeps the returned value without awaiting it.
Type Parameters ​
C ​
C extends SessionCommand
Parameters ​
command ​
C
The command.
Returns ​
Its outcome.
find() ​
find(
text,options?):FindResult
Defined in: graphty-element/src/session/types.ts:1980
What a find box lists as the reader types: the nodes and edges whose values contain the text, best first, and the commonest matched values. Selects nothing and records no step; hand a hit's or a row's target to selection.apply for that.
Matching ignores case and accents and reads the text box grammar of selection.apply({ text }): plain text matches anywhere in a value, exact: only a whole value, and <attribute>: (id:, type:) only that attribute. regex: and a leading = are not run while typing; they set notSearchable and list nothing.
A node is found by its id, its name and its attribute values; an edge by its own attribute values only. A number or boolean value matches only whole. Ranking promises only this: an exact name or id first, name and id matches before attribute values, ties in graph order.
Synchronous: the first call after a change builds an index in one walk of the graph, and every later call in the same revision reads it. At the load limit (50,000 nodes with 20 attributes each, 100,000 edges) the build takes about half a second and a later call 2 to 9 ms.
Parameters ​
text ​
string
What was typed. Blank text finds nothing.
options? ​
The window, the kinds and the scope.
Returns ​
A page of hits and at most three value rows.
Throws ​
A GraphtyError coded E_OPTION_RANGE for a bad limit, offset or kind.
fingerprint() ​
fingerprint():
string
Defined in: graphty-element/src/session/types.ts:1956
The topology fingerprint. Same answer as data.fingerprint().
Returns ​
string
the fingerprint
on() ​
on<
K>(event,handler): () =>void
Defined in: graphty-element/src/session/types.ts:2056
Watch the session.
Type Parameters ​
K ​
K extends keyof SessionEventMap
Parameters ​
event ​
K
Which event.
handler ​
(detail) => void
Called with the event's detail.
Returns ​
A function that stops the subscription. There is no off to learn.
() => void
plan() ​
plan(
command):Promise<Plan>
Defined in: graphty-element/src/session/types.ts:2049
What one command would do, what it would cost, and whether it would be allowed.
Parameters ​
command ​
What would be done.
Returns ​
Promise<Plan>
The plan.
redo() ​
redo():
Promise<HistoryOutcome>
Defined in: graphty-element/src/session/types.ts:2011
Redo the last undone step. Resolves once the picture matches the state.
Returns ​
Promise<HistoryOutcome>
What was done; { kind: "nothing" } when there was nothing to redo.
run() ​
run(
command,options?):Run
Defined in: graphty-element/src/session/types.ts:1990
Do one thing, as a command.
The same verb runs.start offers, reached through the serialisable form -- so a recipe, a journal entry and an agent's tool call all replay through one door rather than three.
Parameters ​
command ​
What to do.
options? ​
The signal, the progress handler and how the call joins the queue.
Returns ​
The run, awaitable and watchable straight away.
setAccelerator() ​
setAccelerator(
accelerator):void
Defined in: graphty-element/src/session/types.ts:1943
Attach an accelerator the caller built, or detach the current one with null.
For tests and third parties. An injected accelerator is never replaced by a probed one and is not disposed by the session -- whoever built it owns its lifetime.
Parameters ​
accelerator ​
GraphAccelerator | null
The accelerator to attach, or null to detach.
Returns ​
void
snapshot() ​
snapshot():
GraphSnapshot
Defined in: graphty-element/src/session/types.ts:1951
The current snapshot. Its structure, id map and attribute columns are the graph's own, shared rather than copied; its position and graphty.pinned columns are copies taken now, because the graph's own are written by the layout every frame and a write into them would place nodes without a step. Place and pin through session.positions.
Returns ​
the sealed graph-format snapshot
transaction() ​
transaction<
T>(label,fn,options?):Promise<T>
Defined in: graphty-element/src/session/types.ts:2029
Run fn, and record everything it dispatches through tx as one step. Throw, or abort the transaction, to roll all of it back. A transaction that changed nothing records nothing.
Type Parameters ​
T ​
T
Parameters ​
label ​
string
The step's label.
fn ​
(tx, signal) => T | Promise<T>
The body; signal fires when the transaction is aborted.
options? ​
Provenance stamped on the step.
Returns ​
Promise<T>
What fn returned, once the step is recorded and the picture has caught up.
undo() ​
undo():
Promise<HistoryOutcome>
Defined in: graphty-element/src/session/types.ts:2006
Undo the last step, or cancel pending undoable work dispatched after it instead. Never waits for pending work. Resolves once the picture matches the state.
Returns ​
Promise<HistoryOutcome>
What was done; { kind: "nothing" } when there was nothing to undo.