@graphty/graph-io 0.0.0 → 0.2.1

package/src/common/text.ts

@@ -0,0 +1,294 @@
+/**
+ * The fixed lexical grammar of design section 5.1 for untyped text sources (CSV cells, GML
+ * values, DOT strings, Pajek tokens), reproduced from the core's reference implementation so the
+ * two agree (invariant I15). Text importers parse each cell with parseTextCell() and push the JS
+ * value; the sink's per-column inference then widens `bool -> i32 -> f64 -> string` and never per
+ * cell, so a column that saw `1` and then `"01"` becomes string for all rows.
+ *
+ * - `bool` is exactly `true` / `false` (case-sensitive);
+ * - `i32` is `/^-?(0|[1-9][0-9]*)$/` within `[-2^31, 2^31)`; `0` / `1` are i32, never bool;
+ * - `f64` is a decimal or exponent literal accepted by `Number()` that is not empty, not
+ *   whitespace, not `Infinity` / `NaN`, not a hex / octal / binary form, has no leading zeros in
+ *   its integer part, and whose value is finite (an integer literal outside i32 range is f64);
+ * - everything else is `string`.
+ */
+
+import { type ColumnHandle, GraphFormatError, type GraphSink, INVALID_INDEX } from "@graphty/graph-format";
+
+import { type ImportReportBuilder } from "./report.js";
+
+const I32_TEXT = /^-?(0|[1-9][0-9]*)$/;
+const F64_TEXT = /^[+-]?((0|[1-9][0-9]*)(\.[0-9]*)?|\.[0-9]+)([eE][+-]?[0-9]+)?$/;
+const I32_MIN = -2147483648;
+const I32_MAX = 2147483647;
+
+/**
+ * The dtype a text cell parses as under the design section 5.1 grammar.
+ * Consumed by the per-format importers and exporters under src/formats.
+ * @public
+ */
+export type TextDtype = "bool" | "i32" | "f64" | "string";
+
+/**
+ * Classify one text cell by the fixed grammar.
+ * @param text - the cell text, exactly as read (no trimming)
+ * @returns bool, i32, f64 or string
+ */
+export function inferTextDtype(text: string): TextDtype {
+    if (text === "true" || text === "false") {
+        return "bool";
+    }
+    if (I32_TEXT.test(text)) {
+        const n = Number(text);
+        if (n >= I32_MIN && n <= I32_MAX) {
+            return "i32";
+        }
+        return Number.isFinite(n) ? "f64" : "string";
+    }
+    if (F64_TEXT.test(text) && Number.isFinite(Number(text))) {
+        return "f64";
+    }
+    return "string";
+}
+
+/**
+ * Parse one text cell into the JS value its grammar class implies: a boolean for bool, a number for
+ * i32 / f64, the text itself for string. The sink infers the column dtype from the value.
+ * @param text - the cell text, exactly as read
+ * @returns the value
+ */
+export function parseTextCell(text: string): boolean | number | string {
+    switch (inferTextDtype(text)) {
+        case "bool":
+            return text === "true";
+        case "i32":
+        case "f64":
+            return Number(text);
+        case "string":
+            return text;
+        default:
+            return text;
+    }
+}
+
+/**
+ * Whether a text cell is a number under the f64 grammar (an i32 or f64 literal).
+ * @param text - the cell text
+ * @returns true when parseTextCell(text) returns a number
+ */
+export function isNumericText(text: string): boolean {
+    const dtype = inferTextDtype(text);
+    return dtype === "i32" || dtype === "f64";
+}
+
+/**
+ * Whether a numeric cell text is the canonical spelling of its value (`String(value) === text`),
+ * so that the sink's own re-formatting of the value would reproduce it.
+ * @param text - the cell text
+ * @param value - the parsed value
+ * @returns true when the lexical form survives a widening to string
+ */
+function isCanonicalNumberText(text: string, value: number): boolean {
+    return String(value) === text;
+}
+
+/**
+ * The widening rank of a text dtype in the design section 5.1 order.
+ * @param dtype - the text dtype
+ * @returns 0 for bool, 1 for i32, 2 for f64, 3 for string
+ */
+function textDtypeRank(dtype: TextDtype): number {
+    switch (dtype) {
+        case "bool":
+            return 0;
+        case "i32":
+            return 1;
+        case "f64":
+            return 2;
+        case "string":
+            return 3;
+        default: {
+            const name: string = dtype;
+            throw new GraphFormatError("E_UNSUPPORTED", `unknown text dtype ${name}`, { dtype: name });
+        }
+    }
+}
+
+/**
+ * The inferred-column writer of the untyped text formats (CSV, DOT, Pajek; design section 5.1):
+ * parses every cell by the fixed grammar and pushes the scalar, and keeps the COLUMN's dtype the
+ * one the grammar implies rather than the one the values happen to imply:
+ *
+ * - a column whose cells are all `2.0`-style f64 text is widened to f64 through the sink's
+ *   widening call even though every value is integral (the values alone would infer i32);
+ * - a numeric cell whose text is not the canonical spelling of its value (`1e5`, `-0`, `1.0`) is
+ *   remembered, and when a later cell widens the column to string the original texts are written
+ *   back, so the lexical form is never rewritten by the widening.
+ *
+ * A sink without the optional widening call keeps the value-inferred dtype and the writer records
+ * one W_WIDENING_UNSUPPORTED warning per column.
+ * Consumed by the per-format importers under src/formats.
+ * @public
+ */
+export class TextCellWriter {
+    /** The column name in the sink. */
+    readonly name: string;
+
+    private readonly domain: "node" | "edge";
+
+    private readonly sink: GraphSink;
+
+    private readonly report: ImportReportBuilder;
+
+    private handle: ColumnHandle = INVALID_INDEX as ColumnHandle;
+
+    /** The widest text dtype seen (the column's dtype under the 5.1 grammar). */
+    private textDtype: TextDtype | null = null;
+
+    /** The widest dtype the pushed values imply (what the sink inferred on its own). */
+    private valueDtype: TextDtype | null = null;
+
+    private readonly keptRows: number[] = [];
+
+    private readonly keptTexts: string[] = [];
+
+    /**
+     * Create a writer; the column is declared by the sink's inference on the first write.
+     * @param name - the column name
+     * @param domain - node or edge
+     * @param sink - the sink
+     * @param report - the report the widening warning is recorded in
+     */
+    constructor(name: string, domain: "node" | "edge", sink: GraphSink, report: ImportReportBuilder) {
+        this.name = name;
+        this.domain = domain;
+        this.sink = sink;
+        this.report = report;
+    }
+
+    /**
+     * The column handle once the first cell was written.
+     * @returns the handle, or INVALID_INDEX before the first write
+     */
+    get column(): ColumnHandle {
+        return this.handle;
+    }
+
+    /**
+     * Write one cell text.
+     * @param row - the node or edge index
+     * @param text - the cell text, exactly as read
+     */
+    write(row: number, text: string): void {
+        const kind = inferTextDtype(text);
+        const value = parseTextCell(text);
+        const wasString = this.textDtype === "string";
+        const textDtype =
+            this.textDtype === null || textDtypeRank(kind) > textDtypeRank(this.textDtype) ? kind : this.textDtype;
+        // a string column keeps every cell's lexical form; a numeric text is never re-spelled. The
+        // sink may refuse the value (a declared column of another dtype): the state advances only
+        // once the cell is written, so a refused cell leaves the writer as it was.
+        this.set(row, textDtype === "string" ? text : value);
+        this.textDtype = textDtype;
+        const valueKind = kindOfValue(value);
+        if (this.valueDtype === null || textDtypeRank(valueKind) > textDtypeRank(this.valueDtype)) {
+            this.valueDtype = valueKind;
+        }
+        if (this.textDtype === "string") {
+            if (!wasString && this.keptRows.length > 0) {
+                // the sink just widened the column to string from the values; restore the texts
+                // whose lexical form the values did not carry
+                for (let i = 0; i < this.keptRows.length; i++) {
+                    this.set(this.keptRows[i], this.keptTexts[i]);
+                }
+                this.keptRows.length = 0;
+                this.keptTexts.length = 0;
+            }
+            return;
+        }
+        if (typeof value === "number" && !isCanonicalNumberText(text, value)) {
+            this.keptRows.push(row);
+            this.keptTexts.push(text);
+        }
+        if (this.textDtype === "f64" && this.valueDtype !== "f64") {
+            this.widen("f64");
+        }
+    }
+
+    /**
+     * Write a value (the parsed scalar, or a text into a widened column).
+     * @param row - the row
+     * @param value - the value
+     */
+    private set(row: number, value: unknown): void {
+        if (this.handle === INVALID_INDEX) {
+            if (this.domain === "node") {
+                this.sink.setNodeValue(this.name, row, value);
+                this.handle = this.sink.nodeColumn(this.name);
+            } else {
+                this.sink.setEdgeValue(this.name, row, value);
+                this.handle = this.sink.edgeColumn(this.name);
+            }
+            return;
+        }
+        if (this.domain === "node") {
+            this.sink.setNodeValue(this.handle, row, value);
+        } else {
+            this.sink.setEdgeValue(this.handle, row, value);
+        }
+    }
+
+    /**
+     * Widen the column to the dtype the text grammar implies, through the sink's optional call.
+     * @param dtype - the dtype
+     */
+    private widen(dtype: "f64"): void {
+        const { sink } = this;
+        const supported =
+            this.domain === "node" ? sink.widenNodeColumn !== undefined : sink.widenEdgeColumn !== undefined;
+        if (!supported) {
+            this.report.warnOnce(
+                "coercion",
+                WIDENING_UNSUPPORTED_CODE,
+                `column "${this.name}" holds ${dtype} text but the sink cannot widen an inferred column; it keeps the value-inferred dtype`,
+                { element: this.name },
+            );
+            this.valueDtype = dtype;
+            return;
+        }
+        try {
+            if (this.domain === "node") {
+                sink.widenNodeColumn?.(this.handle, dtype);
+            } else {
+                sink.widenEdgeColumn?.(this.handle, dtype);
+            }
+            this.valueDtype = dtype;
+        } catch (err) {
+            if (!(err instanceof GraphFormatError) || err.code !== "E_COLUMN_TYPE") {
+                throw err;
+            }
+            // a caller's declared column of the name: its dtype stands
+            this.valueDtype = dtype;
+        }
+    }
+}
+
+/** Issue code: the sink has no widening call, so a text column keeps the dtype its values imply. */
+export const WIDENING_UNSUPPORTED_CODE = "W_WIDENING_UNSUPPORTED";
+
+/**
+ * The text dtype a parsed cell value implies on its own (what the sink's inference sees).
+ * @param value - the parsed value
+ * @returns the dtype
+ */
+function kindOfValue(value: boolean | number | string): TextDtype {
+    if (typeof value === "boolean") {
+        return "bool";
+    }
+    if (typeof value === "string") {
+        return "string";
+    }
+    return Number.isInteger(value) && value >= -2147483648 && value <= 2147483647 && !Object.is(value, -0)
+        ? "i32"
+        : "f64";
+}

