@graphty/graph-io 0.0.0 → 0.2.1

package/dist/src/common/format.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Number formatting for exporters (design section 3.7): an f32 weight is written as the shortest
+ * decimal that round-trips through Math.fround (never `String(x)`, which prints
+ * 0.10000000149011612 for a stored 0.1); an f64 value as its shortest JS text; a GML real always
+ * with a decimal point so the dtype survives (design section 8.5); non-finite values as the
+ * spelling the target syntax accepts.
+ */
+/**
+ * The shortest decimal text that reads back to the same f32 value through Math.fround.
+ * @param value - an f32 value (a JS number holding one)
+ * @returns the text; "Infinity" / "-Infinity" / "NaN" for the non-finite values, "0" for both zeros
+ */
+export declare function formatF32(value: number): string;
+/**
+ * The shortest text of an f64 value: `String(x)`, which is already the shortest round-tripping
+ * decimal in JS.
+ * @param value - the value
+ * @returns the text; "Infinity" / "-Infinity" / "NaN" for the non-finite values
+ */
+export declare function formatF64(value: number): string;
+/**
+ * A decimal text with a decimal point or an exponent guaranteed for a finite value (`2.0`,
+ * `1e+21`, `1.5e-7`), so an
+ * untyped re-import keeps the column f64 rather than i32 (design section 8.5); negative zero is
+ * written `-0.0` so it reads back as -0; non-finite values are the JS spellings (`Infinity`,
+ * `-Infinity`, `NaN`), which the CSV / DOT / Pajek importers read back as text. The one
+ * implementation of the "decimal point guaranteed" rule for every text format; GML has its own
+ * spellings of the non-finite values in formatGmlReal().
+ * @param value - the value
+ * @param dtype - the column dtype the value comes from; f32 values use the shortest fround-round-trip text
+ * @returns the text
+ */
+export declare function formatDecimal(value: number, dtype?: "f32" | "f64" | "i32" | "u32" | "u8"): string;
+/**
+ * A GML real: the shortest text with a decimal point guaranteed (`2.0`, `1.0e-7`), so a re-import
+ * keeps the column real rather than int. Non-finite values have no GML spelling and are written
+ * as the texts NetworkX's writer emits and its reader accepts, `+INF`, `-INF` and `NAN` (the
+ * lowercase `inf` / `nan` would lex as keys there).
+ * @param value - the value
+ * @param dtype - the column dtype the value comes from; f32 values use the shortest fround-round-trip text
+ * @returns the text
+ */
+export declare function formatGmlReal(value: number, dtype?: "f32" | "f64" | "i32" | "u32" | "u8"): string;
+/**
+ * An integer text for a value known to be integral (an i32 / u32 / u8 cell, an f64 that holds an
+ * integer), avoiding the exponent form `String()` uses above 1e21.
+ * @param value - an integral value
+ * @returns the digits
+ */
+export declare function formatInteger(value: number): string;
+/**
+ * The text of a numeric cell of any numeric dtype, dispatching on the dtype: f32 through
+ * formatF32, everything else through formatF64.
+ * @param value - the value
+ * @param dtype - the column dtype the value came from
+ * @returns the text
+ */
+export declare function formatNumber(value: number, dtype: "f32" | "f64" | "i32" | "u32" | "u8"): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/src/common/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/common/format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAc/C;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,IAAY,GAAG,MAAM,CAUxG;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,IAAY,GAAG,MAAM,CAcxG;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,IAAI,GAAG,MAAM,CAE/F"}

package/dist/src/common/format.js

