@osmix/shared 0.0.2 → 0.0.7

package/src/relation-multipolygon.ts

@@ -0,0 +1,225 @@
+/**
+ * Multipolygon relation building utilities.
+ *
+ * Implements the OSM multipolygon relation specification to construct
+ * polygon geometries from way members. Handles outer/inner roles,
+ * way connection, and ring closure.
+ *
+ * @see https://wiki.openstreetmap.org/wiki/Relation:multipolygon
+ *
+ * @module
+ */
+
+import type { LonLat, OsmRelation, OsmRelationMember, OsmWay } from "./types"
+
+/**
+ * Get way members from a relation, grouped by role (outer/inner).
+ */
+export function getWayMembersByRole(relation: OsmRelation): {
+	outer: OsmRelationMember[]
+	inner: OsmRelationMember[]
+} {
+	const outer: OsmRelationMember[] = []
+	const inner: OsmRelationMember[] = []
+
+	for (const member of relation.members) {
+		if (member.type !== "way") continue
+		const role = member.role?.toLowerCase() ?? ""
+		if (role === "outer") {
+			outer.push(member)
+		} else if (role === "inner") {
+			inner.push(member)
+		}
+	}
+
+	return { outer, inner }
+}
+
+/**
+ * Connect ways that share endpoints to form a continuous ring.
+ * Returns an array of rings (each ring is an array of way IDs in order).
+ *
+ * This function handles:
+ * - Ways that are reversed (end matches end, or start matches start).
+ * - Closed ways (single ways that form a ring).
+ * - Disconnected chains (multiple independent rings).
+ */
+export function connectWaysToRings(wayMembers: OsmWay[]): OsmWay[][] {
+	if (wayMembers.length === 0) return []
+
+	const rings: OsmWay[][] = []
+	const used = new Set<number>()
+	const wayMap = new Map<number, OsmWay>()
+
+	// Build map of way ID to member
+	for (const member of wayMembers) {
+		wayMap.set(member.id, member)
+	}
+
+	// Helper to reverse a way's refs
+	const reverseWay = (way: OsmWay): OsmWay => ({
+		...way,
+		refs: [...way.refs].reverse(),
+	})
+
+	// Build rings by connecting ways
+	for (const startWay of wayMembers) {
+		if (used.has(startWay.id)) continue
+		if (startWay.refs.length < 2) throw Error("Way has less than 2 refs")
+
+		const ring: OsmWay[] = [startWay]
+		used.add(startWay.id)
+
+		let currentStart = startWay.refs[0]!
+		let currentEnd = startWay.refs[startWay.refs.length - 1]!
+
+		// Try to extend the ring forward
+		while (true) {
+			let found = false
+			for (const nextWay of wayMembers) {
+				if (used.has(nextWay.id)) continue
+				if (nextWay.refs.length < 2) throw Error("Way has less than 2 refs")
+				const nextStart = nextWay.refs[0]!
+				const nextEnd = nextWay.refs[nextWay.refs.length - 1]!
+
+				// Check if next way connects to current end
+				if (currentEnd === nextStart) {
+					ring.push(nextWay)
+					used.add(nextWay.id)
+					currentEnd = nextEnd
+					found = true
+					break
+				}
+				if (currentEnd === nextEnd) {
+					// Need to reverse next way
+					ring.push(reverseWay(nextWay))
+					used.add(nextWay.id)
+					currentEnd = nextStart
+					found = true
+					break
+				}
+			}
+
+			if (!found) break
+		}
+
+		// Try to extend the ring backward
+		currentStart = startWay.refs[0]!
+		currentEnd = startWay.refs[startWay.refs.length - 1]!
+
+		while (true) {
+			let found = false
+			for (const nextWay of wayMembers) {
+				if (used.has(nextWay.id)) continue
+				if (nextWay.refs.length < 2) throw Error("Way has less than 2 refs")
+
+				const nextStart = nextWay.refs[0]!
+				const nextEnd = nextWay.refs[nextWay.refs.length - 1]!
+
+				// Check if next way connects to current start
+				if (currentStart === nextEnd) {
+					ring.unshift(nextWay)
+					used.add(nextWay.id)
+					currentStart = nextStart
+					found = true
+					break
+				}
+				if (currentStart === nextStart) {
+					// Need to reverse next way
+					ring.unshift(reverseWay(nextWay))
+					used.add(nextWay.id)
+					currentStart = nextEnd
+					found = true
+					break
+				}
+			}
+
+			if (!found) break
+		}
+
+		// Only add ring if it's closed (first and last node are the same)
+		if (ring.length > 0) {
+			const firstWay = ring[0]
+			const lastWay = ring[ring.length - 1]
+			if (firstWay?.refs[0] === lastWay?.refs[lastWay.refs.length - 1]) {
+				rings.push(ring)
+			}
+		}
+	}
+
+	return rings
+}
+
+/**
+ * Build polygon rings from way members of a relation.
+ * Returns an array where each element is an array of coordinate rings (outer + inner).
+ *
+ * Based on OSM multipolygon relation specification:
+ * https://wiki.openstreetmap.org/wiki/Relation:multipolygon
+ *
+ * This implementation connects way members into closed rings, and then groups them
+ * into polygons. Currently, it associates all inner rings with every outer ring
+ * found in the relation, which is a simplification. A robust implementation would
+ * use point-in-polygon checks to strictly nest holes inside their parent outer ring.
+ */
+export function buildRelationRings(
+	relation: OsmRelation,
+	getWay: (wayId: number) => OsmWay | null,
+	getNodeCoordinates: (nodeId: number) => LonLat | undefined,
+): LonLat[][][] {
+	const { outer, inner } = getWayMembersByRole(relation)
+
+	// Connect outer ways into rings
+	const outerRings = connectWaysToRings(
+		outer.map((m) => getWay(m.ref)).filter((w) => w !== null),
+	)
+	// Connect inner ways into rings
+	const innerRings = connectWaysToRings(
+		inner.map((m) => getWay(m.ref)).filter((w) => w !== null),
+	)
+
+	const wayRingToCoords = (ring: OsmWay[]): LonLat[] => {
+		const coords: LonLat[] = []
+		for (const way of ring) {
+			for (const nodeId of way.refs) {
+				const coord = getNodeCoordinates(nodeId)
+				if (coord) coords.push(coord)
+			}
+		}
+
+		// Ensure ring is closed
+		if (coords.length > 0) {
+			const first = coords[0]
+			const last = coords[coords.length - 1]
+			if (first && last && (first[0] !== last[0] || first[1] !== last[1])) {
+				coords.push([first[0], first[1]])
+			}
+		}
+		return coords
+	}
+
+	// Convert way rings to coordinate rings
+	const coordinateRings: LonLat[][][] = []
+
+	for (const outerRing of outerRings) {
+		const outerCoordinates: LonLat[] = wayRingToCoords(outerRing)
+
+		if (outerCoordinates.length >= 3) {
+			// Find inner rings that belong to this outer ring
+			const innerCoordinates: LonLat[][] = []
+			for (const innerRing of innerRings) {
+				const innerCoords: LonLat[] = wayRingToCoords(innerRing)
+
+				if (innerCoords.length >= 3) {
+					// TODO: do proper point-in-polygon test with https://github.com/rowanwins/point-in-polygon-hao
+					innerCoordinates.push(innerCoords)
+				}
+			}
+
+			// Create polygon: [outer ring, ...inner rings]
+			coordinateRings.push([outerCoordinates, ...innerCoordinates])
+		}
+	}
+
+	return coordinateRings
+}

