@graphty/graph-io 0.3.48 → 0.3.50

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,49 @@ 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 fails the load with `E_SOURCE_PARAM` (`name:
+     * "maxNodes"`, `reason: "uncappable"`): the query is never run past the cap the caller set.
+     * @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;
+        try {
+            result = await this.transport.run(
+                rows === null
+                    ? query
+                    : `CALL {\n${withoutTrailingSemicolons(query.trim())}\n}\nRETURN * LIMIT ${String(rows)}`,
+                parameters,
+            );
+        } catch (err) {
+            if (rows === null || !(err instanceof ImportError) || err.issue?.code !== SOURCE_ISSUE.E_SOURCE_QUERY) {
+                throw err;
+            }
+            return failOn(ctx.report, "E_SOURCE_PARAM", "the server cannot cap this query; load it without maxNodes", {
+                name: "maxNodes",
+                reason: "uncappable",
+            });
+        }
+        const collected = new Collector();
+        collected.add(result, false);
+        requireGraph(result, collected, ctx.report);
+        const full = rows !== null && result.rows.length >= rows;
+        return { collected, next: full ? { rows: rows * 2 } : null };
     }
 
     /**
@@ -238,14 +296,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 +345,66 @@ 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 at = fields.indexOf("key");
+            const last = rows.at(-1)?.[at];
+            const key = typeof last === "string" || typeof last === "number" ? last : null;
+            if (key !== null) {
+                const keys = rows.map((row) => row[at]);
+                const among = await this.transport.run(edgesAmong(profile, this.filters), { keys, last: key });
+                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 +522,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 +535,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 that touch one node page: each
+ * starts from the page's own nodes `$keys` (an id or index lookup, never a scan of every
+ * relationship), with its other end on this page or an earlier one (at or before `$last`), so each
+ * relationship arrives once, with the page that loads its later end.
+ * @param profile - the server's profile
+ * @param filters - the filters
+ * @returns the statement; it reads `$keys` and `$last`
+ */
+export function edgesAmong(profile: CypherProfile, filters: QueryFilters): string {
+    const ka = idExpression("a", profile, filters);
+    const kb = idExpression("b", profile, filters);
+    const ends = [nodePredicate("a", filters), nodePredicate("b", filters)].filter((p) => p !== null);
+    const rest = ends.length === 0 ? "" : ` AND ${ends.join(" AND ")}`;
+    const pattern = `MATCH (a)-[r${typesPattern(filters)}]->(b)`;
+    return [
+        `${pattern} WHERE ${ka} IN $keys AND ${kb} <= $last${rest} RETURN a, r, b`,
+        "UNION ALL",
+        `${pattern} WHERE ${kb} IN $keys AND ${ka} <= $last AND NOT ${ka} IN $keys${rest} RETURN a, r, b`,
+    ].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

package/src/sources/params.ts

@@ -6,6 +6,7 @@
 import { type CypherParams } from "./cypher/params.js";
 import { type NdexParams } from "./ndex/params.js";
 import { type OpenAlexParams, type RestParams } from "./rest/params.js";
+import { type SparqlParams } from "./sparql/params.js";
 
 /**
  * Parameter types by source id; extend it by declaration merging:
@@ -26,4 +27,6 @@ export interface SourceParamsMap {
     rest: RestParams;
     /** OpenAlex. */
     openalex: OpenAlexParams;
+    /** Any SPARQL 1.1 endpoint. */
+    sparql: SparqlParams;
 }

package/src/sources/rest/descriptor.ts

