@osmix/core 0.1.10 → 0.3.0

package/test/entity-index-errors.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { Osm } from "../src/osm.ts";
+import { TypedBufferAllocationError } from "../src/typed-arrays.ts";
+
+describe("entity index errors", () => {
+  it("adds entity and component context to typed-buffer failures", () => {
+    const osm = new Osm({ id: "allocation-error" });
+    const allocationError = new TypedBufferAllocationError(
+      {
+        operation: "compact",
+        typedArray: "Float64Array",
+        bufferType: "shared-array-buffer",
+        elementCount: 273_574_591,
+        bytesPerElement: 8,
+        requiredBytes: 2_188_596_728,
+      },
+      new RangeError("Array buffer allocation failed"),
+    );
+    vi.spyOn(osm.nodes.ids, "buildIndex").mockImplementation(() => {
+      throw allocationError;
+    });
+
+    expect(() => osm.nodes.buildIndex()).toThrowError(
+      expect.objectContaining({
+        name: "OsmEntityIndexBuildError",
+        code: "OSM_ENTITY_INDEX_BUILD_FAILED",
+        stage: "entity-index-finalization",
+        entityType: "node",
+        component: "ids",
+        operation: "compact",
+        typedArray: "Float64Array",
+        bufferType: "shared-array-buffer",
+        elementCount: 273_574_591,
+        bytesPerElement: 8,
+        requiredBytes: 2_188_596_728,
+        cause: allocationError,
+      }),
+    );
+  });
+});

package/test/ids.bench.ts

@@ -0,0 +1,33 @@
+import { describe, test } from "vitest";
+
+import { Ids } from "../src/ids";
+import { Osm } from "../src/osm";
+
+const values = Array.from({ length: 20_000 }, (_, index) => (index * 7919) % 100_000);
+
+function buildIds() {
+  const ids = new Ids();
+  for (const value of values) ids.add(value);
+  ids.buildIndex();
+  return ids;
+}
+
+const osm = new Osm();
+for (const value of values) osm.nodes.addNode({ id: value, lon: value, lat: value });
+osm.buildIndexes();
+
+describe("sorted ID iteration", () => {
+  test("build shuffled sorted index", async ({ bench }) => {
+    await bench("build shuffled sorted index", () => {
+      buildIds();
+    }).run();
+  });
+
+  test("iterate all sorted entities", async ({ bench }) => {
+    await bench("iterate all sorted entities", () => {
+      let checksum = 0;
+      for (const node of osm.nodes.sorted()) checksum += node.id + node.lon;
+      if (checksum === 0) throw Error("Unexpected empty benchmark");
+    }).run();
+  });
+});

package/test/ids.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { Ids } from "../src/ids";
+import { Osm } from "../src/osm";
+
+function buildIds(values: number[]) {
+  const ids = new Ids();
+  for (const value of values) ids.add(value);
+  ids.buildIndex();
+  return ids;
+}
+
+describe("Ids sorted entries", () => {
+  it.each([
+    { name: "empty", values: [], entries: [] },
+    {
+      name: "ascending",
+      values: [1, 2, 3],
+      entries: [
+        [1, 0],
+        [2, 1],
+        [3, 2],
+      ],
+    },
+    {
+      name: "reverse",
+      values: [3, 2, 1],
+      entries: [
+        [1, 2],
+        [2, 1],
+        [3, 0],
+      ],
+    },
+    {
+      name: "sparse",
+      values: [100, 2, 50],
+      entries: [
+        [2, 1],
+        [50, 2],
+        [100, 0],
+      ],
+    },
+    {
+      name: "duplicates",
+      values: [5, 2, 5, 2],
+      entries: [
+        [2, 1],
+        [2, 3],
+        [5, 0],
+        [5, 2],
+      ],
+    },
+  ])("preserves sorted ID and original-position order for $name IDs", ({ values, entries }) => {
+    expect(Array.from(buildIds(values).sortedEntries())).toEqual(entries);
+  });
+
+  it("preserves sorted entries through transfer reconstruction", () => {
+    const source = buildIds([9, 3, 9, 1]);
+    const reconstructed = new Ids(source.transferables());
+
+    expect(Array.from(reconstructed.sortedEntries())).toEqual([
+      [1, 3],
+      [3, 1],
+      [9, 0],
+      [9, 2],
+    ]);
+  });
+
+  it("orders negative IDs canonically for OSM serialization", () => {
+    expect(Array.from(buildIds([3, -3, -1, 2, -2, 1, -2]).osmSortedEntries())).toEqual([
+      [-1, 2],
+      [-2, 4],
+      [-2, 6],
+      [-3, 1],
+      [1, 5],
+      [2, 3],
+      [3, 0],
+    ]);
+  });
+
+  it("omits redundant sorted buffers for ascending IDs", () => {
+    const transferables = buildIds([1, 2, 3]).transferables();
+
+    expect(transferables.idsAreSorted).toBe(true);
+    expect(transferables.sortedIds).toBeUndefined();
+    expect(transferables.sortedIdPositionToIndex).toBeUndefined();
+    expect(Ids.getBytesRequired(3)).toBe(
+      3 * Float64Array.BYTES_PER_ELEMENT + Float64Array.BYTES_PER_ELEMENT,
+    );
+    expect(Array.from(new Ids(transferables).sortedEntries())).toEqual([
+      [1, 0],
+      [2, 1],
+      [3, 2],
+    ]);
+  });
+
+  it("retains derived lookup buffers for unsorted IDs", () => {
+    const transferables = buildIds([3, 1, 2]).transferables();
+
+    expect(transferables.idsAreSorted).toBe(false);
+    expect(transferables.sortedIds?.byteLength).toBe(3 * Float64Array.BYTES_PER_ELEMENT);
+    expect(transferables.sortedIdPositionToIndex?.byteLength).toBe(
+      3 * Uint32Array.BYTES_PER_ELEMENT,
+    );
+  });
+
+  it("streams sorted entities without looking up each ID again", () => {
+    const osm = new Osm();
+    osm.nodes.addNode({ id: 2, lon: 20, lat: 20 });
+    osm.nodes.addNode({ id: 1, lon: 10, lat: 10 });
+    osm.nodes.addNode({ id: 1, lon: 11, lat: 11 });
+    osm.buildIndexes();
+    const getIndexFromId = vi.spyOn(osm.nodes.ids, "getIndexFromId");
+
+    expect([...osm.nodes.sorted()].map((node) => [node.id, node.lon])).toEqual([
+      [1, 10],
+      [1, 11],
+      [2, 20],
+    ]);
+    expect(getIndexFromId).not.toHaveBeenCalled();
+  });
+});

