@osmix/core 0.1.10 → 0.3.0

package/src/ids.ts

@@ -7,40 +7,37 @@
  * @module
  */
 
-import { assertValue } from "@osmix/shared/assert"
-import type { ContentHasher } from "@osmix/shared/content-hasher"
-import {
-	BufferConstructor,
-	type BufferType,
-	ResizeableTypedArray as RTA,
-} from "./typed-arrays.ts"
+import { assertValue } from "@osmix/shared/assert";
+import type { ContentHasher } from "@osmix/shared/content-hasher";
+
+import { BufferConstructor, type BufferType, ResizeableTypedArray as RTA } from "./typed-arrays.ts";
 
 /**
  * Union type for looking up entities by either OSM ID or internal array index.
  */
-export type IdOrIndex = { id: number } | { index: number }
+export type IdOrIndex = { id: number } | { index: number };
 
 /**
  * Number of IDs per anchor block for the two-level binary search.
  * Smaller values increase anchor array size but speed up block-level search;
  * larger values reduce anchor overhead but slow the final search.
  */
-const BLOCK_SIZE = 256
+const BLOCK_SIZE = 256;
 
 /**
  * Serializable state for worker transfer.
  */
 export interface IdsTransferables<T extends BufferType = BufferType> {
-	/** Entity IDs in insertion order. */
-	ids: T
-	/** Sorted IDs for binary search (aliases `ids` if already sorted). */
-	sortedIds: T
-	/** Maps sorted position → original insertion index. */
-	sortedIdPositionToIndex: T
-	/** Anchor array: every BLOCK_SIZE-th sorted ID. */
-	anchors: T
-	/** True if IDs were inserted in ascending order. */
-	idsAreSorted: boolean
+  /** Entity IDs in insertion order. */
+  ids: T;
+  /** Sorted IDs for binary search. Omitted when `idsAreSorted` is true. */
+  sortedIds?: T;
+  /** Maps sorted position → original insertion index. Omitted for sorted IDs. */
+  sortedIdPositionToIndex?: T;
+  /** Anchor array: every BLOCK_SIZE-th sorted ID. */
+  anchors: T;
+  /** True if IDs were inserted in ascending order. */
+  idsAreSorted: boolean;
 }
 
 /**
@@ -50,241 +47,287 @@ export interface IdsTransferables<T extends BufferType = BufferType> {
  * Max capacity: ~2^32 entities.
  */
 export class Ids {
-	/** All IDs in insertion order */
-	private ids: RTA<Float64Array>
-	/** Whether buildIndex() has been called */
-	private indexBuilt = false
-	/** True if IDs were added in ascending order (allows index optimization) */
-	private idsAreSorted = true
-	/** Sorted view of IDs for binary search */
-	private idsSorted: Float64Array
-	/** Maps position in sorted array → original insertion index */
-	private sortedIdPositionToIndex: Uint32Array
-	/** Anchor array for two-level binary search: every BLOCK_SIZE-th sorted ID */
-	private anchors: Float64Array
+  /** All IDs in insertion order */
+  private ids: RTA<Float64Array>;
+  /** Whether buildIndex() has been called */
+  private indexBuilt = false;
+  /** True if IDs were added in ascending order (allows index optimization) */
+  private idsAreSorted = true;
+  /** Sorted view of IDs for binary search */
+  private idsSorted: Float64Array;
+  /** Maps position in sorted array → original insertion index */
+  private sortedIdPositionToIndex: Uint32Array;
+  /** Anchor array for two-level binary search: every BLOCK_SIZE-th sorted ID */
+  private anchors: Float64Array;
+
+  /**
+   * Create a new Ids index.
+   * @param transferables - Optional serialized state to reconstruct from.
+   */
+  constructor(transferables?: IdsTransferables) {
+    if (transferables) {
+      this.ids = RTA.from(Float64Array, transferables.ids);
+      if (transferables.idsAreSorted) {
+        this.idsSorted = this.ids.array;
+        this.sortedIdPositionToIndex = new Uint32Array(new BufferConstructor(0));
+      } else {
+        if (!transferables.sortedIds || !transferables.sortedIdPositionToIndex) {
+          throw Error("Unsorted IDs require sorted lookup buffers.");
+        }
+        this.idsSorted = new Float64Array(transferables.sortedIds);
+        this.sortedIdPositionToIndex = new Uint32Array(transferables.sortedIdPositionToIndex);
+      }
+      this.anchors = new Float64Array(transferables.anchors);
+      this.idsAreSorted = transferables.idsAreSorted;
+      this.indexBuilt = true;
+    } else {
+      this.ids = new RTA(Float64Array);
+      this.idsSorted = new Float64Array(new BufferConstructor(0));
+      this.sortedIdPositionToIndex = new Uint32Array(new BufferConstructor(0));
+      this.anchors = new Float64Array(new BufferConstructor(0));
+    }
+  }
+
+  /** Number of IDs stored in this index. */
+  get size() {
+    return this.ids.length;
+  }
+
+  /** Returns true if buildIndex() has been called and lookups are enabled. */
+  isReady() {
+    return this.indexBuilt;
+  }
+
+  /** Returns true if IDs were inserted in ascending order. */
+  isSorted() {
+    return this.idsAreSorted;
+  }
 
-	/**
-	 * Create a new Ids index.
-	 * @param transferables - Optional serialized state to reconstruct from.
-	 */
-	constructor(transferables?: IdsTransferables) {
-		if (transferables) {
-			this.ids = RTA.from(Float64Array, transferables.ids)
-			this.idsSorted = new Float64Array(transferables.sortedIds)
-			this.sortedIdPositionToIndex = new Uint32Array(
-				transferables.sortedIdPositionToIndex,
-			)
-			this.anchors = new Float64Array(transferables.anchors)
-			this.idsAreSorted = transferables.idsAreSorted
-			this.indexBuilt = true
-		} else {
-			this.ids = new RTA(Float64Array)
-			this.idsSorted = new Float64Array(new BufferConstructor(0))
-			this.sortedIdPositionToIndex = new Uint32Array(new BufferConstructor(0))
-			this.anchors = new Float64Array(new BufferConstructor(0))
-		}
-	}
+  /**
+   * Add an ID to the index.
+   * @param id - The OSM entity ID to add.
+   * @returns The internal array index where this ID was stored.
+   * @throws If the index has already been built.
+   */
+  add(id: number): number {
+    if (this.indexBuilt) throw Error("ID index already built.");
+    if (this.ids.length > 0 && id < this.ids.at(-1)) this.idsAreSorted = false;
+    return this.ids.push(id);
+  }
 
-	/** Number of IDs stored in this index. */
-	get size() {
-		return this.ids.length
-	}
+  /**
+   * Get the ID at a specific internal index.
+   * @param index - The internal array index.
+   * @returns The OSM entity ID at that index.
+   */
+  at(index: number): number {
+    return this.ids.at(index);
+  }
 
-	/** Returns true if buildIndex() has been called and lookups are enabled. */
-	isReady() {
-		return this.indexBuilt
-	}
+  /**
+   * Check if an ID exists in this index.
+   * @param id - The OSM entity ID to check.
+   * @returns True if the ID exists in this index.
+   */
+  has(id: number): boolean {
+    return this.getIndexFromId(id) !== -1;
+  }
 
-	/** Returns true if IDs were inserted in ascending order. */
-	isSorted() {
-		return this.idsAreSorted
-	}
+  /**
+   * Build the index of IDs to positions.
+   *
+   * If the IDs are not sorted, we need to sort them and build a new index.
+   * If the IDs are sorted, we can use the existing index.
+   */
+  buildIndex() {
+    if (this.indexBuilt) throw Error("ID index already built.");
+    this.ids.compact();
+    if (!this.idsAreSorted) {
+      // Build the sorted index
+      const idsBuffer = new BufferConstructor(this.size * Float64Array.BYTES_PER_ELEMENT);
+      const posBuffer = new BufferConstructor(this.size * Uint32Array.BYTES_PER_ELEMENT);
+      this.idsSorted = new Float64Array(idsBuffer);
+      this.sortedIdPositionToIndex = new Uint32Array(posBuffer);
 
-	/**
-	 * Add an ID to the index.
-	 * @param id - The OSM entity ID to add.
-	 * @returns The internal array index where this ID was stored.
-	 * @throws If the index has already been built.
-	 */
-	add(id: number): number {
-		if (this.indexBuilt) throw Error("ID index already built.")
-		if (this.ids.length > 0 && id < this.ids.at(-1)) this.idsAreSorted = false
-		return this.ids.push(id)
-	}
+      // Sort positions by ID, using the original position as a deterministic
+      // tie-breaker for duplicate IDs.
+      const sortedPositions = new Uint32Array(this.size);
+      for (let i = 0; i < this.size; i++) sortedPositions[i] = i;
+      sortedPositions.sort((a, b) => {
+        const idDifference = this.ids.array[a]! - this.ids.array[b]!;
+        return idDifference === 0 ? a - b : idDifference;
+      });
+      for (let i = 0; i < this.size; i++) {
+        const position = sortedPositions[i]!;
+        this.idsSorted[i] = this.ids.array[position]!;
+        this.sortedIdPositionToIndex[i] = position;
+      }
+    } else {
+      // Point to the same array
+      this.idsSorted = this.ids.array;
+      // Sorted position is already the insertion index; no identity map is needed.
+      this.sortedIdPositionToIndex = new Uint32Array(new BufferConstructor(0));
+    }
 
-	/**
-	 * Get the ID at a specific internal index.
-	 * @param index - The internal array index.
-	 * @returns The OSM entity ID at that index.
-	 */
-	at(index: number): number {
-		return this.ids.at(index)
-	}
+    // Build anchors (every blockSize-th key)
+    const aLen = Math.ceil(this.size / BLOCK_SIZE);
+    const sab = new BufferConstructor(aLen * Float64Array.BYTES_PER_ELEMENT);
+    this.anchors = new Float64Array(sab, 0, aLen);
+    for (let j = 0; j < aLen; j++) {
+      const id = this.idsSorted[Math.min(j * BLOCK_SIZE, this.size - 1)];
+      assertValue(id, "ID is undefined");
+      this.anchors[j] = id;
+    }
 
-	/**
-	 * Check if an ID exists in this index.
-	 * @param id - The OSM entity ID to check.
-	 * @returns True if the ID exists in this index.
-	 */
-	has(id: number): boolean {
-		return this.getIndexFromId(id) !== -1
-	}
+    this.indexBuilt = true;
+  }
 
-	/**
-	 * Build the index of IDs to positions.
-	 *
-	 * If the IDs are not sorted, we need to sort them and build a new index.
-	 * If the IDs are sorted, we can use the existing index.
-	 */
-	buildIndex() {
-		if (this.indexBuilt) throw Error("ID index already built.")
-		this.ids.compact()
-		if (!this.idsAreSorted) {
-			// Build the sorted index
-			const idsBuffer = new BufferConstructor(
-				this.size * Float64Array.BYTES_PER_ELEMENT,
-			)
-			const posBuffer = new BufferConstructor(
-				this.size * Uint32Array.BYTES_PER_ELEMENT,
-			)
-			this.idsSorted = new Float64Array(idsBuffer)
-			this.sortedIdPositionToIndex = new Uint32Array(posBuffer)
+  /**
+   * Look up the internal array index for an OSM entity ID.
+   *
+   * @param id - The OSM entity ID to look up.
+   * @returns The internal array index, or -1 if not found.
+   * @throws If the index has not been built.
+   */
+  getIndexFromId(id: number): number {
+    if (!this.indexBuilt) throw Error("IdIndex not built.");
 
-			// Fill and sort with positions.
-			for (let i = 0; i < this.size; i++) {
-				this.idsSorted[i] = this.ids.at(i)
-				this.sortedIdPositionToIndex[i] = i
-			}
+    // binary search anchors
+    let lo = 0;
+    let hi = this.anchors.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >>> 1;
+      const anchor = this.anchors[mid];
+      assertValue(anchor, "Anchor is undefined");
+      if (anchor <= id) lo = mid;
+      else hi = mid - 1;
+    }
+    const start = lo * BLOCK_SIZE;
+    const end = Math.min(start + BLOCK_SIZE, this.idsSorted.length);
 
-			// Sort by id, carrying position; use native sort on chunks or a custom radix/merge for stability.
-			// For simplicity:
-			const tmp: { id: number; pos: number }[] = Array.from(
-				{ length: this.size },
-				(_, i) => ({
-					id: this.idsSorted[i] as number,
-					pos: this.sortedIdPositionToIndex[i] as number,
-				}),
-			)
-			tmp.sort((a, b) => a.id - b.id)
-			tmp.forEach(({ id, pos }, i) => {
-				this.idsSorted[i] = id
-				this.sortedIdPositionToIndex[i] = pos
-			})
-		} else {
-			// Point to the same array
-			this.idsSorted = this.ids.array
-			// Create the sortedIdPositionToIndex array
-			const posBuffer = new BufferConstructor(
-				this.size * Uint32Array.BYTES_PER_ELEMENT,
-			)
-			this.sortedIdPositionToIndex = new Uint32Array(posBuffer)
-			for (let i = 0; i < this.size; i++) {
-				this.sortedIdPositionToIndex[i] = i
-			}
-		}
+    // binary search within block
+    let l = start;
+    let r = end - 1;
+    while (l <= r) {
+      const m = (l + r) >>> 1;
+      const v = this.idsSorted[m];
+      assertValue(v, "Value is undefined");
+      if (v === id) {
+        if (this.idsAreSorted) return m;
+        const index = this.sortedIdPositionToIndex[m];
+        assertValue(index, "Position is undefined");
+        return index;
+      }
+      if (v < id) l = m + 1;
+      else r = m - 1;
+    }
 
-		// Build anchors (every blockSize-th key)
-		const aLen = Math.ceil(this.size / BLOCK_SIZE)
-		const sab = new BufferConstructor(aLen * Float64Array.BYTES_PER_ELEMENT)
-		this.anchors = new Float64Array(sab, 0, aLen)
-		for (let j = 0; j < aLen; j++) {
-			const id = this.idsSorted[Math.min(j * BLOCK_SIZE, this.size - 1)]
-			assertValue(id, "ID is undefined")
-			this.anchors[j] = id
-		}
+    // ID not found
+    return -1;
+  }
 
-		this.indexBuilt = true
-	}
+  /**
+   * Pass an ID or an index, get both.
+   */
+  idOrIndex(i: IdOrIndex): [index: number, id: number] {
+    if ("id" in i) return [this.getIndexFromId(i.id), i.id];
+    return [i.index, this.at(i.index)];
+  }
 