@@ -0,0 +1,106 @@
+/**
+ * Number formatting for exporters (design section 3.7): an f32 weight is written as the shortest
+ * decimal that round-trips through Math.fround (never `String(x)`, which prints
+ * 0.10000000149011612 for a stored 0.1); an f64 value as its shortest JS text; a GML real always
+ * with a decimal point so the dtype survives (design section 8.5); non-finite values as the
+ * spelling the target syntax accepts.
+ */
+/**
+ * The shortest decimal text that reads back to the same f32 value through Math.fround.
+ * @param value - an f32 value (a JS number holding one)
+ * @returns the text; "Infinity" / "-Infinity" / "NaN" for the non-finite values, "0" for both zeros
+ */
+export function formatF32(value) {
+    if (!Number.isFinite(value)) {
+        return String(value);
+    }
+    if (value === 0) {
+        return "0";
+    }
+    for (let digits = 1; digits <= 9; digits++) {
+        const text = value.toPrecision(digits);
+        if (Math.fround(Number(text)) === value) {
+            return String(Number(text));
+        }
+    }
+    return String(value);
+}
+/**
+ * The shortest text of an f64 value: `String(x)`, which is already the shortest round-tripping
+ * decimal in JS.
+ * @param value - the value
+ * @returns the text; "Infinity" / "-Infinity" / "NaN" for the non-finite values
+ */
+export function formatF64(value) {
+    return String(value);
+}
+/**
+ * A decimal text with a decimal point or an exponent guaranteed for a finite value (`2.0`,
+ * `1e+21`, `1.5e-7`), so an
+ * untyped re-import keeps the column f64 rather than i32 (design section 8.5); negative zero is
+ * written `-0.0` so it reads back as -0; non-finite values are the JS spellings (`Infinity`,
+ * `-Infinity`, `NaN`), which the CSV / DOT / Pajek importers read back as text. The one
+ * implementation of the "decimal point guaranteed" rule for every text format; GML has its own
+ * spellings of the non-finite values in formatGmlReal().
+ * @param value - the value
+ * @param dtype - the column dtype the value comes from; f32 values use the shortest fround-round-trip text
+ * @returns the text
+ */
+export function formatDecimal(value, dtype = "f64") {
+    if (!Number.isFinite(value)) {
+        return String(value);
+    }
+    if (Object.is(value, -0)) {
+        return "-0.0";
+    }
+    const text = formatNumber(value, dtype);
+    // an exponent form (`1e+21`, `1.5e-7`) is already f64 text under the 5.1 grammar
+    return text.includes(".") || text.includes("e") ? text : `${text}.0`;
+}
+/**
+ * A GML real: the shortest text with a decimal point guaranteed (`2.0`, `1.0e-7`), so a re-import
+ * keeps the column real rather than int. Non-finite values have no GML spelling and are written
+ * as the texts NetworkX's writer emits and its reader accepts, `+INF`, `-INF` and `NAN` (the
+ * lowercase `inf` / `nan` would lex as keys there).
+ * @param value - the value
+ * @param dtype - the column dtype the value comes from; f32 values use the shortest fround-round-trip text
+ * @returns the text
+ */
+export function formatGmlReal(value, dtype = "f64") {
+    if (Number.isNaN(value)) {
+        return "NAN";
+    }
+    if (!Number.isFinite(value)) {
+        return value > 0 ? "+INF" : "-INF";
+    }
+    const text = formatDecimal(value, dtype);
+    if (text.includes(".")) {
+        return text;
+    }
+    // NetworkX's real pattern requires a decimal point even in the exponent form (`1.0e-7`)
+    const e = text.indexOf("e");
+    return `${text.slice(0, e)}.0${text.slice(e)}`;
+}
+/**
+ * An integer text for a value known to be integral (an i32 / u32 / u8 cell, an f64 that holds an
+ * integer), avoiding the exponent form `String()` uses above 1e21.
+ * @param value - an integral value
+ * @returns the digits
+ */
+export function formatInteger(value) {
+    if (Number.isSafeInteger(value) || !Number.isFinite(value)) {
+        return String(value);
+    }
+    return BigInt(value).toString();
+}
+/**
+ * The text of a numeric cell of any numeric dtype, dispatching on the dtype: f32 through
+ * formatF32, everything else through formatF64.
+ * @param value - the value
+ * @param dtype - the column dtype the value came from
+ * @returns the text
+ */
+export function formatNumber(value, dtype) {
+    return dtype === "f32" ? formatF32(value) : formatF64(value);
+}
+//# sourceMappingURL=format.js.map