package/src/stream-to-bytes.ts

@@ -1,5 +1,22 @@
+/**
+ * Stream to byte array conversion.
+ *
+ * Consumes a ReadableStream and concatenates all chunks into a single Uint8Array.
+ *
+ * @module
+ */
+
 import { concatBytes } from "./concat-bytes"
 
+/**
+ * Consume a ReadableStream and return all data as a single Uint8Array.
+ *
+ * Reads all chunks from the stream and concatenates them.
+ * The stream will be fully consumed after this function returns.
+ *
+ * @param stream - The stream to consume.
+ * @returns A Promise resolving to the concatenated bytes.
+ */
 export async function streamToBytes(
 	stream: ReadableStream<Uint8Array<ArrayBuffer>>,
 ): Promise<Uint8Array<ArrayBuffer>> {

package/src/test/fixtures.ts

@@ -1,7 +1,4 @@
-import { createReadStream, createWriteStream } from "node:fs"
-import { readFile, writeFile } from "node:fs/promises"
 import { dirname, join, resolve } from "node:path"
-import { Readable, Writable } from "node:stream"
 import { fileURLToPath } from "node:url"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -25,27 +22,34 @@ export async function getFixtureFile(
 ): Promise<Uint8Array<ArrayBufferLike>> {
 	const filePath = getFixturePath(url)
 	try {
-		const file = await readFile(filePath)
-		return new Uint8Array<ArrayBuffer>(file.buffer as ArrayBuffer)
+		const file = await Bun.file(filePath).arrayBuffer()
+		return new Uint8Array<ArrayBuffer>(file)
 	} catch (_error) {
+		if (process.env["CI"]) {
+			throw Error(`Do not download fixtures in CI: ${url} not found`)
+		}
 		const response = await fetch(url)
 		const buffer = await response.arrayBuffer()
 		const data = new Uint8Array<ArrayBuffer>(buffer)
-		await writeFile(filePath, data)
+		await Bun.write(filePath, data)
 		return data
 	}
 }
 
 export function getFixtureFileReadStream(url: string) {
-	return Readable.toWeb(
-		createReadStream(getFixturePath(url)),
-	) as unknown as ReadableStream<Uint8Array<ArrayBufferLike>>
+	return Bun.file(getFixturePath(url)).stream()
 }
 
 export function getFixtureFileWriteStream(url: string) {
-	return Writable.toWeb(
-		createWriteStream(getFixturePath(url)),
-	) as unknown as WritableStream<Uint8Array<ArrayBufferLike>>
+	const incrementalWriter = Bun.file(getFixturePath(url)).writer()
+	return new WritableStream<Uint8Array<ArrayBufferLike>>({
+		write: (chunk: Uint8Array<ArrayBufferLike>) => {
+			incrementalWriter.write(chunk)
+		},
+		close: () => {
+			incrementalWriter.end()
+		},
+	})
 }
 
 export type PbfFixture = {

package/src/throttle.ts

@@ -0,0 +1,37 @@
+/**
+ * Throttling utilities for rate-limiting function calls.
+ *
+ * Useful for limiting progress updates from workers or other high-frequency
+ * operations to avoid overwhelming the UI or logging.
+ *
+ * @module
+ */
+
+/**
+ * Create a throttled version of a function that only executes at most
+ * once per `timeFrame` milliseconds.
+ *
+ * @param func - The function to throttle.
+ * @param timeFrame - Minimum time between calls in milliseconds.
+ * @returns A throttled version of the function.
+ *
+ * @example
+ * ```ts
+ * const logThrottled = throttle((msg) => console.log(msg), 1000)
+ * // Only logs at most once per second
+ * for (let i = 0; i < 1000; i++) logThrottled(`Progress: ${i}`)
+ * ```
+ */
+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
+		}
+	}
+}

