@graphty/graph-format 0.0.0 → 0.2.0

package/dist/src/columns/infer.js

@@ -0,0 +1,268 @@
+/**
+ * Type inference for untyped sources (design section 5.1, decision C4): CSV cells, GML values, DOT
+ * strings, `fromRecords` and `addNodeRecord`. Inference runs per COLUMN, never per cell, widening
+ * monotonically in the order `(unset) -> bool -> i32 -> f64 -> string -> json`; it never yields
+ * `f32`. The lexical grammar for text is fixed so two implementations agree (invariant I15):
+ *
+ * - `bool` is exactly `true` / `false` (case-sensitive);
+ * - `i32` is `/^-?(0|[1-9][0-9]*)$/` within `[-2^31, 2^31)`;
+ * - `f64` is a decimal or exponent literal accepted by `Number()` that is not empty, not whitespace,
+ *   not `Infinity` / `NaN` and not a hex / octal / binary form (and whose value is finite);
+ * - everything else is `string`. `0` / `1` text is `i32`, never `bool`.
+ *
+ * JS values map by `typeof`: `boolean -> bool`, integral `number` in i32 range -> `i32`, other
+ * `number -> f64`, `string -> string`, array or plain object -> `json`; `null` and `undefined` are
+ * unset and do not widen.
+ */
+import { GraphFormatError } from "../errors.js";
+/** The widening order of design section 5.1; a column only ever moves to the right. */
+export const WIDENING_ORDER = ["bool", "i32", "f64", "string", "json"];
+const I32_TEXT = /^-?(0|[1-9][0-9]*)$/;
+// integer part without leading zeros ("01" is a string, design section 5.1), optional fraction, optional exponent
+const F64_TEXT = /^[+-]?((0|[1-9][0-9]*)(\.[0-9]*)?|\.[0-9]+)([eE][+-]?[0-9]+)?$/;
+const I32_MIN = -2147483648;
+const I32_MAX = 2147483647;
+/**
+ * The rank of a dtype in the widening order.
+ * @param dtype - an inferred dtype
+ * @returns 0 for bool up to 4 for json
+ */
+export function wideningRank(dtype) {
+    return WIDENING_ORDER.indexOf(dtype);
+}
+/**
+ * Widen a column's dtype by one observation: the wider of the two, where null (unset, nothing seen
+ * yet) is narrower than everything.
+ * @param current - the column's dtype so far, or null when no value has been seen
+ * @param observed - the dtype of the newly observed value, or null for an unset cell
+ * @returns the widened dtype (null only when both are null)
+ */
+export function widenDtype(current, observed) {
+    if (current === null) {
+        return observed;
+    }
+    if (observed === null) {
+        return current;
+    }
+    return wideningRank(observed) > wideningRank(current) ? observed : current;
+}
+/**
+ * Classify one text cell by the fixed lexical grammar. Exported as the reference implementation of
+ * the text grammar of design section 5.1, which the text importers of graph-io must reproduce
+ * exactly (invariant I15); the core itself only infers from JS values, so nothing in src/ calls it.
+ * @public
+ * @param text - the cell text, exactly as read (no trimming)
+ * @returns bool, i32, f64 or string
+ */
+export function inferTextDtype(text) {
+    if (text === "true" || text === "false") {
+        return "bool";
+    }
+    if (I32_TEXT.test(text)) {
+        const n = Number(text);
+        if (n >= I32_MIN && n <= I32_MAX) {
+            return "i32";
+        }
+        return Number.isFinite(n) ? "f64" : "string";
+    }
+    if (F64_TEXT.test(text) && Number.isFinite(Number(text))) {
+        return "f64";
+    }
+    return "string";
+}
+/**
+ * Classify one JS value by `typeof`.
+ * @param value - the cell value
+ * @returns the dtype, or null for an unset cell (`undefined` or `null`); E_COLUMN_TYPE for a bigint,
+ * symbol or function, which no dtype can hold
+ */
+export function inferValueDtype(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    switch (typeof value) {
+        case "boolean":
+            return "bool";
+        case "number":
+            return Number.isInteger(value) && value >= I32_MIN && value <= I32_MAX ? "i32" : "f64";
+        case "string":
+            return "string";
+        case "object":
+            return "json";
+        default:
+            throw new GraphFormatError("E_COLUMN_TYPE", `a ${typeof value} value cannot be stored in a column`, {
+                reason: "unsupported value type",
+                found: typeof value,
+            });
+    }
+}
+/**
+ * Parse a text cell into the storage value of a dtype the column has widened to. A text column
+ * never widens to json, but a column that was inferred from JS values may later receive text; in
+ * that case the text is stored as a string value. Part of the reference text grammar of design
+ * section 5.1 (see inferTextDtype).
+ * @public
+ * @param text - the cell text
+ * @param dtype - the column's current dtype
+ * @returns a boolean for bool, a number for i32 / f64, the text itself for string / json
+ */
+export function parseText(text, dtype) {
+    switch (dtype) {
+        case "bool":
+            if (text === "true") {
+                return true;
+            }
+            if (text === "false") {
+                return false;
+            }
+            throw new GraphFormatError("E_COLUMN_TYPE", `text "${text}" is not a bool`, { value: text, dtype });
+        case "i32":
+        case "f64": {
+            const inferred = inferTextDtype(text);
+            if (inferred === "string") {
+                throw new GraphFormatError("E_COLUMN_TYPE", `text "${text}" is not a ${dtype}`, { value: text, dtype });
+            }
+            if (inferred === "bool") {
+                return text === "true" ? 1 : 0;
+            }
+            return Number(text);
+        }
+        case "string":
+        case "json":
+            return text;
+        default: {
+            const name = dtype;
+            throw new GraphFormatError("E_COLUMN_TYPE", `unknown dtype ${name}`, { dtype: name });
+        }
+    }
+}
+/**
+ * Convert a JS value to the storage value of a (possibly wider) inferred dtype, applying the
+ * widening conversions of design section 5.1: a bool widened to a number becomes 1 / 0, a number or
+ * boolean widened to string becomes its canonical JS text, anything widened to json is kept as is.
+ * @param value - the cell value (never undefined or null; unset cells are handled by the caller)
+ * @param dtype - the column's dtype
+ * @returns the storage value; E_COLUMN_TYPE when the value cannot be represented in the dtype
+ */
+export function coerceValue(value, dtype) {
+    switch (dtype) {
+        case "bool":
+            if (typeof value === "boolean") {
+                return value;
+            }
+            break;
+        case "i32":
+        case "f64":
+            if (typeof value === "number") {
+                return value;
+            }
+            if (typeof value === "boolean") {
+                return value ? 1 : 0;
+            }
+            break;
+        case "string":
+            if (typeof value === "string") {
+                return value;
+            }
+            if (typeof value === "number" || typeof value === "boolean") {
+                return String(value);
+            }
+            break;
+        case "json":
+            return value;
+        default: {
+            const name = dtype;
+            throw new GraphFormatError("E_COLUMN_TYPE", `unknown dtype ${name}`, { dtype: name });
+        }
+    }
+    throw new GraphFormatError("E_COLUMN_TYPE", `a ${typeof value} value cannot be stored in a ${dtype} column`, {
+        dtype,
+        found: typeof value,
+    });
+}
+/**
+ * Infer the dtype of a whole column of JS values in one pass.
+ * @param values - the cell values; undefined and null are unset
+ * @returns the widened dtype, or null when every cell is unset
+ */
+export function inferValuesDtype(values) {
+    let dtype = null;
+    for (const value of values) {
+        dtype = widenDtype(dtype, inferValueDtype(value));
+        if (dtype === "json") {
+            break;
+        }
+    }
+    return dtype;
+}
+/**
+ * Infer the dtype of a whole column of text cells in one pass. Part of the reference text grammar
+ * of design section 5.1 (see inferTextDtype).
+ * @public
+ * @param cells - the cell texts; an empty string is a string value, not an unset cell (the caller
+ * decides how blanks map to unset before calling)
+ * @returns the widened dtype, or null when the column is empty
+ */
+export function inferTextsDtype(cells) {
+    let dtype = null;
+    for (const text of cells) {
+        dtype = widenDtype(dtype, inferTextDtype(text));
+        if (dtype === "string") {
+            break;
+        }
+    }
+    return dtype;
+}
+/**
+ * A per-column inference accumulator for row-at-a-time sources (`addNodeRecord`, CSV streaming):
+ * observe every cell and read `dtype`; each observe call reports whether the column widened so the
+ * caller can reallocate storage and record the widening in FreezeReport.widened.
+ */
+export class DtypeInferrer {
+    constructor() {
+        this.current = null;
+    }
+    /**
+     * The column's dtype so far.
+     * @returns the widened dtype, or null until a set cell has been observed
+     */
+    get dtype() {
+        return this.current;
+    }
+    /**
+     * Observe a JS value.
+     * @param value - the cell value; undefined and null are unset and never widen
+     * @returns true when the column's dtype changed
+     */
+    observeValue(value) {
+        return this.apply(inferValueDtype(value));
+    }
+    /**
+     * Observe a text cell. Part of the reference text grammar of design section 5.1 (see
+     * inferTextDtype).
+     * @public
+     * @param text - the cell text
+     * @returns true when the column's dtype changed
+     */
+    observeText(text) {
+        return this.apply(inferTextDtype(text));
+    }
+    /**
+     * Force the dtype to at least the given one (a declared lower bound, or the dtype of a column
+     * being merged in).
+     * @param dtype - the dtype to widen to
+     * @returns true when the column's dtype changed
+     */
+    widenTo(dtype) {
+        return this.apply(dtype);
+    }
+    apply(observed) {
+        const next = widenDtype(this.current, observed);
+        if (next === this.current) {
+            return false;
+        }
+        this.current = next;
+        return true;
+    }
+}
+//# sourceMappingURL=infer.js.map

