@osmix/core 0.0.2 → 0.0.6

package/src/entities.ts

@@ -1,59 +1,151 @@
-import type { OsmEntity, OsmEntityType, OsmTags } from "@osmix/json"
-import { type IdOrIndex, Ids, type IdsTransferables } from "./ids"
-import type StringTable from "./stringtable"
-import { Tags, type TagsTransferables } from "./tags"
+/**
+ * Base class for OSM entity collections.
+ *
+ * Provides common ID and tag storage, streaming iteration, and sorted access.
+ * Subclasses implement entity-specific storage and spatial indexing.
+ *
+ * @module
+ */
 
-export interface EntitiesTransferables
-	extends IdsTransferables,
-		TagsTransferables {}
+import type {
+	GeoBbox2D,
+	OsmEntity,
+	OsmEntityType,
+	OsmTags,
+} from "@osmix/shared/types"
+import type { IdOrIndex, Ids, IdsTransferables } from "./ids"
+import type { Tags, TagsTransferables } from "./tags"
+import type { BufferType } from "./typed-arrays"
 
+/**
+ * Serializable representation of an Entities collection for worker transfer.
+ * Combines ID and tag transferables; subclasses add entity-specific data.
+ */
+export interface EntitiesTransferables<T extends BufferType = BufferType>
+	extends IdsTransferables<T>,
+		TagsTransferables<T> {}
+
+/**
+ * Abstract base for typed entity collections.
+ *
+ * Lifecycle:
+ * 1. **Ingest**: `addEntity()` (no lookups).
+ * 2. **Finalize**: `buildIndex()`.
+ * 3. **Query**: Lookups and iteration enabled.
+ */
 export abstract class Entities<T extends OsmEntity> {
+	/** The type of entity stored in this collection ("node", "way", or "relation"). */
 	indexType: OsmEntityType
-	stringTable: StringTable
+	/** ID storage and lookup */
 	ids: Ids
+	/** Tag storage and search */
 	tags: Tags
 
-	private indexBuilt = false
+	/** Whether buildIndex() has been called */
+	protected indexBuilt = false
 
-	constructor(
-		indexType: OsmEntityType,
-		stringTable: StringTable,
-		ids?: Ids,
-		tags?: Tags,
-	) {
-		this.stringTable = stringTable
+	/**
+	 * Create a new Entities collection.
+	 * @param indexType - The entity type ("node", "way", or "relation").
+	 * @param ids - The ID storage instance.
+	 * @param tags - The tag storage instance.
+	 */
+	constructor(indexType: OsmEntityType, ids: Ids, tags: Tags) {
 		this.indexType = indexType
-		this.ids = ids ?? new Ids()
-		this.tags = tags ?? new Tags(stringTable)
+		this.ids = ids
+		this.tags = tags
 	}
 
-	get isReady() {
-		return this.ids.isReady && this.tags.isReady && this.indexBuilt
+	/**
+	 * Get transferable objects for passing to another thread.
+	 */
+	transferables(): EntitiesTransferables {
+		return {
+			...this.ids.transferables(),
+			...this.tags.transferables(),
+		}
 	}
 
+	/**
+	 * Check if the index is built and ready for use.
+	 */
+	isReady() {
+		return this.ids.isReady() && this.tags.isReady() && this.indexBuilt
+	}
+
+	/** Number of entities in this collection. */
 	get size() {
 		return this.ids.size
 	}
 
+	/**
+	 * Compact entity-specific typed arrays.
+	 * Called by `buildIndex()` after ID and tag indexes are built.
+	 * @abstract
+	 */
 	abstract buildEntityIndex(): void
 
+	/**
+	 * Finalize indexes.
+	 * Must be called after adding entities and before querying.
+	 */
 	buildIndex() {
-		console.time(`${this.indexType}Index.finish`)
+		if (this.indexBuilt) return
+		console.time(`${this.indexType}Index.buildIndex`)
 		this.ids.buildIndex()
 		this.tags.buildIndex()
 		this.buildEntityIndex()
 		this.indexBuilt = true
-		console.timeEnd(`${this.indexType}Index.finish`)
+		console.timeEnd(`${this.indexType}Index.buildIndex`)
 	}
 
+	/**
+	 * Get the bounding box of an entity.
+	 * @param idOrIndex - Entity identifier (by ID or internal index).
+	 * @returns Geographic bounding box [minLon, minLat, maxLon, maxLat].
+	 * @abstract
+	 */
+	abstract getEntityBbox(idOrIndex: IdOrIndex): GeoBbox2D
+
+	/**
+	 * Reconstruct a full entity object from index data.
+	 * @param index - Internal array index.
+	 * @param id - OSM entity ID.
+	 * @param tags - Optional pre-fetched tags.
+	 * @returns The complete entity object.
+	 * @abstract
+	 */
 	abstract getFullEntity(index: number, id: number, tags?: OsmTags): T
 
+	/**
+	 * Add an entity to the index. Tags can be provided as an array of keys and values, or as an object.
+	 */
+	addEntity(id: number, tags: number[], values: number[]): number
+	addEntity(id: number, tags: OsmTags): number
+	addEntity(id: number, tags: OsmTags | number[], values?: number[]): number {
+		const entityIndex = this.ids.add(id)
+		if (Array.isArray(tags)) {
+			if (values === undefined)
+				throw Error("Values are required when tags is an array")
+			this.tags.addTagKeysAndValues(entityIndex, tags, values)
+		} else {
+			this.tags.addTags(entityIndex, tags)
+		}
+		return entityIndex
+	}
+
+	/**
+	 * Get an entity by ID or index.
+	 */
 	get(idOrIndex: IdOrIndex): T | null {
 		const [index, id] = this.ids.idOrIndex(idOrIndex)
 		if (index === -1) return null
 		return this.getFullEntity(index, id, this.tags.getTags(index))
 	}
 
+	/**
+	 * Get an entity by index.
+	 */
 	getByIndex(index: number): T {
 		return this.getFullEntity(
 			index,
@@ -62,6 +154,9 @@ export abstract class Entities<T extends OsmEntity> {
 		)
 	}
 
+	/**
+	 * Get multiple entities by their indexes.
+	 */
 	getEntitiesByIndex(indexes: number[]): T[] {
 		const entities: T[] = []
 		for (const index of indexes) {
@@ -72,12 +167,18 @@ export abstract class Entities<T extends OsmEntity> {
 		return entities
 	}
 
+	/**
+	 * Iterate over all entities in the index.
+	 */
 	*[Symbol.iterator](): Generator<T> {
 		for (let i = 0; i < this.size; i++) {
 			yield this.getFullEntity(i, this.ids.at(i), this.tags.getTags(i))
 		}
 	}
 
+	/**
+	 * Get an entity by ID.
+	 */
 	getById(id: number): T | null {
 		const index = this.ids.getIndexFromId(id)
 		if (index !== -1)
@@ -85,6 +186,9 @@ export abstract class Entities<T extends OsmEntity> {
 		return null
 	}
 
+	/**
+	 * Iterate over entities sorted by ID.
+	 */
 	*sorted(): Generator<T> {
 		for (const id of this.ids.sorted) {
 			const index = this.ids.getIndexFromId(id)
@@ -92,4 +196,16 @@ export abstract class Entities<T extends OsmEntity> {
 			yield this.getFullEntity(index, id, this.tags.getTags(index))
 		}
 	}
+
+	/**
+	 * Search for entities with a specific tag key and optional value.
+	 */
+	search(key: string, val?: string): T[] {
+		const keyIndex = this.tags.find(key)
+		const entities = this.tags
+			.hasKey(keyIndex)
+			.map((index) => this.getByIndex(index))
+		if (val === undefined) return entities
+		return entities.filter((entity) => entity.tags?.[key] === val)
+	}
 }

package/src/ids.ts

@@ -1,92 +1,130 @@
+/**
+ * ID storage and lookup for OSM entities.
+ *
+ * Uses a two-level binary search (anchor array + block search) to map 64-bit OSM IDs
+ * to internal array indices. Balances memory usage with O(log n) lookup speed.
+ *
+ * @module
+ */
+
 import { assertValue } from "@osmix/shared/assert"
 import {
 	BufferConstructor,
 	type BufferType,
-	ResizeableTypedArray,
+	ResizeableTypedArray as RTA,
 } from "./typed-arrays"
 
+/**
+ * Union type for looking up entities by either OSM ID or internal array index.
+ */
 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
 
-export interface IdsTransferables {
-	ids: BufferType
-	sortedIds: BufferType
-	sortedIdPositionToIndex: BufferType
-	anchors: BufferType
+/**
+ * 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
 }
 
 /**
- * Efficiently store and lookup IDs.
+ * Efficiently store and lookup OSM entity IDs.
  *
- * This is used to store IDs in a sorted array and then use binary search to find the index of an ID.
- * Maps max out at 2^32 IDs.
+ * Stores 64-bit IDs in a Float64Array and maintains a sorted index for O(log n) lookups.
+ * Max capacity: ~2^32 entities.
  */
 export class Ids {
-	private ids: ResizeableTypedArray<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
 
-	static from({
-		ids,
-		sortedIds,
-		sortedIdPositionToIndex,
-		anchors,
-		idsAreSorted,
-	}: IdsTransferables) {
-		const idIndex = new Ids()
-		idIndex.ids = ResizeableTypedArray.from(Float64Array, ids)
-		idIndex.idsSorted = new Float64Array(sortedIds)
-		idIndex.sortedIdPositionToIndex = new Uint32Array(sortedIdPositionToIndex)
-		idIndex.anchors = new Float64Array(anchors)
-		idIndex.indexBuilt = true
-		idIndex.idsAreSorted = idsAreSorted
-		return idIndex
-	}
-
-	constructor() {
-		this.ids = new ResizeableTypedArray(Float64Array)
-		this.idsSorted = new Float64Array(new BufferConstructor(0))
-		this.sortedIdPositionToIndex = new Uint32Array(new BufferConstructor(0))
-		this.anchors = new Float64Array(new BufferConstructor(0))
-	}
-
-	transferables(): IdsTransferables {
-		return {
-			ids: this.ids.array.buffer,
-			sortedIds: this.idsSorted.buffer,
-			sortedIdPositionToIndex: this.sortedIdPositionToIndex.buffer,
-			anchors: this.anchors.buffer,
-			idsAreSorted: 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))
 		}
 	}
 
+	/** Number of IDs stored in this index. */
 	get size() {
 		return this.ids.length
 	}
 
-	get isReady() {
+	/** 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
 	}
 
-	add(id: number): void {
+	/**
+	 * 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
-		this.ids.push(id)
+		return this.ids.push(id)
 	}
 
+	/**
+	 * 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)
 	}
 
+	/**
+	 * 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
 	}
@@ -158,7 +196,13 @@ export class Ids {
 		this.indexBuilt = true
 	}
 
-	// Lookup id → 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.")
 
@@ -204,7 +248,35 @@ export class Ids {
 		return [i.index, this.at(i.index)]
 	}
 
+	/** Returns the sorted array of IDs for iteration. */
 	get sorted() {
 		return this.idsSorted
 	}
+
+	/**
+	 * 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 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
+		)
+	}
 }

package/src/index.ts

@@ -1,7 +1,36 @@
+/**
+ * @osmix/core - In-memory OSM entity storage with spatial indexing.
+ *
+ * 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.
+ * - **Worker-ready**: Zero-copy transfer via `transferables()`.
+ * - **Tag indexing**: Fast reverse lookup by tag key.
+ *
+ * @example
+ * ```ts
+ * import { Osm } from "@osmix/core"
+ * const osm = new Osm({ id: "example" })
+ * osm.nodes.addNode({ id: 1, lon: -122.4, lat: 47.6, tags: { name: "Seattle" } })
+ * osm.buildIndexes()
+ * osm.buildSpatialIndexes()
+ * const nearby = osm.nodes.findIndexesWithinRadius(-122.4, 47.6, 10)
+ * ```
+ *
+ * @module @osmix/core
+ */
+
 /// <reference path="./types/kdbush.d.ts" />
+/// <reference path="./types/geokdbush.d.ts" />
+/// <reference path="./types/geoflatbush.d.ts" />
 
-export { Nodes } from "./nodes"
-export { Osmix } from "./osmix"
-export { Relations } from "./relations"
-export { throttle } from "./utils"
-export { Ways } from "./ways"
+export * from "./nodes"
+export * from "./osm"
+export * from "./relations"
+export * from "./stringtable"
+export * from "./tags"
+export { BufferConstructor, type BufferType } from "./typed-arrays"
+export * from "./utils" // TODO Move into shared?
+export * from "./ways"