@osmix/core 0.2.0 → 0.3.0

package/src/ways.ts

@@ -4,24 +4,32 @@ import type { GeoBbox2D, LonLat, OsmTags, OsmWay } from "@osmix/types";
 import Flatbush from "flatbush";
 import { around as geoAround } from "geoflatbush";
 
-import { Entities, type EntitiesTransferables } from "./entities.ts";
+import { Entities, type EntitiesTransferables, isValidSpatialBbox } from "./entities.ts";
 import { type IdOrIndex, Ids } from "./ids.ts";
+import { MAX_UINT32_OFFSET, MAX_WAY_REFS, assertCapacity } from "./limits.ts";
 import type { Nodes } from "./nodes.ts";
 import type StringTable from "./stringtable.ts";
 import { Tags } from "./tags.ts";
-import {
-  BufferConstructor,
-  type BufferType,
-  IdArrayType,
-  ResizeableTypedArray as RTA,
-} from "./typed-arrays.ts";
+import { BufferConstructor, type BufferType, ResizeableTypedArray as RTA } from "./typed-arrays.ts";
+
+/**
+ * Node-index sentinel stored for way refs whose node is not present in the dataset.
+ * Returned by {@link Ways.getRefIndexes} in place of a node index.
+ */
+export const MISSING_NODE_INDEX = 0xffffffff;
+const HASH_REF_CHUNK_SIZE = 8192;
 
 export interface WaysTransferables<
   T extends BufferType = BufferType,
 > extends EntitiesTransferables<T> {
   refStart: T;
   refCount: T;
+  /** Node indexes, with `0xffffffff` marking an unresolved reference. */
   refs: T;
+  /** Sorted positions in `refs` whose node ID could not be resolved. */
+  missingRefPositions: T;
+  /** OSM node IDs parallel to `missingRefPositions`. */
+  missingRefIds: T;
   bbox: T;
   /** Optional - can be rebuilt via buildSpatialIndex() */
   spatialIndex?: T;
@@ -33,10 +41,15 @@ export class Ways extends Entities<OsmWay> {
   private spatialIndexBuilt = false;
 
   private refStart: RTA<Uint32Array>;
-  private refCount: RTA<Uint16Array>; // Maximum 2,000 nodes per way
+  private refCount: RTA<Uint16Array>; // Maximum MAX_WAY_REFS (65,535) nodes per way
+
+  // Node indexes. Missing node IDs are preserved in sparse parallel arrays.
+  private refs: RTA<Uint32Array>;
+  private missingRefPositions: RTA<Uint32Array>;
+  private missingRefIds: RTA<Float64Array>;
 
-  // Node IDs
-  private refs: RTA<Float64Array>;
+  // Temporary OSM node IDs used when nodes are not indexed during ingestion.
+  private pendingRefIds: RTA<Float64Array> | null;
 
   // Bounding box of the way in geographic coordinates
   private bbox: RTA<Float64Array>;
@@ -44,12 +57,24 @@ export class Ways extends Entities<OsmWay> {
   // Node reference index
   private nodes: Nodes;
 
-  private getNodeLonLat(id: number): [number, number] {
-    const coordinate = this.nodes.getNodeLonLat({ id });
-    if (!coordinate) throw Error(`Node ${id} not found for way geometry`);
+  private getNodeLonLat(refPosition: number): [number, number] {
+    const coordinate = this.tryGetNodeLonLat(refPosition);
+    if (!coordinate) {
+      throw Error(`Node ${this.getMissingRefId(refPosition)} not found for way geometry`);
+    }
     return coordinate;
   }
 
+  /** Resolve a reference position to coordinates, or null when the node is absent. */
+  private tryGetNodeLonLat(refPosition: number): [number, number] | null {
+    const nodeIndex = this.refs.at(refPosition);
+    if (nodeIndex !== MISSING_NODE_INDEX) {
+      return this.nodes.getNodeLonLat({ index: nodeIndex });
+    }
+    // A missing ref may still resolve if the node was added after finalization.
+    return this.nodes.getNodeLonLat({ id: this.getMissingRefId(refPosition) });
+  }
+
   /**
    * Create a new Ways index.
    */
@@ -58,7 +83,10 @@ export class Ways extends Entities<OsmWay> {
       super("way", new Ids(transferables), new Tags(stringTable, transferables));
       this.refStart = RTA.from(Uint32Array, transferables.refStart);
       this.refCount = RTA.from(Uint16Array, transferables.refCount);
-      this.refs = RTA.from(IdArrayType, transferables.refs);
+      this.refs = RTA.from(Uint32Array, transferables.refs);
+      this.missingRefPositions = RTA.from(Uint32Array, transferables.missingRefPositions);
+      this.missingRefIds = RTA.from(Float64Array, transferables.missingRefIds);
+      this.pendingRefIds = null;
       this.bbox = RTA.from(Float64Array, transferables.bbox);
       // Only load spatial index if provided (not stored in IndexedDB)
       if (transferables.spatialIndex?.byteLength) {
@@ -70,7 +98,10 @@ export class Ways extends Entities<OsmWay> {
       super("way", new Ids(), new Tags(stringTable));
       this.refStart = new RTA(Uint32Array);
       this.refCount = new RTA(Uint16Array);
-      this.refs = new RTA(IdArrayType);
+      this.refs = new RTA(Uint32Array);
+      this.missingRefPositions = new RTA(Uint32Array);
+      this.missingRefIds = new RTA(Float64Array);
+      this.pendingRefIds = new RTA(Float64Array);
       this.bbox = new RTA(Float64Array);
     }
     this.nodes = nodes;
@@ -80,10 +111,11 @@ export class Ways extends Entities<OsmWay> {
    * Add a single way to the index.
    */
   addWay(way: OsmWay) {
+    this.assertRefCapacity(way.id, way.refs.length);
     const wayIndex = this.addEntity(way.id, way.tags ?? {});
-    this.refStart.push(this.refs.length);
+    this.refStart.push(this.refLength);
     this.refCount.push(way.refs.length);
-    for (const ref of way.refs) this.refs.push(ref);
+    this.appendRefIds(way.refs);
     return wayIndex;
   }
 
@@ -94,6 +126,7 @@ export class Ways extends Entities<OsmWay> {
     ways: OsmPbfWay[],
     blockStringIndexMap: Uint32Array,
     filter?: (way: OsmWay) => OsmWay | null,
+    nodeIdToIndex?: (nodeId: number) => number,
   ) {
     let added = 0;
     for (const way of ways) {
@@ -121,10 +154,12 @@ export class Ways extends Entities<OsmWay> {
         : null;
       if (filter && filteredWay === null) continue;
 
+      const addedRefs = filteredWay?.refs ?? refs;
+      this.assertRefCapacity(way.id, addedRefs.length);
       this.addEntity(way.id, tagKeys, tagValues);
-      this.refStart.push(this.refs.length);
-      this.refCount.push(filteredWay?.refs.length ?? refs.length);
-      this.refs.pushMany(filteredWay?.refs ?? refs);
+      this.refStart.push(this.refLength);
+      this.refCount.push(addedRefs.length);
+      this.appendRefIds(addedRefs, nodeIdToIndex);
       added++;
     }
     return added;
@@ -132,20 +167,52 @@ export class Ways extends Entities<OsmWay> {
 
   /**
    * Compact the internal arrays to free up memory.
+   *
+   * Must run after the node ID index is built (`Osm.buildIndexes()` orders
+   * nodes before ways) so pending OSM node IDs resolve to compact `Uint32`
+   * node indexes. If the node index is not ready, every pending ref degrades
+   * to the larger missing-ref representation (sentinel + sorted ID lookup).
    */
   buildEntityIndex() {
     this.refStart.compact();
     this.refCount.compact();
+    if (this.pendingRefIds && this.pendingRefIds.length > 0) {
+      if (this.refs.length > 0) throw Error("Mixed pending and indexed way references.");
+      const refsBuffer = new BufferConstructor(
+        this.pendingRefIds.length * Uint32Array.BYTES_PER_ELEMENT,
+      );
+      this.refs = RTA.from(Uint32Array, refsBuffer);
+      const canResolveNodes = this.nodes.ids.isReady();
+      if (!canResolveNodes) {
+        console.warn(
+          "Ways.buildEntityIndex ran before the node index was ready; all way references will use the missing-ref representation.",
+        );
+      }
+      for (let i = 0; i < this.pendingRefIds.length; i++) {
+        const refId = this.pendingRefIds.at(i);
+        const nodeIndex = canResolveNodes ? this.nodes.ids.getIndexFromId(refId) : -1;
+        this.setIndexedRef(i, refId, nodeIndex);
+      }
+    }
+    this.pendingRefIds = null;
     this.refs.compact();
+    this.missingRefPositions.compact();
+    this.missingRefIds.compact();
   }
 
   /**
    * Build the spatial index for ways.
    * If bbox data already exists (e.g., loaded from storage), reuses it.
+   * Returns the existing index when it is already built.
    */
   buildSpatialIndex() {
     if (!this.nodes.isReady()) throw Error("Node index is not ready.");
-    if (this.size === 0) return this.spatialIndex;
+    if (this.spatialIndexBuilt) return this.spatialIndex;
+    if (this.size === 0) {
+      this.spatialIndex = new Flatbush(1, 128, Float64Array, BufferConstructor);
+      this.spatialIndexBuilt = true;
+      return this.spatialIndex;
+    }
 
     this.spatialIndex = new Flatbush(this.size, 128, Float64Array, BufferConstructor);
 
@@ -164,7 +231,9 @@ export class Ways extends Entities<OsmWay> {
         maxX = this.bbox.at(i * 4 + 2);
         maxY = this.bbox.at(i * 4 + 3);
       } else {
-        // Calculate bbox from node coordinates
+        // Calculate bbox from resolvable node coordinates. Missing refs are
+        // preserved losslessly in storage but contribute no geometry; a way
+        // with no resolvable refs keeps an inverted bbox that never matches.
         minX = Number.POSITIVE_INFINITY;
         minY = Number.POSITIVE_INFINITY;
         maxX = Number.NEGATIVE_INFINITY;
@@ -172,8 +241,9 @@ export class Ways extends Entities<OsmWay> {
         const start = this.refStart.at(i);
         const count = this.refCount.at(i);
         for (let j = start; j < start + count; j++) {
-          const refId = this.refs.at(j);
-          const [lon, lat] = this.getNodeLonLat(refId);
+          const coordinate = this.tryGetNodeLonLat(j);
+          if (!coordinate) continue;
+          const [lon, lat] = coordinate;
           if (lon < minX) minX = lon;
           if (lon > maxX) maxX = lon;
           if (lat < minY) minY = lat;
@@ -219,7 +289,21 @@ export class Ways extends Entities<OsmWay> {
   getRefIds(index: number): number[] {
     const start = this.refStart.at(index);
     const count = this.refCount.at(index);
-    return Array.from(this.refs.slice(start, start + count));
+    const refs = Array.from<number>({ length: count });
+    for (let i = 0; i < count; i++) refs[i] = this.getRefId(start + i);
+    return refs;
+  }
+
+  /**
+   * Get the node indexes referenced by a way without allocating.
+   *
+   * Returns a view into internal storage; do not mutate it or hold it across writes. Refs to
+   * nodes absent from the dataset are {@link MISSING_NODE_INDEX}. Requires `buildEntityIndex()`.
+   */
+  getRefIndexes(index: number): Uint32Array {
+    if (this.pendingRefIds !== null) throw Error("Way index is not built.");
+    const start = this.refStart.at(index);
+    return this.refs.array.subarray(start, start + this.refCount.at(index));
   }
 
   /**
@@ -243,8 +327,7 @@ export class Ways extends Entities<OsmWay> {
     const start = this.refStart.at(index);
     const line = new Float64Array(count * 2);
     for (let i = 0; i < count; i++) {
-      const ref = this.refs.at(start + i);
-      const [lon, lat] = this.getNodeLonLat(ref);
+      const [lon, lat] = this.getNodeLonLat(start + i);
       line[i * 2] = lon;
       line[i * 2 + 1] = lat;
     }
@@ -253,14 +336,31 @@ export class Ways extends Entities<OsmWay> {
 
   /**
    * Get the coordinates of a way as an array of [lon, lat] pairs.
+   * Throws when a referenced node cannot be resolved; use
+   * `getResolvedCoordinates()` for tolerant consumers such as bbox building.
    */
   getCoordinates(index: number): LonLat[] {
     const count = this.refCount.at(index);
     const start = this.refStart.at(index);
     const coords: [number, number][] = [];
     for (let refIndex = start; refIndex < start + count; refIndex++) {
-      const ref = this.refs.at(refIndex);
-      coords.push(this.getNodeLonLat(ref));
+      coords.push(this.getNodeLonLat(refIndex));
+    }
+    return coords;
+  }
+
+  /**
+   * Get the resolvable coordinates of a way, skipping missing node refs.
+   * Preferred over `getCoordinates()` when partial geometry is acceptable,
+   * e.g. computing bounding boxes over referentially incomplete extracts.
+   */
+  getResolvedCoordinates(index: number): LonLat[] {
+    const count = this.refCount.at(index);
+    const start = this.refStart.at(index);
+    const coords: [number, number][] = [];
+    for (let refIndex = start; refIndex < start + count; refIndex++) {
+      const coordinate = this.tryGetNodeLonLat(refIndex);
+      if (coordinate) coords.push(coordinate);
     }
     return coords;
   }
@@ -270,7 +370,13 @@ export class Ways extends Entities<OsmWay> {
    */
   intersects(bbox: GeoBbox2D, filterFn?: (index: number) => boolean): number[] {
     if (this.size === 0) return [];
-    return this.spatialIndex.search(bbox[0], bbox[1], bbox[2], bbox[3], filterFn);
+    // A way with no resolvable refs stores an inverted bbox. Flatbush's
+    // contained-node fast path skips per-leaf intersection tests, so filter
+    // inverted boxes out explicitly.
+    return this.spatialIndex.search(bbox[0], bbox[1], bbox[2], bbox[3], (index, x0, y0, x1, y1) => {
+      if (!isValidSpatialBbox(x0, y0, x1, y1)) return false;
+      return filterFn ? filterFn(index) : true;
+    });
   }
 
   /**
@@ -284,7 +390,15 @@ export class Ways extends Entities<OsmWay> {
   neighbors(lon: number, lat: number, maxResults?: number, maxDistanceKm?: number): number[] {
     if (this.size === 0) return [];
     // Use geoflatbush for proper geographic distance calculations
-    return geoAround(this.spatialIndex, lon, lat, maxResults, maxDistanceKm);
+    return geoAround(this.spatialIndex, lon, lat, maxResults, maxDistanceKm, (index) => {
+      const offset = index * 4;
+      return isValidSpatialBbox(
+        this.bbox.at(offset),
+        this.bbox.at(offset + 1),
+        this.bbox.at(offset + 2),
+        this.bbox.at(offset + 3),
+      );
+    });
   }
 
   /**
@@ -338,6 +452,8 @@ export class Ways extends Entities<OsmWay> {
       refStart: this.refStart.array.buffer,
       refCount: this.refCount.array.buffer,
       refs: this.refs.array.buffer,
+      missingRefPositions: this.missingRefPositions.array.buffer,
+      missingRefIds: this.missingRefIds.array.buffer,
       bbox: this.bbox.array.buffer,
     };
     // Only include spatial index if it was built
@@ -350,7 +466,7 @@ export class Ways extends Entities<OsmWay> {
   /**
    * Get the approximate memory requirements for a given number of ways in bytes.
    */
-  static getBytesRequired(count: number) {
+  static getBytesRequired(count: number, refCount = 0, missingRefCount = 0, tagCount = 0) {
     if (count === 0) return 0;
     // Approximate nodes per way
     let numNodes = count;
@@ -365,9 +481,11 @@ export class Ways extends Entities<OsmWay> {
 
     return (
       Ids.getBytesRequired(count) +
-      Tags.getBytesRequired(count) +
+      Tags.getBytesRequired(count, count, tagCount) +
       count * Uint32Array.BYTES_PER_ELEMENT + // refStart
       count * Uint16Array.BYTES_PER_ELEMENT + // refCount
+      refCount * Uint32Array.BYTES_PER_ELEMENT + // node indexes
+      missingRefCount * (Uint32Array.BYTES_PER_ELEMENT + Float64Array.BYTES_PER_ELEMENT) + // missing refs
       count * 4 * Float64Array.BYTES_PER_ELEMENT + // bbox
       spatialIndexBytes
     );
@@ -377,10 +495,87 @@ export class Ways extends Entities<OsmWay> {
    * Update a ContentHasher with way-specific data (node references).
    */
   override updateHash(hasher: ContentHasher): ContentHasher {
-    return super
-      .updateHash(hasher)
-      .update(this.refStart.array)
-      .update(this.refCount.array)
-      .update(this.refs.array);
+    super.updateHash(hasher).update(this.refCount.array);
+    const chunk = new Float64Array(Math.min(HASH_REF_CHUNK_SIZE, this.refs.length));
+    let chunkLength = 0;
+    for (let i = 0; i < this.refs.length; i++) {
+      chunk[chunkLength++] = this.getRefId(i);
+      if (chunkLength === chunk.length) {
+        hasher.update(chunk);
+        chunkLength = 0;
+      }
+    }
+    if (chunkLength > 0) hasher.update(chunk.subarray(0, chunkLength));
+    return hasher;
+  }
+
+  /** Logical reference length during either pending-ID or indexed ingestion. */
+  /** Reject a way whose ref count would wrap `refCount` or the `refStart` offsets. */
+  private assertRefCapacity(wayId: number, refCount: number) {
+    assertCapacity("way-refs", refCount, MAX_WAY_REFS, () => `Way ${wayId}`);
+    assertCapacity(
+      "total-way-refs",
+      this.refLength + refCount,
+      MAX_UINT32_OFFSET,
+      () => `The dataset (at way ${wayId})`,
+    );
+  }
+
+  private get refLength(): number {
+    return this.pendingRefIds?.length ?? this.refs.length;
+  }
+
+  /** Append OSM node IDs, optionally resolving them directly to node indexes. */
+  private appendRefIds(refIds: number[], nodeIdToIndex?: (nodeId: number) => number) {
+    if (nodeIdToIndex) {
+      if ((this.pendingRefIds?.length ?? 0) > 0) {
+        throw Error("Cannot mix unresolved and directly indexed way references.");
+      }
+      this.pendingRefIds = null;
+      for (const refId of refIds) {
+        this.setIndexedRef(this.refs.length, refId, nodeIdToIndex(refId));
+      }
+      return;
+    }
+    if (!this.pendingRefIds) {
+      throw Error("Directly indexed way references require a node ID resolver.");
+    }
+    this.pendingRefIds.pushMany(refIds);
+  }
+
+  /** Store one resolved or losslessly preserved missing reference. */
+  private setIndexedRef(position: number, refId: number, nodeIndex: number) {
+    if (nodeIndex < 0) {
+      this.refs.set(position, MISSING_NODE_INDEX);
+      this.missingRefPositions.push(position);
+      this.missingRefIds.push(refId);
+      return;
+    }
+    if (!Number.isInteger(nodeIndex) || nodeIndex >= MISSING_NODE_INDEX) {
+      throw Error(`Invalid node index ${nodeIndex} for reference ${refId}`);
+    }
+    this.refs.set(position, nodeIndex);
+  }
+
+  /** Reconstruct the public OSM node ID for one internal reference position. */
+  private getRefId(position: number): number {
+    const nodeIndex = this.refs.at(position);
+    return nodeIndex === MISSING_NODE_INDEX
+      ? this.getMissingRefId(position)
+      : this.nodes.ids.at(nodeIndex);
+  }
+
+  /** Find the OSM node ID for a sentinel reference position. */
+  private getMissingRefId(position: number): number {
+    let low = 0;
+    let high = this.missingRefPositions.length - 1;
+    while (low <= high) {
+      const middle = (low + high) >>> 1;
+      const candidate = this.missingRefPositions.at(middle);
+      if (candidate === position) return this.missingRefIds.at(middle);
+      if (candidate < position) low = middle + 1;
+      else high = middle - 1;
+    }
+    throw Error(`Missing node ID not found for way reference position ${position}`);
   }
 }

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

@@ -1,4 +1,4 @@
-import { bench, describe } from "vitest";
+import { describe, test } from "vitest";
 
 import { Ids } from "../src/ids";
 import { Osm } from "../src/osm";
@@ -17,13 +17,17 @@ for (const value of values) osm.nodes.addNode({ id: value, lon: value, lat: valu
 osm.buildIndexes();
 
 describe("sorted ID iteration", () => {
-  bench("build shuffled sorted index", () => {
-    buildIds();
+  test("build shuffled sorted index", async ({ bench }) => {
+    await bench("build shuffled sorted index", () => {
+      buildIds();
+    }).run();
   });
 
-  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");
+  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

@@ -66,6 +66,44 @@ describe("Ids sorted entries", () => {
     ]);
   });
 
+  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 });

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