// Progressive ingest: load the graph chunk by chunk from an async iterable — a streamed response, a server's pages — and show a correct partial graph before the last byte arrives
cy.load(source: | AsyncIterable<ElementsInput<NodeData, EdgeData>> | Iterable<ElementsInput<NodeData, EdgeData>>, options?: LoadOptions): LoadRunProgressive ingest: load the graph chunk by chunk from an async iterable — a streamed response, a server's pages — and show a correct partial graph before the last byte arrives. Each chunk is any input form (definition, columnar or wire); a chunk may name nodes an earlier chunk loaded — by id in the definition form, and through node references (refs) in the columnar and wire forms, which is what keeps a chunk's cut edges as cheap as its own. A plain iterable (an array of chunks) works too.
Every chunk lands through the bulk load path — one bulk style pass, no per-element handle — and the renderer gets a turn between chunks, even when the source hands them over synchronously; the second chunk is not asked for until the first is drawn. Every element drawn is correct; completeness arrives — a frame may show some of the graph, never a wrong piece of it.
An initial load — one that starts on an instance holding no elements, the streamed counterpart of options.elements — holds cy.ready until its first chunk is drawn (headless: until it is in the model), fits the viewport once to that chunk and then holds it (never a re-fit per chunk; fit: false keeps the viewport as it is), and applies the graph-level data() a wire chunk carries. The load re-points cy.ready, so read it after calling load() — a reference taken before resolves on the renderer alone. A load into a populated graph is a streamed cy.add(): cy.ready, the viewport and data() are left alone. Positions are the payload's (the preset layout case); a layout cannot start while a load runs — run it once the promise resolves.
Events: loadstart; loadchunk after each chunk (with add per element while anyone listens for it, as the bulk path emits them); loadready once the first chunk is drawn; loadstop when the load ends — completed, failed or cancelled (event.cancelled). Each carries event.progress: { chunks, nodes, edges } so far.
Completion is the returned promise, resolving with the final progress; it carries cancel() (contract): cancelling stops pulling chunks, closes the source's iterator, keeps what has landed, and rejects with a CancelledError. cy.destroy() cancels a running load. A chunk that fails to ingest rejects the load; the chunks before it stay, and a node reference that names no node fails its chunk before anything of it is added.
| Name | Description |
|---|---|
source: | AsyncIterable<ElementsInput<NodeData, EdgeData>> | Iterable<ElementsInput<NodeData, EdgeData>> | an async iterable (or iterable) of chunks, each a definition, columnar or wire payload |
options: LoadOptions? |
|
Fields of options
| Name | Description |
|---|---|
fit: boolean? | Fit the viewport once, to the first chunk, and then hold it — a load never re-fits per chunk, so the screen does not jump as the graph fills in. Default: true for an initial load (one that starts on an instance holding no elements), false for a load into a populated graph. |
padding: number? | the rendered-space padding of that fit, in px (default 0, as |
LoadRunthe load's completion: a promise of the final { chunks, nodes, edges }, with cancel()
Example
await cy.load([[{ data: { id: 'd' } }]]);console.log(cy.hasElementWithId('d')); // truesynchronously, when source is not an (async) iterable of chunks (a single payload is refused — pass [ payload ]), on an unknown option, while another load is running on this instance, or on a destroyed instance