@osmix/core 0.0.2 → 0.0.6

package/src/typed-arrays.ts

@@ -1,12 +1,28 @@
+/**
+ * Resizable typed array utilities.
+ *
+ * Wraps typed arrays with automatic buffer expansion (ArrayList semantics).
+ * Uses SharedArrayBuffer (if available) for zero-copy worker transfer.
+ *
+ * @module
+ */
+
 /**
  * Use SharedArrayBuffer if the runtime supports it, otherwise fall back to ArrayBuffer.
+ * SharedArrayBuffer enables zero-copy transfer between workers.
  */
 export const BufferConstructor =
 	typeof SharedArrayBuffer !== "undefined"
 		? (SharedArrayBuffer as SharedArrayBufferConstructor)
 		: (ArrayBuffer as ArrayBufferConstructor)
+
+/** The buffer type used by this runtime (SharedArrayBuffer or ArrayBuffer). */
 export type BufferType = InstanceType<typeof BufferConstructor>
 
+/**
+ * Union of all standard typed array types.
+ * Generic over buffer type to preserve SharedArrayBuffer compatibility.
+ */
 export type TypedArray<B extends BufferType = BufferType> =
 	| Int8Array<B>
 	| Uint8Array<B>
@@ -18,6 +34,9 @@ export type TypedArray<B extends BufferType = BufferType> =
 	| Float32Array<B>
 	| Float64Array<B>
 
+/**
+ * Constructor interface for typed arrays.
+ */
 export interface TypedArrayConstructor<
 	T extends TypedArray<BufferType> = TypedArray<BufferType>,
 > {
@@ -26,37 +45,63 @@ export interface TypedArrayConstructor<
 }
 
 /**
- * OSM IDs can be stored as 64-bit floating point numbers.
+ * Float64Array for storing OSM IDs.
+ *
+ * OSM IDs are 64-bit integers. JavaScript's number type (IEEE 754 double)
+ * can exactly represent integers up to 2^53, which covers all current OSM IDs.
+ * Float64Array allows typed array operations while maintaining precision.
  */
 export const IdArrayType = Float64Array
 
 /**
- * When we are storing coordinates, we need to be able to store 64-bit floating point numbers.
- * However, for benchmarking it is handy to test 32-bit floating point numbers.
- */
-export const CoordinateArrayType = Float64Array
-
-/**
- * When we are storing indexes into other arrays, we never need an index to exceed 2^32.
+ * Uint32Array for storing array indices.
+ *
+ * Internal indices into typed arrays never exceed 2^32 elements,
+ * so Uint32Array provides the best balance of range and memory efficiency.
  */
 export const IndexArrayType = Uint32Array
 
 /**
- * Default buffer size.
+ * Initial buffer size for ResizeableTypedArray.
+ * 1 MiB provides reasonable initial capacity while avoiding excessive memory allocation.
  */
 export const DEFAULT_BUFFER_SIZE = 2 ** 20 // 1 MiB
 