-	/**
-	 * Look up the internal array index for an OSM entity ID.
-	 *
-	 * @param id - The OSM entity ID to look up.
-	 * @returns The internal array index, or -1 if not found.
-	 * @throws If the index has not been built.
-	 */
-	getIndexFromId(id: number): number {
-		if (!this.indexBuilt) throw Error("IdIndex not built.")
+  /** Returns the sorted array of IDs for iteration. */
+  get sorted() {
+    return this.idsSorted;
+  }
 
-		// binary search anchors
-		let lo = 0
-		let hi = this.anchors.length - 1
-		while (lo < hi) {
-			const mid = (lo + hi + 1) >>> 1
-			const anchor = this.anchors[mid]
-			assertValue(anchor, "Anchor is undefined")
-			if (anchor <= id) lo = mid
-			else hi = mid - 1
-		}
-		const start = lo * BLOCK_SIZE
-		const end = Math.min(start + BLOCK_SIZE, this.idsSorted.length)
+  /** @internal Iterate sorted IDs with their original storage positions. */
+  *sortedEntries(): Generator<readonly [id: number, index: number]> {
+    for (let i = 0; i < this.idsSorted.length; i++) {
+      yield this.sortedEntry(i);
+    }
+  }
 
-		// binary search within block
-		let l = start
-		let r = end - 1
-		while (l <= r) {
-			const m = (l + r) >>> 1
-			const v = this.idsSorted[m]
-			assertValue(v, "Value is undefined")
-			if (v === id) {
-				if (this.idsAreSorted) return m
-				const index = this.sortedIdPositionToIndex[m]
-				assertValue(index, "Position is undefined")
-				return index
-			}
-			if (v < id) l = m + 1
-			else r = m - 1
-		}
+  /**
+   * Iterate in canonical OSM file order: negative IDs first by increasing
+   * absolute value, followed by non-negative IDs in ascending order.
+   *
+   * @internal
+   */
+  *osmSortedEntries(): Generator<readonly [id: number, index: number]> {
+    let firstNonNegative = 0;
+    while (firstNonNegative < this.idsSorted.length && this.idsSorted[firstNonNegative]! < 0) {
+      firstNonNegative++;
+    }
 
-		// ID not found
-		return -1
-	}
+    // Numeric sorting places negative IDs in the opposite of canonical OSM
+    // order. Reverse ID groups while preserving duplicate insertion order.
+    let groupEnd = firstNonNegative;
+    while (groupEnd > 0) {
+      const id = this.idsSorted[groupEnd - 1];
+      assertValue(id, "Sorted ID is undefined");
+      let groupStart = groupEnd - 1;
+      while (groupStart > 0 && this.idsSorted[groupStart - 1] === id) groupStart--;
+      for (let position = groupStart; position < groupEnd; position++) {
+        yield this.sortedEntry(position);
+      }
+      groupEnd = groupStart;
+    }
 
-	/**
-	 * Pass an ID or an index, get both.
-	 */
-	idOrIndex(i: IdOrIndex): [index: number, id: number] {
-		if ("id" in i) return [this.getIndexFromId(i.id), i.id]
-		return [i.index, this.at(i.index)]
-	}
+    for (let position = firstNonNegative; position < this.idsSorted.length; position++) {
+      yield this.sortedEntry(position);
+    }
+  }
 
