@graphty/graph-format 0.0.0 → 0.2.0

package/src/types/wire.ts

@@ -0,0 +1,207 @@
+/**
+ * The wire form of a snapshot (design sections 9.1, 9.2 and 12.2): a JSON-serialisable manifest
+ * plus a list of ArrayBuffers. The same object is what postMessage, structuredClone, IndexedDB and
+ * the GSNP byte container carry; `buffers` is literally the postMessage transfer list. Absent
+ * members are null, never optional (design section 12.1).
+ */
+
+import { type ColumnMeta, type GraphMeta, type ValidationLevel } from "./columns.js";
+import { type NodeIdMapKind, type SnapshotFlags, type ViewName } from "./snapshot.js";
+
+/** Element type of a wire buffer reference: the five typed-array dtypes plus "utf8" for byte stores. */
+export type WireDtype = "u32" | "i32" | "f32" | "f64" | "u8" | "utf8";
+
+/**
+ * One typed array inside WireSnapshot.buffers (design section 9.1). Validation at level "structure"
+ * checks byteOffset % elementSize === 0, byteLength === length * elementSize and that the range lies
+ * inside the buffer (E_BAD_SERIALIZATION with details.ref otherwise).
+ */
+export interface WireBufferRef {
+    /** Index into WireSnapshot.buffers (always 0 inside a byte container). */
+    readonly buffer: number;
+    /** Byte offset inside the buffer (relative to the buffer region inside a container). */
+    readonly byteOffset: number;
+    /** Byte length of the array. */
+    readonly byteLength: number;
+    /** Element type. */
+    readonly dtype: WireDtype;
+    /** Element count. */
+    readonly length: number;
+}
+
+/**
+ * An Arrow Utf8 store on the wire: u32 offsets plus UTF-8 bytes (string ids, string columns, dictionaries, JSON text).
+ */
+export interface WireUtf8 {
+    /** rows + 1 offsets. */
+    readonly offsets: WireBufferRef;
+    /** The concatenated UTF-8 bytes. */
+    readonly utf8: WireBufferRef;
+}
+
+/**
+ * One column on the wire (design section 9.1): the resolved metadata plus the buffers its dtype
+ * uses, each null when not applicable. meta.default, options and extra are JSON values with the
+ * tagged encoding of design section 5.9 for non-finite numbers.
+ */
+export interface WireColumn {
+    /** Resolved metadata. */
+    readonly meta: ColumnMeta;
+    /** Values (numeric dtypes), packed words (bool) or codes (dict); null for string / list / json. */
+    readonly data: WireBufferRef | null;
+    /** Validity bitmap words; null when every row is set. */
+    readonly validity: WireBufferRef | null;
+    /** Number of unset rows (recomputed from the bitmap by validation). */
+    readonly nullCount: number;
+    /** dict only: the dictionary strings. */
+    readonly dictionary: WireUtf8 | null;
+    /** string only: the Utf8 store. */
+    readonly strings: WireUtf8 | null;
+    /** list only: rows + 1 offsets into the child. */
+    readonly offsets: WireBufferRef | null;
+    /** list only: the child column. */
+    readonly child: WireColumn | null;
+    /** json only: the JSON text of every row as a Utf8 store. */
+    readonly jsonText: WireUtf8 | null;
+}
+
+/** The arena region inside one wire buffer, so a receiver keeps the one-writeBuffer path (design section 9.1). */
+export interface WireArena {
+    /** Index into WireSnapshot.buffers. */
+    readonly buffer: number;
+    /** Start of the arena inside the buffer. */
+    readonly byteOffset: number;
+    /** Total padded length of the arena. */
+    readonly byteLength: number;
+    /** Hot prefix length (design section 10.3). */
+    readonly hotByteLength: number;
+}
+
+/**
+ * The id map on the wire (design section 4.5), one shape for every kind: the members a kind does not
+ * use are null. The reverse Map is never serialised; a receiver rebuilds it lazily.
+ */
+export interface WireIdMap {
+    /** The storage kind. */
+    readonly kind: NodeIdMapKind;
+    /** Number of ids. */
+    readonly size: number;
+    /** identity only: id === index + offset; 0 otherwise. */
+    readonly offset: number;
+    /** dense: u32 ids per index; numeric: f64 ids per index. */
+    readonly values: WireBufferRef | null;
+    /** mixed: u8 tag per index (0 number, 1 string). */
+    readonly tags: WireBufferRef | null;
+    /** mixed: f64 per index (0 where string). */
+    readonly numbers: WireBufferRef | null;
+    /** string / mixed: u32 offsets of the Utf8 store. */
+    readonly offsets: WireBufferRef | null;
+    /** string / mixed: the UTF-8 bytes. */
+    readonly utf8: WireBufferRef | null;
+}
+
+/**
+ * The JSON-serialisable manifest of a wire snapshot (design section 9.1). Readers refuse a
+ * formatVersion or wire major they do not know (E_UNSUPPORTED_VERSION), ignore unknown manifest
+ * fields of a newer minor, refuse an unknown column dtype unless unknownColumns is "skip", refuse an
+ * unknown id-map kind, and ignore unknown view entries.
+ */
+export interface WireManifest {
+    /** Discriminator. */
+    readonly format: "graphty-snapshot";
+    /** Wire [major, minor]. */
+    readonly wire: readonly [major: number, minor: number];
+    /** The producing package version (masked when golden fixtures are compared). */
+    readonly producer: string;
+    /** The data-model major. */
+    readonly formatVersion: 1;
+    /** Whether the graph is directed. */
+    readonly directed: boolean;
+    /** The four counts. */
+    readonly counts: {
+        readonly nodes: number;
+        readonly edges: number;
+        readonly arcs: number;
+        readonly selfLoops: number;
+    };
+    /** The flags (invariant I9). */
+    readonly flags: SnapshotFlags;
+    /**
+     * The core arrays; null for an identity permutation (always, whether or not a getter materialised it), an absent
+     * weights array or a zero-length array.
+     */
+    readonly core: {
+        readonly rowPtr: WireBufferRef;
+        readonly colIdx: WireBufferRef | null;
+        readonly weights: WireBufferRef | null;
+        readonly arcToEdge: WireBufferRef | null;
+        readonly edgeToArc: WireBufferRef | null;
+    };
+    /** The arena region when the core lives in one buffer; null otherwise. */
+    readonly arena: WireArena | null;
+    /** The id map. */
+    readonly ids: WireIdMap;
+    /** Node columns in declaration order. */
+    readonly nodeColumns: readonly WireColumn[];
+    /** Edge columns in declaration order. */
+    readonly edgeColumns: readonly WireColumn[];
+    /** Graph columns in declaration order. */
+    readonly graphColumns: readonly WireColumn[];
+    /** Extension tables with their own row counts (design section 5.10). */
+    readonly extensions: readonly {
+        readonly name: string;
+        readonly rowCount: number;
+        readonly columns: readonly WireColumn[];
+    }[];
+    /** Graph metadata. */
+    readonly meta: GraphMeta;
+    /** Cached views included on request: view name -> member name -> buffer; null unless includeViews named some. */
+    readonly views: Readonly<Record<string, Readonly<Record<string, WireBufferRef>>>> | null;
+    /** Buffer indices that were copied rather than transferred (shared storage, design section 9.1). */
+    readonly copied: readonly number[];
+    /** The snapshot label. */
+    readonly label: string | null;
+}
+
+/**
+ * The plain-object, transferable, versioned representation of a snapshot: the only cloneable shape (design section
+ * 9.1).
+ */
+export interface WireSnapshot {
+    /** The manifest. */
+    readonly manifest: WireManifest;
+    /** The buffers the manifest's references index; the postMessage transfer list when produced with transfer: true. */
+    readonly buffers: readonly ArrayBuffer[];
+}
+
+/** Options of toWire() (design section 9.1). */
+export interface ToWireOptions {
+    /**
+     * Put only exclusively owned buffers into `buffers` as transferables and copy every shared one (listed in
+     * manifest.copied); default false (nothing is transferable).
+     */
+    readonly transfer?: boolean | undefined;
+    /** Cached views to carry; the receiver recomputes the rest. Scalar views are ignored. */
+    readonly includeViews?: readonly ViewName[] | undefined;
+    /** Whether attribute columns are carried; default true. */
+    readonly includeColumns?: boolean | undefined;
+}
+
+/** Options of toBytes() and toByteChunks() (design section 9.2). */
+export interface ToBytesOptions {
+    /** Cached views to carry. */
+    readonly includeViews?: readonly ViewName[] | undefined;
+}
+
+/** Options of fromWire(), fromBytes() and fromByteChunks() (design sections 9.1 and 9.2). */
+export interface FromWireOptions {
+    /** Validation level; default "structure" for fromWire, "full" for fromBytes. */
+    readonly validate?: ValidationLevel | undefined;
+    /** Copy the buffers instead of adopting them; default false. */
+    readonly copy?: boolean | undefined;
+    /**
+     * What to do with a column whose dtype the reader does not know; default "error" (E_UNSUPPORTED); "skip" drops it
+     * and records the name in meta.extra["graphty.skippedColumns"].
+     */
+    readonly unknownColumns?: "error" | "skip" | undefined;
+}

