@graphty/graph-io 0.3.24 → 0.3.26

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

@@ -1 +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"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/common/format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAc/C;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,IAAY,GAAG,MAAM,CAUxG;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,IAAY,GAAG,MAAM,CAcxG;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED;;;;;;;GAOG;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

@@ -9,6 +9,7 @@
  * 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 negative zero
+ * @category Plugin helpers
  */
 export function formatF32(value) {
     if (!Number.isFinite(value)) {
@@ -25,19 +26,39 @@ export function formatF32(value) {
     }
     return String(value);
 }
+/**
+ * Whether a number read from a file keeps its decimal value in an f32 column: the shortest decimal
+ * of its f32 rounding reads back as the same number (0.2 does; 123456789.123 and 0.123456789 do not).
+ * @param value - a finite number
+ * @returns true when nothing a reader would see is lost
+ * @category Plugin helpers
+ */
+export function survivesF32(value) {
+    return Number(formatF32(Math.fround(value))) === value;
+}
 /**
  * The shortest text of an f64 value: `String(x)`, which is already the shortest round-tripping
  * decimal in JS, except for negative zero, which `String()` writes as "0".
  * @param value - the value
  * @returns the text; "Infinity" / "-Infinity" / "NaN" for the non-finite values, "-0" for negative zero
+ * @category Plugin helpers
  */
 export function formatF64(value) {
     return Object.is(value, -0) ? "-0" : String(value);
 }
+/**
+ * The text of a node id for the text formats that write ids bare (DOT, Pajek, XGMML): the string
+ * itself, or the shortest decimal of a number (formatF64).
+ * @param id - the id
+ * @returns the text
+ */
+export function idText(id) {
+    return typeof id === "number" ? formatF64(id) : id;
+}
 /**
  * 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
+ * untyped re-import keeps the column f64 rather than i32; 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
@@ -45,6 +66,7 @@ export function formatF64(value) {
  * @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
+ * @category Plugin helpers
  */
 export function formatDecimal(value, dtype = "f64") {
     if (!Number.isFinite(value)) {
@@ -65,6 +87,7 @@ export function formatDecimal(value, dtype = "f64") {
  * @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
+ * @category Plugin helpers
  */
 export function formatGmlReal(value, dtype = "f64") {
     if (Number.isNaN(value)) {
@@ -86,6 +109,7 @@ export function formatGmlReal(value, dtype = "f64") {
  * integer), avoiding the exponent form `String()` uses above 1e21.
  * @param value - an integral value
  * @returns the digits
+ * @category Plugin helpers
  */
 export function formatInteger(value) {
     if (Number.isSafeInteger(value) || !Number.isFinite(value)) {
@@ -99,6 +123,7 @@ export function formatInteger(value) {
  * @param value - the value
  * @param dtype - the column dtype the value came from
  * @returns the text
+ * @category Plugin helpers
  */
 export function formatNumber(value, dtype) {
     return dtype === "f32" ? formatF32(value) : formatF64(value);

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

@@ -1 +1 @@
-{"version":3,"file":"format.js","sourceRoot":"","sources":["../../../src/common/format.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../../src/common/format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa;IACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IACD,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;QACd,OAAO,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;IAC7C,CAAC;IACD,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;YACtC,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QAChC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACrC,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC;AAC3D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa;IACnC,OAAO,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,EAAU;IAC7B,OAAO,OAAO,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,QAA8C,KAAK;IAC5F,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IACD,IAAI,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvB,OAAO,MAAM,CAAC;IAClB,CAAC;IACD,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACxC,iFAAiF;IACjF,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC;AACzE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,QAA8C,KAAK;IAC5F,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IACvC,CAAC;IACD,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACzC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,wFAAwF;IACxF,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC5B,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACvC,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,KAA2C;IACnF,OAAO,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AACjE,CAAC"}

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

@@ -21,12 +21,14 @@ 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
+ * @category Plugin helpers
  */
 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
+ * @category Plugin helpers
  */
 export declare function isCanonicalIntegerText(text: string): boolean;
 /**
@@ -34,6 +36,7 @@ export declare function isCanonicalIntegerText(text: string): boolean;
  * @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
+ * @category Plugin helpers
  */
 export declare function coerceIdText(text: string, mode: IdCoercion): NodeId;
 /**
@@ -41,12 +44,13 @@ export declare function coerceIdText(text: string, mode: IdCoercion): NodeId;
  * @param value - the value
  * @param mode - the coercion rule
  * @returns the id; E_INVALID_ID when the rule rejects the value
+ * @category Plugin helpers
  */
 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).
+ * (two distinct texts mapping to one number) so the importer can report them as coercion issues.
+ * @category Writing a format
  */
 export declare class IdCoercer {
     /** The rule. */
@@ -57,8 +61,11 @@ export declare class IdCoercer {
     private readonly firstText;
     /** The merge detected by the most recent text() call, or null. */
     lastMerge: {
+        /** The number both texts became. */
         readonly id: number;
+        /** The text just read. */
         readonly text: string;
+        /** The first text that became the same number. */
         readonly previousText: string;
     } | null;
     /**

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

@@ -1 +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"}
+{"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;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAsBnE;AAED;;;;;;GAMG;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;QACP,oCAAoC;QACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,0BAA0B;QAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,kDAAkD;QAClD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;KACjC,GAAG,IAAI,CAAQ;IAEhB;;;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

@@ -22,6 +22,7 @@ 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
+ * @category Plugin helpers
  */
 export function canonicalId(text) {
     if (text !== "-0" && CANONICAL_INTEGER.test(text)) {
@@ -36,6 +37,7 @@ export function canonicalId(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
+ * @category Plugin helpers
  */
 export function isCanonicalIntegerText(text) {
     return typeof canonicalId(text) === "number";
@@ -45,6 +47,7 @@ export function isCanonicalIntegerText(text) {
  * @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
+ * @category Plugin helpers
  */
 export function coerceIdText(text, mode) {
     switch (mode) {
@@ -74,6 +77,7 @@ export function coerceIdText(text, mode) {
  * @param value - the value
  * @param mode - the coercion rule
  * @returns the id; E_INVALID_ID when the rule rejects the value
+ * @category Plugin helpers
  */
 export function coerceId(value, mode) {
     if (typeof value === "string") {
@@ -105,8 +109,8 @@ function invalidId(value, reason) {
 }
 /**
  * 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).
+ * (two distinct texts mapping to one number) so the importer can report them as coercion issues.
+ * @category Writing a format
  */
 export class IdCoercer {
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../../src/common/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,gBAAgB,EAAgC,MAAM,uBAAuB,CAAC;AAEvF,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AAEhD,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACpC,IAAI,IAAI,KAAK,IAAI,IAAI,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QACvB,IAAI,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1B,OAAO,CAAC,CAAC;QACb,CAAC;IACL,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IAC/C,OAAO,OAAO,WAAW,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,IAAgB;IACvD,QAAQ,IAAI,EAAE,CAAC;QACX,KAAK,MAAM,CAAC;QACZ,KAAK,QAAQ;YACT,OAAO,IAAI,CAAC;QAChB,KAAK,WAAW;YACZ,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC7B,KAAK,QAAQ,CAAC,CAAC,CAAC;YACZ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC3B,MAAM,SAAS,CAAC,IAAI,EAAE,4BAA4B,CAAC,CAAC;YACxD,CAAC;YACD,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;YACvB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtB,MAAM,SAAS,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC;YACjD,CAAC;YACD,OAAO,CAAC,CAAC;QACb,CAAC;QACD,OAAO,CAAC,CAAC,CAAC;YACN,MAAM,IAAI,GAAW,IAAI,CAAC;YAC1B,MAAM,IAAI,gBAAgB,CAAC,eAAe,EAAE,uBAAuB,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/G,CAAC;IACL,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc,EAAE,IAAgB;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACrC,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,SAAS,CAAC,KAAK,EAAE,qBAAqB,CAAC,CAAC;QAClD,CAAC;QACD,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACrD,CAAC;IACD,IAAI,IAAI,KAAK,QAAQ,IAAI,CAAC,OAAO,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,EAAE,CAAC;QACnG,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IACD,MAAM,SAAS,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,KAAK,6BAA6B,IAAI,GAAG,CAAC,CAAC;AAC5G,CAAC;AAED;;;;;GAKG;AACH,SAAS,SAAS,CAAC,KAAc,EAAE,MAAc;IAC7C,MAAM,KAAK,GAAG,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC;IAC5F,OAAO,IAAI,gBAAgB,CAAC,cAAc,EAAE,mBAAmB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,MAAM,EAAE,EAAE;QAC/F,MAAM;QACN,KAAK,EAAE,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK;KAC9D,CAAC,CAAC;AACP,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,SAAS;IAalB;;;OAGG;IACH,YAAY,IAAgB;QAb5B,6DAA6D;QAC7D,eAAU,GAAG,CAAC,CAAC;QAKf,kEAAkE;QAClE,cAAS,GAAyF,IAAI,CAAC;QAOnG,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1D,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,IAAY;QACb,MAAM,EAAE,GAAG,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,IAAI,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC;YACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACxC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBACzB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YACjC,CAAC;iBAAM,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;gBAC3B,IAAI,CAAC,UAAU,EAAE,CAAC;gBAClB,IAAI,CAAC,SAAS,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;YAC1D,CAAC;QACL,CAAC;QACD,OAAO,EAAE,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAc;QAChB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,OAAO,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;CACJ"}
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../../src/common/ids.ts"],"names":[],"mappings":"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"}

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

@@ -4,15 +4,23 @@
  * text chunks, as lines, or as one string, with BOM handling, cancellation through an AbortSignal
  * and byte progress.
  *
- * Bytes are decoded ONCE, here, for every importer. The encoding is, in order of precedence: the
- * caller's `encoding` option; a byte order mark (UTF-8, UTF-16LE, UTF-16BE); the encoding the file
- * declares (the importer's `declaredEncoding` reader: the XML prolog for GEXF and GraphML, the
- * `charset` attribute for DOT); else UTF-8. Decoding is strict (`fatal: true`): an invalid sequence
+ * Bytes are decoded ONCE, here, for every importer. The encoding is, in order of precedence: a
+ * byte order mark (UTF-8, UTF-16LE, UTF-16BE; a UTF-32 one is E_INVALID_ENCODING); the caller's
+ * `encoding` option; the encoding the file declares (the importer's `declaredEncoding` reader: the
+ * XML prolog for GEXF and GraphML, the `charset` attribute for DOT); else UTF-8. Whenever two of
+ * them disagree the one that applies is named in a W_ENCODING_CONFLICT warning. BOM-less UTF-16
+ * (every other byte 0) is E_INVALID_ENCODING asking for the option, and a known non-graph file (an
+ * HTML page, a PDF, gzip or zip data, a PNG) is E_FOREIGN_FORMAT. Decoding is strict (`fatal: true`): an invalid sequence
  * is never a silent U+FFFD that could alias two ids. Only in the last case, when bytes that are not
  * valid UTF-8 appear while everything before them was ASCII, is the rest of the input read as
  * windows-1252 (the superset of ISO 8859-1 that Excel, Pajek and older tools write), with the
- * warning W_ENCODING_FALLBACK; invalid UTF-8 after valid non-ASCII UTF-8 is E_INVALID_UTF8. A
- * leading U+FEFF is stripped from text and from decoded bytes alike.
+ * warning W_ENCODING_FALLBACK; invalid UTF-8 after valid non-ASCII UTF-8, in data holding control
+ * bytes (binary data), or cut at the end of the input is E_INVALID_UTF8.
+ *
+ * The decoded text, whatever the input shape, is then checked once: leading U+FEFFs are stripped, a
+ * trailing Ctrl-Z (the DOS end-of-file marker) is dropped, the first control character or stray
+ * U+FEFF is reported W_CONTROL_CHARACTER, and a text that is empty or only whitespace is the fatal
+ * E_EMPTY_INPUT.
  */
 import { type ImportInput } from "../types.js";
 import { INVALID_UTF8_CODE } from "./codes.js";
@@ -20,8 +28,8 @@ 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
+ * @category Plugin helpers
  */
 export interface ReadOptions {
     /** The cancellation signal, or null / undefined for none. */
@@ -35,33 +43,81 @@ export interface ReadOptions {
      * windows-1252 (ASCII-compatible), the encoding label it declares, or null.
      */
     readonly declaredEncoding?: ((head: string) => string | null) | undefined;
+    /** How many leading bytes the declaration reader sees (default 1024). */
+    readonly declarationBytes?: number | undefined;
+    /**
+     * Whether BOM-less UTF-16 that the NUL pattern of its head shows is read in that encoding (JSON:
+     * RFC 8259 section 8.1, RFC 4627 section 3) instead of failing with E_INVALID_ENCODING.
+     */
+    readonly bomlessUtf16?: boolean | undefined;
+    /** Whether an input with no text but whitespace is valid (else E_EMPTY_INPUT). */
+    readonly allowEmpty?: boolean | undefined;
+    /**
+     * Whether the format is XML: an (X)HTML document is then left to the format's own root-element
+     * check (an XHTML page may embed the format's elements) instead of being E_FOREIGN_FORMAT.
+     */
+    readonly xml?: boolean | undefined;
+    /**
+     * Whether a NUL byte in undeclared input fails the import as binary data (or BOM-less UTF-16)
+     * even where the bytes are valid UTF-8: for formats whose grammar never reports a NUL itself
+     * (CSV). False by default, so a format's own syntax error names it.
+     */
+    readonly nulIsBinary?: boolean | undefined;
 }
 /**
  * The canonical name of an encoding label, or null when the platform's TextDecoder does not know it.
  * @param label - a WHATWG encoding label ("latin1", "UTF-16LE", "cp1252", ...)
  * @returns the canonical name ("windows-1252", "utf-16le", ...) or null
+ * @category Plugin helpers
  */
 export declare function canonicalEncoding(label: string): string | null;
 /**
- * A zip entry name as text (APPNOTE 4.4.17): UTF-8 when the bytes are valid UTF-8, whether or not
- * the entry sets the language-encoding flag (bit 11), else windows-1252 (WHATWG has no CP437, and
- * session entry names are ASCII in practice). Never throws: a name is a matching key, never a path,
- * so an undecodable one still has to name its entry.
+ * What a head is when it is a known file type that is no graph format: compressed or archived data,
+ * an image, a PDF, an HTML page. Graph formats are text (or, for a Cytoscape session, a zip the
+ * registry hands to its own importer), so such an input is never read as text.
+ * @param head - the first bytes or characters of the input
+ * @returns a description such as "gzip-compressed data (decompress it first)", or null
+ * @category Plugin helpers
+ */
+export declare function foreignKind(head: Uint8Array | string): string | null;
+/**
+ * A zip entry name as text (APPNOTE 4.4.17 and appendix D): UTF-8 when the bytes are valid UTF-8,
+ * whether or not the entry sets the language-encoding flag (bit 11); otherwise code page 437 when
+ * the flag is clear (what Windows and older tools write), and windows-1252 when the entry claims
+ * UTF-8 (or no flags are known). Never throws: a name is a matching key, never a path, so an
+ * undecodable one still has to name its entry.
  * @param bytes - the name bytes from the central directory or a local header
+ * @param cp437 - the entry's bit 11 is clear: decode a non-UTF-8 name as code page 437
  * @returns the name
+ * @category Plugin helpers
+ */
+export declare function decodeEntryName(bytes: Uint8Array, cp437?: boolean): string;
+/**
+ * The longest string V8 makes (2^29 - 24 UTF-16 code units); longer text cannot be one string.
+ * @category Plugin helpers
  */
-export declare function decodeEntryName(bytes: Uint8Array): string;
+export declare const MAX_TEXT_LENGTH: number;
 /**
  * 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
+ * @category Plugin helpers
  */
 export declare function isImportInput(input: unknown): input is ImportInput;
+/**
+ * The input as one of the ImportInput shapes, or E_UNSUPPORTED naming what was passed and how to
+ * pass it instead (an ArrayBuffer, a Blob, a fetch Response, null from a failed read).
+ * @param input - what the caller passed
+ * @returns the input (a Uint8Array from another realm re-viewed in this one)
+ * @category Plugin helpers
+ */
+export declare function normalizeInput(input: unknown): 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.
+ * null for a stream or an iterable.
  * @param input - the input
  * @returns the size, or null when unknown up front
+ * @category Plugin helpers
  */
 export declare function inputLength(input: ImportInput): number | null;
 /**
@@ -69,46 +125,79 @@ export declare function inputLength(input: ImportInput): number | null;
  * `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.
+ * all gets a synthesized AbortError.
  * @param signal - the signal, or null
+ * @category Writing a format
  */
 export declare function throwIfAborted(signal: AbortSignal | null | undefined): void;
+/**
+ * A promise that also settles when the signal fires, rejecting with its reason: a read that stalls
+ * (a network body that never delivers) cannot keep an aborted import pending. The caller checks
+ * the signal before calling.
+ * @param promise - the pending operation
+ * @param signal - the cancellation signal, or null
+ * @returns the operation's result, or the abort reason as a rejection
+ * @category Plugin helpers
+ */
+export declare function abortable<T>(promise: Promise<T>, signal: AbortSignal | null): Promise<T>;
+/**
+ * A reader of a stream, or E_UNSUPPORTED when another reader holds the stream already.
+ * @param stream - the stream
+ * @returns the reader
+ * @category Plugin helpers
+ */
+export declare function lockReader(stream: ReadableStream<Uint8Array>): ReadableStreamDefaultReader<Uint8Array>;
 /**
  * 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
+ * The signal is checked before every chunk and while a stream read is pending; a stream is
+ * canceled when the consumer stops early or the signal fires. Progress is reported after every
+ * chunk, in bytes (text counted as UTF-8).
+ * @param rawInput - the input
+ * @param report - the report decode errors and the text checks are recorded in (E_INVALID_UTF8,
+ * E_EMPTY_INPUT, ... then ImportError)
+ * @param options - cancellation, progress and the encoding
+ * @yields decoded text; leading BOMs and a trailing Ctrl-Z removed
  * @returns nothing
+ * @category Writing a format
  */
-export declare function textChunks(input: ImportInput, report: ImportReportBuilder, options?: ReadOptions): AsyncGenerator<string, void, undefined>;
+export declare function textChunks(rawInput: ImportInput, report: ImportReportBuilder, options?: ReadOptions): AsyncGenerator<string, void, undefined>;
 /**
  * Read the whole input as bytes, for a binary format (a zip): nothing is decoded. The signal is
- * checked before every chunk and progress reported after it; a stream is cancelled when the read
+ * checked before every chunk and progress reported after it; a stream is canceled when the read
  * stops early.
- * @param input - the input
+ * @param rawInput - the input
  * @param options - cancellation and progress (the encoding is ignored)
  * @returns the bytes, or null when the input is text (a string, or a chunk that is a string),
  * which a binary format cannot read
  */
-export declare function readBytes(input: ImportInput, options?: ReadOptions): Promise<Uint8Array | null>;
+export declare function readBytes(rawInput: ImportInput, options?: ReadOptions): Promise<Uint8Array | null>;
 /**
- * Read the whole input as one string (the GML / DOT / JSON path, design section 8.4).
- * @param input - the input
+ * Fail an import whose text is longer than one JavaScript string can hold.
+ * @param report - the report
+ * @param message - what is too long
+ * @param line - the line, when known
+ * @category Plugin helpers
+ */
+export declare function tooLarge(report: ImportReportBuilder, message: string, line?: number): never;
+/**
+ * Read the whole input as one string (what the GML, DOT and JSON importers do), failing with
+ * E_TOO_LARGE (category unsupported) before the join when it is longer than one JavaScript string
+ * can hold. A string input is used as it is (one progress call), after the same text checks.
+ * @param rawInput - 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
+ * @returns the decoded text without a leading BOM or a trailing Ctrl-Z
+ * @category Writing a format
  */
-export declare function readText(input: ImportInput, report: ImportReportBuilder, options?: ReadOptions): Promise<string>;
+export declare function readText(rawInput: 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).
+ * @category Writing a format
  */
 export declare class LineReader implements AsyncIterable<string> {
     private readonly input;
@@ -127,6 +216,11 @@ export declare class LineReader implements AsyncIterable<string> {
      * @returns the line number; 0 before the first line
      */
     get line(): number;
+    /**
+     * The E_TOO_LARGE message of a line longer than one string.
+     * @returns the message
+     */
+    private lineTooLong;
     /**
      * Iterate the lines.
      * @yields one line at a time, terminator removed

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

@@ -1 +1 @@
-{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../../src/common/input.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAiD,iBAAiB,EAAyB,MAAM,YAAY,CAAC;AACrH,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;IAC5F,qGAAqG;IACrG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC9C;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;CAC7E;AAQD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM9D;AA2MD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAMzD;AA8BD;;;;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,CAmGzC;AA4CD;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CA6BzG;AAED;;;;;;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"}
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../../src/common/input.ts"],"names":[],"mappings":"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"}