@maplibre/geojson-vt 5.0.3 → 6.0.0

package/src/definitions.ts

@@ -53,34 +53,212 @@ export type GeoJSONVTOptions = {
      * @default 0
      */
     debug?: number;
+    /**
+     * Enable Supercluster for point features.
+     * @default false
+     */
+    cluster?: boolean;
+    /**
+     * Options for the Supercluster point clustering algorithm.
+     * @see {@link SuperclusterOptions}
+     */
+    clusterOptions?: SuperclusterOptions;
 };
 
+export type GeoJSONToTileOptions = GeoJSONVTOptions & {
+    /**
+     * Whether to wrap features around the antimeridian
+     * @default false
+     */
+    wrap?: boolean;
+    /**
+     * Whether to clip features to the tile boundary
+     * @default false
+     */
+    clip?: boolean;
+};
 
 export type StartEndSizeArray = number[] & { start?: number; end?: number; size?: number };
 
 export type PartialGeoJSONVTFeature = {
     id?: number | string | undefined;
     tags: GeoJSON.GeoJsonProperties;
-    minX: number;
-    minY: number;
-    maxX: number;
-    maxY: number;
+    minX?: number;
+    minY?: number;
+    maxX?: number;
+    maxY?: number;
+}
+
+export type GeoJSONVTInternalPointFeature = PartialGeoJSONVTFeature & {
+    type: 'Point';
+    geometry: number[];
+};
+
+export type GeoJSONVTInternalMultiPointFeature = PartialGeoJSONVTFeature & {
+    type: 'MultiPoint';
+    geometry: number[];
+};
+
+export type GeoJSONVTInternalLineStringFeature = PartialGeoJSONVTFeature & {
+    type: 'LineString';
+    geometry: StartEndSizeArray;
+};
+
+export type GeoJSONVTInternalMultiLineStringFeature = PartialGeoJSONVTFeature & {
+    type: 'MultiLineString';
+    geometry: StartEndSizeArray[];
+};
+
+export type GeoJSONVTInternalPolygonFeature = PartialGeoJSONVTFeature & {
+    type: 'Polygon';
+    geometry: StartEndSizeArray[];
+};
+
+export type GeoJSONVTInternalMultiPolygonFeature = PartialGeoJSONVTFeature & {
+    type: 'MultiPolygon';
+    geometry: StartEndSizeArray[][];
+};
+
+export type GeoJSONVTInternalFeature =
+    | GeoJSONVTInternalPointFeature
+    | GeoJSONVTInternalMultiPointFeature
+    | GeoJSONVTInternalLineStringFeature
+    | GeoJSONVTInternalMultiLineStringFeature
+    | GeoJSONVTInternalPolygonFeature
+    | GeoJSONVTInternalMultiPolygonFeature;
+
+/**
+ * The geojson properies related to a cluster.
+ */
+export type ClusterProperties = {
+    cluster: true;
+    cluster_id: number;
+    point_count: number;
+    point_count_abbreviated: string | number;
+    [key: string]: unknown;
+};
+
+/**
+ * A geojson point with cluster properties, see {@link ClusterProperties}.
+ */
+export type ClusterFeature = GeoJSON.Feature<GeoJSON.Point, ClusterProperties>;
+
+/**
+ * A geojson point that is either a regular point or a cluster, which is a point with cluster properties.
+ * See {@link ClusterFeature} for more information
+ */
+export type ClusterOrPointFeature = ClusterFeature | GeoJSON.Feature<GeoJSON.Point>;
+
+export type GeoJSONVTInternalTileFeaturePoint = {
+    id? : number | string | undefined;
+    type: 1;
+    tags: GeoJSON.GeoJsonProperties | null;
+    geometry: number[];
+}
+
+export type GeoJSONVTInternalTileFeatureNonPoint = {
+    id? : number | string | undefined;
+    type: 2 | 3;
+    tags: GeoJSON.GeoJsonProperties | null;
+    geometry: number[][];
+}
+export type GeoJSONVTInternalTileFeature = GeoJSONVTInternalTileFeaturePoint | GeoJSONVTInternalTileFeatureNonPoint;
+
+export type GeoJSONVTInternalTile = {
+    transformed: boolean;
+    features: GeoJSONVTInternalTileFeature[];
+    source: GeoJSONVTInternalFeature[] | null;
+    x: number;
+    y: number;
+    z: number;
+    minX?: number;
+    minY?: number;
+    maxX?: number;
+    maxY?: number;
+    numPoints?: number;
+    numSimplified?: number;
+    numFeatures?: number;
+}
+
+export type GeoJSONVTFeaturePoint = {
+    id? : number | string | undefined;
+    type: 1;
+    tags: GeoJSON.GeoJsonProperties | null;
+    geometry: [number, number][]
 }
 
