@procedures/geo 0.2.3 → 0.4.0

package/src/geo.ts

@@ -24,19 +24,34 @@ export const NOMINATIM_URL = "https://nominatim.openstreetmap.org";
 /** The public OSRM demonstration server. It has a fair-use limit. A self-hosted OSRM has the same API. */
 export const OSRM_URL = "https://router.project-osrm.org";
 
+/**
+ * The part of `fetch` that this package uses. A host or a test can give its own function, for
+ * example a fetch with a cache or a recorder. The default is the global `fetch`.
+ */
+export type FetchJson = (
+  url: string,
+  init: { headers: Record<string, string>; signal: AbortSignal }
+) => Promise<{ ok: boolean; status: number; json(): Promise<unknown> }>;
+
 /** This function gets a JSON document, with a time limit and the signal of the call. */
 export async function getJson(
   url: string,
-  options: { timeoutMs: number; signal?: AbortSignal | undefined; headers?: Record<string, string> },
+  options: {
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+    headers?: Record<string, string>;
+    fetch?: FetchJson | undefined;
+  },
   service: string
 ): Promise<unknown> {
   const signals = [AbortSignal.timeout(options.timeoutMs), ...(options.signal ? [options.signal] : [])];
-  let response: Response;
+  const fetchJson: FetchJson = options.fetch ?? fetch;
+  let response: Awaited<ReturnType<FetchJson>>;
   try {
-    response = await fetch(url, { signal: AbortSignal.any(signals), headers: { accept: "application/json", ...options.headers } });
+    response = await fetchJson(url, { signal: AbortSignal.any(signals), headers: { accept: "application/json", ...options.headers } });
   } catch (error) {
     const reason = (error as { name?: string }).name === "TimeoutError" ? `no answer in ${options.timeoutMs} ms` : "the request failed";
-    throw new Error(`${service} did not answer: ${reason}`);
+    throw new Error(`${service} did not answer: ${reason}`, { cause: error });
   }
   if (!response.ok) throw new Error(`${service} gave HTTP ${response.status}`);
   return response.json();
@@ -54,13 +69,14 @@ export async function geocode(
     baseUrl?: string | undefined;
     timeoutMs: number;
     signal?: AbortSignal | undefined;
+    fetch?: FetchJson | undefined;
   }
 ): Promise<GeocodeResult | undefined> {
   const params = new URLSearchParams({ format: "jsonv2", limit: "1", q: query });
   if (options.countryCodes !== undefined) params.set("countrycodes", options.countryCodes);
   const rows = (await getJson(
     `${options.baseUrl ?? NOMINATIM_URL}/search?${params.toString()}`,
-    { timeoutMs: options.timeoutMs, signal: options.signal, headers: { "user-agent": options.userAgent } },
+    { timeoutMs: options.timeoutMs, signal: options.signal, headers: { "user-agent": options.userAgent }, fetch: options.fetch },
     "Nominatim"
   )) as Array<{ lat?: string; lon?: string; display_name?: string }>;
   const first = Array.isArray(rows) ? rows[0] : undefined;
@@ -74,11 +90,11 @@ export async function geocode(
 export async function drivingRoute(
   from: Point,
   to: Point,
-  options: { baseUrl?: string | undefined; timeoutMs: number; signal?: AbortSignal | undefined }
+  options: { baseUrl?: string | undefined; timeoutMs: number; signal?: AbortSignal | undefined; fetch?: FetchJson | undefined }
 ): Promise<RouteResult> {
   const body = (await getJson(
     `${options.baseUrl ?? OSRM_URL}/route/v1/driving/${from.lon},${from.lat};${to.lon},${to.lat}?overview=false`,
-    { timeoutMs: options.timeoutMs, signal: options.signal },
+    { timeoutMs: options.timeoutMs, signal: options.signal, fetch: options.fetch },
     "OSRM"
   )) as { code?: string; routes?: Array<{ duration?: number; distance?: number }> };
   const route = body.routes?.[0];

package/src/geohash.ts

@@ -0,0 +1,97 @@
+/**
+ * The geohash of a point, and the cell of a geohash. A geohash interleaves the bits of the
+ * longitude and the latitude, and writes five bits as one character of a base-32 alphabet.
+ */
+
+import type { Point } from "./geo.js";
+
+/** The base-32 alphabet of the geohash. It has no `a`, `i`, `l` or `o`. */
+export const GEOHASH_ALPHABET = "0123456789bcdefghjkmnpqrstuvwxyz";
+
+/** The precision (number of characters) when the caller gives none. At the equator, a cell of 7 characters is approximately 153 m by 153 m. */
+export const DEFAULT_GEOHASH_PRECISION = 7;
+
+/** The maximum precision. A cell of 12 characters is smaller than 4 cm by 4 cm. */
+export const MAX_GEOHASH_PRECISION = 12;
+
+/** The cell of a geohash: its edges, in degrees, and its center. */
+export interface GeohashCell {
+  readonly south: number;
+  readonly west: number;
+  readonly north: number;
+  readonly east: number;
+  readonly center: Point;
+}
+
+const checkPoint = (point: Point): void => {
+  if (!Number.isFinite(point.lat) || point.lat < -90 || point.lat > 90) throw new RangeError(`The latitude ${point.lat} is not from -90 to 90`);
+  if (!Number.isFinite(point.lon) || point.lon < -180 || point.lon > 180) throw new RangeError(`The longitude ${point.lon} is not from -180 to 180`);
+};
+
+/**
+ * This function gives the geohash of a point. The first bit is the longitude. A coordinate on
+ * the middle of a range goes to the upper half.
+ */
+export const geohash = (point: Point, precision: number = DEFAULT_GEOHASH_PRECISION): string => {
+  checkPoint(point);
+  if (!Number.isInteger(precision) || precision < 1 || precision > MAX_GEOHASH_PRECISION) {
+    throw new RangeError(`The precision ${precision} is not an integer from 1 to ${MAX_GEOHASH_PRECISION}`);
+  }
+  const latRange = [-90, 90] as [number, number];
+  const lonRange = [-180, 180] as [number, number];
+  let hash = "";
+  let bits = 0;
+  let value = 0;
+  let evenBit = true;
+  while (hash.length < precision) {
+    const range = evenBit ? lonRange : latRange;
+    const coordinate = evenBit ? point.lon : point.lat;
+    const mid = (range[0] + range[1]) / 2;
+    if (coordinate >= mid) {
+      value = (value << 1) | 1;
+      range[0] = mid;
+    } else {
+      value <<= 1;
+      range[1] = mid;
+    }
+    evenBit = !evenBit;
+    bits += 1;
+    if (bits === 5) {
+      hash += GEOHASH_ALPHABET[value];
+      bits = 0;
+      value = 0;
+    }
+  }
+  return hash;
+};
+
+/**
+ * This function gives the cell of a geohash: its edges and its center. Upper case letters are
+ * correct. It throws a `RangeError` for a character that is not in the alphabet.
+ */
+export const decodeGeohash = (hash: string): GeohashCell => {
+  if (hash.length === 0 || hash.length > MAX_GEOHASH_PRECISION) {
+    throw new RangeError(`A geohash has 1 to ${MAX_GEOHASH_PRECISION} characters`);
+  }
+  const lat = [-90, 90] as [number, number];
+  const lon = [-180, 180] as [number, number];
+  let evenBit = true;
+  for (const char of hash.toLowerCase()) {
+    const value = GEOHASH_ALPHABET.indexOf(char);
+    if (value === -1) throw new RangeError(`"${char}" is not a character of a geohash`);
+    for (let bit = 4; bit >= 0; bit -= 1) {
+      const range = evenBit ? lon : lat;
+      const mid = (range[0] + range[1]) / 2;
+      if ((value >> bit) & 1) range[0] = mid;
+      else range[1] = mid;
+      evenBit = !evenBit;
+    }
+  }
+  return {
+    south: lat[0],
+    west: lon[0],
+    north: lat[1],
+    east: lon[1],
+    center: { lat: (lat[0] + lat[1]) / 2, lon: (lon[0] + lon[1]) / 2 },
+  };
+};

package/src/index.ts

@@ -2,3 +2,6 @@
 export * from "./module.js";
 export * from "./procedures.js";
 export * from "./geo.js";
+export * from "./distance.js";
+export * from "./geohash.js";
+export * from "./types.js";

package/src/procedures/geo/distance.ts

@@ -0,0 +1,16 @@
+/**
+ * geo.distance procedure
+ *
+ * Give the great-circle distance between two points
+ */
+
+import { greatCircleKm } from "../../distance.js";
+import type { GeoDistanceInput, GeoDistanceOutput } from "../../types.js";
+
+/**
+ * This function gives the great-circle distance between two points, in kilometres. It changes
+ * nothing.
+ */
+export async function geoDistance(input: GeoDistanceInput): Promise<GeoDistanceOutput> {
+  return { km: greatCircleKm(input.from, input.to) };
+}

package/src/procedures/geo/geohash.ts

@@ -0,0 +1,16 @@
+/**
+ * geo.geohash procedure
+ *
+ * Give the geohash of a point
+ */
+
+import { decodeGeohash, geohash } from "../../geohash.js";
+import type { GeoGeohashInput, GeoGeohashOutput } from "../../types.js";
+
+/**
+ * This function gives the geohash of a point and the cell of that geohash. It changes nothing.
+ */
+export async function geoGeohash(input: GeoGeohashInput): Promise<GeoGeohashOutput> {
+  const hash = geohash(input.point, input.precision);
+  return { hash, cell: decodeGeohash(hash) };
+}

package/src/procedures/geo/index.ts

@@ -0,0 +1,2 @@
+export { geoDistance } from "./distance.js";
+export { geoGeohash } from "./geohash.js";

package/src/procedures.ts

@@ -1,12 +1,25 @@
 /**
- * The procedures of `@procedures/geo`: `geo.geocode` and `geo.route`.
+ * The procedures of `@procedures/geo`: `geo.geocode`, `geo.route`, `geo.distance` and `geo.geohash`.
  */
 
 import { createProcedure, zodAdapter, type AnyProcedure, type ProcedureContext } from "@procedures/client";
 import { z } from "zod";
 import { drivingRoute, geocode, type GeocodeResult, type RouteResult } from "./geo.js";
+import { geoDistance } from "./procedures/geo/distance.js";
+import { geoGeohash } from "./procedures/geo/geohash.js";
+import {
+  GeoDistanceInputSchema,
+  GeoDistanceOutputSchema,
+  GeoGeohashInputSchema,
+  GeoGeohashOutputSchema,
+  type GeoDistanceInput,
+  type GeoDistanceOutput,
+  type GeoGeohashInput,
+  type GeoGeohashOutput,
+} from "./types.js";
 
 const NETWORK_READ = { reads: ["network"], writes: [] };
+const PURE = { reads: [], writes: [] };
 const point = z.object({ lat: z.number().min(-90).max(90), lon: z.number().min(-180).max(180) });
 const timeoutMs = z.number().int().positive().max(120_000).default(20_000).describe("The time limit, in milliseconds (default: 20000)");
 
@@ -79,4 +92,36 @@ export const geoRouteProcedure: AnyProcedure = createProcedure()
   )
   .build() as AnyProcedure;
 
-export const geoProcedures: AnyProcedure[] = [geoGeocodeProcedure, geoRouteProcedure];
+// =============================================================================
+// geo.distance
+// =============================================================================
+
+export const geoDistanceProcedure: AnyProcedure = createProcedure()
+  .path(["geo", "distance"])
+  .input(zodAdapter<GeoDistanceInput>(GeoDistanceInputSchema))
+  .output(zodAdapter<GeoDistanceOutput>(GeoDistanceOutputSchema))
+  .meta({
+    description: "Give the great-circle distance between two points in kilometres (haversine), without the network",
+    output: "json",
+    effects: PURE,
+  })
+  .handler(async (input: GeoDistanceInput): Promise<GeoDistanceOutput> => geoDistance(input))
+  .build() as AnyProcedure;
+
+// =============================================================================
+// geo.geohash
+// =============================================================================
+
+export const geoGeohashProcedure: AnyProcedure = createProcedure()
+  .path(["geo", "geohash"])
+  .input(zodAdapter<GeoGeohashInput>(GeoGeohashInputSchema))
+  .output(zodAdapter<GeoGeohashOutput>(GeoGeohashOutputSchema))
+  .meta({
+    description: "Give the geohash of a point and the cell of that geohash, without the network",
+    output: "json",
+    effects: PURE,
+  })
+  .handler(async (input: GeoGeohashInput): Promise<GeoGeohashOutput> => geoGeohash(input))
+  .build() as AnyProcedure;
+
+export const geoProcedures: AnyProcedure[] = [geoGeocodeProcedure, geoRouteProcedure, geoDistanceProcedure, geoGeohashProcedure];

package/src/types.ts

@@ -0,0 +1,67 @@
+/**
+ * Type definitions of the procedures of this package
+ */
+
+import { z } from "zod";
+import type { Point } from "./geo.js";
+import type { GeohashCell } from "./geohash.js";
+
+const point = z.object({ lat: z.number().min(-90).max(90), lon: z.number().min(-180).max(180) });
+
+// =============================================================================
+// geo.distance Types - Give the great-circle distance between two points
+// =============================================================================
+
+/** The input of `geo.distance`: two points. */
+export interface GeoDistanceInput {
+  from: Point;
+  to: Point;
+}
+
+/** The output of `geo.distance`: the great-circle distance in kilometres, without rounding. */
+export interface GeoDistanceOutput {
+  km: number;
+}
+
+export const GeoDistanceInputSchema: z.ZodType<GeoDistanceInput> = z.object({
+  from: point.describe("The first point (degrees)"),
+  to: point.describe("The second point (degrees)"),
+});
+
+export const GeoDistanceOutputSchema: z.ZodType<GeoDistanceOutput> = z.object({
+  km: z.number().describe("The great-circle distance in kilometres (haversine, Earth radius 6371 km), without rounding"),
+});
+
+// =============================================================================
+// geo.geohash Types - Give the geohash of a point
+// =============================================================================
+
+/** The input of `geo.geohash`: a point and the number of characters. */
+export interface GeoGeohashInput {
+  point: Point;
+  precision: number;
+}
+
+/** The output of `geo.geohash`: the geohash and its cell. */
+export interface GeoGeohashOutput {
+  hash: string;
+  cell: GeohashCell;
+}
+
+export const GeoGeohashInputSchema: z.ZodType<GeoGeohashInput, { point: Point; precision?: number | undefined }> = z.object({
+  point: point.describe("The point (degrees)"),
+  precision: z.number().int().min(1).max(12).default(7).describe("The number of characters, from 1 to 12 (default: 7)"),
+});
+
+export const GeoGeohashOutputSchema: z.ZodType<GeoGeohashOutput> = z.object({
+  hash: z.string().describe("The geohash"),
+  cell: z
+    .object({
+      south: z.number(),
+      west: z.number(),
+      north: z.number(),
+      east: z.number(),
+      center: z.object({ lat: z.number(), lon: z.number() }),
+    })
+    .describe("The cell of the geohash: its edges and its center (degrees)"),
+});