+/**
+ * Auto-expanding typed array wrapper.
+ *
+ * - `push()` appends elements, doubling buffer size as needed.
+ * - `compact()` shrinks buffer to fit data.
+ * - Supports growable SharedArrayBuffer and resizable ArrayBuffer.
+ */
 export class ResizeableTypedArray<TA extends TypedArray> {
+	/** The typed array constructor for this instance */
 	ArrayType: TypedArrayConstructor<TA>
+	/** The current typed array view into the buffer */
 	array: TA
+	/** Number of items actually stored (may be less than array.length) */
 	items = 0
 
+	/** The underlying ArrayBuffer or SharedArrayBuffer */
 	buffer: BufferType
+	/** Current buffer size in bytes */
 	bufferSize: number
+	/** Maximum byte length for growable buffers */
 	maxByteLength: number
 
+	/** Buffer constructor (SharedArrayBuffer or ArrayBuffer) */
 	BC: SharedArrayBufferConstructor | ArrayBufferConstructor
 
+	/**
+	 * Reconstruct a ResizeableTypedArray from an existing buffer.
+	 *
+	 * Used after transferring buffers between workers. The resulting array
+	 * is considered "compacted" with items = array.length.
+	 *
+	 * @param ArrayType - The typed array constructor.
+	 * @param buffer - The existing buffer to wrap.
+	 * @returns A new ResizeableTypedArray wrapping the buffer.
+	 */
 	static from<TA extends TypedArray>(
 		ArrayType: TypedArrayConstructor<TA>,
 		buffer: BufferType,
@@ -71,6 +116,12 @@ export class ResizeableTypedArray<TA extends TypedArray> {
 		return rta
 	}
 
+	/**
+	 * Create a new ResizeableTypedArray with an empty buffer.
+	 *
+	 * @param ArrayType - The typed array constructor (e.g., Float64Array).
+	 * @param BC - Buffer constructor to use (defaults to SharedArrayBuffer if available).
+	 */
 	constructor(
 		ArrayType: TypedArrayConstructor<TA>,
 		BC:
@@ -87,13 +138,21 @@ export class ResizeableTypedArray<TA extends TypedArray> {
 		this.array = new this.ArrayType(this.buffer)
 	}
 
+	/**
+	 * Iterate over the array values.
+	 */
 	[Symbol.iterator](): ArrayIterator<number> {
 		return this.array[Symbol.iterator]()
 	}
 
+	/**
+	 * Double the buffer capacity.
+	 * Uses in-place grow/resize if supported, otherwise allocates new buffer and copies.
+	 */
 	expandArray() {
 		this.bufferSize *= 2
 		if (this.bufferSize > this.buffer.maxByteLength) {
+			// Need a completely new buffer with larger maxByteLength
 			this.maxByteLength *= 2
 			const newBuffer = new this.BC(this.bufferSize, {
 				maxByteLength: this.maxByteLength,
@@ -103,6 +162,7 @@ export class ResizeableTypedArray<TA extends TypedArray> {
 			this.buffer = newBuffer
 			this.array = newArray
 		} else {
+			// Can grow/resize the existing buffer in place
 			if (this.buffer instanceof SharedArrayBuffer && this.buffer.growable) {
 				this.buffer.grow(this.bufferSize)
 			} else if (this.buffer instanceof ArrayBuffer && this.buffer.resizable) {
@@ -114,7 +174,7 @@ export class ResizeableTypedArray<TA extends TypedArray> {
 	}
 
 	/**
-	 * Handles negative numbers
+	 * Get the value at an index. Handles negative indices.
 	 */
 	at(index: number): number {
 		if (index < -this.length || index >= this.length)
@@ -125,6 +185,9 @@ export class ResizeableTypedArray<TA extends TypedArray> {
 		return result
 	}
 
+	/**
+	 * Get a slice of the array.
+	 */
 	slice(start: number, end: number) {
 		return this.array.slice(start, end)
 	}
@@ -133,6 +196,9 @@ export class ResizeableTypedArray<TA extends TypedArray> {
 		return this.items
 	}
 
+	/**
+	 * Push a value to the end of the array.
+	 */
 	push(value: number): number {
 		if (this.length >= this.array.length) {
 			this.expandArray()
@@ -141,19 +207,40 @@ export class ResizeableTypedArray<TA extends TypedArray> {
 		return this.length - 1
 	}
 
+	/**
+	 * Set a value at a specific index. Expands array if needed.
+	 */
+	set(index: number, value: number) {
+		if (index < 0) throw Error("Index out of bounds")
+		if (index >= this.length) {
+			while (index >= this.array.length) this.expandArray()
+			this.items = index + 1
+		}
+		this.array[index] = value
+	}
+
+	/**
+	 * Push multiple values to the end of the array.
+	 */
 	pushMany(values: number[] | TypedArray) {
 		while (this.length + values.length > this.array.length) this.expandArray()
 		this.array.set(values, this.length)
 		this.items += values.length
 	}
 
+	/**
+	 * Shrink the buffer to exactly fit stored items.
+	 * Buffer becomes fixed-length after compacting.
+	 */
 	compact() {
 		if (this.buffer instanceof SharedArrayBuffer) {
+			// SharedArrayBuffer uses slice() to create a new fixed-size buffer
 			this.buffer = this.buffer.slice(
 				0,
 				this.length * this.ArrayType.BYTES_PER_ELEMENT,
 			)
 		} else {
+			// ArrayBuffer uses transferToFixedLength() to detach and resize
 			this.buffer = this.buffer.transferToFixedLength(
 				this.length * this.ArrayType.BYTES_PER_ELEMENT,
 			)

package/src/types/geoflatbush.d.ts

@@ -0,0 +1,37 @@
+declare module "geoflatbush" {
+	import type Flatbush from "flatbush"
+
+	/**
+	 * Returns an array of the closest items from a given location in order of increasing distance.
+	 * @param index - A Flatbush index with geographic bounding boxes in degrees (minLng, minLat, maxLng, maxLat).
+	 * @param lng - Query point longitude in degrees.
+	 * @param lat - Query point latitude in degrees.
+	 * @param maxResults - Maximum number of items to return (default: Infinity).
+	 * @param maxDistance - Maximum distance in kilometers (default: Infinity).
+	 * @param filterFn - Optional filter function called with index of each item.
+	 * @returns Array of item indices from the index, sorted by distance.
+	 */
+	export function around(
+		index: Flatbush,
+		lng: number,
+		lat: number,
+		maxResults?: number,
+		maxDistance?: number,
+		filterFn?: (index: number) => boolean,
+	): number[]
+
+	/**
+	 * Returns the great circle distance between two locations in kilometers.
+	 * @param lng1 - First point longitude in degrees.
+	 * @param lat1 - First point latitude in degrees.
+	 * @param lng2 - Second point longitude in degrees.
+	 * @param lat2 - Second point latitude in degrees.
+	 * @returns Distance in kilometers.
+	 */
+	export function distance(
+		lng: number,
+		lat: number,
+		lng2: number,
+		lat2: number,
+	): number
+}

package/src/types/geokdbush.d.ts

@@ -0,0 +1,37 @@
+declare module "geokdbush" {
+	import type KDBush from "kdbush"
+
+	/**
+	 * Returns an array of the closest points from a given location in order of increasing distance.
+	 * @param index - A KDBush index with geographic coordinates (lng, lat) in degrees.
+	 * @param lng - Query point longitude in degrees.
+	 * @param lat - Query point latitude in degrees.
+	 * @param maxResults - Maximum number of points to return (default: Infinity).
+	 * @param maxDistance - Maximum distance in kilometers (default: Infinity).
+	 * @param predicate - Optional filter function called with index of each point.
+	 * @returns Array of point indices from the index, sorted by distance.
+	 */
+	export function around(
+		index: KDBush,
+		lng: number,
+		lat: number,
+		maxResults?: number,
+		maxDistance?: number,
+		predicate?: (index: number) => boolean,
+	): number[]
+
+	/**
+	 * Returns the great circle distance between two locations in kilometers.
+	 * @param lng1 - First point longitude in degrees.
+	 * @param lat1 - First point latitude in degrees.
+	 * @param lng2 - Second point longitude in degrees.
+	 * @param lat2 - Second point latitude in degrees.
+	 * @returns Distance in kilometers.
+	 */
+	export function distance(
+		lng1: number,
+		lat1: number,
+		lng2: number,
+		lat2: number,
+	): number
+}

package/src/types/kdbush.d.ts

@@ -1,21 +1,39 @@
 declare module "kdbush" {
-	import type { BufferConstructor, BufferType } from "../typed-arrays"
+	import type {
+		BufferConstructor,
+		BufferType,
+		TypedArray,
+		TypedArrayConstructor,
+	} from "../typed-arrays"
+
 	export default class KDBush {
 		constructor(
 			length: number,
-			nodeSize: number,
-			ArrayType: Float64ArrayConstructor,
-			BufferConstructor: BufferConstructor,
+			nodeSize?: number,
+			ArrayType?: TypedArrayConstructor,
+			BufferConstructor?: BufferConstructor,
 		)
 
+		/** Number of items in the index */
+		numItems: number
+
+		/** Size of the KD-tree node */
+		nodeSize: number
+
 		/** Serialized index data buffer */
 		data: BufferType
 
+		/** Internal array of indices (used by geokdbush) */
+		ids: Uint16Array | Uint32Array
+
+		/** Internal array of coordinates [x0, y0, x1, y1, ...] (used by geokdbush) */
+		coords: TypedArray
+
 		/** Add a point before calling finish */
-		add(x: number, y: number): void
+		add(x: number, y: number): number
 
 		/** Finalize the index after adding all points */
-		finish(): void
+		finish(): this
 
 		/** Query points within a bounding box; returns internal point indexes */
 		range(minX: number, minY: number, maxX: number, maxY: number): number[]

package/src/utils.ts

@@ -1,19 +1,14 @@
-import type { GeoBbox2D, LonLat } from "@osmix/shared/types"
+/**
+ * Utility functions for @osmix/core.
+ * @module
+ */
 
-export function throttle<T extends unknown[]>(
-	func: (...args: T) => void,
-	timeFrame: number,
-) {
-	let lastTime = 0
-	return (...args: T) => {
-		const now = Date.now()
-		if (now - lastTime >= timeFrame) {
-			func(...args)
-			lastTime = now
-		}
-	}
-}
+import type { GeoBbox2D, LonLat } from "@osmix/shared/types"
 
+/**
+ * Compute the bounding box of a set of coordinates.
+ * Returns `[minLon, minLat, maxLon, maxLat]`.
+ */
 export function bboxFromLonLats(lonLats: LonLat[]): GeoBbox2D {
 	let minLon = Number.POSITIVE_INFINITY
 	let minLat = Number.POSITIVE_INFINITY