@maplibre/geojson-vt 6.2.0 → 6.3.0

package/src/deconvert.ts

@@ -1,12 +1,13 @@
+import {mercatorWorldCoordinateHelper, type WorldCoordinateHelper} from './world-coordinate-helper';
 import type {GeoJSONVTInternalFeature} from './definitions';
 
 /**
  * Converts internal source features back to GeoJSON format.
  */
-export function convertToGeoJSON(source: GeoJSONVTInternalFeature[], worldCoordinates = false): GeoJSON.GeoJSON {
+export function convertToGeoJSON(source: GeoJSONVTInternalFeature[], worldCoordinateHelper: WorldCoordinateHelper = mercatorWorldCoordinateHelper): GeoJSON.GeoJSON {
     const geojson: GeoJSON.GeoJSON = {
         type: 'FeatureCollection',
-        features: source.map(feature => featureToGeoJSON(feature, worldCoordinates))
+        features: source.map(feature => featureToGeoJSON(feature, worldCoordinateHelper))
     };
 
     return geojson;
@@ -15,10 +16,10 @@ export function convertToGeoJSON(source: GeoJSONVTInternalFeature[], worldCoordi
 /**
  * Converts a single internal feature to GeoJSON format.
  */
-export function featureToGeoJSON(feature: GeoJSONVTInternalFeature, worldCoordinates = false): GeoJSON.Feature {
+export function featureToGeoJSON(feature: GeoJSONVTInternalFeature, worldCoordinateHelper: WorldCoordinateHelper = mercatorWorldCoordinateHelper): GeoJSON.Feature {
     const geojsonFeature: GeoJSON.Feature = {
         type: 'Feature',
-        geometry: geometryToGeoJSON(feature, worldCoordinates),
+        geometry: geometryToGeoJSON(feature, worldCoordinateHelper),
         properties: feature.tags
     };
     if (feature.id != null) {
@@ -31,68 +32,51 @@ export function featureToGeoJSON(feature: GeoJSONVTInternalFeature, worldCoordin
 /**
  * Converts a single internal feature geometry to GeoJSON format.
  */
-function geometryToGeoJSON(feature: GeoJSONVTInternalFeature, worldCoordinates: boolean): GeoJSON.Geometry {
+function geometryToGeoJSON(feature: GeoJSONVTInternalFeature, worldCoordinateHelper: WorldCoordinateHelper): GeoJSON.Geometry {
     const {type, geometry} = feature;
 
     switch (type) {
         case 'Point':
             return {
                 type: type,
-                coordinates: unprojectPoint(geometry[0], geometry[1], worldCoordinates)
+                coordinates: unprojectPoint(geometry[0], geometry[1], worldCoordinateHelper)
             };
         case 'MultiPoint':
             return {
                 type: type,
-                coordinates: unprojectPoints(geometry, worldCoordinates)
+                coordinates: unprojectPoints(geometry, worldCoordinateHelper)
             };
         case 'LineString':
             return {
                 type: type,
-                coordinates: unprojectPoints(geometry.points, worldCoordinates)
+                coordinates: unprojectPoints(geometry.points, worldCoordinateHelper)
             };
         case 'MultiLineString':
         case 'Polygon':
             return {
                 type: type,
-                coordinates: geometry.map(ring => unprojectPoints(ring.points, worldCoordinates))
+                coordinates: geometry.map(ring => unprojectPoints(ring.points, worldCoordinateHelper))
             };
         case 'MultiPolygon':
             return {
                 type: type,
                 coordinates: geometry.map(polygon =>
-                    polygon.map(ring => unprojectPoints(ring.points, worldCoordinates))
+                    polygon.map(ring => unprojectPoints(ring.points, worldCoordinateHelper))
                 )
             };
     }
 }
 
-export function unprojectPoints(coords: number[] | Float64Array, worldCoordinates = false): GeoJSON.Position[] {
+export function unprojectPoints(coords: number[] | Float64Array, worldCoordinateHelper: WorldCoordinateHelper = mercatorWorldCoordinateHelper): GeoJSON.Position[] {
     const result: GeoJSON.Position[] = [];
 
     for (let i = 0; i < coords.length; i += 3) {
-        result.push(unprojectPoint(coords[i], coords[i + 1], worldCoordinates));
+        result.push(unprojectPoint(coords[i], coords[i + 1], worldCoordinateHelper));
     }
 
     return result;
 }
 
-function unprojectPoint(x: number, y: number, worldCoordinates: boolean): GeoJSON.Position {
-    return [unprojectX(x, worldCoordinates), unprojectY(y, worldCoordinates)];
-}
-
-/**
- * Convert spherical mercator in [0..1] range to longitude, or keep a world coordinate as it is
- */
-export function unprojectX(x: number, worldCoordinates = false): number {
-    if (worldCoordinates) return x;
-    return (x - 0.5) * 360;
-}
-
-/**
- * Convert spherical mercator in [0..1] range to latitude, or keep a world coordinate as it is
- */
-export function unprojectY(y: number, worldCoordinates = false): number {
-    if (worldCoordinates) return y;
-    const y2 = (180 - y * 360) * Math.PI / 180;
-    return 360 * Math.atan(Math.exp(y2)) / Math.PI - 90;
+function unprojectPoint(x: number, y: number, worldCoordinateHelper: WorldCoordinateHelper): GeoJSON.Position {
+    return [worldCoordinateHelper.unprojectX(x), worldCoordinateHelper.unprojectY(y)];
 }

package/src/definitions.ts

@@ -1,3 +1,9 @@
+/**
+ * The space positions are given in, see `coordinates` in {@link GeoJSONVTOptions}.
+ * @experimental
+ */
+export type GeoJSONVTCoordinatesType = 'lngLat' | 'unitSquare';
+
 export type GeoJSONVTOptions = {
     /**
      * Max zoom to preserve detail on
@@ -54,15 +60,23 @@ export type GeoJSONVTOptions = {
      */
     debug?: number;
     /**
-     * Whether positions are world coordinates instead of lng/lat: x and y from 0 to 1 across the world square, y growing
-     * downward, where web mercator would put a lng/lat. The world is then a square that ends at its edges, for data in a
-     * world of its own such as a map projection's: positions are neither projected nor wrapped around or clamped,
-     * features are cut at the tile buffer around the square, points outside it are left out of the clusters, `getTile`
-     * returns `null` outside it, and `getData` and the cluster methods return world coordinates too.
+     * The space the positions are in. `'lngLat'` is longitude and latitude, which web mercator puts in the square from 0
+     * to 1 that tile 0/0/0 covers, with latitudes beyond ~85.05 degrees clamped onto its top and bottom. `'unitSquare'`
+     * is x and y in that square already, y growing downward, taken as they are, for data in another projection.
+     * `getData` and the cluster methods return positions in the same space.
      * @experimental
-     * @default false
+     * @default 'lngLat'
      */
-    worldCoordinates?: boolean;
+    coordinates?: GeoJSONVTCoordinatesType;
+    /**
+     * Whether the world wraps around the antimeridian. With `true`, features near the left or right edge are copied
+     * across it, and the tiles at either edge include what lies past it. With `false`, the world is the square and ends
+     * at its edges. Features are cut at the tile buffer around it, points outside it are left out of the clusters, and
+     * `getTile` returns `null` outside it. `geoJSONToTile` doesn't wrap unless this is `true`.
+     * @experimental
+     * @default true
+     */
+    wrap?: boolean;
     /**
      * Enable Supercluster for point features. Each position of a MultiPoint feature is clustered as a point of its own.
      * Other geometry types are left out.
@@ -70,15 +84,15 @@ export type GeoJSONVTOptions = {
      */
     cluster?: boolean;
     /**
-     * Options for the Supercluster point clustering algorithm.
+     * Options for the Supercluster point clustering algorithm. `coordinates` and `wrap` come from the options above.
      * @see {@link SuperclusterOptions}
      */
-    clusterOptions?: SuperclusterOptions;
+    clusterOptions?: Omit<SuperclusterOptions, 'coordinates' | 'wrap'>;
 };
 
 export type GeoJSONToTileOptions = GeoJSONVTOptions & {
     /**
-     * Whether to wrap features around the antimeridian. Has no effect with `worldCoordinates`.
+     * Whether to wrap features around the antimeridian, see `wrap` in {@link GeoJSONVTOptions}.
      * @default false
      */
     wrap?: boolean;
@@ -275,4 +289,19 @@ export type SuperclusterOptions = {
      * @default props => props
      */
     map?: (props: GeoJSON.GeoJsonProperties) => Record<string, unknown>;
+    /**
+     * The space the points are in, see `coordinates` in {@link GeoJSONVTOptions}. The bounding box of `getClusters` is
+     * in the same space.
+     * @experimental
+     * @default 'lngLat'
+     */
+    coordinates?: GeoJSONVTCoordinatesType;
+    /**
+     * Whether the world wraps around the antimeridian, see `wrap` in {@link GeoJSONVTOptions}. With `false`, points
+     * outside the square are left out of the clusters, the tiles at an edge get no points from the opposite one, and
+     * `getTile` returns `null` outside the square.
+     * @experimental
+     * @default true
+     */
+    wrap?: boolean;
 };

package/src/difference.ts

@@ -70,9 +70,10 @@ type HashedGeoJSONVTSourceDiff = {
  * @param source 
  * @param dataDiff 
  * @param options 
+ * @param unlocated - the features without coordinates, by id, so that an update can give them some
  * @returns 
  */
-export function applySourceDiff(source: GeoJSONVTInternalFeature[], dataDiff: GeoJSONVTSourceDiff, options: GeoJSONVTOptions): ApplySourceDiffResult {
+export function applySourceDiff(source: GeoJSONVTInternalFeature[], dataDiff: GeoJSONVTSourceDiff, options: GeoJSONVTOptions, unlocated?: Map<string | number, GeoJSON.Feature>): ApplySourceDiffResult {
     // convert diff to sets/maps for o(1) lookups
     const diff = diffToHashed(dataDiff, options);
 
@@ -82,9 +83,12 @@ export function applySourceDiff(source: GeoJSONVTInternalFeature[], dataDiff: Ge
     if (diff.removeAll) {
         affected = source;
         source = [];
+        unlocated?.clear();
     }
 
     if (diff.remove.size || diff.add.size) {
+        for (const id of diff.remove) unlocated?.delete(id);
+
         const removeFeatures = [];
 
         // Collect features to remove (explicit removals + replacements via add)
@@ -101,7 +105,7 @@ export function applySourceDiff(source: GeoJSONVTInternalFeature[], dataDiff: Ge
         }
 
         if (diff.add.size) {
-            let addFeatures = convertToInternal({type: 'FeatureCollection', features: Array.from(diff.add.values())}, options);
+            let addFeatures = convertToInternal({type: 'FeatureCollection', features: Array.from(diff.add.values())}, options, unlocated);
             addFeatures = wrap(addFeatures, options);
             affected = affected.concat(addFeatures);
             source = source.concat(addFeatures);
@@ -121,8 +125,14 @@ export function applySourceDiff(source: GeoJSONVTInternalFeature[], dataDiff: Ge
         }
         for (const [id, update] of diff.update) {
             const oldFeatures = oldFeaturesMap.get(id); 
-            if (!oldFeatures || oldFeatures.length === 0) continue;
-            const updatedFeatures = getUpdatedFeatures(oldFeatures, update, options);
+            if (!oldFeatures || oldFeatures.length === 0) {
+                if (!unlocated?.has(id)) continue;
+                const locatedFeatures = getUpdatedUnlocatedFeatures(id, update, options, unlocated);
+                affected = affected.concat(locatedFeatures);
+                keepFeatures = keepFeatures.concat(locatedFeatures);
+                continue;
+            }
+            const updatedFeatures = getUpdatedFeatures(oldFeatures, update, options, unlocated);
 
             affected = affected.concat(oldFeatures, updatedFeatures);
             keepFeatures = keepFeatures.concat(updatedFeatures);
@@ -138,28 +148,18 @@ export function applySourceDiff(source: GeoJSONVTInternalFeature[], dataDiff: Ge
  * @param vtFeatures - the original features
  * @param update - the update object to apply
  * @param options - the options to use for the wrap method
+ * @param unlocated - the features without coordinates, by id, which a new geometry without coordinates adds the feature to
  * @returns Updated features. If geometry is updated, returns new feature(s) converted from geojson and wrapped, with the id the feature already has. If only properties are updated, returns feature(s) with tags updated.
  */
-function getUpdatedFeatures(vtFeatures: GeoJSONVTInternalFeature[], update: GeoJSONVTFeatureDiff, options: GeoJSONVTOptions): GeoJSONVTInternalFeature[] {
+function getUpdatedFeatures(vtFeatures: GeoJSONVTInternalFeature[], update: GeoJSONVTFeatureDiff, options: GeoJSONVTOptions, unlocated?: Map<string | number, GeoJSON.Feature>): GeoJSONVTInternalFeature[] {
     const changeGeometry = !!update.newGeometry;
-    const changeProps =
-        update.removeAllProperties ||
-        update.removeProperties?.length > 0 ||
-        update.addOrUpdateProperties?.length > 0;
+    const changeProps = hasPropertyChanges(update);
 
     // if geometry changed, need to create a new geojson feature and convert to internal format
     if (changeGeometry) {
         const vtFeature = vtFeatures[0];
-        const geojsonFeature = {
-            type: 'Feature' as const,
-            id: vtFeature.id,
-            geometry: update.newGeometry,
-            properties: changeProps ? applyPropertyUpdates(vtFeature.tags, update) : vtFeature.tags
-        };
-
-        let features = convertToInternal({type: 'FeatureCollection', features: [geojsonFeature]}, {...options, promoteId: undefined, generateId: false});
-        features = wrap(features, options);
-        return features;
+        const properties = changeProps ? applyPropertyUpdates(vtFeature.tags, update) : vtFeature.tags;
+        return convertNewGeometry(vtFeature.id, update.newGeometry, properties, options, unlocated);
     }
 
     if (changeProps) {
@@ -175,6 +175,35 @@ function getUpdatedFeatures(vtFeatures: GeoJSONVTInternalFeature[], update: GeoJ
     return vtFeatures;
 }
 
+/**
+ * Gets the features an update gives a feature without coordinates: none, unless its new geometry has some.
+ * Its property changes apply either way.
+ */
+function getUpdatedUnlocatedFeatures(id: string | number, update: GeoJSONVTFeatureDiff, options: GeoJSONVTOptions, unlocated: Map<string | number, GeoJSON.Feature>): GeoJSONVTInternalFeature[] {
+    const feature = unlocated.get(id);
+    const properties = hasPropertyChanges(update) ? applyPropertyUpdates(feature.properties, update) : feature.properties;
+    if (!update.newGeometry) {
+        unlocated.set(id, {...feature, properties});
+        return [];
+    }
+    return convertNewGeometry(id, update.newGeometry, properties, options, unlocated);
+}
+
+/**
+ * Converts the new geometry of a feature to internal format, keeping the id the feature already has
+ */
+function convertNewGeometry(id: GeoJSONVTInternalFeature['id'], geometry: GeoJSON.Geometry, properties: GeoJSON.GeoJsonProperties, options: GeoJSONVTOptions, unlocated?: Map<string | number, GeoJSON.Feature>): GeoJSONVTInternalFeature[] {
+    const geojsonFeature = {type: 'Feature' as const, id, geometry, properties};
+    const features = convertToInternal({type: 'FeatureCollection', features: [geojsonFeature]}, {...options, promoteId: undefined, generateId: false}, unlocated);
+    return wrap(features, options);
+}
+
+function hasPropertyChanges(update: GeoJSONVTFeatureDiff): boolean {
+    return update.removeAllProperties ||
+        update.removeProperties?.length > 0 ||
+        update.addOrUpdateProperties?.length > 0;
+}
+
 /**
  * helper to apply property updates from a diff update object to a properties object
  */

package/src/geojson-to-tile.ts

@@ -40,8 +40,8 @@ import type {GeoJSONToTileOptions, GeoJSONVTTile} from './definitions';
  */
 
 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;
+    options = {...defaultOptions, wrap: false, ...options};
+    const {wrap: shouldWrap, clip: shouldClip = false} = options;
 
     let features = convertToInternal(data, options);
     if (shouldWrap) {

package/src/geojsonvt.test.ts

@@ -38,25 +38,25 @@ test('publicly exposed cluster methods: return undefined when clustering is disa
     expect(index.getClusterLeaves(123, 10, 0)).toBeNull();
 });
 
-test('worldCoordinates cuts a line at the buffer around the world instead of wrapping or clamping it', () => {
+test('a unit square without wrap cuts a line at the buffer around the world instead of wrapping or clamping it', () => {
     const fromThreeWorldsNorthToEast = {type: 'LineString' as const, coordinates: [[0.25, -3], [0.75, 0.5], [1.25, 0.5]]};
 
-    const index = new GeoJSONVT(fromThreeWorldsNorthToEast, {worldCoordinates: true});
+    const index = new GeoJSONVT(fromThreeWorldsNorthToEast, {coordinates: 'unitSquare', wrap: false});
 
     expect(index.getTile(0, 0, 0).features.map(feature => feature.geometry)).toEqual([[[[2770, -64], [3072, 2048], [4160, 2048]]]]);
 });
 
-test('worldCoordinates cuts the top tile at the world again on update, so a feature can move in from outside', () => {
+test('a unit square without wrap cuts the top tile at the world again on update, so a feature can move in from outside', () => {
     const movingIn = {type: 'Feature' as const, id: 'moving in', geometry: {type: 'Point' as const, coordinates: [1.25, 0.5]}, properties: {}};
     const stayingOut = {type: 'Feature' as const, id: 'staying out', geometry: {type: 'Point' as const, coordinates: [1.5, 0.5]}, properties: {}};
-    const index = new GeoJSONVT({type: 'FeatureCollection', features: [movingIn, stayingOut]}, {worldCoordinates: true, updateable: true});
+    const index = new GeoJSONVT({type: 'FeatureCollection', features: [movingIn, stayingOut]}, {coordinates: 'unitSquare', wrap: false, updateable: true});
 
     index.updateData({update: [{id: 'moving in', newGeometry: {type: 'Point', coordinates: [0.5, 0.5]}}]});
 
     expect(index.getTile(0, 0, 0).features.map(feature => feature.id)).toEqual(['moving in']);
 });
 
-test('worldCoordinates returns the data in world coordinates', () => {
+test('a unit square without wrap returns the data in the unit square', () => {
     const features: GeoJSON.Feature[] = [
         {type: 'Feature', id: 'point', geometry: {type: 'Point', coordinates: [0.25, 0.75]}, properties: {}},
         {type: 'Feature', id: 'multi point', geometry: {type: 'MultiPoint', coordinates: [[0.25, 0.75], [0.5, 0.5]]}, properties: {}},
@@ -65,14 +65,14 @@ test('worldCoordinates returns the data in world coordinates', () => {
         {type: 'Feature', id: 'polygon', geometry: {type: 'Polygon', coordinates: [[[0.25, 0.25], [0.75, 0.25], [0.75, 0.75], [0.25, 0.25]]]}, properties: {}},
         {type: 'Feature', id: 'multi polygon', geometry: {type: 'MultiPolygon', coordinates: [[[[0.25, 0.25], [0.75, 0.25], [0.75, 0.75], [0.25, 0.25]]]]}, properties: {}}
     ];
-    const index = new GeoJSONVT({type: 'FeatureCollection', features}, {worldCoordinates: true, updateable: true});
+    const index = new GeoJSONVT({type: 'FeatureCollection', features}, {coordinates: 'unitSquare', wrap: false, updateable: true});
 
     expect(index.getData()).toEqual({type: 'FeatureCollection', features});
 });
 
-test('worldCoordinates keeps a MultiLineString it splits for lineMetrics in world coordinates', () => {
+test('a unit square without wrap keeps a MultiLineString it splits for lineMetrics in the unit square', () => {
     const multiLine = {type: 'MultiLineString' as const, coordinates: [[[0.25, 0.75], [0.5, 0.5]], [[0.5, 0.25], [0.75, 0.25]]]};
-    const index = new GeoJSONVT(multiLine, {worldCoordinates: true, lineMetrics: true, updateable: true});
+    const index = new GeoJSONVT(multiLine, {coordinates: 'unitSquare', wrap: false, lineMetrics: true, updateable: true});
 
     expect(index.getData()).toEqual({type: 'FeatureCollection', features: [
         {type: 'Feature', geometry: {type: 'LineString', coordinates: [[0.25, 0.75], [0.5, 0.5]]}},
@@ -80,9 +80,9 @@ test('worldCoordinates keeps a MultiLineString it splits for lineMetrics in worl
     ]});
 });
 
-test('worldCoordinates hands the update filter features in world coordinates', () => {
+test('a unit square without wrap hands the update filter features in the unit square', () => {
     const point = {type: 'Feature' as const, id: 'p', geometry: {type: 'Point' as const, coordinates: [0.25, 0.75]}, properties: {}};
-    const index = new GeoJSONVT({type: 'FeatureCollection', features: [point]}, {worldCoordinates: true, updateable: true});
+    const index = new GeoJSONVT({type: 'FeatureCollection', features: [point]}, {coordinates: 'unitSquare', wrap: false, updateable: true});
     const filtered: GeoJSON.Geometry[] = [];
 
     index.updateData({add: [{...point, id: 'q'}]}, feature => {
@@ -93,7 +93,7 @@ test('worldCoordinates hands the update filter features in world coordinates', (
     expect(filtered).toContainEqual({type: 'Point', coordinates: [0.25, 0.75]});
 });
 
-test('worldCoordinates leaves points outside the world out of the clusters', () => {
+test('a unit square without wrap leaves points outside the world out of the clusters', () => {
     const data = {
         type: 'FeatureCollection' as const,
         features: [
@@ -103,12 +103,12 @@ test('worldCoordinates leaves points outside the world out of the clusters', ()
         ]
     };
 
-    const index = new GeoJSONVT(data, {worldCoordinates: true, cluster: true});
+    const index = new GeoJSONVT(data, {coordinates: 'unitSquare', wrap: false, cluster: true});
 
     expect(index.getTile(0, 0, 0).features.map(feature => feature.geometry)).toEqual([[[507, 256]]]);
 });
 
-test('worldCoordinates keeps points at either edge out of the clustered tile at the other edge', () => {
+test('a unit square without wrap keeps points at either edge out of the clustered tile at the other edge', () => {
     const data = {
         type: 'FeatureCollection' as const,
         features: [
@@ -117,12 +117,12 @@ test('worldCoordinates keeps points at either edge out of the clustered tile at
         ]
     };
 
-    const index = new GeoJSONVT(data, {worldCoordinates: true, cluster: true});
+    const index = new GeoJSONVT(data, {coordinates: 'unitSquare', wrap: false, cluster: true});
 
     expect(index.getTile(0, 0, 0).features).toHaveLength(2);
 });
 
-test('worldCoordinates returns cluster children and leaves in world coordinates', () => {
+test('a unit square without wrap returns cluster children and leaves in the unit square', () => {
     const points = {
         type: 'FeatureCollection' as const,
         features: Array.from({length: 20}, (_, i) => ({
@@ -131,7 +131,7 @@ test('worldCoordinates returns cluster children and leaves in world coordinates'
             properties: {name: `Point ${i}`}
         }))
     };
-    const index = new GeoJSONVT(points, {worldCoordinates: true, cluster: true, clusterOptions: {radius: 100}});
+    const index = new GeoJSONVT(points, {coordinates: 'unitSquare', wrap: false, cluster: true, clusterOptions: {radius: 100}});
     const cluster = index.getTile(0, 0, 0).features.find(f => (f.tags as {cluster?: boolean})?.cluster);
     const clusterId = (cluster.tags as {cluster_id: number}).cluster_id;
 
@@ -142,10 +142,41 @@ test('worldCoordinates returns cluster children and leaves in world coordinates'
     expect(leafPositions).toEqual(expect.arrayContaining(points.features.map(point => point.geometry.coordinates)));
 });
 
-test('worldCoordinates returns no tile for a column on either side of the world', () => {
+test('a unit square without wrap stays without wrap for clusters after updateData', () => {
+    const point = (id: string, x: number) => ({type: 'Feature' as const, id, properties: {}, geometry: {type: 'Point' as const, coordinates: [x, 0.5]}});
+    const index = new GeoJSONVT({type: 'FeatureCollection', features: [point('a', 0.01)]}, {coordinates: 'unitSquare', wrap: false, cluster: true, updateable: true});
+
+    index.updateData({add: [point('b', 0.99)]});
+
+    expect(index.getTile(1, -1, 0)).toBeNull();
+});
+
+test('wraps positions in the unit square around the antimeridian by default', () => {
+    const nearTheEastEdge = {type: 'Feature' as const, properties: {}, geometry: {type: 'Point' as const, coordinates: [0.999, 0.25]}};
+    const index = new GeoJSONVT(nearTheEastEdge, {coordinates: 'unitSquare'});
+
+    expect(index.getTile(1, 0, 0).features.map(feature => feature.geometry)).toEqual([[[-8, 2048]]]);
+});
+
+test('cuts the top tile above and below for positions in a unit square that wraps', () => {
+    const fromThreeBelowToThreeAbove = {type: 'Feature' as const, properties: {}, geometry: {type: 'LineString' as const, coordinates: [[0.25, -3], [0.75, 3]]}};
+    const index = new GeoJSONVT(fromThreeBelowToThreeAbove, {coordinates: 'unitSquare'});
+
+    expect(index.getTile(0, 0, 0).features[0].geometry).toEqual([[[2043, -64], [2395, 4160]]]);
+});
+
+test('copies no lng/lat features across the antimeridian without wrap', () => {
+    const nearTheAntimeridian = {type: 'Feature' as const, properties: {}, geometry: {type: 'Point' as const, coordinates: [179.9, -10]}};
+    const index = new GeoJSONVT(nearTheAntimeridian, {wrap: false});
+
+    expect(index.getTile(1, 0, 1)?.features ?? []).toEqual([]);
+    expect(index.getTile(1, 1, 1).features).toHaveLength(1);
+});
+
+test('a unit square without wrap returns no tile for a column on either side of the world', () => {
     const inTheTwoTopTiles = {type: 'MultiPoint' as const, coordinates: [[0.25, 0.25], [0.75, 0.25]]};
 
-    const index = new GeoJSONVT(inTheTwoTopTiles, {worldCoordinates: true});
+    const index = new GeoJSONVT(inTheTwoTopTiles, {coordinates: 'unitSquare', wrap: false});
 
     expect([index.getTile(1, -1, 0), index.getTile(1, 2, 0)]).toEqual([null, null]);
 });
@@ -210,6 +241,126 @@ test('leaves out a MultiPolygon that has only empty polygons', () => {
     expect(index.getData()).toEqual({type: 'FeatureCollection', features: []});
 });
 
+test('updateData draws a feature again when an update gives back the coordinates an earlier one took away', () => {
+    const line = {type: 'Feature' as const, id: 'line', properties: {name: 'line'}, geometry: {type: 'LineString' as const, coordinates: [[0, 0], [10, 10]]}};
+    const index = new GeoJSONVT({type: 'FeatureCollection', features: [line]}, {updateable: true});
+
+    index.updateData({update: [{id: 'line', newGeometry: {type: 'LineString', coordinates: []}}]});
+    index.updateData({update: [{id: 'line', newGeometry: line.geometry}]});
+
+    expect(index.getTile(0, 0, 0).features.map(feature => feature.tags)).toEqual([{name: 'line'}]);
+});
+
+test('updateData draws a feature loaded without a geometry once an update gives it one', () => {
+    const later: GeoJSON.Feature = {type: 'Feature', id: 'later', properties: {name: 'later'}, geometry: null};
+    const index = new GeoJSONVT({type: 'FeatureCollection', features: [later]}, {updateable: true});
+
+    index.updateData({update: [{id: 'later', newGeometry: {type: 'Point', coordinates: [10, 10]}}]});
+
+    expect(index.getTile(0, 0, 0).features.map(feature => feature.tags)).toEqual([{name: 'later'}]);
+});
+
+test('updateData draws a feature added without coordinates once an update gives it some', () => {
+    const index = new GeoJSONVT({type: 'FeatureCollection', features: []}, {updateable: true});
+
+    index.updateData({add: [{type: 'Feature', id: 'added', properties: {name: 'added'}, geometry: {type: 'Polygon', coordinates: []}}]});
+    index.updateData({update: [{id: 'added', newGeometry: {type: 'Polygon', coordinates: [[[0, 0], [10, 0], [10, 10], [0, 0]]]}}]});
+
+    expect(index.getTile(0, 0, 0).features.map(feature => feature.tags)).toEqual([{name: 'added'}]);
+});
+
+test('updateData leaves a feature without a geometry removed when an update gives it one', () => {
+    const kept = {type: 'Feature' as const, id: 'kept', properties: {}, geometry: {type: 'Point' as const, coordinates: [0, 0]}};
+    const removed: GeoJSON.Feature = {type: 'Feature', id: 'removed', properties: {}, geometry: null};
+    const index = new GeoJSONVT({type: 'FeatureCollection', features: [kept, removed]}, {updateable: true});
+
+    index.updateData({remove: ['removed']});
+    index.updateData({update: [{id: 'removed', newGeometry: {type: 'Point', coordinates: [10, 10]}}]});
+
+    expect(index.getTile(0, 0, 0).features.map(feature => feature.id)).toEqual(['kept']);
+});
+
+test('updateData leaves a feature without a geometry removed by removeAll when an update gives it one', () => {
+    const kept = {type: 'Feature' as const, id: 'kept', properties: {}, geometry: {type: 'Point' as const, coordinates: [0, 0]}};
+    const removed: GeoJSON.Feature = {type: 'Feature', id: 'removed', properties: {}, geometry: null};
+    const index = new GeoJSONVT({type: 'FeatureCollection', features: [removed]}, {updateable: true});
+
+    index.updateData({removeAll: true, add: [kept]});
+    index.updateData({update: [{id: 'removed', newGeometry: {type: 'Point', coordinates: [10, 10]}}]});
+
+    expect(index.getTile(0, 0, 0).features.map(feature => feature.id)).toEqual(['kept']);
+});
+
+test('updateData keeps the property changes made to a feature while it has no geometry', () => {
+    const renamed: GeoJSON.Feature = {type: 'Feature', id: 'renamed', properties: {name: 'before'}, geometry: null};
+    const index = new GeoJSONVT({type: 'FeatureCollection', features: [renamed]}, {updateable: true});
+
+    index.updateData({update: [{id: 'renamed', addOrUpdateProperties: [{key: 'name', value: 'after'}]}]});
+    index.updateData({update: [{id: 'renamed', newGeometry: {type: 'Point', coordinates: [10, 10]}}]});
+
+    expect(index.getTile(0, 0, 0).features.map(feature => feature.tags)).toEqual([{name: 'after'}]);
+});
+
+test('updateData does not bring back a feature the update filter took out after an update gave it a geometry', () => {
+    const kept = {type: 'Feature' as const, id: 'kept', properties: {}, geometry: {type: 'Point' as const, coordinates: [0, 0]}};
+    const hidden: GeoJSON.Feature = {type: 'Feature', id: 'hidden', properties: {hidden: true}, geometry: null};
+    const index = new GeoJSONVT({type: 'FeatureCollection', features: [kept, hidden]}, {updateable: true});
+
+    index.updateData({update: [{id: 'hidden', newGeometry: {type: 'Point', coordinates: [10, 10]}}]}, feature => !feature.properties.hidden);
+    index.updateData({update: [{id: 'hidden', newGeometry: {type: 'Point', coordinates: [20, 20]}}]});
+
+    expect(index.getTile(0, 0, 0).features.map(feature => feature.id)).toEqual(['kept']);
+});
+
+test('updateData does not bring back a feature the update filter took out while it had no coordinates', () => {
+    const point = {type: 'Feature' as const, id: 'point', properties: {keep: true}, geometry: {type: 'Point' as const, coordinates: [0, 0]}};
+    const index = new GeoJSONVT({type: 'FeatureCollection', features: [point]}, {updateable: true});
+    const keepIfMarked = (feature: GeoJSON.Feature) => feature.properties?.keep === true;
+
+    index.updateData({update: [{id: 'point', newGeometry: {type: 'Point', coordinates: []}, addOrUpdateProperties: [{key: 'keep', value: false}]}]}, keepIfMarked);
+    index.updateData({update: [{id: 'point', newGeometry: {type: 'Point', coordinates: [10, 10]}, addOrUpdateProperties: [{key: 'keep', value: true}]}]}, keepIfMarked);
+
+    expect(index.getData()).toEqual({type: 'FeatureCollection', features: []});
+});
+
+test('updateData draws a bare geometry loaded without coordinates once an update gives it some', () => {
+    const index = new GeoJSONVT({type: 'LineString', coordinates: []}, {updateable: true, generateId: true});
+
+    index.updateData({update: [{id: 0, newGeometry: {type: 'LineString', coordinates: [[0, 0], [10, 10]]}}]});
+
+    expect(index.getTile(0, 0, 0)?.features.map(feature => feature.id)).toEqual([0]);
+});
+
+test('updateData keeps a feature loaded without a geometry away from the update filter', () => {
+    const point = {type: 'Feature' as const, id: 'point', properties: {}, geometry: {type: 'Point' as const, coordinates: [0, 0]}};
+    const later: GeoJSON.Feature = {type: 'Feature', id: 'later', properties: {}, geometry: null};
+    const index = new GeoJSONVT({type: 'FeatureCollection', features: [point, later]}, {updateable: true});
+    const pointsOnly = (feature: GeoJSON.Feature) => feature.geometry.type === 'Point';
+
+    index.updateData({update: [{id: 'point', addOrUpdateProperties: [{key: 'name', value: 'p'}]}]}, pointsOnly);
+    index.updateData({update: [{id: 'later', newGeometry: {type: 'Point', coordinates: [10, 10]}}]}, pointsOnly);
+
+    expect(index.getTile(0, 0, 0)?.features.map(feature => feature.id).sort()).toEqual(['later', 'point']);
+});
+
+test('updateData hands the filter a feature without coordinates with its promoted id', () => {
+    const index = new GeoJSONVT({type: 'FeatureCollection', features: [{type: 'Feature', id: 'raw', properties: {key: 'promoted'}, geometry: {type: 'Point', coordinates: []}}]}, {updateable: true, promoteId: 'key'});
+
+    index.updateData({}, feature => feature.id === 'promoted');
+    index.updateData({update: [{id: 'promoted', newGeometry: {type: 'Point', coordinates: [10, 10]}}]});
+
+    expect(index.getTile(0, 0, 0)?.features.map(feature => feature.id)).toEqual(['promoted']);
+});
+
+test('updateData hands the filter a feature without coordinates with its generated id', () => {
+    const index = new GeoJSONVT({type: 'FeatureCollection', features: [{type: 'Feature', properties: {}, geometry: {type: 'Point', coordinates: []}}]}, {updateable: true, generateId: true});
+
+    index.updateData({}, feature => feature.id === 0);
+    index.updateData({update: [{id: 0, newGeometry: {type: 'Point', coordinates: [10, 10]}}]});
+
+    expect(index.getTile(0, 0, 0)?.features.map(feature => feature.id)).toEqual([0]);
+});
+
 test('keeps the corner of a polygon whose vertex lies on the left edge of a tile', () => {
     const polygon = {
         type: 'Polygon' as const,
@@ -261,14 +412,14 @@ test('clusters each position of a MultiPoint feature when clustering is on', ()
     ]);
 });
 
-test('worldCoordinates leaves the positions of a MultiPoint outside the world out of the clusters', () => {
+test('a unit square without wrap leaves the positions of a MultiPoint outside the world out of the clusters', () => {
     const multiPoint = {
         type: 'Feature' as const,
         properties: {},
         geometry: {type: 'MultiPoint' as const, coordinates: [[0.99, 0.5], [1.03, 0.5], [0.5, -0.03]]}
     };
 
-    const index = new GeoJSONVT(multiPoint, {worldCoordinates: true, cluster: true});
+    const index = new GeoJSONVT(multiPoint, {coordinates: 'unitSquare', wrap: false, cluster: true});
 
     expect(index.getTile(0, 0, 0).features.map(feature => feature.geometry)).toEqual([[[507, 256]]]);
 });