@graphty/graph-io 0.3.48 → 0.3.50

package/src/index.ts

@@ -108,7 +108,7 @@ export {
 
 // ============================================================ 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), loaded on first use.
+// (@graphty/graph-io/sources/ndex, /cypher, /rest, /sparql), loaded on first use.
 export {
     SOURCE_ISSUE,
     type SourceBlockedCause,
@@ -119,7 +119,9 @@ export {
     type AwsSigV4Options,
     type CredentialBind,
     credentials,
+    credentialSlots,
     fromStorableCredential,
+    type SlotValue,
     type StorableCredential,
     storableCredential,
 } from "./sources/credentials.js";
@@ -136,8 +138,10 @@ export {
     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,
@@ -164,6 +168,7 @@ export {
     type RetryOptions,
     type SourceBase,
     type SourceContext,
+    type SourceCredentialSlot,
     type SourceCursor,
     type SourceDescriptor,
     type SourceFeature,
@@ -185,6 +190,7 @@ export {
     type SourceRuntime,
     type SourceRuntimeReason,
     type SourceSample,
+    type SourceTotal,
     type SourceValidators,
 } from "./sources/types.js";
 
@@ -227,6 +233,7 @@ export {
     type CysImportOptions,
 } from "./formats/cys/index.js";
 export {
+    type BendPoint,
     DOT_ISSUE,
     DOT_LOSS,
     DOT_STYLE_BLOCK_ATTRIBUTE,
@@ -235,6 +242,9 @@ export {
     type DotExportOptions,
     dotImporter,
     type DotImportOptions,
+    graphvizPosBends,
+    RANK_COLUMN,
+    RANK_SET_COLUMN,
 } from "./formats/dot/index.js";
 export {
     GEXF_1_2_CAPABILITIES,
@@ -281,6 +291,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). */

package/src/sources/builtins.ts

@@ -11,13 +11,15 @@ import {
     NEPTUNE_SOURCE_ID,
     OPENALEX_SOURCE_ID,
     REST_SOURCE_ID,
+    SPARQL_SOURCE_ID,
 } from "./ids.js";
 import { NDEX_DESCRIPTOR } from "./ndex/descriptor.js";
 import { OPENALEX_DESCRIPTOR, REST_DESCRIPTOR } from "./rest/descriptor.js";
+import { SPARQL_DESCRIPTOR } from "./sparql/descriptor.js";
 import { type LazySource } from "./types.js";
 
 /**
- * The six built-in sources, each loading its subpath on first use.
+ * The seven built-in sources, each loading its subpath on first use.
  * @returns the lazy sources, in catalog order
  */
 export function builtinSources(): readonly LazySource[] {
@@ -52,5 +54,10 @@ export function builtinSources(): readonly LazySource[] {
             descriptor: OPENALEX_DESCRIPTOR,
             load: async () => (await import("./rest/index.js")).openalexSource,
         },
+        {
+            id: SPARQL_SOURCE_ID,
+            descriptor: SPARQL_DESCRIPTOR,
+            load: async () => (await import("./sparql/index.js")).sparqlSource,
+        },
     ];
 }

package/src/sources/context.ts

@@ -835,6 +835,7 @@ class SourceFetcher {
             ...(finish?.server === undefined ? {} : { server: finish.server }),
             ...(finish?.budget === undefined ? {} : { budget: finish.budget }),
             ...(finish?.validators === undefined ? {} : { validators: finish.validators }),
+            ...(finish?.total === undefined ? {} : { total: finish.total }),
         });
     }
 }

package/src/sources/credentials.ts

@@ -7,7 +7,13 @@
  */
 
 import { failAlone } from "./fail.js";
-import { type AwsCredentials, type Credential, type CredentialKind } from "./types.js";
+import {
+    type AwsCredentials,
+    type Credential,
+    type CredentialKind,
+    type SourceCredentialSlot,
+    type SourceDescriptor,
+} from "./types.js";
 
 /**
  * Where a credential may go: the load's endpoint origin by default. Experimental.
@@ -145,6 +151,63 @@ function base64(text: string): string {
     return btoa(binary);
 }
 
+/**
+ * The plain value a slot's credential is made from: a key or a token, or a user name and password.
+ * @category Network sources
+ */
+export type SlotValue =
+    | string
+    | {
+          /** A basic slot's user name. */
+          readonly username: string;
+          /** A basic slot's password. */
+          readonly password: string;
+      };
+
+/**
+ * The credential a slot describes, from its plain value.
+ * @param slot - the slot
+ * @param value - the key or token, or a basic slot's user name and password
+ * @param bind - the origins it may be sent to
+ * @returns the credential
+ */
+function forSlot(slot: SourceCredentialSlot, value: SlotValue, bind?: CredentialBind): Credential {
+    if (typeof value !== "string") {
+        if (slot.kind === "basic") {
+            return new SourceCredential({ kind: "basic", username: value.username, password: value.password }, bind);
+        }
+    } else if (slot.kind === "bearer") {
+        return new SourceCredential({ kind: "bearer", token: value }, bind);
+    } else if (slot.kind === "api-key") {
+        const send = slot.send ?? { query: slot.name };
+        const header = "header" in send ? send.header : null;
+        const query = "query" in send ? send.query : null;
+        return new SourceCredential({ kind: "api-key", header, query, value }, bind);
+    }
+    return failAlone("E_SOURCE_PARAM", `a ${slot.kind} slot cannot take this value`, {
+        name: "credential",
+        reason: "type",
+    });
+}
+
+/**
+ * The credential slots a source takes: the ones its descriptor declares, else one slot `default`
+ * of its first credential kind when it takes a credential (`auth`), else none. Experimental.
+ * @param descriptor - the source's descriptor
+ * @returns the slots
+ * @category Network sources
+ */
+export function credentialSlots(descriptor: SourceDescriptor | undefined): readonly SourceCredentialSlot[] {
+    if (descriptor?.credentials !== undefined) {
+        return descriptor.credentials;
+    }
+    const kind = descriptor?.auth?.[0];
+    if (kind === undefined || descriptor?.authRequired === "none") {
+        return [];
+    }
+    return [{ name: "default", kind, required: descriptor?.authRequired === "required" }];
+}
+
 /**
  * The factories that make credentials. Pass the result as the `credential` option of a load; it is
  * sent only to the load's endpoint origin, or to `bind.origins` when you give them. Experimental.
@@ -213,6 +276,21 @@ export const credentials = Object.freeze({
     custom(apply: (request: Request) => Promise<Request> | Request, kind: string, bind?: CredentialBind): Credential {
         return new SourceCredential({ kind: "custom", name: kind, apply }, bind);
     },
+    /**
+     * The credential a source's slot describes (`credentialSlots(descriptor)`), from its plain
+     * value: an API key sent as the slot says, a bearer token, or a basic slot's user name and
+     * password.
+     * @example
+     * ```ts
+     * const [slot] = credentialSlots(openalex.descriptor); // api_key, sent as ?api_key=
+     * const credential = credentials.forSlot(slot, key);
+     * ```
+     * @param slot - the slot
+     * @param value - the key or token, or `{ username, password }` for a basic slot
+     * @param bind - the origins it may be sent to
+     * @returns the credential
+     */
+    forSlot,
 });
 
 /**
@@ -248,6 +326,17 @@ export function credentialHeader(credential: Credential): string | null {
         : null;
 }
 
+/**
+ * The query parameter a credential is sent in, so a cursor can leave it out; null for one sent in
+ * a header or not at all.
+ * @param credential - the credential
+ * @returns the parameter's name
+ */
+export function credentialQuery(credential: Credential): string | null {
+    const secret = secretOf(credential);
+    return secret?.kind === "api-key" && secret.header === null ? (secret.query ?? "api_key") : null;
+}
+
 /**
  * Add a credential to a request. Internal to graph-io: only `ctx.fetch` calls it.
  * @param credential - the credential

package/src/sources/cypher/descriptor.ts

@@ -3,7 +3,7 @@
  * the sources' code.
  */
 