@@ -17,6 +17,8 @@ export const REST_DESCRIPTOR: SourceDescriptor = Object.freeze({
     version: 1,
     auth: ["bearer", "api-key"],
     authRequired: "optional",
+    // ponytail: a mapping without `expand` or paging cannot do either; per-mapping features when a form needs them
+    features: ["expand", "probe", "validate", "page"],
     params: [{ name: "mapping", plainName: "Mapping", type: "text", required: true }],
     samples: [
         {
@@ -47,7 +49,13 @@ export const OPENALEX_DESCRIPTOR: SourceDescriptor = Object.freeze({
     defaultEndpoint: "https://api.openalex.org",
     auth: ["api-key"],
     authRequired: "optional",
+    // OpenAlex documents its key as the api_key query parameter
+    credentials: [
+        { name: "api_key", kind: "api-key", required: false, plainName: "API key", send: { query: "api_key" } },
+    ],
+    apiKey: { query: "api_key" },
     rateLimit: { requests: 10, perMs: 1000 },
+    features: ["expand", "probe", "validate", "page"],
     params: [
         { name: "work", plainName: "Work", type: "string" },
         { name: "author", plainName: "Author", type: "string" },
@@ -69,6 +77,7 @@ export const OPENALEX_DESCRIPTOR: SourceDescriptor = Object.freeze({
             plainName: "Watts-Strogatz paper's citations",
             params: { work: "W2112090702" },
             whole: false,
+            firstPage: 200,
         },
     ],
 });

package/src/sources/rest/openalex.ts

@@ -266,8 +266,10 @@ const methods = restMethods<OpenAlexParams>(plan, false);
  * The OpenAlex preset (https://openalex.org): `work` (the citation graph around a work, default)
  * or `author` (the works they wrote), `graph: "coauthorship"` for authors joined by shared works,
  * and `include` (`"authors"`, `"institutions"`, `"topics"`) for more node kinds. Without a key,
- * the first page loads and a later one warns W_SOURCE_AUTH with `report.source.next`; pass
- * `credentials.apiKey({ query: "api_key" }, key)` and continue with the cursor. Experimental.
+ * the first page loads and a later one warns W_SOURCE_AUTH with `report.source.next`. Its one
+ * optional credential slot, `api_key`, is sent as the `api_key` query parameter: pass
+ * `credentials.forSlot(slot, key)` (or `credentials.apiKey({ query: "api_key" }, key)`) and
+ * continue with the cursor. Experimental.
  * @category Network sources
  */
 export const openalexSource: GraphSource<OpenAlexParams> = defineSource<OpenAlexParams>({

package/src/sources/rest/source.ts

@@ -19,6 +19,7 @@ import {
     type GraphSource,
     type RecordBatch,
     type SourceContext,
+    type SourceCredentialSlot,
     type SourceCursor,
     type SourceDescriptor,
     type SourceFinish,
@@ -697,6 +698,44 @@ export type RestSourceInfo = {
     readonly id: string;
 } & Partial<SourceDescriptor>;
 
+/**
+ * The credential slot a mapping's `auth` describes: an API key's slot is named by the query
+ * parameter or header it is sent in (`{ query: "api_key" }` is the slot `api_key`), a bearer
+ * token's is `default`. Optional, as a mapping cannot say a key is required.
+ * @param mapping - the mapping
+ * @returns the slots
+ */
+function mappingSlots(mapping: RestMapping): readonly SourceCredentialSlot[] {
+    const { auth } = mapping;
+    if (auth === undefined) {
+        return [];
+    }
+    if (auth.kind === "bearer") {
+        return [{ name: "default", kind: "bearer", required: false }];
+    }
+    const { header } = auth;
+    if (header !== undefined) {
+        return [{ name: header.toLowerCase(), kind: "api-key", required: false, send: { header } }];
+    }
+    const query = auth.query ?? "api_key";
+    return [{ name: query, kind: "api-key", required: false, send: { query } }];
+}
+
+/**
+ * Where a mapping's API key goes, as a descriptor says it.
+ * @param auth - the mapping's auth
+ * @returns `{ apiKey }`, or nothing when the mapping takes no key or does not say where
+ */
+function apiKeyOf(auth: RestMapping["auth"]): Pick<SourceDescriptor, "apiKey"> {
+    if (auth?.kind !== "api-key") {
+        return {};
+    }
+    if (auth.header !== undefined) {
+        return { apiKey: { header: auth.header } };
+    }
+    return auth.query === undefined ? {} : { apiKey: { query: auth.query } };
+}
+
 /**
  * Turn a REST mapping into a source: a `records` source that loads the mapping's `load` request
  * page by page, with `expand` (breadth-first over the `expand` requests, `{ids}` batched; depth 0
@@ -733,6 +772,8 @@ export function restSource(mapping: RestMapping, info: RestSourceInfo): GraphSou
         defaultEndpoint: mapping.endpoint,
         auth,
         authRequired: auth.length === 0 ? "none" : "optional",
+        credentials: mappingSlots(mapping),
+        ...apiKeyOf(mapping.auth),
         ...(mapping.rateLimit === undefined ? {} : { rateLimit: mapping.rateLimit }),
         ...fields,
     });

package/src/sources/run.ts

@@ -15,7 +15,7 @@ import { type FormatRegistry } from "../registry.js";
 import { SNIFF_HEAD_BYTES } from "../sniff.js";
 import { type CommonImportOptions, ImportError, type ImportInput, type ImportReport } from "../types.js";
 import { type CreatedContext, createSourceContext, detectRuntime, LimitStop } from "./context.js";
-import { originOf } from "./credentials.js";
+import { credentialQuery, originOf } from "./credentials.js";
 import { checkParams } from "./define.js";
 import { failOn, warnOn } from "./fail.js";
 import { SOURCE_FORMAT_PREFIX } from "./ids.js";
@@ -60,6 +60,8 @@ interface Prepared {
     readonly params: Record<string, unknown>;
     /** The sink wrapper's counters, set once the sink is known. */
     readonly counts: { nodes: Set<number>; edgesAtStart: number; sink: GraphSink | null };
+    /** The query parameter the call's credential is sent in, which a cursor never keeps; null for none. */
+    readonly secretQuery: string | null;
 }
 
 /**
@@ -131,7 +133,8 @@ function prepare(
             edges: counts.sink === null ? 0 : counts.sink.edgeCount - counts.edgesAtStart,
         }),
     });
-    return { report, created, params, counts };
+    const secretQuery = options.credential === undefined ? null : credentialQuery(options.credential);
+    return { report, created, params, counts, secretQuery };
 }
 
 /**
@@ -721,6 +724,7 @@ export async function runMethod<T>(
  */
 export function withSource(report: ImportReport, prepared: Prepared, next: SourceCursor | null): ImportReport {
     const own = prepared.report.finish();
+    const cursor = prepared.secretQuery === null || next === null ? next : withoutParam(next, prepared.secretQuery);
     // issues the context recorded (retries, limits) that a source's own report does not hold
     const missing = own.issues.filter((i) => !report.issues.includes(i));
     return Object.freeze({
@@ -728,10 +732,38 @@ export function withSource(report: ImportReport, prepared: Prepared, next: Sourc
         issues: missing.length === 0 ? report.issues : Object.freeze([...report.issues, ...missing]),
         warningCount: report.warningCount + missing.filter((i) => i.severity === "warning").length,
         errorCount: report.errorCount + missing.filter((i) => i.severity === "error").length,
-        source: prepared.created.info(next),
+        source: prepared.created.info(cursor),
     });
 }
 
+/**
+ * A cursor without a query parameter in any URL it holds: a next-page link a service returns
+ * repeats the API key the request carried, and a cursor is saved where a credential never is.
+ * The credential is sent again with every request, so the next page does not need it there.
+ * @param value - the cursor, or a value inside it
+ * @param name - the parameter
+ * @returns the value without it
+ */
+function withoutParam<T>(value: T, name: string): T {
+    if (typeof value === "string" && /^https?:\/\//i.test(value)) {
+        const url = new URL(value);
+        if (!url.searchParams.has(name)) {
+            return value;
+        }
+        url.searchParams.delete(name);
+        return url.href as T;
+    }
+    if (Array.isArray(value)) {
+        return Object.freeze(value.map((each: unknown) => withoutParam(each, name))) as T;
+    }
+    if (typeof value === "object" && value !== null) {
+        return Object.freeze(
+            Object.fromEntries(Object.entries(value).map(([key, each]) => [key, withoutParam(each, name)])),
+        ) as T;
+    }
+    return value;
+}
+
 /**
  * What a failed call throws: the signal's reason when it aborted, an ImportError with the source
  * info attached, or the error itself.

package/src/sources/sigv4.ts

@@ -75,12 +75,14 @@ async function sha256(data: Uint8Array | ArrayBuffer): Promise<string> {
 }
 
 /**
- * SHA-256 of a text's UTF-8 bytes, as lowercase hex (the Cypher source's content hash).
- * @param text - the text
+ * SHA-256 as 64 lowercase hexadecimal digits: of bytes exactly as given, or of a text's UTF-8 bytes
+ * (the Cypher source's content hash, a project file's record of a file it loaded). Web Crypto where
+ * there is one, else plain JavaScript (a page that is not a secure context). Experimental.
+ * @param data - the bytes or the text
  * @returns the digest
  */
-export function sha256Hex(text: string): Promise<string> {
-    return sha256(utf8(text));
+export function sha256Hex(data: string | Uint8Array): Promise<string> {
+    return sha256(typeof data === "string" ? utf8(data) : data);
 }
 
 /**

package/src/sources/sparql/descriptor.ts

@@ -0,0 +1,67 @@
+/**
+ * The SPARQL source's descriptor: catalog data, available without loading the source's code.
+ */
+
+import { type SourceDescriptor } from "../types.js";
+
+/** A small Wikidata query: physics Nobel laureates and their doctoral advisors. */
+const WIKIDATA_ADVISORS = `PREFIX wd: <http://www.wikidata.org/entity/>
+PREFIX wdt: <http://www.wikidata.org/prop/direct/>
+PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+CONSTRUCT { ?person wdt:P184 ?advisor . ?person rdfs:label ?name . ?advisor rdfs:label ?advisorName . }
+WHERE {
+  ?person wdt:P166 wd:Q38104 ; wdt:P184 ?advisor ; rdfs:label ?name .
+  ?advisor rdfs:label ?advisorName .
+  FILTER(lang(?name) = "en" && lang(?advisorName) = "en")
+}`;
+
+/**
+ * The descriptor of the `sparql` source. Experimental.
+ * @category Network sources
+ */
+export const SPARQL_DESCRIPTOR: SourceDescriptor = Object.freeze({
+    plainName: "SPARQL endpoint",
+    kind: "sparql",
+    version: 1,
+    auth: ["basic", "bearer"],
+    authRequired: "optional",
+    features: ["expand", "probe", "validate", "page"],
+    params: [
+        { name: "query", plainName: "Query", type: "query", language: "sparql" },
+        {
+            name: "mode",
+            plainName: "Mode",
+            type: "enum",
+            values: [
+                { value: "query", label: "Query" },
+                { value: "all", label: "Everything" },
+                { value: "neighborhood", label: "Seed nodes" },
+            ],
+        },
+        { name: "ids", plainName: "Seed IRIs", type: "node-id" },
+        { name: "language", plainName: "Language", type: "string", advanced: true },
+        { name: "predicates", plainName: "Follow predicates", type: "string", advanced: true },
+        {
+            name: "pageSize",
+            plainName: "Page size",
+            type: "integer",
+            default: 1000,
+            min: 1,
+            max: 10000,
+            advanced: true,
+        },
+    ],
+    samples: [
+        {
+            id: "wikidata-physics-advisors",
+            plainName: "Wikidata: physics Nobel laureates and their advisors",
+            endpoint: "https://query.wikidata.org/sparql",
+            params: {
+                query: WIKIDATA_ADVISORS,
+                pageSize: 100,
+                language: "en",
+                predicates: ["http://www.wikidata.org/prop/direct/"], // NOSONAR(S5332): an RDF namespace IRI, never fetched; Wikidata's IRIs are http
+            },
+        },
+    ],
+});