@graphty/graph-io 0.3.25 → 0.3.27

package/dist/src/common/escape.js

@@ -25,24 +25,26 @@ const XML_REPLACEMENTS = {
  * surrogate) has no XML spelling at all and is E_COLUMN_TYPE; the exporters' check() counts them.
  * @param text - the text
  * @returns the escaped text
+ * @category Plugin helpers
  */
 export function escapeXmlText(text) {
     if (hasIllegalXmlChar(text)) {
         throw illegalXml(text);
     }
-    return text.replace(XML_TEXT_SPECIAL, (c) => XML_REPLACEMENTS[c]);
+    return text.replaceAll(XML_TEXT_SPECIAL, (c) => XML_REPLACEMENTS[c]);
 }
 /**
  * Escape text for a double-quoted XML attribute value: `&`, `<`, `>`, `"` and the whitespace
- * characters attribute normalisation would fold; a character XML 1.0 forbids is E_COLUMN_TYPE.
+ * characters attribute normalization would fold; a character XML 1.0 forbids is E_COLUMN_TYPE.
  * @param text - the text
  * @returns the escaped text
+ * @category Plugin helpers
  */
 export function escapeXmlAttribute(text) {
     if (hasIllegalXmlChar(text)) {
         throw illegalXml(text);
     }
-    return text.replace(XML_ATTR_SPECIAL, (c) => XML_REPLACEMENTS[c]);
+    return text.replaceAll(XML_ATTR_SPECIAL, (c) => XML_REPLACEMENTS[c]);
 }
 /**
  * The error of a text no XML 1.0 document can carry.
@@ -63,9 +65,10 @@ const GML_SPECIAL = /["&]|[^ -~]/gu;
  * A lone surrogate cannot be written and is E_COLUMN_TYPE.
  * @param text - the text
  * @returns the quoted GML string
+ * @category Plugin helpers
  */
 export function quoteGmlString(text) {
-    const escaped = text.replace(GML_SPECIAL, (c) => {
+    const escaped = text.replaceAll(GML_SPECIAL, (c) => {
         const code = c.codePointAt(0);
         if (code === undefined) {
             return c;
@@ -103,18 +106,23 @@ const GML_NAMED = (() => {
 /**
  * Decode the character entities of a GML string body (the inverse of quoteGmlString on the text
  * between the quotes): numeric references, the XML entities and the ISO-8859-1 HTML entities. An
- * unknown named entity is left as written and handed to `onUnknown`.
+ * unknown named entity, or a numeric reference beyond U+10FFFF, is left as written and handed to
+ * `onUnknown`.
  * @param body - the text between the quotes
- * @param onUnknown - called with each unknown named entity (`&name;`), when given
+ * @param onUnknown - called with each entity left as written (`&name;`, `&#99999999;`), when given
  * @returns the decoded text
+ * @category Plugin helpers
  */
 export function decodeGmlString(body, onUnknown) {
-    return body.replace(GML_ENTITY, (whole, entity) => {
-        if (entity.startsWith("#x")) {
-            return String.fromCodePoint(Number.parseInt(entity.slice(2), 16));
-        }
+    return body.replaceAll(GML_ENTITY, (whole, entity) => {
         if (entity.startsWith("#")) {
-            return String.fromCodePoint(Number.parseInt(entity.slice(1), 10));
+            const code = entity.startsWith("#x") ? Number.parseInt(entity.slice(2), 16) : Number(entity.slice(1));
+            if (code <= 0x10ffff) {
+                return String.fromCodePoint(code);
+            }
+            // beyond Unicode: no character to decode to, kept as written like an unknown name
+            onUnknown?.(whole);
+            return whole;
         }
         const known = GML_NAMED.get(entity);
         if (known === undefined) {
@@ -131,6 +139,7 @@ const DOT_KEYWORDS = new Set(["node", "edge", "graph", "digraph", "subgraph", "s
  * a digit, or a numeral, and not a keyword (case-insensitive).
  * @param text - the text
  * @returns true when the text can be written bare
+ * @category Plugin helpers
  */
 export function isBareDotId(text) {
     if (DOT_KEYWORDS.has(text.toLowerCase())) {
@@ -167,6 +176,7 @@ function isDotIdentifier(text) {
  * 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`
+ * @category Plugin helpers
  */
 export function isWritableDotText(text) {
     return !text.endsWith("\\") && !text.includes('\\"') && !/\\[\r\n]/.test(text);
@@ -178,41 +188,46 @@ export function isWritableDotText(text) {
  * backslash has no DOT spelling (isWritableDotText); the caller refuses it before writing.
  * @param text - the id or label text
  * @returns the DOT ID
+ * @category Plugin helpers
  */
 export function quoteDotId(text) {
     if (isBareDotId(text)) {
         return text;
     }
-    return `"${text.replace(/"/g, '\\"')}"`;
+    const escaped = text.replaceAll('"', String.raw `\"`);
+    return `"${escaped}"`;
 }
 /**
- * Write a set CSV cell per RFC 4180: quoted with `"` doubled when the text contains the
- * delimiter, a quote, a CR or LF, or leading / trailing whitespace; bare otherwise. The empty
- * string is written as the quoted empty cell `""`, so the importers can tell a set empty string
- * (and an empty-string node id, legal under design section 4.1) from an unset cell, which every
- * exporter writes as nothing between the delimiters.
+ * Write a set CSV cell per RFC 4180: quoted, with the quote character doubled, when the text
+ * contains the delimiter, the quote character, a CR or LF, or leading / trailing whitespace; bare
+ * otherwise. The empty string is written as an empty quoted cell (`""`), so the importers can tell a
+ * set empty string (and an empty-string node id) from an unset cell, which every exporter writes as
+ * nothing between the delimiters.
  * @param text - the cell text of a set cell
  * @param delimiter - the field delimiter (default ",")
+ * @param quote - the quote character (default `"`)
  * @returns the cell as written
+ * @category Plugin helpers
  */
-export function quoteCsvCell(text, delimiter = ",") {
+export function quoteCsvCell(text, delimiter = ",", quote = '"') {
     if (text.length === 0) {
-        return '""';
+        return quote + quote;
     }
     if (!text.includes(delimiter) &&
-        !text.includes('"') &&
+        !text.includes(quote) &&
         !text.includes("\n") &&
         !text.includes("\r") &&
         text === text.trim()) {
         return text;
     }
-    return `"${text.replace(/"/g, '""')}"`;
+    return `${quote}${text.split(quote).join(quote + quote)}${quote}`;
 }
 /**
  * Whether a text can be a Pajek label: Pajek has no escape mechanism inside its double-quoted
  * labels, so a text containing a double quote, a CR or an LF cannot be written.
  * @param text - the label text
  * @returns true when quotePajekLabel() can write it
+ * @category Plugin helpers
  */
 export function isPajekLabel(text) {
     return !text.includes('"') && !text.includes("\n") && !text.includes("\r");
@@ -224,6 +239,7 @@ export function isPajekLabel(text) {
  * the exporter's check() counts those.
  * @param text - the label text
  * @returns the label as written
+ * @category Plugin helpers
  */
 export function quotePajekLabel(text) {
     if (!isPajekLabel(text)) {
@@ -232,7 +248,8 @@ export function quotePajekLabel(text) {
             value: text,
         });
     }
-    if (text.length > 0 && !/[\s"]/.test(text) && !text.startsWith("[")) {
+    // a bare `%` token starts a comment for the importer, so such a text is quoted too
+    if (text.length > 0 && !/[\s"]/.test(text) && !text.startsWith("[") && !text.startsWith("%")) {
         return text;
     }
     return `"${text}"`;

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

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

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

@@ -5,36 +5,63 @@
  * the ids the format cannot hold and hands the exporter the originals to write into its
  * `graphty:originalId` attribute).
  *
- * Every exporter's check() calls checkCapabilities() first and appends its format-specific notes
- * (design section 8.5 names W_GML_RECORD_NUMBER_TYPE and W_OPEN_INTERVAL); export() calls
+ * Every exporter's check() calls checkCapabilities() first and appends its format-specific notes;
+ * export() calls
  * sanitizeIds() before writing anything.
  */
-import { type Dtype, type GraphSnapshot, type NodeId } from "@graphty/graph-format";
+import { type Dtype, GraphFormatError, type GraphSnapshot, type IdCoercion, type NodeId } from "@graphty/graph-format";
 import { type ExportCapabilities, type LossNote } from "../types.js";
 import { type ResolvedExportOptions } from "./options.js";
-/** The shared LossNote codes of checkCapabilities(). */
+/**
+ * The shared LossNote codes of checkCapabilities().
+ * @category Issue and loss codes
+ */
 export declare const LOSS: Readonly<{
-    /** The format has no mixed direction; expanded pairs are written per onMixedDirection. */
+    /**
+     * A node or edge attribute is not written: the format has no attributes, or none of this kind
+     * (`CheckExtras.attributes` false).
+     */
+    COLUMN_DROPPED: "W_COLUMN_DROPPED";
+    /**
+     * The graph has both directed and undirected edges, the format holds one direction per file, and
+     * `onMixedDirection` is "directed" or "undirected": every edge is written with that direction.
+     */
     MIXED_DIRECTION: "W_MIXED_DIRECTION";
-    /** The format has no mixed direction and onMixedDirection is "error": export() will throw E_DIRECTED. */
+    /**
+     * The graph has both directed and undirected edges and `onMixedDirection` is "error". An import stops; a save to a
+     * format that holds one direction per file fails with E_DIRECTED. Pass "directed" or "undirected" to read or write
+     * it anyway.
+     */
     MIXED_DIRECTION_ERROR: "E_MIXED_DIRECTION";
     /** Parallel edges in a format without them. */
     MULTI_EDGES: "W_MULTI_EDGES";
     /** Self-loops in a format without them. */
     SELF_LOOPS: "W_SELF_LOOPS";
-    /** The format requires edge ids and the snapshot has none; canonical e0..e{E-1} are generated. */
+    /**
+     * The format needs an id on every edge and the graph has none, so the file gets ids e0, e1, e2 and so on, which
+     * read back as edge ids.
+     */
     EDGE_IDS_GENERATED: "W_EDGE_IDS_GENERATED";
-    /** The snapshot has an edge id column and the format cannot write one. */
+    /** The graph has edge ids and the format has no place for them, so they are not written. */
     EDGE_IDS_DROPPED: "W_EDGE_IDS_DROPPED";
     /** Ids outside the format's charset are rewritten (sanitizeIds "mangle"). */
     ID_MANGLED: "W_ID_MANGLED";
-    /** Ids outside the format's charset and sanitizeIds "error": export() will throw E_INVALID_ID. */
+    /**
+     * Node ids the format cannot write, under `sanitizeIds: "error"`; the save fails with E_INVALID_ID. Pass
+     * `sanitizeIds: "mangle"` to rewrite them.
+     */
     ID_CHARSET: "E_ID_CHARSET";
     /** The format numbers nodes 1..N; ids that are not their 1-based index are kept as labels only. */
     ID_RENUMBERED: "W_ID_RENUMBERED";
-    /** A column dtype the format does not keep as declared. */
+    /**
+     * An attribute's type is one the format cannot store as it is (for example, a 32-bit float in a format that has only 64-bit
+     * numbers), so it reads back with the nearest type the format has.
+     */
     DTYPE: "W_DTYPE_UNSUPPORTED";
-    /** A multi-component column in a format without strides. */
+    /**
+     * An attribute with several numbers per element (other than a position) is written as separate values or a list,
+     * and does not read back as one attribute.
+     */
     COMPONENTS: "W_COMPONENTS_FLATTENED";
     /** A list column in a format without lists. */
     LIST: "W_LIST_UNSUPPORTED";
@@ -48,9 +75,9 @@ export declare const LOSS: Readonly<{
     HIERARCHY: "W_HIERARCHY_DROPPED";
     /** A start / end / timestamp column in a format without temporal support. */
     TEMPORAL: "W_TEMPORAL_DROPPED";
-    /** A `<column>.text` companion (design section 5.1) the format cannot carry. */
+    /** A `<column>.text` companion the format cannot carry. */
     TEMPORAL_TEXT: "W_TEMPORAL_TEXT_DROPPED";
-    /** A role column the format has no slot for; written as a plain attribute, the role lost. */
+    /** An attribute with a role the format has no place for is written as a plain attribute; the role is lost. */
     ROLE: "W_ROLE_DROPPED";
     /** A parents (multi-parent) column in a format with single containment only. */
     PARENTS: "W_PARENTS_DROPPED";
@@ -60,31 +87,55 @@ export declare const LOSS: Readonly<{
     MUTUAL_AS_UNDIRECTED: "W_MUTUAL_AS_UNDIRECTED";
     /** Node ids whose written text reads back as the other type under the importer's id rule. */
     ID_TEXT_TYPE: "W_ID_TEXT_TYPE";
-    /** Two node ids share one written text; export() throws E_INVALID_ID. */
+    /**
+     * Two node ids would be written as the same text (the number 5 and the text "5"); the save fails with
+     * E_INVALID_ID.
+     */
     ID_TEXT_COLLISION: "E_ID_TEXT_COLLISION";
-    /** A plain column named like the importer's weight key reads back as THE weight. */
+    /**
+     * An attribute without the weight role is named like the attribute graph-io reads weights from (for example, `weight`), so
+     * it reads back as the edge weight.
+     */
     WEIGHT_KEY_CLASH: "W_WEIGHT_KEY_CLASH";
-    /** A role-less column whose written name the importer maps to a role. */
+    /**
+     * An attribute without a role is written where the format keeps a role (for example, a `name` column as the label), and
+     * reads back with that role.
+     */
     ROLE_ASSUMED: "W_ROLE_ASSUMED";
-    /** A role column written into the format's slot reads back under the importer's fixed name. */
+    /**
+     * An attribute with a role (for example, the label) is written where the format keeps that role, and reads back under the
+     * name the format's importer gives it.
+     */
     COLUMN_NAME_CHANGED: "W_COLUMN_NAME_CHANGED";
     /** A declared column whose every row is unset vanishes through a format without declarations. */
     EMPTY_COLUMN: "W_EMPTY_COLUMN_DROPPED";
-    /** A string / dict column that reads back as the other storage class (the dictionary heuristic). */
+    /**
+     * A text attribute reads back as a dictionary attribute, or the reverse, because the importer chooses by how often
+     * its values repeat. The values are the same.
+     */
     STORAGE_CLASS: "W_STORAGE_CLASS_CHANGED";
-    /** An f64 column whose set values are all integral reads back as i32 through an untyped format. */
+    /**
+     * A number attribute whose values are all whole numbers reads back as integers, because the format does not record
+     * the type.
+     */
     INTEGRAL_F64: "W_INTEGRAL_F64_AS_I32";
-    /** Text cells that read back as numbers or booleans under the 5.1 grammar. */
+    /**
+     * A text value that reads back as a number or a boolean, because the format does not record that it was text (the
+     * text "42" reads back as the number 42).
+     */
     TEXT_INFERRED: "W_TEXT_INFERRED";
-    /** A string cell holding a character XML 1.0 forbids; export() throws E_COLUMN_TYPE. */
+    /** A text value holds a character XML 1.0 forbids (most control characters); the save fails with E_COLUMN_TYPE. */
     XML_ILLEGAL_CHAR: "E_XML_ILLEGAL_CHAR";
-    /** A dict column without declared options gains one on re-import. */
+    /**
+     * A text attribute stored as a dictionary, without a declared list of allowed values, reads back with its distinct
+     * values as that list.
+     */
     OPTIONS_GAINED: "W_OPTIONS_GAINED";
     /** A spells column in a format without spells. */
     SPELLS: "W_SPELLS_DROPPED";
     /** Dynamic attribute values (extension tables) in a format without them. */
     DYNAMIC_VALUES: "W_DYNAMIC_VALUES_DROPPED";
-    /** An open-interval column in a format without open intervals (design section 5.1). */
+    /** An open-interval column in a format without open intervals. */
     OPEN_INTERVAL: "W_OPEN_INTERVAL";
     /** Graph-level attributes in a format without them. */
     GRAPH_ATTRIBUTES: "W_GRAPH_ATTRIBUTES_DROPPED";
@@ -94,26 +145,50 @@ export declare const LOSS: Readonly<{
     VIZ: "W_VIZ_DROPPED";
     /** An extension table the format cannot carry. */
     EXTENSION_TABLE: "W_EXTENSION_TABLE_DROPPED";
+    /** A NaN or infinite number the format cannot spell; not written (or written as null), it reads back unset. */
+    NONFINITE_AS_NULL: "W_NONFINITE_AS_NULL";
+    /**
+     * The graph has edge weights and the file does not keep them (the format has no weights, or an option turned them
+     * off): every edge reads back with the default weight 1.
+     */
+    WEIGHTS_DROPPED: "W_WEIGHTS_DROPPED";
 }>;
-/** The capabilities of a format that keeps nothing beyond plain topology; the base every exporter overrides. */
+/**
+ * The error a save throws for the first `E_` note of a check() result, or null when there is none.
+ * An exporter calls it before it writes anything, so every format refuses a save the same way: an
+ * id note (E_ID_CHARSET, E_ID_TEXT_COLLISION) throws E_INVALID_ID, E_MIXED_DIRECTION throws
+ * E_DIRECTED, E_XML_ILLEGAL_CHAR throws E_COLUMN_TYPE, and any other note E_UNSUPPORTED. Map your
+ * own note codes onto these with `codes`. The error's `details.code` is the note's code.
+ * @param notes - what check() returned
+ * @param codes - the error code for each of your own note codes, such as
+ *   `{ E_PAIRS_BAD_ID: "E_INVALID_ID" }`
+ * @returns the error to throw, or null
+ * @category Writing a format
+ */
+export declare function refusedSave(notes: readonly LossNote[], codes?: Readonly<Record<string, "E_INVALID_ID" | "E_DIRECTED" | "E_COLUMN_TYPE" | "E_UNSUPPORTED">>): GraphFormatError | null;
+/**
+ * The capabilities of a format that keeps nothing beyond plain topology; the base every exporter overrides.
+ * @category Plugin helpers
+ */
 export declare const NO_CAPABILITIES: ExportCapabilities;
 /**
  * Build a capabilities table from the fields a format supports; every field left out is the
  * conservative NO_CAPABILITIES value, so an exporter states what it keeps and nothing is assumed.
  * @param supported - the fields the format supports
  * @returns a frozen table
+ * @category Writing a format
  */
 export declare function capabilities(supported: Partial<ExportCapabilities>): ExportCapabilities;
 /**
- * Format facts checkCapabilities() needs that the 12.4 table does not carry.
- * Consumed by the per-format importers and exporters under src/formats.
+ * Format facts checkCapabilities() needs that the capabilities table does not carry.
  * @public
+ * @category Writing a format
  */
 export interface CheckExtras {
     /** Whether the format can write open intervals (GEXF 1.2 startopen / endopen); default false. */
     readonly openIntervals?: boolean | undefined;
     /**
-     * Whether the format carries the `<column>.text` companions of design section 5.1 (the lexical
+     * Whether the format carries the `<column>.text` companion columns (the lexical
      * form of a temporal value); default false, and every companion is then reported as
      * W_TEMPORAL_TEXT_DROPPED.
      */
@@ -137,9 +212,37 @@ export interface CheckExtras {
      * importer gives it). Defaults to none.
      */
     readonly roleNames?: Readonly<Record<string, string>> | undefined;
+    /**
+     * False for a format that writes no node or edge attributes except the ones whose role is in
+     * `roles`: every other attribute column is reported once as W_COLUMN_DROPPED, instead of the
+     * type and role notes a written column gets. Default true. `nodeAttributes` and
+     * `edgeAttributes` override it for one kind.
+     */
+    readonly attributes?: boolean | undefined;
+    /** Like `attributes`, for node attributes only: false for a format that writes no node attributes. */
+    readonly nodeAttributes?: boolean | undefined;
+    /** Like `attributes`, for edge attributes only: false for a format that writes no edge attributes. */
+    readonly edgeAttributes?: boolean | undefined;
+    /**
+     * Columns the format writes although it writes no other attributes: a column a format option
+     * names, such as an edge label column. Keyed by `node` or `edge`. They get no W_COLUMN_DROPPED
+     * note; the type notes of a written column still apply.
+     */
+    readonly writtenColumns?: Readonly<Partial<Record<"node" | "edge", readonly string[]>>> | undefined;
+    /**
+     * False for a format (or an option) that writes no edge weights: a weighted graph gets one
+     * W_WEIGHTS_DROPPED note. Default true.
+     */
+    readonly weights?: boolean | undefined;
+    /**
+     * How the format's importer turns id text back into ids ("canonical" for most text formats), so
+     * an id that comes back with another type (the text "7" as the number 7) is reported as
+     * W_ID_TEXT_TYPE. Omit it when the format records each id's type.
+     */
+    readonly idsReadBack?: IdCoercion | undefined;
 }
 /**
- * The generic pre-flight of design section 8.5: compare a snapshot with a format's capabilities
+ * The generic pre-flight check: compare a snapshot with a format's capabilities
  * and return one LossNote per gap, with the shared codes of LOSS. Format-specific notes are the
  * exporter's to append.
  * @param snapshot - the snapshot about to be exported
@@ -147,6 +250,7 @@ export interface CheckExtras {
  * @param options - the resolved common export options
  * @param extras - format facts the capabilities table does not carry
  * @returns the notes, empty when the export is exact
+ * @category Writing a format
  */
 export declare function checkCapabilities(snapshot: GraphSnapshot, caps: ExportCapabilities, options: ResolvedExportOptions, extras?: CheckExtras): LossNote[];
 /**
@@ -154,6 +258,7 @@ export declare function checkCapabilities(snapshot: GraphSnapshot, caps: ExportC
  * expanded pair count once; an expanded self-loop has no mirror and counts once).
  * @param snapshot - the snapshot
  * @returns the count; 0 for an undirected snapshot or one without the directed role
+ * @category Plugin helpers
  */
 export declare function countMixedEdges(snapshot: GraphSnapshot): number;
 /**
@@ -161,18 +266,19 @@ export declare function countMixedEdges(snapshot: GraphSnapshot): number;
  * over the forward CSR; an undirected parallel edge is counted in both rows.
  * @param snapshot - the snapshot
  * @returns the count
+ * @category Plugin helpers
  */
 export declare function countParallelArcs(snapshot: GraphSnapshot): number;
 /**
  * The id charsets of ExportCapabilities.
- * Consumed by the per-format importers and exporters under src/formats.
  * @public
+ * @category Plugin helpers
  */
 export type IdCharset = ExportCapabilities["idCharset"];
 /**
- * The ids to write for every node after sanitising (design section 8.5).
- * Consumed by the per-format importers and exporters under src/formats.
+ * The ids to write for every node after sanitising.
  * @public
+ * @category Writing a format
  */
 export interface SanitizedIds {
     /** The charset applied. */
@@ -202,12 +308,14 @@ export interface SanitizedIds {
  * Whether a code point is an XML NameChar.
  * @param cp - the code point
  * @returns true when it may appear in an NMTOKEN
+ * @category Plugin helpers
  */
 export declare function isNameChar(cp: number): boolean;
 /**
  * Whether a text is an XML NMTOKEN (one or more NameChars; GraphML node and edge ids).
  * @param text - the text
  * @returns true for a non-empty text of NameChars
+ * @category Plugin helpers
  */
 export declare function isNmtoken(text: string): boolean;
 /**
@@ -215,6 +323,7 @@ export declare function isNmtoken(text: string): boolean;
  * @param id - the id
  * @param charset - the charset
  * @returns true when the id needs no rewriting ("dense-1-based" is never true: see sanitizeIds)
+ * @category Plugin helpers
  */
 export declare function isRepresentableId(id: NodeId, charset: IdCharset): boolean;
 /**
@@ -223,10 +332,11 @@ export declare function isRepresentableId(id: NodeId, charset: IdCharset): boole
  * @param snapshot - the snapshot
  * @param charset - the charset
  * @returns the count
+ * @category Plugin helpers
  */
 export declare function countUnrepresentableIds(snapshot: GraphSnapshot, charset: IdCharset): number;
 /**
- * Sanitise the node ids for a charset (design section 8.5). Under "error" any id the charset
+ * Sanitise the node ids for a charset. Under "error" any id the charset
  * cannot hold is E_INVALID_ID (details.reason "charset") and nothing is written; under "mangle"
  * such ids are rewritten deterministically and uniquely: NMTOKEN by replacing every other
  * character with `_` (an empty result becomes `_`) and suffixing `_2`, `_3`... on collision;
@@ -238,12 +348,14 @@ export declare function countUnrepresentableIds(snapshot: GraphSnapshot, charset
  * @param charset - the charset
  * @param mode - the resolved sanitizeIds option
  * @returns the ids to write
+ * @category Writing a format
  */
 export declare function sanitizeIds(snapshot: GraphSnapshot, charset: IdCharset, mode: "error" | "mangle"): SanitizedIds;
 /**
  * Rewrite a text as an NMTOKEN: every character that is not a NameChar becomes `_`.
  * @param text - the text
  * @returns a non-empty NMTOKEN
+ * @category Plugin helpers
  */
 export declare function mangleNmtoken(text: string): string;
 //# sourceMappingURL=export.d.ts.map

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

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