@osmix/core 0.2.0 → 0.3.0

package/test/nodes-spatial-index.test.ts

@@ -0,0 +1,261 @@
+import type { GeoBbox2D } from "@osmix/types";
+import { describe, expect, it } from "vitest";
+
+import { IndirectKdIndex } from "../src/indirect-kd-index.ts";
+import { Nodes, SpatialIndexNotBuiltError } from "../src/nodes.ts";
+import { Osm } from "../src/osm.ts";
+
+const EARTH_RADIUS_KM = 6371.0088;
+
+describe("indirect node spatial indexes", () => {
+  it("stores exactly one Uint32 per indexed node", () => {
+    const osm = new Osm();
+    for (let i = 0; i < 10; i++) {
+      osm.nodes.addNode({
+        id: i + 1,
+        lon: i,
+        lat: i,
+        ...(i % 3 === 0 ? { tags: { name: `${i}` } } : {}),
+      });
+    }
+    osm.buildIndexes();
+    osm.nodes.buildSpatialIndex("all");
+    osm.nodes.buildSpatialIndex("tagged");
+
+    const transferables = osm.nodes.transferables();
+    expect(transferables.allSpatialIndex?.byteLength).toBe(10 * Uint32Array.BYTES_PER_ELEMENT);
+    expect(transferables.taggedSpatialIndex?.byteLength).toBe(4 * Uint32Array.BYTES_PER_ELEMENT);
+    expect(osm.nodes.taggedSize).toBe(4);
+    expect(Nodes.getSpatialIndexBytesRequired(133_881_054)).toBe(535_524_216);
+  });
+
+  it("keeps all-node and tagged-node capabilities independent", () => {
+    const osm = new Osm();
+    osm.nodes.addNode({ id: 1, lon: 1, lat: 1, tags: { amenity: "bench" } });
+    osm.nodes.addNode({ id: 2, lon: 2, lat: 2 });
+    osm.nodes.addNode({ id: 3, lon: 3, lat: 3, tags: { name: "three" } });
+    osm.buildIndexes();
+
+    osm.nodes.buildSpatialIndex("tagged");
+    expect(osm.nodes.hasSpatialIndex("tagged")).toBe(true);
+    expect(osm.nodes.hasSpatialIndex("all")).toBe(false);
+    expect(osm.nodes.findTaggedIndexesWithinBbox([-180, -90, 180, 90])).toEqual([0, 2]);
+    expect(() => osm.nodes.findIndexesWithinBbox([-180, -90, 180, 90])).toThrowError(
+      SpatialIndexNotBuiltError,
+    );
+
+    osm.nodes.buildSpatialIndex("all");
+    expect(osm.nodes.findIndexesWithinBbox([-180, -90, 180, 90])).toEqual([0, 1, 2]);
+  });
+
+  it("throws a structured error when the requested capability is absent", () => {
+    const osm = new Osm();
+    osm.nodes.addNode({ id: 1, lon: 0, lat: 0 });
+    osm.buildIndexes();
+
+    let error: unknown;
+    try {
+      osm.nodes.findIndexesWithinRadius(0, 0, 1);
+    } catch (caught) {
+      error = caught;
+    }
+    expect(error).toBeInstanceOf(SpatialIndexNotBuiltError);
+    expect(error).toMatchObject({
+      name: "SpatialIndexNotBuiltError",
+      code: "SPATIAL_INDEX_NOT_BUILT",
+      entityType: "node",
+      indexKind: "all",
+    });
+  });
+
+  it("round-trips both capabilities through transferables, including empty indexes", () => {
+    const source = new Osm();
+    source.nodes.addNode({ id: 1, lon: -1, lat: -1, tags: { name: "one" } });
+    source.nodes.addNode({ id: 2, lon: 1, lat: 1 });
+    source.buildIndexes();
+    source.nodes.buildSpatialIndex("all");
+    source.nodes.buildSpatialIndex("tagged");
+
+    const reconstructed = new Osm(source);
+    expect(reconstructed.nodes.hasSpatialIndex("all")).toBe(true);
+    expect(reconstructed.nodes.hasSpatialIndex("tagged")).toBe(true);
+    expect(reconstructed.nodes.findIndexesWithinBbox([-2, -2, 2, 2])).toEqual([0, 1]);
+    expect(reconstructed.nodes.findTaggedIndexesWithinBbox([-2, -2, 2, 2])).toEqual([0]);
+
+    const empty = new Osm();
+    empty.buildIndexes();
+    empty.nodes.buildSpatialIndex("all");
+    empty.nodes.buildSpatialIndex("tagged");
+    const emptyReconstructed = new Osm(empty);
+    expect(emptyReconstructed.nodes.hasSpatialIndex("all")).toBe(true);
+    expect(emptyReconstructed.nodes.hasSpatialIndex("tagged")).toBe(true);
+    expect(emptyReconstructed.nodes.findIndexesWithinBbox([-180, -90, 180, 90])).toEqual([]);
+  });
+
+  it("reconstructs a permutation from ArrayBuffer as well as SharedArrayBuffer", () => {
+    const lons = new Int32Array([-1_000_000, 0, 1_000_000]);
+    const lats = new Int32Array([-1_000_000, 0, 1_000_000]);
+    const built = IndirectKdIndex.build(lons, lats, 3, (indexes) => indexes.set([0, 1, 2]));
+    const arrayBuffer = new ArrayBuffer(built.buffer.byteLength);
+    new Uint8Array(arrayBuffer).set(new Uint8Array(built.buffer));
+
+    const reconstructed = IndirectKdIndex.from(lons, lats, arrayBuffer);
+    expect(reconstructed.range(-1, -1, 1, 1)).toEqual([1]);
+  });
+
+  it("matches naive inclusive bbox scans across randomized data", () => {
+    const osm = randomOsm(1_000);
+    osm.nodes.buildSpatialIndex("all");
+
+    const random = mulberry32(20260717);
+    for (let i = 0; i < 100; i++) {
+      const lonA = random() * 360 - 180;
+      const lonB = random() * 360 - 180;
+      const latA = random() * 180 - 90;
+      const latB = random() * 180 - 90;
+      const bbox: GeoBbox2D = [
+        Math.min(lonA, lonB),
+        Math.min(latA, latB),
+        Math.max(lonA, lonB),
+        Math.max(latA, latB),
+      ];
+      const expected = naiveBbox(osm, bbox);
+      expect(osm.nodes.findIndexesWithinBbox(bbox).sort((a, b) => a - b)).toEqual(expected);
+    }
+  });
+
+  it("matches naive haversine scans and orders equal distances by node index", () => {
+    const osm = randomOsm(1_000, [
+      { id: 10_001, lon: 1, lat: 0 },
+      { id: 10_002, lon: -1, lat: 0 },
+    ]);
+    osm.nodes.buildSpatialIndex("all");
+
+    const queries: [number, number, number][] = [
+      [0, 0, 120],
+      [179.8, 0, 500],
+      [-73.9, 40.7, 1_000],
+      [20, 89.8, 100],
+      [0, -89.8, 100],
+      [30, 20, Number.POSITIVE_INFINITY],
+    ];
+    for (const [lon, lat, radius] of queries) {
+      expect(osm.nodes.findIndexesWithinRadius(lon, lat, radius)).toEqual(
+        naiveRadius(osm, lon, lat, radius),
+      );
+    }
+
+    const eastIndex = osm.nodes.ids.getIndexFromId(10_001);
+    const westIndex = osm.nodes.ids.getIndexFromId(10_002);
+    const equalDistanceResults = osm.nodes.findIndexesWithinRadius(0, 0, 112);
+    expect(equalDistanceResults.indexOf(eastIndex)).toBeLessThan(
+      equalDistanceResults.indexOf(westIndex),
+    );
+  });
+
+  it("handles antimeridian-crossing bboxes and polar radii", () => {
+    const osm = new Osm();
+    osm.nodes.addNode({ id: 1, lon: 179.9, lat: 0 });
+    osm.nodes.addNode({ id: 2, lon: -179.9, lat: 0 });
+    osm.nodes.addNode({ id: 3, lon: 0, lat: 0 });
+    osm.nodes.addNode({ id: 4, lon: 160, lat: 89.9 });
+    osm.nodes.addNode({ id: 5, lon: -20, lat: 89.9 });
+    osm.buildIndexes();
+    osm.nodes.buildSpatialIndex("all");
+
+    expect(osm.nodes.findIndexesWithinBbox([179, -1, -179, 1])).toEqual([0, 1]);
+    expect(osm.nodes.findIndexesWithinRadius(179.95, 0, 20)).toEqual([0, 1]);
+    expect(osm.nodes.findIndexesWithinRadius(70, 90, 20)).toEqual([3, 4]);
+  });
+
+  it("handles large runs of duplicate coordinates and inclusive boundaries", () => {
+    const osm = new Osm();
+    for (let i = 0; i < 256; i++) {
+      osm.nodes.addNode({ id: i + 1, lon: 12.3456789, lat: -45.6789123 });
+    }
+    osm.nodes.addNode({ id: 257, lon: 12.345679, lat: -45.6789123 });
+    osm.buildIndexes();
+    osm.nodes.buildSpatialIndex("all");
+
+    expect(
+      osm.nodes.findIndexesWithinBbox([12.3456789, -45.6789123, 12.3456789, -45.6789123]),
+    ).toHaveLength(256);
+    expect(osm.nodes.findIndexesWithinRadius(12.3456789, -45.6789123, 0)).toEqual(
+      Array.from({ length: 256 }, (_, index) => index),
+    );
+  });
+
+  it("includes a stored microdegree coordinate on its exact floating-point boundary", () => {
+    const osm = new Osm();
+    const lon = -179.9382715;
+    osm.nodes.addNode({ id: 1, lon, lat: 0 });
+    osm.buildIndexes();
+    osm.nodes.buildSpatialIndex("all");
+
+    // This degree value does not multiply back to its stored integer exactly.
+    expect((lon * 1e7) % 1).not.toBe(0);
+    expect(osm.nodes.findIndexesWithinBbox([lon, 0, lon, 0])).toEqual([0]);
+  });
+});
+
+function randomOsm(
+  count: number,
+  extraNodes: { id: number; lon: number; lat: number }[] = [],
+): Osm {
+  const osm = new Osm();
+  const random = mulberry32(42);
+  for (let i = 0; i < count; i++) {
+    osm.nodes.addNode({
+      id: i + 1,
+      lon: random() * 360 - 180,
+      lat: random() * 180 - 90,
+      ...(i % 11 === 0 ? { tags: { name: `${i}` } } : {}),
+    });
+  }
+  for (const node of extraNodes) osm.nodes.addNode(node);
+  osm.buildIndexes();
+  return osm;
+}
+
+function naiveBbox(osm: Osm, bbox: GeoBbox2D): number[] {
+  const indexes: number[] = [];
+  for (let i = 0; i < osm.nodes.size; i++) {
+    const [lon, lat] = osm.nodes.getNodeLonLat({ index: i });
+    const longitudeMatches =
+      bbox[0] <= bbox[2] ? lon >= bbox[0] && lon <= bbox[2] : lon >= bbox[0] || lon <= bbox[2];
+    if (longitudeMatches && lat >= bbox[1] && lat <= bbox[3]) indexes.push(i);
+  }
+  return indexes;
+}
+
+function naiveRadius(osm: Osm, lon: number, lat: number, radiusKm: number): number[] {
+  const matches: { distance: number; index: number }[] = [];
+  for (let i = 0; i < osm.nodes.size; i++) {
+    const [nodeLon, nodeLat] = osm.nodes.getNodeLonLat({ index: i });
+    const distance = haversineDistanceKm(lon, lat, nodeLon, nodeLat);
+    if (distance <= radiusKm) matches.push({ distance, index: i });
+  }
+  matches.sort((a, b) => a.distance - b.distance || a.index - b.index);
+  return matches.map(({ index }) => index);
+}
+
+function haversineDistanceKm(lon1: number, lat1: number, lon2: number, lat2: number): number {
+  const radians = Math.PI / 180;
+  const latDelta = (lat2 - lat1) * radians;
+  const lonDelta = (lon2 - lon1) * radians;
+  const a =
+    Math.sin(latDelta / 2) ** 2 +
+    Math.sin(lonDelta / 2) ** 2 * Math.cos(lat1 * radians) * Math.cos(lat2 * radians);
+  return 2 * EARTH_RADIUS_KM * Math.atan2(Math.sqrt(a), Math.sqrt(Math.max(0, 1 - a)));
+}
+
+function mulberry32(seed: number): () => number {
+  let state = seed;
+  return () => {
+    state |= 0;
+    state = (state + 0x6d2b79f5) | 0;
+    let value = Math.imul(state ^ (state >>> 15), 1 | state);
+    value = (value + Math.imul(value ^ (value >>> 7), 61 | value)) ^ value;
+    return ((value ^ (value >>> 14)) >>> 0) / 4_294_967_296;
+  };
+}