package/src/common/weights.ts

@@ -0,0 +1,202 @@
+/**
+ * Weight resolution shared by every importer (design sections 3.7 and 8.4): which source field is
+ * THE weight (`weightFrom`, per-format default, null = unweighted), how its text or JSON value
+ * becomes the number passed to `addEdge`, and the E_INVALID_WEIGHT boundary.
+ *
+ * An edge whose weight field is absent or blank is pushed WITHOUT a weight argument, never with an
+ * explicit 1: the builder's weightSet bitmap then records that the weight was defaulted, and the
+ * exporter re-emits no weight for it (decision D-WSET). NaN and non-numeric text are
+ * E_INVALID_WEIGHT before the sink is touched, so the importer records the issue and skips the edge
+ * with the sink unchanged; Infinity and negative values are legal weights (design section 3.7).
+ */
+
+import { type Column, GraphFormatError, type GraphSnapshot } from "@graphty/graph-format";
+
+import { parseDecimalText } from "./declared-types.js";
+import { formatF32, formatF64, formatInteger } from "./format.js";
+
+/** The weight of an edge added without one (design section 3.7). */
+export const DEFAULT_WEIGHT = 1;
+
+/**
+ * Whether a source field is the weight field under the resolved `weightFrom` option.
+ * @param name - the field name (attribute title, CSV header, JSON key)
+ * @param weightFrom - the resolved option; null means unweighted
+ * @returns true when the field is THE weight
+ */
+export function isWeightField(name: string, weightFrom: string | null): boolean {
+    return weightFrom !== null && name === weightFrom;
+}
+
+/**
+ * The weight argument of addEdge from a text cell: undefined for a blank cell (the weight is
+ * omitted), the number otherwise.
+ * @param text - the cell text
+ * @returns the weight, or undefined when blank; E_INVALID_WEIGHT for NaN or non-numeric text
+ */
+export function parseWeightText(text: string): number | undefined {
+    const trimmed = text.trim();
+    if (trimmed.length === 0) {
+        return undefined;
+    }
+    let value: number;
+    try {
+        value = parseDecimalText(trimmed);
+    } catch (err) {
+        throw invalidWeight(text, err);
+    }
+    if (Number.isNaN(value)) {
+        throw invalidWeight(text, null);
+    }
+    return value;
+}
+
+/**
+ * The weight argument of addEdge from a typed value (JSON, a record field): undefined for null /
+ * undefined, the number for a finite or infinite number, the parsed number for numeric text.
+ * @param value - the field value
+ * @returns the weight, or undefined when absent; E_INVALID_WEIGHT for NaN, a boolean, an object or non-numeric text
+ */
+export function weightFromValue(value: unknown): number | undefined {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value === "number") {
+        if (Number.isNaN(value)) {
+            throw invalidWeight(value, null);
+        }
+        return value;
+    }
+    if (typeof value === "string") {
+        return parseWeightText(value);
+    }
+    throw invalidWeight(value, null);
+}
+
+/**
+ * The E_INVALID_WEIGHT error of a rejected value.
+ * @param value - the rejected value
+ * @param cause - the parse error, or null
+ * @returns the error
+ */
+function invalidWeight(value: unknown, cause: unknown): GraphFormatError {
+    let shown: string;
+    switch (typeof value) {
+        case "string":
+            shown = JSON.stringify(value);
+            break;
+        case "number":
+            shown = String(value);
+            break;
+        default:
+            shown = typeof value;
+    }
+    return new GraphFormatError("E_INVALID_WEIGHT", `invalid edge weight ${shown}`, {
+        value: typeof value === "object" ? typeof value : value,
+        cause: cause instanceof Error ? cause.message : null,
+    });
+}
+
+// ============================================================ the exporter side
+
+/**
+ * The explicit weights of a snapshot for exporters (design sections 3.7 and 8.5): the weight
+ * role column when present (its validity says which edges had an explicit weight, its dtype how
+ * the value is written), else `edgeList().weights` as f32 for every edge of a weighted snapshot;
+ * nothing for an unweighted one. One implementation for every exporter.
+ * Consumed by the per-format exporters under src/formats.
+ * @public
+ */
+export interface ExplicitWeights {
+    /** Whether any edge can have an explicit weight (the snapshot is weighted). */
+    readonly weighted: boolean;
+    /** The dtype the values are read from: the shadow column's, or f32 for the arc array. */
+    readonly dtype: "f32" | "f64";
+    /**
+     * Whether an edge's weight was explicit in the source.
+     * @param e - the logical edge index
+     * @returns true when the exporter must write it
+     */
+    isExplicit(e: number): boolean;
+    /**
+     * The weight value of an edge (meaningful when explicit).
+     * @param e - the logical edge index
+     * @returns the value
+     */
+    value(e: number): number;
+    /**
+     * The weight text of an edge: the shortest round-tripping decimal for its dtype, or the
+     * integer digits when `integral` is requested and the value is an integer; null when the
+     * weight was defaulted.
+     * @param e - the logical edge index
+     * @param integral - write an integral value without a decimal part (formats declaring an int weight)
+     * @returns the text, or null
+     */
+    text(e: number, integral?: boolean): string | null;
+}
+
+/** The dtypes a weight role column may have (an integer column declared by a caller included). */
+const NUMERIC_DTYPES: ReadonlySet<string> = new Set(["f32", "f64", "i32", "u32", "u8"]);
+
+/**
+ * The shortest round-tripping text of a weight by the shadow column's dtype.
+ * @param dtype - the shadow column's dtype
+ * @returns the formatter
+ */
+function weightFormatter(dtype: string): (value: number) => string {
+    switch (dtype) {
+        case "f32":
+            return formatF32;
+        case "f64":
+            return formatF64;
+        default:
+            return formatInteger;
+    }
+}
+
+/**
+ * Build the explicit-weight view of a snapshot.
+ * @param snapshot - the snapshot
+ * @returns the view
+ */
+export function explicitWeights(snapshot: GraphSnapshot): ExplicitWeights {
+    const shadowColumn = snapshot.edges.byRole("weight");
+    const shadow: Column | null = shadowColumn !== null && NUMERIC_DTYPES.has(shadowColumn.dtype) ? shadowColumn : null;
+    if (shadow !== null) {
+        const dtype = shadow.dtype === "f32" ? "f32" : "f64";
+        const format = weightFormatter(shadow.dtype);
+        return {
+            weighted: true,
+            dtype,
+            isExplicit: (e: number): boolean => shadow.isSet(e),
+            value: (e: number): number => shadow.value(e) as number,
+            text: (e: number, integral = false): string | null => {
+                if (!shadow.isSet(e)) {
+                    return null;
+                }
+                const value = shadow.value(e) as number;
+                return integral && Number.isInteger(value) ? formatInteger(value) : format(value);
+            },
+        };
+    }
+    const { weights } = snapshot.edgeList();
+    if (weights === null || !snapshot.flags.weighted) {
+        return {
+            weighted: false,
+            dtype: "f32",
+            isExplicit: (): boolean => false,
+            value: (): number => DEFAULT_WEIGHT,
+            text: (): string | null => null,
+        };
+    }
+    return {
+        weighted: true,
+        dtype: "f32",
+        isExplicit: (): boolean => true,
+        value: (e: number): number => weights[e],
+        text: (e: number, integral = false): string => {
+            const value = weights[e];
+            return integral && Number.isInteger(value) ? formatInteger(value) : formatF32(value);
+        },
+    };
+}