package/dist/src/common/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../../src/common/format.ts"],"names":[],"mappings":"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"}

package/dist/src/common/ids.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Id coercion (design section 4.1): the importer-side rule that turns a text cell or a JSON value
+ * into a NodeId before it reaches the sink. The core never coerces.
+ *
+ * - "keep": typed values pass through; anything that is not a string or a number is E_INVALID_ID.
+ * - "canonical": text becomes a number iff it is canonical integer text (`/^-?(0|[1-9][0-9]*)$/`
+ *   and a safe integer, excluding "-0" which would collide with "0"); every other text stays a
+ *   string. Injective on text, so `String(id)` on export reproduces the cell exactly: "01", "1.0"
+ *   and "+1" stay strings, "1" becomes 1. Typed values pass through as under "keep".
+ * - "string": `String(v)` for strings, numbers, booleans, bigints and null; anything else is
+ *   E_INVALID_ID.
+ * - "number": `Number(text)` for text (empty or whitespace-only text, NaN and non-finite results
+ *   are E_INVALID_ID); numbers pass through; anything else is E_INVALID_ID. This rule can merge
+ *   distinct cells ("01" and "1"); IdCoercer counts such merges so the importer can report them as
+ *   coercion issues.
+ */
+import { type IdCoercion, type NodeId } from "@graphty/graph-format";
+import { ID_MERGED_CODE } from "./codes.js";
+export { ID_MERGED_CODE };
+/**
+ * The "canonical" rule on one text cell.
+ * @param text - the cell text, exactly as read
+ * @returns the number for canonical safe-integer text (never for "-0"), the text itself otherwise
+ */
+export declare function canonicalId(text: string): NodeId;
+/**
+ * Whether a text cell is canonical integer text under the "canonical" rule (a number after import).
+ * @param text - the cell text
+ * @returns true when canonicalId(text) returns a number
+ */
+export declare function isCanonicalIntegerText(text: string): boolean;
+/**
+ * Coerce a text cell under a rule.
+ * @param text - the cell text, exactly as read
+ * @param mode - the coercion rule
+ * @returns the id; E_INVALID_ID when the rule rejects the text
+ */
+export declare function coerceIdText(text: string, mode: IdCoercion): NodeId;
+/**
+ * Coerce a typed value (a JSON scalar, a record field) under a rule.
+ * @param value - the value
+ * @param mode - the coercion rule
+ * @returns the id; E_INVALID_ID when the rule rejects the value
+ */
+export declare function coerceId(value: unknown, mode: IdCoercion): NodeId;
+/**
+ * A stateful coercer for one import call: applies the rule and, under "number", detects merges
+ * (two distinct texts mapping to one number) so the importer can report them as coercion issues
+ * (design section 4.1).
+ */
+export declare class IdCoercer {
+    /** The rule. */
+    readonly mode: IdCoercion;
+    /** Texts merged into an id another text already produced. */
+    mergeCount: number;
+    /** The text that first produced each numeric id, kept only under "number". */
+    private readonly firstText;
+    /** The merge detected by the most recent text() call, or null. */
+    lastMerge: {
+        readonly id: number;
+        readonly text: string;
+        readonly previousText: string;
+    } | null;
+    /**
+     * Create a coercer.
+     * @param mode - the rule
+     */
+    constructor(mode: IdCoercion);
+    /**
+     * Coerce a text cell, recording a merge under "number" when a different text already produced
+     * the same number.
+     * @param text - the cell text
+     * @returns the id
+     */
+    text(text: string): NodeId;
+    /**
+     * Coerce a typed value.
+     * @param value - the value
+     * @returns the id
+     */
+    value(value: unknown): NodeId;
+}
+//# sourceMappingURL=ids.d.ts.map