package/src/util/mask.ts

@@ -0,0 +1,89 @@
+/**
+ * The public packed-mask helpers of design section 7.4 (makeMask, maskTest, maskSet, maskCount,
+ * maskToIndices) plus the E_MASK_LENGTH check that filterEdges() and inducedSubgraph({ mask }) apply
+ * to a caller's mask. A NodeMask / EdgeMask is the same layout as a validity bitmap and a bool column
+ * (decision C13): ceil(length / 32) Uint32Array words, LSB-first, bit i set means index i is included.
+ * Masks are not part of the snapshot contract; no kernel is required to honour one.
+ */
+
+import {
+    bitmapCount,
+    bitmapGet,
+    bitmapToIndices,
+    bitmapWordCount,
+    bitmapWrite,
+    makeBitmap,
+} from "../columns/bitmap.js";
+import { GraphFormatError } from "../errors.js";
+import { type U32 } from "../types/index.js";
+
+/**
+ * Allocate a packed mask over `length` indices: ceil(length / 32) words, every bit clear, or every bit
+ * below `length` set when `fill` is true (design section 7.4).
+ * @param length - the number of indices the mask covers (nodeCount, edgeCount or arcCount)
+ * @param fill - the initial value of every bit; defaults to false
+ * @returns the mask words
+ */
+export function makeMask(length: number, fill?: boolean): U32 {
+    return makeBitmap(length, fill === true);
+}
+
+/**
+ * Whether index i is in the mask.
+ * @param mask - the mask words
+ * @param i - the index, below the mask's length
+ * @returns true when bit i is set
+ */
+export function maskTest(mask: U32, i: number): boolean {
+    return bitmapGet(mask, i);
+}
+
+/**
+ * Include or exclude index i.
+ * @param mask - the mask words
+ * @param i - the index, below the mask's length
+ * @param value - true to include, false to exclude
+ */
+export function maskSet(mask: U32, i: number, value: boolean): void {
+    bitmapWrite(mask, i, value);
+}
+
+/**
+ * The number of included indices below `length` (the loop guard of an algorithm-owned alive mask,
+ * design section 7.4).
+ * @param mask - the mask words, at least ceil(length / 32) of them
+ * @param length - the number of indices the mask covers
+ * @returns the number of set bits in [0, length)
+ */
+export function maskCount(mask: U32, length: number): number {
+    return bitmapCount(mask, length);
+}
+
+/**
+ * The included indices below `length` in ascending order, as a fresh U32.
+ * @param mask - the mask words, at least ceil(length / 32) of them
+ * @param length - the number of indices the mask covers
+ * @returns the set bit indices
+ */
+export function maskToIndices(mask: U32, length: number): U32 {
+    return bitmapToIndices(mask, length);
+}
+
+/**
+ * Check that a caller-supplied mask has enough words for `length` indices; filterEdges() and
+ * inducedSubgraph({ mask }) call it before reading the mask (design section 11.2). Throws
+ * E_MASK_LENGTH when mask.length < ceil(length / 32).
+ * @param mask - the mask words
+ * @param length - the number of indices the mask must cover
+ * @param what - what the mask is over, for the message ("edges", "nodes")
+ */
+export function checkMaskLength(mask: U32, length: number, what: string): void {
+    const required = bitmapWordCount(length);
+    if (mask.length < required) {
+        throw new GraphFormatError(
+            "E_MASK_LENGTH",
+            `mask over ${what} has ${mask.length} words; ${required} needed for ${length} ${what}`,
+            { found: mask.length, required, length },
+        );
+    }
+}

