@graphty/graph-io 0.3.47 → 0.3.49

package/src/index.ts

@@ -62,6 +62,7 @@ export {
     createRegistry,
     downloadGraph,
     type DownloadGraphOptions,
+    expandFromSource,
     exportGraph,
     type ExportGraphOptions,
     exportGraphToBlob,
@@ -70,18 +71,25 @@ export {
     type FormatInfo,
     FormatRegistry,
     importAllGraphs,
+    importFromSource,
     importGraph,
     type ImportGraphOptions,
     type ImportGraphResult,
     listFormats,
+    listFromSource,
     listGraphs,
+    listSources,
     loadFromFile,
+    loadFromSource,
     loadFromUrl,
     type LoadFromUrlOptions,
+    probeSource,
+    registerSource,
     registry,
     sniff,
     SNIFF_FAILED_CODE,
     UNKNOWN_FORMAT_CODE,
+    validateSource,
 } from "./registry.js";
 export {
     extensionOf,
@@ -98,6 +106,91 @@ export {
     type SniffResult,
 } from "./sniff.js";
 
+// ============================================================ network sources (experimental)
+// The contract, the load functions and credentials; each built-in source's code is its own subpath
+// (@graphty/graph-io/sources/ndex, /cypher, /rest, /sparql), loaded on first use.
+export {
+    SOURCE_ISSUE,
+    type SourceBlockedCause,
+    type SourceIssueCode,
+    type SourceIssueParams,
+} from "./sources/codes.js";
+export {
+    type AwsSigV4Options,
+    type CredentialBind,
+    credentials,
+    fromStorableCredential,
+    type StorableCredential,
+    storableCredential,
+} from "./sources/credentials.js";
+export { defineSource } from "./sources/define.js";
+export {
+    CYPHER_SOURCE_ID,
+    NDEX_SOURCE_ID,
+    NEO4J_SOURCE_ID,
+    NEPTUNE_SOURCE_ID,
+    OPENALEX_SOURCE_ID,
+    REST_SOURCE_ID,
+    SOURCE_ATTR_PREFIX,
+    SOURCE_DEGREE_ATTR,
+    SOURCE_ENTITY_ATTR,
+    SOURCE_FORMAT_PREFIX,
+    SOURCE_STUB_ATTR,
+    SPARQL_SOURCE_ID,
+} from "./sources/ids.js";
+export { type SourceParamsMap } from "./sources/params.js";
+export { sha256Hex } from "./sources/sigv4.js";
+export {
+    type Recording,
+    recordingFrom,
+    type ReplayCall,
+    type ReplayFetch,
+    replayFetch,
+    type ReplayOptions,
+} from "./sources/testing.js";
+export {
+    type AwsCredentials,
+    type Credential,
+    type CredentialKind,
+    type EdgeRecord,
+    type ExpandRequest,
+    type FileFn,
+    type GraphSource,
+    type ImportFn,
+    type LazySource,
+    type LoadFromSourceOptions,
+    type NodeRecord,
+    type QueryLanguage,
+    type RecordBatch,
+    type RecordsFn,
+    type RetryOptions,
+    type SourceBase,
+    type SourceContext,
+    type SourceCursor,
+    type SourceDescriptor,
+    type SourceFeature,
+    type SourceFile,
+    type SourceFinish,
+    type SourceFreshness,
+    type SourceInfo,
+    type SourceKind,
+    type SourceLimitOptions,
+    type SourceLimits,
+    type SourceListing,
+    type SourceListItem,
+    type SourceListQuery,
+    type SourceParamDescriptor,
+    type SourceParamType,
+    type SourceProbe,
+    type SourceReportInfo,
+    type SourceRequestInit,
+    type SourceRuntime,
+    type SourceRuntimeReason,
+    type SourceSample,
+    type SourceTotal,
+    type SourceValidators,
+} from "./sources/types.js";
+
 // ============================================================ formats (8.4, 8.5)
 export {
     CSV_CAPABILITIES,
@@ -191,6 +284,7 @@ export {
     type JsonImportOptions,
     type JsonShapeMeta,
     jsonShapeOf,
+    sniffJsonDialect,
 } from "./formats/json/index.js";
 export {
     exportNeo4jFiles,

package/src/positions/convert.ts

@@ -16,6 +16,15 @@ export function flipY(y: number): number {
     return y === 0 ? 0 : -y;
 }
 
+/**
+ * How much longer a unit of y is than a unit of x, for a program that stretches its axes apart.
+ * @param extra - how the file spells its coordinates
+ * @returns `pxPerUnitY / pxPerUnit`, 1 when either is absent
+ */
+function yStretch(extra: PositionColumnExtra): number {
+    return extra.pxPerUnit === undefined || extra.pxPerUnitY === undefined ? 1 : extra.pxPerUnitY / extra.pxPerUnit;
+}
+
 /**
  * One coordinate from a file's spelling into the neutral convention, in place.
  * @param p - x, y, z as the file wrote them; becomes the node's center, y up
@@ -29,6 +38,7 @@ export function toNeutral(
     size: readonly [number, number] | null,
     realZ: boolean,
 ): void {
+    p[1] *= yStretch(extra);
     if (extra.anchor === "top-left" && size !== null) {
         p[0] += size[0] / 2;
         p[1] += extra.yAxis === "down" ? size[1] / 2 : -size[1] / 2;
@@ -60,8 +70,9 @@ export function toFilePositions(
 ): Float64Array {
     const out = new Float64Array(coords.length);
     const down = extra.yAxis === "down";
+    const stretch = yStretch(extra);
     for (let i = 0; i < coords.length; i += 3) {
-        let y = coords[i + 1];
+        let y = coords[i + 1] / stretch;
         let z = coords[i + 2];
         if (down) {
             y = flipY(y);

package/src/positions/extract.ts

@@ -89,6 +89,11 @@ export function extractPositions(
     const coords = readRows(n, spelling, notes);
     signal?.throwIfAborted();
     const containers = containersOf(snapshot);
+    if (spelling.extra.containersFollowChildren === true) {
+        for (const row of containers) {
+            coords.values.fill(Number.NaN, 3 * row, 3 * row + 3);
+        }
+    }
     const groups = applyGroups(spelling, coords);
     collectGroups(spelling, coords, containers, groups);
     const { placed, total } = countPlaced(coords, containers, notes);
@@ -104,6 +109,7 @@ export function extractPositions(
         },
         units: spelling.extra.units ?? "file",
         ...(spelling.extra.pxPerUnit === undefined ? {} : { pxPerUnit: spelling.extra.pxPerUnit }),
+        ...(spelling.extra.viewerFit === undefined ? {} : { viewerFit: spelling.extra.viewerFit }),
         medianNodeSize: spelling.medianNodeSize ?? medianSize(spelling.size, n, containers),
         dims: coords.realZ ? 3 : 2,
         coords: coords.values,
@@ -132,12 +138,35 @@ function spellingOf(importer: GraphImporter, snapshot: GraphSnapshot, signal: Ab
     }
     const column = hook?.column === undefined ? snapshot.nodes.byRole("position") : snapshot.nodes.get(hook.column);
     if (column === null || column.meta.components < 2) {
-        return null;
+        return hook?.unplacedCircle === undefined ? null : circleSpelling(snapshot, hook);
     }
     const extra = { ...extraOf(column.meta.extra), ...extraOf(hook ?? {}) };
     return { read: vectorReader(column), size: sizeReader(snapshot, extra), extra, ...hookFields(hook) };
 }
 
+/**
+ * The spelling of a file that places no node, whose program puts them round a circle (`unplacedCircle`).
+ * @param snapshot - the graph
+ * @param hook - the hook's answer, with its circle
+ * @returns the spelling
+ */
+function circleSpelling(snapshot: GraphSnapshot, hook: ImporterPositions): Spelling {
+    const circle = hook.unplacedCircle;
+    const n = snapshot.nodeCount;
+    const read: RowReader = (row, out) => {
+        if (circle === undefined || n === 0) {
+            return false;
+        }
+        const a = ((circle.startDegrees + (circle.direction * 360 * row) / n) * Math.PI) / 180;
+        out[0] = circle.center[0] + circle.radius * Math.cos(a);
+        out[1] = circle.center[1] + circle.radius * Math.sin(a);
+        out[2] = 0;
+        return true;
+    };
+    const extra = { ...extraOf(hook), sourceDims: 2 } as const;
+    return { read, size: sizeReader(snapshot, extra), extra, ...hookFields(hook) };
+}
+
 /**
  * The spelling of the simple hook form: plain x / y (/ z) columns.
  * @param snapshot - the graph
@@ -211,8 +240,15 @@ function extraOf(source: object): PositionColumnExtra {
     pick("width", (v) => typeof v === "string");
     pick("height", (v) => typeof v === "string");
     pick("pxPerUnit", (v) => typeof v === "number" && Number.isFinite(v) && v > 0);
+    pick("pxPerUnitY", (v) => typeof v === "number" && Number.isFinite(v) && v > 0);
     pick("zOrigin", (v) => typeof v === "number" && Number.isFinite(v));
     pick("zeroUnplaced", (v) => typeof v === "boolean");
+    pick("originUnplaced", (v) => typeof v === "boolean");
+    pick("containersFollowChildren", (v) => typeof v === "boolean");
+    const fit = extra.viewerFit as Readonly<Record<string, unknown>> | null | undefined;
+    if (typeof fit?.padding === "number" && Number.isFinite(fit.padding) && fit.padding >= 0) {
+        out.viewerFit = { padding: fit.padding };
+    }
     return out;
 }
 
@@ -247,11 +283,29 @@ function readRows(n: number, spelling: Spelling, notes: NoteCollector<PositionNo
     if (spelling.extra.zeroUnplaced === true) {
         dropZeroPile(values);
     }
+    if (spelling.extra.originUnplaced === true) {
+        placeUnplacedAtOrigin(values);
+    }
     const realZ = spelling.extra.sourceDims === 3 && !constantZ(values);
     convertRows(values, spelling.extra, spelling.size, realZ, notes);
     return { values, realZ };
 }
 
+/**
+ * Put every unplaced row at the origin, when at least one row is placed.
+ * @param values - the coordinates, three per row; NaN rows are unplaced
+ */
+function placeUnplacedAtOrigin(values: Float64Array): void {
+    if (!values.some((v) => !Number.isNaN(v))) {
+        return;
+    }
+    for (let i = 0; i < values.length; i += 3) {
+        if (Number.isNaN(values[i])) {
+            values.fill(0, i, i + 3);
+        }
+    }
+}
+
 /**
  * Convert every placed row in place.
  * @param values - the raw coordinates

package/src/positions/index.ts

@@ -19,5 +19,6 @@ export type {
     PositionColumnExtra,
     PositionNote,
     PositionReadContext,
+    ViewerFit,
     YAxis,
 } from "./types.js";

package/src/positions/types.ts

@@ -41,6 +41,19 @@ export interface PositionColumnExtra {
      * the same unit as the file's px style lengths; the coordinates themselves stay as written.
      */
     readonly pxPerUnit?: number;
+    /**
+     * How many px one unit of y is, when the program that draws the file stretches its axes apart
+     * (Pajek fits the file's 0..1 square to its Draw window, x across the width and y down the
+     * height); absent when y is `pxPerUnit` like x. `extractPositions()` returns y in x's unit.
+     */
+    readonly pxPerUnitY?: number;
+    /**
+     * Set when the coordinates have no fixed length: the program that draws the file fits their
+     * bounding box into its canvas, `padding` px in from each side, and draws label sizes in the
+     * canvas's px rather than in the coordinates' unit (sigma.js). Absent when the coordinates
+     * keep their own length.
+     */
+    readonly viewerFit?: ViewerFit;
     /** How many coordinates the file wrote per node: 2, or 3 when it stored a z. */
     readonly sourceDims?: 2 | 3;
     /** Which way y grows; "down" is flipped to y up. */
@@ -58,6 +71,30 @@ export interface PositionColumnExtra {
      * rows are placed, a (0, 0) shared by two or more rows counts as unplaced.
      */
     readonly zeroUnplaced?: boolean;
+    /**
+     * The program that draws the file puts a node the file gives no position at the origin, (0, 0, 0) as written,
+     * when other nodes are placed (Gephi), rather than leaving it for a layout to place.
+     */
+    readonly originUnplaced?: boolean;
+    /**
+     * The program that draws the file draws a container node (one other nodes name as their
+     * parent) around its children, wherever the container's own stored coordinate says: Cytoscape.js
+     * computes a compound node's position and size from its children's. A container's stored
+     * coordinate is then not read, and it has no position here unless the file stores its box.
+     */
+    readonly containersFollowChildren?: boolean;
+}
+
+/**
+ * How the program that draws a file fits coordinates that have no fixed length into its canvas.
+ * @category Positions
+ */
+export interface ViewerFit {
+    /**
+     * The px the fitted bounding box keeps from each end of the canvas's smaller side; along the
+     * longer side the room is that side's share of the same fraction (sigma.js's `stagePadding`).
+     */
+    readonly padding: number;
 }
 
 /**
@@ -104,6 +141,22 @@ export interface ImporterPositions extends PositionColumnExtra {
     readonly medianNodeSize?: number | null;
     /** The tool that wrote the file, when the importer knows it better than `meta.creator`. */
     readonly tool?: GraphTool | null;
+    /**
+     * Where the program that draws the file puts its nodes when the file places none: evenly round a circle in node
+     * order, the first at `startDegrees`, each next one further round in `direction` (1: the angle grows, -1: it
+     * shrinks), in the file's own coordinates as the rest of this answer spells them (Pajek: center 0.5, 0.5, radius
+     * 0.4, the first vertex on the left). Absent, such a file has no positions.
+     */
+    readonly unplacedCircle?: {
+        /** The circle's center, x and y. */
+        readonly center: readonly [number, number];
+        /** Its radius. */
+        readonly radius: number;
+        /** The angle of the first node, in degrees. */
+        readonly startDegrees: number;
+        /** Which way round the next nodes go: 1 the angle grows, -1 it shrinks. */
+        readonly direction: 1 | -1;
+    };
 }
 
 /**
@@ -186,6 +239,13 @@ export interface FilePositions {
      * it with the file's px style lengths.
      */
     readonly pxPerUnit?: number;
+    /**
+     * Set when the coordinates have no fixed length: the program that draws the file fits their
+     * bounding box into its canvas, `padding` px in from each side, and draws label sizes in the
+     * canvas's px (sigma.js). A label of `s` px is then `s / k` units, where k is the px per unit of
+     * that fit on the canvas it is drawn on. Absent otherwise.
+     */
+    readonly viewerFit?: ViewerFit;
     /** The median node diameter, in `units`, when the file stores node sizes; else null. */
     readonly medianNodeSize: number | null;
     /** 3 when the nodes differ in z, else 2 (z is then 0). */