package/dist/src/common/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../../src/common/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAoB,KAAK,UAAU,EAAE,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEvF,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAI5C,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAsBnE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAcjE;AAgBD;;;;GAIG;AACH,qBAAa,SAAS;IAClB,gBAAgB;IAChB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAE1B,6DAA6D;IAC7D,UAAU,SAAK;IAEf,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IAEvD,kEAAkE;IAClE,SAAS,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAQ;IAEvG;;;OAGG;gBACS,IAAI,EAAE,UAAU;IAK5B;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAe1B;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;CAOhC"}

package/dist/src/common/ids.js

@@ -0,0 +1,158 @@
+/**
+ * Id coercion (design section 4.1): the importer-side rule that turns a text cell or a JSON value
+ * into a NodeId before it reaches the sink. The core never coerces.
+ *
+ * - "keep": typed values pass through; anything that is not a string or a number is E_INVALID_ID.
+ * - "canonical": text becomes a number iff it is canonical integer text (`/^-?(0|[1-9][0-9]*)$/`
+ *   and a safe integer, excluding "-0" which would collide with "0"); every other text stays a
+ *   string. Injective on text, so `String(id)` on export reproduces the cell exactly: "01", "1.0"
+ *   and "+1" stay strings, "1" becomes 1. Typed values pass through as under "keep".
+ * - "string": `String(v)` for strings, numbers, booleans, bigints and null; anything else is
+ *   E_INVALID_ID.
+ * - "number": `Number(text)` for text (empty or whitespace-only text, NaN and non-finite results
+ *   are E_INVALID_ID); numbers pass through; anything else is E_INVALID_ID. This rule can merge
+ *   distinct cells ("01" and "1"); IdCoercer counts such merges so the importer can report them as
+ *   coercion issues.
+ */
+import { GraphFormatError } from "@graphty/graph-format";
+import { ID_MERGED_CODE } from "./codes.js";
+const CANONICAL_INTEGER = /^-?(0|[1-9][0-9]*)$/;
+export { ID_MERGED_CODE };
+/**
+ * The "canonical" rule on one text cell.
+ * @param text - the cell text, exactly as read
+ * @returns the number for canonical safe-integer text (never for "-0"), the text itself otherwise
+ */
+export function canonicalId(text) {
+    if (text !== "-0" && CANONICAL_INTEGER.test(text)) {
+        const n = Number(text);
+        if (Number.isSafeInteger(n)) {
+            return n;
+        }
+    }
+    return text;
+}
+/**
+ * Whether a text cell is canonical integer text under the "canonical" rule (a number after import).
+ * @param text - the cell text
+ * @returns true when canonicalId(text) returns a number
+ */
+export function isCanonicalIntegerText(text) {
+    return typeof canonicalId(text) === "number";
+}
+/**
+ * Coerce a text cell under a rule.
+ * @param text - the cell text, exactly as read
+ * @param mode - the coercion rule
+ * @returns the id; E_INVALID_ID when the rule rejects the text
+ */
+export function coerceIdText(text, mode) {
+    switch (mode) {
+        case "keep":
+        case "string":
+            return text;
+        case "canonical":
+            return canonicalId(text);
+        case "number": {
+            if (text.trim().length === 0) {
+                throw invalidId(text, "empty text is not a number");
+            }
+            const n = Number(text);
+            if (!Number.isFinite(n)) {
+                throw invalidId(text, "not a finite number");
+            }
+            return n;
+        }
+        default: {
+            const name = mode;
+            throw new GraphFormatError("E_UNSUPPORTED", `unknown id coercion ${name}`, { option: "ids", found: name });
+        }
+    }
+}
+/**
+ * Coerce a typed value (a JSON scalar, a record field) under a rule.
+ * @param value - the value
+ * @param mode - the coercion rule
+ * @returns the id; E_INVALID_ID when the rule rejects the value
+ */
+export function coerceId(value, mode) {
+    if (typeof value === "string") {
+        return coerceIdText(value, mode);
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw invalidId(value, "not a finite number");
+        }
+        return mode === "string" ? String(value) : value;
+    }
+    if (mode === "string" && (typeof value === "boolean" || typeof value === "bigint" || value === null)) {
+        return String(value);
+    }
+    throw invalidId(value, `a ${value === null ? "null" : typeof value} is not an id under ids: "${mode}"`);
+}
+/**
+ * The E_INVALID_ID error of a rejected value.
+ * @param value - the rejected value
+ * @param reason - why
+ * @returns the error
+ */
+function invalidId(value, reason) {
+    const shown = typeof value === "string" || typeof value === "number" ? value : typeof value;
+    return new GraphFormatError("E_INVALID_ID", `invalid node id ${JSON.stringify(shown)}: ${reason}`, {
+        reason,
+        value: typeof value === "bigint" ? value.toString() : value,
+    });
+}
+/**
+ * A stateful coercer for one import call: applies the rule and, under "number", detects merges
+ * (two distinct texts mapping to one number) so the importer can report them as coercion issues
+ * (design section 4.1).
+ */
+export class IdCoercer {
+    /**
+     * Create a coercer.
+     * @param mode - the rule
+     */
+    constructor(mode) {
+        /** Texts merged into an id another text already produced. */
+        this.mergeCount = 0;
+        /** The merge detected by the most recent text() call, or null. */
+        this.lastMerge = null;
+        this.mode = mode;
+        this.firstText = mode === "number" ? new Map() : null;
+    }
+    /**
+     * Coerce a text cell, recording a merge under "number" when a different text already produced
+     * the same number.
+     * @param text - the cell text
+     * @returns the id
+     */
+    text(text) {
+        const id = coerceIdText(text, this.mode);
+        this.lastMerge = null;
+        if (this.firstText !== null && typeof id === "number") {
+            const previous = this.firstText.get(id);
+            if (previous === undefined) {
+                this.firstText.set(id, text);
+            }
+            else if (previous !== text) {
+                this.mergeCount++;
+                this.lastMerge = { id, text, previousText: previous };
+            }
+        }
+        return id;
+    }
+    /**
+     * Coerce a typed value.
+     * @param value - the value
+     * @returns the id
+     */
+    value(value) {
+        if (typeof value === "string") {
+            return this.text(value);
+        }
+        this.lastMerge = null;
+        return coerceId(value, this.mode);
+    }
+}
+//# sourceMappingURL=ids.js.map