package/src/tile.ts

@@ -0,0 +1,89 @@
+/**
+ * XYZ tile coordinate utilities.
+ *
+ * Provides conversions between geographic coordinates (lon/lat) and
+ * tile pixel coordinates for XYZ tiled map systems. Supports various
+ * tile sizes and zoom levels.
+ *
+ * @module
+ */
+
+import { pointToTileFraction } from "@mapbox/tilebelt"
+import type { GeoBbox2D, LonLat, Tile, TilePxBbox, XY } from "./types"
+
+const RADIANS_TO_DEGREES = 180 / Math.PI
+
+function tile2lon(x: number, z: number): number {
+	return (x / 2 ** z) * 360 - 180
+}
+
+function tile2lat(y: number, z: number): number {
+	const n = Math.PI - (2 * Math.PI * y) / 2 ** z
+	return RADIANS_TO_DEGREES * Math.atan(0.5 * (Math.exp(n) - Math.exp(-n)))
+}
+
+/**
+ * Get the geographic bounding box of a tile.
+ * Returns [west, south, east, north].
+ */
+export function tileToBbox(tile: Tile): GeoBbox2D {
+	const [tx, ty, tz] = tile
+	const n = tile2lat(ty, tz)
+	const s = tile2lat(ty + 1, tz)
+	const e = tile2lon(tx + 1, tz)
+	const w = tile2lon(tx, tz)
+	return [w, s, e, n]
+}
+
+/**
+ * Convert a bounding box from geographic coordinates to tile pixel coordinates.
+ */
+export function bboxToTilePx(
+	bbox: GeoBbox2D,
+	tile: Tile,
+	tileSize = 256,
+): TilePxBbox {
+	const [minX, minY] = llToTilePx([bbox[0], bbox[3]], tile, tileSize)
+	const [maxX, maxY] = llToTilePx([bbox[2], bbox[1]], tile, tileSize)
+	return [minX, minY, maxX, maxY]
+}
+
+/**
+ * Convert a geographic coordinate to tile pixel coordinates.
+ * Returns [x, y] in pixels relative to the top-left of the tile.
+ */
+export function llToTilePx(ll: LonLat, tile: Tile, tileSize = 256): XY {
+	const [tx, ty, tz] = tile
+	const tf = pointToTileFraction(ll[0], ll[1], tz)
+	const x = (tf[0] - tx) * tileSize
+	const y = (tf[1] - ty) * tileSize
+	return [x, y]
+}
+
+/**
+ * Convert tile pixel coordinates to geographic coordinates.
+ */
+export function tilePxToLonLat(px: XY, tile: Tile, tileSize = 256): LonLat {
+	const [tx, ty, tz] = tile
+	const lon = tile2lon(px[0] / tileSize + tx, tz)
+	const lat = tile2lat(px[1] / tileSize + ty, tz)
+	return [lon, lat]
+}
+
+/**
+ * Clamp a pixel coordinate to the tile bounds and round to the nearest integer. Useful for converting a floating point pixel
+ * coordinate to a the exact tile pixel it is contained by.
+ */
+export function clampAndRoundPx(
+	px: XY,
+	tileSizeOrBbox: number | GeoBbox2D,
+): XY {
+	const [minX, minY, maxX, maxY] =
+		typeof tileSizeOrBbox === "number"
+			? [0, 0, tileSizeOrBbox, tileSizeOrBbox]
+			: tileSizeOrBbox
+	return [
+		Math.max(minX, Math.min(maxX, Math.round(px[0]))),
+		Math.max(minY, Math.min(maxY, Math.round(px[1]))),
+	]
+}

