@graphty/graph-io 0.0.0 → 0.2.0

package/dist/src/children.js

@@ -0,0 +1,274 @@
+/**
+ * The children CSR over a containment column (design sections 5.10, 7.1 and 8.2): containment
+ * (GEXF `pid` / `<parents>`, Cytoscape `parent`, DOT clusters, GraphML nested graphs) is a node
+ * column with the `parent` role (u32, refersTo node) or the `parents` role (list of u32) and never
+ * enters the CSR of the snapshot. Importers and exporters that need to walk containers top-down
+ * (nested subgraphs, cluster blocks, parent lists) build this inverse index once: for every node
+ * `u`, `children[rowPtr[u] .. rowPtr[u + 1])` are its children in ascending index order, `roots`
+ * are the nodes with no parent, and `depthFirst()` is the pre-order the nested writers use.
+ *
+ * The helper is deliberately outside the core (7.1: it computes a property the arrays do not
+ * already imply and only io needs it). A reference is ignored when it is unset, INVALID_INDEX, out
+ * of range, or the node itself; a cycle (a parent chain that never reaches a root) is reported
+ * through `unreachable` and its members are appended to the depth-first order in index order so
+ * every node is written exactly once.
+ */
+import { INVALID_INDEX } from "@graphty/graph-format";
+/**
+ * The children CSR of a snapshot's containment column (design sections 5.10 and 7.1): the inverse
+ * of the parent relation as a compressed sparse row structure over node indices.
+ */
+export class ChildrenCsr {
+    /**
+     * Build the CSR; use childrenCsr() rather than the constructor.
+     * @param nodeCount - the node count
+     * @param rowPtr - the row pointers
+     * @param children - the child list
+     * @param parentCount - parents per node (0 for a root)
+     * @param dropped - references ignored
+     * @param column - the source column, or null
+     */
+    constructor(nodeCount, rowPtr, children, parentCount, dropped, column) {
+        this.nodeCount = nodeCount;
+        this.rowPtr = rowPtr;
+        this.children = children;
+        this.parentCount = parentCount;
+        this.edgeCount = children.length;
+        this.dropped = dropped;
+        this.column = column;
+        let rootCount = 0;
+        for (let u = 0; u < nodeCount; u++) {
+            if (parentCount[u] === 0) {
+                rootCount++;
+            }
+        }
+        const roots = new Uint32Array(rootCount);
+        let r = 0;
+        for (let u = 0; u < nodeCount; u++) {
+            if (parentCount[u] === 0) {
+                roots[r++] = u;
+            }
+        }
+        this.roots = roots;
+        this.unreachable = nodeCount - this.reachableCount();
+    }
+    /**
+     * The children of a node, as a view into `children` (do not modify).
+     * @param node - the node index
+     * @returns the child indices in ascending order; empty for a leaf
+     */
+    childrenOf(node) {
+        return this.children.subarray(this.rowPtr[node], this.rowPtr[node + 1]);
+    }
+    /**
+     * How many children a node has.
+     * @param node - the node index
+     * @returns the count
+     */
+    childCount(node) {
+        return this.rowPtr[node + 1] - this.rowPtr[node];
+    }
+    /**
+     * Whether a node is a container (has at least one child).
+     * @param node - the node index
+     * @returns true when it has children
+     */
+    hasChildren(node) {
+        return this.rowPtr[node + 1] > this.rowPtr[node];
+    }
+    /**
+     * How many parents a node has: 0 for a root, 1 under a `parent` column, any number under `parents`.
+     * @param node - the node index
+     * @returns the parent count
+     */
+    parentCountOf(node) {
+        return this.parentCount[node];
+    }
+    /**
+     * Whether a node has no parent.
+     * @param node - the node index
+     * @returns true for a root
+     */
+    isRoot(node) {
+        return this.parentCount[node] === 0;
+    }
+    /**
+     * Whether the snapshot has any containment at all.
+     * @returns true when at least one child reference was kept
+     */
+    isEmpty() {
+        return this.edgeCount === 0;
+    }
+    /**
+     * A pre-order depth-first traversal from the roots in index order (children in ascending
+     * order), then every node not yet visited (a cycle member, or a multi-parent node reached
+     * only through a cycle) in index order at depth 0. Each node appears exactly once, so nested
+     * writers emit every element once even for a `parents` column that shares a child.
+     * @returns the order, the depth of every node and whether the order differs from index order
+     */
+    depthFirst() {
+        const n = this.nodeCount;
+        const order = new Uint32Array(n);
+        const depth = new Uint32Array(n);
+        const visited = new Uint8Array(n);
+        const stackNode = [];
+        const stackCursor = [];
+        let position = 0;
+        let reordered = false;
+        const place = (u, d) => {
+            visited[u] = 1;
+            if (u !== position) {
+                reordered = true;
+            }
+            order[position++] = u;
+            depth[u] = d;
+        };
+        const visit = (root) => {
+            place(root, 0);
+            stackNode.push(root);
+            stackCursor.push(this.rowPtr[root]);
+            while (stackNode.length > 0) {
+                const top = stackNode.length - 1;
+                const u = stackNode[top];
+                const cursor = stackCursor[top];
+                if (cursor >= this.rowPtr[u + 1]) {
+                    stackNode.pop();
+                    stackCursor.pop();
+                    continue;
+                }
+                stackCursor[top] = cursor + 1;
+                const v = this.children[cursor];
+                if (visited[v] === 1) {
+                    continue;
+                }
+                place(v, stackNode.length);
+                stackNode.push(v);
+                stackCursor.push(this.rowPtr[v]);
+            }
+        };
+        for (const root of this.roots) {
+            visit(root);
+        }
+        for (let u = 0; u < n; u++) {
+            if (visited[u] === 0) {
+                visit(u);
+            }
+        }
+        return { order, depth, reordered };
+    }
+    /**
+     * The nodes reachable from the roots by following child references.
+     * @returns how many nodes a traversal from the roots reaches
+     */
+    reachableCount() {
+        const visited = new Uint8Array(this.nodeCount);
+        // every node is pushed at most once, so a stack of nodeCount entries never overflows
+        const stack = new Uint32Array(this.nodeCount);
+        let top = 0;
+        let count = 0;
+        for (const root of this.roots) {
+            visited[root] = 1;
+            count++;
+            stack[top++] = root;
+            while (top > 0) {
+                const u = stack[--top];
+                for (let k = this.rowPtr[u]; k < this.rowPtr[u + 1]; k++) {
+                    const v = this.children[k];
+                    if (visited[v] === 0) {
+                        visited[v] = 1;
+                        count++;
+                        stack[top++] = v;
+                    }
+                }
+            }
+        }
+        return count;
+    }
+}
+/**
+ * Build the children CSR of a snapshot (design section 7.1: a graph-io helper, not a core view).
+ * @param snapshot - the snapshot
+ * @param options - which column to read; the `parent` role, then `parents`, by default
+ * @returns the CSR; empty (every node a root) when the snapshot has no containment column
+ */
+export function childrenCsr(snapshot, options = {}) {
+    const column = resolveColumn(snapshot, options.column === undefined ? "auto" : options.column);
+    return childrenFromColumn(snapshot.nodeCount, column);
+}
+/**
+ * Build the children CSR over one containment column without a snapshot (an importer that holds
+ * the column before freezing, a test).
+ * @param nodeCount - the node count the references index into
+ * @param column - a u32 `parent`-shaped column, a list-of-u32 `parents`-shaped column, or null for none
+ * @returns the CSR
+ */
+export function childrenFromColumn(nodeCount, column) {
+    const rowPtr = new Uint32Array(nodeCount + 1);
+    const parentCount = new Uint32Array(nodeCount);
+    let dropped = 0;
+    const references = [];
+    if (column !== null) {
+        const rows = Math.min(column.length, nodeCount);
+        const keep = (child, parent) => {
+            if (!Number.isInteger(parent) || parent === INVALID_INDEX || parent >= nodeCount || parent === child) {
+                dropped++;
+                return;
+            }
+            references.push(child, parent);
+            rowPtr[parent + 1]++;
+            parentCount[child]++;
+        };
+        if (column.dtype === "u32") {
+            const { data } = column;
+            for (let i = 0; i < rows; i++) {
+                if (column.isSet(i)) {
+                    keep(i, data[i]);
+                }
+            }
+        }
+        else if (column.dtype === "list") {
+            for (let i = 0; i < rows; i++) {
+                if (!column.isSet(i)) {
+                    continue;
+                }
+                for (const item of column.sliceOf(i)) {
+                    if (typeof item === "number") {
+                        keep(i, item);
+                    }
+                    else {
+                        dropped++;
+                    }
+                }
+            }
+        }
+        else {
+            throw new TypeError(`a containment column must be u32 or a list of u32, found ${column.dtype} column "${column.meta.name}"`);
+        }
+    }
+    for (let u = 0; u < nodeCount; u++) {
+        rowPtr[u + 1] += rowPtr[u];
+    }
+    const children = new Uint32Array(rowPtr[nodeCount]);
+    const fill = rowPtr.slice(0, nodeCount);
+    // references were collected in ascending child order, so each parent's range fills ascending
+    for (let k = 0; k < references.length; k += 2) {
+        children[fill[references[k + 1]]++] = references[k];
+    }
+    return new ChildrenCsr(nodeCount, rowPtr, children, parentCount, dropped, column);
+}
+/**
+ * The column a ChildrenOptions selects.
+ * @param snapshot - the snapshot
+ * @param choice - the option value
+ * @returns the column, or null when the snapshot has none of that shape
+ */
+function resolveColumn(snapshot, choice) {
+    if (typeof choice !== "string") {
+        return choice;
+    }
+    if (choice === "parent" || choice === "parents") {
+        return snapshot.nodes.byRole(choice);
+    }
+    return snapshot.nodes.byRole("parent") ?? snapshot.nodes.byRole("parents");
+}
+//# sourceMappingURL=children.js.map