package/src/common/writer.ts

@@ -0,0 +1,123 @@
+/**
+ * The output side of the exporter contract (design sections 8.5 and 12.4): an exporter produces
+ * its document as a sequence of text parts (a sync or async generator of strings, one per line or
+ * element); these helpers turn that sequence into `export()`'s `AsyncIterable<Uint8Array>` of
+ * UTF-8 chunks of a bounded size, into `exportToString()`'s one string, or into a
+ * `ReadableStream<Uint8Array>` for a caller that wants a stream.
+ */
+
+/**
+ * Text parts an exporter produces.
+ * Consumed by the per-format importers and exporters under src/formats.
+ * @public
+ */
+export type TextParts = Iterable<string> | AsyncIterable<string>;
+
+/** The target size of one encoded chunk; parts are coalesced up to it and never split. */
+export const DEFAULT_CHUNK_BYTES = 64 * 1024;
+
+/**
+ * Encode text parts as UTF-8 chunks of about `chunkBytes` each. Small parts are coalesced; a part
+ * larger than the chunk size is emitted whole. The last chunk may be short; nothing is emitted for
+ * an empty document.
+ * @param parts - the text parts
+ * @param chunkBytes - the target chunk size in bytes
+ * @yields UTF-8 chunks
+ * @returns nothing
+ */
+export async function* encodeChunks(
+    parts: TextParts,
+    chunkBytes: number = DEFAULT_CHUNK_BYTES,
+): AsyncGenerator<Uint8Array, void, undefined> {
+    const encoder = new TextEncoder();
+    let pending: string[] = [];
+    let pendingUnits = 0;
+    for await (const part of parts) {
+        if (part.length === 0) {
+            continue;
+        }
+        pending.push(part);
+        pendingUnits += part.length;
+        // UTF-16 code units are a lower bound on the UTF-8 byte count; flush when the lower bound reaches the target
+        if (pendingUnits >= chunkBytes) {
+            yield encoder.encode(pending.length === 1 ? pending[0] : pending.join(""));
+            pending = [];
+            pendingUnits = 0;
+        }
+    }
+    if (pending.length > 0) {
+        yield encoder.encode(pending.length === 1 ? pending[0] : pending.join(""));
+    }
+}
+
+/**
+ * Join text parts into one string.
+ * @param parts - the text parts
+ * @returns the whole document
+ */
+export async function joinText(parts: TextParts): Promise<string> {
+    const collected: string[] = [];
+    for await (const part of parts) {
+        collected.push(part);
+    }
+    return collected.join("");
+}
+
+/**
+ * Decode UTF-8 chunks back into one string (for tests and for callers holding an export() result).
+ * @param chunks - the chunks
+ * @returns the decoded text
+ */
+export async function decodeChunks(chunks: AsyncIterable<Uint8Array>): Promise<string> {
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    const parts: string[] = [];
+    for await (const chunk of chunks) {
+        parts.push(decoder.decode(chunk, { stream: true }));
+    }
+    parts.push(decoder.decode());
+    return parts.join("");
+}
+
+/**
+ * Collect UTF-8 chunks into one Uint8Array.
+ * @param chunks - the chunks
+ * @returns the concatenated bytes
+ */
+export async function collectBytes(chunks: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
+    const parts: Uint8Array[] = [];
+    let total = 0;
+    for await (const chunk of chunks) {
+        parts.push(chunk);
+        total += chunk.byteLength;
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.byteLength;
+    }
+    return out;
+}
+
+/**
+ * Wrap an async iterable of chunks as a ReadableStream, pulling one chunk per read and cancelling
+ * the iterable when the stream is cancelled.
+ * @param chunks - the chunks
+ * @returns a byte stream
+ */
+export function toReadableStream(chunks: AsyncIterable<Uint8Array>): ReadableStream<Uint8Array> {
+    const iterator = chunks[Symbol.asyncIterator]();
+    return new ReadableStream<Uint8Array>({
+        async pull(controller): Promise<void> {
+            const { done, value } = await iterator.next();
+            if (done) {
+                controller.close();
+                return;
+            }
+            controller.enqueue(value);
+        },
+        async cancel(): Promise<void> {
+            await iterator.return?.(undefined);
+        },
+    });
+}