package/test/osm-bbox.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+
+import { Osm } from "../src/osm";
+
+describe("Osm.bbox", () => {
+  it("is null for a dataset without nodes", () => {
+    const osm = new Osm();
+    osm.buildIndexes();
+
+    expect(osm.bbox()).toBeNull();
+    expect(osm.info().bbox).toBeNull();
+  });
+
+  it("covers every node once nodes are added", () => {
+    const osm = new Osm();
+    osm.nodes.addNode({ id: 1, lon: -9.2, lat: 38.7 });
+    osm.nodes.addNode({ id: 2, lon: -8.6, lat: 41.1 });
+    osm.buildIndexes();
+
+    expect(osm.bbox()).toEqual([-9.2, 38.7, -8.6, 41.1]);
+    expect(osm.info().bbox).toEqual([-9.2, 38.7, -8.6, 41.1]);
+  });
+
+  it("stays null after an empty dataset is transferred and reconstructed", () => {
+    const empty = new Osm();
+    empty.buildIndexes();
+
+    expect(new Osm(empty.transferables()).bbox()).toBeNull();
+  });
+});

package/test/relations.bench.ts

@@ -1,9 +1,11 @@
-import { bench, describe } from "vitest";
+import { describe, test } from "vitest";
 
 import { Osm } from "../src/osm";
 
 function createManyMemberRelations() {
   const osm = new Osm({ id: "relations-benchmark" });
+  osm.nodes.addNode({ id: 1, lon: 0, lat: 0 });
+  for (let id = 0; id < 10_000; id++) osm.ways.addWay({ id, refs: [1] });
   for (let relationId = 0; relationId < 100; relationId++) {
     osm.relations.addRelation({
       id: relationId,
@@ -14,14 +16,17 @@ function createManyMemberRelations() {
       })),
     });
   }