package/src/util/options.ts

@@ -0,0 +1,57 @@
+/**
+ * Enum-valued option checking (design section 11.1): a value outside its documented set is refused
+ * with E_UNSUPPORTED (`details.field`, `details.found`, `details.reason` "unsupported option") at
+ * the call, never taken as a default. Every public entry point that reads an enum option -- the
+ * builder constructor and freeze overrides, the derived graphs, `degreeOrder`, `validate`,
+ * `set`, `indicesOf`, `fromRecords`, `foldArcs` -- goes through here, so typed callers see no change
+ * and an untyped caller's typo is an error rather than a silently different result.
+ */
+
+import { GraphFormatError } from "../errors.js";
+
+/**
+ * Check that an option value is one of the allowed literals (undefined is accepted and returned so
+ * the caller applies its default).
+ * @param field - the option name for the error
+ * @param value - the value
+ * @param allowed - the documented literals
+ * @returns the value, narrowed
+ */
+export function assertOneOf<T extends string>(field: string, value: unknown, allowed: readonly T[]): T | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || !(allowed as readonly string[]).includes(value)) {
+        throw new GraphFormatError(
+            "E_UNSUPPORTED",
+            `option ${field} has an unsupported value ${describeOption(value)}`,
+            {
+                field,
+                found: value,
+                reason: "unsupported option",
+            },
+        );
+    }
+    return value as T;
+}
+
+/**
+ * A plain-ASCII rendering of an option value for an error message.
+ * @param value - the value
+ * @returns the rendering
+ */
+function describeOption(value: unknown): string {
+    if (typeof value === "string") {
+        return JSON.stringify(value.length > 40 ? `${value.slice(0, 37)}...` : value);
+    }
+    if (typeof value === "number" || typeof value === "boolean" || value === null) {
+        return String(value);
+    }
+    return `a ${typeof value}`;
+}
+
+/** The WeightReducer literals (design section 7.3). */
+export const WEIGHT_REDUCERS = ["first", "last", "sum", "min", "max"] as const;
+
+/** The ColumnReducer literals (design section 7.3). */
+export const COLUMN_REDUCERS = [...WEIGHT_REDUCERS, "mean", "count", "drop"] as const;