-	/** Returns the sorted array of IDs for iteration. */
-	get sorted() {
-		return this.idsSorted
-	}
+  private sortedEntry(position: number): readonly [id: number, index: number] {
+    const id = this.idsSorted[position];
+    assertValue(id, "Sorted ID is undefined");
+    if (this.idsAreSorted) return [id, position];
+    const index = this.sortedIdPositionToIndex[position];
+    assertValue(index, "Sorted position is undefined");
+    return [id, index];
+  }
 
-	/**
-	 * Get transferable buffers for passing to another thread.
-	 * @returns Serializable representation of this index.
-	 */
-	transferables(): IdsTransferables {
-		return {
-			ids: this.ids.array.buffer,
-			sortedIds: this.idsSorted.buffer,
-			sortedIdPositionToIndex: this.sortedIdPositionToIndex.buffer,
-			anchors: this.anchors.buffer,
-			idsAreSorted: this.idsAreSorted,
-		}
-	}
+  /**
+   * Get transferable buffers for passing to another thread.
+   * @returns Serializable representation of this index.
+   */
+  transferables(): IdsTransferables {
+    const base: IdsTransferables = {
+      ids: this.ids.array.buffer,
+      anchors: this.anchors.buffer,
+      idsAreSorted: this.idsAreSorted,
+    };
+    if (this.idsAreSorted) return base;
+    return {
+      ...base,
+      sortedIds: this.idsSorted.buffer,
+      sortedIdPositionToIndex: this.sortedIdPositionToIndex.buffer,
+    };
+  }
 
