@graphty/graph-io 0.2.4 → 0.3.0

package/dist/src/types.d.ts

@@ -10,9 +10,10 @@
 import { type Dtype, type DuplicatePolicy, GraphFormatError, type GraphSink, type GraphSnapshot, type IdCoercion } from "@graphty/graph-format";
 /**
  * What an importer reads (design section 8.4): whole text, whole bytes, a byte stream (a browser
- * `File.stream()`, a fetch body) or an async iterable of text or byte chunks. Bytes are decoded as
- * UTF-8 with `fatal: true`, so an invalid sequence is a parse-error and never a silent U+FFFD that
- * could alias two ids.
+ * `File.stream()`, a fetch body) or an async iterable of text or byte chunks. Bytes are decoded
+ * strictly in the encoding the `encoding` option, a byte order mark or the file's own declaration
+ * names, else as UTF-8 (undeclared bytes that are not UTF-8 are read as windows-1252 with a
+ * warning), so an invalid sequence is a parse-error and never a silent U+FFFD that could alias two ids.
  */
 export type ImportInput = string | Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<string | Uint8Array>;
 /**
@@ -55,6 +56,13 @@ export interface CommonImportOptions {
     signal?: AbortSignal | undefined;
     /** Progress in bytes; `bytesTotal` is known for in-memory input only. */
     onProgress?: ((bytesDone: number, bytesTotal?: number) => void) | undefined;
+    /**
+     * The character encoding of byte input (a WHATWG label such as "utf-8", "windows-1252",
+     * "iso-8859-1", "utf-16le"); overrides the byte order mark and any encoding the file declares.
+     * Absent: a BOM decides, else the declaration (XML prolog, DOT `charset`), else UTF-8, and
+     * bytes that are not valid UTF-8 are read as windows-1252 with a warning. Ignored for text input.
+     */
+    encoding?: string | undefined;
 }
 /**
  * An importer plugin (design section 8.4): pushes scalars into the caller's sink in one pass and
@@ -83,6 +91,17 @@ export interface GraphImporter<Opts = unknown> {
      * @returns the import report
      */
     import(input: ImportInput, sink: GraphSink, options?: Opts & CommonImportOptions): Promise<ImportReport>;
