@graphty/graph-format 0.0.0 → 0.2.0

package/src/errors.ts

@@ -0,0 +1,115 @@
+/**
+ * The error class and the closed set of error codes of @graphty/graph-format (design section 11).
+ *
+ * Policy (design section 11.1): the builder and the constructors throw on malformed input, on the
+ * first error, with a GraphFormatError carrying a stable `code`; snapshot methods that take an index
+ * are total for in-range arguments and unchecked otherwise; only GraphFormatError instances are ever
+ * thrown by this package. Messages are plain ASCII and name the offending index, id or value when it
+ * is a number or a short string. ImportError (code E_IMPORT) is declared by @graphty/graph-io.
+ */
+
+/**
+ * The closed union of error codes a GraphFormatError can carry (design section 11.2). Each code is
+ * stable across versions and is the value consumers branch on; the message is for humans.
+ *
+ * - E_INVALID_ID: NaN, a non-finite number, a bigint, an object, null, undefined or a string with a
+ *   lone surrogate used as an id (details.reason "lone surrogate").
+ * - E_UNKNOWN_NODE: addEdge with addMissingNodes false, addEdgeByIndex with a dead or out-of-range
+ *   index (details.index), or a requireIndex miss.
+ * - E_INDEX_RANGE: ids.idOf / table.value out of range; inducedSubgraph with a repeated or
+ *   out-of-range index.
+ * - E_TOO_LARGE: nodeCount, edgeCount or arcCount would exceed MAX_COUNT.
+ * - E_INVALID_WEIGHT: a NaN weight at addEdge / setEdgeWeight / addEdges.
+ * - E_DIRECTED: mate() on a directed snapshot; setDirected() refused (locked, or a change the edge
+ *   set does not allow).
+ * - E_SELF_LOOP: a self-loop under selfLoops "error".
+ * - E_DUPLICATE_EDGE: a parallel edge under duplicateEdges "error" (details source, target, edges).
+ * - E_DUPLICATE_EDGE_ID: a unique role "id" edge column violated (both edge indices in details).
+ * - E_DUPLICATE_ID: a unique node column violated; addGraph with onDuplicateNode "error"; a
+ *   repeated id in the `ids` array or F64 given to fromEdgeArrays / fromCsr.
+ * - E_DUPLICATE_ROLE: two columns with the same role in one table.
+ * - E_UNKNOWN_COLUMN: require() of an absent column.
+ * - E_COLUMN_TYPE: requireTyped() dtype mismatch; a non-JSON default / fill / options / extra value
+ *   (details.field); a string value with a lone surrogate.
+ * - E_COLUMN_LENGTH: set() with data.length !== rowCount * components.
+ * - E_COLUMN_ALIGNMENT: a u8 array without a constructible padded u32 view under adopt "strict".
+ * - E_COLUMN_EXISTS: declareNodeColumn / declareEdgeColumn twice with a different declaration.
+ * - E_COLUMN_IMMUTABLE: mutableData() / markDirty() / mutableValidity() / setAll() on an immutable
+ *   column.
+ * - E_NO_DEFAULT: materializeDefault() on a column without a declared default.
+ * - E_PARTITION: contract() partition of the wrong length or holding INVALID_INDEX.
+ * - E_INVALID_PERMUTATION: relabel() with a perm that is not a permutation of 0..n-1.
+ * - E_MASK_LENGTH: filterEdges() / inducedSubgraph({ mask }) with a short mask.
+ * - E_GPU_INELIGIBLE: gpuView() / paddedU32View() on a string, list or json column.
+ * - E_INVALID_SNAPSHOT: validate() failure (details.invariant, row / arc / edge / column) or
+ *   validate({ checksum: true }) on a snapshot without recorded checksums (details.reason
+ *   "no-checksum").
+ * - E_BAD_SERIALIZATION: bad magic, endianness probe, manifest or buffer reference (details.ref).
+ * - E_UNSUPPORTED_VERSION: unknown wire major or formatVersion (details.kind "wire" | "format",
+ *   details.found, details.supported).
+ * - E_DETACHED: a core accessor after a consuming transfer.
+ * - E_BUILDER_DISPOSED: any call on a disposed builder.
+ * - E_UNSUPPORTED: big-endian host (details.reason); unknown wire dtype (details.dtype) or id-map
+ *   kind (details.kind).
+ * - E_IMPORT: reserved for @graphty/graph-io's ImportError.
+ */
+export type GraphFormatErrorCode =
+    | "E_INVALID_ID"
+    | "E_UNKNOWN_NODE"
+    | "E_INDEX_RANGE"
+    | "E_TOO_LARGE"
+    | "E_INVALID_WEIGHT"
+    | "E_DIRECTED"
+    | "E_SELF_LOOP"
+    | "E_DUPLICATE_EDGE"
+    | "E_DUPLICATE_EDGE_ID"
+    | "E_DUPLICATE_ID"
+    | "E_DUPLICATE_ROLE"
+    | "E_UNKNOWN_COLUMN"
+    | "E_COLUMN_TYPE"
+    | "E_COLUMN_LENGTH"
+    | "E_COLUMN_ALIGNMENT"
+    | "E_COLUMN_EXISTS"
+    | "E_COLUMN_IMMUTABLE"
+    | "E_NO_DEFAULT"
+    | "E_PARTITION"
+    | "E_INVALID_PERMUTATION"
+    | "E_MASK_LENGTH"
+    | "E_GPU_INELIGIBLE"
+    | "E_INVALID_SNAPSHOT"
+    | "E_BAD_SERIALIZATION"
+    | "E_UNSUPPORTED_VERSION"
+    | "E_DETACHED"
+    | "E_BUILDER_DISPOSED"
+    | "E_UNSUPPORTED"
+    | "E_IMPORT";
+
+const EMPTY_DETAILS: Readonly<Record<string, unknown>> = Object.freeze({});
+
+/**
+ * The only error type this package throws (design section 11.2). `code` is the stable, programmatic
+ * discriminator; `details` carries the machine-readable context named per code in the
+ * GraphFormatErrorCode documentation (index, id, edge, invariant, row, found, supported, ...) as a
+ * frozen shallow copy of what the thrower supplied. `name` is "GraphFormatError" so stack traces and
+ * test matchers read naturally.
+ */
+export class GraphFormatError extends Error {
+    /** The stable error code (design section 11.2). */
+    readonly code: GraphFormatErrorCode;
+
+    /** Machine-readable context for the failure; an empty frozen object when none was supplied. */
+    readonly details: Readonly<Record<string, unknown>>;
+
+    /**
+     * Create a GraphFormatError.
+     * @param code - the stable error code the caller can branch on
+     * @param message - a plain-ASCII human-readable message naming the offending index, id or value
+     * @param details - optional machine-readable context; copied shallowly and frozen
+     */
+    constructor(code: GraphFormatErrorCode, message: string, details?: Readonly<Record<string, unknown>>) {
+        super(message);
+        this.name = "GraphFormatError";
+        this.code = code;
+        this.details = details === undefined ? EMPTY_DETAILS : Object.freeze({ ...details });
+    }
+}

