@graphty/graph-io 0.3.24 → 0.3.26

package/dist/src/common/writer.js

@@ -5,7 +5,11 @@
  * UTF-8 chunks of a bounded size, into `exportToString()`'s one string, or into a
  * `ReadableStream<Uint8Array>` for a caller that wants a stream.
  */
-/** The target size of one encoded chunk; parts are coalesced up to it and never split. */
+import { GraphFormatError } from "@graphty/graph-format";
+/**
+ * The target size of one encoded chunk; parts are coalesced up to it and never split.
+ * @category Plugin helpers
+ */
 export const DEFAULT_CHUNK_BYTES = 64 * 1024;
 /**
  * Encode text parts as UTF-8 chunks of about `chunkBytes` each. Small parts are coalesced; a part
@@ -15,6 +19,7 @@ export const DEFAULT_CHUNK_BYTES = 64 * 1024;
  * @param chunkBytes - the target chunk size in bytes
  * @yields UTF-8 chunks
  * @returns nothing
+ * @category Writing a format
  */
 export async function* encodeChunks(parts, chunkBytes = DEFAULT_CHUNK_BYTES) {
     const encoder = new TextEncoder();
@@ -41,6 +46,7 @@ export async function* encodeChunks(parts, chunkBytes = DEFAULT_CHUNK_BYTES) {
  * Join text parts into one string.
  * @param parts - the text parts
  * @returns the whole document
+ * @category Writing a format
  */
 export async function joinText(parts) {
     const collected = [];
@@ -53,6 +59,7 @@ export async function joinText(parts) {
  * Decode UTF-8 chunks back into one string (for tests and for callers holding an export() result).
  * @param chunks - the chunks
  * @returns the decoded text
+ * @category Plugin helpers
  */
 export async function decodeChunks(chunks) {
     const decoder = new TextDecoder("utf-8", { fatal: true });
@@ -67,6 +74,7 @@ export async function decodeChunks(chunks) {
  * Collect UTF-8 chunks into one Uint8Array.
  * @param chunks - the chunks
  * @returns the concatenated bytes
+ * @category Plugin helpers
  */
 export async function collectBytes(chunks) {
     const parts = [];
@@ -85,9 +93,10 @@ export async function collectBytes(chunks) {
 }
 /**
  * Wrap an async iterable of chunks as a ReadableStream, pulling one chunk per read and cancelling
- * the iterable when the stream is cancelled.
+ * the iterable when the stream is canceled.
  * @param chunks - the chunks
  * @returns a byte stream
+ * @category Saving
  */
 export function toReadableStream(chunks) {
     const iterator = chunks[Symbol.asyncIterator]();
@@ -105,4 +114,23 @@ export function toReadableStream(chunks) {
         },
     });
 }
+/**
+ * The indentation of one nesting level from an `indent` option: a number of spaces (0 to 16), or
+ * the text itself (spaces or tabs). The JSON and DOT exporters take the same option this way.
+ * @param value - the option value
+ * @param fallback - the indentation when the option is not given
+ * @returns the text of one level; "" for none
+ */
+export function indentUnit(value, fallback) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 16) {
+        return " ".repeat(value);
+    }
+    if (typeof value === "string" && /^[ \t]{0,16}$/.test(value)) {
+        return value;
+    }
+    throw new GraphFormatError("E_UNSUPPORTED", `option indent: ${typeof value === "string" || typeof value === "number" ? JSON.stringify(value) : typeof value} is not a number of spaces (0 to 16) or a string of spaces or tabs`, { option: "indent", found: typeof value === "string" || typeof value === "number" ? value : typeof value });
+}
 //# sourceMappingURL=writer.js.map

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

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

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

@@ -8,11 +8,13 @@
  * instead of re-reading the token from its `<`, and line numbers are counted from a cached next
  * line-break position, so a document without line breaks costs the same as one with them.
  *
- * What it handles: the XML declaration and processing instructions (skipped), comments (skipped),
+ * What it handles: the XML declaration and processing instructions (skipped), comments (skipped;
+ * a `--` inside one, which XML 1.0 forbids, is accepted: a comment carries no data and banner
+ * comments such as `<!-- ----- -->` are common in hand-written files),
  * CDATA sections (text), a DOCTYPE with an internal subset (skipped; entity declarations are not
  * expanded, so an unknown entity reference is a syntax error), the five predefined entities and
  * numeric character references (decimal and hexadecimal) in text and attribute values, attribute
- * value whitespace normalisation, end-of-line normalisation (CR LF and lone CR become LF), and
+ * value whitespace normalization, end-of-line normalization (CR LF and lone CR become LF), and
  * well-formedness: matching end tags, one root element, no text outside it, no duplicate
  * attributes, no unterminated markup at the end of the input. Namespaces are not resolved; element
  * and attribute names are reported as written (with their prefix).
@@ -26,15 +28,21 @@
  */
 import { type GraphSnapshot } from "@graphty/graph-format";
 import { type LossNote } from "../types.js";
-/** The events of the tokenizer; every callback is synchronous. */
+/**
+ * The events of the tokenizer; every callback is synchronous.
+ * @category Plugin helpers
+ */
 export interface XmlHandler {
     /**
      * An element starts (a self-closing element produces start then end).
      * @param name - the element name as written, prefix included
      * @param attrs - the attributes, entities decoded, in document order
      * @param line - the 1-based line of the `<`
+     * @param ns - the namespace URI the element's prefix (or the default namespace) is bound to:
+     * "" when the element is in no namespace, null when its prefix is undeclared or the name is not
+     * namespace-well-formed (a leading or trailing colon, two colons)
      */
-    start(name: string, attrs: ReadonlyMap<string, string>, line: number): void;
+    start(name: string, attrs: ReadonlyMap<string, string>, line: number, ns: string | null): void;
     /**
      * An element ends.
      * @param name - the element name
@@ -48,8 +56,17 @@ export interface XmlHandler {
      * @param line - the 1-based line where the run starts
      */
     text(text: string, line: number): void;
+    /**
+     * A DOCTYPE declaration (optional; its internal subset is never expanded).
+     * @param text - the declaration as written, from `<!DOCTYPE` to its `>`
+     * @param line - the 1-based line of the `<`
+     */
+    doctype?(text: string, line: number): void;
 }
-/** A well-formedness or syntax error, with the line it was found on. */
+/**
+ * A well-formedness or syntax error, with the line it was found on.
+ * @category Plugin helpers
+ */
 export declare class XmlSyntaxError extends Error {
     /** The 1-based line. */
     readonly line: number;
@@ -61,10 +78,22 @@ export declare class XmlSyntaxError extends Error {
     constructor(message: string, line: number);
 }
 /**
- * Opt-in repairs of two defects the Cytoscape XGMML writer is known to produce (research note
- * `research-xgmml.md` 3.8 and 5). Each is off unless its callback is given; GEXF and GraphML never
+ * The input holds no markup at all (empty, whitespace only, a byte order mark only): an importer
+ * reports it as E_EMPTY_INPUT rather than as a syntax error.
+ * @category Plugin helpers
+ */
+export declare class XmlEmptyInputError extends XmlSyntaxError {
+    /**
+     * Create the error.
+     * @param line - the 1-based line where the input ended
+     */
+    constructor(line: number);
+}
+/**
+ * Opt-in repairs of two defects the Cytoscape XGMML writer is known to produce. Each is off unless its callback is given; GEXF and GraphML never
  * pass them, so their documents stay strictly well-formed. The callback is told the line of each
  * repair, so the importer can warn per occurrence.
+ * @category Plugin helpers
  */
 export interface XmlRepairs {
     /**
@@ -87,6 +116,7 @@ export interface XmlRepairs {
  * written even as a character reference, so a conforming parser rejects the whole document.
  * @param text - the text
  * @returns true when the text cannot appear in an XML 1.0 document
+ * @category Plugin helpers
  */
 export declare function hasIllegalXmlChar(text: string): boolean;
 /**
@@ -96,6 +126,7 @@ export declare function hasIllegalXmlChar(text: string): boolean;
  * the first such text. Shared by the GEXF and GraphML exporters' check().
  * @param snapshot - the snapshot
  * @returns the notes, empty when every text is writable
+ * @category Plugin helpers
  */
 export declare function xmlIllegalTextNotes(snapshot: GraphSnapshot): LossNote[];
 /**
@@ -103,12 +134,22 @@ export declare function xmlIllegalTextNotes(snapshot: GraphSnapshot): LossNote[]
  * for the shared byte decoder (common/input.ts).
  * @param head - the start of the document, decoded as windows-1252
  * @returns the declared label, or null when there is no declaration or it names no encoding
+ * @category Plugin helpers
  */
 export declare function xmlDeclaredEncoding(head: string): string | null;
+/**
+ * The head of a document as text for an XML format's sniff(): UTF-16 when a byte order mark (or
+ * BOM-less UTF-16 `<?`, XML 1.0 Appendix F) says so, else UTF-8, never failing.
+ * @param head - the first bytes
+ * @returns the text, a leading byte order mark removed
+ * @category Plugin helpers
+ */
+export declare function sniffXmlText(head: Uint8Array): string;
 /**
  * Whether a text is an XML Name.
  * @param text - the text
  * @returns true for a well-formed name
+ * @category Plugin helpers
  */
 export declare function isXmlName(text: string): boolean;
 /**
@@ -117,18 +158,21 @@ export declare function isXmlName(text: string): boolean;
  * @param line - the line, for errors
  * @param repairs - the opt-in repairs (XGMML only); none by default
  * @returns the decoded text
+ * @category Plugin helpers
  */
 export declare function decodeEntities(raw: string, line: number, repairs?: XmlRepairs): string;
 /**
  * Whether a text is whitespace only.
  * @param text - the text
  * @returns true when every character is XML whitespace (also for an empty text)
+ * @category Plugin helpers
  */
 export declare function isWhitespace(text: string): boolean;
 /**
  * The local part of a possibly prefixed XML name.
  * @param name - the name as written
  * @returns the text after the last colon, or the name itself
+ * @category Plugin helpers
  */
 export declare function localName(name: string): string;
 /**
@@ -137,11 +181,13 @@ export declare function localName(name: string): string;
  * @param chunks - the text (already UTF-8 decoded, BOM removed)
  * @param handler - the event sink
  * @param repairs - the opt-in repairs (XGMML only); none by default
+ * @category Plugin helpers
  */
 export declare function tokenizeXml(chunks: AsyncIterable<string>, handler: XmlHandler, repairs?: XmlRepairs): Promise<void>;
 /**
  * The tokenizer state: the unconsumed tail of the input, the current line, the open element
  * stack and the text run being accumulated. `push()` chunks, then `finish()`.
+ * @category Plugin helpers
  */
 export declare class XmlTokenizer {
     private readonly handler;
@@ -166,6 +212,20 @@ export declare class XmlTokenizer {
     private readonly stack;
     private rootSeen;
     private rootClosed;
+    /** Whether any markup was consumed (an input with none is empty, not malformed). */
+    private markupSeen;
+    /** Whether nothing has been consumed yet: the XML declaration may only appear here. */
+    private atStart;
+    /** Whether a DOCTYPE declaration was read (one is allowed, in the prolog). */
+    private doctypeSeen;
+    /** The version of the XML declaration, or null. */
+    private version;
+    /** The last two characters of the character data since the last markup, for the `]]>` check. */
+    private textTail;
+    /** A high surrogate held back from the end of the previous chunk (its low half may start the next). */
+    private pendingHigh;
+    /** The namespace declarations in scope, innermost last. */
+    private readonly bindings;
     private readonly repairs;
     /**
      * Create a tokenizer.
@@ -173,6 +233,12 @@ export declare class XmlTokenizer {
      * @param repairs - the opt-in repairs (XGMML only); none by default
      */
     constructor(handler: XmlHandler, repairs?: XmlRepairs);
+    /**
+     * Whether the document's XML declaration says version 1.1 (read by the XML 1.0 rules all the
+     * same; the syntax error of a 1.1-only construct then says why).
+     * @returns true after a `<?xml version="1.1"?>` declaration
+     */
+    get declaresXml11(): boolean;
     /**
      * Feed one chunk and emit every complete token in it.
      * @param chunk - the text
@@ -181,9 +247,9 @@ export declare class XmlTokenizer {
     /** Signal the end of the input: flush the last text run and check well-formedness. */
     finish(): void;
     /**
-     * Append normalised text: continue a pending token's terminator scan over the new text alone,
+     * Append normalized text: continue a pending token's terminator scan over the new text alone,
      * and once the token is complete (or when none is pending) scan the buffer for tokens.
-     * @param text - the text, line breaks normalised
+     * @param text - the text, line breaks normalized
      */
     private feed;
     /**
@@ -233,6 +299,48 @@ export declare class XmlTokenizer {
      * @returns the index after the markup, or -1 when the buffer ends before the markup does
      */
     private consumeMarkup;
+    /**
+     * Read the markup starting at `pos` (a `<`) and deliver what it means.
+     * @param pos - the index of the `<`
+     * @returns the index after the markup, or -1 when the buffer ends before the markup does
+     */
+    private markupEnd;
+    /**
+     * Read the CDATA section at `pos` into the text.
+     * @param pos - the index of the `<`
+     * @returns the index after the section, or -1 when the buffer ends before the section does
+     */
+    private cdataEnd;
+    /**
+     * Read the `<!...>` markup at `pos`: a comment, a CDATA section or the DOCTYPE.
+     * @param pos - the index of the `<`
+     * @returns the index after the markup, or -1 when the buffer ends before the markup does
+     */
+    private declarationEnd;
+    /**
+     * Check a processing instruction `<?target ...?>` (skipped otherwise): its target must be a
+     * name, and the reserved target `xml` is the XML declaration, allowed only at the very start
+     * of the document with a 1.x version.
+     * @param pos - the index of the `<`
+     * @param end - the index of the `?>`
+     */
+    private processingInstruction;
+    /**
+     * The line of a buffer position after `start`, the position the current line count refers to.
+     * Used on the error path only.
+     * @param start - a position on line `this.line`
+     * @param at - the position
+     * @returns its line
+     */
+    private lineIn;
+    /**
+     * Decode the entities of a text, naming XML 1.1 when a character reference XML 1.0 forbids
+     * appears in a document that declares version 1.1.
+     * @param raw - the text as written
+     * @param line - the line the text starts on
+     * @returns the decoded text
+     */
+    private decode;
     /**
      * Parse a start tag at `pos`.
      * @param pos - the index of the `<`
@@ -275,8 +383,16 @@ export declare class XmlTokenizer {
      * Open an element.
      * @param name - the element name
      * @param attrs - its attributes
+     * @param declaresNamespace - whether an attribute name starts with `xmlns`
      */
     private startElement;
+    /**
+     * The namespace an element name is in (Namespaces in XML 1.0 section 6).
+     * @param name - the element name as written
+     * @returns the URI; "" for no namespace; null for an undeclared prefix or a name that is not
+     * namespace-well-formed
+     */
+    private namespaceOf;
     /**
      * Close an element, checking that it matches the innermost open one.
      * @param name - the element name

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

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