-	/**
-	 * Get the approximate memory requirements for a given number of IDs in bytes.
-	 */
-	static getBytesRequired(count: number) {
-		if (count === 0) return 0
-		return (
-			count * Float64Array.BYTES_PER_ELEMENT + // ids
-			count * Float64Array.BYTES_PER_ELEMENT + // sortedIds
-			count * Uint32Array.BYTES_PER_ELEMENT + // sortedIdPositionToIndex
-			Math.ceil(count / BLOCK_SIZE) * Float64Array.BYTES_PER_ELEMENT // anchors
-		)
-	}
+  /**
+   * Get the approximate memory requirements for a given number of IDs in bytes.
+   *
+   * `idsAreSorted` defaults to true because PBF entity collections arrive in
+   * ascending ID order and retain no separate sort buffers. Pass false when
+   * estimating a programmatically built (unsorted) collection, which also
+   * retains sorted IDs plus a position map.
+   */
+  static getBytesRequired(count: number, idsAreSorted = true) {
+    if (count === 0) return 0;
+    return (
+      count * Float64Array.BYTES_PER_ELEMENT + // ids
+      (idsAreSorted
+        ? 0
+        : count * (Float64Array.BYTES_PER_ELEMENT + Uint32Array.BYTES_PER_ELEMENT)) + // sort index
+      Math.ceil(count / BLOCK_SIZE) * Float64Array.BYTES_PER_ELEMENT // anchors
+    );
+  }
 
