@maplibre/geojson-vt 5.0.0 → 5.0.2

package/src/convert.ts

@@ -0,0 +1,178 @@
+
+import {simplify} from './simplify';
+import {createFeature} from './feature';
+import type { GeoJSONVTFeature, GeoJSONVTOptions, StartEndSizeArray } from './definitions';
+
+/**
+ * converts GeoJSON feature into an intermediate projected JSON vector format with simplification data
+ * @param data
+ * @param options
+ * @returns
+ */
+export function convert(data: GeoJSON.GeoJSON, options: GeoJSONVTOptions): GeoJSONVTFeature[] {
+    const features: GeoJSONVTFeature[] = [];
+
+    switch (data.type) {
+        case 'FeatureCollection':
+            for (let i = 0; i < data.features.length; i++) {
+                convertFeature(features, data.features[i], options, i);
+            }
+            break;
+        case 'Feature':
+            convertFeature(features, data, options);
+            break;
+        default:
+            convertFeature(features, {type: "Feature" as const, geometry: data, properties: undefined}, options);
+    }
+
+    return features;
+}
+
+function convertFeature(features: GeoJSONVTFeature[], geojson: GeoJSON.Feature, options: GeoJSONVTOptions, index?: number) {
+    if (!geojson.geometry) return;
+
+    if (geojson.geometry.type === 'GeometryCollection') {
+        for (const singleGeometry of geojson.geometry.geometries) {
+            convertFeature(features, {
+                id: geojson.id,
+                type: 'Feature',
+                geometry: singleGeometry,
+                properties: geojson.properties
+            }, options, index);
+        }
+        return;
+    }
+
+    const coords = geojson.geometry.coordinates;
+    if (!coords?.length) return;
+
+    const tolerance = Math.pow(options.tolerance / ((1 << options.maxZoom) * options.extent), 2);
+    let id = geojson.id;
+    if (options.promoteId) {
+        id = geojson.properties?.[options.promoteId];
+    } else if (options.generateId) {
+        id = index || 0;
+    }
+
+    switch (geojson.geometry.type) {
+        case 'Point': {
+            const pointGeometry: StartEndSizeArray = [];
+            convertPoint(geojson.geometry.coordinates, pointGeometry);
+
+            features.push(createFeature(id, geojson.geometry.type, pointGeometry, geojson.properties));
+            return;
+        }
+
+        case 'MultiPoint': {
+            const multiPointGeometry: StartEndSizeArray = [];
+            for (const p of geojson.geometry.coordinates) {
+                convertPoint(p, multiPointGeometry);
+            }
+
+            features.push(createFeature(id, geojson.geometry.type, multiPointGeometry, geojson.properties));
+            return;
+        }
+
+        case 'LineString': {
+            const lineGeometry: StartEndSizeArray = [];
+            convertLine(geojson.geometry.coordinates, lineGeometry, tolerance, false);
+
+            features.push(createFeature(id, geojson.geometry.type, lineGeometry, geojson.properties));
+            return;
+        }
+
+        case 'MultiLineString': {
+            if (options.lineMetrics) {
+                // explode into linestrings in order to track metrics
+                for (const line of geojson.geometry.coordinates) {
+                    const lineGeometry: StartEndSizeArray = [];
+                    convertLine(line, lineGeometry, tolerance, false);
+                    features.push(createFeature(id, 'LineString', lineGeometry, geojson.properties));
+                }
+                return;
+            }
+
+            const multiLineGeometry: StartEndSizeArray[] = [];
+            convertLines(geojson.geometry.coordinates, multiLineGeometry, tolerance, false);
+
+            features.push(createFeature(id, geojson.geometry.type, multiLineGeometry, geojson.properties));
+            return;
+        }
+
+        case 'Polygon': {
+            const polygonGeometry: StartEndSizeArray[] = [];
+            convertLines(geojson.geometry.coordinates, polygonGeometry, tolerance, true);
+
+            features.push(createFeature(id, geojson.geometry.type, polygonGeometry, geojson.properties));
+            return;
+        }
+
+        case 'MultiPolygon': {
+            const multiPolygonGeometry: StartEndSizeArray[][] = [];
+            for (const polygon of geojson.geometry.coordinates) {
+                const newPolygon: StartEndSizeArray[] = [];
+                convertLines(polygon, newPolygon, tolerance, true);
+                multiPolygonGeometry.push(newPolygon);
+            }
+
+            features.push(createFeature(id, geojson.geometry.type, multiPolygonGeometry, geojson.properties));
+            return;
+        }
+
+        default:
+            throw new Error('Input data is not a valid GeoJSON object.');
+    }
+}
+
+function convertPoint(coords: GeoJSON.Position, out: number[]) {
+    out.push(projectX(coords[0]), projectY(coords[1]), 0);
+}
+
+function convertLine(ring: GeoJSON.Position[], out: StartEndSizeArray, tolerance: number, isPolygon: boolean) {
+    let x0, y0;
+    let size = 0;
+
+    for (let j = 0; j < ring.length; j++) {
+        const x = projectX(ring[j][0]);
+        const y = projectY(ring[j][1]);
+
+        out.push(x, y, 0);
+
+        if (j > 0) {
+            if (isPolygon) {
+                size += (x0 * y - x * y0) / 2; // area
+            } else {
+                size += Math.sqrt(Math.pow(x - x0, 2) + Math.pow(y - y0, 2)); // length
+            }
+        }
+        x0 = x;
+        y0 = y;
+    }
+
+    const last = out.length - 3;
+    out[2] = 1;
+    if (tolerance > 0) simplify(out, 0, last, tolerance);
+    out[last + 2] = 1;
+
+    out.size = Math.abs(size);
+    out.start = 0;
+    out.end = out.size;
+}
+
+function convertLines(rings: GeoJSON.Position[][], out: StartEndSizeArray[], tolerance: number, isPolygon: boolean) {
+    for (let i = 0; i < rings.length; i++) {
+        const geom: StartEndSizeArray = [];
+        convertLine(rings[i], geom, tolerance, isPolygon);
+        out.push(geom);
+    }
+}
+
+function projectX(x: number) {
+    return x / 360 + 0.5;
+}
+
+function projectY(y: number) {
+    const sin = Math.sin(y * Math.PI / 180);
+    const y2 = 0.5 - 0.25 * Math.log((1 + sin) / (1 - sin)) / Math.PI;
+    return y2 < 0 ? 0 : y2 > 1 ? 1 : y2;
+}

