keepset 0.38.0 → 0.39.0

package/dist/node/fetch-dataset.js

@@ -1,4 +1,4 @@
-import { $ as ArchiveError, H as getCollectionTarget, L as getOwn, U as getTarget, at as RecipeError, it as NativeParseError, rt as KeepsetError, t as getDataset, z as countTarget } from "../bundled-U2l4WT5T.js";
+import { $ as ArchiveError, H as getCollectionTarget, L as getOwn, U as getTarget, at as RecipeError, it as NativeParseError, rt as KeepsetError, t as getDataset, z as countTarget } from "../bundled-6dYCPVD-.js";
 import { RoundTripMismatchError, assertRoundTrip, encode } from "crossmap";
 import { z } from "zod";
 import { createHash } from "node:crypto";
@@ -127,6 +127,15 @@ function endpoint$1(fields, column, lineNumber) {
 	return value.trim();
 }
 /**
+* Whether a line meets one of the recipe's `where` conditions.
+* @param fields - The line's fields, at least as many as the highest column the recipe names.
+* @param condition - The condition.
+* @returns True when the condition's column, trimmed, equals its value.
+*/
+function meets(fields, condition) {
+	return fields[condition.column]?.trim() === condition.equals;
+}
+/**
 * Resolves `detect` to a fixed delimiter from the first data line: tab when it holds a tab, comma when it holds a comma, whitespace otherwise. The rule is a function of the file's bytes, so a recipe that detects still reads the same way every time.
 * @param dataLine - The first line that is neither skipped, blank nor a comment.
 * @returns The fixed delimiter.
@@ -149,31 +158,33 @@ function multiplicity(fields, column, lineNumber) {
 	return Number(value);
 }
 /**
-* Parses a delimited edge list: one edge per line, source and target in the configured columns, after `skipLines` header lines, with blank lines and lines whose first non-blank characters are a comment prefix skipped. A `detect` delimiter is fixed from the first data line. A recipe that names a `keep` column reads only the lines whose field there is one of its values; one that names a `multiplicityColumn` emits as many edges for a line as the field says, none for a zero; one that says `mirrored` emits each pair of mirror-image lines once. Nodes are the endpoints of the lines read, in order of first appearance.
-* @param text - The file text.
+* Parses a delimited edge list: one edge per line, source and target in the configured columns, after `skipLines` header lines, with blank lines and lines whose first non-blank characters are a comment prefix skipped. A `detect` delimiter is fixed from the first data line. A recipe that names a `keep` column reads only the lines whose field there is one of its values, and one that states `where` reads only the lines whose listed columns, trimmed, equal their values, so a file that records several kinds of row (an interaction file listing genetic beside physical interactions) is read for the rows the dataset is made of; a line that is not read is still checked for the fields it needs. A recipe that names a `multiplicityColumn` emits as many edges for a line as the field says, none for a zero; one that says `mirrored` emits each pair of mirror-image lines once. Nodes are the endpoints of the lines read, in order of first appearance. The text is read line by line, so a file longer than the engine's longest string is read too.
+* @param text - The file text, whole or in pieces.
 * @param options - The recipe's edge-list parser.
 * @returns The native graph.
-* @throws NativeParseError naming the line when a data line has too few fields, an empty endpoint or a multiplicity that is not a whole number, when a mirrored table has a line without its mirror, or when the file holds no edges.
+* @throws NativeParseError naming the line when a data line has too few fields, an empty endpoint or a multiplicity that is not a whole number, when a mirrored table has a line without its mirror, or when no line is an edge.
 */
 function parseEdgeList(text, options) {
 	let split = options.delimiter === "detect" ? void 0 : splitters[options.delimiter];
-	const needed = Math.max(options.sourceColumn, options.targetColumn, options.keep?.column ?? 0, options.multiplicityColumn ?? 0) + 1;
+	const { where } = options;
+	const needed = Math.max(options.sourceColumn, options.targetColumn, options.keep?.column ?? 0, options.multiplicityColumn ?? 0, ...where === void 0 ? [] : where.map((condition) => condition.column)) + 1;
 	const order = new NodeOrder();
 	const edges = [];
 	const awaiting = /* @__PURE__ */ new Map();
-	const all = lines(text);
-	for (const [index, line] of all.entries()) {
-		const lineNumber = index + 1;
+	let lastLine = 0;
+	forEachLine(typeof text === "string" ? [text] : text, (line, lineNumber) => {
+		lastLine = lineNumber;
 		const content = line.trimStart();
-		if (index < options.skipLines || content === "" || options.commentPrefixes.some((prefix) => content.startsWith(prefix))) continue;
+		if (lineNumber <= options.skipLines || content === "" || options.commentPrefixes.some((prefix) => content.startsWith(prefix))) return;
 		split ??= splitters[detect(line)];
 		const fields = split(line);
 		if (fields.length < needed) throw new NativeParseError("edge-list", lineNumber, `expected at least ${String(needed)} fields, found ${String(fields.length)}`);
-		if (options.keep !== void 0 && !options.keep.values.includes(fields[options.keep.column]?.trim() ?? "")) continue;
+		if (options.keep !== void 0 && !options.keep.values.includes(fields[options.keep.column]?.trim() ?? "")) return;
+		if (where !== void 0 && !where.every((condition) => meets(fields, condition))) return;
 		const source = endpoint$1(fields, options.sourceColumn, lineNumber);
 		const target = endpoint$1(fields, options.targetColumn, lineNumber);
 		const count = options.multiplicityColumn === void 0 ? 1 : multiplicity(fields, options.multiplicityColumn, lineNumber);
-		if (count === 0) continue;
+		if (count === 0) return;
 		order.add(source);
 		order.add(target);
 		if (options.mirrored === true && source !== target) {
@@ -185,7 +196,7 @@ function parseEdgeList(text, options) {
 			const waiting = awaiting.get(key);
 			if (waiting !== void 0 && waiting.length > 0) {
 				waiting.shift();
-				continue;
+				return;
 			}
 			const mirror = JSON.stringify([
 				target,
@@ -198,12 +209,12 @@ function parseEdgeList(text, options) {
 			source,
 			target
 		});
-	}
+	});
 	for (const [key, waiting] of awaiting) {
 		const [first] = waiting;
 		if (first !== void 0) throw new NativeParseError("edge-list", first, `the table is mirrored but this line has no mirror image (${key} is never listed)`);
 	}
-	if (edges.length === 0) throw new NativeParseError("edge-list", all.length, "the file holds no edges");
+	if (edges.length === 0) throw new NativeParseError("edge-list", lastLine, where === void 0 ? "the file holds no edges" : "no line of the file meets the recipe's where conditions");
 	return {
 		nodes: order.nodes(),
 		edges
@@ -211,7 +222,7 @@ function parseEdgeList(text, options) {
 }
 //#endregion
 //#region src/parsers/gd-contest.ts
-const FORMAT$14 = "gd-contest";
+const FORMAT$15 = "gd-contest";
 const NUMBER$9 = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[Ee][+-]?\d+)?$/;
 /**
 * Reads a vertex number, which the format numbers from 0 to N - 1.
@@ -220,7 +231,7 @@ const NUMBER$9 = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[Ee][+-]?\d+)?$/;
 * @returns The vertex id as text.
 */
 function vertex$1(token, count) {
-	if (!/^(?:0|[1-9]\d*)$/.test(token.text) || Number(token.text) >= count) throw new NativeParseError(FORMAT$14, token.line, `expected a vertex number from 0 to ${String(count - 1)}, found ${JSON.stringify(token.text)}`);
+	if (!/^(?:0|[1-9]\d*)$/.test(token.text) || Number(token.text) >= count) throw new NativeParseError(FORMAT$15, token.line, `expected a vertex number from 0 to ${String(count - 1)}, found ${JSON.stringify(token.text)}`);
 	return token.text;
 }
 /**
@@ -240,17 +251,17 @@ function parseGdContest(text) {
 		});
 	}
 	const [first] = tokens;
-	if (first === void 0) throw new NativeParseError(FORMAT$14, 1, "the file holds no vertex count");
-	if (!/^(?:0|[1-9]\d*)$/.test(first.text)) throw new NativeParseError(FORMAT$14, first.line, `the vertex count must be a non-negative integer, found ${JSON.stringify(first.text)}`);
+	if (first === void 0) throw new NativeParseError(FORMAT$15, 1, "the file holds no vertex count");
+	if (!/^(?:0|[1-9]\d*)$/.test(first.text)) throw new NativeParseError(FORMAT$15, first.line, `the vertex count must be a non-negative integer, found ${JSON.stringify(first.text)}`);
 	const count = Number(first.text);
 	const coordinates = tokens.slice(1, 1 + 2 * count);
-	if (coordinates.length < 2 * count) throw new NativeParseError(FORMAT$14, lines(text).length, `expected ${String(2 * count)} coordinates for ${String(count)} vertices, found ${String(coordinates.length)}`);
-	for (const coordinate of coordinates) if (!NUMBER$9.test(coordinate.text)) throw new NativeParseError(FORMAT$14, coordinate.line, `coordinate ${JSON.stringify(coordinate.text)} is not a number`);
+	if (coordinates.length < 2 * count) throw new NativeParseError(FORMAT$15, lines(text).length, `expected ${String(2 * count)} coordinates for ${String(count)} vertices, found ${String(coordinates.length)}`);
+	for (const coordinate of coordinates) if (!NUMBER$9.test(coordinate.text)) throw new NativeParseError(FORMAT$15, coordinate.line, `coordinate ${JSON.stringify(coordinate.text)} is not a number`);
 	const ends = tokens.slice(1 + 2 * count);
 	const edges = [];
 	for (let source = ends.shift(); source !== void 0; source = ends.shift()) {
 		const target = ends.shift();
-		if (target === void 0) throw new NativeParseError(FORMAT$14, source.line, `edge from vertex ${source.text} has no second vertex`);
+		if (target === void 0) throw new NativeParseError(FORMAT$15, source.line, `edge from vertex ${source.text} has no second vertex`);
 		edges.push({
 			source: vertex$1(source, count),
 			target: vertex$1(target, count)
@@ -420,7 +431,7 @@ function parseGml(text) {
 }
 //#endregion
 //#region src/parsers/hgb.ts
-const FORMAT$13 = "hgb";
+const FORMAT$14 = "hgb";
 /** A type code or node id as the HGB files write them: a non-negative decimal integer with no sign or leading zero. */
 const CODE = /^(?:0|[1-9]\d*)$/;
 /** A number as a decimal literal with an optional sign and exponent, so `Number` cannot read hex, an empty string or infinity. */
@@ -440,7 +451,7 @@ const LINK_FIELDS = 4;
 */
 function resolve(field, types, where) {
 	const type = types[CODE.test(field) ? Number(field) : -1];
-	if (type === void 0) throw new NativeParseError(FORMAT$13, where.line, `${where.file}: the ${where.kind} type ${JSON.stringify(field)} is not one of the ${String(types.length)} the recipe names`);
+	if (type === void 0) throw new NativeParseError(FORMAT$14, where.line, `${where.file}: the ${where.kind} type ${JSON.stringify(field)} is not one of the ${String(types.length)} the recipe names`);
 	return type;
 }
 /**
@@ -458,9 +469,9 @@ function parseHgb(parts, options) {
 	forEachLine(parts.nodes, (line, number) => {
 		const fields = line.split("	");
 		const [id, , type] = fields;
-		if (fields.length !== NODE_FIELDS && fields.length !== NODE_FIELDS_WITH_ATTRIBUTES || id === void 0 || type === void 0) throw new NativeParseError(FORMAT$13, number, `node.dat: expected ${String(NODE_FIELDS)} or ${String(NODE_FIELDS_WITH_ATTRIBUTES)} fields separated by tabs, found ${String(fields.length)}`);
-		if (!CODE.test(id)) throw new NativeParseError(FORMAT$13, number, `node.dat: the node id ${JSON.stringify(id)} is not a non-negative integer`);
-		if (typeOf.has(id)) throw new NativeParseError(FORMAT$13, number, `node.dat: the node id ${id} is repeated`);
+		if (fields.length !== NODE_FIELDS && fields.length !== NODE_FIELDS_WITH_ATTRIBUTES || id === void 0 || type === void 0) throw new NativeParseError(FORMAT$14, number, `node.dat: expected ${String(NODE_FIELDS)} or ${String(NODE_FIELDS_WITH_ATTRIBUTES)} fields separated by tabs, found ${String(fields.length)}`);
+		if (!CODE.test(id)) throw new NativeParseError(FORMAT$14, number, `node.dat: the node id ${JSON.stringify(id)} is not a non-negative integer`);
+		if (typeOf.has(id)) throw new NativeParseError(FORMAT$14, number, `node.dat: the node id ${id} is repeated`);
 		const nodeType = resolve(type, options.nodeTypes, {
 			file: "node.dat",
 			line: number,
@@ -472,12 +483,12 @@ function parseHgb(parts, options) {
 			type: nodeType
 		});
 	});
-	if (nodes.length === 0) throw new NativeParseError(FORMAT$13, 1, "node.dat: the file holds no nodes");
+	if (nodes.length === 0) throw new NativeParseError(FORMAT$14, 1, "node.dat: the file holds no nodes");
 	const edges = [];
 	forEachLine(parts.links, (line, number) => {
 		const fields = line.split("	");
 		const [source, target, type, weight] = fields;
-		if (fields.length !== LINK_FIELDS || source === void 0 || target === void 0 || type === void 0 || weight === void 0) throw new NativeParseError(FORMAT$13, number, `link.dat: expected ${String(LINK_FIELDS)} fields separated by tabs, found ${String(fields.length)}`);
+		if (fields.length !== LINK_FIELDS || source === void 0 || target === void 0 || type === void 0 || weight === void 0) throw new NativeParseError(FORMAT$14, number, `link.dat: expected ${String(LINK_FIELDS)} fields separated by tabs, found ${String(fields.length)}`);
 		const linkType = resolve(type, options.linkTypes, {
 			file: "link.dat",
 			line: number,
@@ -493,17 +504,17 @@ function parseHgb(parts, options) {
 			linkType.target
 		]]) {
 			const actual = typeOf.get(id);
-			if (actual === void 0) throw new NativeParseError(FORMAT$13, number, `link.dat: the ${end} ${JSON.stringify(id)} is not a node of node.dat`);
-			if (actual !== expected) throw new NativeParseError(FORMAT$13, number, `link.dat: a ${linkType.name} link's ${end} must be a ${expected} node, and ${id} is a ${actual} node`);
+			if (actual === void 0) throw new NativeParseError(FORMAT$14, number, `link.dat: the ${end} ${JSON.stringify(id)} is not a node of node.dat`);
+			if (actual !== expected) throw new NativeParseError(FORMAT$14, number, `link.dat: a ${linkType.name} link's ${end} must be a ${expected} node, and ${id} is a ${actual} node`);
 		}
-		if (!DECIMAL$5.test(weight) || Number(weight) !== 1) throw new NativeParseError(FORMAT$13, number, `link.dat: the weight ${JSON.stringify(weight)} is not 1; a weighted HGB file would lose its weights`);
+		if (!DECIMAL$5.test(weight) || Number(weight) !== 1) throw new NativeParseError(FORMAT$14, number, `link.dat: the weight ${JSON.stringify(weight)} is not 1; a weighted HGB file would lose its weights`);
 		edges.push({
 			source,
 			target,
 			type: linkType.name
 		});
 	});
-	if (edges.length === 0) throw new NativeParseError(FORMAT$13, 1, "link.dat: the file holds no links");
+	if (edges.length === 0) throw new NativeParseError(FORMAT$14, 1, "link.dat: the file holds no links");
 	return {
 		nodes,
 		edges
@@ -511,7 +522,7 @@ function parseHgb(parts, options) {
 }
 //#endregion
 //#region src/parsers/kg-triples.ts
-const FORMAT$12 = "kg-triples";
+const FORMAT$13 = "kg-triples";
 /** The character each delimiter option splits a line on. A line is split on exactly that character, so a field cannot hide a second delimiter. */
 const DELIMITERS$1 = {
 	tab: "	",
@@ -533,8 +544,8 @@ const QUOTE$2 = "\"";
 */
 function value(field, quoted, where) {
 	const inner = quoted ? field.slice(1, -1) : field;
-	if (quoted && (field.length < 2 || !field.startsWith(QUOTE$2) || !field.endsWith(QUOTE$2) || inner.includes(QUOTE$2))) throw new NativeParseError(FORMAT$12, where.line, `${where.part}the field ${JSON.stringify(field)} is not one value wrapped in double quotes`);
-	if (inner === "") throw new NativeParseError(FORMAT$12, where.line, `${where.part}a field is empty`);
+	if (quoted && (field.length < 2 || !field.startsWith(QUOTE$2) || !field.endsWith(QUOTE$2) || inner.includes(QUOTE$2))) throw new NativeParseError(FORMAT$13, where.line, `${where.part}the field ${JSON.stringify(field)} is not one value wrapped in double quotes`);
+	if (inner === "") throw new NativeParseError(FORMAT$13, where.line, `${where.part}a field is empty`);
 	return inner;
 }
 /**
@@ -558,16 +569,16 @@ function parseKgTriples(parts, options) {
 		let lastLine = 0;
 		forEachLine(part.pieces, (line, number) => {
 			lastLine = number;
-			if (line.trim() === "") throw new NativeParseError(FORMAT$12, number, `${label}the line is blank`);
+			if (line.trim() === "") throw new NativeParseError(FORMAT$13, number, `${label}the line is blank`);
 			if (number === 1 && options.header === "names") return;
 			if (number === 1 && options.header === "count") {
-				if (!COUNT$1.test(line)) throw new NativeParseError(FORMAT$12, number, `${label}expected the number of triples on the first line, found ${JSON.stringify(line)}`);
+				if (!COUNT$1.test(line)) throw new NativeParseError(FORMAT$13, number, `${label}expected the number of triples on the first line, found ${JSON.stringify(line)}`);
 				declared = Number(line);
 				return;
 			}
 			const fields = line.split(delimiter);
 			const [head, middle, last] = fields;
-			if (fields.length !== TRIPLE_FIELDS || head === void 0 || middle === void 0 || last === void 0) throw new NativeParseError(FORMAT$12, number, `${label}expected ${String(TRIPLE_FIELDS)} fields separated by ${options.delimiter}, found ${String(fields.length)}`);
+			if (fields.length !== TRIPLE_FIELDS || head === void 0 || middle === void 0 || last === void 0) throw new NativeParseError(FORMAT$13, number, `${label}expected ${String(TRIPLE_FIELDS)} fields separated by ${options.delimiter}, found ${String(fields.length)}`);
 			const where = {
 				line: number,
 				part: label
@@ -593,8 +604,8 @@ function parseKgTriples(parts, options) {
 			});
 			triples += 1;
 		});
-		if (triples === 0) throw new NativeParseError(FORMAT$12, lastLine, `${label}the file holds no triples`);
-		if (declared !== void 0 && declared !== triples) throw new NativeParseError(FORMAT$12, lastLine, `${label}the first line declares ${String(declared)} triples, the file holds ${String(triples)}`);
+		if (triples === 0) throw new NativeParseError(FORMAT$13, lastLine, `${label}the file holds no triples`);
+		if (declared !== void 0 && declared !== triples) throw new NativeParseError(FORMAT$13, lastLine, `${label}the first line declares ${String(declared)} triples, the file holds ${String(triples)}`);
 	}
 	return {
 		nodes: order.nodes(),
@@ -603,7 +614,7 @@ function parseKgTriples(parts, options) {
 }
 //#endregion
 //#region src/parsers/konect.ts
-const FORMAT$11 = "konect";
+const FORMAT$12 = "konect";
 /** The network formats of KONECT's first line (Kunegis, "The KONECT Handbook", table 1): undirected, directed and bipartite. */
 const NETWORK_FORMATS = /* @__PURE__ */ new Set([
 	"sym",
@@ -678,9 +689,9 @@ function parseKonect(pieces, options) {
 		}));
 	});
 	const { header } = state;
-	if (header === void 0) throw new NativeParseError(FORMAT$11, lastLine, "the file has no first line naming its format and weights");
-	if (edges.length === 0) throw new NativeParseError(FORMAT$11, lastLine, "the file holds no edges");
-	if (header.counts !== void 0 && header.counts.edges !== edges.length) throw new NativeParseError(FORMAT$11, lastLine, `the second line declares ${String(header.counts.edges)} edges, the file holds ${String(edges.length)}`);
+	if (header === void 0) throw new NativeParseError(FORMAT$12, lastLine, "the file has no first line naming its format and weights");
+	if (edges.length === 0) throw new NativeParseError(FORMAT$12, lastLine, "the file holds no edges");
+	if (header.counts !== void 0 && header.counts.edges !== edges.length) throw new NativeParseError(FORMAT$12, lastLine, `the second line declares ${String(header.counts.edges)} edges, the file holds ${String(edges.length)}`);
 	return {
 		nodes: order.nodes(),
 		edges
@@ -698,9 +709,9 @@ function readHeader(content, number, options) {
 	const match = FORMAT_LINE.exec(content);
 	const network = match?.[1];
 	const weights = match?.[2];
-	if (network === void 0 || weights === void 0 || !NETWORK_FORMATS.has(network)) throw new NativeParseError(FORMAT$11, number, `expected a first line "% FORMAT WEIGHTS" with FORMAT one of ${[...NETWORK_FORMATS].join(", ")}, found ${JSON.stringify(content)}`);
-	if (!WEIGHTED_TYPES.has(weights) && !UNWEIGHTED_TYPES.has(weights)) throw new NativeParseError(FORMAT$11, number, `the weight type ${JSON.stringify(weights)} is not one this parser reads (its third column is not an edge weight or a repetition count)`);
-	if (options.weighted !== WEIGHTED_TYPES.has(weights)) throw new NativeParseError(FORMAT$11, number, `the file's weight type is ${weights}, so a recipe with weighted ${String(WEIGHTED_TYPES.has(weights))} reads it, not one with weighted ${String(options.weighted)}`);
+	if (network === void 0 || weights === void 0 || !NETWORK_FORMATS.has(network)) throw new NativeParseError(FORMAT$12, number, `expected a first line "% FORMAT WEIGHTS" with FORMAT one of ${[...NETWORK_FORMATS].join(", ")}, found ${JSON.stringify(content)}`);
+	if (!WEIGHTED_TYPES.has(weights) && !UNWEIGHTED_TYPES.has(weights)) throw new NativeParseError(FORMAT$12, number, `the weight type ${JSON.stringify(weights)} is not one this parser reads (its third column is not an edge weight or a repetition count)`);
+	if (options.weighted !== WEIGHTED_TYPES.has(weights)) throw new NativeParseError(FORMAT$12, number, `the file's weight type is ${weights}, so a recipe with weighted ${String(WEIGHTED_TYPES.has(weights))} reads it, not one with weighted ${String(options.weighted)}`);
 	return {
 		line: number,
 		network
@@ -720,15 +731,15 @@ function readEdge(content, number, context) {
 	const [from, to, third, time] = fields;
 	const expected = options.timestamped ? TIMESTAMPED_COLUMNS : options.weighted ? WEIGHTED_COLUMNS : void 0;
 	const fits = expected === void 0 ? fields.length === ENDPOINT_COLUMNS || fields.length === WEIGHTED_COLUMNS : fields.length === expected;
-	if (from === void 0 || to === void 0 || !fits) throw new NativeParseError(FORMAT$11, number, `expected ${expected === void 0 ? `${String(ENDPOINT_COLUMNS)} or ${String(WEIGHTED_COLUMNS)}` : String(expected)} columns for this recipe, found ${String(fields.length)}`);
+	if (from === void 0 || to === void 0 || !fits) throw new NativeParseError(FORMAT$12, number, `expected ${expected === void 0 ? `${String(ENDPOINT_COLUMNS)} or ${String(WEIGHTED_COLUMNS)}` : String(expected)} columns for this recipe, found ${String(fields.length)}`);
 	const bipartite = header.network === "bip";
 	const source = endpoint(from, bipartite ? LEFT_PREFIX : "", header.counts?.left, number);
 	const target = endpoint(to, bipartite ? RIGHT_PREFIX : "", header.counts?.right, number);
 	order.add(source);
 	order.add(target);
-	if (third !== void 0 && !options.weighted && (!DECIMAL$4.test(third) || Number(third) !== 1)) throw new NativeParseError(FORMAT$11, number, `the third column ${JSON.stringify(third)} is not 1; an edge that stands for several would be read as one`);
-	if (third !== void 0 && options.weighted && !DECIMAL$4.test(third)) throw new NativeParseError(FORMAT$11, number, `the weight ${JSON.stringify(third)} is not a number`);
-	if (time !== void 0 && !DECIMAL$4.test(time)) throw new NativeParseError(FORMAT$11, number, `the time ${JSON.stringify(time)} is not a number`);
+	if (third !== void 0 && !options.weighted && (!DECIMAL$4.test(third) || Number(third) !== 1)) throw new NativeParseError(FORMAT$12, number, `the third column ${JSON.stringify(third)} is not 1; an edge that stands for several would be read as one`);
+	if (third !== void 0 && options.weighted && !DECIMAL$4.test(third)) throw new NativeParseError(FORMAT$12, number, `the weight ${JSON.stringify(third)} is not a number`);
+	if (time !== void 0 && !DECIMAL$4.test(time)) throw new NativeParseError(FORMAT$12, number, `the time ${JSON.stringify(time)} is not a number`);
 	const edge = {
 		source,
 		target
@@ -747,10 +758,215 @@ function readEdge(content, number, context) {
 * @throws NativeParseError when the token is not a positive integer or exceeds the set's size.
 */
 function endpoint(token, prefix, size, number) {
-	if (!NODE_ID.test(token) || size !== void 0 && Number(token) > size) throw new NativeParseError(FORMAT$11, number, `${JSON.stringify(token)} is not a node id from 1${size === void 0 ? "" : ` to ${String(size)}`}`);
+	if (!NODE_ID.test(token) || size !== void 0 && Number(token) > size) throw new NativeParseError(FORMAT$12, number, `${JSON.stringify(token)} is not a node id from 1${size === void 0 ? "" : ` to ${String(size)}`}`);
 	return `${prefix}${token}`;
 }
 //#endregion
+//#region src/parsers/ogb.ts
+const FORMAT$11 = "ogb";
+/** The files of an OGB raw directory this reader takes, by their path under the dataset's root directory. A relation's files sit in `raw/relations/<head>___<relation>___<tail>/`. */
+const RAW = /^(?<root>(?:[^/]+\/)*?)raw\/(?<name>num-node-list|num-node-dict|edge|num-edge-list|triplet-type-list|relations\/[^/]+\/(?:edge|num-edge-list))\.csv\.gz$/u;
+const INDEX = /^(?:0|[1-9]\d*)$/;
+/** The fields of a line of `triplet-type-list.csv.gz`: a head type, a relation and a tail type. */
+const TRIPLET_PARTS = 3;
+/**
+* Orders two names by code point, the order Python's `sorted` gives the ASCII type and relation names OGB uses.
+* @param left - A name.
+* @param right - Another.
+* @returns Negative, zero or positive.
+*/
+function compare(left, right) {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+* Visits the non-blank lines of a file, read a piece at a time.
+* @param file - The file.
+* @param visit - Called with each non-blank line and its number.
+*/
+function forEachRow(file, visit) {
+	forEachLine(file.text(), (text, line) => {
+		if (text.trim() !== "") visit({
+			text,
+			line
+		});
+	});
+}
+/**
+* The non-blank lines of a small file, such as a count or the triplet list.
+* @param file - The file.
+* @returns Each non-blank line and its number.
+*/
+function rows(file) {
+	const all = [];
+	forEachRow(file, (row) => {
+		all.push(row);
+	});
+	return all;
+}
+/**
+* Reads a file that holds one line, such as a count.
+* @param file - The file.
+* @returns The line's text.
+* @throws NativeParseError when the file holds no line or more than one.
+*/
+function onlyLine(file) {
+	const all = rows(file);
+	const [only] = all;
+	if (all.length !== 1 || only === void 0) throw new NativeParseError(FORMAT$11, all[1]?.line ?? 1, `${file.path} must hold one line, found ${String(all.length)}`);
+	return only.text.trim();
+}
+/**
+* Reads a non-negative integer.
+* @param text - The field.
+* @param file - The file, for the error.
+* @param line - The 1-based line, for the error.
+* @returns The integer.
+* @throws NativeParseError when the field is not a non-negative integer.
+*/
+function index(text, file, line) {
+	const trimmed = text.trim();
+	if (!INDEX.test(trimmed)) throw new NativeParseError(FORMAT$11, line, `${file.path}: expected a non-negative integer, found ${JSON.stringify(text)}`);
+	return Number(trimmed);
+}
+/**
+* Reads an `edge.csv.gz` file, one `<source>,<target>` pair of node indices per line, checking each index against its node type's count and the line count against the relation's `num-edge-list.csv.gz`.
+* @param edges - The edge file.
+* @param count - The relation's `num-edge-list.csv.gz`.
+* @param ends - The source and target node types' counts and how each index is named.
+* @param emit - Called with each edge, in file order, so a large file is never held twice.
+* @throws NativeParseError naming the file and line for a line that is not a pair of indices, an index outside its type's nodes, or a line count other than the recorded one.
+*/
+function readEdges(edges, count, ends, emit) {
+	const recorded = index(onlyLine(count), count, 1);
+	let read = 0;
+	forEachRow(edges, ({ text, line }) => {
+		const fields = text.split(",");
+		const [first, second] = fields;
+		if (fields.length !== 2 || first === void 0 || second === void 0) throw new NativeParseError(FORMAT$11, line, `${edges.path}: expected a source and a target index, found ${JSON.stringify(text)}`);
+		const source = index(first, edges, line);
+		const target = index(second, edges, line);
+		if (source >= ends.sources || target >= ends.targets) throw new NativeParseError(FORMAT$11, line, `${edges.path}: edge ${text} names a node outside the ${String(ends.sources)} sources and ${String(ends.targets)} targets the dataset records`);
+		emit({
+			source: ends.source(source),
+			target: ends.target(target)
+		});
+		read += 1;
+	});
+	if (read !== recorded) throw new NativeParseError(FORMAT$11, read, `${edges.path} holds ${String(read)} edges, but ${count.path} records ${String(recorded)}`);
+}
+/**
+* Takes one file of the dataset directory by its name under `raw/`.
+* @param files - The files by name.
+* @param name - The name, such as `edge` or `relations/paper___cites___paper/edge`.
+* @param root - The dataset's root directory, for the error.
+* @returns The file.
+* @throws NativeParseError when the archive's selection holds no such file.
+*/
+function required$1(files, name, root) {
+	const file = files.get(name);
+	if (file === void 0) throw new NativeParseError(FORMAT$11, 1, `the dataset directory ${root} has no raw/${name}.csv.gz among the files the recipe selects`);
+	return file;
+}
+/**
+* Parses an Open Graph Benchmark dataset from the files of its raw directory, as OGB's own `read_csv_graph_raw` and `read_csv_heterograph_raw` read them (ogb/io/read_graph_raw.py in snap-stanford/ogb). A homogeneous dataset has `raw/num-node-list.csv.gz` (its one graph's node count), `raw/edge.csv.gz` (one `<source>,<target>` pair of node indices per line, no header) and `raw/num-edge-list.csv.gz`: its nodes are `0` to `N - 1`, isolated ones included, and its edges the pairs in file order. A heterogeneous dataset has `raw/num-node-dict.csv.gz` (a header of node types over one row of their counts), `raw/triplet-type-list.csv.gz` (one `<head>,<relation>,<tail>` type triplet per line) and, per triplet, `raw/relations/<head>___<relation>___<tail>/edge.csv.gz` and `num-edge-list.csv.gz`, whose indices count within the head and tail types: its nodes are `<type>:<index>` for each type in sorted order and each index from 0, and its edges are each relation's pairs in file order, relations in the sorted order of their triplets, which is the order OGB reads them in. Edges keep the file's direction. Relation names, node features, labels and splits are not carried, as no graph parser in this version carries more than topology.
+* @param files - The files the recipe's archive selects, gunzipped and decoded: every one must be a file of one dataset's raw directory named above.
+* @returns The native graph.
+* @throws NativeParseError naming the file and line for a file outside the raw layout, files of two datasets, a dataset with neither or both node-count files, a missing file, a graph count other than one, a malformed count or triplet, a relation directory the triplet list does not name, an edge that is not a pair of indices of the dataset's nodes, or an edge file whose line count differs from its recorded count.
+*/
+function parseOgb(files) {
+	const byName = /* @__PURE__ */ new Map();
+	const roots = /* @__PURE__ */ new Set();
+	for (const file of files) {
+		const match = RAW.exec(file.path);
+		const name = match?.groups?.["name"];
+		const root = match?.groups?.["root"];
+		if (name === void 0 || root === void 0) throw new NativeParseError(FORMAT$11, 1, `${file.path} is not a file of an OGB raw directory this reader takes`);
+		roots.add(root);
+		byName.set(name, file);
+	}
+	const [root] = roots;
+	if (roots.size !== 1 || root === void 0) throw new NativeParseError(FORMAT$11, 1, `the recipe must select the raw files of one dataset, found ${roots.size === 0 ? "none" : `the directories ${[...roots].join(", ")}`}`);
+	const homogeneous = byName.get("num-node-list");
+	const heterogeneous = byName.get("num-node-dict");
+	const neitherOrBoth = `the dataset directory ${root} must have exactly one of raw/num-node-list.csv.gz (one node type) and raw/num-node-dict.csv.gz (several)`;
+	const edges = [];
+	if (homogeneous !== void 0) {
+		if (heterogeneous !== void 0) throw new NativeParseError(FORMAT$11, 1, neitherOrBoth);
+		const [relation] = [...byName.keys()].filter((name) => name.startsWith("relations/"));
+		if (relation !== void 0 || byName.has("triplet-type-list")) throw new NativeParseError(FORMAT$11, 1, `the dataset directory ${root} has raw/num-node-list.csv.gz, so it has one node type, but the recipe selects ${relation === void 0 ? "raw/triplet-type-list.csv.gz" : `raw/${relation}.csv.gz`} as well`);
+		const count = index(onlyLine(homogeneous), homogeneous, 1);
+		const name = (node) => String(node);
+		readEdges(required$1(byName, "edge", root), required$1(byName, "num-edge-list", root), {
+			sources: count,
+			targets: count,
+			source: name,
+			target: name
+		}, (edge) => {
+			edges.push(edge);
+		});
+		return {
+			nodes: Array.from({ length: count }, (_, node) => ({ id: String(node) })),
+			edges
+		};
+	}
+	if (heterogeneous === void 0) throw new NativeParseError(FORMAT$11, 1, neitherOrBoth);
+	for (const stray of ["edge", "num-edge-list"]) if (byName.has(stray)) throw new NativeParseError(FORMAT$11, 1, `the dataset directory ${root} has raw/num-node-dict.csv.gz, so its edges are in raw/relations/, but the recipe selects raw/${stray}.csv.gz as well`);
+	const header = rows(heterogeneous);
+	const [types, counts] = header;
+	if (header.length !== 2 || types === void 0 || counts === void 0) throw new NativeParseError(FORMAT$11, header[2]?.line ?? 1, `${heterogeneous.path} must hold a header of node types and one row of their counts, found ${String(header.length)} lines`);
+	const typeNames = types.text.split(",").map((type) => type.trim());
+	const typeCounts = counts.text.split(",");
+	if (typeNames.length !== typeCounts.length || typeNames.some((type) => type === "") || new Set(typeNames).size !== typeNames.length) throw new NativeParseError(FORMAT$11, counts.line, `${heterogeneous.path} must name each node type once, over one count per type`);
+	const nodeTypes = typeNames.map((type, position) => {
+		const count = typeCounts[position];
+		if (count === void 0) throw new NativeParseError(FORMAT$11, counts.line, `${heterogeneous.path} gives node type ${type} no count`);
+		return {
+			type,
+			count: index(count, heterogeneous, counts.line)
+		};
+	});
+	nodeTypes.sort((left, right) => compare(left.type, right.type));
+	const nodeCounts = new Map(nodeTypes.map(({ type, count }) => [type, count]));
+	const triplets = required$1(byName, "triplet-type-list", root);
+	const relations = [];
+	for (const { text, line } of rows(triplets)) {
+		const parts = text.split(",").map((part) => part.trim());
+		const [head, relation, tail] = parts;
+		if (parts.length !== TRIPLET_PARTS || head === void 0 || relation === void 0 || tail === void 0 || relation === "") throw new NativeParseError(FORMAT$11, line, `${triplets.path}: expected a head type, a relation and a tail type, found ${JSON.stringify(text)}`);
+		const sources = nodeCounts.get(head);
+		const targets = nodeCounts.get(tail);
+		if (sources === void 0 || targets === void 0) throw new NativeParseError(FORMAT$11, line, `${triplets.path}: ${text} names a node type that ${heterogeneous.path} does not count`);
+		relations.push({
+			head,
+			relation,
+			tail,
+			sources,
+			targets
+		});
+	}
+	relations.sort((left, right) => compare(left.head, right.head) || compare(left.relation, right.relation) || compare(left.tail, right.tail));
+	const listed = new Set(relations.map(({ head, relation, tail }) => `relations/${head}___${relation}___${tail}`));
+	for (const name of byName.keys()) {
+		const directory = name.slice(0, name.lastIndexOf("/"));
+		if (name.startsWith("relations/") && !listed.has(directory)) throw new NativeParseError(FORMAT$11, 1, `raw/${directory}/ is not one of the relations ${triplets.path} lists`);
+	}
+	for (const { head, relation, tail, sources, targets } of relations) {
+		const directory = `relations/${head}___${relation}___${tail}`;
+		readEdges(required$1(byName, `${directory}/edge`, root), required$1(byName, `${directory}/num-edge-list`, root), {
+			sources,
+			targets,
+			source: (node) => `${head}:${String(node)}`,
+			target: (node) => `${tail}:${String(node)}`
+		}, (edge) => {
+			edges.push(edge);
+		});
+	}
+	return {
+		nodes: nodeTypes.flatMap(({ type, count }) => Array.from({ length: count }, (_, node) => ({ id: `${type}:${String(node)}` }))),
+		edges
+	};
+}
+//#endregion
 //#region src/parsers/matrix-market.ts
 /** How many tokens an entry line of each field type holds: the coordinates, then the value's parts (none for a pattern, a real and an imaginary part for a complex value). */
 const tokensPerEntry = /* @__PURE__ */ new Map([
@@ -2978,9 +3194,9 @@ function parseNative(bytes, parser) {
 		pieces: decodePieces(bytes, parser)
 	}], parser);
 	if (parser.format === "hgb") throw new NativeParseError(parser.format, 1, "an HGB dataset is two files, nodes and links, which a recipe reads from a parts archive");
+	if (parser.format === "edge-list") return parseEdgeList(decodePieces(bytes, parser), parser);
 	const text = decode(bytes, parser);
 	if (parser.format === "geojson") return parseGeojson(text, parser);
-	if (parser.format === "edge-list") return parseEdgeList(text, parser);
 	if (parser.format === "matrix-market") return parseMatrixMarket(text);
 	if (parser.format === "gml") return parseGml(text);
 	if (parser.format === "ucinet-dl") return parseUcinetDl(text, parser);
@@ -2994,6 +3210,7 @@ function parseNative(bytes, parser) {
 	if (parser.format === "verolog-2019") return parseVerolog2019(text);
 	if (parser.format === "vrp-rep") return parseVrpRep(text);
 	if (parser.format === "hhcrsp") return parseHhcrsp(text);
+	if (parser.format === "ogb") throw new NativeParseError(parser.format, 1, "the format reads the several files a files archive selects, not one file");
 	return parsePajek(text);
 }
 /**
@@ -3019,6 +3236,20 @@ function parseNativeParts(parts, parser) {
 	}
 	throw new NativeParseError(parser.format, 1, `the ${parser.format} parser reads one file, not named parts`);
 }
+/**
+* Reads the several files of a multi-file format into the one native document they make together.
+* @param files - The files a `files` archive selects, each with its path in the archive, in path order.
+* @param parser - The recipe's parser, which must be a multi-file format.
+* @returns The native graph.
+* @throws NativeParseError when a file is not valid in the stated encoding or the files are not in the stated format, or when the parser reads one file and not several.
+*/
+function parseNativeFiles(files, parser) {
+	if (parser.format !== "ogb") throw new NativeParseError(parser.format, 1, "the format reads one file, not the several a files archive selects");
+	return parseOgb(files.map((file) => ({
+		path: file.path,
+		text: () => decodePieces(file.bytes, parser)
+	})));
+}
 //#endregion
 //#region src/node/bzip2.ts
 /** The four bytes every bzip2 stream starts with, as ASCII: `BZh` and the block size digit, `1` to `9`. */
@@ -4912,6 +5143,30 @@ function sheetToCsv(bytes, archive) {
 	return gridToCsv(read(bytes, archive.sheet));
 }
 /**
+* Unpacks downloaded bytes into every file a multi-file format's selector matches, gunzipping each when the layout's `inner` says so. The paths stay the archive's own, so a gunzipped `edge.csv.gz` keeps its name.
+* @param bytes - The downloaded bytes.
+* @param archive - The recipe's archive layout, which selects files with `files`.
+* @returns Each matching file, in path order.
+* @throws ArchiveError when the bytes, or a file `inner` gunzips, are not well-formed, or the selector matches no member.
+*/
+function unpackFiles(bytes, archive) {
+	const files = unpackMembers(bytes, {
+		kind: archive.kind,
+		members: archive.files
+	});
+	if (archive.inner === void 0) return files;
+	return files.map((file) => {
+		try {
+			return {
+				path: file.path,
+				bytes: gunzip(file.bytes)
+			};
+		} catch (error) {
+			throw new ArchiveError(`member ${file.path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+		}
+	});
+}
+/**
 * Gunzips bytes, rethrowing zlib's failure in the package's taxonomy.
 * @param bytes - Gzip data.
 * @returns The decompressed bytes.
@@ -5450,6 +5705,20 @@ async function runToNative(dataset, options) {
 			provenance: provenanceOf({ members: parts.map((part) => part.path) })
 		};
 	}
+	if ("files" in archive) {
+		const files = await step(entry.id, "extract", () => unpackFiles(bytes, archive));
+		return {
+			collection: false,
+			documents: [{
+				id: void 0,
+				native: {
+					...await step(entry.id, "parse", () => parseNativeFiles(files, recipe.parser)),
+					meta: metaOf(entry)
+				}
+			}],
+			provenance: provenanceOf({ members: files.map((file) => file.path) })
+		};
+	}
 	const unpacked = await step(entry.id, "extract", () => unpack(bytes, archive));
 	const parsed = await step(entry.id, "parse", () => parseNative(unpacked.bytes, recipe.parser));
 	return {

package/dist-cli/keepset.mjs

@@ -4,7 +4,7 @@ import { KeepsetError, NAME_SEPARATOR, countTarget, getDataset, listDatasets, li
 import { fetchDataset, roundTripDataset } from "keepset/node";
 import { parseArgs } from "node:util";
 //#region package.json
-var version = "0.38.0";
+var version = "0.39.0";
 //#endregion
 //#region cli/run.ts
 /**
@@ -136,7 +136,7 @@ function formatShow(dataset) {
 	else {
 		const { archive } = recipe;
 		const innerText = "inner" in archive && archive.inner !== void 0 ? `, inner ${archive.inner.kind}${"member" in archive.inner ? `, member ${selectorText(archive.inner.member)}` : ""}` : "";
-		const memberText = "member" in archive ? `, member ${selectorText(archive.member)}${innerText}` : "members" in archive ? `, members ${selectorText(archive.members)}` : "parts" in archive ? `, parts ${archive.parts.map((part) => `${part.name} from ${selectorText(part.member)}`).join(", ")}` : "";
+		const memberText = "member" in archive ? `, member ${selectorText(archive.member)}${innerText}` : "members" in archive ? `, members ${selectorText(archive.members)}` : "parts" in archive ? `, parts ${archive.parts.map((part) => `${part.name} from ${selectorText(part.member)}`).join(", ")}` : "files" in archive ? `, files ${selectorText(archive.files)}${innerText}` : "";
 		const { format, ...options } = recipe.parser;
 		lines.push(`  source: [${String(recipe.source)}]`, `  archive: ${archive.kind}${memberText}`, `  parser: ${format} ${JSON.stringify(options)}`);
 	}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "keepset",
   "description": "Library, CLI and statically generated catalogue for dataset fetch-and-normalise recipes",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "bin": {
     "keepset": "./dist-cli/keepset.mjs"
   },