package/dist/src/common/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../../src/common/ids.ts"],"names":[],"mappings":"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"}

package/dist/src/common/input.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Input handling shared by every importer (design section 8.4): the ImportInput union (whole
+ * text, whole bytes, a byte stream, an async iterable of text or byte chunks) read as a sequence of
+ * UTF-8 text chunks, as lines, or as one string, with BOM handling, cancellation through an
+ * AbortSignal and byte progress.
+ *
+ * Bytes are decoded with `new TextDecoder("utf-8", { fatal: true })` in streaming mode, so a
+ * multi-byte character split across two chunks decodes correctly and an invalid sequence is a
+ * parse-error (issue code E_INVALID_UTF8) that aborts the import, never a silent U+FFFD that could
+ * alias two ids. A leading U+FEFF is stripped from text and from decoded bytes alike.
+ */
+import { type ImportInput } from "../types.js";
+import { INVALID_UTF8_CODE } from "./codes.js";
+import { type ImportReportBuilder } from "./report.js";
+export { INVALID_UTF8_CODE };
+/**
+ * Cancellation and progress hooks of the reader; the resolved importer options satisfy this shape.
+ * Consumed by the per-format importers and exporters under src/formats.
+ * @public
+ */
+export interface ReadOptions {
+    /** The cancellation signal, or null / undefined for none. */
+    readonly signal?: AbortSignal | null | undefined;
+    /** The progress callback, or null / undefined for none. */
+    readonly onProgress?: ((bytesDone: number, bytesTotal?: number) => void) | null | undefined;
+}
+/**
+ * Whether a value is an ImportInput this module can read.
+ * @param input - any value
+ * @returns true for a string, a Uint8Array, a ReadableStream or an async iterable
+ */
+export declare function isImportInput(input: unknown): input is ImportInput;
+/**
+ * The total size of an in-memory input (bytes for a Uint8Array, UTF-16 code units for a string),
+ * for the `bytesTotal` argument of onProgress; null for a stream or an iterable.
+ * @param input - the input
+ * @returns the size, or null when unknown up front
+ */
+export declare function inputLength(input: ImportInput): number | null;
+/**
+ * Throw the signal's reason when it is aborted, exactly as the platform's
+ * `AbortSignal.throwIfAborted()` does: the reason as it is (the DOMException named "AbortError"
+ * of a reason-less abort, or whatever the caller passed to `abort(reason)`, an Error or not), so a
+ * caller can compare the rejection with `signal.reason`. Only a runtime that stores no reason at
+ * all gets a synthesised AbortError.
+ * @param signal - the signal, or null
+ */
+export declare function throwIfAborted(signal: AbortSignal | null | undefined): void;
+/**
+ * Read an ImportInput as a sequence of decoded text chunks. Chunk boundaries carry no meaning:
+ * a caller that needs lines uses LineReader, one that needs the whole document uses readText().
+ * The signal is checked before every chunk; a stream is cancelled when the consumer stops early
+ * or the signal fires. Progress is reported after every chunk.
+ * @param input - the input
+ * @param report - the report the decode error is recorded in (E_INVALID_UTF8, then ImportError)
+ * @param options - cancellation and progress
+ * @yields decoded text; the first chunk has any leading BOM removed
+ * @returns nothing
+ */
+export declare function textChunks(input: ImportInput, report: ImportReportBuilder, options?: ReadOptions): AsyncGenerator<string, void, undefined>;
+/**
+ * Read the whole input as one string (the GML / DOT / JSON path, design section 8.4).
+ * @param input - the input
+ * @param report - the report the decode error is recorded in
+ * @param options - cancellation and progress
+ * @returns the decoded text without a leading BOM
+ */
+export declare function readText(input: ImportInput, report: ImportReportBuilder, options?: ReadOptions): Promise<string>;
+/**
+ * Lines of an ImportInput without allocating anything per line but the string itself: iterate with
+ * `for await (const text of reader)` and read `reader.line` (1-based) for the line just yielded.
+ * `\n`, `\r\n` and lone `\r` all end a line; the terminator is not part of the text; a final
+ * line without a terminator is yielded when non-empty, and every line in between is yielded even
+ * when empty (the importer decides what a blank line means).
+ */
+export declare class LineReader implements AsyncIterable<string> {
+    private readonly input;
+    private readonly report;
+    private readonly options;
+    private lineNumber;
+    /**
+     * Create a reader over an input; nothing is read until iteration starts.
+     * @param input - the input
+     * @param report - the report decode errors are recorded in
+     * @param options - cancellation and progress
+     */
+    constructor(input: ImportInput, report: ImportReportBuilder, options?: ReadOptions);
+    /**
+     * The 1-based number of the line most recently yielded.
+     * @returns the line number; 0 before the first line
+     */
+    get line(): number;
+    /**
+     * Iterate the lines.
+     * @yields one line at a time, terminator removed
+     * @returns nothing
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<string, void, undefined>;
+}
+//# sourceMappingURL=input.d.ts.map

package/dist/src/common/input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../../src/common/input.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAE7B;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC;IACjD,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;CAC/F;AAYD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAQlE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAQ7D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAU3E;AAgBD;;;;;;;;;;GAUG;AACH,wBAAuB,UAAU,CAC7B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,mBAAmB,EAC3B,OAAO,GAAE,WAAgB,GAC1B,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CA8EzC;AA4CD;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC1B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,mBAAmB,EAC3B,OAAO,GAAE,WAAgB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED;;;;;;GAMG;AACH,qBAAa,UAAW,YAAW,aAAa,CAAC,MAAM,CAAC;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IAEpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAE7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IAEtC,OAAO,CAAC,UAAU,CAAK;IAEvB;;;;;OAKG;gBACS,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,mBAAmB,EAAE,OAAO,GAAE,WAAgB;IAMtF;;;OAGG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;OAIG;IACI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC;CAoE3E"}