+    /**
+     * Read every graph of an input that can hold several (a DOT file with several graphs, a
+     * Pajek project with several networks, a JGF `graphs` array), each into its own sink. An
+     * importer without this method reads one graph per input. `import()` reads the first graph
+     * and warns how many it skipped.
+     * @param input - the text, bytes or stream to read
+     * @param sinkFor - called once per graph, in document order, before that graph's first push
+     * @param options - format-specific and common options
+     * @returns one report per graph, in document order
+     */
+    importAll?(input: ImportInput, sinkFor: (index: number) => GraphSink, options?: Opts & CommonImportOptions): Promise<ImportReport[]>;
 }
 /**
  * What a format can express without loss (design section 8.5): the fidelity matrix of research

package/dist/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACH,KAAK,KAAK,EACV,KAAK,eAAe,EACpB,gBAAgB,EAChB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,UAAU,EAClB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC;AAEhH;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAChC;;;OAGG;IACH,GAAG,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAC7B,kHAAkH;IAClH,UAAU,CAAC,EAAE,IAAI,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;IAClD,mHAAmH;IACnH,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,gEAAgE;IAChE,cAAc,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IAC7C,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IAClD,uGAAuG;IACvG,gBAAgB,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;IAC9E,uFAAuF;IACvF,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,4GAA4G;IAC5G,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACvC,iGAAiG;IACjG,WAAW,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,CAAC;IACxC,gGAAgG;IAChG,IAAI,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAC;IACpC,wGAAwG;IACxG,iBAAiB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,0GAA0G;IAC1G,UAAU,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC9D,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,4FAA4F;IAC5F,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACjC,yEAAyE;IACzE,UAAU,CAAC,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IAC5E;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,IAAI,GAAG,OAAO;IACzC,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;OAIG;IACH,KAAK,CAAC,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC;IACjC;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,IAAI,GAAG,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACzG;;;;;;;;;OASG;IACH,SAAS,CAAC,CACN,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,SAAS,EACrC,OAAO,CAAC,EAAE,IAAI,GAAG,mBAAmB,GACrC,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAC/B,iDAAiD;IACjD,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,sBAAsB;IACtB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,kBAAkB;IAClB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;IACnD,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,KAAK,GAAG,SAAS,GAAG,SAAS,GAAG,eAAe,CAAC;IACpE,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,wCAAwC;IACxC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,oBAAoB;IACpB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,2BAA2B;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,gBAAgB,CAAC;IACtE,8BAA8B;IAC9B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACzB;AAED,mHAAmH;AACnH,MAAM,WAAW,QAAQ;IACrB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,gGAAgG;AAChG,MAAM,WAAW,mBAAmB;IAChC,kHAAkH;IAClH,WAAW,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC7C,iGAAiG;IACjG,gBAAgB,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,CAAC;CACtE;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,IAAI,GAAG,OAAO;IACzC,uBAAuB;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mCAAmC;IACnC,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;IAC1C;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,IAAI,GAAG,mBAAmB,GAAG,SAAS,QAAQ,EAAE,CAAC;IAC1F;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,IAAI,GAAG,mBAAmB,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;IACjG;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,IAAI,GAAG,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAClG;AAED,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GACrB,aAAa,GAAG,eAAe,GAAG,kBAAkB,GAAG,aAAa,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE/G,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IACxB,oBAAoB;IACpB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,gFAAgF;AAChF,MAAM,WAAW,YAAY;IACzB,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sBAAsB;IACtB,QAAQ,CAAC,MAAM,EAAE;QACb,oBAAoB;QACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,oEAAoE;QACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,oCAAoC;QACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,oCAAoC;QACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,2EAA2E;QAC3E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;KAClC,CAAC;IACF,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,oCAAoC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,gBAAgB;IAC7C,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAE9B;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAKjG"}

package/dist/src/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAGH,gBAAgB,GAInB,MAAM,uBAAuB,CAAC;AAgO/B;;;;GAIG;AACH,MAAM,OAAO,WAAY,SAAQ,gBAAgB;IAI7C;;;;;OAKG;IACH,YAAY,OAAe,EAAE,MAAoB,EAAE,OAA2C;QAC1F,KAAK,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;CACJ"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAGH,gBAAgB,GAInB,MAAM,uBAAuB,CAAC;AAuP/B;;;;GAIG;AACH,MAAM,OAAO,WAAY,SAAQ,gBAAgB;IAI7C;;;;;OAKG;IACH,YAAY,OAAe,EAAE,MAAoB,EAAE,OAA2C;QAC1F,KAAK,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;CACJ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/graph-io",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Importers and exporters (GEXF, GraphML, GML, DOT, Pajek, CSV, JSON, Neo4j) for the @graphty/graph-format snapshot",
   "author": "Adam Powers <apowers@ato.ms>",
   "type": "module",
@@ -56,6 +56,7 @@
   "sideEffects": false,
   "files": [
     "dist/",
+    "!dist/*.tsbuildinfo",
     "src/",
     "README.md",
     "LICENSE"
@@ -91,7 +92,7 @@
   },
   "homepage": "https://github.com/graphty-org/graphty-monorepo/tree/master/graph-io#readme",
   "dependencies": {
-    "@graphty/graph-format": "^1.0.2"
+    "@graphty/graph-format": "^1.0.3"
   },
   "peerDependencies": {
     "@graphty/graph-format": "^1.0.0"
@@ -118,7 +119,7 @@
     "test:ui": "vitest --ui",
     "test:run": "vitest run",
     "coverage": "vitest run --coverage",
-    "coverage:preview": "npx serve coverage -p 9057",
+    "coverage:preview": "npx serve coverage -p ${PORT:?start it through servherd, which sets PORT}",
     "benchmark": "tsx benchmarks/run.ts",
     "ready:commit": "npm run build:all && npm run lint && npm run typecheck:strict-consumer && npm run test:run"
   }

package/src/common/codes.ts

@@ -75,6 +75,15 @@ export const OPTION_IGNORED_CODE = "W_OPTION_IGNORED";
 /** An invalid UTF-8 sequence in the input (fatal). */
 export const INVALID_UTF8_CODE = "E_INVALID_UTF8";
 