package/dist/src/columns/infer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"infer.js","sourceRoot":"","sources":["../../../src/columns/infer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKhD,uFAAuF;AACvF,MAAM,CAAC,MAAM,cAAc,GAA6B,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AAEjG,MAAM,QAAQ,GAAG,qBAAqB,CAAC;AACvC,kHAAkH;AAClH,MAAM,QAAQ,GAAG,gEAAgE,CAAC;AAClF,MAAM,OAAO,GAAG,CAAC,UAAU,CAAC;AAC5B,MAAM,OAAO,GAAG,UAAU,CAAC;AAE3B;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAoB;IAC7C,OAAO,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,OAA6B,EAAE,QAA8B;IACpF,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,QAAQ,CAAC;IACpB,CAAC;IACD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,OAAO,CAAC;IACnB,CAAC;IACD,OAAO,YAAY,CAAC,QAAQ,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;AAC/E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACvC,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACtC,OAAO,MAAM,CAAC;IAClB,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC;YAC/B,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;IACjD,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QACvD,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,OAAO,QAAQ,CAAC;AACpB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC1C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACxC,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,QAAQ,OAAO,KAAK,EAAE,CAAC;QACnB,KAAK,SAAS;YACV,OAAO,MAAM,CAAC;QAClB,KAAK,QAAQ;YACT,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,OAAO,IAAI,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;QAC3F,KAAK,QAAQ;YACT,OAAO,QAAQ,CAAC;QACpB,KAAK,QAAQ;YACT,OAAO,MAAM,CAAC;QAClB;YACI,MAAM,IAAI,gBAAgB,CAAC,eAAe,EAAE,KAAK,OAAO,KAAK,qCAAqC,EAAE;gBAChG,MAAM,EAAE,wBAAwB;gBAChC,KAAK,EAAE,OAAO,KAAK;aACtB,CAAC,CAAC;IACX,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAAoB;IACxD,QAAQ,KAAK,EAAE,CAAC;QACZ,KAAK,MAAM;YACP,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;gBAClB,OAAO,IAAI,CAAC;YAChB,CAAC;YACD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;gBACnB,OAAO,KAAK,CAAC;YACjB,CAAC;YACD,MAAM,IAAI,gBAAgB,CAAC,eAAe,EAAE,SAAS,IAAI,iBAAiB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACxG,KAAK,KAAK,CAAC;QACX,KAAK,KAAK,CAAC,CAAC,CAAC;YACT,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBACxB,MAAM,IAAI,gBAAgB,CAAC,eAAe,EAAE,SAAS,IAAI,cAAc,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAC5G,CAAC;YACD,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;gBACtB,OAAO,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACnC,CAAC;YACD,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;QACD,KAAK,QAAQ,CAAC;QACd,KAAK,MAAM;YACP,OAAO,IAAI,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC;YACN,MAAM,IAAI,GAAW,KAAK,CAAC;YAC3B,MAAM,IAAI,gBAAgB,CAAC,eAAe,EAAE,iBAAiB,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1F,CAAC;IACL,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,KAAoB;IAC5D,QAAQ,KAAK,EAAE,CAAC;QACZ,KAAK,MAAM;YACP,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC7B,OAAO,KAAK,CAAC;YACjB,CAAC;YACD,MAAM;QACV,KAAK,KAAK,CAAC;QACX,KAAK,KAAK;YACN,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC5B,OAAO,KAAK,CAAC;YACjB,CAAC;YACD,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC7B,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACzB,CAAC;YACD,MAAM;QACV,KAAK,QAAQ;YACT,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC5B,OAAO,KAAK,CAAC;YACjB,CAAC;YACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC1D,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;YACzB,CAAC;YACD,MAAM;QACV,KAAK,MAAM;YACP,OAAO,KAAK,CAAC;QACjB,OAAO,CAAC,CAAC,CAAC;YACN,MAAM,IAAI,GAAW,KAAK,CAAC;YAC3B,MAAM,IAAI,gBAAgB,CAAC,eAAe,EAAE,iBAAiB,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1F,CAAC;IACL,CAAC;IACD,MAAM,IAAI,gBAAgB,CAAC,eAAe,EAAE,KAAK,OAAO,KAAK,gCAAgC,KAAK,SAAS,EAAE;QACzG,KAAK;QACL,KAAK,EAAE,OAAO,KAAK;KACtB,CAAC,CAAC;AACP,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAyB;IACtD,IAAI,KAAK,GAAyB,IAAI,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACzB,KAAK,GAAG,UAAU,CAAC,KAAK,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;QAClD,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;YACnB,MAAM;QACV,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,KAAuB;IACnD,IAAI,KAAK,GAAyB,IAAI,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,KAAK,GAAG,UAAU,CAAC,KAAK,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;QAChD,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;YACrB,MAAM;QACV,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,aAAa;IAA1B;QACY,YAAO,GAAyB,IAAI,CAAC;IAgDjD,CAAC;IA9CG;;;OAGG;IACH,IAAI,KAAK;QACL,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,KAAc;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;;OAMG;IACH,WAAW,CAAC,IAAY;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,KAAoB;QACxB,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAEO,KAAK,CAAC,QAA8B;QACxC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAChD,IAAI,IAAI,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;YACxB,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,OAAO,IAAI,CAAC;IAChB,CAAC;CACJ"}