-	/**
-	 * Update a ContentHasher with the IDs data.
-	 * Uses the sorted IDs for consistent hashing regardless of insertion order.
-	 */
-	updateHash(hasher: ContentHasher): ContentHasher {
-		return hasher.update(this.idsSorted)
-	}
+  /**
+   * Update a ContentHasher with the IDs data.
+   * Uses the sorted IDs for consistent hashing regardless of insertion order.
+   */
+  updateHash(hasher: ContentHasher): ContentHasher {
+    return hasher.update(this.idsSorted);
+  }
 }

package/src/index.ts

@@ -4,8 +4,8 @@
  * Efficiently stores and queries OpenStreetMap entities (nodes, ways, relations).
  *
  * Features:
- * - **Memory-efficient**: Uses typed arrays and Int32Array microdegrees.
- * - **Spatial indexing**: KDBush (points) and Flatbush (bboxes) for fast geographic queries.
+ * - **Memory-efficient**: Uses typed arrays; coordinates are Int32 at 1e-7 degrees.
+ * - **Spatial indexing**: Compact indirect KD trees (points) and Flatbush (bboxes).
  * - **Worker-ready**: Zero-copy transfer via `transferables()`.
  * - **Tag indexing**: Fast reverse lookup by tag key.
  *
@@ -22,16 +22,25 @@
  * @module @osmix/core
  */
 