package/src/util/shared-buffers.ts

@@ -0,0 +1,56 @@
+/**
+ * The conservative owner count of design section 9.1. The format shares storage deliberately:
+ * `withColumns()` shares the core, same-node-space derived graphs share the node table and the id
+ * map, `clone()` and `set(name, column)` share Column objects between tables, `transpose()` adopts
+ * the cached reverse arrays as its core. Every holder of a buffer, column, table or id map claims it
+ * once (the snapshot and table constructors do so); a target claimed by more than one holder is
+ * SHARED, and `toWire({ transfer: true })` / `transferables()` copy its buffers instead of
+ * transferring them, so no sibling snapshot is ever silently emptied. The count is never decremented
+ * (conservative: a holder that is garbage-collected still counts, which only ever causes a copy).
+ *
+ * Holders are tracked at three granularities because a shared holder materialises buffers lazily
+ * (the Utf8 store of a string column or a string id map, the Float64Array of a numeric id map): a
+ * buffer, a Column (or a NodeIdMap) and an AttributeTable. The wire module treats a buffer as shared
+ * when the buffer itself, the column that holds it or the table that holds the column is shared.
+ * This module is a leaf (it imports nothing) so every module may use it without a cycle.
+ */
+
+/** Target (ArrayBuffer, Column, AttributeTable or NodeIdMap) -> number of holders recorded. */
+const HOLDERS = new WeakMap<object, number>();
+
+/**
+ * Record one holder of a buffer, column, table or id map. Called by every constructor that keeps a
+ * reference to storage it did not allocate itself; the second claim of the same target marks it
+ * shared.
+ * @param target - the buffer, Column, AttributeTable or NodeIdMap now held
+ */
+export function claimHolder(target: object): void {
+    HOLDERS.set(target, (HOLDERS.get(target) ?? 0) + 1);
+}
+
+/**
+ * Record that a target has gained another holder (design section 9.1), so it is treated as shared
+ * from now on whatever its previous count.
+ * @param target - the buffer, Column, AttributeTable or NodeIdMap that is now held by more than one holder
+ */
+export function noteShared(target: object): void {
+    HOLDERS.set(target, Math.max(HOLDERS.get(target) ?? 0, 1) + 1);
+}
+
+/**
+ * The number of holders recorded for a target.
+ * @param target - the buffer, Column, AttributeTable or NodeIdMap
+ * @returns the count, 0 when never claimed
+ */
+export function holderCount(target: object): number {
+    return HOLDERS.get(target) ?? 0;
+}
+
+/**
+ * Whether a target has been recorded as held by more than one holder.
+ * @param target - the buffer, Column, AttributeTable or NodeIdMap
+ * @returns true when at least two holders were recorded
+ */
+export function isShared(target: object): boolean {
+    return (HOLDERS.get(target) ?? 0) > 1;
+}