package/src/definitions.ts

@@ -0,0 +1,86 @@
+export type GeoJSONVTOptions = {
+    /**
+     * Max zoom to preserve detail on
+     * @default 14
+     */
+    maxZoom?: number;
+    /**
+     * Max zoom in the tile index
+     * @default 5
+     */
+    indexMaxZoom?: number;
+    /**
+     * Max number of points per tile in the tile index
+     * @default 100000
+     */
+    indexMaxPoints?: number;
+    /**
+     * Simplification tolerance (higher means simpler)
+     * @default 3
+     */
+    tolerance?: number;
+    /**
+     * Tile extent
+     * @default 4096
+     */
+    extent?: number;
+    /**
+     * Tile buffer on each side
+     * @default 64
+     */
+    buffer?: number;
+    /**
+     * Whether to calculate line metrics
+     * @default false
+     */
+    lineMetrics?: boolean;
+    /**
+     * Name of a feature property to be promoted to feature.id
+     */
+    promoteId?: string | null;
+    /**
+     * Whether to generate feature ids. Cannot be used with promoteId
+     * @default false
+     */
+    generateId?: boolean;
+    /**
+     * Whether geojson can be updated (with caveat of a stored simplified copy)
+     * @default false
+     */
+    updateable?: boolean;
+    /**
+     * Logging level (0, 1 or 2)
+     * @default 0
+     */
+    debug?: number;
+};
+
+
+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;
+}
+
+export type GeometryTypeMap = {
+    Point: number[];
+    MultiPoint: number[];
+    LineString: StartEndSizeArray;
+    MultiLineString: StartEndSizeArray[];
+    Polygon: StartEndSizeArray[];
+    MultiPolygon: StartEndSizeArray[][];
+}
+
+export type GeometryType = "Point" | "MultiPoint" | "LineString" | "MultiLineString" | "Polygon" | "MultiPolygon";
+
+export type GeoJSONVTFeature = {
+    [K in GeometryType]: PartialGeoJSONVTFeature & {
+        type: K;
+        geometry: GeometryTypeMap[K];
+    }
+}[GeometryType];

package/src/difference.test.ts

