@graphty/graph-format 0.0.0 → 0.2.0

package/dist/src/columns/growable.js

@@ -0,0 +1,296 @@
+/**
+ * Growable typed staging for the builder (design section 6.2): structure-of-arrays typed arrays that
+ * grow by doubling (capacity rounded up to 16 elements, backing buffers a multiple of 64 bytes) into
+ * a resizable ArrayBuffer when the engine has one and by allocate-and-copy otherwise. The edge arrays
+ * (src, dst, weight), the incidence lists, the per-declaration column data and the alive / weightSet /
+ * validity bitmaps of the builder are all instances of the two classes here.
+ *
+ * Nothing a snapshot holds may alias staging (invariant I18): view() hands out a zero-copy window for
+ * the freeze passes to read, and trim() produces the exact-length copy over a fresh fixed-length
+ * buffer that a snapshot may keep.
+ */
+import { allocateStagingBuffer, growTypedArray, HAS_RESIZABLE_ARRAY_BUFFER, roundUp, STAGING_ELEMENT_GRANULE, stagingByteLength, } from "../util/typed-array.js";
+import { bitmapClearTrailing, bitmapCount, bitmapGet, bitmapSet, bitmapWordCount, bitmapWrite } from "./bitmap.js";
+/** Every bit set: the fill word of a range of whole words. */
+const ALL_ONES = 0xffffffff;
+/**
+ * A typed array that grows by doubling (design section 6.2). `length` is the number of elements in
+ * use; `capacity` the allocated element count. Elements between length and capacity are unspecified
+ * until written. Growth may replace the backing view object, so hot loops that cache `array` re-read
+ * it after any call that can grow (push, pushAll, resize, ensureCapacity).
+ */
+export class GrowableTypedArray {
+    /**
+     * Create an empty growable array.
+     * @param ctor - the typed-array class of the elements (Uint32Array, Float32Array, ...)
+     * @param options - initial capacity and buffer kind
+     */
+    constructor(ctor, options) {
+        this.used = 0;
+        this.ctor = ctor;
+        this.resizable = options?.resizable ?? HAS_RESIZABLE_ARRAY_BUFFER;
+        this.backing = this.allocate(options?.capacity ?? 0);
+    }
+    /**
+     * The number of elements in use.
+     * @returns the length
+     */
+    get length() {
+        return this.used;
+    }
+    /**
+     * The allocated element count; growth happens when length would exceed it.
+     * @returns the capacity
+     */
+    get capacity() {
+        return this.backing.length;
+    }
+    /**
+     * The backing view over the whole capacity, for hot loops that index it directly. Its identity
+     * changes whenever the array grows.
+     * @returns the backing typed array
+     */
+    get array() {
+        return this.backing;
+    }
+    /**
+     * Append one element.
+     * @param value - the element
+     * @returns the index it was written at (the old length)
+     */
+    push(value) {
+        const index = this.used;
+        if (index >= this.backing.length) {
+            this.backing = growTypedArray(this.backing, this.ctor, index + 1, this.resizable);
+        }
+        this.backing[index] = value;
+        this.used = index + 1;
+        return index;
+    }
+    /**
+     * Append many elements at once (bulk addEdges input).
+     * @param values - the elements, in order
+     * @returns the index the first one was written at (the old length)
+     */
+    pushAll(values) {
+        const index = this.used;
+        const end = index + values.length;
+        this.ensureCapacity(end);
+        this.backing.set(values, index);
+        this.used = end;
+        return index;
+    }
+    /**
+     * Read element i.
+     * @param i - the index, below length
+     * @returns the element
+     */
+    get(i) {
+        return this.backing[i];
+    }
+    /**
+     * Write element i.
+     * @param i - the index, below length
+     * @param value - the element
+     */
+    set(i, value) {
+        this.backing[i] = value;
+    }
+    /**
+     * Make sure at least `n` elements fit without a further reallocation.
+     * @param n - the capacity to guarantee
+     */
+    ensureCapacity(n) {
+        if (n > this.backing.length) {
+            this.backing = growTypedArray(this.backing, this.ctor, n, this.resizable);
+        }
+    }
+    /**
+     * Set the length: growing fills the new elements with `fill` (the incidence lists grow with
+     * INVALID_INDEX), shrinking drops the tail without releasing capacity.
+     * @param length - the new length
+     * @param fill - the value written into elements [old length, length); defaults to 0
+     */
+    resize(length, fill = 0) {
+        if (length > this.used) {
+            this.ensureCapacity(length);
+            this.backing.fill(fill, this.used, length);
+        }
+        this.used = length;
+    }
+    /**
+     * A zero-copy window over the elements in use. It aliases staging, so it is for the freeze passes
+     * to read from and never for a snapshot to keep (invariant I18); it is invalidated by growth.
+     * @returns a view of exactly `length` elements
+     */
+    view() {
+        return new this.ctor(this.backing.buffer, 0, this.used);
+    }
+    /**
+     * An exact-length copy over a fresh fixed-length ArrayBuffer: what a snapshot may keep, and what a
+     * compaction writes back through.
+     * @returns a new typed array of `length` elements
+     */
+    trim() {
+        const out = new this.ctor(new ArrayBuffer(this.used * this.ctor.BYTES_PER_ELEMENT), 0, this.used);
+        out.set(this.view());
+        return out;
+    }
+    /**
+     * Drop every element but keep the capacity (a builder reused after a merging freeze).
+     */
+    clear() {
+        this.used = 0;
+    }
+    /**
+     * Drop the elements and the backing storage (freeze({ release: true }) and dispose(), design
+     * section 6.1). The array is usable again afterwards; the next push allocates.
+     */
+    release() {
+        this.used = 0;
+        this.backing = this.allocate(0);
+    }
+    /**
+     * Allocate a backing view of at least `capacity` elements over a fresh staging buffer.
+     * @param capacity - the element count wanted; 0 allocates an empty view over an empty buffer
+     * @returns the view
+     */
+    allocate(capacity) {
+        const bytesPerElement = this.ctor.BYTES_PER_ELEMENT;
+        const byteLength = capacity === 0 ? 0 : stagingByteLength(roundUp(capacity, STAGING_ELEMENT_GRANULE), bytesPerElement);
+        return new this.ctor(allocateStagingBuffer(byteLength, this.resizable), 0, byteLength / bytesPerElement);
+    }
+}
+/**
+ * A growable packed bitmap (design section 6.2: nodeAlive, edgeAlive, weightSet and the validity of
+ * every staging column), in the one LSB-first u32 layout of design section 5.3. `length` is in bits;
+ * every bit at or above it is kept clear so view() and trim() are exact bitmaps over `length` bits.
+ */
+export class GrowableBitmap {
+    /**
+     * Create an empty bitmap.
+     * @param options - initial capacity in bits and buffer kind
+     */
+    constructor(options) {
+        this.bits = 0;
+        this.words = new GrowableTypedArray(Uint32Array, {
+            capacity: bitmapWordCount(options?.capacity ?? 0),
+            resizable: options?.resizable,
+        });
+    }
+    /**
+     * The number of bits in use.
+     * @returns the length in bits
+     */
+    get length() {
+        return this.bits;
+    }
+    /**
+     * Append one bit.
+     * @param value - the bit
+     * @returns the index it was written at (the old length)
+     */
+    push(value) {
+        const index = this.bits;
+        if (index % 32 === 0) {
+            this.words.push(0);
+        }
+        if (value) {
+            bitmapWrite(this.words.array, index, true);
+        }
+        this.bits = index + 1;
+        return index;
+    }
+    /**
+     * Read bit i.
+     * @param i - the bit index, below length
+     * @returns true when set
+     */
+    get(i) {
+        return bitmapGet(this.words.array, i);
+    }
+    /**
+     * Write bit i.
+     * @param i - the bit index, below length
+     * @param value - the bit
+     */
+    set(i, value) {
+        bitmapWrite(this.words.array, i, value);
+    }
+    /**
+     * The number of set bits below length.
+     * @returns the count
+     */
+    count() {
+        return bitmapCount(this.words.array, this.bits);
+    }
+    /**
+     * Set the length in bits: growing writes `fill` into the new bits, shrinking clears the dropped
+     * bits so the trailing-bits-clear convention holds.
+     * @param length - the new length in bits
+     * @param fill - the value of bits [old length, length); defaults to false
+     */
+    resize(length, fill = false) {
+        const oldBits = this.bits;
+        this.words.resize(bitmapWordCount(length), 0);
+        if (length < oldBits) {
+            bitmapClearTrailing(this.words.array, length);
+        }
+        else if (fill && length > oldBits) {
+            this.setRange(oldBits, length);
+        }
+        this.bits = length;
+    }
+    /**
+     * Set every bit in [from, to): the ragged head and tail bit by bit, the whole words in between
+     * with one fill.
+     * @param from - the first bit to set
+     * @param to - one past the last bit to set
+     */
+    setRange(from, to) {
+        const { array } = this.words;
+        let i = from;
+        while (i < to && i % 32 !== 0) {
+            bitmapSet(array, i++);
+        }
+        const fullEnd = to - (to % 32);
+        if (i < fullEnd) {
+            array.fill(ALL_ONES, i / 32, fullEnd / 32);
+            i = fullEnd;
+        }
+        while (i < to) {
+            bitmapSet(array, i++);
+        }
+    }
+    /**
+     * A zero-copy window over the ceil(length / 32) words in use; aliases staging (invariant I18) and
+     * is invalidated by growth.
+     * @returns the words
+     */
+    view() {
+        return this.words.view();
+    }
+    /**
+     * An exact copy of the words in use over a fresh fixed-length ArrayBuffer: a validity bitmap or a
+     * bool column's data a snapshot may keep.
+     * @returns a new U32 of ceil(length / 32) words
+     */
+    trim() {
+        return this.words.trim();
+    }
+    /**
+     * Drop every bit but keep the capacity.
+     */
+    clear() {
+        this.bits = 0;
+        this.words.clear();
+    }
+    /**
+     * Drop the bits and the backing storage.
+     */
+    release() {
+        this.bits = 0;
+        this.words.release();
+    }
+}
+//# sourceMappingURL=growable.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"growable.js","sourceRoot":"","sources":["../../../src/columns/growable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EACH,qBAAqB,EACrB,cAAc,EACd,0BAA0B,EAC1B,OAAO,EACP,uBAAuB,EACvB,iBAAiB,GAEpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEnH,8DAA8D;AAC9D,MAAM,QAAQ,GAAG,UAAU,CAAC;AAa5B;;;;;GAKG;AACH,MAAM,OAAO,kBAAkB;IAM3B;;;;OAIG;IACH,YAAY,IAAuB,EAAE,OAAyB;QAPtD,SAAI,GAAG,CAAC,CAAC;QAQb,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,0BAA0B,CAAC;QAClE,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,IAAI,CAAC,CAAC,CAAC;IACzD,CAAC;IAED;;;OAGG;IACH,IAAI,MAAM;QACN,OAAO,IAAI,CAAC,IAAI,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,IAAI,QAAQ;QACR,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACH,IAAI,KAAK;QACL,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;IAED;;;;OAIG;IACH,IAAI,CAAC,KAAa;QACd,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC;QACxB,IAAI,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YAC/B,IAAI,CAAC,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC;QACtB,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,MAAyB;QAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC;QACxB,MAAM,GAAG,GAAG,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC;QAClC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAChB,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,CAAS;QACT,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,CAAS,EAAE,KAAa;QACxB,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACH,cAAc,CAAC,CAAS;QACpB,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YAC1B,IAAI,CAAC,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAC9E,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAc,EAAE,IAAI,GAAG,CAAC;QAC3B,IAAI,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YACrB,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;YAC5B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,IAAI;QACA,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5D,CAAC;IAED;;;;OAIG;IACH,IAAI;QACA,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAClG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACrB,OAAO,GAAG,CAAC;IACf,CAAC;IAED;;OAEG;IACH,KAAK;QACD,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;IAClB,CAAC;IAED;;;OAGG;IACH,OAAO;QACH,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACd,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC;IAED;;;;OAIG;IACK,QAAQ,CAAC,QAAgB;QAC7B,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC;QACpD,MAAM,UAAU,GACZ,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,QAAQ,EAAE,uBAAuB,CAAC,EAAE,eAAe,CAAC,CAAC;QACxG,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,CAAC;IAC7G,CAAC;CACJ;AAED;;;;GAIG;AACH,MAAM,OAAO,cAAc;IAIvB;;;OAGG;IACH,YAAY,OAAyB;QAN7B,SAAI,GAAG,CAAC,CAAC;QAOb,IAAI,CAAC,KAAK,GAAG,IAAI,kBAAkB,CAAM,WAAW,EAAE;YAClD,QAAQ,EAAE,eAAe,CAAC,OAAO,EAAE,QAAQ,IAAI,CAAC,CAAC;YACjD,SAAS,EAAE,OAAO,EAAE,SAAS;SAChC,CAAC,CAAC;IACP,CAAC;IAED;;;OAGG;IACH,IAAI,MAAM;QACN,OAAO,IAAI,CAAC,IAAI,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACH,IAAI,CAAC,KAAc;QACf,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC;QACxB,IAAI,KAAK,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC;YACnB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvB,CAAC;QACD,IAAI,KAAK,EAAE,CAAC;YACR,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,CAAC,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC;QACtB,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,CAAS;QACT,OAAO,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,CAAS,EAAE,KAAc;QACzB,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;IAC5C,CAAC;IAED;;;OAGG;IACH,KAAK;QACD,OAAO,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAc,EAAE,IAAI,GAAG,KAAK;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC;QAC1B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9C,IAAI,MAAM,GAAG,OAAO,EAAE,CAAC;YACnB,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAClD,CAAC;aAAM,IAAI,IAAI,IAAI,MAAM,GAAG,OAAO,EAAE,CAAC;YAClC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACnC,CAAC;QACD,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;OAKG;IACK,QAAQ,CAAC,IAAY,EAAE,EAAU;QACrC,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAC7B,IAAI,CAAC,GAAG,IAAI,CAAC;QACb,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC;YAC5B,SAAS,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;QAC1B,CAAC;QACD,MAAM,OAAO,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;QAC/B,IAAI,CAAC,GAAG,OAAO,EAAE,CAAC;YACd,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,OAAO,GAAG,EAAE,CAAC,CAAC;YAC3C,CAAC,GAAG,OAAO,CAAC;QAChB,CAAC;QACD,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC;YACZ,SAAS,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;QAC1B,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,IAAI;QACA,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,IAAI;QACA,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,KAAK;QACD,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACd,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,OAAO;QACH,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACd,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;CACJ"}

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