+/** Bytes that are not valid in the encoding a BOM, a declaration or the `encoding` option chose (fatal). */
+export const INVALID_ENCODING_CODE = "E_INVALID_ENCODING";
+
+/** Bytes that are not valid UTF-8 (and declare no other encoding) were read as windows-1252. */
+export const ENCODING_FALLBACK_CODE = "W_ENCODING_FALLBACK";
+
+/** The file declares an encoding the platform's TextDecoder does not know; the declaration is ignored. */
+export const UNKNOWN_ENCODING_CODE = "W_UNKNOWN_ENCODING";
+
 /** The sink refused the file's direction (locked or non-empty); the file is read as the sink's. */
 export const DIRECTION_REFUSED_CODE = "W_DIRECTION_REFUSED";
 

package/src/common/escape.ts

@@ -148,15 +148,16 @@ function isDotIdentifier(text: string): boolean {
 
 /**
  * Whether a text can be written as a DOT ID at all. Graphviz's scanner consumes a backslash pair
- * `\\` as one unit and `\"` as an escaped quote, left to right, so a backslash that precedes a
- * double quote or ends the text cannot be written: the written `\\"` reads as a pair and a closing
- * quote, and a trailing backslash escapes the closing quote. Every other text is writable;
- * quoteDotId() writes it.
+ * `\\` as one unit, `\"` as an escaped quote and a backslash before a line break as a line
+ * continuation (both removed), left to right, so a backslash that precedes a double quote or a
+ * line break, or ends the text, cannot be written: the written `\\"` reads as a pair and a closing
+ * quote, a backslash before a line break vanishes with the break, and a trailing backslash escapes
+ * the closing quote. Every other text is writable; quoteDotId() writes it.
  * @param text - the id, name or value text
  * @returns true when quoteDotId(text) reads back as `text`
  */
 export function isWritableDotText(text: string): boolean {
-    return !text.endsWith("\\") && !text.includes('\\"');
+    return !text.endsWith("\\") && !text.includes('\\"') && !/\\[\r\n]/.test(text);
 }
 
 /**

package/src/common/format.ts

@@ -9,14 +9,14 @@
 /**
  * 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
+ * @returns the text; "Infinity" / "-Infinity" / "NaN" for the non-finite values, "-0" for negative zero
  */
 export function formatF32(value: number): string {
     if (!Number.isFinite(value)) {
         return String(value);
     }
     if (value === 0) {
-        return "0";
+        return Object.is(value, -0) ? "-0" : "0";
     }
     for (let digits = 1; digits <= 9; digits++) {
         const text = value.toPrecision(digits);
@@ -29,12 +29,12 @@ export function formatF32(value: number): string {
 
 /**
  * The shortest text of an f64 value: `String(x)`, which is already the shortest round-tripping
- * decimal in JS.
+ * 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
+ * @returns the text; "Infinity" / "-Infinity" / "NaN" for the non-finite values, "-0" for negative zero
  */
 export function formatF64(value: number): string {
-    return String(value);
+    return Object.is(value, -0) ? "-0" : String(value);
 }
 
 /**

package/src/common/input.ts

@@ -1,19 +1,24 @@
 /**
  * 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.
+ * 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.
+ * 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
+ * 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.
  */
 
 import { GraphFormatError } from "@graphty/graph-format";
 
 import { type ImportInput } from "../types.js";
-import { INVALID_UTF8_CODE } from "./codes.js";
+import { ENCODING_FALLBACK_CODE, INVALID_ENCODING_CODE, INVALID_UTF8_CODE, UNKNOWN_ENCODING_CODE } from "./codes.js";
 import { type ImportReportBuilder } from "./report.js";
 
 export { INVALID_UTF8_CODE };
@@ -28,6 +33,251 @@ export interface ReadOptions {
     readonly signal?: AbortSignal | null | undefined;
     /** The progress callback, or null / undefined for none. */
     readonly onProgress?: ((bytesDone: number, bytesTotal?: number) => void) | null | undefined;
+    /** The caller's `encoding` option (a label TextDecoder knows), or null / undefined for detection. */
+    readonly encoding?: string | null | undefined;
+    /**
+     * The format's reader of a declared encoding: given the head of the input decoded as
+     * windows-1252 (ASCII-compatible), the encoding label it declares, or null.
+     */
+    readonly declaredEncoding?: ((head: string) => string | null) | undefined;
+}
+
+/** How many leading bytes the declaration check sees (an XML prolog, a DOT `charset` near the top). */
+const HEAD_BYTES = 1024;
+
+/** How many leading bytes the BOM check needs. */
+const BOM_BYTES = 3;
+
+/**
+ * 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
+ */
+export function canonicalEncoding(label: string): string | null {
+    try {
+        return new TextDecoder(label.trim()).encoding;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The encoding a byte order mark announces.
+ * @param head - the first bytes
+ * @returns "utf-8", "utf-16le", "utf-16be" or null
+ */
+function bomEncoding(head: Uint8Array): string | null {
+    if (head.byteLength >= 3 && head[0] === 0xef && head[1] === 0xbb && head[2] === 0xbf) {
+        return "utf-8";
+    }
+    if (head.byteLength >= 2 && head[0] === 0xff && head[1] === 0xfe) {
+        return "utf-16le";
+    }
+    if (head.byteLength >= 2 && head[0] === 0xfe && head[1] === 0xff) {
+        return "utf-16be";
+    }
+    return null;
+}
+
+/**
+ * The one byte decoder of an import: picks the encoding from the head (option, BOM, declaration,
+ * UTF-8) and decodes strictly, switching to windows-1252 with a warning when undeclared input
+ * turns out not to be UTF-8 while everything decoded so far was ASCII.
+ */
+class ByteDecoder {
+    private decoder: TextDecoder | null = null;
+
+    private encoding = "utf-8";
+
+    /** Whether a failed UTF-8 decode may switch to windows-1252 (nothing chose UTF-8 explicitly). */
+    private mayFallBack = false;
+
+    /** Whether every character decoded so far was ASCII (so switching encodings changes no earlier text). */
+    private asciiSoFar = true;
+
+    /** While asciiSoFar: the bytes the UTF-8 decoder holds back (a sequence split across chunks). */
+    private carry: Uint8Array = new Uint8Array(0);
+
+    /** Bytes decoded so far, for error positions. */
+    private offset = 0;
+
+    /**
+     * Create the decoder of one import.
+     * @param report - where warnings and the fatal decode error go
+     * @param options - the encoding option and the format's declaration reader
+     */
+    constructor(
+        private readonly report: ImportReportBuilder,
+        private readonly options: ReadOptions,
+    ) {}
+
+    /**
+     * Whether start() ran.
+     * @returns true once the encoding is chosen
+     */
+    get started(): boolean {
+        return this.decoder !== null;
+    }
+
+    /**
+     * Choose the encoding from the first bytes of the input.
+     * @param head - the first bytes (up to HEAD_BYTES; fewer when the input is shorter)
+     */
+    start(head: Uint8Array): void {
+        const explicit = this.options.encoding ?? null;
+        if (explicit !== null) {
+            this.use(explicit, false);
+            return;
+        }
+        const bom = bomEncoding(head);
+        if (bom !== null) {
+            this.use(bom, false);
+            return;
+        }
+        const declared = this.options.declaredEncoding?.(new TextDecoder("windows-1252").decode(head)) ?? null;
+        if (declared !== null) {
+            const canonical = canonicalEncoding(declared);
+            if (canonical === null) {
+                this.report.warning(
+                    "unsupported",
+                    UNKNOWN_ENCODING_CODE,
+                    `the input declares the encoding ${JSON.stringify(declared)}, which this platform cannot decode; reading it as UTF-8`,
+                    { element: declared },
+                );
+            } else if (canonical !== "utf-8" && !canonical.startsWith("utf-16")) {
+                // a declared UTF-16 without a BOM is not UTF-16 (its declaration read as ASCII), and
+                // a declared UTF-8 gets the same undeclared treatment: tools often write the default
+                // prolog over Latin-1 bytes
+                this.use(canonical, false);
+                return;
+            }
+        }
+        this.use("utf-8", true);
+    }
+
+    /**
+     * Decode the next bytes.
+     * @param bytes - the bytes
+     * @param stream - whether more bytes follow
+     * @returns the text
+     */
+    decode(bytes: Uint8Array, stream: boolean): string {
+        const decoder = this.decoder as TextDecoder;
+        let text: string;
+        try {
+            text = decoder.decode(bytes, { stream });
+        } catch (err) {
+            if (!(err instanceof TypeError)) {
+                throw err;
+            }
+            text = this.recover(bytes, stream);
+        }
+        if (this.asciiSoFar && this.mayFallBack) {
+            if (/[\u0080-\uffff]/.test(text)) {
+                this.asciiSoFar = false;
+                this.carry = new Uint8Array(0);
+            } else {
+                // every character so far is one ASCII byte, so what was not emitted is held back
+                const all = this.carry.byteLength === 0 ? bytes : concatBytes([this.carry, bytes]);
+                this.carry = all.slice(text.length);
+            }
+        }
+        this.offset += bytes.byteLength;
+        return text;
+    }
+
+    /**
+     * A decode failed: switch to windows-1252 when allowed, else fail the import.
+     * @param bytes - the bytes that failed
+     * @param stream - whether more bytes follow
+     * @returns the bytes decoded as windows-1252
+     */
+    private recover(bytes: Uint8Array, stream: boolean): string {
+        const where = { byteOffset: this.offset };
+        const all = this.carry.byteLength === 0 ? bytes : concatBytes([this.carry, bytes]);
+        // a NUL byte never occurs in windows-1252 text: it marks binary data (or BOM-less UTF-16)
+        if (this.mayFallBack && this.asciiSoFar && !all.includes(0) && !startsWithUtf8(all)) {
+            this.report.warning(
+                "coercion",
+                ENCODING_FALLBACK_CODE,
+                `the input is not valid UTF-8 (near byte ${this.offset}) and declares no encoding; read as windows-1252 (pass the encoding option to choose another)`,
+            );
+            this.use("windows-1252", false);
+            return (this.decoder as TextDecoder).decode(all, { stream });
+        }
+        if (this.encoding === "utf-8") {
+            const after = this.mayFallBack ? " after valid non-ASCII UTF-8 text; pass the encoding option" : "";
+            return this.report.fail(
+                INVALID_UTF8_CODE,
+                `invalid UTF-8 near byte ${this.offset}${after}`,
+                undefined,
+                where,
+            );
+        }
+        return this.report.fail(
+            INVALID_ENCODING_CODE,
+            `the bytes near byte ${this.offset} are not valid ${this.encoding}`,
+            undefined,
+            where,
+        );
+    }
+
+    /**
+     * Switch to an encoding.
+     * @param label - the encoding label
+     * @param mayFallBack - whether a UTF-8 failure may switch to windows-1252
+     */
+    private use(label: string, mayFallBack: boolean): void {
+        this.decoder = new TextDecoder(label, { fatal: true, ignoreBOM: true });
+        this.encoding = this.decoder.encoding;
+        this.mayFallBack = mayFallBack;
+    }
+}
+
+/**
+ * Whether the first non-ASCII byte of a chunk starts a valid UTF-8 sequence: then the chunk holds
+ * valid non-ASCII UTF-8 before whatever made it fail, and the input is not windows-1252.
+ * @param bytes - a chunk that failed to decode as UTF-8
+ * @returns true when its first non-ASCII sequence is valid UTF-8
+ */
+function startsWithUtf8(bytes: Uint8Array): boolean {
+    const i = bytes.findIndex((b) => b >= 0x80);
+    const lead = bytes[i];
+    let length = 0;
+    if (lead >= 0xc2 && lead <= 0xdf) {
+        length = 2;
+    } else if (lead >= 0xe0 && lead <= 0xef) {
+        length = 3;
+    } else if (lead >= 0xf0 && lead <= 0xf4) {
+        length = 4;
+    }
+    if (i < 0 || length === 0 || i + length > bytes.byteLength) {
+        return false;
+    }
+    try {
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(i, i + length));
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Join byte chunks.
+ * @param chunks - the chunks
+ * @returns one array holding them in order
+ */
+function concatBytes(chunks: readonly Uint8Array[]): Uint8Array {
+    if (chunks.length === 1) {
+        return chunks[0];
+    }
+    const out = new Uint8Array(chunks.reduce((sum, c) => sum + c.byteLength, 0));
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
 }
 
 /**
@@ -143,22 +393,13 @@ export async function* textChunks(
         onProgress?.(done, total ?? undefined);
         return;
     }
-    const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
-    const decode = (bytes: Uint8Array, stream: boolean): string => {
-        try {
-            return decoder.decode(bytes, { stream });
-        } catch (err) {
-            if (err instanceof TypeError) {
-                report.fail(INVALID_UTF8_CODE, `invalid UTF-8 near byte ${done}`, undefined, { byteOffset: done });
-            }
-            throw err;
-        }
-    };
+    const decoder = new ByteDecoder(report, options);
     if (input instanceof Uint8Array) {
+        decoder.start(input.subarray(0, HEAD_BYTES));
         for (let offset = 0; offset < input.byteLength; offset += DECODE_SLICE) {
             throwIfAborted(signal);
             const slice = input.subarray(offset, Math.min(offset + DECODE_SLICE, input.byteLength));
-            const text = emit(decode(slice, offset + DECODE_SLICE < input.byteLength));
+            const text = emit(decoder.decode(slice, offset + DECODE_SLICE < input.byteLength));
             done = Math.min(offset + DECODE_SLICE, input.byteLength);
             if (text.length > 0) {
                 yield text;
@@ -170,18 +411,42 @@ export async function* textChunks(
         }
         return;
     }
+    // the first bytes of a stream are held back until the BOM check (and the declaration check,
+    // when the format has one) can see enough of them, or the input ended, or text arrived, so a
+    // BOM or a declaration split across small chunks is still seen
+    const needed = options.declaredEncoding === undefined ? BOM_BYTES : HEAD_BYTES;
+    let head: Uint8Array[] = [];
+    let headLength = 0;
+    const flushHead = (stream: boolean): string => {
+        const bytes = concatBytes(head);
+        head = [];
+        headLength = 0;
+        decoder.start(bytes.subarray(0, HEAD_BYTES));
+        return decoder.decode(bytes, stream);
+    };
     const chunks = isReadableStream(input) ? streamChunks(input, signal) : input;
     for await (const chunk of chunks) {
         throwIfAborted(signal);
         let text: string;
         if (typeof chunk === "string") {
             // finish any byte sequence still pending in the decoder before switching to text
-            const pending = decode(new Uint8Array(0), false);
+            let pending = "";
+            if (!decoder.started && headLength > 0) {
+                pending = flushHead(false);
+            } else if (decoder.started) {
+                pending = decoder.decode(new Uint8Array(0), false);
+            }
             text = emit(pending + chunk);
             done += chunk.length;
         } else if (chunk instanceof Uint8Array) {
-            text = emit(decode(chunk, true));
             done += chunk.byteLength;
+            if (decoder.started) {
+                text = emit(decoder.decode(chunk, true));
+            } else {
+                head.push(chunk);
+                headLength += chunk.byteLength;
+                text = headLength >= needed ? emit(flushHead(true)) : "";
+            }
         } else {
             throw new GraphFormatError("E_UNSUPPORTED", "an input chunk must be a string or a Uint8Array", {
                 reason: "chunk type",
@@ -193,7 +458,13 @@ export async function* textChunks(
         }
         onProgress?.(done);
     }
-    const tail = emit(decode(new Uint8Array(0), false));
+    let tail = "";
+    if (!decoder.started && headLength > 0) {
+        tail = flushHead(false);
+    } else if (decoder.started) {
+        tail = decoder.decode(new Uint8Array(0), false);
+    }
+    tail = emit(tail);
     if (tail.length > 0) {
         yield tail;
     }

package/src/common/options.ts

@@ -9,6 +9,7 @@ import { type DuplicatePolicy, GraphFormatError, type GraphSink, type IdCoercion
 
 import { type CommonExportOptions, type CommonImportOptions } from "../types.js";
 import { OPTION_IGNORED_CODE, SINK_OPTION_CODE } from "./codes.js";
+import { canonicalEncoding } from "./input.js";
 import { type ImportReportBuilder } from "./report.js";
 
 /** The defaults an importer supplies for the options whose default is per format (design section 8.4). */
@@ -59,6 +60,8 @@ export interface ResolvedImportOptions {
     readonly signal: AbortSignal | null;
     /** The progress callback, or null. */
     readonly onProgress: ((bytesDone: number, bytesTotal?: number) => void) | null;
+    /** The caller's byte encoding (canonical name), or null to detect it. */
+    readonly encoding: string | null;
 }
 
 /** CommonExportOptions with every field present (design section 8.5 defaults applied). */
@@ -213,6 +216,7 @@ export function resolveImportOptions(
         errorLimit: errorLimitOption(o.errorLimit),
         signal: signalOption(o.signal),
         onProgress: progressOption(o.onProgress),
+        encoding: encodingOption(o.encoding),
     });
 }
 
@@ -350,6 +354,26 @@ function progressOption(value: unknown): ((bytesDone: number, bytesTotal?: numbe
     });
 }
 
+/**
+ * Resolve the encoding option: a label the platform's TextDecoder knows.
+ * @param value - the caller's value
+ * @returns the canonical encoding name, or null for detection
+ */
+function encodingOption(value: unknown): string | null {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const canonical = typeof value === "string" ? canonicalEncoding(value) : null;
+    if (canonical === null) {
+        throw new GraphFormatError(
+            "E_UNSUPPORTED",
+            `option encoding: ${describe(value)} is not an encoding this platform's TextDecoder knows`,
+            { option: "encoding", found: value },
+        );
+    }
+    return canonical;
+}
+
 /**
  * A short description of an option value for an error message.
  * @param value - the value

package/src/common/text.ts

@@ -277,7 +277,9 @@ export class TextCellWriter {
 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).
+ * The text dtype a parsed cell value implies on its own (what the sink's inference sees). It must
+ * be graph-format's inference rule exactly: -0 is an integer there, so a column holding only
+ * `-0.0` is inferred i32 and must be widened to f64, or the sign is lost.
  * @param value - the parsed value
  * @returns the dtype
  */
@@ -288,7 +290,5 @@ function kindOfValue(value: boolean | number | string): TextDtype {
     if (typeof value === "string") {
         return "string";
     }
-    return Number.isInteger(value) && value >= -2147483648 && value <= 2147483647 && !Object.is(value, -0)
-        ? "i32"
-        : "f64";
+    return Number.isInteger(value) && value >= -2147483648 && value <= 2147483647 ? "i32" : "f64";
 }

package/src/common/weights.ts

@@ -135,6 +135,9 @@ export interface ExplicitWeights {
     text(e: number, integral?: boolean): string | null;
 }
 
+/** A weight of -0 keeps its sign: every importer's weight grammar reads "-0" back as -0. */
+const NEGATIVE_ZERO_TEXT = "-0";
+
 /** 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"]);
 
@@ -175,6 +178,9 @@ export function explicitWeights(snapshot: GraphSnapshot): ExplicitWeights {
                     return null;
                 }
                 const value = shadow.value(e) as number;
+                if (Object.is(value, -0)) {
+                    return NEGATIVE_ZERO_TEXT;
+                }
                 return integral && Number.isInteger(value) ? formatInteger(value) : format(value);
             },
         };
@@ -196,6 +202,9 @@ export function explicitWeights(snapshot: GraphSnapshot): ExplicitWeights {
         value: (e: number): number => weights[e],
         text: (e: number, integral = false): string => {
             const value = weights[e];
+            if (Object.is(value, -0)) {
+                return NEGATIVE_ZERO_TEXT;
+            }
             return integral && Number.isInteger(value) ? formatInteger(value) : formatF32(value);
         },
     };