package/test/limits.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  MAX_RELATION_MEMBERS,
+  MAX_STRING_BYTES,
+  MAX_UINT32_OFFSET,
+  MAX_WAY_REFS,
+  Osm,
+  OsmCapacityError,
+  Relations,
+  Tags,
+  assertCapacity,
+} from "../src";
+import StringTable from "../src/stringtable.ts";
+
+describe("storage capacity limits", () => {
+  it("stores a way with exactly MAX_WAY_REFS refs", () => {
+    const osm = new Osm({ id: "max-way" });
+    const refs = Array.from({ length: MAX_WAY_REFS }, (_, i) => i + 1);
+    osm.ways.addWay({ id: 1, refs });
+    osm.buildIndexes();
+    expect(osm.ways.getById(1)?.refs).toHaveLength(MAX_WAY_REFS);
+  });
+
+  it("rejects a way with more than MAX_WAY_REFS refs instead of wrapping", () => {
+    const osm = new Osm({ id: "long-way" });
+    const refs = Array.from({ length: MAX_WAY_REFS + 1 }, (_, i) => i + 1);
+    const add = () => osm.ways.addWay({ id: 7, refs });
+    expect(add).toThrow(OsmCapacityError);
+    expect(add).toThrow("Way 7 has 65,536 node refs; Osmix stores at most 65,535.");
+    expect(osm.ways.size).toBe(0);
+  });
+
+  it("rejects a relation with more than MAX_RELATION_MEMBERS members", () => {
+    const osm = new Osm({ id: "big-relation" });
+    const members = Array.from({ length: MAX_RELATION_MEMBERS + 1 }, (_, i) => ({
+      type: "node" as const,
+      ref: i + 1,
+    }));
+    try {
+      osm.relations.addRelation({ id: 9, members });
+      expect.unreachable();
+    } catch (error) {
+      expect(error).toBeInstanceOf(OsmCapacityError);
+      expect(error).toMatchObject({
+        code: "OSM_CAPACITY_EXCEEDED",
+        limit: "relation-members",
+        value: MAX_RELATION_MEMBERS + 1,
+        max: MAX_RELATION_MEMBERS,
+      });
+    }
+    expect(osm.relations.size).toBe(0);
+  });
+
+  it("rejects a string longer than MAX_STRING_BYTES UTF-8 bytes", () => {
+    const table = new StringTable();
+    const fits = "a".repeat(MAX_STRING_BYTES);
+    expect(table.get(table.add(fits))).toBe(fits);
+    // "é" is two UTF-8 bytes, so this string is short in characters but too long in bytes.
+    const tooLong = "é".repeat((MAX_STRING_BYTES + 1) / 2);
+    expect(() => table.add(tooLong)).toThrow(OsmCapacityError);
+    expect(() => table.add(tooLong)).toThrow(/65,536 UTF-8 bytes/);
+  });
+
+  it("reports dataset-wide offset overflow", () => {
+    expect(() =>
+      assertCapacity("total-way-refs", MAX_UINT32_OFFSET + 1, MAX_UINT32_OFFSET, () => "Data"),
+    ).toThrow("Data has 4,294,967,296 node refs; Osmix stores at most 4,294,967,295.");
+    expect(() =>
+      assertCapacity("total-way-refs", MAX_UINT32_OFFSET, MAX_UINT32_OFFSET, () => "Data"),
+    ).not.toThrow();
+  });
+});
+
+describe("byte estimators", () => {
+  it("counts tag pairs at 12 bytes each", () => {
+    expect(Tags.getBytesRequired(10, 10, 5) - Tags.getBytesRequired(10, 10)).toBe(60);
+  });
+
+  it("counts relation members at 13 bytes each", () => {
+    expect(Relations.getBytesRequired(1, 4) - Relations.getBytesRequired(1)).toBe(52);
+  });
+});