package/src/ids/edge-id-index.ts

@@ -0,0 +1,179 @@
+/**
+ * Edge ids are optional data, not structure (design section 4.6): an edge column with role "id"
+ * (dtype string, dict, u32 or f64 in practice; any scalar numeric dtype is read the same way) holds
+ * them, importers declare it `unique: true`, and `snapshot.edgeIndexOf(id)` resolves an id through
+ * a Map built lazily on the first call. This module owns that lazy index and the uniqueness check
+ * freeze runs over the SET rows of a unique id column (E_DUPLICATE_EDGE_ID with both edge indices).
+ * Equality is SameValueZero (a JS Map key), the same rule as node ids.
+ */
+
+import { INVALID_INDEX } from "../constants.js";
+import { GraphFormatError } from "../errors.js";
+import { type Column, type EdgeId } from "../types/index.js";
+
+/**
+ * The E_COLUMN_TYPE error for a column whose dtype cannot hold edge ids.
+ * @param column - the column
+ * @returns the error
+ */
+function unsupportedDtype(column: Column): GraphFormatError {
+    return new GraphFormatError(
+        "E_COLUMN_TYPE",
+        `column ${JSON.stringify(column.meta.name)} of dtype ${column.dtype} cannot hold edge ids`,
+        { column: column.meta.name, dtype: column.dtype, reason: "edge id dtype" },
+    );
+}
+
+/**
+ * The id stored in one SET row of an edge id column: the decoded string of a string column, the
+ * dictionary value of a dict column, or the (first component of the) number of a numeric column.
+ * The caller has checked `column.isSet(row)`.
+ * @param column - the id column
+ * @param row - a set row
+ * @returns the id
+ */
+export function edgeIdOfRow(column: Column, row: number): EdgeId {
+    switch (column.dtype) {
+        case "string":
+            return column.valueAt(row);
+        case "dict":
+            return column.dictionary[column.codes[row]];
+        case "f32":
+        case "f64":
+        case "i32":
+        case "u32":
+        case "u8":
+            return column.data[row * column.meta.components];
+        case "bool":
+        case "list":
+        case "json":
+            throw unsupportedDtype(column);
+        default:
+            throw unsupportedDtype(column);
+    }
+}
+
+/**
+ * Whether a column's dtype can hold edge ids (string, dict or a scalar numeric dtype).
+ * @param column - the column
+ * @returns true when edgeIdOfRow can read it
+ */
+export function canHoldEdgeIds(column: Column): boolean {
+    switch (column.dtype) {
+        case "string":
+        case "dict":
+        case "f32":
+        case "f64":
+        case "i32":
+        case "u32":
+        case "u8":
+            return true;
+        case "bool":
+        case "list":
+        case "json":
+            return false;
+        default:
+            return false;
+    }
+}
+
+/**
+ * Build the id -> edge index map of an id column over its SET rows in one pass. When an id repeats
+ * the lowest edge index wins (a unique column never repeats; `findDuplicateEdgeId` reports it).
+ * @param column - the edge id column
+ * @returns a fresh Map from id to logical edge index
+ */
+export function buildEdgeIdMap(column: Column): Map<EdgeId, number> {
+    if (!canHoldEdgeIds(column)) {
+        throw unsupportedDtype(column);
+    }
+    const map = new Map<EdgeId, number>();
+    const rows = column.length;
+    for (let e = 0; e < rows; e++) {
+        if (!column.isSet(e)) {
+            continue;
+        }
+        const id = edgeIdOfRow(column, e);
+        if (!map.has(id)) {
+            map.set(id, e);
+        }
+    }
+    return map;
+}
+
+/**
+ * The lazily built index behind `snapshot.edgeIndexOf(id)` (design section 4.6): a Map from id to
+ * logical edge index over the set rows of the role "id" edge column, built on the first lookup and
+ * rebuilt when a mutable column's `version` has changed since.
+ */
+export class EdgeIdIndex {
+    /** The edge id column. */
+    private readonly column: Column;
+
+    /** The map, or null before the first lookup. */
+    private map: Map<EdgeId, number> | null;
+
+    /** column.version when the map was built. */
+    private builtVersion: number;
+
+    /**
+     * Wrap an edge id column; nothing is built until the first lookup.
+     * @param column - the edge column with role "id"; E_COLUMN_TYPE when its dtype cannot hold ids
+     */
+    constructor(column: Column) {
+        if (!canHoldEdgeIds(column)) {
+            throw unsupportedDtype(column);
+        }
+        this.column = column;
+        this.map = null;
+        this.builtVersion = -1;
+    }
+
+    /**
+     * Whether the map has been built (and is current).
+     * @returns true when the next lookup will not build
+     */
+    get built(): boolean {
+        return this.map !== null && this.builtVersion === this.column.version;
+    }
+
+    /**
+     * Number of distinct ids over the set rows; builds the map.
+     * @returns the id count
+     */
+    get size(): number {
+        return this.ensure().size;
+    }
+
+    /**
+     * The logical edge index of an id.
+     * @param id - the edge id
+     * @returns the edge index, or INVALID_INDEX on a miss
+     */
+    indexOf(id: EdgeId): number {
+        const index = this.ensure().get(id);
+        return index === undefined ? INVALID_INDEX : index;
+    }
+
+    /**
+     * Whether an id is present.
+     * @param id - the edge id
+     * @returns true when some set row holds it
+     */
+    has(id: EdgeId): boolean {
+        return this.ensure().has(id);
+    }
+
+    /**
+     * The map, built on first use and rebuilt after the column's version changed.
+     * @returns the id -> edge index map
+     */
+    private ensure(): Map<EdgeId, number> {
+        const { version } = this.column;
+        if (this.map === null || this.builtVersion !== version) {
+            this.map = buildEdgeIdMap(this.column);
+            this.builtVersion = version;
+        }
+        return this.map;
+    }
+}