Graphty

Appearance

@graphty/graphty-element / index / DataSource

Abstract Class: DataSource ​

Defined in: graphty-element/src/data/DataSource.ts:296

Base class for all data source implementations that load graph data from various formats. Provides common functionality for validation, chunking, error handling, and data fetching.

Constructors ​

Constructor ​

new DataSource(errorLimit?, chunkSize?): DataSource

Defined in: graphty-element/src/data/DataSource.ts:347

Creates a new DataSource instance.

Parameters ​

errorLimit? ​

number = 100

Maximum number of errors before stopping data processing

chunkSize? ​

number = DataSource.DEFAULT_CHUNK_SIZE

Number of nodes to process per chunk

Returns ​

DataSource

Properties ​

DEFAULT_CHUNK_SIZE ​

readonly static DEFAULT_CHUNK_SIZE: 1000 = 1000

Defined in: graphty-element/src/data/DataSource.ts:298

descriptor? ​

static optional descriptor?: FormatDescriptor

Defined in: graphty-element/src/data/DataSource.ts:313

What the catalogue publishes about this format: its plain name, the extensions and media types its files carry, and the options a host can configure reading it with.

REQUIRED OF A REGISTERED FORMAT and refused without it, because a reader filed with no description is one a picker cannot offer, formatDescriptor cannot find and a dropped file cannot be recognised as. It is a static on the class so that one registration is the only registration: a description filed separately from its reader would be a catalogue entry a consumer can see, select, and then be told does not exist.

The element's own seven do not set it -- their descriptions are the frozen built-in table ./catalog publishes, which is what keeps that table meaning "what the element ships".

detect? ​

static optional detect?: (sample) => boolean

Defined in: graphty-element/src/data/DataSource.ts:324

Reads the first bytes of a file and says whether this format claims it.

Optional, and asked only after every built-in sniffer has been asked, so a registered format can claim a file the element could not already read and can never take one a built-in claims. It is also what tells two formats apart when both claim an extension -- which is how a third party's XML dialect gets the disambiguation GraphML and GEXF get by namespace. A sniffer that throws is treated as "no" rather than failing the import.

Parameters ​

sample ​

string

Returns ​

boolean

edgeSchema ​

edgeSchema: $ZodObject<Readonly<Readonly<{[k: string]: $ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; }>>, $ZodObjectConfig> | null = null

Defined in: graphty-element/src/data/DataSource.ts:335

listGraphs? ​

static optional listGraphs?: GraphLister

Defined in: graphty-element/src/data/DataSource.ts:333