package/dist/src/children.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"children.js","sourceRoot":"","sources":["../../src/children.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAmC,aAAa,EAAE,MAAM,uBAAuB,CAAC;AA0BvF;;;GAGG;AACH,MAAM,OAAO,WAAW;IAoBpB;;;;;;;;OAQG;IACH,YACI,SAAiB,EACjB,MAAmB,EACnB,QAAqB,EACrB,WAAwB,EACxB,OAAe,EACf,MAAqB;QAErB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;YACjC,IAAI,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;gBACvB,SAAS,EAAE,CAAC;YAChB,CAAC;QACL,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,SAAS,CAAC,CAAC;QACzC,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;YACjC,IAAI,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;gBACvB,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;YACnB,CAAC;QACL,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,SAAS,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;IACzD,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,IAAY;QACnB,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;IAC5E,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,IAAY;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACrD,CAAC;IAED;;;;OAIG;IACH,WAAW,CAAC,IAAY;QACpB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACrD,CAAC;IAED;;;;OAIG;IACH,aAAa,CAAC,IAAY;QACtB,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,IAAY;QACf,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxC,CAAC;IAED;;;OAGG;IACH,OAAO;QACH,OAAO,IAAI,CAAC,SAAS,KAAK,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;OAMG;IACH,UAAU;QACN,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;QACzB,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC;QACjC,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;QAClC,MAAM,SAAS,GAAa,EAAE,CAAC;QAC/B,MAAM,WAAW,GAAa,EAAE,CAAC;QACjC,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,CAAS,EAAQ,EAAE;YACzC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACf,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;gBACjB,SAAS,GAAG,IAAI,CAAC;YACrB,CAAC;YACD,KAAK,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;YACtB,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACjB,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,CAAC,IAAY,EAAQ,EAAE;YACjC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;YACf,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrB,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;YACpC,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC1B,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;gBACjC,MAAM,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;gBACzB,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;gBAChC,IAAI,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;oBAC/B,SAAS,CAAC,GAAG,EAAE,CAAC;oBAChB,WAAW,CAAC,GAAG,EAAE,CAAC;oBAClB,SAAS;gBACb,CAAC;gBACD,WAAW,CAAC,GAAG,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC;gBAC9B,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;gBAChC,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;oBACnB,SAAS;gBACb,CAAC;gBACD,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;gBAC3B,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAClB,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YACrC,CAAC;QACL,CAAC,CAAC;QACF,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC5B,KAAK,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC;QACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACzB,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnB,KAAK,CAAC,CAAC,CAAC,CAAC;YACb,CAAC;QACL,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACvC,CAAC;IAED;;;OAGG;IACK,cAAc;QAClB,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC/C,qFAAqF;QACrF,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAClB,KAAK,EAAE,CAAC;YACR,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;YACpB,OAAO,GAAG,GAAG,CAAC,EAAE,CAAC;gBACb,MAAM,CAAC,GAAG,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC;gBACvB,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;oBACvD,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;oBAC3B,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;wBACnB,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;wBACf,KAAK,EAAE,CAAC;wBACR,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;oBACrB,CAAC;gBACL,CAAC;YACL,CAAC;QACL,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;CACJ;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,QAAuB,EAAE,UAA2B,EAAE;IAC9E,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/F,OAAO,kBAAkB,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAiB,EAAE,MAAqB;IACvE,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IAC9C,MAAM,WAAW,GAAG,IAAI,WAAW,CAAC,SAAS,CAAC,CAAC;IAC/C,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAChD,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,MAAc,EAAQ,EAAE;YACjD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,KAAK,aAAa,IAAI,MAAM,IAAI,SAAS,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;gBACnG,OAAO,EAAE,CAAC;gBACV,OAAO;YACX,CAAC;YACD,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAC/B,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;YACrB,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,CAAC,CAAC;QACF,IAAI,MAAM,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;YACzB,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC;YACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC5B,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;oBAClB,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;gBACrB,CAAC;YACL,CAAC;QACL,CAAC;aAAM,IAAI,MAAM,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC5B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;oBACnB,SAAS;gBACb,CAAC;gBACD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;oBACnC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;wBAC3B,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;oBAClB,CAAC;yBAAM,CAAC;wBACJ,OAAO,EAAE,CAAC;oBACd,CAAC;gBACL,CAAC;YACL,CAAC;QACL,CAAC;aAAM,CAAC;YACJ,MAAM,IAAI,SAAS,CACf,4DAA4D,MAAM,CAAC,KAAK,YAAY,MAAM,CAAC,IAAI,CAAC,IAAI,GAAG,CAC1G,CAAC;QACN,CAAC;IACL,CAAC;IACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;QACjC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACxC,6FAA6F;IAC7F,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5C,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,IAAI,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AACtF,CAAC;AAED;;;;;GAKG;AACH,SAAS,aAAa,CAAC,QAAuB,EAAE,MAAgD;IAC5F,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,MAAM,CAAC;IAClB,CAAC;IACD,IAAI,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9C,OAAO,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AAC/E,CAAC"}

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

