@graphty/graph-io 0.3.17 → 0.3.18

package/dist/chunks/{importer-B6rKRxzv.js → importer-Du5crN9l.js}

@@ -1,5 +1,7 @@
 import { GraphFormatError, INVALID_INDEX } from "@graphty/graph-format";
-import { ar as capabilities, M as LOSS, aO as joinText, aB as encodeChunks, as as checkCapabilities, aV as resolveExportOptions, a_ as countMixedEdges, aC as explicitWeights, aQ as pairFolding, aE as formatF32, aF as formatF64, aj as UNKNOWN_ENCODING_CODE, u as ENCODING_FALLBACK_CODE, F as INVALID_ENCODING_CODE, J as INVALID_UTF8_CODE, Y as OPTION_IGNORED_CODE, a6 as SINK_OPTION_CODE, H as HYPEREDGE_CODE, R as MULTIPLE_GRAPHS_CODE, w as ID_MERGED_CODE, o as DUPLICATE_EDGE_ID_CODE, q as DUPLICATE_NODE_CODE, ak as UNKNOWN_PARENT_CODE, e as BAD_VALUE_CODE, O as MISSING_ENDPOINT_CODE, P as MISSING_ID_CODE, ac as SYNTAX_CODE, s as EMPTY_INPUT_CODE, aW as resolveImportOptions, I as ImportReportBuilder, aS as readText, aT as reportSinkOptions, aU as reportUnusedOptions, a as throwIfAborted, K as IdCoercer, r as DirectionResolver, a$ as weightFromValue, b0 as uniqueColumnName } from "./writer-DHHfHn11.js";
+import { aC as resolveExportOptions, ay as pairFolding, as as declareResolved, ag as UNKNOWN_ENCODING_CODE, s as ENCODING_FALLBACK_CODE, z as INVALID_ENCODING_CODE, F as INVALID_UTF8_CODE, V as OPTION_IGNORED_CODE, a3 as SINK_OPTION_CODE, H as HYPEREDGE_CODE, ad as TOO_LARGE_CODE, D as DANGLING_REFERENCE_CODE, A as AMBIGUOUS_GRAPH_NAME_CODE, G as GRAPH_NOT_FOUND_CODE, P as MULTIPLE_GRAPHS_CODE, v as ID_MERGED_CODE, n as DUPLICATE_EDGE_ID_CODE, p as DUPLICATE_NODE_CODE, ah as UNKNOWN_PARENT_CODE, e as BAD_VALUE_CODE, M as MISSING_ENDPOINT_CODE, N as MISSING_ID_CODE, a9 as SYNTAX_CODE, r as EMPTY_INPUT_CODE, aD as resolveImportOptions, I as ImportReportBuilder, az as readText, t as textChunks, aA as reportSinkOptions, aB as reportUnusedOptions, a as throwIfAborted, J as IdCoercer, q as DirectionResolver, aE as uniqueColumnName, ao as chooseGraph } from "./report-BOk0p5y8.js";
+import { c as capabilities, L as LOSS, n as joinText, e as encodeChunks, a as checkCapabilities, r as countMixedEdges, f as explicitWeights, h as formatF32, i as formatF64, w as weightFromValue } from "./writer-GAdltGmC.js";
+import { a as OBOGRAPHS_PREDICATE_TAGS, c as compactOboIri, o as oboColumnDecl, P as PLACEHOLDER_COLUMN, s as synonymScopeOf, O as OBO_NODE_COLUMNS } from "./ontology-BnrJ4I98.js";
 const JSON_DIALECTS = Object.freeze([
   "node-link",
   "d3",
@@ -11,7 +13,8 @@ const JSON_DIALECTS = Object.freeze([
 const JSON_IMPORT_DIALECTS = Object.freeze([
   ...JSON_DIALECTS,
   "adjacency",
-  "tree"
+  "tree",
+  "obographs"
 ]);
 const META_KEY = "json";
 function isJsonObject(value) {
@@ -41,7 +44,7 @@ function sniffJsonDialect(root) {
     return "jgf";
   }
   if (Array.isArray(root.graphs)) {
-    return "jgf";
+    return isOboGraph(firstJsonObject(root.graphs)) ? "obographs" : "jgf";
   }
   if (!hasKey(root, "edges") && !hasKey(root, "links")) {
     if (hasKey(root, "nodes") && hasKey(root, "adjacency")) {
@@ -70,6 +73,15 @@ function sniffJsonDialect(root) {
   const bare = !hasKey(root, "directed") && !hasKey(root, "multigraph") && !hasKey(root, "graph");
   return bare && hasKey(root, "links") ? "d3" : "node-link";
 }
+const OBOGRAPHS_NODE_TYPES = /* @__PURE__ */ new Set(["CLASS", "INDIVIDUAL", "PROPERTY"]);
+function isOboGraph(graph) {
+  if (graph === null) {
+    return false;
+  }
+  const isEdge = (e) => isJsonObject(e) && (hasKey(e, "obj") && (hasKey(e, "sub") || hasKey(e, "subj")) || hasKey(e, "pred"));
+  const isNode = (n) => isJsonObject(n) && (hasKey(n, "lbl") || hasKey(n, "meta") || OBOGRAPHS_NODE_TYPES.has(n.type));
+  return Array.isArray(graph.edges) && graph.edges.some(isEdge) || Array.isArray(graph.nodes) && graph.nodes.some(isNode);
+}
 function firstJsonObject(value) {
   if (!Array.isArray(value)) {
     return null;
@@ -107,7 +119,9 @@ const DIALECT_DEFAULT_DIRECTED = Object.freeze({
   vis: false,
   // networkx adjacency_data declares `directed`; tree_graph always builds a DiGraph
   adjacency: false,
-  tree: true
+  tree: true,
+  // OBO Graphs edges point from the subject (child) to the object (parent)
+  obographs: true
 });
 const JSON_DTYPES = Object.freeze(["f64", "i32", "bool", "string"]);
 const COMMON = {
@@ -1356,6 +1370,383 @@ const jsonExporter = Object.freeze({
 function jsonCapabilities(dialect) {
   return dialectCapabilities(dialect);
 }
+const NODE_KEYS = /* @__PURE__ */ new Set(["id", "lbl", "type", "propertyType", "meta"]);
+const META_KEYS = /* @__PURE__ */ new Set([
+  "definition",
+  "comments",
+  "subsets",
+  "xrefs",
+  "synonyms",
+  "basicPropertyValues",
+  "deprecated"
+]);
+const FRAME_TYPES = Object.freeze({
+  CLASS: "Term",
+  INDIVIDUAL: "Instance",
+  PROPERTY: "Typedef"
+});
+const BUILTIN_PREDICATES = Object.freeze({
+  is_a: "is_a",
+  subPropertyOf: "is_a",
+  type: "instance_of",
+  inverseOf: "inverse_of"
+});
+const PROPERTY_PREDICATES = /* @__PURE__ */ new Set(["subPropertyOf", "inverseOf"]);
+class ColumnWriter {
+  /**
+   * Create a writer.
+   * @param ctx - the import context
+   */
+  constructor(ctx) {
+    this.handles = /* @__PURE__ */ new Map();
+    this.ctx = ctx;
+  }
+  /**
+   * Write a node cell of the vocabulary.
+   * @param name - the column
+   * @param row - the node index
+   * @param value - the value
+   */
+  node(name, row, value) {
+    this.ctx.sink.setNodeValue(this.handle("node", name), row, value);
+  }
+  /**
+   * Write an edge cell of the vocabulary.
+   * @param name - the column
+   * @param row - the edge index
+   * @param value - the value
+   */
+  edge(name, row, value) {
+    this.ctx.sink.setEdgeValue(this.handle("edge", name), row, value);
+  }
+  /**
+   * The handle of a column, declared on first use.
+   * @param domain - node or edge
+   * @param name - the column
+   * @returns the handle
+   */
+  handle(domain, name) {
+    const key = `${domain}:${name}`;
+    const cached = this.handles.get(key);
+    if (cached !== void 0) {
+      return cached;
+    }
+    const { handle } = declareResolved(this.ctx.sink, domain, oboColumnDecl(domain, name), this.ctx.report);
+    this.handles.set(key, handle);
+    return handle;
+  }
+}
+function vocabularyOf(nodes, oboIds) {
+  const shorthands = /* @__PURE__ */ new Map();
+  const propertyIds = /* @__PURE__ */ new Set();
+  for (const node of nodes) {
+    if (!isJsonObject(node) || typeof node.id !== "string" || node.type !== "PROPERTY") {
+      continue;
+    }
+    propertyIds.add(node.id);
+    const shorthand = basicValues(node.meta).find((pv) => OBOGRAPHS_PREDICATE_TAGS.get(pv.pred) === "shorthand");
+    if (shorthand !== void 0) {
+      shorthands.set(node.id, shorthand.val);
+    }
+  }
+  const compact = (iri) => oboIds === "curie" ? compactOboIri(iri) : iri;
+  return {
+    id: (iri) => oboIds === "curie" ? shorthands.get(iri) ?? compactOboIri(iri) : iri,
+    relation: (pred) => BUILTIN_PREDICATES[pred] ?? shorthands.get(pred) ?? compact(pred),
+    isProperty: (iri) => propertyIds.has(iri),
+    properties: {}
+  };
+}
+function basicValues(meta) {
+  if (!isJsonObject(meta) || !Array.isArray(meta.basicPropertyValues)) {
+    return [];
+  }
+  return meta.basicPropertyValues.filter(
+    (pv) => isJsonObject(pv) && typeof pv.pred === "string" && typeof pv.val === "string"
+  );
+}
+function strings(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.flatMap((item) => {
+    if (typeof item === "string") {
+      return [item];
+    }
+    return isJsonObject(item) && typeof item.val === "string" ? [item.val] : [];
+  });
+}
+function importObographs(ctx, root) {
+  const graph = chosenGraph(ctx, root, "OBO Graphs");
+  const nodes = sectionOf(ctx, graph, "nodes");
+  const edges = sectionOf(ctx, graph, "edges");
+  const vocabulary = vocabularyOf(nodes, ctx.json.oboIds);
+  const columns = new ColumnWriter(ctx);
+  ctx.reportNodeIdFrom("obographs", "the node ids");
+  ctx.setHeader(true);
+  ctx.sink.reserve(nodes.length, edges.length);
+  for (let i = 0; i < nodes.length; i++) {
+    readNode(ctx, columns, vocabulary, nodes[i], `nodes[${i}]`);
+  }
+  const propertyEdges = readEdges(ctx, columns, vocabulary, edges);
+  const graphMeta = {};
+  for (const key of Object.keys(graph)) {
+    if (key !== "nodes" && key !== "edges") {
+      graphMeta[key] = graph[key];
+    }
+  }
+  const document = {};
+  for (const key of Object.keys(root)) {
+    if (key !== "graphs") {
+      document[key] = root[key];
+    }
+  }
+  const label = typeof graph.lbl === "string" ? graph.lbl : null;
+  const name = label ?? (typeof graph.id === "string" ? graph.id : null);
+  ctx.sink.setMeta({
+    sourceFormat: "json",
+    name,
+    extra: {
+      json: { dialect: "obographs" },
+      obographs: {
+        ids: ctx.json.oboIds,
+        graph: graphMeta,
+        document,
+        properties: vocabulary.properties,
+        propertyEdges
+      }
+    }
+  });
+}
+function sectionOf(ctx, graph, key) {
+  const value = graph[key];
+  if (value === void 0 || value === null) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    return ctx.report.fail(JSON_ISSUE.SHAPE, `an OBO Graphs graph's ${key} must be an array`, { element: key });
+  }
+  return value;
+}
+function readNode(ctx, columns, vocabulary, record, element) {
+  if (!isJsonObject(record)) {
+    ctx.badElement("node", element);
+    return;
+  }
+  if (typeof record.id !== "string") {
+    if (record.id === void 0) {
+      ctx.coerceId(void 0, element);
+    } else {
+      badValue(ctx, `${element}.id must be a string; the node is skipped`);
+    }
+    ctx.countSkipped("node");
+    return;
+  }
+  if (record.type === "PROPERTY" && ctx.json.typedefs === "metadata") {
+    const shorthand = vocabulary.id(record.id) === record.id ? void 0 : vocabulary.id(record.id);
+    const entry = {};
+    for (const [key, value] of Object.entries({
+      lbl: record.lbl,
+      propertyType: record.propertyType,
+      shorthand,
+      meta: record.meta
+    })) {
+      if (value !== void 0) {
+        entry[key] = value;
+      }
+    }
+    vocabulary.properties[record.id] = entry;
+    return;
+  }
+  const id = ctx.coerceId(vocabulary.id(record.id), element);
+  const row = id === null ? -1 : ctx.pushNode(id, element);
+  if (row < 0) {
+    return;
+  }
+  try {
+    writeNode(ctx, columns, vocabulary, record, row, element);
+  } catch (err) {
+    ctx.report.recordError(err, { element: record.id });
+  }
+}
+function writeNode(ctx, columns, vocabulary, record, row, element) {
+  const unrecognized = {};
+  const text = (key, column) => {
+    const value = record[key];
+    if (typeof value === "string") {
+      columns.node(column, row, column === "type" ? FRAME_TYPES[value] ?? value : value);
+    } else if (value !== void 0 && value !== null) {
+      badValue(ctx, `${element}.${key} must be a string`);
+    }
+  };
+  text("type", "type");
+  text("lbl", "name");
+  text("propertyType", "propertyType");
+  for (const key of Object.keys(record)) {
+    if (!NODE_KEYS.has(key)) {
+      unrecognized[key] = record[key];
+    }
+  }
+  const { meta } = record;
+  if (isJsonObject(meta)) {
+    writeMeta(columns, vocabulary, meta, row, unrecognized);
+  } else if (meta !== void 0 && meta !== null) {
+    badValue(ctx, `${element}.meta must be an object`);
+  }
+  if (Object.keys(unrecognized).length > 0) {
+    columns.node("obo.unrecognized", row, unrecognized);
+  }
+}
+function writeMeta(columns, vocabulary, meta, row, unrecognized) {
+  const { definition } = meta;
+  if (isJsonObject(definition) && typeof definition.val === "string") {
+    columns.node("def", row, definition.val);
+    columns.node("def.xrefs", row, strings(definition.xrefs));
+  }
+  const comments = strings(meta.comments);
+  if (comments.length > 0) {
+    columns.node("comment", row, comments.join("\n"));
+  }
+  const subsets = strings(meta.subsets).map((s) => vocabulary.id(s));
+  if (subsets.length > 0) {
+    columns.node("subset", row, subsets);
+  }
+  const xrefs = strings(meta.xrefs);
+  if (xrefs.length > 0) {
+    columns.node("xref", row, xrefs);
+  }
+  if (Array.isArray(meta.synonyms) && meta.synonyms.length > 0) {
+    columns.node(
+      "synonym",
+      row,
+      meta.synonyms.filter(isJsonObject).map((s) => ({
+        text: typeof s.val === "string" ? s.val : null,
+        scope: typeof s.pred === "string" ? synonymScopeOf(s.pred) : null,
+        type: typeof s.synonymType === "string" ? vocabulary.id(s.synonymType) : null,
+        xrefs: strings(s.xrefs)
+      }))
+    );
+  }
+  if (typeof meta.deprecated === "boolean") {
+    columns.node("is_obsolete", row, meta.deprecated);
+  }
+  writePropertyValues(columns, vocabulary, basicValues(meta), row);
+  for (const key of Object.keys(meta)) {
+    if (!META_KEYS.has(key)) {
+      unrecognized[`meta.${key}`] = meta[key];
+    }
+  }
+}
+function writePropertyValues(columns, vocabulary, values, row) {
+  const lists = /* @__PURE__ */ new Map();
+  const others = [];
+  for (const { pred, val } of values) {
+    const tag = OBOGRAPHS_PREDICATE_TAGS.get(pred);
+    if (tag === "shorthand") {
+      continue;
+    }
+    if (tag === void 0) {
+      others.push({ relation: vocabulary.id(pred), value: val, datatype: null });
+    } else if (OBO_NODE_COLUMNS[tag].dtype === "list") {
+      const list = lists.get(tag) ?? [];
+      list.push(tag === "alt_id" ? val : vocabulary.id(val));
+      lists.set(tag, list);
+    } else {
+      columns.node(tag, row, val);
+    }
+  }
+  for (const [tag, list] of lists) {
+    columns.node(tag, row, list);
+  }
+  if (others.length > 0) {
+    columns.node("property_value", row, others);
+  }
+}
+function badValue(ctx, message) {
+  ctx.report.error("validation-error", JSON_ISSUE.BAD_VALUE, message);
+}
+function readEdges(ctx, columns, vocabulary, edges) {
+  const { report, sink } = ctx;
+  const propertyEdges = [];
+  const dangling = [];
+  let dropped = 0;
+  const endpoint = (raw, element) => {
+    const id = ctx.coerceId(vocabulary.id(raw), element);
+    if (id === null || sink.indexOf(id) !== INVALID_INDEX) {
+      return id;
+    }
+    dangling.push(raw);
+    if (!ctx.options.addMissingNodes) {
+      return null;
+    }
+    const row = ctx.pushNode(id, element);
+    if (row >= 0) {
+      columns.node(PLACEHOLDER_COLUMN, row, true);
+    }
+    return id;
+  };
+  for (let i = 0; i < edges.length; i++) {
+    const element = `edges[${i}]`;
+    const record = edges[i];
+    if (!isJsonObject(record)) {
+      ctx.badElement("edge", element);
+      continue;
+    }
+    const subKey = hasKey(record, "sub") ? "sub" : "subj";
+    if (subKey === "subj" && hasKey(record, "subj")) {
+      report.warnOnce(
+        "coercion",
+        JSON_ISSUE.OBOGRAPHS_SUBJ,
+        `${element} uses the outdated key subj; read as sub`,
+        {
+          element
+        }
+      );
+    }
+    const sub = record[subKey];
+    const { obj, pred } = record;
+    if (typeof sub !== "string" || typeof obj !== "string") {
+      ctx.missingEndpoint(element, typeof sub === "string" ? "obj" : "sub");
+      continue;
+    }
+    const between = typeof pred === "string" && PROPERTY_PREDICATES.has(pred) || vocabulary.isProperty(sub) || vocabulary.isProperty(obj);
+    if (between && ctx.json.typedefs === "metadata") {
+      propertyEdges.push(record);
+      continue;
+    }
+    try {
+      const u = endpoint(sub, `${element}.sub`);
+      const v = endpoint(obj, `${element}.obj`);
+      if (u === null || v === null) {
+        dropped++;
+        ctx.countSkipped("edge");
+        continue;
+      }
+      const edge = ctx.pushEdge(u, v, "directed", void 0, element);
+      if (typeof pred === "string") {
+        columns.edge("relation", edge, vocabulary.relation(pred));
+      } else {
+        badValue(ctx, `${element} has no pred; its relation is unset`);
+      }
+      if (isJsonObject(record.meta)) {
+        columns.edge("meta", edge, record.meta);
+      }
+    } catch (err) {
+      ctx.skip(err, "edge", element);
+    }
+  }
+  if (dangling.length > 0) {
+    const shown = [...new Set(dangling)].slice(0, 5).join(", ");
+    const action = ctx.options.addMissingNodes ? "each became a placeholder node (graphty.placeholder)" : `${dropped} edge(s) to them were dropped (addMissingNodes false)`;
+    report.warning(
+      "validation-error",
+      JSON_ISSUE.DANGLING_REFERENCE,
+      `${new Set(dangling).size} edge endpoint(s) missing from nodes: ${shown}; ${action}`,
+      { element: dangling[0] }
+    );
+  }
+  return propertyEdges;
+}
 const JSON_ISSUE = Object.freeze({
   /** The text is empty or whitespace (fatal). */
   EMPTY_INPUT: EMPTY_INPUT_CODE,
@@ -1391,8 +1782,18 @@ 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. */
@@ -1475,6 +1876,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)) {
@@ -1488,6 +1897,9 @@ function resolveJsonOptions(options) {
     targetKey: keyOption("targetKey", o.targetKey),
     indexLinks,
     graphIndex,
+    choice: { graphIndex: o.graphIndex, graphName: o.graphName },
+    oboIds,
+    typedefs,
     nodesPath,
     edgesPath
   };
@@ -2059,7 +2471,7 @@ class ImportContext {
    */
   declareEdgeIds(edges, read, name, unique) {
     let numbers = 0;
-    let strings = 0;
+    let strings2 = 0;
     for (const edge of edges) {
       if (!isJsonObject(edge)) {
         continue;
@@ -2068,16 +2480,16 @@ class ImportContext {
       if (typeof raw === "number") {
         numbers++;
       } else if (typeof raw === "string") {
-        strings++;
+        strings2++;
       }
     }
-    if (numbers + strings === 0) {
+    if (numbers + strings2 === 0) {
       return null;
     }
-    const dtype = strings === 0 ? "f64" : "string";
+    const dtype = strings2 === 0 ? "f64" : "string";
     const columnName = uniqueColumnName(name, "id", (candidate) => this.edges.taken(candidate));
     const handle = this.edges.declare({ name: columnName, dtype, role: "id", nullable: true, unique });
-    const stringify = strings > 0 && numbers > 0;
+    const stringify = strings2 > 0 && numbers > 0;
     const seen = unique ? /* @__PURE__ */ new Set() : null;
     if (stringify) {
       this.report.warning(
@@ -3029,31 +3441,84 @@ function importJgf(ctx, root) {
   ctx.setMeta(shape, { name: label, ...ctx.weightOriginPatch() });
 }
 function jgfGraphOf(ctx, root) {
+  return isJsonObject(root.graph) ? root.graph : chosenGraph(ctx, root, "JGF");
+}
+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`,
+      `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;
 }
+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;
+}
+function countOf(section) {
+  if (section === void 0 || section === null) {
+    return 0;
+  }
+  if (Array.isArray(section)) {
+    return section.length;
+  }
+  return isJsonObject(section) ? Object.keys(section).length : null;
+}
+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 }];
+}
+const MAX_TEXT_LENGTH = 2 ** 29 - 24;
+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("");
+}
 function pushJgfNode(ctx, id, record, labelColumn, element) {
   const index = ctx.pushNode(id, element);
   if (index < 0) {
@@ -3408,11 +3873,27 @@ 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.
@@ -3425,9 +3906,9 @@ 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);
@@ -3439,7 +3920,7 @@ const jsonImporter = Object.freeze({
 });
 function readGraph(root, dialect, sink, report, resolved, json, options) {
   const ctx = new ImportContext(sink, report, resolved, json, options?.defaultDirected !== void 0);
-  reportSinkOptions(sink, options, report);
+  reportSinkOptions(sink, options, report, dialect === "obographs");
   reportUnusedOptions(options, report, USED_OPTIONS);
   if (dialect === "cytoscape") {
     importCytoscape(ctx, root);
@@ -3467,6 +3948,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}`, {
@@ -3487,4 +3971,4 @@ export {
   jsonCapabilities as j,
   sniffJsonDialect as s
 };
-//# sourceMappingURL=importer-B6rKRxzv.js.map
+//# sourceMappingURL=importer-Du5crN9l.js.map