@osmix/shared 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @osmix/shared
+
+## 0.0.1
+
+### Patch Changes
+
+- Initial release

package/README.md

@@ -0,0 +1,30 @@
+# @osmix/shared
+
+`@osmix/shared` exposes small geometry helpers that packages across the Osmix workspace rely on.
+
+## Highlights
+
+- `haversineDistance` – Compute great-circle distances between lon/lat pairs in meters.
+- `clipPolyline` – Re-export of [`lineclip`](https://github.com/mourner/lineclip) for clipping projected polylines to axis-aligned bounding boxes with types added.
+
+## Installation
+
+```sh
+npm install @osmix/shared
+```
+
+## Usage
+
+```ts
+import { haversineDistance, clipPolyline } from "@osmix/shared"
+
+const meters = haversineDistance([-122.33, 47.61], [-122.30, 47.63])
+
+const segments = clipPolyline(
+	[
+		[-122.33, 47.61],
+		[-122.31, 47.62],
+	],
+	[-122.40, 47.50, -122.20, 47.70],
+)
+```

package/package.json

@@ -0,0 +1,52 @@
+{
+	"$schema": "https://json.schemastore.org/package",
+	"name": "@osmix/shared",
+	"type": "module",
+	"version": "0.0.1",
+	"description": "Shared utilities for Osmix",
+	"exports": {
+		"./*": "./src/*.ts",
+		"./tsconfig/base.json": "./tsconfig/base.json",
+		"./tsconfig/test.json": "./tsconfig/test.json",
+		"./tsconfig/app.json": "./tsconfig/app.json",
+		"./test/*": "./src/test/*.ts"
+	},
+	"publishConfig": {
+		"access": "public",
+		"exports": {
+			"./*": {
+				"import": "./dist/*.js",
+				"types": "./dist/*.d.ts"
+			}
+		},
+		"files": [
+			"dist",
+			"README.md",
+			"LICENSE"
+		]
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/conveyal/osmix.git"
+	},
+	"homepage": "https://github.com/conveyal/osmix#readme",
+	"bugs": {
+		"url": "https://github.com/conveyal/osmix/issues"
+	},
+	"sideEffects": false,
+	"scripts": {
+		"build": "tsc",
+		"bench": "vitest bench",
+		"test": "vitest",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"typescript": "catalog:",
+		"vitest": "catalog:"
+	},
+	"dependencies": {
+		"@mapbox/sphericalmercator": "catalog:",
+		"lineclip": "^2.0.0"
+	}
+}

package/src/assert.ts

@@ -0,0 +1,11 @@
+/**
+ * Short utility for checking index access.
+ */
+export function assertValue<T>(
+	value?: T,
+	message?: string,
+): asserts value is NonNullable<T> {
+	if (value === undefined || value === null) {
+		throw Error(message ?? "Value is undefined or null")
+	}
+}

package/src/bytes-to-stream.ts

@@ -0,0 +1,8 @@
+export function bytesToStream(bytes: Uint8Array<ArrayBuffer>) {
+	return new ReadableStream<Uint8Array<ArrayBuffer>>({
+		start(controller) {
+			controller.enqueue(bytes)
+			controller.close()
+		},
+	})
+}

package/src/concat-bytes.ts

@@ -0,0 +1,15 @@
+/**
+ * Concatenates multiple `Uint8Array` segments into a contiguous array.
+ */
+export function concatBytes(
+	parts: Uint8Array<ArrayBuffer>[],
+): Uint8Array<ArrayBuffer> {
+	const total = parts.reduce((n, p) => n + p.length, 0)
+	const out = new Uint8Array<ArrayBuffer>(new ArrayBuffer(total))
+	let offset = 0
+	for (const p of parts) {
+		out.set(p, offset)
+		offset += p.length
+	}
+	return out
+}

package/src/haversine-distance.ts

@@ -0,0 +1,21 @@
+/**
+ * Calculate the haversine distance between two LonLat points.
+ * @param p1 - The first point
+ * @param p2 - The second point
+ * @returns The haversine distance in meters
+ */
+export function haversineDistance(
+	p1: [number, number],
+	p2: [number, number],
+): number {
+	const R = 6371008.8 // Earth's radius in meters
+	const dLat = (p2[1] - p1[1]) * (Math.PI / 180)
+	const dLon = (p2[0] - p1[0]) * (Math.PI / 180)
+	const lat1 = p1[1] * (Math.PI / 180)
+	const lat2 = p2[1] * (Math.PI / 180)
+	const a =
+		Math.sin(dLat / 2) ** 2 +
+		Math.sin(dLon / 2) ** 2 * Math.cos(lat1) * Math.cos(lat2)
+	const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
+	return R * c
+}

package/src/lineclip.d.ts

@@ -0,0 +1,11 @@
+declare module "lineclip" {
+	export function clipPolyline(
+		points: [number, number][],
+		bbox: [number, number, number, number],
+	): [number, number][][]
+
+	export function clipPolygon(
+		points: [number, number][],
+		bbox: [number, number, number, number],
+	): [number, number][]
+}

package/src/lineclip.ts

@@ -0,0 +1,2 @@
+/// <reference path="./lineclip.d.ts" />
+export { clipPolygon, clipPolyline } from "lineclip"

package/src/spherical-mercator.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest"
+import SphericalMercatorTile from "./spherical-mercator"
+import type { Tile } from "./types"
+
+function lonLatForPixel(
+	merc: SphericalMercatorTile,
+	tileIndex: Tile,
+	tileSize: number,
+	px: number,
+	py: number,
+): [number, number] {
+	const [x, y, z] = tileIndex
+	return merc.ll([x * tileSize + px, y * tileSize + py], z) as [number, number]
+}
+
+describe("SphericalMercatorTile", () => {
+	it("projects lon/lat to tile-local pixels", () => {
+		const tile: Tile = [300, 300, 10]
+		const [tx, ty, tz] = tile
+		const tileSize = 256
+		const merc = new SphericalMercatorTile({ size: tileSize, tile })
+
+		const insideLonLat = lonLatForPixel(merc, tile, tileSize, 32, 16)
+		expect(merc.llToTilePx(insideLonLat)).toEqual([32, 16])
+
+		const outsideTopLeft = merc.ll(
+			[tx * tileSize - 10, ty * tileSize - 10],
+			tz,
+		) as [number, number]
+		expect(outsideTopLeft).toEqual([-74.54498291015625, 59.54128017205441])
+		expect(merc.llToTilePx(outsideTopLeft)).toEqual([-10, -10])
+
+		const outsideBottomRight = merc.ll(
+			[(tx + 1) * tileSize + 10, (ty + 1) * tileSize + 10],
+			tz,
+		) as [number, number]
+		expect(merc.llToTilePx(outsideBottomRight, tile)).toEqual([
+			tileSize + 10,
+			tileSize + 10,
+		])
+	})
+})

package/src/spherical-mercator.ts

@@ -0,0 +1,42 @@
+import { SphericalMercator } from "@mapbox/sphericalmercator"
+import type { GeoBbox2D, LonLat, Tile, XY } from "./types"
+
+/**
+ * Extends the SphericalMercator class to provide tile-local pixel coordinate calculations and clamping.
+ */
+export default class SphericalMercatorTile extends SphericalMercator {
+	tileSize: number
+	tile?: Tile
+	constructor(
+		options: ConstructorParameters<typeof SphericalMercator>[0] & {
+			tile?: Tile
+		},
+	) {
+		super(options)
+		this.tile = options?.tile
+		this.tileSize = options?.size ?? 256
+	}
+
+	llToTilePx(ll: LonLat, tile?: Tile): XY {
+		if (tile == null && this.tile == null)
+			throw Error("Tile must be set on construction or passed as an argument.")
+		const [tx, ty, tz] = (tile ?? this.tile)!
+		const merc = this.px(ll, tz)
+		const x = merc[0] - tx * this.tileSize
+		const y = merc[1] - ty * this.tileSize
+		return [x, y]
+	}
+
+	clampAndRoundPx(px: XY, bbox?: GeoBbox2D): XY {
+		const [minX, minY, maxX, maxY] = bbox ?? [
+			0,
+			0,
+			this.tileSize,
+			this.tileSize,
+		]
+		return [
+			Math.max(minX, Math.min(maxX, Math.round(px[0]))),
+			Math.max(minY, Math.min(maxY, Math.round(px[1]))),
+		]
+	}
+}

package/src/stream-to-bytes.ts

@@ -0,0 +1,20 @@
+import { concatBytes } from "./concat-bytes"
+
+export async function streamToBytes(
+	stream: ReadableStream<Uint8Array<ArrayBuffer>>,
+): Promise<Uint8Array<ArrayBuffer>> {
+	const reader = stream.getReader()
+	const chunks: Uint8Array<ArrayBuffer>[] = []
+
+	while (true) {
+		const { done, value } = await reader.read()
+
+		if (done) {
+			break
+		}
+
+		chunks.push(value)
+	}
+
+	return concatBytes(chunks)
+}

package/src/test/fixtures.ts

@@ -0,0 +1,198 @@
+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))
+const ROOT_DIR = resolve(__dirname, "../../../../")
+const FIXTURES_DIR = resolve(ROOT_DIR, "fixtures")
+
+export function getFixturePath(url: string) {
+	if (url.startsWith("http")) {
+		const fileName = url.split("/").pop()
+		if (!fileName) throw new Error("Invalid URL")
+		return join(FIXTURES_DIR, fileName)
+	}
+	return join(FIXTURES_DIR, url)
+}
+
+/**
+ * Get file from the cache folder or download it from the URL
+ */
+export async function getFixtureFile(url: string): Promise<ArrayBuffer> {
+	const filePath = getFixturePath(url)
+	try {
+		const file = await readFile(filePath)
+		return file.buffer as ArrayBuffer
+	} catch (_error) {
+		const response = await fetch(url)
+		const buffer = await response.arrayBuffer()
+		await writeFile(filePath, new Uint8Array(buffer))
+		return buffer
+	}
+}
+
+export function getFixtureFileReadStream(url: string) {
+	return Readable.toWeb(
+		createReadStream(getFixturePath(url)),
+	) as unknown as ReadableStream<ArrayBuffer>
+}
+
+export function getFixtureFileWriteStream(url: string) {
+	return Writable.toWeb(
+		createWriteStream(getFixturePath(url)),
+	) as unknown as WritableStream<Uint8Array>
+}
+
+export type PbfFixture = {
+	url: string
+	bbox: {
+		bottom: number
+		top: number
+		left: number
+		right: number
+	}
+	nodesWithTags: number
+	nodes: number
+	ways: number
+	relations: number
+	node0: {
+		lat: number
+		lon: number
+		id: number
+	}
+	way0: number
+	relation0: number
+	uniqueStrings: number
+	primitiveGroups: number
+}
+
+/**
+ * List of PBFs and their metadata used for testing. Cached locally in the top level fixtures directory so they can
+ * be used across packages and apps.
+ *
+ * `monaco.pbf` is checked into the repository so it can be used in CI without causing repeated downloads.
+ *
+ * Below, we export a subset of the PBFs that we want to use for current tests.
+ */
+const monacoPbfFixture: PbfFixture = {
+	url: "monaco.pbf",
+	bbox: {
+		bottom: 43.7232244,
+		top: 43.7543687,
+		left: 7.4053929,
+		right: 7.4447259,
+	},
+	nodesWithTags: 1_254,
+	nodes: 14_286,
+	ways: 3_346,
+	relations: 46,
+	node0: {
+		lat: 43.7371175,
+		lon: 7.4229093,
+		id: 21911883,
+	},
+	way0: 4097656,
+	relation0: 3410831,
+	uniqueStrings: 1_060,
+	primitiveGroups: 7,
+}
+
+export const AllPBFs: Record<string, PbfFixture> = {
+	monaco: monacoPbfFixture,
+	montenegro: {
+		url: "https://download.geofabrik.de/europe/montenegro-250101.osm.pbf",
+		bbox: {
+			bottom: 41.61621,
+			top: 43.562169,
+			left: 18.17282,
+			right: 20.358827,
+		},
+		nodesWithTags: 63_321,
+		nodes: 3_915_383,
+		ways: 321_330,
+		relations: 5_501,
+		node0: {
+			lat: 42.1982436,
+			lon: 18.9656482,
+			id: 26860768,
+		},
+		way0: 123,
+		relation0: 123,
+		uniqueStrings: 55_071,
+		primitiveGroups: 532,
+	},
+	croatia: {
+		url: "https://download.geofabrik.de/europe/croatia-250101.osm.pbf",
+		bbox: {
+			bottom: 42.16483,
+			top: 46.557562,
+			left: 13.08916,
+			right: 19.459968,
+		},
+		nodesWithTags: 481_613,
+		nodes: 23_063_621,
+		ways: 2_315_247,
+		relations: 39_098,
+		primitiveGroups: 3_178,
+		node0: {
+			lat: 42.9738772,
+			lon: 17.021989,
+			id: 4_511_653,
+		},
+		way0: 123,
+		relation0: 123,
+		uniqueStrings: 269_315,
+	},
+	italy: {
+		url: "https://download.geofabrik.de/europe/italy-250101.osm.pbf",
+		bbox: {
+			bottom: 35.07638,
+			left: 6.602696,
+			right: 19.12499,
+			top: 47.100045,
+		},
+		nodesWithTags: 1_513_303,
+		nodes: 250_818_620,
+		ways: 27_837_987,
+		relations: 100_000,
+		primitiveGroups: 34_901,
+		node0: {
+			lat: 41.9033,
+			lon: 12.4534,
+			id: 1,
+		},
+		way0: 123,
+		relation0: 123,
+		uniqueStrings: 3190,
+	},
+	washington: {
+		url: "https://download.geofabrik.de/north-america/us/washington-250101.osm.pbf",
+		bbox: {
+			bottom: 45.53882,
+			top: 49.00708,
+			left: -126.7423,
+			right: -116.911526,
+		},
+		nodesWithTags: 1_513_303,
+		nodes: 43_032_447,
+		ways: 4_541_651,
+		relations: 44_373,
+		node0: {
+			lat: 47.64248,
+			lon: -122.3196898,
+			id: 29445653,
+		},
+		way0: 123,
+		relation0: 123,
+		uniqueStrings: 598_993,
+		primitiveGroups: 34_901,
+	},
+} as const
+
+/**
+ * A subset of the PBFs that we want to use for current tests. Do not check in changes to this list as it will cause CI to
+ * attempt to download PBFs that are not checked into the repository.
+ */
+export const PBFs: Record<string, PbfFixture> = { monaco: monacoPbfFixture }