package/src/transform-bytes.ts

@@ -1,6 +1,29 @@
+/**
+ * Transform stream utilities.
+ *
+ * Helpers for piping byte arrays through TransformStreams (e.g., compression).
+ *
+ * @module
+ */
+
 import { bytesToStream } from "./bytes-to-stream"
 import { streamToBytes } from "./stream-to-bytes"
 
+/**
+ * Pipe a byte array through a TransformStream and return the result.
+ *
+ * Useful for applying compression/decompression or other transformations
+ * to byte data using the Web Streams API.
+ *
+ * @param bytes - The input bytes.
+ * @param transformStream - The transform to apply (e.g., CompressionStream).
+ * @returns A Promise resolving to the transformed bytes.
+ *
+ * @example
+ * ```ts
+ * const compressed = await transformBytes(data, new CompressionStream('gzip'))
+ * ```
+ */
 export async function transformBytes(
 	bytes: Uint8Array<ArrayBuffer>,
 	transformStream: TransformStream<

package/src/types.ts

@@ -1,9 +1,23 @@
+/**
+ * Shared type definitions used across all Osmix packages.
+ *
+ * Includes geographic primitives (LonLat, Bbox), tile coordinates,
+ * and core OSM entity types (Node, Way, Relation).
+ *
+ * @module
+ */
+
+/** Geographic coordinate as [longitude, latitude] tuple. */
 export type LonLat = [lon: number, lat: number]
+/** 2D pixel or cartesian coordinate as [x, y] tuple. */
 export type XY = [x: number, y: number]
+
+/** Geographic coordinate as object with lon/lat properties. */
 export interface ILonLat {
 	lon: number
 	lat: number
 }
+/** XYZ tile coordinate as [x, y, z] tuple. */
 export type Tile = [x: number, y: number, z: number]
 
 /**
@@ -13,7 +27,9 @@ export type LonLatToPixel = (ll: LonLat, zoom: number) => XY
 
 export type LonLatToTilePixel = (ll: LonLat, z: number, extent: number) => XY
 
-export type Rgba = [number, number, number, number] | Uint8ClampedArray
+export type Rgba =
+	| [r: number, g: number, b: number, a: number]
+	| Uint8ClampedArray
 
 /**
  * A bounding box in the format [minLon, minLat, maxLon, maxLat].
@@ -25,3 +41,79 @@ export type GeoBbox2D = [
 	maxLon: number,
 	maxLat: number,
 ]
+
+/**
+ * A pixel bounding box in the format [minX, minY, maxX, maxY]. Note: minY is north. maxY is south.
+ */
+export type TilePxBbox = [
+	minX: number,
+	minY: number,
+	maxX: number,
+	maxY: number,
+]
+
+/**
+ * Shared OSM Types
+ */
+
+export type OsmEntityType = "node" | "way" | "relation"
+
+export interface OsmInfoParsed {
+	version?: number
+	timestamp?: number
+	changeset?: number
+	uid?: number
+	user_sid?: number
+	visible?: boolean
+	user?: string
+}
+
+export interface OsmTags {
+	[key: string]: string | number
+}
+
+interface IOsmEntity {
+	id: number
+	info?: OsmInfoParsed
+	tags?: OsmTags
+}
+
+export interface OsmNode extends IOsmEntity, ILonLat {}
+
+export interface OsmWay extends IOsmEntity {
+	// OSM IDs of the nodes that make up this way
+	refs: number[]
+}
+
+export interface OsmRelationMember {
+	type: OsmEntityType
+	ref: number
+	role?: string
+}
+
+export interface OsmRelation extends IOsmEntity {
+	members: OsmRelationMember[]
+}
+
+export type OsmEntity = OsmNode | OsmWay | OsmRelation
+
+export interface OsmEntityTypeMap extends Record<OsmEntityType, IOsmEntity> {
+	node: OsmNode
+	way: OsmWay
+	relation: OsmRelation
+}
+
+/**
+ * Semantic kinds of OSM relations based on their type tag and structure.
+ */
+export type RelationKind = "area" | "line" | "point" | "logic" | "super"
+
+/**
+ * Metadata about a relation kind, including expected roles and whether member order matters.
+ */
+export interface RelationKindMetadata {
+	kind: RelationKind
+	expectedRoles?: string[]
+	orderMatters: boolean
+	description: string
+}

package/src/utils.ts

@@ -0,0 +1,79 @@
+/**
+ * General OSM entity utilities.
+ *
+ * Provides type guards, equality checks, and type detection for OSM entities.
+ * Uses deep equality checking for tags, info, and entity-specific properties.
+ *
+ * @module
+ */
+
+import { dequal } from "dequal/lite"
+import type {
+	OsmEntity,
+	OsmEntityType,
+	OsmNode,
+	OsmRelation,
+	OsmWay,
+} from "./types"
+
+/**
+ * Check if two entities have equal tags and info.
+ */
+function isTagsAndInfoEqual(a: OsmEntity, b: OsmEntity) {
+	return dequal(a.tags, b.tags) && dequal(a.info, b.info)
+}
+
+/** Type guard: check if entity is a Node. */
+export function isNode(entity: OsmEntity): entity is OsmNode {
+	return "lon" in entity && "lat" in entity
+}
+
+/** Check if two nodes are equal (position, tags, and info). */
+export function isNodeEqual(a: OsmNode, b: OsmNode) {
+	return a.lat === b.lat && a.lon === b.lon && isTagsAndInfoEqual(a, b)
+}
+
+/** Type guard: check if entity is a Way. */
+export function isWay(entity: OsmEntity): entity is OsmWay {
+	return "refs" in entity
+}
+
+/** Type guard: check if entity is a Relation. */
+export function isRelation(entity: OsmEntity): entity is OsmRelation {
+	return "members" in entity
+}
+
+/** Check if two ways are equal (refs, tags, and info). */
+export function isWayEqual(a: OsmWay, b: OsmWay) {
+	return dequal(a.refs, b.refs) && isTagsAndInfoEqual(a, b)
+}
+
+/** Check if two relations are equal (members, tags, and info). */
+export function isRelationEqual(a: OsmRelation, b: OsmRelation) {
+	return dequal(a.members, b.members) && isTagsAndInfoEqual(a, b)
+}
+
+/** Check if two entities have equal properties (type-aware comparison). */
+export function entityPropertiesEqual(a: OsmEntity, b: OsmEntity) {
+	if (!dequal(a.tags, b.tags)) return false
+	if (!dequal(a.info, b.info)) return false
+	if (isNode(a) && isNode(b)) return isNodeEqual(a, b)
+	if (isWay(a) && isWay(b)) return isWayEqual(a, b)
+	if (isRelation(a) && isRelation(b)) return isRelationEqual(a, b)
+	return false
+}
+
+/** Get the entity type ("node", "way", or "relation") for an entity. */
+export function getEntityType(entity: OsmEntity): OsmEntityType {
+	if (isNode(entity)) return "node"
+	if (isWay(entity)) return "way"
+	if (isRelation(entity)) return "relation"
+	throw Error("Unknown entity type")
+}
+
+/**
+ * Check if a relation is a multipolygon relation.
+ */
+export function isMultipolygonRelation(relation: OsmRelation): boolean {
+	return relation.tags?.["type"] === "multipolygon"
+}