@graphty/graph-io 0.3.48 → 0.3.49

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,
@@ -136,8 +136,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,
@@ -185,6 +187,7 @@ export {
     type SourceRuntime,
     type SourceRuntimeReason,
     type SourceSample,
+    type SourceTotal,
     type SourceValidators,
 } from "./sources/types.js";
 
@@ -281,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). */

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/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,
         {

package/src/sources/cypher/index.ts

@@ -25,10 +25,11 @@ import {
     type SourceDescriptor,
     type SourceFreshness,
     type SourceProbe,
+    type SourceTotal,
     type SourceValidators,
 } from "../types.js";
 import { CYPHER_DESCRIPTOR, NEO4J_DESCRIPTOR, NEPTUNE_DESCRIPTOR } from "./descriptor.js";
-import { canonicalRows, Collector, compareText, requireGraph, writeCollected } from "./flatten.js";
+import { canonicalRows, Collector, compareText, type QueryResult, requireGraph, writeCollected } from "./flatten.js";
 import { type CypherParams } from "./params.js";
 import { type CypherProfile, neo4jProfile, neptuneProfile, serverFacts } from "./profiles.js";
 import {
@@ -36,12 +37,14 @@ import {
     counts,
     DEFAULT_PAGE_SIZE,
     edgePage,
+    edgesAmong,
     MAX_DEPTH,
     MAX_PAGE_SIZE,
     neighborhood,
     nodePage,
     type QueryFilters,
     quoted,
+    storeCount,
 } from "./query-builder.js";
 import { boltTransport } from "./transports/bolt.js";
 import { neptuneAnalyticsTransport } from "./transports/neptune-analytics.js";
@@ -77,6 +80,20 @@ interface Page {
 /** The directions an expansion may follow. */
 const DIRECTIONS: ReadonlySet<string> = new Set(["out", "in", "both"]);
 
+/**
+ * A query without the semicolons it ends with, so it can sit inside `CALL { }`. A loop, not
+ * `/;+$/`, which backtracks over every run of semicolons that is not at the end.
+ * @param query - the trimmed query
+ * @returns the query
+ */
+function withoutTrailingSemicolons(query: string): string {
+    let end = query.length;
+    while (end > 0 && query[end - 1] === ";") {
+        end--;
+    }
+    return query.slice(0, end);
+}
+
 /**
  * A list parameter: an array, or one value. A string is one item, never split, since an id or a
  * label may hold any character.
@@ -124,6 +141,8 @@ class Reader {
     private known: CypherProfile | null = null;
     private degree = true;
     readonly filters: QueryFilters;
+    /** What the source holds for this load, when a count ran. */
+    counted: SourceTotal | undefined;
     /** The raw id property, for the node ids. */
     readonly idProperty: string | null;
 
@@ -195,9 +214,10 @@ class Reader {
     /**
      * The pages of a read, as `mode` asks.
      * @param cursor - where to resume
+     * @param counting - whether a first page of mode "all" may count what the source holds
      * @yields one page at a time
      */
-    async *pages(cursor: SourceCursor | null): AsyncGenerator<Page> {
+    async *pages(cursor: SourceCursor | null, counting = true): AsyncGenerator<Page> {
         const { params, ctx } = this;
         const { report } = ctx;
         const mode = params.mode ?? (typeof params.query === "string" && params.query !== "" ? "query" : "all");
@@ -205,11 +225,7 @@ class Reader {
             if (typeof params.query !== "string" || params.query.trim() === "") {
                 failOn(report, "E_SOURCE_PARAM", "mode query needs a query", { name: "query", reason: "required" });
             }
-            const result = await this.transport.run(params.query, params.parameters ?? {});
-            const collected = new Collector();
-            collected.add(result, false);
-            requireGraph(result, collected, report);
-            yield { collected, next: null };
+            yield await this.userQuery(params.query, cursor);
             return;
         }
         const profile = await this.profile();
@@ -230,7 +246,47 @@ class Reader {
             yield { collected, next: null };
             return;
         }
-        yield* this.everything(profile, cursor);
+        yield* this.everything(profile, cursor, counting);
+    }
+
+    /**
+     * Mode "query": the reader's own query, as written. With a node cap (or a cursor from a capped
+     * run) the server returns at most that many rows (`CALL { query } RETURN * LIMIT n`), and a full
+     * result hands back a cursor that runs the query again with twice the rows, for the caller to
+     * merge. A server that refuses the wrapper runs the query uncapped.
+     * @param query - the query
+     * @param cursor - where to resume: `{ rows }` from an earlier capped run
+     * @returns the one page
+     */
+    private async userQuery(query: string, cursor: SourceCursor | null): Promise<Page> {
+        const { params, ctx } = this;
+        const parameters = params.parameters ?? {};
+        const asked = cursor?.rows ?? ctx.limits.maxNodes;
+        const rows =
+            asked === undefined || asked === null
+                ? null
+                : Number(checkedInteger(asked, "maxNodes", 1, Number.MAX_SAFE_INTEGER, ctx.report));
+        let result: QueryResult;
+        let capped = rows !== null;
+        try {
+            result = await this.transport.run(
+                rows === null
+                    ? query
+                    : `CALL {\n${withoutTrailingSemicolons(query.trim())}\n}\nRETURN * LIMIT ${String(rows)}`,
+                parameters,
+            );
+        } catch (err) {
+            if (!capped || !(err instanceof ImportError) || err.issue?.code !== SOURCE_ISSUE.E_SOURCE_QUERY) {
+                throw err;
+            }
+            capped = false;
+            result = await this.transport.run(query, parameters);
+        }
+        const collected = new Collector();
+        collected.add(result, false);
+        requireGraph(result, collected, ctx.report);
+        const full = capped && rows !== null && result.rows.length >= rows;
+        return { collected, next: full ? { rows: rows * 2 } : null };
     }
 
     /**
@@ -238,14 +294,33 @@ class Reader {
      * id expression (never SKIP), so a page is stable under unrelated writes.
      * @param profile - the server's profile
      * @param cursor - where to resume
+     * @param counting - whether a first page may count what the source holds
      * @yields one page at a time
      */
-    private async *everything(profile: CypherProfile, cursor: SourceCursor | null): AsyncGenerator<Page> {
+    private async *everything(
+        profile: CypherProfile,
+        cursor: SourceCursor | null,
+        counting: boolean,
+    ): AsyncGenerator<Page> {
         const { params, ctx } = this;
         const size = checkedInteger(params.pageSize ?? DEFAULT_PAGE_SIZE, "pageSize", 1, MAX_PAGE_SIZE, ctx.report);
+        if (cursor === null && counting) {
+            this.counted = await this.count(profile);
+        }
+        const cap = ctx.limits.maxNodes;
+        if (cap !== undefined && cursor?.phase !== "edges") {
+            const capped = Number(checkedInteger(cap, "maxNodes", 1, Number.MAX_SAFE_INTEGER, ctx.report));
+            yield* this.cappedNodes(profile, cursor, Math.min(Number(size), capped));
+            return;
+        }
+
         let phase: "nodes" | "edges" = cursor?.phase === "edges" ? "edges" : "nodes";
         let after: string | number | boolean | null = cursor?.after ?? null;
-        const total = params.countFirst === true && cursor === null ? await this.total() : undefined;
+        const { counted } = this;
+        const total =
+            params.countFirst === true && counted !== undefined
+                ? (counted.nodes ?? 0) + (counted.edges ?? 0)
+                : undefined;
         for (;;) {
             const nodes = phase === "nodes";
             const { collected, rows, fields } = await this.generated(
@@ -268,13 +343,67 @@ class Reader {
     }
 
     /**
-     * How many nodes and relationships the filters match, for progress.
-     * @returns the count
+     * Mode "all" under a node cap: pages of at most the cap's nodes, each with the relationships
+     * among the nodes loaded so far, so a capped load stops at its cap with its edges, and its
+     * next page (`data.more`) continues by key.
+     * @param profile - the server's profile
+     * @param cursor - where to resume
+     * @param size - the page size
+     * @yields one page at a time
+     */
+    private async *cappedNodes(
+        profile: CypherProfile,
+        cursor: SourceCursor | null,
+        size: number,
+    ): AsyncGenerator<Page> {
+        let after: string | number | boolean | null = cursor?.after ?? null;
+        for (;;) {
+            const { collected, rows, fields } = await this.generated(
+                (d) => nodePage(profile, this.filters, String(size), after !== null, d),
+                after === null ? {} : { after },
+            );
+            const last = rows.at(-1)?.[fields.indexOf("key")];
+            const key = typeof last === "string" || typeof last === "number" ? last : null;
+            if (key !== null) {
+                const among = await this.transport.run(edgesAmong(profile, this.filters, after !== null), {
+                    last: key,
+                    ...(after === null ? {} : { after }),
+                });
+                collected.add(among, false);
+            }
+            const next = rows.length >= size && key !== null ? { phase: "nodes", after: key } : null;
+            yield { collected, next };
+            if (next === null) {
+                return;
+            }
+            after = key;
+        }
+    }
+
+    /**
+     * What a first page of mode "all" counts: with `countFirst`, the nodes and relationships the
+     * filters match (for progress too); else, on Neo4j with at most one label and the server's
+     * ids, the nodes from the count store; else nothing.
+     * @param profile - the server's profile
+     * @returns the count, or undefined
      */
-    private async total(): Promise<number> {
-        const [n, r] = counts(this.filters);
-        const [a, b] = await Promise.all([this.transport.run(n, {}), this.transport.run(r, {})]);
-        return Number(a.rows[0]?.[0] ?? 0) + Number(b.rows[0]?.[0] ?? 0);
+    private async count(profile: CypherProfile): Promise<SourceTotal | undefined> {
+        // A count is a non-negative integer; anything else a server answers is no count.
+        const first = async (statement: string): Promise<number | undefined> => {
+            const c = Number((await this.transport.run(statement, {})).rows[0]?.[0]);
+            return Number.isSafeInteger(c) && c >= 0 ? c : undefined;
+        };
+        const { labels, idProperty } = this.filters;
+        if (this.params.countFirst === true) {
+            const [n, r] = counts(this.filters);
+            const [nodes, edges] = await Promise.all([first(n), first(r)]);
+            return { ...(nodes === undefined ? {} : { nodes }), ...(edges === undefined ? {} : { edges }) };
+        }
+        if (profile.name !== "neo4j" || labels.length > 1 || idProperty !== null) {
+            return undefined;
+        }
+        const nodes = await first(storeCount(labels[0]));
+        return nodes === undefined ? undefined : { nodes };
     }
 
     /**
@@ -392,7 +521,8 @@ function cypher(preset: Preset): GraphSource<CypherParams> {
                         break;
                     }
                 }
-                return ctx.finish({ next, ...(await reader.facts(lines)) });
+                const total = reader.counted === undefined ? {} : { total: reader.counted };
+                return ctx.finish({ next, ...total, ...(await reader.facts(lines)) });
             }),
         expand: (request, sink, ctx) =>
             withReader(request.params, ctx, preset, (reader) => expand(reader, request, sink)),
@@ -404,7 +534,7 @@ function cypher(preset: Preset): GraphSource<CypherParams> {
         validate: (params, seen, ctx) =>
             withReader(params, ctx, preset, async (reader): Promise<SourceFreshness> => {
                 const lines: string[] = [];
-                for await (const page of reader.pages(null)) {
+                for await (const page of reader.pages(null, false)) {
                     lines.push(...canonicalRows(page.collected, reader.idProperty));
                 }
                 const { validators } = await reader.facts(lines);

package/src/sources/cypher/params.ts

@@ -36,6 +36,6 @@ export interface CypherParams {
     readonly long?: "f64" | "string" | undefined;
     /** Run a count first, for a progress total. @defaultValue false */
     readonly countFirst?: boolean | undefined;
-    /** Rows per page of mode "all", 1 to 100000. A load stops between pages, so a cap overshoots by at most one page. @defaultValue 1000 */
+    /** Rows per page of mode "all", 1 to 100000. Under a node cap a page holds at most the cap's nodes, with the relationships among the nodes loaded so far. @defaultValue 1000 */
     readonly pageSize?: number | undefined;
 }

package/src/sources/cypher/query-builder.ts

@@ -215,6 +215,28 @@ export function edgePage(profile: CypherProfile, filters: QueryFilters, pageSize
         .join(" ");
 }
 
+/**
+ * The relationships among the nodes a capped mode "all" has loaded: both ends at or before the
+ * node page's last key `$last`, and, after the first page, one end past the previous page's last
+ * key `$after`, so each relationship arrives with the page that loads its later end.
+ * @param profile - the server's profile
+ * @param filters - the filters
+ * @param after - whether earlier pages were loaded
+ * @returns the statement; it reads `$last` and `$after`
+ */
+export function edgesAmong(profile: CypherProfile, filters: QueryFilters, after: boolean): string {
+    const where = [nodePredicate("a", filters), nodePredicate("b", filters)].filter((p) => p !== null);
+    return [
+        `MATCH (a)-[r${typesPattern(filters)}]->(b)`,
+        where.length === 0 ? null : `WHERE ${where.join(" AND ")}`,
+        `WITH a, r, b, ${idExpression("a", profile, filters)} AS ka, ${idExpression("b", profile, filters)} AS kb`,
+        `WHERE ka <= $last AND kb <= $last${after ? " AND (ka > $after OR kb > $after)" : ""}`,
+        "RETURN a, r, b",
+    ]
+        .filter((l) => l !== null)
+        .join(" ");
+}
+
 /** How far a neighborhood reaches. */
 interface NeighborhoodShape {
     /** The checked depth, as text. */
@@ -292,3 +314,14 @@ export function counts(filters: QueryFilters): readonly [string, string] {
         `MATCH (a)-[r${typesPattern(filters)}]->(b)${whereClause(where.length === 0 ? null : where.join(" AND "))} RETURN count(r) AS c`,
     ];
 }
+
+/**
+ * The node count of a mode "all" load with at most one label and the server's ids: a pattern
+ * Neo4j answers from its count store in one cheap lookup, whatever the graph's size.
+ * @param label - the quoted label, or undefined for every node
+ * @returns the statement
+ */
+export function storeCount(label: string | undefined): string {
+    const pattern = label === undefined ? "n" : `n:${label}`;
+    return `MATCH (${pattern}) RETURN count(n) AS c`;
+}

package/src/sources/ids.ts

@@ -42,6 +42,12 @@ export const REST_SOURCE_ID = "rest";
  */
 export const OPENALEX_SOURCE_ID = "openalex";
 
+/**
+ * The SPARQL source, for any SPARQL 1.1 endpoint. Experimental.
+ * @category Network sources
+ */
+export const SPARQL_SOURCE_ID = "sparql";
+
 /**
  * The prefix of the reserved attribute namespace sources and graphty-element write facts under.
  * @category Network sources