@@ -0,0 +1,121 @@
+/**
+ * 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.
+ */
+/** The dtypes inference can produce, in widening order. */
+export type InferredDtype = "bool" | "i32" | "f64" | "string" | "json";
+/** The widening order of design section 5.1; a column only ever moves to the right. */
+export declare const WIDENING_ORDER: readonly InferredDtype[];
+/**
+ * The rank of a dtype in the widening order.
+ * @param dtype - an inferred dtype
+ * @returns 0 for bool up to 4 for json
+ */
+export declare function wideningRank(dtype: InferredDtype): number;
+/**
+ * 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 declare function widenDtype(current: InferredDtype | null, observed: InferredDtype | null): InferredDtype | null;
+/**
+ * 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 declare function inferTextDtype(text: string): "bool" | "i32" | "f64" | "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 declare function inferValueDtype(value: unknown): InferredDtype | null;
+/**
+ * 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 declare function parseText(text: string, dtype: InferredDtype): boolean | number | string;
+/**
+ * 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 declare function coerceValue(value: unknown, dtype: InferredDtype): unknown;
+/**
+ * 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 declare function inferValuesDtype(values: Iterable<unknown>): InferredDtype | null;
+/**
+ * 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 declare function inferTextsDtype(cells: Iterable<string>): InferredDtype | null;
+/**
+ * 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 declare class DtypeInferrer {
+    private current;
+    /**
+     * The column's dtype so far.
+     * @returns the widened dtype, or null until a set cell has been observed
+     */
+    get dtype(): InferredDtype | null;
+    /**
+     * 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: unknown): boolean;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: InferredDtype): boolean;
+    private apply;
+}
+//# sourceMappingURL=infer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"infer.d.ts","sourceRoot":"","sources":["../../../src/columns/infer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEvE,uFAAuF;AACvF,eAAO,MAAM,cAAc,EAAE,SAAS,aAAa,EAA6C,CAAC;AAQjG;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAEzD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI,GAAG,aAAa,GAAG,IAAI,CAQ9G;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,CAe9E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAmBpE;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CA6BvF;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAmCzE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,aAAa,GAAG,IAAI,CAShF;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,aAAa,GAAG,IAAI,CAS7E;AAED;;;;GAIG;AACH,qBAAa,aAAa;IACtB,OAAO,CAAC,OAAO,CAA8B;IAE7C;;;OAGG;IACH,IAAI,KAAK,IAAI,aAAa,GAAG,IAAI,CAEhC;IAED;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAIrC;;;;;;OAMG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIlC;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO;IAItC,OAAO,CAAC,KAAK;CAQhB"}