@graphty/graph-io 0.3.18 → 0.3.19

package/dist/obo.js

@@ -1,4 +1,4 @@
-import { O, o } from "./chunks/importer-aNJfe0qu.js";
+import { O, o } from "./chunks/importer-ByPGO-09.js";
 export {
   O as OBO_ISSUE,
   o as oboImporter

package/dist/pajek.js

@@ -1,4 +1,4 @@
-import { P, a, p, b } from "./chunks/importer-d0uQxFp6.js";
+import { P, a, p, b } from "./chunks/importer-BVGtU1NA.js";
 export {
   P as PAJEK_ISSUE,
   a as PAJEK_LOSS,

package/dist/src/common/json-elements.d.ts

@@ -0,0 +1,286 @@
+/**
+ * The JSON reading the two CX formats share (design section 1.0 of
+ * design/graph-io/cytoscape-and-obo/design.md): the exact-integer rewrite (also used by the JSON
+ * importer), a streaming scanner that walks a CX document's top-level array and hands over each
+ * aspect element as soon as its closing brace arrives (section 1.2.5), and the CX id rule of
+ * section 1.0.2.
+ *
+ * The scanner never holds the document as one string, so a file larger than the longest string a
+ * JavaScript engine can hold is still read: it keeps the text of the element being read and
+ * nothing else. Each element is parsed with `JSON.parse`; an integer literal beyond 2^53 is kept as
+ * an ExactInteger (its digits) so an id never loses a digit.
+ */
+import { type ColumnDecl, type ColumnHandle, type GraphSink, type NodeId } from "@graphty/graph-format";
+import { type ImportReportBuilder } from "./report.js";
+/** A run of 16 digits not inside a fraction: the shortest integer literal that can exceed 2^53 (9007199254740992). */
+export declare const MAYBE_UNSAFE_INTEGER: RegExp;
+/** What rewriteNumbers() found. */
+interface RewrittenNumbers {
+    /** The rewritten text. */
+    readonly text: string;
+    /** The non-standard tokens seen (only when they were allowed). */
+    readonly tokens: Set<string>;
+    /** The integer literals beyond 2^53 that were quoted. */
+    readonly bigIntegers: string[];
+}
+/**
+ * Rewrite the numbers JSON.parse cannot read exactly, outside strings and in value positions only:
+ * NaN / Infinity / -Infinity become sentinel strings (when `nonstandard` is true), an integer
+ * literal that is not a safe integer becomes a string of its digits (or, with `exactSentinel`, a
+ * sentinel string reviveExact() turns into an ExactInteger). A container stack tells a value
+ * position (after `:`, `[`, or `,` inside an array) from a key position, so `{NaN: 1}` stays invalid.
+ * @param text - the document text
+ * @param options - which rewrites apply
+ * @param options.nonstandard - rewrite NaN / Infinity / -Infinity (default true)
+ * @param options.exactSentinel - quote big integers as sentinels instead of bare digits (default false)
+ * @returns the rewritten text, the non-standard tokens seen and the integer literals quoted
+ */
+export declare function rewriteNumbers(text: string, options?: {
+    readonly nonstandard?: boolean;
+    readonly exactSentinel?: boolean;
+}): RewrittenNumbers;
+/**
+ * The JSON.parse reviver that turns the non-standard sentinel strings of rewriteNumbers() back into
+ * numbers.
+ * @param _key - the member key (unused)
+ * @param value - the parsed value
+ * @returns the number for a sentinel string, the value otherwise
+ */
+export declare function reviveNonstandard(_key: string, value: unknown): unknown;
+/** An integer literal beyond 2^53, kept as its exact digits (a CX id must never lose a digit). */
+export declare class ExactInteger {
+    /** The digits, with a leading minus for a negative value. */
+    readonly digits: string;
+    /**
+     * Wrap the digits of an integer literal.
+     * @param digits - the literal
+     */
+    constructor(digits: string);
+    /**
+     * The nearest number (JSON.stringify writes it as such).
+     * @returns the number
+     */
+    toJSON(): number;
+}
+/**
+ * Parse one JSON value, keeping integer literals beyond 2^53 as ExactInteger.
+ * @param text - the JSON text
+ * @returns the value and whether it may hold an ExactInteger; SyntaxError when it is not JSON
+ */
+export declare function parseExact(text: string): {
+    readonly value: unknown;
+    readonly exact: boolean;
+};
+/**
+ * A parsed value with every ExactInteger replaced by its nearest number, for metadata and for
+ * values that are not ids.
+ * @param value - the value
+ * @param onPrecision - called with the digits of each integer that lost precision
+ * @returns the plain JSON value
+ */
+export declare function plainJson(value: unknown, onPrecision?: (digits: string) => void): unknown;
+/** A problem with the document's JSON; the importer turns it into a fatal E_SYNTAX or E_EMPTY_INPUT. */
+export declare class JsonScanError extends Error {
+    /** The 1-based line of the problem. */
+    readonly line: number;
+    /** Whether the document holds nothing but whitespace. */
+    readonly empty: boolean;
+    /**
+     * Create the error.
+     * @param message - what is wrong
+     * @param line - the 1-based line
+     * @param empty - whether the input is empty
+     */
+    constructor(message: string, line: number, empty?: boolean);
+}
+/** One thing the scanner found in a CX document. */
+export type AspectEvent = {
+    /** A top-level value that is not an array: the whole document, parsed. */
+    readonly kind: "root";
+    readonly value: unknown;
+    readonly line: number;
+} | {
+    /** A member `{"<aspect>": [` whose elements follow one by one. */
+    readonly kind: "block";
+    readonly aspect: string;
+    readonly block: number;
+    readonly line: number;
+} | {
+    /** One element of the current block, parsed. */
+    readonly kind: "element";
+    readonly aspect: string;
+    readonly block: number;
+    readonly value: unknown;
+    /** Whether the value may hold an ExactInteger. */
+    readonly exact: boolean;
+    /** The element's JSON text (for lexical checks of its ids). */
+    readonly text: string;
+    readonly line: number;
+} | {
+    /** Keys after the first one of a block member (`{"nodes": [...], "edges": [...]}`); their values were skipped. */
+    readonly kind: "extraKeys";
+    readonly aspect: string;
+    readonly block: number;
+    readonly keys: readonly string[];
+    readonly line: number;
+} | {
+    /**
+     * An element, or a member, nested deeper than MAX_ELEMENT_DEPTH: not parsed, so nothing
+     * downstream recurses into it (aspect: the block's aspect, null for a member).
+     */
+    readonly kind: "deep";
+    readonly aspect: string | null;
+    readonly block: number;
+    readonly depth: number;
+    readonly line: number;
+} | {
+    /** Any other member of the top-level array (a CX2 descriptor, `{"ndexStatus": {...}}`, `1`), parsed. */
+    readonly kind: "member";
+    readonly block: number;
+    readonly value: unknown;
+    readonly exact: boolean;
+    readonly line: number;
+};
+/**
+ * Walk a CX document (CX1 or CX2): a top-level array of members, each normally a one-key object
+ * `{"<aspect>": [elements]}`. The elements of such a block are parsed and yielded one at a time;
+ * any other member is parsed whole and yielded as a "member". A document that is not an array is
+ * yielded as one "root" event. Syntax errors throw JsonScanError.
+ * @param chunks - the decoded text
+ * @yields the events in document order
+ * @returns nothing
+ */
+export declare function scanAspects(chunks: AsyncIterable<string>): AsyncGenerator<AspectEvent, void, undefined>;
+/**
+ * Report an element or member the scanner refused for its depth (E_BAD_ASPECT_BLOCK; skipped).
+ * @param report - the report
+ * @param event - the "deep" event
+ */
+export declare function reportTooDeep(report: ImportReportBuilder, event: Extract<AspectEvent, {
+    kind: "deep";
+}>): void;
+/** How an id was spelled, when it was not a plain safe integer. */
+type CxIdNote = "text" | "precision" | null;
+/** A CX id, decided per id: a safe integer is a number, a larger one its exact digits. */
+interface CxId {
+    /** The node or edge id. */
+    readonly id: NodeId;
+    /** "text": spelled as a string or a non-integer literal (W_ID_TEXT_TYPE); "precision": beyond 2^53 (W_PRECISION). */
+    readonly note: CxIdNote;
+}
+/**
+ * Apply the CX id rule (design section 1.0.2) to a parsed value: a safe integer is the id; an
+ * integer beyond 2^53 is its exact digit string; a string spelling a decimal integer is that
+ * integer (as Jackson coerces it); anything else is E_INVALID_ID.
+ * @param raw - the parsed value
+ * @param inexactLiteral - whether the number was written as a non-integer literal (`5.0`, `1e3`)
+ * @returns the id and how it was spelled
+ */
+export declare function cxId(raw: unknown, inexactLiteral?: boolean): CxId;
+/**
+ * Whether the element text writes a top-level key's number as a non-integer literal (`"id": 5.0`,
+ * `"@id": 1e3`). A lexical check, so the parsed value (5) cannot tell. Only a key of the element
+ * itself counts, not one nested in its `v` (where `s` and `id` are ordinary attribute names).
+ * @param text - the element's JSON text
+ * @param key - the key
+ * @returns true when the literal holds a fraction or an exponent
+ */
+export declare function inexactLiteral(text: string, key: string): boolean;
+/** The name of the position column of every Cytoscape-family importer. */
+export declare const POSITION_COLUMN = "position";
+/**
+ * The position column of a Cytoscape-family importer: f32 x3, y-up, 2 source dimensions.
+ * @param format - the importer's format name
+ * @param sourceDims - 3 when z goes into the position (zAs "position")
+ * @returns the declaration
+ */
+export declare function positionDecl(format: string, sourceDims?: number): ColumnDecl;
+/**
+ * The stacking-order column `z` (f64, origin namespace "cytoscape").
+ * @param format - the importer's format name
+ * @returns the declaration
+ */
+export declare function zDecl(format: string): ColumnDecl;
+/**
+ * Cytoscape's screen y (growing downward) as graph-io's y (growing upward), and back: a negation
+ * that never yields -0.
+ * @param y - the coordinate
+ * @returns the flipped coordinate
+ */
+export declare function flipY(y: number): number;
+/**
+ * The order, metadata and status rules CX1 and CX2 share (design section 1.0.1): a third
+ * `metaData` or an aspect after the post-metadata or after `status` is W_ASPECT_ORDER; declared
+ * element counts are compared with what was read (W_COUNT_MISMATCH); `status.success: false` is
+ * fatal (E_STATUS_FAILED) and `success: true` with an error text a warning (W_STATUS_WARNING).
+ */
+export declare class CxStructure {
+    private readonly report;
+    /** Elements read per aspect name. */
+    readonly counts: Map<string, number>;
+    /** Blocks read per aspect name. */
+    readonly blocks: Map<string, number>;
+    /** The element counts the metadata declares, by aspect name (a later declaration wins). */
+    private readonly declared;
+    private metaDataBlocks;
+    private networkBlocks;
+    private postMetadata;
+    private statusSeen;
+    /** The status element, when one was read. */
+    status: unknown;
+    /**
+     * Whether a status block was read.
+     * @returns true once a status block began
+     */
+    get hasStatus(): boolean;
+    /**
+     * Create the checker.
+     * @param report - the report
+     */
+    constructor(report: ImportReportBuilder);
+    /**
+     * Record the start of a block (or a member holding one aspect).
+     * @param aspect - the aspect name
+     * @param line - its line
+     */
+    block(aspect: string, line: number): void;
+    /**
+     * Record one element of a block; metaData and status elements are checked here.
+     * @param aspect - the aspect name
+     * @param value - the parsed element
+     * @param line - its line
+     */
+    element(aspect: string, value: unknown, line: number): void;
+    /**
+     * Check a status element: success false is fatal, an error text with success true a warning.
+     * @param value - the element
+     * @param line - its line
+     */
+    private readStatus;
+    /**
+     * Whether the status element is one object with a boolean success.
+     * @returns true for a well-formed status
+     */
+    statusWellFormed(): boolean;
+    /** Compare the declared element counts with what was read (W_COUNT_MISMATCH per aspect). */
+    checkCounts(): void;
+}
+/**
+ * Whether a value is a plain JSON object.
+ * @param value - any value
+ * @returns true for a non-null, non-array object
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Declare a column under a name no column of the table holds yet: a per-element visual property
+ * whose name an attribute already has gets `<name>#2` (W_COLUMN_RENAMED), even when the two share a
+ * shape, so the visual value never overwrites the attribute.
+ * @param sink - the sink
+ * @param domain - node or edge
+ * @param decl - the declaration
+ * @param report - the report the rename is recorded in
+ * @returns the handle
+ */
+export declare function declareFresh(sink: GraphSink, domain: "node" | "edge", decl: ColumnDecl, report: ImportReportBuilder): ColumnHandle;
+export {};
+//# sourceMappingURL=json-elements.d.ts.map

package/dist/src/common/json-elements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-elements.d.ts","sourceRoot":"","sources":["../../../src/common/json-elements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACH,KAAK,UAAU,EACf,KAAK,YAAY,EAEjB,KAAK,SAAS,EAEd,KAAK,MAAM,EACd,MAAM,uBAAuB,CAAC;AAW/B,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAIvD,sHAAsH;AACtH,eAAO,MAAM,oBAAoB,QAAyB,CAAC;AAqB3D,mCAAmC;AACnC,UAAU,gBAAgB;IACtB,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACnF,gBAAgB,CA+DlB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAMvE;AAED,kGAAkG;AAClG,qBAAa,YAAY;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;;OAGG;gBACS,MAAM,EAAE,MAAM;IAI1B;;;OAGG;IACH,MAAM,IAAI,MAAM;CAGnB;AAeD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAS7F;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAgBzF;AAID,wGAAwG;AACxG,qBAAa,aAAc,SAAQ,KAAK;IACpC,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAExB;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,UAAQ;CAM3D;AAED,oDAAoD;AACpD,MAAM,MAAM,WAAW,GACjB;IACI,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB,GACD;IACI,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB,GACD;IACI,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB,GACD;IACI,kHAAkH;IAClH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB,GACD;IACI;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB,GACD;IACI,wGAAwG;IACxG,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB,CAAC;AAuQR;;;;;;;;GAQG;AACH,wBAAuB,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,SAAS,CAAC,CA2C9G;AAoJD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,mBAAmB,EAAE,KAAK,EAAE,OAAO,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,CAO9G;AAID,mEAAmE;AACnE,KAAK,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;AAE5C,0FAA0F;AAC1F,UAAU,IAAI;IACV,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,qHAAqH;IACrH,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CAC3B;AAID;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,cAAc,UAAQ,GAAG,IAAI,CAe/D;AAeD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAwBjE;AAID,0EAA0E;AAC1E,eAAO,MAAM,eAAe,aAAa,CAAC;AAK1C;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,SAAI,GAAG,UAAU,CAWvE;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAQhD;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvC;AAOD;;;;;GAKG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAE7C,qCAAqC;IACrC,QAAQ,CAAC,MAAM,sBAA6B;IAE5C,mCAAmC;IACnC,QAAQ,CAAC,MAAM,sBAA6B;IAE5C,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IAEtD,OAAO,CAAC,cAAc,CAAK;IAE3B,OAAO,CAAC,aAAa,CAAK;IAE1B,OAAO,CAAC,YAAY,CAAS;IAE7B,OAAO,CAAC,UAAU,CAAS;IAE3B,6CAA6C;IAC7C,MAAM,EAAE,OAAO,CAAa;IAE5B;;;OAGG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;;OAGG;gBACS,MAAM,EAAE,mBAAmB;IAIvC;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IA8CzC;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAa3D;;;;OAIG;IACH,OAAO,CAAC,UAAU;IA4BlB;;;OAGG;IACH,gBAAgB,IAAI,OAAO;IAI3B,4FAA4F;IAC5F,WAAW,IAAI,IAAI;CAatB;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CACxB,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,mBAAmB,GAC5B,YAAY,CAcd"}