@graphty/graph-io 0.3.16 → 0.3.18

package/src/formats/json/importer.ts

@@ -43,10 +43,14 @@ import {
 
 import { uniqueColumnName } from "../../common/attributes.js";
 import {
+    AMBIGUOUS_GRAPH_NAME_CODE,
+    BAD_VALUE_CODE,
+    DANGLING_REFERENCE_CODE,
     DUPLICATE_EDGE_ID_CODE,
     DUPLICATE_NODE_CODE,
     EMPTY_INPUT_CODE,
     ENCODING_FALLBACK_CODE,
+    GRAPH_NOT_FOUND_CODE,
     HYPEREDGE_CODE,
     INVALID_ENCODING_CODE,
     INVALID_UTF8_CODE,
@@ -55,13 +59,15 @@ import {
     MULTIPLE_GRAPHS_CODE,
     OPTION_IGNORED_CODE,
     SYNTAX_CODE,
+    TOO_LARGE_CODE,
     UNKNOWN_ENCODING_CODE,
     UNKNOWN_PARENT_CODE,
 } from "../../common/codes.js";
 import { DirectionResolver, type EdgeKind } from "../../common/direction.js";
 import { ID_MERGED_CODE, IdCoercer } from "../../common/ids.js";
-import { readText, throwIfAborted } from "../../common/input.js";
+import { readText, textChunks, throwIfAborted } from "../../common/input.js";
 import {
+    chooseGraph,
     type ImportFormatDefaults,
     reportSinkOptions,
     reportUnusedOptions,
@@ -71,7 +77,14 @@ import {
 } from "../../common/options.js";
 import { ImportReportBuilder } from "../../common/report.js";
 import { weightFromValue } from "../../common/weights.js";
-import { type CommonImportOptions, type GraphImporter, type ImportInput, type ImportReport } from "../../types.js";
+import {
+    type CommonImportOptions,
+    type GraphChoiceOptions,
+    type GraphImporter,
+    type GraphListing,
+    type ImportInput,
+    type ImportReport,
+} from "../../types.js";
 import {
     CLASSES_COLUMN,
     CYTOSCAPE_ELEMENT_KEYS,
@@ -91,9 +104,14 @@ import {
     sniffJsonDialect,
     SUFFIX,
 } from "./dialect.js";
+import { importObographs } from "./obographs.js";
 
-/** The format-specific options of the JSON importer. */
-export interface JsonImportOptions {
+/**
+ * The format-specific options of the JSON importer. `graphIndex` / `graphName` choose one graph of
+ * a JGF or OBO Graphs `graphs` array (the first by default); a graph's name is its `id`, else its
+ * label.
+ */
+export interface JsonImportOptions extends GraphChoiceOptions {
     /** The dialect to read; "auto" (default) sniffs the parsed document. */
     dialect?: JsonImportDialect | "auto" | undefined;
     /**
@@ -112,8 +130,18 @@ export interface JsonImportOptions {
      * every endpoint is an integer below the node count and no node id is a number.
      */
     indexLinks?: boolean | "auto" | undefined;
-    /** jgf: which graph of a `graphs` array to read; 0 by default. */
-    graphIndex?: number | undefined;
+    /**
+     * obographs: "curie" (default) reads `http://purl.obolibrary.org/obo/GO_0008150` as `GO:0008150`
+     * and `.../obo/go#regulates` as `regulates`, the identifiers the `.obo` file of the same ontology
+     * writes; "iri" keeps every IRI as written.
+     */
+    oboIds?: "curie" | "iri" | undefined;
+    /**
+     * obographs: "metadata" (default) keeps PROPERTY nodes and their subPropertyOf / inverseOf edges
+     * in `meta.extra.obographs`, as the OBO importer keeps `[Typedef]` frames; "nodes" makes them
+     * nodes and edges.
+     */
+    typedefs?: "metadata" | "nodes" | undefined;
     /**
      * node-link / d3 / vis / graphology: where the node array is, as a dotted path of object keys
      * from the document root (`"data.nodes"`); the object holding it is read as the graph record
@@ -157,7 +185,7 @@ export const JSON_ISSUE = Object.freeze({
     /** An index endpoint is not an integer below the node count, or names a skipped node. */
     BAD_INDEX: "E_BAD_INDEX",
     /** A declared field has the wrong JSON type (JGF label / relation / metadata, Cytoscape position / classes). */
-    BAD_VALUE: "E_BAD_VALUE",
+    BAD_VALUE: BAD_VALUE_CODE,
     /** A graph-level flag (`directed`, `multigraph`, graphology `options`) has the wrong type; the default is used. */
     BAD_FLAG: "W_BAD_FLAG",
     /** A Cytoscape `data.parent` names an unknown node. */
@@ -170,8 +198,18 @@ export const JSON_ISSUE = Object.freeze({
     ID_MERGED: ID_MERGED_CODE,
     /** Edge ids of mixed JSON types were stored as text. */
     EDGE_ID_STRINGIFIED: "W_EDGE_ID_STRINGIFIED",
-    /** A JGF `graphs` array holds more than one graph; only `graphIndex` is read. */
+    /** A JGF or OBO Graphs `graphs` array holds more than one graph; only the chosen one is read. */
     MULTIPLE_GRAPHS: MULTIPLE_GRAPHS_CODE,
+    /** `graphIndex` is beyond the `graphs` array, or `graphName` names none of its graphs (fatal). */
+    GRAPH_NOT_FOUND: GRAPH_NOT_FOUND_CODE,
+    /** `graphName` names more than one graph of the `graphs` array (fatal). */
+    AMBIGUOUS_GRAPH_NAME: AMBIGUOUS_GRAPH_NAME_CODE,
+    /** obographs: an edge uses the outdated `subj` key of the OBO Graphs README; it is read as `sub`. */
+    OBOGRAPHS_SUBJ: "W_JSON_OBOGRAPHS_SUBJ",
+    /** obographs: an edge endpoint missing from `nodes` (a placeholder node is made, or the edge dropped under addMissingNodes false). */
+    DANGLING_REFERENCE: DANGLING_REFERENCE_CODE,
+    /** The document is longer than one JavaScript string can hold (fatal; category unsupported). */
+    TOO_LARGE: TOO_LARGE_CODE,
     /** JGF hyperedges under the "error" policy. */
     HYPEREDGE: HYPEREDGE_CODE,
     /** JGF hyperedges skipped under the default "skip" policy. */
@@ -257,7 +295,7 @@ const GRAPHOLOGY_EDGE_KEYS: ReadonlySet<string> = new Set(["key", "source", "tar
 const VIS_SOURCE_KEYS: readonly string[] = Object.freeze(["from"]);
 const VIS_TARGET_KEYS: readonly string[] = Object.freeze(["to"]);
 
-type JsonRecord = Record<string, unknown>;
+export type JsonRecord = Record<string, unknown>;
 
 /** An edge id column declared from a scan of the file's edge ids. */
 interface EdgeIdColumn {
@@ -285,6 +323,12 @@ interface ResolvedJsonOptions {
     readonly targetKey: string | null;
     readonly indexLinks: boolean | "auto";
     readonly graphIndex: number;
+    /** The caller's graphIndex / graphName, as given, for chooseGraph(). */
+    readonly choice: GraphChoiceOptions;
+    /** obographs: CURIE or IRI ids. */
+    readonly oboIds: "curie" | "iri";
+    /** obographs: PROPERTY nodes as metadata or as nodes. */
+    readonly typedefs: "metadata" | "nodes";
     /** The dotted path segments of the node array, or null for the root's own nodes key. */
     readonly nodesPath: readonly string[] | null;
     /** The dotted path segments of the edge array, or null for the edges / links key beside the nodes. */
@@ -312,6 +356,14 @@ function resolveJsonOptions(options: (JsonImportOptions & CommonImportOptions) |
     if (!Number.isInteger(graphIndex) || graphIndex < 0) {
         throw unsupportedOption("graphIndex", graphIndex, ["a non-negative integer"]);
     }
+    const oboIds = o.oboIds ?? "curie";
+    if (oboIds !== "curie" && oboIds !== "iri") {
+        throw unsupportedOption("oboIds", oboIds, ["curie", "iri"]);
+    }
+    const typedefs = o.typedefs ?? "metadata";
+    if (typedefs !== "metadata" && typedefs !== "nodes") {
+        throw unsupportedOption("typedefs", typedefs, ["metadata", "nodes"]);
+    }
     const nodesPath = pathOption("nodesPath", o.nodesPath);
     const edgesPath = pathOption("edgesPath", o.edgesPath);
     if ((nodesPath !== null || edgesPath !== null) && dialect !== "auto" && !PATH_DIALECTS.has(dialect)) {
@@ -325,6 +377,9 @@ function resolveJsonOptions(options: (JsonImportOptions & CommonImportOptions) |
         targetKey: keyOption("targetKey", o.targetKey),
         indexLinks,
         graphIndex,
+        choice: { graphIndex: o.graphIndex, graphName: o.graphName },
+        oboIds,
+        typedefs,
         nodesPath,
         edgesPath,
     };
@@ -665,7 +720,7 @@ class AttributeWriter {
 /**
  * Everything one import call shares between the dialect readers.
  */
-class ImportContext {
+export class ImportContext {
     readonly sink: GraphSink;
 
     readonly report: ImportReportBuilder;
@@ -2338,38 +2393,140 @@ function importJgf(ctx: ImportContext, root: JsonRecord): void {
 }
 
 /**
- * The graph object of a JGF document: `graph`, or `graphs[graphIndex]`.
+ * The graph object of a JGF document: `graph`, or the graph of `graphs` that graphIndex /
+ * graphName choose (chooseGraph()).
  * @param ctx - the context
  * @param root - the document
  * @returns the graph object; the import fails when there is none
  */
 function jgfGraphOf(ctx: ImportContext, root: JsonRecord): JsonRecord {
+    return isJsonObject(root.graph) ? root.graph : chosenGraph(ctx, root, "JGF");
+}
+
+/**
+ * The graph of a `graphs` array (JGF, OBO Graphs) that graphIndex / graphName choose, with
+ * W_MULTIPLE_GRAPHS when the others are skipped; importAll() reads graphs[graphIndex].
+ * @param ctx - the context
+ * @param root - the document
+ * @param what - the dialect's name, for the messages
+ * @returns the graph object; the import fails when there is none
+ */
+export function chosenGraph(ctx: ImportContext, root: JsonRecord, what: string): JsonRecord {
     const { report } = ctx;
-    if (isJsonObject(root.graph)) {
-        return root.graph;
-    }
     const graphs = arraySection(root.graphs, "graphs", report) ?? [];
     if (graphs.length === 0) {
-        report.fail(JSON_ISSUE.SHAPE, "a JGF document needs a graph object or a non-empty graphs array");
+        report.fail(JSON_ISSUE.SHAPE, `a ${what} document needs a graph object or a non-empty graphs array`);
     }
+    const index =
+        ctx.json.all === true ? ctx.json.graphIndex : chooseGraph(graphs.map(graphNameOf), ctx.json.choice, report);
     if (graphs.length > 1 && ctx.json.all !== true) {
         report.warning(
             "unsupported",
             JSON_ISSUE.MULTIPLE_GRAPHS,
-            `the document holds ${graphs.length} graphs; only graphs[${ctx.json.graphIndex}] is read (${graphs.length - 1} skipped), importAll() reads every one`,
+            `the document holds ${graphs.length} graphs; only graphs[${index}] is read (${graphs.length - 1} skipped), importAll() reads every one`,
             { element: "graphs" },
         );
     }
-    if (ctx.json.graphIndex >= graphs.length) {
-        report.fail(JSON_ISSUE.SHAPE, `graphIndex ${ctx.json.graphIndex} is beyond the ${graphs.length} graph(s)`);
-    }
-    const graph = graphs[ctx.json.graphIndex];
+    const graph = graphs[index];
     if (!isJsonObject(graph)) {
-        return report.fail(JSON_ISSUE.SHAPE, `graphs[${ctx.json.graphIndex}] is not an object`);
+        return report.fail(JSON_ISSUE.SHAPE, `graphs[${index}] is not an object`);
     }
     return graph;
 }
 
+/**
+ * The name a graph of a `graphs` array is listed and chosen by: its `id`, else its `label` (JGF)
+ * or `lbl` (OBO Graphs).
+ * @param graph - the graph
+ * @returns the name, or null
+ */
+function graphNameOf(graph: unknown): string | null {
+    if (!isJsonObject(graph)) {
+        return null;
+    }
+    for (const key of ["id", "label", "lbl"]) {
+        if (typeof graph[key] === "string") {
+            return graph[key];
+        }
+    }
+    return null;
+}
+
+/**
+ * How many elements a nodes or edges section holds: an array's length, an object's key count, 0
+ * when absent, null for anything else.
+ * @param section - the section
+ * @returns the count, or null
+ */
+function countOf(section: unknown): number | null {
+    if (section === undefined || section === null) {
+        return 0;
+    }
+    if (Array.isArray(section)) {
+        return section.length;
+    }
+    return isJsonObject(section) ? Object.keys(section).length : null;
+}
+
+/**
+ * The graphs of a parsed document, for listGraphs(): each entry of a JGF or OBO Graphs `graphs`
+ * array with its name and counts; any other document holds one graph.
+ * @param root - the parsed document
+ * @param dialect - its dialect
+ * @returns the listings
+ */
+function listingsOf(root: unknown, dialect: JsonImportDialect): GraphListing[] {
+    if ((dialect === "jgf" || dialect === "obographs") && isJsonObject(root)) {
+        if (Array.isArray(root.graphs) && !isJsonObject(root.graph)) {
+            return root.graphs.map((graph: unknown, index) => ({
+                index,
+                name: graphNameOf(graph),
+                nodes: isJsonObject(graph) ? countOf(graph.nodes) : null,
+                edges: isJsonObject(graph) ? countOf(graph.edges) : null,
+            }));
+        }
+        if (isJsonObject(root.graph)) {
+            const { graph } = root;
+            return [{ index: 0, name: graphNameOf(graph), nodes: countOf(graph.nodes), edges: countOf(graph.edges) }];
+        }
+    }
+    return [{ index: 0, name: null, nodes: null, edges: null }];
+}
+
+/** The longest string V8 makes (2^29 - 24 UTF-16 code units); a longer document cannot be one JSON.parse input. */
+const MAX_TEXT_LENGTH = 2 ** 29 - 24;
+
+/**
+ * Read the whole input as one string, failing with E_TOO_LARGE (category unsupported) before the
+ * join when it is longer than one JavaScript string can hold (OBO Graphs files such as
+ * ncbitaxon.json are; design 7.1 defers streaming the JSON reader).
+ * @param input - the input
+ * @param report - the report
+ * @param options - cancellation, progress and encoding
+ * @returns the text
+ */
+async function readJsonText(
+    input: ImportInput,
+    report: ImportReportBuilder,
+    options: ResolvedImportOptions,
+): Promise<string> {
+    if (typeof input === "string") {
+        return readText(input, report, options);
+    }
+    const parts: string[] = [];
+    let length = 0;
+    for await (const chunk of textChunks(input, report, options)) {
+        length += chunk.length;
+        if (length > MAX_TEXT_LENGTH) {
+            const message = `the document is longer than ${MAX_TEXT_LENGTH} characters, the most one JavaScript string holds`;
+            report.error("unsupported", JSON_ISSUE.TOO_LARGE, message);
+            throw report.abort(message, { code: JSON_ISSUE.TOO_LARGE });
+        }
+        parts.push(chunk);
+    }
+    return parts.length === 1 ? parts[0] : parts.join("");
+}
+
 /**
  * Push a JGF node: `label` into the declared column, `metadata` as attributes.
  * @param ctx - the context
@@ -2840,12 +2997,32 @@ export const jsonImporter: GraphImporter<JsonImportOptions> = Object.freeze({
         const resolved = resolveImportOptions(options, FORMAT_DEFAULTS);
         const json = resolveJsonOptions(options);
         const report = new ImportReportBuilder("json", resolved.errorLimit);
-        const text = await readText(input, report, resolved);
+        const text = await readJsonText(input, report, resolved);
         const { root, dialect } = documentOf(parseDocument(text, report), json, report);
         readGraph(root, dialect, sink, report, resolved, json, options);
         return report.finish();
     },
 
+    /**
+     * List the graphs of a JSON document without importing them: each entry of a JGF or OBO
+     * Graphs `graphs` array with its name (`id`, else its label) and node and edge counts; any
+     * other document holds one graph.
+     * @param input - the text, bytes or stream
+     * @param options - format-specific and common options
+     * @returns one listing per graph
+     */
+    async listGraphs(
+        input: ImportInput,
+        options?: JsonImportOptions & CommonImportOptions,
+    ): Promise<readonly GraphListing[]> {
+        const resolved = resolveImportOptions(options, FORMAT_DEFAULTS);
+        const json = resolveJsonOptions(options);
+        const report = new ImportReportBuilder("json", resolved.errorLimit);
+        const text = await readJsonText(input, report, resolved);
+        const { root, dialect } = documentOf(parseDocument(text, report), json, report);
+        return listingsOf(root, dialect);
+    },
+
     /**
      * Read every graph of a JSON document: each entry of a JGF `graphs` array into its own sink;
      * any other document holds one graph.
@@ -2862,12 +3039,9 @@ export const jsonImporter: GraphImporter<JsonImportOptions> = Object.freeze({
         const resolved = resolveImportOptions(options, FORMAT_DEFAULTS);
         const json = resolveJsonOptions(options);
         const first = new ImportReportBuilder("json", resolved.errorLimit);
-        const text = await readText(input, first, resolved);
+        const text = await readJsonText(input, first, resolved);
         const { root, dialect } = documentOf(parseDocument(text, first), json, first);
-        const graphs =
-            dialect === "jgf" && isJsonObject(root) && !isJsonObject(root.graph) && Array.isArray(root.graphs)
-                ? root.graphs.length
-                : 1;
+        const graphs = listingsOf(root, dialect).length;
         const reports: ImportReport[] = [];
         for (let i = 0; i < Math.max(graphs, 1); i++) {
             const report = i === 0 ? first : new ImportReportBuilder("json", resolved.errorLimit);
@@ -2898,7 +3072,8 @@ function readGraph(
     options: (JsonImportOptions & CommonImportOptions) | undefined,
 ): void {
     const ctx = new ImportContext(sink, report, resolved, json, options?.defaultDirected !== undefined);
-    reportSinkOptions(sink, options, report);
+    // the obographs reader refuses missing endpoints itself, so addMissingNodes false holds on any sink
+    reportSinkOptions(sink, options, report, dialect === "obographs");
     reportUnusedOptions(options, report, USED_OPTIONS);
     if (dialect === "cytoscape") {
         importCytoscape(ctx, root);
@@ -2928,6 +3103,9 @@ function readGraph(
         case "tree":
             importTree(ctx, doc);
             break;
+        case "obographs":
+            importObographs(ctx, doc);
+            break;
         default: {
             const name: string = dialect;
             throw new GraphFormatError("E_UNSUPPORTED", `unknown dialect ${name}`, {