@osmix/shared 0.0.1 → 0.0.6

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))
@@ -20,29 +17,36 @@ export function getFixturePath(url: string) {
 /**
  * Get file from the cache folder or download it from the URL
  */
-export async function getFixtureFile(url: string): Promise<ArrayBuffer> {
+export async function getFixtureFile(
+	url: string,
+): Promise<Uint8Array<ArrayBufferLike>> {
 	const filePath = getFixturePath(url)
 	try {
-		const file = await readFile(filePath)
-		return file.buffer as ArrayBuffer
+		const file = await Bun.file(filePath).arrayBuffer()
+		return new Uint8Array<ArrayBuffer>(file)
 	} catch (_error) {
 		const response = await fetch(url)
 		const buffer = await response.arrayBuffer()
-		await writeFile(filePath, new Uint8Array(buffer))
-		return buffer
+		const data = new Uint8Array<ArrayBuffer>(buffer)
+		await Bun.write(filePath, data)
+		return data
 	}
 }
 
 export function getFixtureFileReadStream(url: string) {
-	return Readable.toWeb(
-		createReadStream(getFixturePath(url)),
-	) as unknown as ReadableStream<ArrayBuffer>
+	return Bun.file(getFixturePath(url)).stream()
 }
 
 export function getFixtureFileWriteStream(url: string) {
-	return Writable.toWeb(
-		createWriteStream(getFixturePath(url)),
-	) as unknown as WritableStream<Uint8Array>
+	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"
+}

package/src/way-is-area.ts

@@ -0,0 +1,107 @@
+/**
+ * Area detection for OSM ways.
+ *
+ * Implements the OSM wiki heuristics for determining whether a closed way
+ * should be rendered as an area (polygon) or a closed linear feature.
+ *
+ * @see https://wiki.openstreetmap.org/wiki/Key:area
+ * @see https://wiki.openstreetmap.org/wiki/Overpass_turbo/Polygon_Features
+ *
+ * @module
+ */
+
+import type { OsmWay } from "./types"
+
+/**
+ * Tags that imply an area unless their value is exactly "no"
+ */
+const IMPLIED_ANY_VALUE_BUT_NO = new Set([
+	"amenity",
+	"boundary",
+	"building",
+	"building:part",
+	"craft",
+	// 	"golf", Seeing a lot of golf=cartpath which is not an area
+	"historic",
+	"indoor",
+	"landuse",
+	"leisure",
+	"military",
+	"office",
+	"place",
+	"public_transport",
+	"ruins",
+	"shop",
+	"tourism",
+])
+
+/**
+ * Tags that imply an area only for these specific values
+ */
+const INCLUDED_VALUE_TAGS = {
+	barrier: new Set([
+		"city_wall",
+		"ditch",
+		"hedge",
+		"retaining_wall",
+		"wall",
+		"spikes",
+	]),
+	highway: new Set(["services", "rest_area", "escape", "elevator"]),
+	power: new Set(["plant", "substation", "generator", "transformer"]),
+	railway: new Set(["station", "turntable", "roundhouse", "platform"]),
+	waterway: new Set(["riverbank", "dock", "boatyard", "dam"]),
+} as const
+
+/**
+ * Tags that imply an area unless the value is in this exclusion list
+ */
+const EXCLUDED_VALUE_TAGS = {
+	aeroway: new Set(["no", "taxiway"]),
+	"area:highway": new Set(["no"]),
+	man_made: new Set(["no", "cutline", "embankment", "pipeline"]),
+	natural: new Set(["no", "coastline", "cliff", "ridge", "arete", "tree_row"]),
+} as const
+
+/**
+ * Determine if a way is an area based on its tags and nodes.
+ *
+ * This function implements the logic described in the OSM wiki:
+ * https://wiki.openstreetmap.org/wiki/Key:area
+ * https://wiki.openstreetmap.org/wiki/Overpass_turbo/Polygon_Features
+ *
+ * @param way - The way to check.
+ * @returns `true` if the way is an area, `false` otherwise.
+ */
+export function wayIsArea(way?: OsmWay): boolean {
+	if (!way) return false
+	const { refs, tags } = way
+	if (refs.length < 3) return false
+	if (refs[0] !== refs[refs.length - 1]) return false
+
+	// End refs are equal, no tags, assume it is an area.
+	if (!tags || Object.keys(tags).length === 0) return true
+
+	// Explicit override
+	if ("area" in tags) return tags["area"] !== "no"
+
+	// Tags that count if value is NOT "no"
+	for (const key of IMPLIED_ANY_VALUE_BUT_NO) {
+		const v = tags[key]
+		if (v && v !== "no") return true
+	}
+
+	// Tags that are area only for INCLUDED values
+	for (const [key, included] of Object.entries(INCLUDED_VALUE_TAGS)) {
+		const v = tags[key]
+		if (v && included.has(`${v}`)) return true
+	}
+
+	// Tags that are area unless value is excluded
+	for (const [key, excluded] of Object.entries(EXCLUDED_VALUE_TAGS)) {
+		const v = tags[key]
+		if (v && !excluded.has(`${v}`)) return true
+	}
+
+	return false
+}

package/src/zigzag.ts

@@ -0,0 +1,42 @@
+/**
+ * Zigzag encoding/decoding for protobuf-style varints.
+ *
+ * Zigzag encoding converts signed integers to unsigned by interleaving
+ * negative and positive values: 0, -1, 1, -2, 2, ... This allows efficient
+ * varint encoding of small negative numbers.
+ *
+ * @module
+ */
+
+/**
+ * Zigzag encode a number using arithmetic operations.
+ * This supports the full safe integer range (up to Number.MAX_SAFE_INTEGER).
+ * Formula: n < 0 ? -2*n - 1 : 2*n
+ *
+ * Used for encoding IDs in vector tiles to convert negative IDs to positive numbers
+ * for unsigned varint encoding.
+ */
+export function zigzag(num: number): number {
+	return num < 0 ? -2 * num - 1 : 2 * num
+}
+
+/**
+ * Zigzag encode using bitwise operations (for geometry deltas only).
+ * This is faster but limited to 32-bit signed integers.
+ * Used for small coordinate deltas in geometry encoding.
+ */
+export function zigzag32(num: number): number {
+	return (num << 1) ^ (num >> 31)
+}
+
+/**
+ * Decode zigzag-encoded number back to original value.
+ * Zigzag encoding is used to convert negative IDs to positive numbers for unsigned varint
+ * encoding in vector tiles. Uses arithmetic-based decoding to support the full safe integer range.
+ *
+ * Formula: (encoded & 1) === 1 ? -(encoded + 1) / 2 : encoded / 2
+ */
+export function decodeZigzag(encoded: number): number {
+	// Check if encoded is odd (negative) using bitwise, then use arithmetic
+	return (encoded & 1) === 1 ? -(encoded + 1) / 2 : encoded / 2
+}

package/test/haversine-distance.test.ts

@@ -1,8 +1,8 @@
-import { assert, test } from "vitest"
+import { expect, test } from "bun:test"
 import { haversineDistance } from "../src/haversine-distance"
 
 test("haversineDistance", () => {
 	const p1: [number, number] = [-75.343, 39.984]
 	const p2: [number, number] = [-75.534, 39.123]
-	assert.closeTo(haversineDistance(p1, p2), 97129.2211, 0.0001)
+	expect(haversineDistance(p1, p2)).toBeCloseTo(97129.2211, 3)
 })