Lists the graphs a file of this format holds, for a format whose file can hold several (a Cytoscape session's networks). Optional: a format that declares it accepts the graphIndex and graphName options, and listGraphs from ./catalog asks it; a format that does not reads its one graph and refuses a choice of any other. fromImporter sets it from the importer's own listGraphs.

nodeSchema ​

nodeSchema: $ZodObject<Readonly<Readonly<{[k: string]: $ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; }>>, $ZodObjectConfig> | null = null

Defined in: graphty-element/src/data/DataSource.ts:336

type ​

readonly static type: string

Defined in: graphty-element/src/data/DataSource.ts:297

Accessors ​

declaredDirection ​

Get Signature ​

get declaredDirection(): DeclaredDirection | null

Defined in: graphty-element/src/data/DataSource.ts:688

The direction this file declared, or null when it declared none.

READ IT PER CHUNK, not once before the loop. Parsing does not begin until the first chunk is pulled -- getData() is a generator over a generator -- so this is null until then, and the caller that reads it before iterating will always read null. Reading it at the top of each loop body gets the declaration before that chunk's edges are pushed, which is the one thing the builder requires: it accepts a direction change only while it holds no edges.

Returns ​

DeclaredDirection | null

the declaration, or null when the file was silent

type ​

Get Signature ​

get type(): string

Defined in: graphty-element/src/data/DataSource.ts:785

Gets the type identifier for this data source instance.

Returns ​

string

The type string identifier

Methods ​

dataValidator() ​

dataValidator(schema, obj): Promise<boolean>

Defined in: graphty-element/src/data/DataSource.ts:764

Validate data against schema Returns false if validation fails (and adds error to aggregator) Returns true if validation succeeds

Parameters ​

schema ​

$ZodObject

Zod schema to validate against

obj ​

object

Data object to validate

Returns ​

Promise<boolean>

Promise resolving to true if validation succeeds, false otherwise

fromImporter() ​

static fromImporter<Opts>(importer, descriptor, options?): ImporterDataSourceClass

Defined in: graphty-element/src/data/DataSource.ts:885

Turn a graph-io importer into a reader class, ready for DataSource.register.

For an author who already has a GraphImporter (an object whose import(input, sink, options) pushes nodes and edges into a builder). The class reads its input the way every reader does -- inline data, a File or a url with retries -- and hands the importer inline text as it is and anything else as bytes, which the importer decodes. When the importer has listGraphs, the class has it too, so listGraphs from ./catalog lists a file's graphs and the graphIndex / graphName load options reach the importer. Each node and edge attribute the importer set becomes a key of the record under its column name; an edge's weight becomes weight. A repeated node keeps its first declaration, as the element keeps a repeated record. The importer's errors are aggregated like any reader's, and a file the importer gives up on (it throws graph-io's ImportError) fails the load with E_PARSE_FAILED naming the format and the line, leaving the graph on screen as it was. The options the descriptor declares are checked against what a host passes, filled with their defaults, and handed to the importer.

Throw the ImportError re-exported by @graphty/graphty-element/extend, not one from your own copy of graph-io, or the element cannot tell a refusal from a crash.

Type Parameters ​

Opts ​

Opts

Parameters ​

importer ​

GraphImporter<Opts>

the graph-io importer

descriptor ​

FormatDescriptor

the format's catalogue entry; its id is the name the class registers under

options? ​

ImporterSourceOptions<Opts> = {}

fixed importer options and how the file states its direction

Returns ​

ImporterDataSourceClass

a DataSource subclass whose type is descriptor.id

Throws ​

A GraphtyError with E_BAD_COMMAND, details.field: "importer", when importer has no import method.

get() ​

static get(type, opts?): DataSource | null

Defined in: graphty-element/src/data/DataSource.ts:1001

Creates a data source instance by type name.

Parameters ​

type ​

string

The registered type identifier

opts? ​

object = {}

Configuration options for the data source

Returns ​

DataSource | null

A new data source instance or null if type not found

getData() ​

getData(): AsyncGenerator<DataSourceChunk, void, unknown>

Defined in: graphty-element/src/data/DataSource.ts:713

Fetches, validates, and yields graph data in chunks. Filters out invalid nodes and edges based on schema validation.

Returns ​

AsyncGenerator<DataSourceChunk, void, unknown>

Yields ​

DataSourceChunk objects containing validated nodes and edges

getErrorAggregator() ​

getErrorAggregator(): ErrorAggregator

Defined in: graphty-element/src/data/DataSource.ts:674

Get the error aggregator for this data source

Returns ​

ErrorAggregator

The ErrorAggregator instance tracking validation errors

getRegisteredTypes() ​

static getRegisteredTypes(): string[]

Defined in: graphty-element/src/data/DataSource.ts:1021

Get all registered data source types.

Returns ​

string[]

Array of registered data source type names

Since ​

1.5.0

Example ​

typescript
const types = DataSource.getRegisteredTypes();
console.log('Available data sources:', types);
// ['csv', 'gexf', 'gml', 'graphml', 'json', 'pajek']

register() ​

static register<T>(cls, options?): T

Defined in: graphty-element/src/data/DataSource.ts:812

Register a file format: its reader, and the description everything else finds it by.

ONE ACT, NOT TWO. Filing the class is what makes the format loadable; publishing its static descriptor is what puts it in session.catalog.formats(), in formatDescriptor, in formatsForExtension and in detection. They happen together because a reader with no description is invisible to every picker and to every dropped file, and a description without its reader is a catalogue entry a consumer can see, select, and then be told does not exist.

THE ELEMENT'S OWN SEVEN TAKE THE OTHER BRANCH. A class registering under a name that is already in the built-in format table is the element registering one of its own readers; its description is the frozen table ./catalog publishes, and there is nothing to publish. A SECOND registration under such a name is refused, so no plugin can change what json means for a document that was saved yesterday.

Type Parameters ​

T ​

T extends DataSourceClass

Parameters ​

cls ​

T

The reader class, carrying static type and -- unless the element ships this format -- static descriptor and an optional static detect.

options? ​

RegisterOptions

Pass { strict: true } to refuse a second registration under a name this build already gave to a different format, instead of replacing it with a warning.

Returns ​

T

The registered class, so a declaration can be wrapped in the call.

Throws ​

A GraphtyError with E_BAD_COMMAND naming the static or the descriptor member that is missing or wrong, or with E_DUPLICATE_PLUGIN for a format name the element ships.

sourceFetchData() ​

abstract sourceFetchData(): AsyncGenerator<DataSourceChunk, void, unknown>

Defined in: graphty-element/src/data/DataSource.ts:353

Returns ​

AsyncGenerator<DataSourceChunk, void, unknown>

toRecord() ​

static toRecord(fields): AdHocData

Defined in: graphty-element/src/data/DataSource.ts:982

Turn a plain object into a record the element ingests.

A record is typed AdHocData, which is a branded map, and no object literal carries the brand -- so a format author writing typed records used to be forced into a double cast, and the element's own readers write one too. The cast belongs here, once, in the element, rather than in every reader that was ever written.

Two keys on a node record mean something to the element beyond being data: position ({x, y, z}, [x, y] or [x, y, z]) seeds the node's coordinates in FILE units, so a graph that arrives with positions arrives placed; and on an edge record the configured weight key -- weight unless data.knownFields.edgeWeightPath says otherwise -- is the weight algorithms and styles read.

Parameters ​

fields ​

Readonly<Record<string, unknown>>

The record's keys and values.

Returns ​

AdHocData

The same object, typed as a record the element accepts.

toRecords() ​

static toRecords(records): AdHocData[]

Defined in: graphty-element/src/data/DataSource.ts:991

Turn plain objects into records the element ingests. See DataSource.toRecord.

Parameters ​

records ​

readonly Readonly<Record<string, unknown>>[]

The records' keys and values.

Returns ​

AdHocData[]

The same objects, typed as records the element accepts.