@graphty/graph-io 0.3.24 → 0.3.26

package/src/common/temporal.ts

@@ -12,17 +12,23 @@
 
 import { type ColumnDecl, type ColumnRole, GraphFormatError } from "@graphty/graph-format";
 
-/** The temporal kinds a declared type can map to; each fixes the parse grammar and the canonical text. */
+/**
+ * The temporal kinds a declared type can map to; each fixes the parse grammar and the canonical text.
+ * @category Plugin helpers
+ */
 export type TemporalKind = "date" | "dateTime" | "localDateTime" | "time" | "localTime";
 
 /**
  * The GEXF `timeformat` values (design section 5.9).
- * Consumed by the per-format importers and exporters under src/formats.
  * @public
+ * @category Plugin helpers
  */
 export type TimeFormat = "integer" | "double" | "date" | "dateTime";
 
-/** A parsed temporal value: the number stored in the column and the source text when it must be kept. */
+/**
+ * A parsed temporal value: the number stored in the column and the source text when it must be kept.
+ * @category Plugin helpers
+ */
 export interface TemporalValue {
     /** Epoch milliseconds (date, dateTime, localDateTime), milliseconds since midnight (time, localTime), or the raw number. */
     readonly value: number;
@@ -30,10 +36,16 @@ export interface TemporalValue {
     readonly text: string | null;
 }
 
-/** The role of a companion text column. */
+/**
+ * The role of a companion text column.
+ * @category Plugin helpers
+ */
 export const TIME_TEXT_ROLE: ColumnRole = "timeText";
 
-/** The suffix of a companion text column's name. */
+/**
+ * The suffix of a companion text column's name.
+ * @category Plugin helpers
+ */
 export const TIME_TEXT_SUFFIX = ".text";
 
 const DATE_TIME =
@@ -49,6 +61,7 @@ const MS_PER_DAY = 86_400_000;
  * @param text - the source text (already trimmed)
  * @param kind - the temporal kind
  * @returns the value and, when the canonical form differs, the source text; E_COLUMN_TYPE when the text is not of the kind
+ * @category Plugin helpers
  */
 export function parseTemporal(text: string, kind: TemporalKind): TemporalValue {
     let value: number;
@@ -79,6 +92,7 @@ export function parseTemporal(text: string, kind: TemporalKind): TemporalValue {
  * @param text - the source text
  * @param timeFormat - the graph's timeformat, or null when the file declares none
  * @returns the value and the source text when it must be kept
+ * @category Plugin helpers
  */
 export function parseTimeText(text: string, timeFormat: TimeFormat | null): TemporalValue {
     const trimmed = text.trim();
@@ -105,6 +119,7 @@ export function parseTimeText(text: string, timeFormat: TimeFormat | null): Temp
  * @param kind - the temporal kind
  * @returns the canonical text: `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SS[.mmm]Z`, `YYYY-MM-DDTHH:MM:SS[.mmm]`,
  * `HH:MM:SS[.mmm]Z` or `HH:MM:SS[.mmm]`
+ * @category Plugin helpers
  */
 export function formatTemporal(value: number, kind: TemporalKind): string {
     switch (kind) {
@@ -141,6 +156,7 @@ export function formatTemporal(value: number, kind: TemporalKind): string {
  * @param value - the value as stored
  * @param timeFormat - the graph's timeformat, or null for a file that declares none (double)
  * @returns the text
+ * @category Plugin helpers
  */
 export function formatTimeValue(value: number, timeFormat: TimeFormat | null): string {
     switch (timeFormat) {
@@ -163,6 +179,7 @@ export function formatTimeValue(value: number, timeFormat: TimeFormat | null): s
  * The declaration of the companion text column of a temporal column (design section 5.1).
  * @param column - the temporal column's name
  * @returns a string column named `<column>.text` with role timeText and `extra.for` naming the column
+ * @category Plugin helpers
  */
 export function timeTextCompanion(column: string): ColumnDecl {
     return {

package/src/common/text.ts

@@ -15,6 +15,7 @@
 
 import { type ColumnHandle, GraphFormatError, type GraphSink, INVALID_INDEX } from "@graphty/graph-format";
 
+import { PRECISION_CODE } from "./codes.js";
 import { type ImportReportBuilder } from "./report.js";
 
 const I32_TEXT = /^-?(0|[1-9][0-9]*)$/;
@@ -23,16 +24,30 @@ 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.
+ * The dtype a text cell parses as under the fixed text grammar.
  * @public
+ * @category Plugin helpers
  */
 export type TextDtype = "bool" | "i32" | "f64" | "string";
 
+/**
+ * A digit string without its trailing zeros (`"1200"` becomes `"12"`).
+ * @param digits - the digits
+ * @returns the digits up to the last one that is not 0
+ */
+export function trimTrailingZeros(digits: string): string {
+    let end = digits.length;
+    while (end > 0 && digits[end - 1] === "0") {
+        end--;
+    }
+    return digits.slice(0, end);
+}
+
 /**
  * Classify one text cell by the fixed grammar.
  * @param text - the cell text, exactly as read (no trimming)
  * @returns bool, i32, f64 or string
+ * @category Plugin helpers
  */
 export function inferTextDtype(text: string): TextDtype {
     if (text === "true" || text === "false") {
@@ -56,6 +71,7 @@ export function inferTextDtype(text: string): TextDtype {
  * 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
+ * @category Plugin helpers
  */
 export function parseTextCell(text: string): boolean | number | string {
     switch (inferTextDtype(text)) {
@@ -75,6 +91,7 @@ export function parseTextCell(text: string): boolean | number | string {
  * 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
+ * @category Plugin helpers
  */
 export function isNumericText(text: string): boolean {
     const dtype = inferTextDtype(text);
@@ -115,20 +132,23 @@ function textDtypeRank(dtype: TextDtype): number {
 }
 
 /**
- * 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:
+ * Writes the cells of one attribute of a text format whose values carry no type (CSV, DOT, Pajek):
+ * you hand it each cell's text and it stores a number, a boolean or text, choosing one type for the
+ * whole attribute. A column of `2.0`, `3.5` stays a number column with decimals even though `2.0`
+ * alone looks like an integer, and once one cell turns out to be text, earlier cells such as `1e5`
+ * are kept as written instead of as `100000`. Create one writer per attribute name and per kind
+ * ("node" or "edge"), and call `write(index, text)` with the node or edge index the sink gave you:
  *
- * - 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.
+ * ```ts
+ * const color = new TextCellWriter("color", "node", sink, report);
+ * color.write(sink.addNode("a"), "red");
+ * ```
  *
- * 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.
+ * A sink that cannot change a column's type after the fact (one of your own without
+ * `widenNodeColumn` / `widenEdgeColumn`) keeps the type the first values implied, with one W_WIDENING_UNSUPPORTED warning
+ * per attribute.
  * @public
+ * @category Writing a format
  */
 export class TextCellWriter {
     /** The column name in the sink. */
@@ -153,11 +173,11 @@ export class TextCellWriter {
     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
+     * Create a writer. The attribute is added to the sink on the first write.
+     * @param name - the attribute name
+     * @param domain - "node" for a node attribute, "edge" for an edge attribute
+     * @param sink - the sink the importer fills
+     * @param report - the import report, for warnings about the values
      */
     constructor(name: string, domain: "node" | "edge", sink: GraphSink, report: ImportReportBuilder) {
         this.name = name;
@@ -167,7 +187,7 @@ export class TextCellWriter {
     }
 
     /**
-     * The column handle once the first cell was written.
+     * The sink's handle of the attribute's column, for reading it back.
      * @returns the handle, or INVALID_INDEX before the first write
      */
     get column(): ColumnHandle {
@@ -175,13 +195,28 @@ export class TextCellWriter {
     }
 
     /**
-     * Write one cell text.
-     * @param row - the node or edge index
-     * @param text - the cell text, exactly as read
+     * Write one cell.
+     * @param row - the node or edge index, as the sink's addNode() or addEdge() returned it
+     * @param text - the cell text, exactly as read from the file
      */
     write(row: number, text: string): void {
         const kind = inferTextDtype(text);
         const value = parseTextCell(text);
+        if (
+            typeof value === "number" &&
+            !Number.isSafeInteger(value) &&
+            I32_TEXT.test(text) &&
+            BigInt(text) !== BigInt(value)
+        ) {
+            // an integer beyond 2^53 is stored as the nearest double; say so once per column
+            this.report.warnOnce(
+                "precision",
+                PRECISION_CODE,
+                `${this.domain} column "${this.name}": integers beyond 2^53 are stored as the nearest double (first: ${text})`,
+                { element: this.name },
+                `${PRECISION_CODE}:${this.domain}:${this.name}`,
+            );
+        }
         const wasString = this.textDtype === "string";
         const textDtype =
             this.textDtype === null || textDtypeRank(kind) > textDtypeRank(this.textDtype) ? kind : this.textDtype;
@@ -273,7 +308,11 @@ export class TextCellWriter {
     }
 }
 
-/** Issue code: the sink has no widening call, so a text column keeps the dtype its values imply. */
+/**
+ * Your graph builder cannot change an attribute's type after its first value, so a text column keeps the type of its
+ * first values.
+ * @category Issue and loss codes
+ */
 export const WIDENING_UNSUPPORTED_CODE = "W_WIDENING_UNSUPPORTED";
 
 /**

package/src/common/weights.ts

@@ -12,10 +12,15 @@
 
 import { type Column, GraphFormatError, type GraphSnapshot } from "@graphty/graph-format";
 
+import { PRECISION_CODE } from "./codes.js";
 import { parseDecimalText } from "./declared-types.js";
 import { formatF32, formatF64, formatInteger } from "./format.js";
+import { type ImportReportBuilder } from "./report.js";
 
-/** The weight of an edge added without one (design section 3.7). */
+/**
+ * The weight of an edge added without one (design section 3.7).
+ * @category Plugin helpers
+ */
 export const DEFAULT_WEIGHT = 1;
 
 /**
@@ -23,6 +28,7 @@ export const DEFAULT_WEIGHT = 1;
  * @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
+ * @category Plugin helpers
  */
 export function isWeightField(name: string, weightFrom: string | null): boolean {
     return weightFrom !== null && name === weightFrom;
@@ -32,9 +38,12 @@ export function isWeightField(name: string, weightFrom: string | null): boolean
  * 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
+ * @param report - the import report; when given, an integer beyond 2^53 that the nearest double
+ * changes is reported once as W_PRECISION
  * @returns the weight, or undefined when blank; E_INVALID_WEIGHT for NaN or non-numeric text
+ * @category Writing a format
  */
-export function parseWeightText(text: string): number | undefined {
+export function parseWeightText(text: string, report?: ImportReportBuilder): number | undefined {
     const trimmed = text.trim();
     if (trimmed.length === 0) {
         return undefined;
@@ -48,14 +57,42 @@ export function parseWeightText(text: string): number | undefined {
     if (Number.isNaN(value)) {
         throw invalidWeight(text, null);
     }
+    if (report !== undefined) {
+        reportWeightPrecision(trimmed, value, report);
+    }
     return value;
 }
 
+/**
+ * Report once (W_PRECISION) an integer weight beyond 2^53 that the nearest double changes, which
+ * the weights and the exact `graphty.weight` column would otherwise hold silently.
+ * @param text - the weight as written in the file
+ * @param value - the number it was read as
+ * @param report - the import report
+ */
+export function reportWeightPrecision(text: string, value: number, report: ImportReportBuilder): void {
+    if (
+        !Number.isSafeInteger(value) &&
+        Number.isFinite(value) &&
+        /^[+-]?\d+$/.test(text) &&
+        BigInt(text) !== BigInt(value)
+    ) {
+        report.warnOnce(
+            "precision",
+            PRECISION_CODE,
+            `edge weights: integers beyond 2^53 are stored as the nearest double (first: ${text})`,
+            undefined,
+            `${PRECISION_CODE}:edge weight`,
+        );
+    }
+}
+
 /**
  * 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
+ * @category Plugin helpers
  */
 export function weightFromValue(value: unknown): number | undefined {
     if (value === undefined || value === null) {
@@ -100,12 +137,12 @@ function invalidWeight(value: unknown, cause: unknown): GraphFormatError {
 // ============================================================ the exporter side
 
 /**
- * The explicit weights of a snapshot for exporters (design sections 3.7 and 8.5): the weight
+ * The explicit weights of a snapshot for exporters: 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
+ * @category Plugin helpers
  */
 export interface ExplicitWeights {
     /** Whether any edge can have an explicit weight (the snapshot is weighted). */
@@ -161,6 +198,7 @@ function weightFormatter(dtype: string): (value: number) => string {
  * Build the explicit-weight view of a snapshot.
  * @param snapshot - the snapshot
  * @returns the view
+ * @category Writing a format
  */
 export function explicitWeights(snapshot: GraphSnapshot): ExplicitWeights {
     const shadowColumn = snapshot.edges.byRole("weight");
@@ -209,3 +247,35 @@ export function explicitWeights(snapshot: GraphSnapshot): ExplicitWeights {
         },
     };
 }
+
+/**
+ * The weight of every edge, in edge order (`weights[e]` is edge `e`'s weight), exactly as the file
+ * wrote it, or null for a graph without weights. `snapshot.edgeList().weights` holds the same
+ * weights as 32-bit floats, in which 0.1 reads back as 0.10000000149011612; this reads the exact
+ * values the import also kept. An edge without a weight of its own has the weight 1.
+ * @example
+ * ```ts
+ * const { snapshot } = await importGraph("source,target,weight\na,b,0.1\n", { format: "csv" });
+ * edgeWeights(snapshot); // Float64Array [ 0.1 ]
+ * ```
+ * @param snapshot - the graph
+ * @returns one weight per edge, or null when the graph has no weights
+ * @category Loading
+ */
+export function edgeWeights(snapshot: GraphSnapshot): Float64Array | null {
+    const { weights } = snapshot.edgeList();
+    if (weights === null) {
+        return null;
+    }
+    const out = Float64Array.from(weights);
+    const exact = snapshot.edges.byRole("weight");
+    if (exact !== null) {
+        for (let e = 0; e < out.length; e++) {
+            const v = exact.value(e);
+            if (typeof v === "number") {
+                out[e] = v;
+            }
+        }
+    }
+    return out;
+}

package/src/common/writer.ts

@@ -6,14 +6,19 @@
  * `ReadableStream<Uint8Array>` for a caller that wants a stream.
  */
 
+import { GraphFormatError } from "@graphty/graph-format";
+
 /**
  * Text parts an exporter produces.
- * Consumed by the per-format importers and exporters under src/formats.
  * @public
+ * @category Plugin helpers
  */
 export type TextParts = Iterable<string> | AsyncIterable<string>;
 
-/** The target size of one encoded chunk; parts are coalesced up to it and never split. */
+/**
+ * The target size of one encoded chunk; parts are coalesced up to it and never split.
+ * @category Plugin helpers
+ */
 export const DEFAULT_CHUNK_BYTES = 64 * 1024;
 
 /**
@@ -24,6 +29,7 @@ export const DEFAULT_CHUNK_BYTES = 64 * 1024;
  * @param chunkBytes - the target chunk size in bytes
  * @yields UTF-8 chunks
  * @returns nothing
+ * @category Writing a format
  */
 export async function* encodeChunks(
     parts: TextParts,
@@ -54,6 +60,7 @@ export async function* encodeChunks(
  * Join text parts into one string.
  * @param parts - the text parts
  * @returns the whole document
+ * @category Writing a format
  */
 export async function joinText(parts: TextParts): Promise<string> {
     const collected: string[] = [];
@@ -67,6 +74,7 @@ export async function joinText(parts: TextParts): Promise<string> {
  * 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
+ * @category Plugin helpers
  */
 export async function decodeChunks(chunks: AsyncIterable<Uint8Array>): Promise<string> {
     const decoder = new TextDecoder("utf-8", { fatal: true });
@@ -82,6 +90,7 @@ export async function decodeChunks(chunks: AsyncIterable<Uint8Array>): Promise<s
  * Collect UTF-8 chunks into one Uint8Array.
  * @param chunks - the chunks
  * @returns the concatenated bytes
+ * @category Plugin helpers
  */
 export async function collectBytes(chunks: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
     const parts: Uint8Array[] = [];
@@ -101,9 +110,10 @@ export async function collectBytes(chunks: AsyncIterable<Uint8Array>): Promise<U
 
 /**
  * Wrap an async iterable of chunks as a ReadableStream, pulling one chunk per read and cancelling
- * the iterable when the stream is cancelled.
+ * the iterable when the stream is canceled.
  * @param chunks - the chunks
  * @returns a byte stream
+ * @category Saving
  */
 export function toReadableStream(chunks: AsyncIterable<Uint8Array>): ReadableStream<Uint8Array> {
     const iterator = chunks[Symbol.asyncIterator]();
@@ -121,3 +131,27 @@ export function toReadableStream(chunks: AsyncIterable<Uint8Array>): ReadableStr
         },
     });
 }
+
+/**
+ * The indentation of one nesting level from an `indent` option: a number of spaces (0 to 16), or
+ * the text itself (spaces or tabs). The JSON and DOT exporters take the same option this way.
+ * @param value - the option value
+ * @param fallback - the indentation when the option is not given
+ * @returns the text of one level; "" for none
+ */
+export function indentUnit(value: unknown, fallback: string): string {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 16) {
+        return " ".repeat(value);
+    }
+    if (typeof value === "string" && /^[ \t]{0,16}$/.test(value)) {
+        return value;
+    }
+    throw new GraphFormatError(
+        "E_UNSUPPORTED",
+        `option indent: ${typeof value === "string" || typeof value === "number" ? JSON.stringify(value) : typeof value} is not a number of spaces (0 to 16) or a string of spaces or tabs`,
+        { option: "indent", found: typeof value === "string" || typeof value === "number" ? value : typeof value },
+    );
+}