package/src/transform-bytes.ts

@@ -0,0 +1,12 @@
+import { bytesToStream } from "./bytes-to-stream"
+import { streamToBytes } from "./stream-to-bytes"
+
+export async function transformBytes(
+	bytes: Uint8Array<ArrayBuffer>,
+	transformStream: TransformStream<
+		Uint8Array<ArrayBuffer>,
+		Uint8Array<ArrayBuffer>
+	>,
+): Promise<Uint8Array<ArrayBuffer>> {
+	return streamToBytes(bytesToStream(bytes).pipeThrough(transformStream))
+}

package/src/types.ts

@@ -0,0 +1,27 @@
+export type LonLat = [lon: number, lat: number]
+export type XY = [x: number, y: number]
+export interface ILonLat {
+	lon: number
+	lat: number
+}
+export type Tile = [x: number, y: number, z: number]
+
+/**
+ * Project LonLat to pixels
+ */
+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
+
+/**
+ * A bounding box in the format [minLon, minLat, maxLon, maxLat].
+ * GeoJSON.BBox allows for 3D bounding boxes, but we use tools that expect 2D bounding boxes.
+ */
+export type GeoBbox2D = [
+	minLon: number,
+	minLat: number,
+	maxLon: number,
+	maxLat: number,
+]

package/test/haversine-distance.test.ts