@@ -0,0 +1,229 @@
+/**
+ * Attribute declaration shared by the typed importers (design sections 5.1, 5.5 and 5.6): turn a
+ * GEXF `<attribute>`, a GraphML `<key>` or a Neo4j header column into a ColumnDecl with the right
+ * dtype, default, options and origin metadata; parse values (scalars and lists) by the declaration;
+ * derive the deterministic `<name>#<origin.id>` name when a declared name collides; and the dict
+ * heuristic of design section 5.4.
+ *
+ * Naming rule (design section 5.6): a column's name is the GEXF `title` / GraphML `attr.name`,
+ * falling back to the attribute `id` when the title is absent; `origin.id` always keeps the source
+ * id and `origin.title` the title when it differs from the resolved name.
+ */
+import { type ColumnDecl, type ColumnHandle, type ColumnRole, type GraphSink } from "@graphty/graph-format";
+import { type IssueCategory } from "../types.js";
+import { BAD_DEFAULT_CODE, BAD_OPTIONS_CODE, PRECISION_CODE, ROLE_TAKEN_CODE } from "./codes.js";
+import { type DeclaredTypeSpec, type DeclaringFormat } from "./declared-types.js";
+import { type ListSyntax } from "./lists.js";
+import { type ImportReportBuilder, type IssueLocation } from "./report.js";
+import { type TemporalValue } from "./temporal.js";
+/**
+ * What an importer knows about a declared attribute.
+ * Consumed by the per-format importers and exporters under src/formats.
+ * @public
+ */
+export interface AttributeDeclarationInput {
+    /** The declaring format. */
+    readonly format: DeclaringFormat;
+    /** The attribute id (GEXF `id`, GraphML key `id`, Neo4j header name); null when the format has none. */
+    readonly id: string | null;
+    /** The GEXF `title` / GraphML `attr.name`; null when absent (yFiles keys omit it). */
+    readonly title: string | null;
+    /** The declared type text; null for an untyped declaration (stored as string). */
+    readonly type: string | null;
+    /** The declaring namespace ("viz", "yfiles", "neo4j"), or null. */
+    readonly namespace?: string | null | undefined;
+    /** The `<default>` text, or null. */
+    readonly defaultText?: string | null | undefined;
+    /** The GEXF `<options>` text, or null. */
+    readonly optionsText?: string | null | undefined;
+    /** The list syntax of defaults, options and values; "gexf" by default. */
+    readonly listSyntax?: ListSyntax | undefined;
+    /** A role to give the column, or null. */
+    readonly role?: ColumnRole | null | undefined;
+    /** Whether the attribute is dynamic (GEXF mode="dynamic"). */
+    readonly dynamic?: boolean | undefined;
+    /** The importer's `long` option. */
+    readonly long: "f64" | "string";
+    /** Whether a column name is already taken in the target table; drives the `#id` rename. */
+    readonly taken?: ((name: string) => boolean) | undefined;
+}
+/**
+ * A non-fatal problem with a declaration, for the importer to record as a warning.
+ * Consumed by the per-format importers and exporters under src/formats.
+ * @public
+ */
+export interface DeclarationIssue {
+    /** The issue category. */
+    readonly category: IssueCategory;
+    /** The stable code. */
+    readonly code: string;
+    /** A plain-ASCII message. */
+    readonly message: string;
+}
+/**
+ * A declared attribute: the ColumnDecl to push, the spec to parse values with, and what to report.
+ * Consumed by the per-format importers and exporters under src/formats.
+ * @public
+ */
+export interface DeclaredAttribute {
+    /** The declaration for declareNodeColumn / declareEdgeColumn. */
+    readonly decl: ColumnDecl;
+    /** How values are parsed. */
+    readonly spec: DeclaredTypeSpec;
+    /** The list syntax values are split with. */
+    readonly listSyntax: ListSyntax;
+    /** The companion text column of a temporal attribute (design section 5.1), or null. */
+    readonly companion: ColumnDecl | null;
+    /** Whether the name received the `#id` suffix. */
+    readonly renamed: boolean;
+    /** Problems the importer records as warnings (unknown type, unparsable default or options). */
+    readonly issues: readonly DeclarationIssue[];
+}
+/** Issue code: the declared type is not one the format defines; the column is kept as string. */
+export declare const UNKNOWN_TYPE_CODE = "W_UNKNOWN_ATTR_TYPE";
+/** Issue code: the column was renamed `<name>#<id>` because the name was taken (design section 5.6). */
+export declare const RENAMED_CODE = "W_COLUMN_RENAMED";
+export { BAD_DEFAULT_CODE, BAD_OPTIONS_CODE, PRECISION_CODE, ROLE_TAKEN_CODE };
+/** Rows sampled before the dict heuristic decides (design section 5.4). */
+export declare const DICT_SAMPLE_ROWS = 1024;
+/**
+ * Build the column declaration of a declared attribute.
+ * @param input - what the file declares
+ * @returns the declaration, the value spec and any warnings to record
+ */
+export declare function declareAttribute(input: AttributeDeclarationInput): DeclaredAttribute;
+/**
+ * Parse a value text by a declaration: a scalar, or a list split by the syntax with each item
+ * parsed by the item kind.
+ * @param text - the value text
+ * @param spec - the declared type
+ * @param listSyntax - the list syntax
+ * @returns the value to push (a boolean, a number, a string, a JSON value or an array)
+ */
+export declare function parseDeclaredValue(text: string, spec: DeclaredTypeSpec, listSyntax: ListSyntax): unknown;
+/**
+ * Parse a temporal value text by a declaration, keeping the source text when its canonical form
+ * differs (for the companion column).
+ * @param text - the value text
+ * @param spec - a scalar temporal spec
+ * @returns the value and the text to keep, or null text
+ */
+export declare function parseDeclaredTemporal(text: string, spec: DeclaredTypeSpec): TemporalValue;
+/**
+ * Whether a long value's text lost precision when parsed to f64 (design section 5.1: a value with
+ * |v| > 2^53 is stored as the nearest f64 and recorded as a `precision` issue). Decided from the
+ * text, since the parsed number alone cannot tell 2^53 from 2^53 + 1.
+ * @param spec - the declared type
+ * @param text - the value text (trimmed or not)
+ * @returns true when the importer should record a `precision` issue
+ */
+export declare function losesPrecision(spec: DeclaredTypeSpec, text: string): boolean;
+/**
+ * Declare a column on the sink for one domain.
+ * @param sink - the sink
+ * @param domain - node or edge
+ * @param decl - the declaration
+ * @returns the column handle
+ */
+export declare function declareOn(sink: GraphSink, domain: "node" | "edge", decl: ColumnDecl): ColumnHandle;
+/**
+ * The outcome of declareResolved(): the handle and the declaration as it was applied.
+ * Consumed by the per-format importers under src/formats.
+ * @public
+ */
+export interface ResolvedDeclaration {
+    /** The column handle. */
+    readonly handle: ColumnHandle;
+    /** The declaration as applied (its name and role may differ from the request). */
+    readonly decl: ColumnDecl;
+    /** Whether the column was renamed `<name>#<id>` (W_COLUMN_RENAMED recorded). */
+    readonly renamed: boolean;
+    /** Whether the role was dropped because the table already holds it (W_ROLE_TAKEN recorded). */
+    readonly roleDropped: boolean;
+}
+/**
+ * The io rule of design section 5.6 in one place, so every importer agrees: declare a column on
+ * the sink and, when the sink already holds the name with another shape (an earlier import, a
+ * caller's column), rename it `<name>#<origin.id>` (a counter when the source has no id) and
+ * record W_COLUMN_RENAMED (coercion); when the table already holds the role (design section 5.5:
+ * at most one column per role), declare without the role and record W_ROLE_TAKEN (coercion). The
+ * same shape under the same name returns the existing handle, as the sink does.
+ * @param sink - the sink
+ * @param domain - node or edge
+ * @param decl - the wanted declaration
+ * @param report - the report the coercion issues are recorded in
+ * @param where - the line and element, when known
+ * @returns the handle and the declaration as applied
+ */
+export declare function declareResolved(sink: GraphSink, domain: "node" | "edge", decl: ColumnDecl, report: ImportReportBuilder, where?: IssueLocation): ResolvedDeclaration;
+/**
+ * Declare the companion text column of a temporal column (design section 5.1). A table holds at
+ * most one column per role, so when another companion already carries `timeText` this one is
+ * declared without the role (reported once per table); exporters find every companion through
+ * `extra.for`.
+ * @param sink - the sink
+ * @param domain - node or edge
+ * @param companion - the declaration from declareAttribute()
+ * @param report - the report the role loss is recorded in; when omitted the loss is silent
+ * @returns the column handle
+ */
+export declare function declareCompanion(sink: GraphSink, domain: "node" | "edge", companion: ColumnDecl, report?: ImportReportBuilder): ColumnHandle;
+/**
+ * Whether a column name is taken in a sink's table, the usual `taken` callback.
+ * @param sink - the sink
+ * @param domain - node or edge
+ * @returns a predicate over column names
+ */
+export declare function takenIn(sink: GraphSink, domain: "node" | "edge"): (name: string) => boolean;
+/**
+ * The deterministic name of a declared attribute whose preferred name is taken (design section
+ * 5.6): `<name>#<origin.id>`, and `<name>#<origin.id>#2`, `#3`... should that be taken as well.
+ * @param name - the preferred name
+ * @param id - the source id (the attribute id or key id); null falls back to a counter
+ * @param taken - whether a name is already used in the table
+ * @returns a free name
+ */
+export declare function uniqueColumnName(name: string, id: string | null, taken: (name: string) => boolean): string;
+/**
+ * The dict heuristic of design section 5.4 for an untyped string column: observe values until the
+ * sample is full; the column is a dict when the distinct count stays below half the rows, a string
+ * otherwise. The importer buffers the sampled values and declares the column on the decision.
+ */
+export declare class DictHeuristic {
+    private readonly distinct;
+    private rowsSeen;
+    private readonly sampleRows;
+    /**
+     * Create a heuristic.
+     * @param sampleRows - rows observed before deciding; DICT_SAMPLE_ROWS by default
+     */
+    constructor(sampleRows?: number);
+    /**
+     * Rows observed so far.
+     * @returns the count
+     */
+    get rows(): number;
+    /**
+     * Distinct values observed so far.
+     * @returns the count
+     */
+    get distinctCount(): number;
+    /**
+     * Whether the sample is full.
+     * @returns true once sampleRows values were observed
+     */
+    get decided(): boolean;
+    /**
+     * Observe one value.
+     * @param value - the value text
+     * @returns true when this observation completed the sample
+     */
+    observe(value: string): boolean;
+    /**
+     * The dtype the sample suggests: dict when the distinct count is below rows / 2 (and at least
+     * one row was seen), string otherwise. Valid before the sample is full (end of input).
+     * @returns "dict" or "string"
+     */
+    decide(): "dict" | "string";
+}
+//# sourceMappingURL=attributes.d.ts.map

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

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