package/test/memory.test.ts

@@ -1,38 +1,37 @@
-import { describe, expect, it } from "bun:test"
-import { Nodes, Relations, Ways } from "../src"
+import { describe, expect, it } from "vitest";
+
+import { Nodes, Relations, Ways } from "../src";
 
 export function getOsmCoreMemoryRequirements(
-	nodeCount: number,
-	wayCount: number,
-	relationCount: number,
+  nodeCount: number,
+  wayCount: number,
+  relationCount: number,
 ) {
-	const nodesBytes = Nodes.getBytesRequired(nodeCount)
-	const waysBytes = Ways.getBytesRequired(wayCount)
-	const relationsBytes = Relations.getBytesRequired(relationCount)
+  const nodesBytes = Nodes.getBytesRequired(nodeCount);
+  const waysBytes = Ways.getBytesRequired(wayCount);
+  const relationsBytes = Relations.getBytesRequired(relationCount);
 
-	return {
-		nodes: nodesBytes,
-		ways: waysBytes,
-		relations: relationsBytes,
-		total: nodesBytes + waysBytes + relationsBytes,
-	}
+  return {
+    nodes: nodesBytes,
+    ways: waysBytes,
+    relations: relationsBytes,
+    total: nodesBytes + waysBytes + relationsBytes,
+  };
 }
 
 describe("Memory Requirements", () => {
-	it("computes memory requirements for small datasets", () => {
-		const breakdown = getOsmCoreMemoryRequirements(10, 2, 1)
-		expect(breakdown.nodes).toBeGreaterThan(0)
-		expect(breakdown.ways).toBeGreaterThan(0)
-		expect(breakdown.relations).toBeGreaterThan(0)
-		expect(breakdown.total).toBe(
-			breakdown.nodes + breakdown.ways + breakdown.relations,
-		)
-	})
+  it("computes memory requirements for small datasets", () => {
+    const breakdown = getOsmCoreMemoryRequirements(10, 2, 1);
+    expect(breakdown.nodes).toBeGreaterThan(0);
+    expect(breakdown.ways).toBeGreaterThan(0);
+    expect(breakdown.relations).toBeGreaterThan(0);
+    expect(breakdown.total).toBe(breakdown.nodes + breakdown.ways + breakdown.relations);
+  });
 
-	it("computes memory requirements for large datasets", () => {
-		const breakdown = getOsmCoreMemoryRequirements(70000, 20000, 0)
-		expect(breakdown.nodes).toBeGreaterThan(0)
-		expect(breakdown.ways).toBeGreaterThan(0)
-		expect(breakdown.total).toBe(breakdown.nodes + breakdown.ways)
-	})
-})
+  it("computes memory requirements for large datasets", () => {
+    const breakdown = getOsmCoreMemoryRequirements(70000, 20000, 0);
+    expect(breakdown.nodes).toBeGreaterThan(0);
+    expect(breakdown.ways).toBeGreaterThan(0);
+    expect(breakdown.total).toBe(breakdown.nodes + breakdown.ways);
+  });
+});

package/test/no-shared-array-buffer.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+describe("without SharedArrayBuffer", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.resetModules();
+  });
+
+  it("builds indexes and manages ArrayBuffer-backed typed arrays", async () => {
+    vi.stubGlobal("SharedArrayBuffer", undefined);
+    vi.resetModules();
+
+    const { BufferConstructor, ResizeableTypedArray } = await import("../src/typed-arrays.ts");
+    const { Osm } = await import("../src/osm.ts");
+
+    expect(BufferConstructor).toBe(ArrayBuffer);
+
+    const osm = new Osm({ id: "array-buffer-only" });
+    osm.nodes.addNode({ id: 1, lon: 115.2167, lat: -8.65, tags: { place: "city" } });
+    osm.nodes.addNode({ id: 2, lon: 115.22, lat: -8.66 });
+    osm.ways.addWay({ id: 1, refs: [1, 2], tags: { highway: "residential" } });
+    osm.buildIndexes();
+
+    expect(osm.isReady()).toBe(true);
+    expect(osm.nodes.getById(1)?.tags?.["place"]).toBe("city");
+
+    const restored = ResizeableTypedArray.from(Uint8Array, new ArrayBuffer(4));
+    restored.push(9);
+    expect(restored.buffer).toBeInstanceOf(ArrayBuffer);
+
+    const growing = new ResizeableTypedArray(Uint8Array);
+    growing.pushMany(new Uint8Array(growing.capacity));
+    growing.push(7);
+    expect(growing.buffer).toBeInstanceOf(ArrayBuffer);
+    expect(growing.at(-1)).toBe(7);
+
+    const compacted = growing.compact();
+    expect(compacted.buffer).toBeInstanceOf(ArrayBuffer);
+    expect(compacted.length).toBe(growing.length);
+  });
+});

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();
+  });
+});