@@ -0,0 +1,270 @@
+import {test, expect} from 'vitest';
+import {applySourceDiff} from './difference';
+
+const options = {
+    maxZoom: 14,
+    indexMaxZoom: 5,
+    indexMaxPoints: 100000,
+    tolerance: 3,
+    extent: 4096,
+    buffer: 64,
+    updateable: true
+};
+
+test('applySourceDiff: adds a feature using the feature id', () => {
+    const point = {
+        type: 'Feature' as const,
+        id: 'point',
+        geometry: {
+            type: 'Point' as const,
+            coordinates: [0, 0]
+        },
+        properties: {},
+    };
+
+    const {source} = applySourceDiff([], {
+        add: [point]
+    }, options);
+
+    expect(source.length).toBe(1);
+    expect(source[0].id).toBe('point');
+});
+
+test('applySourceDiff: adds a feature using the promoteId', () => {
+    const point2 = {
+        type: 'Feature' as const,
+        geometry: {
+            type: 'Point' as const,
+            coordinates: [0, 0],
+        },
+        properties: {
+            promoteId: 'point2'
+        },
+    };
+
+    const {source} = applySourceDiff([], {
+        add: [point2]
+    }, {promoteId: 'promoteId'});
+
+    expect(source.length).toBe(1);
+    expect(source[0].id).toBe('point2');
+});
+
+test('applySourceDiff: removes a feature by its id', () => {
+    const point = {
+        type: 'Point' as const,
+        id: 'point',
+        geometry: [0, 0],
+        tags: {},
+        minX: 0,
+        minY: 0,
+        maxX: 0,
+        maxY: 0
+    };
+
+    const point2 = {
+        type: 'Point' as const,
+        id: 'point2',
+        geometry: [0, 0],
+        tags: {},
+        minX: 0,
+        minY: 0,
+        maxX: 0,
+        maxY: 0
+    };
+
+    const {source} = applySourceDiff([point, point2], {
+        remove: ['point2'],
+    }, options);
+
+    expect(source.length).toBe(1);
+    expect(source[0].id).toBe('point');
+});
+
+test('applySourceDiff: removeAll clears all features', () => {
+    const point = {
+        type: 'Point' as const,
+        id: 'point',
+        geometry: [0, 0],
+        tags: {},
+        minX: 0,
+        minY: 0,
+        maxX: 0,
+        maxY: 0
+    };
+
+    const point2 = {
+        type: 'Point' as const,
+        id: 'point2',
+        geometry: [0, 0],
+        tags: {},
+        minX: 0,
+        minY: 0,
+        maxX: 0,
+        maxY: 0
+    };
+
+    const source = [point, point2];
+    const result = applySourceDiff(source, {
+        removeAll: true
+    }, options);
+
+    expect(source).toEqual(result.affected);
+    expect(result.source).toEqual([]);
+});
+
+test('applySourceDiff: updates a feature geometry', () => {
+    const point = {
+        type: 'Point' as const,
+        id: 'point',
+        geometry: [0, 0],
+        tags: {},
+        minX: 0,
+        minY: 0,
+        maxX: 0,
+        maxY: 0
+    };
+
+    const {source} = applySourceDiff([point], {
+        update: [{
+            id: 'point',
+            newGeometry: {
+                type: 'Point',
+                coordinates: [1, 0]
+            }
+        }]
+    }, options);
+
+    expect(source.length).toBe(1);
+    expect(source[0].id).toBe('point');
+    expect(source[0].geometry[0]).toBe(0.5027777777777778);
+    expect(source[0].geometry[1]).toBe(0.5);
+});
+
+test('applySourceDiff: adds properties', () => {
+    const point = {
+        type: 'Point' as const,
+        id: 'point',
+        geometry: [0, 0],
+        tags: {},
+        minX: 0,
+        minY: 0,
+        maxX: 0,
+        maxY: 0
+    };
+
+    const {source} = applySourceDiff([point], {
+        update: [{
+            id: 'point',
+            addOrUpdateProperties: [
+                {key: 'prop', value: 'value'},
+                {key: 'prop2', value: 'value2'}
+            ]
+        }]
+    }, options);
+
+    expect(source.length).toBe(1);
+    const tags = source[0].tags;
+    expect(Object.keys(tags).length).toBe(2);
+    expect(tags.prop).toBe('value');
+    expect(tags.prop2).toBe('value2');
+});
+
+test('applySourceDiff: updates properties', () => {
+    const point = {
+        type: 'Point' as const,
+        id: 'point',
+        geometry: [0, 0],
+        tags: {prop: 'value', prop2: 'value2'},
+        minX: 0,
+        minY: 0,
+        maxX: 0,
+        maxY: 0
+    };
+
+    const {source} = applySourceDiff([point], {
+        update: [{
+            id: 'point',
+            addOrUpdateProperties: [
+                {key: 'prop2', value: 'value3'}
+            ]
+        }]
+    }, options);
+    expect(source.length).toBe(1);
+
+    const tags2 = source[0].tags;
+    expect(Object.keys(tags2).length).toBe(2);
+    expect(tags2.prop).toBe('value');
+    expect(tags2.prop2).toBe('value3');
+});
+
+test('applySourceDiff: removes properties', () => {
+    const point = {
+        type: 'Point' as const,
+        id: 'point',
+        geometry: [0, 0],
+        tags: {prop: 'value', prop2: 'value2'},
+        minX: 0,
+        minY: 0,
+        maxX: 0,
+        maxY: 0
+    };
+
+    const {source} = applySourceDiff([point], {
+        update: [{
+            id: 'point',
+            removeProperties: ['prop2']
+        }]
+    }, options);
+
+    expect(source.length).toBe(1);
+    const tags3 = source[0].tags;
+    expect(Object.keys(tags3).length).toBe(1);
+    expect(tags3.prop).toBe('value');
+});
+
+test('applySourceDiff: removes all properties', () => {
+    const point = {
+        type: 'Point' as const,
+        id: 'point',
+        geometry: [0, 0],
+        tags: {prop: 'value', prop2: 'value2'},
+        minX: 0,
+        minY: 0,
+        maxX: 0,
+        maxY: 0
+    };
+
+    const {source} = applySourceDiff([point], {
+        update: [{
+            id: 'point',
+            removeAllProperties: true,
+        }]
+    }, options);
+
+    expect(source.length).toBe(1);
+    expect(Object.keys(source[0].tags).length).toBe(0);
+});
+
+test('applySourceDiff: empty update preserves properties', () => {
+    const point = {
+        type: 'Point' as const,
+        id: 'point',
+        geometry: [0, 0],
+        tags: {prop: 'value', prop2: 'value2'},
+        minX: 0,
+        minY: 0,
+        maxX: 0,
+        maxY: 0
+    };
+
+    const {source} = applySourceDiff([point], {
+        update: [{id: 'point'}]
+    }, options);
+
+    expect(source.length).toBe(1);
+    const tags2 = source[0].tags;
+    expect(Object.keys(tags2).length).toBe(2);
+    expect(tags2.prop).toBe('value');
+    expect(tags2.prop2).toBe('value2');
+});

