@graphty/graph-format 0.0.0 → 0.2.0

package/dist/src/ids/node-id-map.d.ts

@@ -0,0 +1,280 @@
+/**
+ * The immutable id-to-index bijection of a snapshot (design section 4): five storage kinds chosen by
+ * inspecting the ids once in O(n), SameValueZero equality, `INVALID_INDEX` on a miss, a dense-integer
+ * fast path with no Map at all, lazily materialised typed / decoded representations in either
+ * direction, and a reverse `Map` that is shared with the builder (guarded by `index < size`) or built
+ * lazily on the first lookup.
+ *
+ * The class exposes exactly the public surface of design section 12.2. Everything the sibling
+ * modules need beyond it (construction from ids, typed arrays or the wire; the typed form for the
+ * wire; gather and remap for derived graphs and compaction) is a module-level function that reaches
+ * the private storage through a module-private WeakMap, so nothing internal appears on the instance
+ * type.
+ */
+import { type F64, type NodeId, type NodeIdMapContract, type NodeIdMapKind, type U8, type U32, type ValidationLevel } from "../types/index.js";
+/**
+ * A short, plain-ASCII rendering of an id for error messages.
+ * @param id - the value
+ * @returns the number, a quoted (possibly truncated) string, or the type name
+ */
+export declare function describeId(id: unknown): string;
+/**
+ * Check a value as a node id and normalise it (design section 4.1): a finite number (`-0` becomes
+ * `0`) or a string without a lone surrogate. NaN, non-finite numbers, bigints, objects, null and
+ * undefined are E_INVALID_ID; a lone surrogate is E_INVALID_ID with details.reason "lone surrogate".
+ * @param id - the value to check
+ * @returns the id as stored
+ */
+export declare function validateNodeId(id: unknown): NodeId;
+/** The typed representation of an id map, one slot per wire member (design section 4.5). */
+export interface NodeIdMapTypedParts {
+    /** 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; null otherwise. */
+    readonly values: U32 | F64 | null;
+    /** mixed: u8 tag per index (0 number, 1 string); null otherwise. */
+    readonly tags: U8 | null;
+    /** mixed: f64 per index (0 where string); null otherwise. */
+    readonly numbers: F64 | null;
+    /** string / mixed: rows + 1 offsets of the Utf8 store; null otherwise. */
+    readonly offsets: U32 | null;
+    /** string / mixed: the UTF-8 bytes; null otherwise. */
+    readonly utf8: U8 | null;
+}
+/**
+ * Whether an id map's typed storage was transferred away (design section 9.1), for validate().
+ * @param map - the id map
+ * @returns true when detached
+ */
+export declare function idMapDetached(map: NodeIdMap): boolean;
+/**
+ * Bijection between node ids and node indices for one snapshot (design section 4, invariant I11):
+ * `indexOf(idOf(i)) === i` for every i, `size === nodeCount`, SameValueZero equality (so `1` and
+ * `"1"` are distinct, `-0` is `0`, `1.5` is legal and `NaN` never occurs). Immutable. Lookups by id
+ * are total and return `INVALID_INDEX` on a miss (decision C9); `requireIndex` is the checked form.
+ *
+ * Instances are created by the module-level factories (`nodeIdMapFromIds`, `nodeIdMapFromF64`,
+ * `identityNodeIdMap`, `nodeIdMapFromTyped`) and by `gatherNodeIdMap` / `remapNodeIdMap`; the
+ * constructor takes a prepared storage record and is not meant to be called by consumers.
+ */
+export declare class NodeIdMap implements NodeIdMapContract {
+    /** The storage kind (design section 4.2). */
+    readonly kind: NodeIdMapKind;
+    /** Number of ids; equals nodeCount. */
+    readonly size: number;
+    /** identity only: id === index + offset (0 or 1 in practice); 0 for every other kind. */
+    readonly offset: number;
+    /** The private storage; also registered in INTERNALS for the module-level functions. */
+    private readonly storage;
+    /**
+     * The id of a node index.
+     * @param index - the node index
+     * @returns the id; E_INDEX_RANGE when index is not an integer in [0, size)
+     */
+    idOf(index: number): NodeId;
+    /**
+     * Total lookup by id: SameValueZero, never coerces, so `indexOf("1")` misses a map of numbers.
+     * @param id - the node id
+     * @returns the node index, or INVALID_INDEX when absent
+     */
+    indexOf(id: NodeId): number;
+    /**
+     * Whether an id is present.
+     * @param id - the node id
+     * @returns true when present
+     */
+    has(id: NodeId): boolean;
+    /**
+     * Checked lookup by id, for algorithms that today throw "node not found".
+     * @param id - the node id
+     * @returns the node index; E_UNKNOWN_NODE when absent
+     */
+    requireIndex(id: NodeId): number;
+    /**
+     * Bulk lookup.
+     * @param ids - the ids to resolve
+     * @param onMissing - "invalid" (default) writes INVALID_INDEX for a miss; "throw" raises E_UNKNOWN_NODE
+     * @returns a fresh U32 of indices in input order
+     */
+    indicesOf(ids: Iterable<NodeId>, onMissing?: "invalid" | "throw"): U32;
+    /**
+     * Bulk decode of a range of ids in one pass. Bounds follow Array.prototype.slice (negative values
+     * count from the end, out-of-range values are clamped).
+     * @param start - first index (default 0)
+     * @param end - one past the last index (default size)
+     * @returns a fresh array of the ids in index order
+     */
+    idsSlice(start?: number, end?: number): NodeId[];
+    /**
+     * Every id in index order.
+     * @returns a fresh array
+     */
+    toArray(): NodeId[];
+    /**
+     * Iterate the ids in index order.
+     * @yields each id, decoding lazily
+     */
+    [Symbol.iterator](): IterableIterator<NodeId>;
+    /**
+     * Key an index-aligned result vector by id (boundary helper, decision C11).
+     * @param values - one value per node index
+     * @returns a Map from id to value, in index order
+     */
+    toMap<T>(values: ArrayLike<T>): Map<NodeId, T>;
+    /**
+     * Key an index-aligned result vector by String(id), for legacy Map<string, T> result shapes. When
+     * two ids share a string form (1 and "1") the HIGHER index wins, exactly as the legacy
+     * algorithms' assignment in node order does (design section 14.2).
+     * @param values - one value per node index
+     * @returns a Map from String(id) to value
+     */
+    toStringMap<T>(values: ArrayLike<T>): Map<string, T>;
+    /**
+     * Key an index-aligned result vector by String(id), for legacy record result shapes only. The
+     * record has a null prototype so ids such as "__proto__" are ordinary keys; when two ids share a
+     * string form the HIGHER index wins (the legacy assignment order, design section 14.2).
+     * @param values - one value per node index
+     * @returns a record from String(id) to value
+     */
+    toRecord<T>(values: ArrayLike<T>): Record<string, T>;
+    /**
+     * Iterate [id, value] pairs of an index-aligned result vector.
+     * @param values - one value per node index
+     * @yields the pairs in index order
+     */
+    entries<T>(values: ArrayLike<T>): IterableIterator<[NodeId, T]>;
+    /**
+     * String(idOf(i)) -> i, built lazily once, for legacy string-typed id parameters. When two ids
+     * share a string form (always one number and one string, since ids are distinct) the STRING id
+     * wins: a legacy string parameter "1" addressed the node whose id is the string "1".
+     * @returns the read-only string index
+     */
+    stringIndex(): ReadonlyMap<string, number>;
+    /**
+     * Bytes of typed storage currently materialised; excludes the reverse Map and JS strings.
+     * @returns the byte count
+     */
+    byteLength(): number;
+    /**
+     * Unchecked id of an in-range index.
+     * @param index - a node index in [0, size)
+     * @returns the id
+     */
+    private idAt;
+    /**
+     * E_DETACHED when a typed array the map reads from was transferred away (design sections 9.1
+     * and 11.3): derived from the array state (a transferred buffer leaves zero-length views).
+     */
+    private assertAttached;
+    /**
+     * The reverse map of a numeric / string / mixed map, built on first use (one pass over the ids,
+     * after a bulk decode of a wire-decoded Utf8 store) when it was not shared by the builder.
+     * @returns the map from id to index
+     */
+    private reverseMap;
+}
+/**
+ * An identity map: id === index + offset, no storage at all (design section 4.2). What
+ * `fromEdgeArrays` without ids and `contract()` produce; offset 1 covers 1-based files.
+ * @param size - the node count
+ * @param offset - the integer added to every index; default 0
+ * @returns the map
+ */
+export declare function identityNodeIdMap(size: number, offset?: number): NodeIdMap;
+/** Options of nodeIdMapFromIds. */
+interface FromIdsOptions {
+    /**
+     * The builder's reverse map, shared by reference and guarded by `index < size` (decision C17). When
+     * given, the ids are trusted (already validated and distinct) and `validate` is ignored.
+     */
+    readonly map?: Map<NodeId, number> | undefined;
+    /**
+     * Check every id (E_INVALID_ID) and their distinctness (E_DUPLICATE_ID), copying the array and
+     * normalising -0; default true. false trusts the caller (derived graphs) and shares the array.
+     */
+    readonly validate?: boolean | undefined;
+}
+/**
+ * Build a map from decoded ids in index order, choosing the kind in one O(n) pass (design section
+ * 4.2, freeze step 9). With `options.map` (the builder's Map) the array and the Map are shared by
+ * reference and nothing is validated; identity and dense maps drop the Map. Without it the ids are
+ * validated and copied unless `validate` is false.
+ * @param ids - the ids; only entries below `size` are read
+ * @param size - the node count; default ids.length
+ * @param options - the shared map and validation switch
+ * @returns the map
+ */
+export declare function nodeIdMapFromIds(ids: readonly NodeId[], size?: number, options?: FromIdsOptions): NodeIdMap;
+/** Options of nodeIdMapFromF64. */
+interface FromF64Options {
+    /**
+     * Check that every value is finite (E_INVALID_ID) and that the values are distinct (E_DUPLICATE_ID);
+     * default true. The array is adopted by reference either way; -0 entries are rewritten to 0 in a
+     * copy when validating.
+     */
+    readonly validate?: boolean | undefined;
+}
+/**
+ * Build a map from numeric ids in a Float64Array (the `ids: F64` form of `fromEdgeArrays` /
+ * `fromCsr`), choosing identity, dense or numeric in one pass. A numeric map adopts the array as its
+ * typed representation.
+ * @param values - one id per index
+ * @param options - the validation switch
+ * @returns the map
+ */
+export declare function nodeIdMapFromF64(values: F64, options?: FromF64Options): NodeIdMap;
+/**
+ * The distinct backing buffers of an id map's materialised typed storage (dense values and inverse,
+ * numbers, tags, an encoded Utf8 store), for the owner count of design section 9.1.
+ * @param map - the id map
+ * @returns the buffers, each once
+ */
+export declare function idMapBuffers(map: NodeIdMap): ArrayBuffer[];
+/**
+ * Build a map from its typed (wire) representation (design sections 4.5 and 9.5), adopting the arrays
+ * by reference. "structure" checks lengths, tag values, the dense bound and the Utf8 layout
+ * (E_BAD_SERIALIZATION with details.ref); "full" additionally checks invariant I11: finite numbers,
+ * well-formed UTF-8 (a fatal decode) and distinct ids (E_INVALID_SNAPSHOT with details.invariant
+ * "I11"), building the reverse map eagerly. A dense duplicate is always detected because the inverse
+ * array is rebuilt on load. An unknown kind is E_UNSUPPORTED with details.kind.
+ * @param parts - the typed representation
+ * @param validate - the validation level; default "structure"
+ * @returns the map
+ */
+export declare function nodeIdMapFromTyped(parts: NodeIdMapTypedParts, validate?: ValidationLevel): NodeIdMap;
+/**
+ * The typed (wire) representation of a map (design section 4.5), materialising and caching whatever
+ * the map only held in decoded form: the F64 of a numeric map, the Utf8 store of a string map, the
+ * tags + numbers + Utf8 store of a mixed map. The dense inverse and the reverse Map are never part
+ * of it. Repeated calls return the same arrays.
+ * @param map - the id map
+ * @returns the typed parts; every slot the kind does not use is null
+ */
+export declare function nodeIdMapToTyped(map: NodeIdMap): NodeIdMapTypedParts;
+/**
+ * The map of a gathered node space: `out.idOf(i) === map.idOf(indexMap[i])` (design section 7.3:
+ * inducedSubgraph, relabel). The kind is re-detected from the gathered ids, so an identity map
+ * gathered through a prefix stays identity and otherwise becomes dense or numeric per the rules of
+ * design section 4.2. The caller guarantees indexMap has no repeats (a permutation or a selection),
+ * so the result is a bijection without re-validation.
+ * @param map - the source map
+ * @param indexMap - new index -> source index; E_INDEX_RANGE when an entry is out of range
+ * @returns the gathered map
+ */
+export declare function gatherNodeIdMap(map: NodeIdMap, indexMap: U32): NodeIdMap;
+/**
+ * The map of a compacted node space: `out.idOf(remap[old]) === map.idOf(old)` for every old index
+ * whose entry is not INVALID_INDEX (design sections 4.4 and 6.3 step 1). Every new index must be hit
+ * exactly once.
+ * @param map - the source map
+ * @param remap - old index -> new index or INVALID_INDEX; length === map.size
+ * @param newSize - the compacted node count
+ * @returns the remapped map; E_INDEX_RANGE when remap is not a surjection onto [0, newSize)
+ */
+export declare function remapNodeIdMap(map: NodeIdMap, remap: U32, newSize: number): NodeIdMap;
+export {};
+//# sourceMappingURL=node-id-map.d.ts.map

package/dist/src/ids/node-id-map.d.ts.map

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