-import { type SourceDescriptor, type SourceParamDescriptor } from "../types.js";
+import { type SourceDescriptor, type SourceFeature, type SourceParamDescriptor } from "../types.js";
 
 /** The parameters every Cypher source shares. */
 const CYPHER_PARAMS: readonly SourceParamDescriptor[] = [
@@ -38,6 +38,9 @@ const CYPHER_PARAMS: readonly SourceParamDescriptor[] = [
     { name: "pageSize", plainName: "Page size", type: "integer", default: 1000, min: 1, max: 100000, advanced: true },
 ];
 
+/** What every Cypher source can do: expand, probe, validate, and page a capped load. */
+const CYPHER_FEATURES: readonly SourceFeature[] = ["expand", "probe", "validate", "page"];
+
 /** The transport parameter of the generic source. */
 const TRANSPORT_PARAM: SourceParamDescriptor = {
     name: "transport",
@@ -61,6 +64,7 @@ export const CYPHER_DESCRIPTOR: SourceDescriptor = Object.freeze({
     version: 1,
     auth: ["basic", "bearer", "aws-sigv4"],
     authRequired: "optional",
+    features: CYPHER_FEATURES,
     params: [...CYPHER_PARAMS, TRANSPORT_PARAM],
 });
 
@@ -74,6 +78,7 @@ export const NEO4J_DESCRIPTOR: SourceDescriptor = Object.freeze({
     version: 1,
     auth: ["basic", "bearer"],
     authRequired: "optional",
+    features: CYPHER_FEATURES,
     params: [
         ...CYPHER_PARAMS,
         {
@@ -112,6 +117,7 @@ export const NEPTUNE_DESCRIPTOR: SourceDescriptor = Object.freeze({
     version: 1,
     auth: ["aws-sigv4"],
     authRequired: "optional",
+    features: CYPHER_FEATURES,
     params: [
         ...CYPHER_PARAMS,
         {