+  osm.buildIndexes();
   return osm;
 }
 
 const osm = createManyMemberRelations();
-osm.relations.getWayMemberIds();
+osm.relations.isWayMember(0);
 
 describe("relation way membership cache", () => {
-  bench("1000 repeated cached lookups", () => {
-    for (let i = 0; i < 1000; i++) osm.relations.getWayMemberIds();
+  test("1000 repeated cached lookups", async ({ bench }) => {
+    await bench("1000 repeated cached lookups", () => {
+      for (let i = 0; i < 1000; i++) osm.relations.isWayMember(i);
+    }).run();
   });
 });

package/test/relations.test.ts

@@ -28,60 +28,89 @@ function createOsmWithRelations(): OsmType {
   return osm;
 }
 
-describe("relation way membership cache", () => {
-  it("returns an empty cached set for empty relations", () => {
-    const osm = new Osm();
+/** Way membership for every way in `osm`, as sorted way IDs. */
+function wayMemberIds(osm: OsmType): number[] {
+  const ids: number[] = [];
+  for (let i = 0; i < osm.ways.size; i++) {
+    if (osm.relations.isWayMember(i)) ids.push(osm.ways.ids.at(i));
+  }
+  return ids.sort((a, b) => a - b);
+}
 
-    const first = osm.relations.getWayMemberIds();
-    const second = osm.relations.getWayMemberIds();
+/** Osm with ways 10, 20 and 30 and no relations. */
+function createOsmWithWays(): OsmType {
+  const osm = new Osm();
+  osm.nodes.addNode({ id: 1, lon: 0, lat: 0 });
+  for (const id of [10, 20, 30]) osm.ways.addWay({ id, refs: [1] });
+  return osm;
+}
 
-    expect(first).toBe(second);
-    expect(first).toEqual(new Set());
+describe("relation way membership cache", () => {
+  it("reports no members when there are no relations", () => {
+    const osm = createOsmWithWays();
+    osm.buildIndexes();
+
+    expect(wayMemberIds(osm)).toEqual([]);
   });
 
   it("collects unique direct and nested way members", () => {
-    const wayIds = createOsmWithRelations().relations.getWayMemberIds();
-
-    expect(wayIds).toEqual(new Set([10, 20]));
+    expect(wayMemberIds(createOsmWithRelations())).toEqual([10, 20]);
   });
 
   it("does not traverse relations again while the cache is warm", () => {
     const osm = createOsmWithRelations();
     const getByIndex = vi.spyOn(osm.relations, "getByIndex");
 
-    const first = osm.relations.getWayMemberIds();
+    osm.relations.isWayMember(0);
     const callsAfterFirstLookup = getByIndex.mock.calls.length;
-    const second = osm.relations.getWayMemberIds();
+    osm.relations.isWayMember(1);
 
-    expect(second).toBe(first);
     expect(callsAfterFirstLookup).toBeGreaterThan(0);
     expect(getByIndex).toHaveBeenCalledTimes(callsAfterFirstLookup);
   });
 
+  // Relations cannot be added after their ID index is built, so these tests only index nodes and
+  // ways. Membership resolution without nested relations never consults the relation ID index.
   it("invalidates the cache when a relation is added", () => {
-    const osm = new Osm();
+    const osm = createOsmWithWays();
+    osm.nodes.buildIndex();
+    osm.ways.buildIndex();
     osm.relations.addRelation({ id: 1, members: [{ type: "way", ref: 10, role: "" }] });
-    const first = osm.relations.getWayMemberIds();
+    expect(wayMemberIds(osm)).toEqual([10]);
 
     osm.relations.addRelation({ id: 2, members: [{ type: "way", ref: 20, role: "" }] });
-    const second = osm.relations.getWayMemberIds();
 
-    expect(second).not.toBe(first);
-    expect(second).toEqual(new Set([10, 20]));
+    expect(wayMemberIds(osm)).toEqual([10, 20]);
   });
 
   it("invalidates the cache when relations are added in bulk", () => {
-    const osm = new Osm();
+    const osm = createOsmWithWays();
     osm.stringTable.add("");
+    osm.nodes.buildIndex();
+    osm.ways.buildIndex();
     osm.relations.addRelation({ id: 1, members: [{ type: "way", ref: 10, role: "" }] });
-    osm.relations.getWayMemberIds();
+    expect(wayMemberIds(osm)).toEqual([10]);
 
     osm.relations.addRelations(
       [{ id: 2, keys: [], vals: [], memids: [20], roles_sid: [0], types: [1] }],
       new Uint32Array([0]),
     );
 
-    expect(osm.relations.getWayMemberIds()).toEqual(new Set([10, 20]));
+    expect(wayMemberIds(osm)).toEqual([10, 20]);
+  });
+
+  it("ignores way members that are not in the dataset", () => {
+    const osm = createOsmWithWays();
+    osm.relations.addRelation({
+      id: 1,
+      members: [
+        { type: "way", ref: 30, role: "" },
+        { type: "way", ref: 99, role: "" },
+      ],
+    });
+    osm.buildIndexes();
+
+    expect(wayMemberIds(osm)).toEqual([30]);
   });
 
   it("starts with an empty cache after transfer and reconstruction", () => {
@@ -89,13 +118,7 @@ describe("relation way membership cache", () => {
     const reconstructed = new Osm(source);
     const getByIndex = vi.spyOn(reconstructed.relations, "getByIndex");
 
-    const first = reconstructed.relations.getWayMemberIds();
-    const callsAfterFirstLookup = getByIndex.mock.calls.length;
-    const second = reconstructed.relations.getWayMemberIds();
-
-    expect(first).toEqual(new Set([10, 20]));
-    expect(second).toBe(first);
-    expect(callsAfterFirstLookup).toBeGreaterThan(0);
-    expect(getByIndex).toHaveBeenCalledTimes(callsAfterFirstLookup);
+    expect(wayMemberIds(reconstructed)).toEqual([10, 20]);
+    expect(getByIndex.mock.calls.length).toBeGreaterThan(0);
   });
 });

package/test/renumber.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+
+import { Osm } from "../src/osm.ts";
+import { renumberNegativeIds } from "../src/renumber.ts";
+
+function mixedIds() {
+  const osm = new Osm({ id: "mixed" });
+  osm.nodes.addNode({ id: 5, lon: 0, lat: 0 });
+  osm.nodes.addNode({ id: -1, lon: 0.001, lat: 0, tags: { name: "New entrance" } });
+  osm.nodes.addNode({ id: -2, lon: 0.002, lat: 0 });
+  osm.ways.addWay({ id: 7, refs: [5, -1], tags: { highway: "footway" } });
+  osm.ways.addWay({ id: -3, refs: [-1, -2], tags: { highway: "footway" } });
+  osm.relations.addRelation({
+    id: -1,
+    members: [
+      { type: "node", ref: -2, role: "stop" },
+      { type: "way", ref: -3, role: "" },
+      { type: "way", ref: 7, role: "" },
+    ],
+    tags: { type: "route" },
+  });
+  osm.buildIndexes();
+  osm.buildSpatialIndexes();
+  return osm;
+}
+
+describe("renumberNegativeIds", () => {
+  it("gives each type's negative IDs new ones after its highest ID and follows every reference", () => {
+    const input = mixedIds();
+    const { osm, idMap } = renumberNegativeIds(input);
+    expect(idMap).toEqual({
+      nodes: { "-1": 6, "-2": 7 },
+      ways: { "-3": 8 },
+      relations: { "-1": 1 },
+    });
+    expect(osm.nodes.getById(6)?.tags).toEqual({ name: "New entrance" });
+    expect(osm.ways.getById(7)?.refs).toEqual([5, 6]);
+    expect(osm.ways.getById(8)?.refs).toEqual([6, 7]);
+    expect(osm.relations.getById(1)?.members.map((member) => member.ref)).toEqual([7, 8, 7]);
+    expect([...osm.nodes].every((node) => node.id > 0)).toBe(true);
+    // The input keeps its IDs.
+    expect(input.nodes.getById(-1)).not.toBeNull();
+  });
+
+  it("is deterministic and a no-op without negative IDs", () => {
+    expect(renumberNegativeIds(mixedIds()).idMap).toEqual(renumberNegativeIds(mixedIds()).idMap);
+    const positive = new Osm({ id: "positive" });
+    positive.nodes.addNode({ id: 1, lon: 0, lat: 0 });
+    positive.buildIndexes();
+    const { osm, idMap } = renumberNegativeIds(positive);
+    expect(idMap).toEqual({ nodes: {}, ways: {}, relations: {} });
+    expect([...osm.nodes]).toEqual([...positive.nodes]);
+  });
+});

package/test/spatial-index-rebuild.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+
+import { Osm } from "../src/osm.ts";
+
+function buildIndexedOsm() {
+  const osm = new Osm();
+  osm.nodes.addNode({ id: 1, lon: 0, lat: 0 });
+  osm.nodes.addNode({ id: 2, lon: 1, lat: 1 });
+  osm.ways.addWay({ id: 10, refs: [1, 2], tags: { highway: "path" } });
+  osm.relations.addRelation({
+    id: 100,
+    members: [{ type: "way", ref: 10, role: "" }],
+    tags: { type: "route" },
+  });
+  osm.buildIndexes();
+  osm.buildSpatialIndexes();
+  return osm;
+}
+
+describe("spatial index rebuilds", () => {
+  it("reuses built way and relation indexes", () => {
+    const osm = buildIndexedOsm();
+    const waysIndex = osm.ways.buildSpatialIndex();
+    const relationsIndex = osm.relations.buildSpatialIndex();
+
+    osm.buildSpatialIndexes();
+
+    expect(osm.ways.buildSpatialIndex()).toBe(waysIndex);
+    expect(osm.relations.buildSpatialIndex()).toBe(relationsIndex);
+    expect(osm.ways.intersects([-1, -1, 2, 2])).toEqual([0]);
+    expect(osm.relations.intersects([-1, -1, 2, 2])).toEqual([0]);
+  });
+});