@sakuzu/maplibre-gl-draw 1.0.0

package/dist/display/columnar/table.js

@@ -0,0 +1,471 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/** The number of offset arrays of each geometry type */
+const OFFSET_LEVELS = {
+    Point: 0,
+    LineString: 1,
+    MultiPoint: 1,
+    Polygon: 2,
+    MultiLineString: 2,
+    MultiPolygon: 3,
+};
+/**
+ * Whether a column is a dictionary
+ *
+ * @internal
+ */
+export function isDictionaryColumn(column) {
+    return (typeof column === 'object' &&
+        column !== null &&
+        !Array.isArray(column) &&
+        !ArrayBuffer.isView(column) &&
+        'codes' in column);
+}
+/** The number of rows a column holds */
+function columnLength(column) {
+    return isDictionaryColumn(column) ? column.codes.length : column.length;
+}
+/**
+ * The value of a column at a row
+ *
+ * A number of a typed array (null for NaN in a floating point column: the way a missing number
+ * is usually held), the value of a dictionary (null for a code outside it) or the element of a
+ * plain array.
+ *
+ * @internal
+ */
+export function columnValue(column, row) {
+    if (isDictionaryColumn(column)) {
+        const code = column.codes[row];
+        return code >= 0 && code < column.dictionary.length ? column.dictionary[code] : null;
+    }
+    const value = column[row];
+    if ((column instanceof Float64Array || column instanceof Float32Array) && Number.isNaN(value)) {
+        return null;
+    }
+    return value;
+}
+/**
+ * A validated geometry column of a single type: the geometry of a table of one type, or one child
+ * of a mixed geometry column
+ *
+ * @internal
+ */
+export class ColumnarGeometryColumn {
+    /**
+     * @param rows The number of rows (the length of the table), or undefined for a child of a mixed
+     *   column, whose number of rows is read from its arrays
+     * @param path Where the column is in the input (`geometry` or `geometry.children[k]`), for the
+     *   error messages
+     * @throws when the shape of the column does not add up
+     */
+    constructor(geometry, rows, path) {
+        Object.defineProperty(this, "type", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "coords", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The number of values per coordinate (2 or 3) */
+        Object.defineProperty(this, "dimensions", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "offsets", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The number of rows the column holds */
+        Object.defineProperty(this, "length", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        // The messages about the geometry of a table of one type keep their short form
+        const at = rows === undefined ? `${path}: ` : '';
+        if (!geometry || !(geometry.type in OFFSET_LEVELS)) {
+            throw new Error(`Columnar input: ${at}unknown geometry type "${geometry?.type}"`);
+        }
+        if (!(geometry.coords instanceof Float64Array)) {
+            throw new Error(`Columnar input: ${path}.coords must be a Float64Array`);
+        }
+        const dimensions = geometry.dimensions ?? 2;
+        if (dimensions !== 2 && dimensions !== 3) {
+            throw new Error(`Columnar input: ${at}dimensions must be 2 or 3 (got ${dimensions})`);
+        }
+        const offsets = geometry.offsets ?? [];
+        const levels = OFFSET_LEVELS[geometry.type];
+        if (offsets.length !== levels) {
+            throw new Error(`Columnar input: ${at}a ${geometry.type} ${rows === undefined ? 'column' : 'table'} has ${levels} offset arrays (got ${offsets.length})`);
+        }
+        const vertexCount = Math.floor(geometry.coords.length / dimensions);
+        let length = rows;
+        if (length === undefined) {
+            const first = offsets[0];
+            length = levels === 0 ? vertexCount : first instanceof Int32Array ? first.length - 1 : 0;
+            length = Math.max(0, length);
+        }
+        // Each level splits the elements of the level above it
+        let elements = length;
+        for (let level = 0; level < levels; level++) {
+            const array = offsets[level];
+            if (!(array instanceof Int32Array)) {
+                throw new Error(`Columnar input: ${at}offsets[${level}] must be an Int32Array`);
+            }
+            if (array.length < elements + 1) {
+                throw new Error(`Columnar input: ${at}offsets[${level}] has ${array.length} entries for ${elements} elements`);
+            }
+            elements = array[elements];
+        }
+        if (elements > vertexCount) {
+            throw new Error(`Columnar input: ${at}the offsets reach coordinate ${elements} of ${vertexCount} coordinates`);
+        }
+        this.type = geometry.type;
+        this.coords = geometry.coords;
+        this.dimensions = dimensions;
+        this.offsets = offsets;
+        this.length = length;
+    }
+    /** The first coordinate of the run of a row */
+    vertexStart(row) {
+        let at = row;
+        for (let level = 0; level < this.offsets.length; level++)
+            at = this.offsets[level][at];
+        return at;
+    }
+    /** Coordinate `v` as `[lng, lat]` */
+    position(v) {
+        const at = v * this.dimensions;
+        return [this.coords[at], this.coords[at + 1]];
+    }
+    /** The coordinates `[from, to)` as an array of positions */
+    positions(from, to) {
+        const out = new Array(to - from);
+        for (let v = from; v < to; v++)
+            out[v - from] = this.position(v);
+        return out;
+    }
+    /** The coordinates of a row, shaped as for its geometry type */
+    coordinatesOf(row) {
+        const o = this.offsets;
+        switch (this.type) {
+            case 'Point':
+                return this.position(row);
+            case 'LineString':
+            case 'MultiPoint':
+                return this.positions(o[0][row], o[0][row + 1]);
+            case 'Polygon':
+            case 'MultiLineString': {
+                const rings = [];
+                for (let r = o[0][row]; r < o[0][row + 1]; r++) {
+                    rings.push(this.positions(o[1][r], o[1][r + 1]));
+                }
+                return rings;
+            }
+            case 'MultiPolygon': {
+                const polygons = [];
+                for (let p = o[0][row]; p < o[0][row + 1]; p++) {
+                    const rings = [];
+                    for (let r = o[1][p]; r < o[1][p + 1]; r++) {
+                        rings.push(this.positions(o[2][r], o[2][r + 1]));
+                    }
+                    polygons.push(rings);
+                }
+                return polygons;
+            }
+        }
+    }
+}
+/** Whether a geometry column is the mixed form */
+function isMixedGeometry(geometry) {
+    return geometry?.type === 'Mixed';
+}
+/**
+ * A validated columnar table
+ *
+ * @internal
+ */
+export class ColumnarTable {
+    /**
+     * @throws when the shape of the input does not add up (a wrong type, an offset array of the
+     *   wrong length, a column shorter than the table, a row of a mixed column pointing outside its
+     *   child)
+     */
+    constructor(input) {
+        Object.defineProperty(this, "input", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: input
+        });
+        Object.defineProperty(this, "length", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * The geometry columns of a single type: the one column of a table of one type, or the children
+         * of a mixed geometry column
+         */
+        Object.defineProperty(this, "children", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The child of every row (null for a table of one type: every row is in child 0) */
+        Object.defineProperty(this, "childTypes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The row within its child of every row (null for a table of one type: the same row) */
+        Object.defineProperty(this, "childRows", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Whether every geometry of the table is a Point or a MultiPoint */
+        Object.defineProperty(this, "onlyPoints", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "validity", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "ids", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "columns", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The names of the columns (the key order of `columns`) */
+        Object.defineProperty(this, "columnNames", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        const { length, geometry } = input;
+        if (!Number.isInteger(length) || length < 0) {
+            throw new Error(`Columnar input: length must be a non-negative integer (got ${length})`);
+        }
+        if (isMixedGeometry(geometry)) {
+            this.children = readMixedChildren(geometry, length);
+            this.childTypes = geometry.types;
+            this.childRows = geometry.offsets;
+        }
+        else {
+            this.children = [new ColumnarGeometryColumn(geometry, length, 'geometry')];
+            this.childTypes = null;
+            this.childRows = null;
+        }
+        this.onlyPoints = this.children.every((child) => child.type === 'Point' || child.type === 'MultiPoint');
+        if (input.validity && input.validity.length < Math.ceil(length / 8)) {
+            throw new Error('Columnar input: validity is shorter than the table');
+        }
+        if (input.ids && columnLength(input.ids) < length) {
+            throw new Error('Columnar input: ids is shorter than the table');
+        }
+        const columns = input.columns ?? {};
+        for (const [name, column] of Object.entries(columns)) {
+            if (columnLength(column) < length) {
+                throw new Error(`Columnar input: column "${name}" is shorter than the table`);
+            }
+        }
+        this.length = length;
+        this.validity = input.validity;
+        this.ids = input.ids;
+        this.columns = columns;
+        this.columnNames = Object.keys(columns);
+    }
+    /** Whether the validity bitmap marks the row as having a geometry */
+    isValid(row) {
+        const validity = this.validity;
+        return validity === undefined || (validity[row >> 3] & (1 << (row & 7))) !== 0;
+    }
+    /** The index of the child that holds the geometry of a row (-1 for a row without one) */
+    childOf(row) {
+        const types = this.childTypes;
+        if (types === null)
+            return 0;
+        const child = types[row];
+        return child < 0 ? -1 : child;
+    }
+    /** The row within its child of a row */
+    childRowOf(row) {
+        return this.childRows === null ? row : this.childRows[row];
+    }
+    /** The geometry column of a row (undefined for a row without a geometry) */
+    columnOf(row) {
+        const child = this.childOf(row);
+        return child < 0 ? undefined : this.children[child];
+    }
+    /** The value of a column at a row (undefined when the table has no such column) */
+    value(name, row) {
+        const column = this.columns[name];
+        return column === undefined ? undefined : columnValue(column, row);
+    }
+    /** The id of a row */
+    idOf(row) {
+        if (!this.ids)
+            return String(row);
+        return String(columnValue(this.ids, row));
+    }
+    /**
+     * Computes the bbox of every row, `[minX, minY, maxX, maxY]` per row (NaN for a row without a
+     * geometry)
+     */
+    computeBounds() {
+        const n = this.length;
+        const bounds = new Float64Array(n * 4);
+        for (let row = 0; row < n; row++) {
+            const at = row * 4;
+            let minX = Number.POSITIVE_INFINITY;
+            let minY = Number.POSITIVE_INFINITY;
+            let maxX = Number.NEGATIVE_INFINITY;
+            let maxY = Number.NEGATIVE_INFINITY;
+            const column = this.columnOf(row);
+            if (column !== undefined && this.isValid(row)) {
+                const r = this.childRowOf(row);
+                const end = column.vertexStart(r + 1);
+                const coords = column.coords;
+                const stride = column.dimensions;
+                for (let v = column.vertexStart(r); v < end; v++) {
+                    const x = coords[v * stride];
+                    const y = coords[v * stride + 1];
+                    if (x < minX)
+                        minX = x;
+                    if (x > maxX)
+                        maxX = x;
+                    if (y < minY)
+                        minY = y;
+                    if (y > maxY)
+                        maxY = y;
+                }
+            }
+            if (minX === Number.POSITIVE_INFINITY || Number.isNaN(minX) || Number.isNaN(minY)) {
+                bounds[at] = Number.NaN;
+                bounds[at + 1] = Number.NaN;
+                bounds[at + 2] = Number.NaN;
+                bounds[at + 3] = Number.NaN;
+            }
+            else {
+                bounds[at] = minX;
+                bounds[at + 1] = minY;
+                bounds[at + 2] = maxX;
+                bounds[at + 3] = maxY;
+            }
+        }
+        return bounds;
+    }
+    /** The number of coordinates of every row (the estimate of the work of the splitting) */
+    computeVertexCounts() {
+        const n = this.length;
+        const counts = new Int32Array(n);
+        for (let row = 0; row < n; row++) {
+            const column = this.columnOf(row);
+            if (column === undefined)
+                continue;
+            const r = this.childRowOf(row);
+            counts[row] = column.vertexStart(r + 1) - column.vertexStart(r);
+        }
+        return counts;
+    }
+    /** The coordinates of a row, shaped as for its geometry type (a NaN point without a geometry) */
+    coordinatesOf(row) {
+        const column = this.columnOf(row);
+        return column === undefined
+            ? [Number.NaN, Number.NaN]
+            : column.coordinatesOf(this.childRowOf(row));
+    }
+    /** The value of every column at a row */
+    propertiesOf(row) {
+        const properties = {};
+        for (const name of this.columnNames) {
+            properties[name] = columnValue(this.columns[name], row);
+        }
+        return properties;
+    }
+    /**
+     * Materializes one row as a feature
+     *
+     * A row of a mixed column that names no child is a Point with NaN coordinates.
+     *
+     * @param hasGeometry Whether the row has a geometry (a row without one is not visible)
+     */
+    featureAt(row, hasGeometry) {
+        return {
+            id: this.idOf(row),
+            type: this.columnOf(row)?.type ?? 'Point',
+            coordinates: this.coordinatesOf(row),
+            layerId: '',
+            properties: this.propertiesOf(row),
+            locked: false,
+            visible: hasGeometry,
+        };
+    }
+}
+/**
+ * Validates the children of a mixed geometry column and the child and child row of every row
+ *
+ * @throws when an array has the wrong type or is shorter than the table, or when a row names a
+ *   child that does not exist or a row past the end of its child
+ */
+function readMixedChildren(geometry, length) {
+    const { types, offsets, children } = geometry;
+    if (!(types instanceof Int8Array)) {
+        throw new Error('Columnar input: geometry.types must be an Int8Array');
+    }
+    if (!(offsets instanceof Int32Array)) {
+        throw new Error('Columnar input: geometry.offsets must be an Int32Array');
+    }
+    if (!Array.isArray(children)) {
+        throw new Error('Columnar input: geometry.children must be an array');
+    }
+    if (types.length < length) {
+        throw new Error('Columnar input: geometry.types is shorter than the table');
+    }
+    if (offsets.length < length) {
+        throw new Error('Columnar input: geometry.offsets is shorter than the table');
+    }
+    const columns = children.map((child, k) => new ColumnarGeometryColumn(child, undefined, `geometry.children[${k}]`));
+    for (let row = 0; row < length; row++) {
+        const child = types[row];
+        if (child < 0)
+            continue;
+        if (child >= columns.length) {
+            throw new Error(`Columnar input: geometry.types[${row}] is ${child}, but there are ${columns.length} children`);
+        }
+        const at = offsets[row];
+        if (at < 0 || at >= columns[child].length) {
+            throw new Error(`Columnar input: geometry.offsets[${row}] is ${at}, but geometry.children[${child}] has ${columns[child].length} rows`);
+        }
+    }
+    return columns;
+}

package/dist/display/columnar/types.d.ts

@@ -0,0 +1,223 @@
+/**
+ * The columnar input of a dataset
+ *
+ * The rows are given as columns of typed arrays in the layout of GeoArrow (the native encoding
+ * with separated offsets), so a reader of GeoParquet, Arrow or FlatGeobuf can hand what it reads
+ * over without building an object per row, and a Worker can send it to the main thread without a
+ * copy.
+ */
+/**
+ * The geometry type of a geometry column of a single type. A table whose rows have different
+ * types gives a {@link DatasetColumnarMixedGeometry}, made of columns of these types.
+ */
+export type DatasetColumnarGeometryType = 'Point' | 'LineString' | 'Polygon' | 'MultiPoint' | 'MultiLineString' | 'MultiPolygon';
+/**
+ * The geometry column of a columnar table, in the layout of GeoArrow: interleaved coordinates
+ * and the offset arrays, outermost first.
+ *
+ * Every row owns a contiguous run of the coordinates, so the offsets only say where each row,
+ * part and ring starts:
+ *
+ * | Type | `offsets` |
+ * | --- | --- |
+ * | Point | none: row `i` is coordinate `i` |
+ * | LineString, MultiPoint | `[row → coordinate]` |
+ * | Polygon | `[row → ring, ring → coordinate]` |
+ * | MultiLineString | `[row → part, part → coordinate]` |
+ * | MultiPolygon | `[row → polygon, polygon → ring, ring → coordinate]` |
+ *
+ * An offset array has one more entry than the level it splits (the first entry is the start of
+ * the first element, the last is the end of the last), and its values never decrease.
+ *
+ * A row without a geometry has an empty run (two equal offsets), or NaN coordinates for a Point,
+ * or a 0 bit in {@link DatasetColumnarInput.validity}. It is neither drawn nor hit.
+ *
+ * @example A table of two lines
+ * ```ts
+ * const geometry: DatasetColumnarGeometry = {
+ *   type: 'LineString',
+ *   coords: new Float64Array([139.70, 35.68, 139.71, 35.69, 139.72, 35.66, 139.73, 35.67]),
+ *   offsets: [new Int32Array([0, 2, 4])],
+ * };
+ * ```
+ */
+export interface DatasetColumnarGeometry {
+    /** The geometry type of every row */
+    type: DatasetColumnarGeometryType;
+    /**
+     * The coordinates in degrees, interleaved: `[lng0, lat0, lng1, lat1, ...]`, or
+     * `[lng0, lat0, z0, ...]` with `dimensions: 3`
+     */
+    coords: Float64Array;
+    /**
+     * The number of values per coordinate: 2 (`xy`, the default) or 3 (`xyz`; the third value is
+     * skipped)
+     */
+    dimensions?: 2 | 3;
+    /** The offset arrays, outermost first (see the table above). Omitted or empty for Point */
+    offsets?: Int32Array[];
+}
+/**
+ * The geometry column of a table whose rows have different geometry types, in the layout of the
+ * mixed geometry of GeoArrow (a dense union of Arrow): a geometry column of a single type per
+ * child, and for every row of the table the child and the row within it.
+ *
+ * The geometry of row `i` is row `offsets[i]` of `children[types[i]]`, and row `i` behaves exactly
+ * as the feature of that child's type with those coordinates. The rows of a child can be in any
+ * order; the draw order is the order of the table rows. A row with a negative `types[i]` has no
+ * geometry (as a 0 bit in {@link DatasetColumnarInput.validity}, which still applies on top). The
+ * number of rows of a child is read from its arrays: the coordinates for a Point column,
+ * `offsets[0].length - 1` for the others.
+ *
+ * @example A point, a line and a polygon, the polygon first in the table
+ * ```ts
+ * const geometry: DatasetColumnarMixedGeometry = {
+ *   type: 'Mixed',
+ *   types: new Int8Array([2, 0, 1]),
+ *   offsets: new Int32Array([0, 0, 0]),
+ *   children: [
+ *     { type: 'Point', coords: new Float64Array([139.70, 35.68]) },
+ *     {
+ *       type: 'LineString',
+ *       coords: new Float64Array([139.71, 35.69, 139.72, 35.70]),
+ *       offsets: [new Int32Array([0, 2])],
+ *     },
+ *     {
+ *       type: 'Polygon',
+ *       coords: new Float64Array([139.73, 35.66, 139.75, 35.66, 139.75, 35.68, 139.73, 35.66]),
+ *       offsets: [new Int32Array([0, 1]), new Int32Array([0, 4])],
+ *     },
+ *   ],
+ * };
+ * ```
+ */
+export interface DatasetColumnarMixedGeometry {
+    /** Marks the mixed form */
+    type: 'Mixed';
+    /**
+     * For every row, the child column that holds its geometry (an index into `children`; negative
+     * for a row without a geometry)
+     */
+    types: Int8Array;
+    /** For every row, the row within its child column */
+    offsets: Int32Array;
+    /** The geometry columns of a single type */
+    children: DatasetColumnarGeometry[];
+}
+/**
+ * The integer arrays that can hold the codes of a {@link DatasetDictionaryColumn}.
+ */
+export type DatasetDictionaryCodes = Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array;
+/**
+ * An attribute column encoded as a dictionary (the dictionary type of Arrow): the value of row
+ * `i` is `dictionary[codes[i]]`. A negative code, or one past the end of the dictionary, means
+ * no value (`null`).
+ *
+ * @example
+ * ```ts
+ * const category: DatasetDictionaryColumn = {
+ *   codes: new Int32Array([0, 1, 0, -1]),
+ *   dictionary: ['cafe', 'school'],
+ * }; // 'cafe', 'school', 'cafe', null
+ * ```
+ */
+export interface DatasetDictionaryColumn {
+    /** The code of each row */
+    codes: DatasetDictionaryCodes;
+    /** The distinct values */
+    dictionary: readonly (string | number | boolean | null)[];
+}
+/**
+ * An attribute column of a columnar table: a typed array of numbers, a dictionary, or a plain
+ * array of values. Row `i` of the table is element `i` of the column. In a `Float64Array` or a
+ * `Float32Array`, NaN means no value (`null`).
+ */
+export type DatasetColumn = Float64Array | Float32Array | Int32Array | Uint32Array | Int16Array | Uint16Array | Int8Array | Uint8Array | DatasetDictionaryColumn | readonly unknown[];
+/**
+ * The rows of a dataset given as columns, the counterpart of an array of
+ * {@link DatasetFeatureInput}. Pass it as `columnar` to
+ * {@link MapLibreGLDraw.addDataset} or to {@link Dataset.setColumnar}.
+ *
+ * Nothing is copied: the dataset keeps and reads the arrays, so do not change them while the
+ * dataset holds them (replace the table with `setColumnar` instead). Every array can be sent
+ * from a Worker without a copy; `columnarTransferables` from
+ * `@sakuzu/maplibre-gl-draw/columnar` lists their buffers.
+ *
+ * Row `i` behaves as the feature `{ id, type: geometry.type, coordinates, properties }` where
+ * `coordinates` are read from the geometry column, `properties` holds the value of every column at
+ * row `i`, and `id` is `String(ids[i])` (or `String(i)` without `ids`). With a
+ * {@link DatasetColumnarMixedGeometry}, `type` and `coordinates` are those of the row's child
+ * column. The rows have no individual style; the style rule and the base style of the dataset
+ * color them.
+ *
+ * @example
+ * ```ts
+ * const places: DatasetColumnarInput = {
+ *   length: 3,
+ *   geometry: {
+ *     type: 'Point',
+ *     coords: new Float64Array([139.70, 35.68, 139.71, 35.69, 139.72, 35.66]),
+ *   },
+ *   columns: {
+ *     name: ['Shinjuku', 'Yoyogi', 'Shibuya'],
+ *     visitors: new Float64Array([3.5, 0.7, 3.0]),
+ *   },
+ * };
+ * draw.addDataset({ id: 'places', columnar: places });
+ * ```
+ */
+export interface DatasetColumnarInput {
+    /** The number of rows */
+    length: number;
+    /**
+     * The geometry column: of one type, or {@link DatasetColumnarMixedGeometry} for rows of
+     * different types
+     */
+    geometry: DatasetColumnarGeometry | DatasetColumnarMixedGeometry;
+    /**
+     * Which rows have a geometry, as the validity bitmap of Arrow: bit `i % 8` of byte `i >> 3` (the
+     * lowest bit first) is 1 for a row with a geometry. Every row has one when omitted
+     */
+    validity?: Uint8Array;
+    /**
+     * The id of each row, turned into a string with `String()` (the row number as a string when
+     * omitted). The ids must be unique within the table
+     */
+    ids?: DatasetColumn;
+    /**
+     * The attribute columns by name. They become the `properties` of the rows, which the style
+     * rule reads. Passing only the columns that the rule and the host read is enough
+     */
+    columns?: Record<string, DatasetColumn>;
+}
+/**
+ * What `prepareDatasetColumnar` (from `@sakuzu/maplibre-gl-draw/columnar`) computes from a
+ * columnar table so that the main thread does not have to: the bbox of each row, the spatial
+ * chunks and the spatial index of the hit testing.
+ *
+ * Every field is a typed array, so it can be sent from a Worker without a copy. Treat it as
+ * opaque: pass it with the same table to {@link Dataset.setColumnar} or as `prepared` to
+ * {@link MapLibreGLDraw.addDataset}.
+ */
+export interface DatasetColumnarPrepared {
+    /** The number of rows it was computed for (it must equal the `length` of the table) */
+    readonly length: number;
+    /** The bbox of each row, `[minX, minY, maxX, maxY]` (NaN for a row without a geometry) */
+    readonly bounds: Float64Array;
+    /** The rows of every chunk, chunk after chunk */
+    readonly chunkRows: Int32Array;
+    /** Where each chunk starts in `chunkRows` (the chunk count + 1 entries) */
+    readonly chunkOffsets: Int32Array;
+    /** The bbox of each chunk, `[minX, minY, maxX, maxY]` */
+    readonly chunkBounds: Float64Array;
+    /** The number of entries of one node of the spatial index */
+    readonly indexNodeSize: number;
+    /** The number of leaves of the spatial index (the rows with a geometry) */
+    readonly indexItemCount: number;
+    /** The boxes of the spatial index */
+    readonly indexBoxes: Float64Array;
+    /** The rows and child positions of the spatial index */
+    readonly indexEntries: Int32Array;
+    /** The end of each level of the spatial index */
+    readonly indexLevels: Int32Array;
+}

package/dist/display/columnar/types.js

@@ -0,0 +1,3 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};