-/// <reference path="./types/kdbush.d.ts" />
-/// <reference path="./types/geokdbush.d.ts" />
+// oxlint-disable-next-line typescript/triple-slash-reference -- ambient module declarations for untyped packages
 /// <reference path="./types/geoflatbush.d.ts" />
 
-export type { IdOrIndex } from "./ids.ts"
-export * from "./mocks.ts"
-export * from "./nodes.ts"
-export * from "./osm.ts"
-export * from "./relations.ts"
-export * from "./stringtable.ts"
-export * from "./tags.ts"
-export { BufferConstructor, type BufferType } from "./typed-arrays.ts"
-export * from "./ways.ts"
+export type { IdOrIndex } from "./ids.ts";
+export type { OsmReader, OsmWriter } from "./contracts.ts";
+export { OsmEntityIndexBuildError, type OsmEntityIndexComponent } from "./entities.ts";
+export * from "./limits.ts";
+export * from "./nodes.ts";
+export * from "./osm.ts";
+export * from "./relations.ts";
+export { negativeIdMap, renumberNegativeIds, type OsmIdMap } from "./renumber.ts";
+export * from "./stringtable.ts";
+export * from "./tags.ts";
+export {
+  BufferConstructor,
+  ResizeableTypedArray,
+  TypedBufferAllocationError,
+  type BufferType,
+  type TypedBufferAllocationOperation,
+  type TypedBufferType,
+} from "./typed-arrays.ts";
+export * from "./ways.ts";