@graphty/graph-io 0.3.16 → 0.3.18

package/dist/src/formats/json/importer.js

@@ -32,14 +32,15 @@
  */
 import { GraphFormatError, INVALID_INDEX, } from "@graphty/graph-format";
 import { uniqueColumnName } from "../../common/attributes.js";
-import { DUPLICATE_EDGE_ID_CODE, DUPLICATE_NODE_CODE, EMPTY_INPUT_CODE, ENCODING_FALLBACK_CODE, HYPEREDGE_CODE, INVALID_ENCODING_CODE, INVALID_UTF8_CODE, MISSING_ENDPOINT_CODE, MISSING_ID_CODE, MULTIPLE_GRAPHS_CODE, OPTION_IGNORED_CODE, SYNTAX_CODE, UNKNOWN_ENCODING_CODE, UNKNOWN_PARENT_CODE, } from "../../common/codes.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, MISSING_ENDPOINT_CODE, MISSING_ID_CODE, MULTIPLE_GRAPHS_CODE, OPTION_IGNORED_CODE, SYNTAX_CODE, TOO_LARGE_CODE, UNKNOWN_ENCODING_CODE, UNKNOWN_PARENT_CODE, } from "../../common/codes.js";
 import { DirectionResolver } from "../../common/direction.js";
 import { ID_MERGED_CODE, IdCoercer } from "../../common/ids.js";
-import { readText, throwIfAborted } from "../../common/input.js";
-import { reportSinkOptions, reportUnusedOptions, resolveImportOptions, SINK_OPTION_CODE, } from "../../common/options.js";
+import { readText, textChunks, throwIfAborted } from "../../common/input.js";
+import { chooseGraph, reportSinkOptions, reportUnusedOptions, resolveImportOptions, SINK_OPTION_CODE, } from "../../common/options.js";
 import { ImportReportBuilder } from "../../common/report.js";
 import { weightFromValue } from "../../common/weights.js";
 import { CLASSES_COLUMN, CYTOSCAPE_ELEMENT_KEYS, CYTOSCAPE_STRUCTURAL_KEYS, DIALECT_DEFAULT_DIRECTED, hasKey, isJsonImportDialect, isJsonObject, JSON_IMPORT_DIALECTS, META_KEY, NODE_LINK_SOURCE_KEYS, NODE_LINK_TARGET_KEYS, PARENT_COLUMN, POSITION_COLUMN, sniffJsonDialect, SUFFIX, } from "./dialect.js";
+import { importObographs } from "./obographs.js";
 /**
  * The issue codes the JSON importer records (design section 8.6), by name: the codes shared with
  * the other importers (src/common/codes.ts) and the JSON-specific ones. A key is the code without
@@ -67,7 +68,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. */
@@ -80,8 +81,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. */
@@ -180,6 +191,14 @@ function resolveJsonOptions(options) {
     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)) {
@@ -193,6 +212,9 @@ function resolveJsonOptions(options) {
         targetKey: keyOption("targetKey", o.targetKey),
         indexLinks,
         graphIndex,
+        choice: { graphIndex: o.graphIndex, graphName: o.graphName },
+        oboIds,
+        typedefs,
         nodesPath,
         edgesPath,
     };
@@ -493,7 +515,7 @@ class AttributeWriter {
 /**
  * Everything one import call shares between the dialect readers.
  */
-class ImportContext {
+export class ImportContext {
     /**
      * Create the context.
      * @param sink - the sink
@@ -1906,32 +1928,123 @@ function importJgf(ctx, root) {
     ctx.setMeta(shape, { name: label, ...ctx.weightOriginPatch() });
 }
 /**
- * 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, root) {
+    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, root, what) {
     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`, { element: "graphs" });
+        report.warning("unsupported", JSON_ISSUE.MULTIPLE_GRAPHS, `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) {
+    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) {
+    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, dialect) {
+    if ((dialect === "jgf" || dialect === "obographs") && isJsonObject(root)) {
+        if (Array.isArray(root.graphs) && !isJsonObject(root.graph)) {
+            return root.graphs.map((graph, 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, report, options) {
+    if (typeof input === "string") {
+        return readText(input, report, options);
+    }
+    const parts = [];
+    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
@@ -2321,11 +2434,27 @@ export const jsonImporter = 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, options) {
+        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.
@@ -2338,11 +2467,9 @@ export const jsonImporter = 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 = [];
         for (let i = 0; i < Math.max(graphs, 1); i++) {
             const report = i === 0 ? first : new ImportReportBuilder("json", resolved.errorLimit);
@@ -2364,7 +2491,8 @@ export const jsonImporter = Object.freeze({
  */
 function readGraph(root, dialect, sink, report, resolved, json, options) {
     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);
@@ -2394,6 +2522,9 @@ function readGraph(root, dialect, sink, report, resolved, json, options) {
         case "tree":
             importTree(ctx, doc);
             break;
+        case "obographs":
+            importObographs(ctx, doc);
+            break;
         default: {
             const name = dialect;
             throw new GraphFormatError("E_UNSUPPORTED", `unknown dialect ${name}`, {