package/src/{difference.js → difference.ts}

@@ -1,40 +1,73 @@
-import convert from './convert.js'; // GeoJSON conversion and preprocessing
-import wrap from './wrap.js';       // date line processing
-
-// This file provides a set of helper functions for managing "diffs" (changes)
-// to GeoJSON data structures. These diffs describe additions, removals,
-// and updates of features in a GeoJSON source in an efficient way.
-
-// GeoJSON Source Diff:
-// {
-//   removeAll: true,                    // If true, clear all existing features
-//   remove: [featureId, ...],           // Array of feature IDs to remove
-//   add: [feature, ...],                // Array of GeoJSON features to add
-//   update: [GeoJSON Feature Diff, ...]   // Array of per-feature updates
-// }
-
-// GeoJSON Feature Diff:
-// {
-//   id: featureId,                       // ID of the feature being updated
-//   newGeometry: GeoJSON.Geometry,      // Optional new geometry
-//   removeAllProperties: true,          // Remove all properties if true
-//   removeProperties: [key, ...],       // Specific properties to delete
-//   addOrUpdateProperties: [            // Properties to add or update
-//     { key: "name", value: "New name" }
-//   ]
-// }
-
-/* eslint @stylistic/comma-spacing: 0, no-shadow: 0 */
-
-// applies a diff to the geojsonvt source simplified features array
-// returns an object with the affected features and new source array for invalidation
-export function applySourceDiff(source, dataDiff, options) {
+import {convert} from './convert';
+import {wrap} from './wrap';
+import type { GeoJSONVTFeature, GeoJSONVTOptions } from './definitions';
+
+export type GeoJSONVTSourceDiff = {
+    /**
+     * If true, clear all existing features
+     */
+    removeAll?: boolean;
+    /**
+     * Array of feature IDs to remove
+     */
+    remove?: (string | number)[];
+    /**
+     * Array of GeoJSON features to add
+     */
+    add?: GeoJSON.Feature[];
+    /**
+     * Array of per-feature updates
+     */
+    update?: GeoJSONVTFeatureDiff[];
+};
+
+export type GeoJSONVTFeatureDiff = {
+    /**
+     * ID of the feature being updated
+     */
+    id: string | number;
+    /**
+     * Optional new geometry
+     */
+    newGeometry?: GeoJSON.Geometry;
+    /**
+     * Remove all properties if true
+     */
+    removeAllProperties?: boolean;
+    /**
+     * Specific properties to delete
+     */
+    removeProperties?: string[];
+    /**
+     * Properties to add or update
+     */
+    addOrUpdateProperties?: {
+        key: string;
+        value: unknown;
+    }[];
+};
+
+type HashedGeoJSONVTSourceDiff = {
+    removeAll?: boolean | undefined;
+    remove: Set<string | number>;
+    add: Map<string | number | undefined, GeoJSON.Feature>;
+    update: Map<string | number, GeoJSONVTFeatureDiff>;
+};
+
+/**
+ * Applies a GeoJSON Source Diff to an existing set of simplified features
+ * @param source 
+ * @param dataDiff 
+ * @param options 
+ * @returns 
+ */
+export function applySourceDiff(source: GeoJSONVTFeature[], dataDiff: GeoJSONVTSourceDiff, options: GeoJSONVTOptions) {
 
     // convert diff to sets/maps for o(1) lookups
     const diff = diffToHashed(dataDiff);
 
     // collection for features that will be affected by this update
-    let affected = [];
+    let affected: GeoJSONVTFeature[] = [];
 
     // full removal - clear everything before applying diff
     if (diff.removeAll) {
@@ -103,7 +136,7 @@ export function applySourceDiff(source, dataDiff, options) {
 }
 
 // return an updated geojsonvt simplified feature
-function getUpdatedFeature(vtFeature, update, options) {
+function getUpdatedFeature(vtFeature: GeoJSONVTFeature, update: GeoJSONVTFeatureDiff, options: GeoJSONVTOptions): GeoJSONVTFeature | null {
     const changeGeometry = !!update.newGeometry;
 
     const changeProps =
@@ -111,13 +144,10 @@ function getUpdatedFeature(vtFeature, update, options) {
         update.removeProperties?.length > 0 ||
         update.addOrUpdateProperties?.length > 0;
 
-    // nothing to do
-    if (!changeGeometry && !changeProps) return null;
-
     // if geometry changed, need to create new geojson feature and convert to simplified format
     if (changeGeometry) {
         const geojsonFeature = {
-            type: 'Feature',
+            type: 'Feature' as const,
             id: vtFeature.id,
             geometry: update.newGeometry,
             properties: changeProps ? applyPropertyUpdates(vtFeature.tags, update) : vtFeature.tags
@@ -142,8 +172,10 @@ function getUpdatedFeature(vtFeature, update, options) {
     return null;
 }
 
-// helper to apply property updates from a diff update object to a properties object
-function applyPropertyUpdates(tags, update) {
+/**
+ * helper to apply property updates from a diff update object to a properties object
+ */
+function applyPropertyUpdates(tags: GeoJSON.GeoJsonProperties, update: GeoJSONVTFeatureDiff): GeoJSON.GeoJsonProperties {
     if (update.removeAllProperties) {
         return {};
     }
@@ -165,16 +197,22 @@ function applyPropertyUpdates(tags, update) {
     return properties;
 }
 
-// Convert a GeoJSON Source Diff to an idempotent hashed representation using Sets and Maps
-export function diffToHashed(diff) {
-    if (!diff) return {};
-
-    const hashed = {};
-
-    hashed.removeAll = diff.removeAll;
-    hashed.remove = new Set(diff.remove || []);
-    hashed.add    = new Map(diff.add?.map(feature => [feature.id, feature]));
-    hashed.update = new Map(diff.update?.map(update => [update.id, update]));
+/**
+ * Convert a GeoJSON Source Diff to an idempotent hashed representation using Sets and Maps
+ */
+export function diffToHashed(diff: GeoJSONVTSourceDiff): HashedGeoJSONVTSourceDiff {
+    if (!diff) return {
+        remove: new Set(),
+        add: new Map(),
+        update: new Map()
+    };
+
+    const hashed: HashedGeoJSONVTSourceDiff = {
+        removeAll: diff.removeAll,
+        remove: new Set(diff.remove || []),
+        add: new Map(diff.add?.map(feature => [feature.id, feature])),
+        update: new Map(diff.update?.map(update => [update.id, update]))
+    };
 
     return hashed;
 }