@osmix/shared 0.0.2 → 0.0.7

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)
 })

package/test/relation-kind.test.ts

@@ -0,0 +1,426 @@
+import { describe, expect, it } from "bun:test"
+import {
+	buildRelationLineStrings,
+	collectRelationPoints,
+	getRelationKind,
+	getRelationKindMetadata,
+	isAreaRelation,
+	isLineRelation,
+	isLogicRelation,
+	isPointRelation,
+	isSuperRelation,
+	resolveRelationMembers,
+} from "../src/relation-kind"
+import type { LonLat, OsmRelation, OsmWay } from "../src/types"
+
+describe("relation-kind", () => {
+	describe("getRelationKind", () => {
+		it("identifies multipolygon as area", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "multipolygon" },
+				members: [],
+			}
+			expect(getRelationKind(relation)).toBe("area")
+		})
+
+		it("identifies boundary as area", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "boundary" },
+				members: [],
+			}
+			expect(getRelationKind(relation)).toBe("area")
+		})
+
+		it("identifies route as line", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "route" },
+				members: [],
+			}
+			expect(getRelationKind(relation)).toBe("line")
+		})
+
+		it("identifies multilinestring as line", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "multilinestring" },
+				members: [],
+			}
+			expect(getRelationKind(relation)).toBe("line")
+		})
+
+		it("identifies multipoint as point", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "multipoint" },
+				members: [],
+			}
+			expect(getRelationKind(relation)).toBe("point")
+		})
+
+		it("identifies restriction as logic", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "restriction" },
+				members: [],
+			}
+			expect(getRelationKind(relation)).toBe("logic")
+		})
+
+		it("identifies super-relation by having relation members", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "collection" },
+				members: [{ type: "relation", ref: 2 }],
+			}
+			expect(getRelationKind(relation)).toBe("super")
+		})
+
+		it("defaults to logic for untyped relations", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				members: [],
+			}
+			expect(getRelationKind(relation)).toBe("logic")
+		})
+
+		it("handles case-insensitive type tags", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "MULTIPOLYGON" },
+				members: [],
+			}
+			expect(getRelationKind(relation)).toBe("area")
+		})
+	})
+
+	describe("getRelationKindMetadata", () => {
+		it("returns correct metadata for area relations", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "multipolygon" },
+				members: [],
+			}
+			const metadata = getRelationKindMetadata(relation)
+			expect(metadata.kind).toBe("area")
+			expect(metadata.expectedRoles).toEqual(["outer", "inner"])
+			expect(metadata.orderMatters).toBe(false)
+		})
+
+		it("returns correct metadata for line relations", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "route" },
+				members: [],
+			}
+			const metadata = getRelationKindMetadata(relation)
+			expect(metadata.kind).toBe("line")
+			expect(metadata.orderMatters).toBe(true)
+		})
+	})
+
+	describe("isAreaRelation", () => {
+		it("returns true for multipolygon", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "multipolygon" },
+				members: [],
+			}
+			expect(isAreaRelation(relation)).toBe(true)
+		})
+
+		it("returns false for route", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "route" },
+				members: [],
+			}
+			expect(isAreaRelation(relation)).toBe(false)
+		})
+	})
+
+	describe("isLineRelation", () => {
+		it("returns true for route", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "route" },
+				members: [],
+			}
+			expect(isLineRelation(relation)).toBe(true)
+		})
+
+		it("returns true for multilinestring", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "multilinestring" },
+				members: [],
+			}
+			expect(isLineRelation(relation)).toBe(true)
+		})
+	})
+
+	describe("isPointRelation", () => {
+		it("returns true for multipoint", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "multipoint" },
+				members: [],
+			}
+			expect(isPointRelation(relation)).toBe(true)
+		})
+	})
+
+	describe("isSuperRelation", () => {
+		it("returns true for relation with relation members", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "collection" },
+				members: [{ type: "relation", ref: 2 }],
+			}
+			expect(isSuperRelation(relation)).toBe(true)
+		})
+
+		it("returns false for relation without relation members", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "route" },
+				members: [{ type: "way", ref: 2 }],
+			}
+			expect(isSuperRelation(relation)).toBe(false)
+		})
+	})
+
+	describe("isLogicRelation", () => {
+		it("returns true for restriction", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "restriction" },
+				members: [],
+			}
+			expect(isLogicRelation(relation)).toBe(true)
+		})
+	})
+
+	describe("buildRelationLineStrings", () => {
+		it("builds linestrings from connected ways", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "route" },
+				members: [
+					{ type: "way", ref: 1 },
+					{ type: "way", ref: 2 },
+				],
+			}
+
+			const way1: OsmWay = { id: 1, refs: [1, 2] }
+			const way2: OsmWay = { id: 2, refs: [2, 3] }
+
+			const getWay = (id: number) => {
+				if (id === 1) return way1
+				if (id === 2) return way2
+				return null
+			}
+
+			const getNodeCoordinates = (id: number) => {
+				const coords: Record<number, [number, number]> = {
+					1: [0.0, 0.0],
+					2: [1.0, 0.0],
+					3: [2.0, 0.0],
+				}
+				return coords[id]
+			}
+
+			const lineStrings = buildRelationLineStrings(
+				relation,
+				getWay,
+				getNodeCoordinates,
+			)
+			expect(lineStrings).toHaveLength(1)
+			expect(lineStrings[0]).toHaveLength(3)
+		})
+
+		it("handles disconnected ways as separate linestrings", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "route" },
+				members: [
+					{ type: "way", ref: 1 },
+					{ type: "way", ref: 2 },
+				],
+			}
+
+			const way1: OsmWay = { id: 1, refs: [1, 2] }
+			const way2: OsmWay = { id: 2, refs: [3, 4] }
+
+			const getWay = (id: number) => {
+				if (id === 1) return way1
+				if (id === 2) return way2
+				return null
+			}
+
+			const getNodeCoordinates = (id: number) => {
+				const coords: Record<number, [number, number]> = {
+					1: [0.0, 0.0],
+					2: [1.0, 0.0],
+					3: [10.0, 10.0],
+					4: [11.0, 10.0],
+				}
+				return coords[id]
+			}
+
+			const lineStrings = buildRelationLineStrings(
+				relation,
+				getWay,
+				getNodeCoordinates,
+			)
+			expect(lineStrings.length).toBeGreaterThanOrEqual(2)
+		})
+	})
+
+	describe("collectRelationPoints", () => {
+		it("collects point coordinates from node members", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "multipoint" },
+				members: [
+					{ type: "node", ref: 1 },
+					{ type: "node", ref: 2 },
+					{ type: "way", ref: 10 }, // Should be ignored
+				],
+			}
+
+			const getNodeCoordinates = (id: number) => {
+				const coords: Record<number, [number, number]> = {
+					1: [0.0, 0.0],
+					2: [1.0, 1.0],
+				}
+				return coords[id]
+			}
+
+			const points = collectRelationPoints(relation, getNodeCoordinates)
+			expect(points).toHaveLength(2)
+			expect(points[0]).toEqual([0.0, 0.0])
+			expect(points[1]).toEqual([1.0, 1.0])
+		})
+
+		it("handles missing node coordinates", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "multipoint" },
+				members: [
+					{ type: "node", ref: 1 },
+					{ type: "node", ref: 2 },
+				],
+			}
+
+			const getNodeCoordinates = (id: number): LonLat | undefined => {
+				if (id === 1) return [0.0, 0.0] as LonLat
+				return undefined // Missing coordinate
+			}
+
+			const points = collectRelationPoints(relation, getNodeCoordinates)
+			expect(points).toHaveLength(1)
+		})
+	})
+
+	describe("resolveRelationMembers", () => {
+		it("resolves direct members", () => {
+			const relation: OsmRelation = {
+				id: 1,
+				tags: { type: "collection" },
+				members: [
+					{ type: "node", ref: 1 },
+					{ type: "way", ref: 10 },
+				],
+			}
+
+			const getRelation = () => null
+
+			const resolved = resolveRelationMembers(relation, getRelation)
+			expect(resolved.nodes).toEqual([1])
+			expect(resolved.ways).toEqual([10])
+			expect(resolved.relations).toEqual([])
+		})
+
+		it("resolves nested relation members", () => {
+			const relation1: OsmRelation = {
+				id: 1,
+				tags: { type: "collection" },
+				members: [
+					{ type: "relation", ref: 2 },
+					{ type: "node", ref: 1 },
+				],
+			}
+
+			const relation2: OsmRelation = {
+				id: 2,
+				tags: { type: "collection" },
+				members: [
+					{ type: "way", ref: 10 },
+					{ type: "node", ref: 2 },
+				],
+			}
+
+			const getRelation = (id: number) => {
+				if (id === 2) return relation2
+				return null
+			}
+
+			const resolved = resolveRelationMembers(relation1, getRelation)
+			expect(resolved.nodes).toContain(1)
+			expect(resolved.nodes).toContain(2)
+			expect(resolved.ways).toContain(10)
+			expect(resolved.relations).toContain(2)
+		})
+
+		it("detects cycles and prevents infinite recursion", () => {
+			const relation1: OsmRelation = {
+				id: 1,
+				tags: { type: "collection" },
+				members: [{ type: "relation", ref: 2 }],
+			}
+
+			const relation2: OsmRelation = {
+				id: 2,
+				tags: { type: "collection" },
+				members: [{ type: "relation", ref: 1 }], // Circular reference
+			}
+
+			const getRelation = (id: number) => {
+				if (id === 1) return relation1
+				if (id === 2) return relation2
+				return null
+			}
+
+			const resolved = resolveRelationMembers(relation1, getRelation, 10)
+			// Should not crash and should include relation2 but not recurse infinitely
+			expect(resolved.relations).toContain(2)
+		})
+
+		it("respects maxDepth limit", () => {
+			const relation1: OsmRelation = {
+				id: 1,
+				tags: { type: "collection" },
+				members: [{ type: "relation", ref: 2 }],
+			}
+
+			const relation2: OsmRelation = {
+				id: 2,
+				tags: { type: "collection" },
+				members: [{ type: "node", ref: 100 }],
+			}
+
+			const getRelation = (id: number) => {
+				if (id === 1) return relation1
+				if (id === 2) return relation2
+				return null
+			}
+
+			const resolved = resolveRelationMembers(relation1, getRelation, 0)
+			// Should not resolve nested relation when maxDepth is 0
+			expect(resolved.nodes).not.toContain(100)
+		})
+	})
+})