-export type GeometryTypeMap = {
-    Point: number[];
-    MultiPoint: number[];
-    LineString: StartEndSizeArray;
-    MultiLineString: StartEndSizeArray[];
-    Polygon: StartEndSizeArray[];
-    MultiPolygon: StartEndSizeArray[][];
+export type GeoJSONVTFeatureNonPoint = {
+    id? : number | string | undefined;
+    type: 2 | 3;
+    tags: GeoJSON.GeoJsonProperties | null;
+    geometry: [number, number][][]
 }
 
-export type GeometryType = "Point" | "MultiPoint" | "LineString" | "MultiLineString" | "Polygon" | "MultiPolygon";
+export type GeoJSONVTFeature = GeoJSONVTFeaturePoint | GeoJSONVTFeatureNonPoint;
+
+export type GeoJSONVTTile = GeoJSONVTInternalTile & {
+    transformed: true;
+    features: GeoJSONVTFeature[]
+}
 
-export type GeoJSONVTInternalFeature = {
-    [K in GeometryType]: PartialGeoJSONVTFeature & {
-        type: K;
-        geometry: GeometryTypeMap[K];
-    }
-}[GeometryType];
+export interface GeoJSONVTTileIndex {
+    initialize(features: GeoJSONVTInternalFeature[]): void;
+    updateIndex(source: GeoJSONVTInternalFeature[], affected: GeoJSONVTInternalFeature[], options: GeoJSONVTOptions): void;
+    getClusterExpansionZoom(clusterId: number): number | null;
+    getChildren(clusterId: number): ClusterOrPointFeature[] | null;
+    getLeaves(clusterId: number, limit?: number, offset?: number): GeoJSON.Feature<GeoJSON.Point>[] | null
+    getTile(z: number, x: number, y: number): GeoJSONVTTile | null
+}
+
+export type SuperclusterOptions = {
+    /**
+     * Min zoom to generate clusters on
+     * @default 0
+     */
+    minZoom?: number;
+    /**
+     * Max zoom level to cluster the points on
+     * @default 16
+     */
+    maxZoom?: number;
+    /**
+     * Minimum points to form a cluster
+     * @default 2
+     */
+    minPoints?: number;
+    /**
+     * Cluster radius in pixels
+     * @default 40
+     */
+    radius?: number;
+    /**
+     * Tile extent (radius is calculated relative to it)
+     * @default 512
+     */
+    extent?: number;
+    /**
+     * Size of the KD-tree leaf node, affects performance
+     * @default 64
+     */
+    nodeSize?: number;
+    /**
+     * Whether to log timing info
+     * @default false
+     */
+    log?: boolean;
+    /**
+     * Whether to generate numeric ids for input features (in vector tiles)
+     * @default false
+     */
+    generateId?: boolean;
+    /**
+     * A reduce function for calculating custom cluster properties
+     * @default null
+     */
+    reduce?: ((accumulated: Record<string, unknown>, props: Record<string, unknown>) => void) | null;
+    /**
+     * Properties to use for individual points when running the reducer
+     * @default props => props
+     */
+    map?: (props: GeoJSON.GeoJsonProperties) => Record<string, unknown>;
+};

package/src/difference.ts

@@ -1,4 +1,4 @@
-import {convert} from './convert';
+import {convertToInternal} from './convert';
 import {wrap} from './wrap';
 import type { GeoJSONVTInternalFeature, GeoJSONVTOptions } from './definitions';
 
@@ -103,7 +103,7 @@ export function applySourceDiff(source: GeoJSONVTInternalFeature[], dataDiff: Ge
         // convert and add new features
         if (diff.add.size) {
             // projects and adds simplification info
-            let addFeatures = convert({type: 'FeatureCollection', features: Array.from(diff.add.values())}, options);
+            let addFeatures = convertToInternal({type: 'FeatureCollection', features: Array.from(diff.add.values())}, options);
 
             // wraps features (ie extreme west and extreme east)
             addFeatures = wrap(addFeatures, options);
@@ -154,7 +154,7 @@ function getUpdatedFeature(vtFeature: GeoJSONVTInternalFeature, update: GeoJSONV
         };
 
         // projects and adds simplification info
-        let features = convert({type: 'FeatureCollection', features: [geojsonFeature]}, options);
+        let features = convertToInternal({type: 'FeatureCollection', features: [geojsonFeature]}, options);
 
         // wraps features (ie extreme west and extreme east)
         features = wrap(features, options);

package/src/feature.ts

@@ -1,6 +1,13 @@
-import type { GeoJSONVTInternalFeature, GeometryType, GeometryTypeMap } from "./definitions";
+import type { GeoJSONVTInternalFeature, GeoJSONVTInternalLineStringFeature, GeoJSONVTInternalMultiLineStringFeature, GeoJSONVTInternalMultiPointFeature, GeoJSONVTInternalMultiPolygonFeature, GeoJSONVTInternalPointFeature, GeoJSONVTInternalPolygonFeature } from "./definitions";
 
-export type SupportedGeometries = GeoJSON.Point | GeoJSON.MultiPoint | GeoJSON.LineString | GeoJSON.MultiLineString | GeoJSON.Polygon | GeoJSON.MultiPolygon;
+type FeatureTypeMap = {
+    Point: GeoJSONVTInternalPointFeature["geometry"];
+    MultiPoint: GeoJSONVTInternalMultiPointFeature["geometry"];
+    LineString: GeoJSONVTInternalLineStringFeature["geometry"];
+    MultiLineString: GeoJSONVTInternalMultiLineStringFeature["geometry"];
+    Polygon: GeoJSONVTInternalPolygonFeature["geometry"];
+    MultiPolygon: GeoJSONVTInternalMultiPolygonFeature["geometry"];
+};
 
 /**
  * 
@@ -10,9 +17,9 @@ export type SupportedGeometries = GeoJSON.Point | GeoJSON.MultiPoint | GeoJSON.L
  * @param tags - the feature's properties
  * @returns the created feature
  */
-export function createFeature<T extends GeometryType>(id: number | string | undefined, type: T, geom: GeometryTypeMap[T], tags: GeoJSON.GeoJsonProperties): GeoJSONVTInternalFeature {
+export function createFeature<T extends GeoJSONVTInternalFeature["type"]>(id: number | string | undefined, type: T, geom: FeatureTypeMap[T], tags: GeoJSON.GeoJsonProperties): GeoJSONVTInternalFeature {
     // This is mostly for TypeScript type narrowing
-    const data = { type, geom } as { [K in GeometryType]: { type: K, geom: GeometryTypeMap[K] } }[GeometryType];
+    const data = { type, geom } as { [K in GeoJSONVTInternalFeature["type"]]: { type: K, geom: FeatureTypeMap[K] } }[GeoJSONVTInternalFeature["type"]];
 
     const feature = {
         id: id == null ? null : id,

package/src/geojson-to-tile.ts

@@ -0,0 +1,58 @@
+import {AxisType, clip} from './clip';
+import {convertToInternal} from './convert';
+import {defaultOptions} from './geojsonvt';
+import {createTile} from './tile';
+import {transformTile} from './transform';
+import {wrap} from './wrap';
+import type {GeoJSONToTileOptions, GeoJSONVTTile} from './definitions';
+
+/**
+ * Converts GeoJSON data directly to a single vector tile without building a tile index.
+ *
+ * Unlike the {@link GeoJSONVT} class which builds a hierarchical tile index for efficient
+ * repeated tile access, this function generates a single tile on-demand. This is useful when:
+ * - You only need one specific tile and don't need to query multiple tiles
+ * - The source data is already spatially filtered to the tile's bounding box
+ * - You want to avoid the overhead of building a full tile index
+ *
+ * @example
+ * ```ts
+ * import {geoJSONToTile} from '@maplibre/geojson-vt';
+ *
+ * const geojson = {
+ *   type: 'FeatureCollection',
+ *   features: [{
+ *     type: 'Feature',
+ *     geometry: { type: 'Point', coordinates: [-77.03, 38.90] },
+ *     properties: { name: 'Washington, D.C.' }
+ *   }]
+ * };
+ *
+ * const tile = geoJSONToTile(geojson, 10, 292, 391, { extent: 4096 });
+ * ```
+ *
+ * @param data - GeoJSON data (Feature, FeatureCollection, or Geometry)
+ * @param z - Tile zoom level
+ * @param x - Tile x coordinate
+ * @param y - Tile y coordinate
+ * @param options - Optional configuration for tile generation
+ * @returns The generated tile with geometries in tile coordinates, or null if no features
+ */
+
+export function geoJSONToTile(data: GeoJSON.GeoJSON, z: number, x: number, y: number, options: GeoJSONToTileOptions = {}): GeoJSONVTTile {
+    options = {...defaultOptions, ...options};
+    const {wrap: shouldWrap = false, clip: shouldClip = false} = options;
+
+    let features = convertToInternal(data, options);
+    if (shouldWrap) {
+        features = wrap(features, options);
+    }
+    if (shouldClip || options.lineMetrics) {
+        const pow2 = 1 << z;
+        const buffer = options.buffer / options.extent;
+        const left = clip(features, pow2, (x - buffer), (x + 1 + buffer), AxisType.X, -1, 2, options);
+        features = clip(left || [], pow2, (y - buffer), (y + 1 + buffer), AxisType.Y, -1, 2, options);
+    }
+
+    return transformTile(createTile(features ?? [], z, x, y, options), options.extent);
+}

package/src/geojsonvt.test.ts

@@ -0,0 +1,39 @@
+import {test, expect} from 'vitest';
+import {GeoJSONVT} from '.';
+
+test('publicly exposed cluster methods: getClusterExpansionZoom, getClusterChildren, getClusterLeaves', () => {
+    const points = {
+        type: 'FeatureCollection' as const,
+        features: Array.from({length: 20}, (_, i) => ({
+            type: 'Feature' as const,
+            geometry: {type: 'Point' as const, coordinates: [i * 0.0001, i * 0.0001]},
+            properties: {name: `Point ${i}`}
+        }))
+    };
+
+    const index = new GeoJSONVT(points, {
+        updateable: true,
+        cluster: true,
+        clusterOptions: {radius: 100}
+    });
+
+    const tile = index.getTile(0, 0, 0);
+    const cluster = tile.features.find(f => (f.tags as {cluster?: boolean})?.cluster);
+    const clusterId = (cluster.tags as {cluster_id: number}).cluster_id;
+
+    expect(index.getClusterExpansionZoom(clusterId)).toBeGreaterThan(0);
+    expect(index.getClusterChildren(clusterId).length).toBeGreaterThan(0);
+    expect(index.getClusterLeaves(clusterId, 5, 0).length).toBeLessThanOrEqual(5);
+});
+
+test('publicly exposed cluster methods: return undefined when clustering is disabled', () => {
+    const index = new GeoJSONVT({type: 'FeatureCollection', features: []}, {
+        updateable: true,
+        cluster: false,
+        clusterOptions: {radius: 100}
+    });
+
+    expect(index.getClusterExpansionZoom(123)).toBeNull();
+    expect(index.getClusterChildren(123)).toBeNull();
+    expect(index.getClusterLeaves(123, 10, 0)).toBeNull();
+});

package/src/geojsonvt.ts

@@ -0,0 +1,209 @@
+import {convertToInternal} from './convert';
+import {convertToGeoJSON, featureToGeoJSON} from './deconvert';
+import {wrap} from './wrap';
+import {applySourceDiff, type GeoJSONVTSourceDiff} from './difference';
+import {ClusterTileIndex, defaultClusterOptions} from './cluster-tile-index';
+import {TileIndex} from './tile-index';
+import type {ClusterOrPointFeature, GeoJSONVTTileIndex, GeoJSONVTInternalFeature, GeoJSONVTOptions, GeoJSONVTTile, SuperclusterOptions} from './definitions';
+
+export const defaultOptions: GeoJSONVTOptions = {
+    maxZoom: 14,
+    indexMaxZoom: 5,
+    indexMaxPoints: 100000,
+    tolerance: 3,
+    extent: 4096,
+    buffer: 64,
+    lineMetrics: false,
+    promoteId: null,
+    generateId: false,
+    updateable: false,
+    cluster: false,
+    clusterOptions: defaultClusterOptions,
+    debug: 0
+};
+
+/**
+ * Main class for creating and managing a vector tile index from GeoJSON data.
+ */
+export class GeoJSONVT {
+
+    /** 
+     * @internal
+     * This is for the tests
+     */
+    public get tiles() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (this.tileIndex as any)?.tiles ?? {};
+    }
+    /** 
+     * @internal
+     * This is for the tests
+     */
+    public get stats() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (this.tileIndex as any).stats;
+    }
+     /** 
+     * @internal
+     * This is for the tests
+     */
+    public get total() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (this.tileIndex as any).total;
+    }
+
+    private options: GeoJSONVTOptions;
+    
+    private source?: GeoJSONVTInternalFeature[];
+    private tileIndex: GeoJSONVTTileIndex;
+
+    constructor(data: GeoJSON.GeoJSON, options?: GeoJSONVTOptions) {
+        options = this.options = Object.assign({}, defaultOptions, options);
+
+        const debug = options.debug;
+
+        if (debug) console.time('preprocess data');
+
+        if (options.maxZoom < 0 || options.maxZoom > 24) throw new Error('maxZoom should be in the 0-24 range');
+        if (options.promoteId && options.generateId) throw new Error('promoteId and generateId cannot be used together.');
+
+        // projects and adds simplification info
+        let features = convertToInternal(data, options);
+
+        if (debug) {
+            console.timeEnd('preprocess data');
+            console.log('index: maxZoom: %d, maxPoints: %d', options.indexMaxZoom, options.indexMaxPoints);
+            console.time('generate tiles');
+        }
+
+        // wraps features (ie extreme west and extreme east)
+        features = wrap(features, options);
+
+        // for updateable indexes, store a copy of the original simplified features
+        if (options.updateable) {
+            this.source = features;
+        }
+
+        this.initializeIndex(features, options);
+    }
+
+    private initializeIndex(features: GeoJSONVTInternalFeature[], options: GeoJSONVTOptions) {
+        this.tileIndex = options.cluster ? new ClusterTileIndex(options.clusterOptions) : new TileIndex(options);
+        if (!features.length) return;
+        this.tileIndex.initialize(features);
+    }
+
+    /**
+     * Given z, x, and y tile coordinates, returns the corresponding tile with geometries in tile coordinates, much like MVT data is stored.
+     * @param z - tile zoom level
+     * @param x - tile x coordinate
+     * @param y - tile y coordinate
+     * @returns the transformed tile or null if not found
+     */
+    getTile(z: number | string, x: number | string, y: number | string): GeoJSONVTTile | null {
+        z = +z;
+        x = +x;
+        y = +y;
+
+        if (z < 0 || z > 24) return null;
+
+        return this.tileIndex.getTile(z, x, y);
+    }
+
+    /**
+     * Updates the source data feature set using a {@link GeoJSONVTSourceDiff}
+     * @param diff - the source diff object
+     */
+    updateData(diff: GeoJSONVTSourceDiff, filter?: (feature: GeoJSON.Feature) => boolean) {
+        const options = this.options;
+
+        if (!options.updateable) throw new Error('to update tile geojson `updateable` option must be set to true');
+
+        // apply diff and collect affected features and updated source that will be used to invalidate tiles
+        let {affected, source} = applySourceDiff(this.source, diff, options);
+
+        if (filter) {
+            ({affected, source} = this.filterUpdate(source, affected, filter));
+        }
+
+        // nothing has changed
+        if (!affected.length) return;
+
+        // update source with new simplified feature set
+        this.source = source;
+
+        this.tileIndex.updateIndex(source, affected, options);
+    }
+
+    /**
+     * Filter an update using a predicate function. Returns the affected and updated source features.
+     */
+    private filterUpdate(source: GeoJSONVTInternalFeature[], affected: GeoJSONVTInternalFeature[], predicate: (feature: GeoJSON.Feature) => boolean) {
+        const removeIds = new Set();
+
+        for (const feature of source) {
+            if (feature.id == undefined) continue;
+            if (predicate(featureToGeoJSON(feature))) continue;
+            affected.push(feature);
+            removeIds.add(feature.id);
+        }
+        source = source.filter(feature => !removeIds.has(feature.id));
+
+        return {affected, source};
+    }
+
+    /**
+     * Returns source data as GeoJSON - only available when `updateable` option is set to true.
+     */
+    getData(): GeoJSON.GeoJSON {
+        if (!this.options.updateable) throw new Error('to retrieve data the `updateable` option must be set to true');
+        return convertToGeoJSON(this.source);
+    }
+    
+    /**
+     * Update supercluster options and regenerate the index.
+     * @param cluster - whether to enable clustering
+     * @param clusterOptions - {@link SuperclusterOptions}
+     */
+    updateClusterOptions(cluster: boolean, clusterOptions: SuperclusterOptions) {
+        const wasCluster = this.options.cluster;
+        this.options.cluster = cluster;
+        this.options.clusterOptions = clusterOptions;
+
+        if (wasCluster == cluster) {
+            this.tileIndex.updateIndex(this.source, [], this.options);
+            return;    
+        }
+
+        this.initializeIndex(this.source, this.options);
+    }
+
+    /**
+     * Returns the zoom level at which a cluster expands into multiple children.
+     * @param clusterId - The target cluster id.
+     * @returns the expansion zoom or null in case of non-clustered source
+     */
+    getClusterExpansionZoom(clusterId: number): number | null {
+        return this.tileIndex.getClusterExpansionZoom(clusterId);
+    }
+
+    /**
+     * Returns the immediate children (clusters or points) of a cluster as GeoJSON.
+     * @param clusterId - The target cluster id.
+     * @returns the immediate children or null in case of non-clustered source
+     */
+    getClusterChildren(clusterId: number): ClusterOrPointFeature[] | null {
+        return this.tileIndex.getChildren(clusterId);
+    }
+
+    /**
+     * Returns leaf point features under a cluster, paginated by `limit` and `offset`.
+     * @param clusterId - The target cluster id.
+     * @param limit - Maximum number of points to return (defaults to `10`).
+     * @param offset - Number of points to skip before collecting results (defaults to `0`).
+     * @returns leaf point features under a cluster or null in case of non-clustered source
+     */
+    getClusterLeaves(clusterId: number, limit: number, offset: number): GeoJSON.Feature<GeoJSON.Point>[] | null {
+        return this.tileIndex.getLeaves(clusterId, limit, offset);
+    }
+}