@@ -0,0 +1,8 @@
+import { assert, test } from "vitest"
+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)
+})

package/tsconfig/app.json

@@ -0,0 +1,24 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"extends": "./base.json",
+	"compilerOptions": {
+		"noEmit": true,
+		"lib": [
+			"ESNext",
+			"ESNext.AsyncIterable",
+			"ESNext.Array",
+			"ESNext.Intl",
+			"ESNext.Symbol",
+			"DOM",
+			"DOM.Iterable"
+		],
+		"target": "es2024",
+		"jsx": "react-jsx",
+		"allowImportingTsExtensions": true,
+
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noPropertyAccessFromIndexSignature": false,
+		"noUncheckedIndexedAccess": false
+	}
+}

package/tsconfig/base.json

@@ -0,0 +1,28 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"display": "@osmix/tsconfig/base",
+	"compilerOptions": {
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true,
+		"noEmitOnError": true,
+
+		"lib": ["ESNext"],
+		"target": "es2024",
+		"module": "preserve",
+		"moduleDetection": "force",
+
+		"moduleResolution": "bundler",
+		"verbatimModuleSyntax": true,
+		"isolatedModules": true,
+		"erasableSyntaxOnly": true,
+		"skipLibCheck": true,
+
+		"strict": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"noPropertyAccessFromIndexSignature": true
+	}
+}

package/tsconfig/test.json

@@ -0,0 +1,13 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"display": "@osmix/tsconfig/test",
+	"extends": "./base.json",
+	"compilerOptions": {
+		"noEmit": true,
+
+		"noUncheckedIndexedAccess": false,
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noPropertyAccessFromIndexSignature": false
+	}
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"extends": "./tsconfig/base.json",
+	"include": ["src", "test"],
+	"exclude": ["node_modules", "dist"],
+	"compilerOptions": {
+		"outDir": "./dist"
+	}
+}