package/dist/src/columns/remap.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Remap and gather helpers for raw typed arrays, columns and whole tables (design section 5.11):
+ * the propagation of attribute data through compaction (freeze step 10), derived graphs (section
+ * 7.3) and consumer re-attachment after a builder mutation. One name per shape:
+ *
+ * - `remapArray(data, remap, newLength, fill, components)` and `remapColumn(column, remap,
+ *   newLength)` take an OLD -> NEW map (`INVALID_INDEX` drops the row);
+ * - `gatherArray(data, indexMap, components)` and `gatherColumn(column, indexMap)` take a NEW ->
+ *   OLD map (`out[i] = source[indexMap[i]]`);
+ * - `scatterArray(out, values, indexMap, components)` writes results computed on a derived graph
+ *   back into the parent's index space (`out[indexMap[i]] = values[i]`).
+ *
+ * Index-valued columns (`meta.refersTo`, a u32 column or a list of u32) have their VALUES rewritten
+ * through the remap of the space they reference: an in-range value maps to its new index, a
+ * dangling reference becomes `INVALID_INDEX` with the row unset (invariant I12; for a list, the
+ * dangling items are dropped and a row whose every item dangled becomes unset and empty).
+ */
+import { type Column, type F32, type TypedArrayData, type U32 } from "../types/index.js";
+import { AttributeTable } from "./table.js";
+/**
+ * Move rows of an index-aligned array from an old index space to a new one through an OLD -> NEW
+ * remap (`FreezeReport.nodeRemap` / `edgeRemap`, `DerivedGraph.nodeRemap` / `edgeRemap`): row `i`
+ * lands at `remap[i]`, rows mapped to `INVALID_INDEX` are dropped, and rows of the new space no old
+ * row maps to hold `fill`.
+ * @param data - the old array, `oldRows * components` long
+ * @param remap - old index -> new index or INVALID_INDEX; rows beyond `remap.length` are dropped
+ * @param newLength - the row count of the new space
+ * @param fill - the value of rows no old row maps to
+ * @param components - values per row (default 1)
+ * @returns a new array of `newLength * components` values
+ */
+export declare function remapArray<T extends TypedArrayData>(data: T, remap: U32, newLength: number, fill: number, components?: number): T;
+/**
+ * Gather rows through a NEW -> OLD index map: `out[i] = data[indexMap[i]]` (`DerivedGraph.nodeOrigin`
+ * / `edgeOrigin`).
+ * @param data - the source array, `oldRows * components` long
+ * @param indexMap - new index -> old index, every entry in range
+ * @param components - values per row (default 1)
+ * @returns a new array of `indexMap.length * components` values
+ */
+export declare function gatherArray<T extends TypedArrayData>(data: T, indexMap: U32, components?: number): T;
+/**
+ * Scatter values computed on a derived graph back into the parent's index space: `out[indexMap[i]]
+ * = values[i]` (through `nodeOrigin` / `edgeOrigin`). Rows of `out` no value maps to are untouched.
+ * @param out - the destination in the parent's index space
+ * @param values - the values in the derived index space, `indexMap.length * components` long
+ * @param indexMap - derived index -> parent index, every entry in range
+ * @param components - values per row (default 1)
+ * @returns `out`
+ */
+export declare function scatterArray<T extends TypedArrayData>(out: T, values: T, indexMap: U32, components?: number): T;
+/**
+ * Gather the rows of a column through a NEW -> OLD index map: `out[i] = column[indexMap[i]]`
+ * (design section 5.11, `DerivedGraph.nodeOrigin` / `edgeOrigin`). An INVALID_INDEX entry yields an
+ * unset row holding the fill (the column becomes nullable if it was not). Values of a refersTo
+ * column are NOT rewritten here; compose with remapReferences() when the referenced space changed.
+ * @param column - the source column
+ * @param indexMap - new index -> old index (or INVALID_INDEX for a row with no source)
+ * @returns a new column of `indexMap.length` rows
+ */
+export declare function gatherColumn(column: Column, indexMap: U32): Column;
+/**
+ * Rewrite the values of an index-valued column through the remap of the space it references
+ * (design section 5.11): an in-range value maps to its new index; a dangling reference (mapped to
+ * INVALID_INDEX or out of range) becomes INVALID_INDEX with the row unset. For a list of u32 the
+ * dangling items are dropped and a row whose every item dangled becomes unset and empty. A column
+ * without refersTo is returned as it is.
+ * @param column - the column
+ * @param valueRemap - old index -> new index or INVALID_INDEX, over the referenced space
+ * @returns a new column when anything was rewritten; the same object otherwise
+ */
+export declare function remapReferences(column: Column, valueRemap: U32): Column;
+/**
+ * Move a column's rows from an old index space to a new one through an OLD -> NEW remap, rewriting
+ * its values through `valueRemap` when it is an index-valued column (design section 5.11): rows
+ * mapped to INVALID_INDEX are dropped, rows of the new space no old row maps to are unset and hold
+ * the fill (the column becomes nullable if it was not), and dangling references become
+ * INVALID_INDEX with the row unset.
+ * @param column - the source column
+ * @param remap - old row -> new row or INVALID_INDEX
+ * @param newLength - the row count of the new space
+ * @param valueRemap - the remap of the space the column's values reference, or null to leave values alone
+ * @returns a new column of `newLength` rows
+ */
+export declare function remapColumnWith(column: Column, remap: U32, newLength: number, valueRemap: U32 | null): Column;
+/**
+ * Move a column's rows through an OLD -> NEW remap and, when the column refers to its OWN index
+ * space (a node column with `refersTo: "node"` such as `parent`, an edge column with `refersTo:
+ * "edge"` such as `pair`), rewrite its values through the SAME remap (design sections 5.11 and
+ * 12.2). A column whose values reference the OTHER space (a node column referring to edges) has its
+ * rows moved and its values left untouched, because `remap` says nothing about that space; the
+ * internal remapColumnWith() / remapTable() take a second remap for it.
+ * @param column - the source column
+ * @param remap - old row -> new row or INVALID_INDEX
+ * @param newLength - the row count of the new space
+ * @returns a new column of `newLength` rows
+ */
+export declare function remapColumn(column: Column, remap: U32, newLength: number): Column;
+/**
+ * Change the stride of an interleaved f32 array (design section 5.2, the generic stride helper):
+ * every row of `from` values becomes a row of `to` values, extra lanes filled with `fill` and
+ * surplus lanes dropped. A 2D layout result expands to the 3-component position column with
+ * `withComponents(xy, 2, 3, 0)`; the inverse drops `z`. Returns `data` itself when `from === to`.
+ * @param data - the interleaved values, `rows * from` long
+ * @param from - values per row of `data`, 1..16
+ * @param to - values per row of the result, 1..16
+ * @param fill - the value of the lanes `to` adds beyond `from`
+ * @returns a new array of `rows * to` values (the input when the stride is unchanged)
+ */
+export declare function withComponents(data: F32, from: number, to: number, fill: number): F32;
+/**
+ * The remaps of the two index spaces a column's values may reference; null when that space was not
+ * renumbered.
+ */
+interface ReferenceRemaps {
+    /** Old node index -> new node index or INVALID_INDEX; null when nodes were not renumbered. */
+    readonly node: U32 | null;
+    /** Old edge index -> new edge index or INVALID_INDEX; null when edges were not renumbered. */
+    readonly edge: U32 | null;
+}
+/**
+ * Remap every column of a table (freeze step 10, the compaction case; extension tables with
+ * `rowRemap` null): rows move through `rowRemap` when given, and every refersTo column's values are
+ * rewritten through the remap of the space it references. The result is a new table; the source is
+ * untouched.
+ * @param table - the source table
+ * @param rowRemap - old row -> new row or INVALID_INDEX; null when the table's rows are unchanged
+ * @param newLength - the row count of the new table (ignored, and equal to table.rowCount, when rowRemap is null)
+ * @param refs - the node and edge remaps for index-valued columns
+ * @returns the remapped table
+ */
+export declare function remapTable(table: AttributeTable, rowRemap: U32 | null, newLength: number, refs: ReferenceRemaps): AttributeTable;
+/**
+ * Gather every column of a table through a NEW -> OLD index map (derived graphs: `nodeOrigin` /
+ * `edgeOrigin`), rewriting refersTo values through the remaps of the spaces they reference.
+ * @param table - the source table
+ * @param indexMap - new row -> old row
+ * @param refs - the node and edge remaps for index-valued columns
+ * @returns the gathered table of `indexMap.length` rows
+ */
+export declare function gatherTable(table: AttributeTable, indexMap: U32, refs: ReferenceRemaps): AttributeTable;
+export {};
+//# sourceMappingURL=remap.d.ts.map

package/dist/src/columns/remap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remap.d.ts","sourceRoot":"","sources":["../../../src/columns/remap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAE,KAAK,MAAM,EAAmB,KAAK,GAAG,EAAE,KAAK,cAAc,EAAE,KAAK,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAI1G,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA6C5C;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,cAAc,EAC/C,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,GAAG,EACV,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,UAAU,SAAI,GACf,CAAC,CAgCH;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,cAAc,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,UAAU,SAAI,GAAG,CAAC,CA0B/F;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,cAAc,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,UAAU,SAAI,GAAG,CAAC,CAmC1G;AAyCD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,MAAM,CAkIlE;AAkCD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,GAAG,MAAM,CAyEvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,GAAG,IAAI,GAAG,MAAM,CAU7G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAIjF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CA8BrF;AAID;;;GAGG;AACH,UAAU,eAAe;IACrB,8FAA8F;IAC9F,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,CAAC;IAC1B,8FAA8F;IAC9F,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,CAAC;CAC7B;AAkBD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACtB,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,GAAG,GAAG,IAAI,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,eAAe,GACtB,cAAc,CAchB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,eAAe,GAAG,cAAc,CAQvG"}