@graphty/graphty-element 2.6.2 → 3.0.0

package/dist/src/data/GraphStore.d.ts

@@ -1,8 +1,14 @@
-import { type ColumnHandle, type DerivedGraph, type FreezeReport, GraphBuilder, type GraphSnapshot, type U32 } from "@graphty/graph-format";
+import { type ColumnHandle, type DerivedGraph, type FreezeReport, GraphBuilder, type GraphSnapshot, type NodeId, type U32 } from "@graphty/graph-format";
 import { type InputCounters } from "../session/attributes";
 import type { DirectionProvenance } from "../session/types";
 import { type EdgeCounter } from "./edgeIdentity";
 import { ElementPositions } from "./positions";
+/** An edge's stable-identity cells: its hash lanes, its ordinal and its pair's count. */
+export interface EdgeIdentityCells {
+    readonly hash: readonly [number, number];
+    readonly ordinal: number;
+    readonly among: number;
+}
 /** The payload of `snapshot-replaced` (graph-format design 14.4 rule 11). */
 export interface SnapshotReplacement {
     /** The snapshot this one supersedes; null on the first freeze. */
@@ -13,8 +19,12 @@ export interface SnapshotReplacement {
     readonly report: FreezeReport;
 }
 export interface GraphStoreOptions {
-    /** config.data.directed. "auto" leaves the builder unlocked (14.4 rule 1). */
-    readonly directed: boolean | "auto";
+    /**
+     * config.data.directed. "auto" leaves the builder unlocked (14.4 rule 1). Given as a thunk it
+     * is read again whenever the graph is emptied, so a cleared graph takes the setting in force
+     * then, as a freshly built store would.
+     */
+    readonly directed: boolean | "auto" | (() => boolean | "auto");
     /**
      * config.data.knownFields.positionScale: record units -> scene units, read THROUGH A THUNK on
      * every seeding pass rather than captured once.
@@ -44,6 +54,44 @@ export interface GraphStoreOptions {
      */
     readonly inputs?: InputCounters;
 }
+/** Every registered builder column's value in one row, by column name; unset cells are absent. */
+type RowValues = ReadonlyMap<string, unknown>;
+/** A node row a removal took out, with what putting it back needs. */
+interface RemovedNode {
+    /** Its id. */
+    readonly id: NodeId;
+    /** Its row in the graph it was removed from. */
+    readonly index: number;
+    /** Its value in every registered column: the seed coordinate, and any column added later. */
+    readonly values: RowValues;
+}
+/** An edge row a removal took out: resolved endpoints and weight, never re-read through ingest. */
+interface RemovedEdge {
+    /** The element-assigned id. */
+    readonly edgeId: number;
+    /** Its row in the graph it was removed from. */
+    readonly index: number;
+    /** The source id. */
+    readonly source: NodeId;
+    /** The target id. */
+    readonly target: NodeId;
+    /** The weight. */
+    readonly weight: number;
+    /** Its value in every registered column except the edge id. */
+    readonly values: RowValues;
+}
+/** The rows one removal took out, each list in ascending row order. */
+export interface RemovedRows {
+    readonly nodes: readonly RemovedNode[];
+    readonly edges: readonly RemovedEdge[];
+}
+/** A whole graph a replace set aside, for its undo. */
+export interface KeptGraph {
+    /** The graph, frozen fresh so it still carries every builder column and no positions lane. */
+    readonly snapshot: GraphSnapshot;
+    /** How its direction had been settled. */
+    readonly direction: DirectionProvenance;
+}
 /**
  * The element's ONE graph-format builder and the snapshot it freezes to (graph-format design 14.4).
  *
@@ -66,20 +114,28 @@ export interface GraphStoreOptions {
  * render loop reads every frame, and the symptom is a blank canvas with nothing in the console.
  */
 export declare class GraphStore {
-    /** The one builder, alive for the whole life of the Graph. */
-    readonly builder: GraphBuilder;
     /** The element-owned node coordinates, lent to every snapshot. */
     readonly positions: ElementPositions;
-    /** Handle of the importer seed column; `setNodeValue(seedColumn, i, [x, y, z])` seeds a node. */
-    readonly seedColumn: ColumnHandle;
-    /** Handle of the element-assigned edge counter column. */
-    readonly edgeIdColumn: ColumnHandle;
     private readonly options;
+    /** The builder now. Replaced only by a rebuild; see {@link GraphStore.builder}. */
+    private current;
+    private seedHandle;
+    private edgeIdHandle;
+    /** Structural changes waiting to be applied, already folded to their net effect. */
+    private structural;
+    /** Every column of the last freeze, taken before the positions lane replaced the seed column. */
+    private frozenColumns;
+    private rebuilds;
+    /**
+     * Strict: the resident snapshot last sealed. Each dispatch checks its arrays; a snapshot no
+     * longer resident is checked by the sweep after each test.
+     */
+    sealedResident: GraphSnapshot | null;
     private readonly counter;
-    private readonly nodeHashColumn;
-    private readonly edgeHashColumn;
-    private readonly edgeOrdinalColumn;
-    private readonly edgeAmongColumn;
+    private nodeHashColumn;
+    private edgeHashColumn;
+    private edgeOrdinalColumn;
+    private edgeAmongColumn;
     /** Node rows below this have their hash; rows from here to `nodeBound` are new. */
     private nodeMark;
     /** Edges ingested outside a load and not yet completed: row, counter, file id. */
@@ -93,21 +149,81 @@ export declare class GraphStore {
     private loadDepth;
     /** Whether edge pairs are ordered, latched when the first edge is completed. */
     private pairsOrdered;
-    /** The counters whose tick every freeze advances. */
-    private readonly inputs;
+    /** The counters whose tick every freeze advances; the graph primitives bump its fields. */
+    readonly inputs: InputCounters;
     private readonly undirectedCache;
     private cache;
     private cachedRevision;
     private revision;
+    /** The edge-id column, mirrored by builder row: what {@link GraphStore.edgeIdAt} reads. */
+    private edgeIdByIndex;
+    /** Builder row by edge id: what {@link GraphStore.edgeIndexOf} reads. */
+    private readonly indexByEdgeId;
     private pending;
     private pendingPositions;
+    /**
+     * Where the rows each removal and each kept graph took out were in the lane, read again at
+     * every redo: the lane half of a removed row, so undoing the removal puts the node back where
+     * it was rather than where its file seeded it.
+     */
+    private readonly heldLane;
+    /** Rows put back since the last freeze, by what put them back; written once they have rows. */
+    private readonly laneToRestore;
     private publishing;
     private disposed;
+    /** The builder and its `mutationCount` after the last write the store accounted for. */
+    private accounted;
+    /** Builder mutations found unaccounted for before a write of the store's own. */
+    private drift;
     /**
      * Build the empty store: one builder, one position array, the two element columns.
      * @param options - the store's configuration and its three freeze callbacks
      */
     constructor(options: GraphStoreOptions);
+    /**
+     * The one builder. Reading it first applies any structural change still waiting, so a reader
+     * never sees rows in an order the graph does not hold. A rebuild replaces the object: hold the
+     * store, not the builder.
+     * @returns the builder
+     */
+    get builder(): GraphBuilder;
+    /**
+     * Handle of the importer seed column; `setNodeValue(seedColumn, i, [x, y, z])` seeds a node.
+     * @returns the handle of the current builder
+     */
+    get seedColumn(): ColumnHandle;
+    /**
+     * Handle of the element-assigned edge counter column.
+     * @returns the handle of the current builder
+     */
+    get edgeIdColumn(): ColumnHandle;
+    /**
+     * How many times a structural change rebuilt the builder rather than appending to it.
+     * @returns the count
+     */
+    get rebuildCount(): number;
+    /**
+     * The direction setting now.
+     * @returns config.data.directed
+     */
+    private directedSetting;
+    /**
+     * The direction an empty graph starts with: the configured one, or directed until a file says.
+     * @returns Whether it is directed.
+     */
+    private emptyDirected;
+    /**
+     * How an empty graph's direction is settled: by a consumer who named one, and no file can
+     * overrule them, or not yet.
+     * @returns The provenance.
+     */
+    private emptyDirection;
+    /**
+     * A builder with the element's two columns declared.
+     * @param directed - Its direction; locked when the configuration named one.
+     * @returns the builder
+     */
+    private createBuilder;
     /**
      * Whether a reader would get anything other than a settled, fully published snapshot.
      *
@@ -137,6 +253,21 @@ export declare class GraphStore {
      * @throws Error when the store has been disposed
      */
     touch(): void;
+    /**
+     * How many times the builder was mutated with nobody accounting for it: a write that reached
+     * `builder` directly, without the graph primitives. Every legitimate write ends in
+     * {@link GraphStore.touch}, which accounts for it, and begins with {@link GraphStore.audit},
+     * which keeps what it finds. Strict state fails the next dispatch when this is not zero.
+     * @returns The count.
+     */
+    get mutationDrift(): number;
+    /**
+     * Keep the unaccounted mutations found now, before a write of the graph primitives or of the
+     * store itself would account for them.
+     */
+    audit(): void;
+    /** Account for every mutation of the builder so far. */
+    private account;
     /**
      * Take the next element-assigned edge id, written into the graphty.edgeId column at addEdge time.
      * @returns the id, one higher than the last
@@ -162,6 +293,45 @@ export declare class GraphStore {
      * store ignores this, so a load's cleanup may run after a Clear replaced its store.
      */
     closeLoad(): void;
+    /**
+     * Stamp an element-assigned edge id into a builder row's `graphty.edgeId` column, and index it
+     * both ways so the graph primitives can find a row by its id without freezing.
+     *
+     * The counter is never wound back: a redone edge gets the id it had, stamped here again.
+     * @param edgeIndex - the builder row
+     * @param edgeId - the counter
+     */
+    stampEdgeId(edgeIndex: number, edgeId: number): void;
+    /**
+     * The stable-identity cells an edge was given, read from the last freeze without settling:
+     * what an undone add keeps so its redo gives the edge back the identity it had.
+     * @param edgeId - the element-assigned counter
+     * @returns the hash, ordinal and among, or undefined when the last freeze holds no such edge
+     */
+    frozenEdgeIdentity(edgeId: number): EdgeIdentityCells | undefined;
+    /**
+     * Give a re-added edge the identity cells it had, instead of completing it as a new edge.
+     * @param row - the builder row
+     * @param cells - what {@link GraphStore.frozenEdgeIdentity} returned for it
+     */
+    restoreEdgeIdentity(row: number, cells: EdgeIdentityCells): void;
+    /**
+     * The builder row a live edge occupies.
+     * @param edgeId - the element-assigned counter
+     * @returns the row, or INVALID_INDEX when no live edge has that id
+     */
+    edgeIndexOf(edgeId: number): number;
+    /**
+     * The element-assigned id of the edge in one builder row.
+     * @param edgeIndex - the row
+     * @returns the counter, or INVALID_INDEX when the row is not a live edge
+     */
+    edgeIdAt(edgeIndex: number): number;
+    /**
+     * Put back how the direction was settled, when the write that settled it is undone.
+     * @param provenance - what it was before
+     */
+    restoreDirection(provenance: DirectionProvenance): void;
     /**
      * The current snapshot, freezing first when the graph has changed since the last one.
      *
@@ -186,6 +356,130 @@ export declare class GraphStore {
      * @throws Error when the store has been disposed
      */
     getSnapshot(): GraphSnapshot;
+    /**
+     * Take rows out of the graph, recording everything that putting them back needs: their rows,
+     * every registered column's value, and an edge's resolved endpoints and weight. Pins are the
+     * session's `pins` slice, which the removal's own draft records.
+     * Removing a node removes every edge attached to it.
+     * @param nodeIds - The nodes to remove; one the graph does not hold is skipped.
+     * @param edgeIds - The element-assigned ids of edges to remove; likewise.
+     * @returns What was removed.
+     */
+    removeRows(nodeIds: readonly NodeId[], edgeIds: readonly number[]): RemovedRows;
+    /**
+     * Whether the graph holds no node rows, answered without freezing: a clear still waiting to be
+     * applied empties it, and any other structural change still waiting is taken to leave rows.
+     * @returns True when it holds none.
+     */
+    get holdsNoRows(): boolean;
+    /**
+     * Whether structural changes are waiting for the next read. While they are, a write that
+     * would read the builder rebuilds it first; {@link GraphStore.dropAdded} waits with them.
+     * @returns True when some are.
+     */
+    get deferring(): boolean;
+    /**
+     * Take rows an add appended out again -- the undo of an add -- at the next read, with the
+     * structural changes waiting before it, so that undoing adds and removals in one run rebuilds
+     * the graph once rather than once per add.
+     * @param nodes - The nodes the add created.
+     * @param edges - The element-assigned ids of the edges it added.
+     */
+    dropAdded(nodes: readonly NodeId[], edges: readonly number[]): void;
+    /**
+     * Put removed rows back where they were: the undo of {@link GraphStore.removeRows}. Applied at
+     * the next read, folded with whatever else is waiting.
+     * @param rows - What the removal recorded.
+     */
+    insertRows(rows: RemovedRows): void;
+    /**
+     * Take recorded rows out again: the redo of {@link GraphStore.removeRows}. Applied at the next read.
+     * @param rows - What the removal recorded.
+     */
+    dropRows(rows: RemovedRows): void;
+    /**
+     * Forget the cached snapshot without freezing a replacement, once its holders have been told
+     * the dataset is gone: the next freeze then reports no previous snapshot, so nothing releases
+     * the forgotten one a second time.
+     */
+    forgetSnapshot(): void;
+    /**
+     * Set the whole graph aside for a replace: every row, every column and the direction.
+     * @returns What was set aside.
+     */
+    keep(): KeptGraph;
+    /**
+     * Swap the whole graph for an empty one (`restore` false), or back to a kept one (`restore`
+     * true). Applied at the next read; the last replace waiting wins over everything before it.
+     * @param kept - The graph {@link GraphStore.keep} set aside.
+     * @param restore - Whether to go back to it.
+     */
+    replace(kept: KeptGraph, restore: boolean): void;
+    /**
+     * Read again where rows about to be taken out are in the lane, for those it holds now.
+     * @param taken - The removal or the kept graph.
+     * @param ids - Its node ids.
+     */
+    private holdLane;
+    /**
+     * Queue the coordinates rows being put back had in the lane, for the next freeze.
+     * @param taken - The removal or the kept graph.
+     */
+    private putBack;
+    /**
+     * Give rows put back the coordinates they had when they were taken out, before anything seeds
+     * them. Not a move of the arrangement, so it writes the array directly.
+     * @param snapshot - The snapshot just frozen, its lane already remapped.
+     */
+    private restoreLane;
+    /**
+     * Queue a structural change, cancelling it against the one before when they undo each other.
+     * @param change - The change.
+     */
+    private defer;
+    /** Apply the structural changes waiting, if any, by freezing. */
+    private settle;
+    /**
+     * Apply the waiting structural changes to the builder. Appends and removals go straight into
+     * it; anything that must land mid-row rebuilds it once, however many changes are waiting.
+     * @returns The walk from the old builder's rows to the new one's when it rebuilt, else null.
+     */
+    private materialize;
+    /**
+     * Apply one change straight to the builder when that keeps row order: a removal always, an
+     * insert only when every row it puts back belongs at the end.
+     * @param change - The change.
+     * @returns False when it needs a rebuild.
+     */
+    private applyDirect;
+    /**
+     * Build a new builder in one pass, in the style of `GraphBuilder.from`: the rows of the graph
+     * it starts from, with the waiting changes merged in at their recorded rows.
+     * @param replace - The replace it starts from, or null to start from the builder now.
+     * @param changes - The inserts and removals after it, in order.
+     * @returns The walk from the old builder's rows to the new one's.
+     */
+    private rebuild;
+    /**
+     * Write a recorded node row's column values back.
+     * @param index - The row.
+     * @param values - The values.
+     */
+    private writeNode;
+    /**
+     * Write a recorded edge row's id and column values back.
+     * @param index - The row.
+     * @param edgeId - Its element-assigned id.
+     * @param values - The values.
+     */
+    private writeEdge;
+    /**
+     * Every set cell of one row of the last freeze.
+     * @param columns - The columns of that freeze.
+     * @param row - The row.
+     * @returns The values by column name, the edge id and weight excepted.
+     */
+    private rowValues;
     /**
      * The undirected view of a snapshot, cached per snapshot (14.4 rule 8).
      *
@@ -256,6 +550,12 @@ export declare class GraphStore {
      * torn down -- and then re-clear a `pending` that `dispose()` had already cleared.
      */
     private publish;
+    /**
+     * Follow a compacting freeze with the edge-id index: the builder's rows are the snapshot's
+     * from here on.
+     * @param remap - the freeze report's edgeRemap, or null when nothing was renumbered
+     */
+    private remapEdgeIds;
     /**
      * The completion pass (design 12.2, 12.3): hash new nodes, complete session edges, and, when
      * no load is open, complete the load's edges -- ordinal and among per pair over the load's
@@ -269,6 +569,12 @@ export declare class GraphStore {
      * @returns the latched value
      */
     private latchPairsOrdered;
+    /**
+     * Move the edges waiting for the completion pass into a rebuilt builder's rows, before the
+     * pass reads them: a rebuild renumbers rows the way a compacting freeze does.
+     * @param edgeRemap - old builder row to new builder row, INVALID_INDEX for a row dropped
+     */
+    private followRebuild;
     /**
      * Move the pass's marks and the open load's rows into the index space of a freeze just
      * committed. Allocation-free.
@@ -326,3 +632,4 @@ export declare class GraphStore {
     private direction;
     private seedUnplaced;
 }
+export {};

package/dist/src/data/JsonDataSource.d.ts

@@ -42,10 +42,52 @@ export declare class JsonDataSource extends DataSource {
     protected getConfig(): BaseDataSourceConfig;
     /**
      * Fetches and parses JSON data into graph chunks.
-     * Uses JMESPath to extract nodes and edges from the JSON structure.
+     *
+     * The node and edge arrays are found with the configured JMESPath expressions and read by
+     * graph-io's node-link importer, which checks every node's id and every edge's endpoints. The
+     * records the element receives are the ones the file wrote, unchanged, less the ones graph-io
+     * refused and every repeat of a node id after its first record.
+     *
+     * Two things graph-io cannot read are handed to the element as the file wrote them: nodes
+     * whose id is a JMESPath expression rather than a key, and edges whose endpoints no key names
+     * -- the element resolves the first and refuses the second, naming the keys the records carry.
      * @yields DataSourceChunk objects containing parsed nodes and edges
      */
     sourceFetchData(): AsyncGenerator<DataSourceChunk, void, unknown>;
+    /**
+     * Find one of the two arrays with its JMESPath expression.
+     * @param data - the parsed document
+     * @param path - the configured expression
+     * @param what - "nodes" or "edges", for the messages
+     * @returns the array, or an empty one when the expression finds nothing usable
+     */
+    private locate;
+    /**
+     * The key that holds a node's id, when graph-io can read it.
+     *
+     * The configured `nodeIdPath` when it is a key, else the first of `id`, `name`, `key` and
+     * `label` that some record carries -- the identifier keys this reader has always accepted.
+     * Null when the configured path is a JMESPath expression rather than a key.
+     * @param nodes - the node records
+     * @returns the key, or null
+     */
+    private nodeIdKey;
+    /**
+     * The keys that name an edge's endpoints, when graph-io can read them.
+     *
+     * The spelling is the one the element itself would resolve (`src/data/endpoints.ts`): the
+     * configured keys, else the first of `source`/`target`, `src`/`dst` and `from`/`to` that some
+     * record carries. Null when no key names them, or when a configured one is a JMESPath
+     * expression rather than a key: the records then reach the element as the file wrote them.
+     * @param edges - the edge records
+     * @returns the two keys, or null
+     */
+    private endpointKeys;
+    /**
+     * Record an error, and stop the load at the error limit as every reader does.
+     * @param error - the error
+     */
+    private addError;
     /**
      * Validates a node object and logs errors if invalid.
      * Returns true if the node is valid and should be included.

package/dist/src/data/graph-io-import.d.ts

@@ -0,0 +1,89 @@
+import { type Column, type GraphSnapshot, type NodeId } from "@graphty/graph-format";
+import { type CommonImportOptions, type GraphImporter, type ImportReport } from "@graphty/graph-io";
+import type { AdHocData } from "../config/common.js";
+import type { ErrorAggregator } from "./ErrorAggregator.js";
+/** What one import produced: the frozen scratch graph, the importer's report and the declared nodes. */
+export interface ImportedGraph {
+    readonly snapshot: GraphSnapshot;
+    readonly report: ImportReport;
+    /** The ids of the nodes the file declared, as opposed to those an edge created. */
+    readonly declared: ReadonlySet<NodeId>;
+}
+/**
+ * Run a graph-io importer over a document into a scratch builder and freeze it.
+ *
+ * The scratch builder, not the element's own, is the importer's sink: the element's builder holds
+ * no attribute columns, so a data source reads the file here and rebuilds its records from the
+ * columns afterwards (see {@link toRecords}).
+ *
+ * A document that is recognisably this format but breaks off (a tag left open, a stray end tag)
+ * keeps what was read before the break: the importer's fatal error becomes one more error in the
+ * report rather than a thrown one. A document the importer does not recognise at all, or one whose
+ * report holds one of the `fatal` codes, still throws: a `GraphtyError` with `E_PARSE_FAILED`
+ * naming the format and the line, whose `cause` is the importer's `ImportError`.
+ * @param importer - the graph-io importer for the format
+ * @param text - the whole document
+ * @param options - importer options; `ids` defaults to "string", so ids stay the text the file wrote
+ * @param fatal - issue codes that make even a recognisable document unreadable
+ * @returns the snapshot, the report and the declared node ids
+ */
+export declare function importDocument<Opts>(importer: GraphImporter<Opts>, text: string, options: Opts & CommonImportOptions, fatal?: readonly string[]): Promise<ImportedGraph>;
+/**
+ * Copy the errors of an import report into the source's aggregator.
+ *
+ * Warnings stay in the report: the aggregator has always counted only what went wrong, and a
+ * warning is something the importer read and kept.
+ * @param report - the importer's report
+ * @param errors - the data source's aggregator
+ */
+export declare function aggregateErrors(report: ImportReport, errors: ErrorAggregator): void;
+/**
+ * A cell as the element's records carry it.
+ *
+ * An f32 cell is widened to the shortest decimal that reads back to the same f32, so a `float`
+ * attribute written as 0.1 arrives as 0.1 rather than as 0.10000000149011612.
+ * @param column - the column
+ * @param row - the row
+ * @returns the value
+ */
+export declare function cell(column: Column, row: number): unknown;
+/**
+ * The components of a multi-component f32 or f64 cell, each widened as {@link cell} does.
+ * @param column - a column with `components > 1`
+ * @param row - the row
+ * @returns the components
+ */
+export declare function components(column: Column, row: number): number[];
+/**
+ * The title a declared attribute was written with.
+ *
+ * graph-io names an attribute's column after its title (a GEXF `title`, a GraphML `attr.name`),
+ * but renames it `<title>#<id>` when that name is taken -- in GEXF by one of its own fields
+ * (`label`, `color`, `size`, ...). The element has always keyed the value by its title.
+ * @param name - the column name
+ * @param id - the attribute's id in the file
+ * @returns the title
+ */
+export declare function attributeTitle(name: string, id: string): string;
+/** How one format turns a row of the scratch graph into the keys of its record. */
+export interface RecordMapping {
+    /** Write a node's keys onto its record, which already holds `id`. */
+    node(row: number, record: Record<string, unknown>): void;
+    /** Write an edge's keys onto its record, which already holds `source`, `target` and any `weight`. */
+    edge(row: number, record: Record<string, unknown>): void;
+}
+/**
+ * Rebuild the element's node and edge records from an imported graph.
+ *
+ * Only declared nodes become records, in declaration order. Each logical edge of the file becomes one record: when the
+ * importer expanded an edge into two halves to hold a mixed-direction file, the mirror half (the
+ * one whose `pair` points at a lower row) is skipped. An edge carries `weight` only when the file
+ * gave it one, at the precision the importer read it with.
+ * @param imported - the import
+ * @param mapping - the format's mapping from rows to record keys
+ * @returns the records, in file order
+ */
+export declare function toRecords(imported: ImportedGraph, mapping: RecordMapping): {
+    nodes: AdHocData[];
+    edges: AdHocData[];
+};

package/dist/src/data/graph-io-records.d.ts

@@ -0,0 +1,64 @@
+import { type NodeId } from "@graphty/graph-format";
+import { type CommonImportOptions, type GraphImporter, type ImportInput, type ImportReport } from "@graphty/graph-io";
+import type { ErrorAggregator } from "./ErrorAggregator";
+/** One node or edge record, in the shape the element's data bags hold. */
+export type ImportedRecord = Record<string, unknown>;
+/**
+ * One imported node: its id, and every attribute the file set on it.
+ *
+ * The id is kept apart from the attributes because a file may carry an attribute under the very
+ * key the element reads the id from (a JSON node whose id is `name` and which also has an `id`
+ * value); each data source decides which key the id goes under.
+ */
+export interface ImportedNode {
+    /** The node id. */
+    readonly id: NodeId;
+    /** Every attribute the file set. */
+    readonly data: ImportedRecord;
+}
+/** One imported edge: its endpoints, and every attribute the file set on it. See {@link ImportedNode}. */
+export interface ImportedEdge {
+    /** The source node id. */
+    readonly source: NodeId;
+    /** The target node id. */
+    readonly target: NodeId;
+    /** Every attribute the file set, plus `weight` when the importer read a weight for it. */
+    readonly data: ImportedRecord;
+}
+/** What a graph-io import yields once it is turned back into element records. */
+export interface ImportedRecords {
+    /** One entry per node, in node index order. */
+    readonly nodes: ImportedNode[];
+    /** One entry per logical edge, in insertion order. */
+    readonly edges: ImportedEdge[];
+    /** The importer's report, also when it aborted. */
+    readonly report: ImportReport;
+    /** Whether the importer aborted (a fatal issue, or its error limit): the records are then empty. */
+    readonly aborted: boolean;
+}
+/**
+ * Run a graph-io importer into a scratch builder and hand back the records the element consumes.
+ *
+ * The scratch builder is directed, keeps parallel edges and self-loops and adds the endpoints an
+ * edge names, so every record the file holds comes back once, in file order, with the endpoints
+ * the file wrote. Direction is not read from it: each data source declares what its format
+ * states. An importer that aborts -- an empty input, an unclosed quote, a header that names no
+ * column it can read -- does not throw here; its report is returned with `aborted` set, so the
+ * caller can record the issues and yield nothing, as every reader in the element has always done.
+ * @param importer - the graph-io importer
+ * @param input - the text to read
+ * @param options - the importer's options
+ * @returns the records and the report
+ */
+export declare function importRecords<O>(importer: GraphImporter<O>, input: ImportInput, options: O & CommonImportOptions): Promise<ImportedRecords>;
+/**
+ * Record an import report's errors in a data source's error aggregator.
+ *
+ * Only errors are recorded. Warnings did not reach the aggregator before either -- a header with
+ * no rows, a column renamed because its name was taken -- and the aggregator's count is what
+ * decides whether a load is reported as having failed rows.
+ * @param report - the importer's report
+ * @param aggregator - the data source's aggregator
+ * @throws Error when the aggregator's error limit is reached, as every reader does
+ */
+export declare function recordIssues(report: ImportReport, aggregator: ErrorAggregator): void;

package/dist/src/data/lane.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file The coordinate lane as the renderer's public objects hand it out: read-only. The writable
+ * lane is reached only through {@link writableLane}, which no entry point exports.
+ */
+import type { ReadonlyElementPositions } from "../session/types";
+import { ElementPositions } from "./positions";
+/** The key a data manager keeps its writable lane under; see {@link writableLane}. */
+export declare const WRITABLE_LANE: unique symbol;
+/**
+ * The writable coordinate lane of a data manager, for the element's own layout engines and
+ * nodes. A consumer reads `getDataManager().positions`, which has no writer, and places nodes
+ * through `session.positions.set`.
+ * @param manager - A data manager, or a stand-in for one that hands its lane out directly.
+ * @returns The lane, or undefined when the manager keeps none.
+ */
+export declare function writableLane(manager: object | undefined): ElementPositions | undefined;
+/**
+ * The read half of a coordinate lane, as a plain object: a caller holding it can read every row
+ * and reach no writer, not even through a cast.
+ * @param lane - Reads the lane now; a store may replace its lane object.
+ * @returns The read-only coordinates.
+ */
+export declare function readonlyPositions(lane: () => ReadonlyElementPositions): ReadonlyElementPositions;